Получение параметров дела

Активити (робот) "Получение данных дела" предназначено для использования в роботах и может быть полезно в следующих сценариях:

Получение всех данных дела по его ID для дальнейшей обработки;
Извлечение конкретных полей дела (тема, описание, ответственный и т.д.);
Получение информации о файлах, прикреплённых к делу;
Получение ссылок на файлы для скачивания или просмотра;
Проверка статуса и параметров дела перед выполнением операций;
Извлечение данных дела для использования в других активити (роботах);
Получение информации о записях звонков (ссылки на файлы записей);
Автоматизация обработки данных дел в бизнес-процессах;
Получение данных дела для аналитики и отчётности;
Извлечение данных дела для интеграции с внешними системами.

Как работает активити (робот):
- Активити (робот) получает все данные дела по указанному ID через REST API Битрикс24;
- Возвращаются все доступные поля дела (ID, тема, описание, ответственный, даты, статус и т.д.);
- Для файлов, прикреплённых к делу, возвращаются ссылки для просмотра и скачивания;
- Поддерживается получение информации о записях звонков (ссылки на файлы записей);
- Все поля дела возвращаются в возвращаемых параметрах активити (робота);
- Активити (робот) работает через REST API Битрикс24 (crm.activity.get и disk.file.get);
- Поддерживается обработка множественных файлов (массивы для итератора).

Сценарий работы активити (робота) бизнес-процесса

Описание параметров активити (робота)

Название поля	Описание и примеры использования
ID дела	В данном поле указывается идентификатор дела, данные которого нужно получить. Это обязательный параметр. Если указан массив ID, будет обработан только первый элемент массива. Примеры: - {=Variable:ACTIVITY_ID} - получить данные дела с ID из переменной предыдущего активити (робота); - 123 - получить данные дела с ID 123; - {=A1988_22222_92566_99999:new_id_activity} - использовать ID дела из результата активити (робота) "Создание своего дела в CRM"; - {=A1988_22222_92566_99999:search_result_first_string} - использовать первый ID из результата поиска дел; - {=Document:ID} - получить данные дела, если ID дела совпадает с ID документа; - {=Iterator:Value} - получить данные дела для каждого ID из итератора. Как получить ID дела: - Из результата активити (робота) "Создание своего дела в CRM" (параметр new_id_activity); - Из результата активити (робота) "Поиск дел" (параметр search_results_array или search_result_first_string); - Из переменной, созданной в предыдущих шагах бизнес-процесса; - Из поля документа, если дело связано с документом. Важно: Если дело с указанным ID не существует, активити (робот) завершится с ошибкой "Дело с указанным ID не найдено". Всегда проверяйте существование дела перед получением данных.
Делать отладочные сообщения в журнал БП	Варианты: да/нет. Позволяет выбрать, нужно ли создавать отладочные сообщения в журнал БП или нет. Это поле нужно использовать только по необходимости из-за большого расхода запросов и уменьшенной скорости срабатывания активити (робота).
Запускать от имени	Данное поле необходимо для того, чтобы установить сотрудника, с правами которого выполнять действие данного активити (робота). Если у сотрудника не будет прав на выполнение действия, то активити (робот) не сработает. Рекомендуем выбирать всегда сотрудника с правами администратора системы.
Устанавливать текст статуса	Данное поле позволяет включать возможность установки статуса бизнес-процесса. Это необходимо для того, чтобы во время работы активити (робота) информировать пользователя в истории о том, что бизнес-процесс остановился на конкретном шаге. Это особенно важно в момент отладки и выяснения причин неполадок в работе механизма.
Текст статуса	В данном поле указывается текстовый вариант статуса, который Вы можете изменять. Используется только при включённом параметре "Устанавливать текст статуса".
Ожидать ответа	Данное поле Вами не управляется. Оно необходимо для того, чтобы определить, нужно ли ожидать реакции от нашего активити (робота) после запуска.
Период ожидания. Время ожидания ответа от приложения	Указывается в секундах, минутах, часах, днях, но не менее 5 минут и желательно не более 1 часа. Это поле нужно для аварийного завершения активити (робота), и если ответ не получен в течении того количества времени, то активити (робот) завершается.

Примеры использования активити (робота)

Описание примера	Решение
Получение всех данных дела по ID	Параметры: ID дела - {=Variable:ACTIVITY_ID}. Активити (робот) вернёт все доступные поля дела: ID, тема, описание, ответственный, даты создания и завершения, статус, тип дела и другие поля. Все данные будут доступны в возвращаемых параметрах активити (робота).
Получение данных дела из результата поиска	Параметры: ID дела - {=A1988_22222_92566_99999:search_result_first_string}. Активити (робот) получит данные первого дела из результата поиска. Используйте для обработки найденных дел.
Получение информации о файлах дела	Параметры: ID дела - {=Variable:ACTIVITY_ID}. Активити (робот) вернёт информацию о всех файлах, прикреплённых к делу: ID файлов (ids_files_url), ссылки для просмотра (array_files_url), ссылки для скачивания (array_files_load). Используйте массивы для итерации по файлам.
Получение ссылки на запись звонка	Параметры: ID дела - {=Variable:CALL_ACTIVITY_ID}. Активити (робот) вернёт ссылку на запись звонка в параметре file_url и ID файла записи в параметре file_id. Используйте для прослушивания записей звонков.
Проверка статуса дела перед выполнением операции	Параметры: ID дела - {=Variable:ACTIVITY_ID}. Используйте возвращаемый параметр COMPLETED для проверки статуса дела (Y - выполнено, N - не выполнено) перед выполнением операций с делом.
Извлечение данных дела для использования в других активити	Параметры: ID дела - {=Variable:ACTIVITY_ID}. Получите данные дела и используйте их в следующих активити (роботах). Например, используйте SUBJECT для создания нового дела или DESCRIPTION для отправки письма.
Получение данных дела через итератор	Параметры: ID дела - {=Iterator:Value}. Для каждого ID дела из итератора активити (робот) получит данные соответствующего дела. Полезно для массовой обработки дел.
Получение информации о ответственном за дело	Параметры: ID дела - {=Variable:ACTIVITY_ID}. Активити (робот) вернёт ID ответственного за дело в параметре RESPONSIBLE_ID. Используйте для дальнейшей работы с ответственным.
Извлечение дат дела для планирования	Параметры: ID дела - {=Variable:ACTIVITY_ID}. Активити (робот) вернёт дату начала (START_TIME) и дату завершения (END_TIME) дела. Используйте для планирования связанных дел или задач.
Получение данных дела для аналитики	Параметры: ID дела - {=Variable:ACTIVITY_ID}. Получите все данные дела и используйте их для создания отчётов, анализа эффективности работы или для передачи в системы аналитики.

Сценарий работы робота

Возвращаемые параметры данного активити (робота):
Активити (робот) возвращает все доступные поля дела, которые можно получить через REST API Битрикс24. Основные параметры:

- Все поля дела - все доступные поля дела возвращаются в возвращаемых параметрах активити (робота) с теми же названиями, что и в API Битрикс24 (например, ID, SUBJECT, DESCRIPTION, RESPONSIBLE_ID, START_TIME, END_TIME, COMPLETED, OWNER_TYPE_ID, OWNER_ID и другие);
- Ссылка на запись звонка (file_url) - строка со ссылкой на запись звонка (если дело является звонком с записью). Используется для прослушивания записи звонка;
- ID файла записи звонка (file_id) - строка с ID файла записи звонка (если дело является звонком с записью). Используется для работы с файлом записи;
- Ссылка на файл (массив для итератора) (array_files_url) - массив строк со ссылками на файлы, прикреплённые к делу, для просмотра. Используется для итерации по файлам в бизнес-процессе;
- Ссылка на файл для скачивания (массив для итератора) (array_files_load) - массив строк со ссылками на файлы, прикреплённые к делу, для скачивания. Используется для итерации по файлам в бизнес-процессе;
- ID файлов (массив для итератора) (ids_files_url) - массив чисел с ID файлов, прикреплённых к делу. Используется для итерации по файлам в бизнес-процессе;
- Данные дела найдены (activity_data_found) - строка, указывающая результат получения данных. Возможные значения: Y (данные получены успешно) или N (дело не найдено или произошла ошибка);
- Логи ошибок (s_error_logs) - строка с описанием ошибки или сообщением об успешном выполнении. При успешном выполнении содержит сообщение "activity_get_data_success: [ID дела]".

Примеры использования возвращаемых параметров:
- Использовать SUBJECT для создания нового дела с той же темой;
- Использовать DESCRIPTION для отправки письма с содержанием дела;
- Использовать RESPONSIBLE_ID для назначения ответственного в другом деле;
- Использовать array_files_url в итераторе для обработки всех файлов дела;
- Использовать file_url для прослушивания записи звонка;
- Использовать START_TIME и END_TIME для планирования связанных дел;
- Использовать COMPLETED для проверки статуса дела перед выполнением операций;
- Использовать OWNER_TYPE_ID и OWNER_ID для работы с сущностью, к которой привязано дело;
- Проверить activity_data_found для определения успешности получения данных;
- Использовать s_error_logs для логирования и отладки.

Важно о возвращаемых параметрах: Если дело с указанным ID не найдено или произошла ошибка при получении данных, параметр activity_data_found будет равен N, а s_error_logs будет содержать описание ошибки. Всегда проверяйте значение параметра activity_data_found перед использованием данных дела в дальнейших шагах бизнес-процесса.

Важно! Ограничения и рекомендации:

Обязательные параметры:
Для успешного получения данных дела обязательно должен быть указан параметр "ID дела". Если ID дела не указан или указан неверно, активити (робот) завершится с ошибкой "Не указан ID дела".

Обработка массивов ID:
Если в параметре "ID дела" указан массив ID, активити (робот) обработает только первый элемент массива. Для обработки нескольких дел используйте итератор.

Работа с файлами:
Активити (робот) получает информацию о всех файлах, прикреплённых к делу, и возвращает ссылки для просмотра и скачивания. Файлы возвращаются в виде массивов для удобной итерации. Для работы с файлами используются методы disk.file.get через REST API.

Работа с записями звонков:
Если дело является звонком с записью, активити (робот) возвращает ссылку на запись звонка в параметре file_url и ID файла записи в параметре file_id. Эти параметры доступны только для дел типа "Звонок" с записью.

Доступные поля дела:
Активити (робот) возвращает все доступные поля дела, которые можно получить через REST API Битрикс24. Список полей формируется автоматически при установке активити (робота) на основе настроек вашего портала. Некоторые поля могут быть недоступны в зависимости от прав доступа пользователя, указанного в поле "Запускать от имени".

Права доступа:
Убедитесь, что пользователь, указанный в поле "Запускать от имени", имеет права на просмотр дел в CRM. Рекомендуется использовать пользователя с правами администратора системы. Права доступа влияют на то, какие поля дела будут доступны в возвращаемых параметрах.

Обработка ошибок:
Если дело с указанным ID не существует, активити (робот) завершится с ошибкой "Дело с указанным ID не найдено". Параметр activity_data_found будет равен N. Всегда проверяйте значение этого параметра перед использованием данных дела в дальнейших шагах бизнес-процесса.

Использование в итераторе:
Для получения данных нескольких дел рекомендуется использовать итератор. Это позволит обработать все дела последовательно и получить данные каждого дела отдельно.

Производительность:
Получение данных дела требует выполнения запросов к REST API Битрикс24. При работе с большим количеством дел через итератор учитывайте ограничения по количеству запросов к API. Используйте параметр "Делать отладочные сообщения в журнал БП" только при необходимости для уменьшения нагрузки на систему.

Ваша корзина пуста

Получение параметров дела