Поиск дел

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

Поиск дел по типу (звонок, письмо, встреча, задача и т.д.);
Поиск дел, привязанных к конкретной сущности CRM (сделка, лид, контакт, компания);
Фильтрация дел по различным параметрам (ответственный, дата создания, статус и т.д.);
Поиск дел за определённый период времени;
Поиск дел по ответственному за дело;
Поиск дел в смарт-процессах;
Автоматическое определение типа сущности по ID;
Поиск дел с поддержкой множественных сущностей;
Аналитика и отчётность по делам;
Автоматизация процессов на основе найденных дел.

Как работает активити (робот):
- Активити (робот) автоматически получает список всех доступных полей дела из CRM вашего портала;
- Для каждого поля (кроме недоступных для поиска) создаётся параметр, который можно использовать для фильтрации;
- Поддерживается поиск по типу дела (провайдеру) - обязательный параметр;
- Можно указать тип сущности и ID сущности для поиска дел, привязанных к конкретной сущности;
- Поддерживается автоматическое определение типа сущности по ID (если тип не указан);
- Поддерживается множественный выбор типа сущности для поиска дел в нескольких типах сущностей одновременно;
- Поддерживается работа со смарт-процессами (автоматически определяются и добавляются в список);
- Результаты возвращаются в виде массива ID дел, строки с ID через запятую, первого и последнего ID, количества найденных дел;
- Активити (робот) работает через REST API Битрикс24 (crm.activity.list);
- Поддерживается обработка больших объёмов данных (более 50 дел) через batch-запросы;
- Для звонков поддерживается поиск с альтернативными провайдерами (CALL_LIST, CRM_CALL, TELEPHONY, PHONE).

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

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

Название поля	Описание и примеры использования
Тип дела	В данном поле указывается тип дела (провайдера), который нужно найти. Это обязательный параметр. Выбирается из выпадающего списка. Варианты выбора: - Универсальное (CRM_TODO) - универсальные дела; - Встреча (CRM_MEETING) - дела типа "Встреча"; - Звонок (VOXIMPLANT_CALL) - дела типа "Звонок" (поддерживается поиск с альтернативными провайдерами); - Письмо (CRM_EMAIL) - дела типа "Письмо"; - Задачи (TASKS) - задачи (старые дела для обратной совместимости); - Задача (новая) (CRM_TASKS_TASK) - задачи в новой реализации; - Чат (IMOPENLINES_SESSION) - дела типа "Чат"; - Обзвон (CALL_LIST) - дела типа "Обзвон"; - SMS (CRM_SMS) - дела типа "SMS"; - CRM форма (CRM_WEBFORM) - дела типа "CRM форма"; - Визит (VISIT_TRACKER) - дела типа "Визит"; - Слоты (CRM_CALENDAR_SHARING) - дела типа "Слоты"; - Доставка (CRM_DELIVERY) - дела типа "Доставка"; - Документ подписания (CRM_SIGN_DOCUMENT) - дела типа "Документ подписания"; - Сообщение в WhatsApp через ЕЦУ (CRM_NOTIFICATION) - дела типа "Сообщение в WhatsApp"; - Оплата (CRM_PAYMENT) - дела типа "Оплата"; - Дело бизнес-процесса (CRM_BIZPROC_WORKFLOW) - дела типа "Дело бизнес-процесса"; - И другие типы дел. Примеры: - Звонок - найти все дела типа "Звонок"; - Письмо - найти все дела типа "Письмо"; - Встреча - найти все дела типа "Встреча". Важно: Параметр "Тип дела" является обязательным. Без указания типа дела поиск не будет выполнен. Для звонков активити (робот) автоматически ищет дела с альтернативными провайдерами (CALL_LIST, CRM_CALL, TELEPHONY, PHONE) для более полного результата.
Тип сущности	В данном поле указывается тип сущности CRM, в которой нужно искать дела. Это необязательный параметр, поддерживается множественный выбор. Выбирается из выпадающего списка. Варианты выбора: - Лид (L) - для поиска дел, привязанных к лидам; - Сделка (D) - для поиска дел, привязанных к сделкам; - Контакт (C) - для поиска дел, привязанных к контактам; - Компания (CO) - для поиска дел, привязанных к компаниям; - Предложение (Q) - для поиска дел, привязанных к предложениям; - Заказ (O) - для поиска дел, привязанных к заказам; - Счёт (SI) - для поиска дел, привязанных к счетам; - СМАРТ: [название смарт-процесса] - для поиска дел, привязанных к смарт-процессам (список формируется автоматически на основе настроек вашего портала). Примеры: - Сделка (D) - найти все дела, привязанные к сделкам; - Контакт (C) - найти все дела, привязанные к контактам; - Сделка (D), Контакт (C) - найти дела, привязанные к сделкам или контактам (множественный выбор); - СМАРТ: Заявки - найти дела, привязанные к смарт-процессу "Заявки". Особенности работы: - Если тип сущности не указан, но указан ID сущности, активити (робот) автоматически определит тип сущности по ID; - Поддерживается множественный выбор для поиска дел в нескольких типах сущностей одновременно; - Для смарт-процессов список формируется автоматически на основе настроек вашего портала.
ID сущности	В данном поле указывается идентификатор сущности CRM, в которой нужно искать дела. Это необязательный параметр. Если указан без указания типа сущности, активити (робот) автоматически определит тип сущности по ID. Примеры: - {=Document:ID} - искать дела в текущей сущности из документа (сделка, лид, контакт, компания); - 123 - искать дела в сущности с ID 123; - {=Variable:DEAL_ID} - использовать ID из переменной предыдущего активити (робота); - {=A1988_22222_92566_99999:search_results} - использовать ID из результата поиска (первый элемент массива); - {=Iterator:Value} - использовать ID для каждого элемента в итераторе. Особенности работы: - Если тип сущности не указан, активити (робот) автоматически определит тип сущности по ID (проверяет лид, сделку, контакт, компанию, смарт-процессы); - Если указан тип сущности, используется указанный тип; - Можно использовать вместе с типом сущности для более точного поиска.
Ответственный	В данном поле указывается сотрудник, дела которого нужно найти. Это необязательный параметр, используется как дополнительный фильтр при поиске дел. Примеры: - {=Document:ASSIGNED_BY_ID} - искать дела ответственного из текущей сущности; - {=User:ID} - искать дела текущего пользователя; - [U1] - искать дела пользователя с ID 1; - user_25 - искать дела пользователя с ID 25; - {=Variable:RESPONSIBLE_ID} - использовать ID из переменной предыдущего активити (робота). Когда использовать: - Для фильтрации дел по ответственному; - Для поиска дел конкретного сотрудника; - Для анализа работы конкретного пользователя.
Дата создания	В данном поле можно указать дату создания дела для фильтрации результатов. Это необязательный параметр. Поддерживаются различные операторы сравнения (=, !, >=, <=, >, <, %, !%). Примеры: - ={{=dateadd({=System:Now}, "-7d")}} - найти дела, созданные 7 дней назад; - >={{=dateadd({=System:Now}, "-30d")}} - найти дела, созданные за последние 30 дней; - <={{=dateadd({=System:Now}, "-1d")}} - найти дела, созданные до вчерашнего дня; - {=Variable:START_DATE} - использовать дату из переменной предыдущего активити (робота). Операторы сравнения: - = - точное совпадение; - ! - не равно; - >= - больше или равно; - <= - меньше или равно; - > - больше; - < - меньше; - % - содержит (для строк); - !% - не содержит (для строк).
Делать отладочные сообщения в журнал БП	Варианты: да/нет. Позволяет выбрать, нужно ли создавать отладочные сообщения в журнал БП или нет. Это поле нужно использовать только по необходимости из-за большого расхода запросов и уменьшенной скорости срабатывания активити (робота).
Запускать от имени	Данное поле необходимо для того, чтобы установить сотрудника, с правами которого выполнять действие данного активити (робота). Если у сотрудника не будет прав на выполнение действия, то активити (робот) не сработает. Рекомендуем выбирать всегда сотрудника с правами администратора системы.
Устанавливать текст статуса	Данное поле позволяет включать возможность установки статуса бизнес-процесса. Это необходимо для того, чтобы во время работы активити (робота) информировать пользователя в истории о том, что бизнес-процесс остановился на конкретном шаге. Это особенно важно в момент отладки и выяснения причин неполадок в работе механизма.
Текст статуса	В данном поле указывается текстовый вариант статуса, который Вы можете изменять. Используется только при включённом параметре "Устанавливать текст статуса".
Ожидать ответа	Данное поле Вами не управляется. Оно необходимо для того, чтобы определить, нужно ли ожидать реакции от нашего активити (робота) после запуска.
Период ожидания. Время ожидания ответа от приложения	Указывается в секундах, минутах, часах, днях, но не менее 5 минут и желательно не более 1 часа. Это поле нужно для аварийного завершения активити (робота), и если ответ не получен в течении того количества времени, то активити (робот) завершается.

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

Описание примера	Решение
Поиск всех звонков сделки	Параметры: Тип дела - Звонок (VOXIMPLANT_CALL), Тип сущности - Сделка (D), ID сущности - {=Document:ID}. Активити (робот) найдёт все звонки, привязанные к указанной сделке. Результат будет возвращён в параметре search_results_array.
Поиск писем контакта за последний месяц	Параметры: Тип дела - Письмо (CRM_EMAIL), Тип сущности - Контакт (C), ID сущности - {=Document:ID}, Дата создания - >={{=dateadd({=System:Now}, "-1m")}}. Активити (робот) найдёт все письма контакта, созданные за последний месяц.
Поиск дел с автоматическим определением типа сущности	Параметры: Тип дела - Универсальное (CRM_TODO), ID сущности - {=Variable:ENTITY_ID}, Тип сущности - не указывается. Активити (робот) автоматически определит тип сущности по ID и найдёт все универсальные дела, привязанные к этой сущности.
Поиск дел в нескольких типах сущностей	Параметры: Тип дела - Встреча (CRM_MEETING), Тип сущности - Сделка (D), Контакт (C) (множественный выбор), ID сущности - не указывается. Активити (робот) найдёт все встречи, привязанные к сделкам или контактам.
Поиск дел ответственного сотрудника	Параметры: Тип дела - Задача (новая) (CRM_TASKS_TASK), Ответственный - {=User:ID}, Тип сущности - не указывается, ID сущности - не указывается. Активити (робот) найдёт все задачи текущего пользователя.
Поиск дел смарт-процесса	Параметры: Тип дела - Универсальное (CRM_TODO), Тип сущности - СМАРТ: Заявки, ID сущности - {=Document:ID}. Активити (робот) найдёт все универсальные дела, привязанные к указанному элементу смарт-процесса "Заявки".
Поиск дел за определённый период	Параметры: Тип дела - Письмо (CRM_EMAIL), Тип сущности - Сделка (D), ID сущности - {=Document:ID}, Дата создания - >={{=dateadd({=System:Now}, "-7d")}} и <={{=System:Now}}. Активити (робот) найдёт все письма сделки, созданные за последние 7 дней.
Поиск дел через итератор	Параметры: Тип дела - Звонок (VOXIMPLANT_CALL), Тип сущности - Контакт (C), ID сущности - {=Iterator:Value}. Для каждого ID контакта из итератора активити (робот) найдёт все звонки этого контакта.
Поиск дел с фильтрацией по теме	Параметры: Тип дела - Универсальное (CRM_TODO), Тип сущности - Сделка (D), ID сущности - {=Document:ID}, Тема - %Важное%. Активити (робот) найдёт все универсальные дела сделки, тема которых содержит слово "Важное".
Поиск дел с использованием всех доступных полей	Параметры: Тип дела - Встреча (CRM_MEETING), Тип сущности - Сделка (D), ID сущности - {=Document:ID}, Ответственный - {=Document:ASSIGNED_BY_ID}, Дата начала - >={{=System:Now}}, Статус - N. Активити (робот) найдёт все предстоящие встречи сделки, назначенные ответственному за сделку.

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

Возвращаемые параметры данного активити (робота):
- Результат поиска (массив для итератора) (search_results_array) - массив чисел с ID найденных дел (например, [123, 456, 789]). Используется для итерации по результатам в бизнес-процессе.
- Результат поиска (строка) (search_results_string) - строка со всеми результатами поиска, разделёнными запятыми (например, "123,456,789"). Удобно для передачи в другие активити (роботы) или для отображения в отчётах.
- Первый результат поиска (search_result_first_string) - строка с первым результатом поиска (например, "123"). Полезно, когда нужно получить только первое найденное дело.
- Последний результат поиска (search_result_last_string) - строка с последним результатом поиска (например, "789"). Полезно для получения последнего дела из списка.
- Количество найденных элементов (count_search) - числовое значение, указывающее количество найденных дел. Используется для проверки наличия дел и для аналитики.
- Соответствует условиям (math_search_results) - строка, указывающая результат поиска. Возможные значения: Y (найдены дела) или N (дела не найдены). Используется в условиях для проверки успешности поиска.
- Логи ошибок (s_error_logs) - строка с описанием ошибки или сообщением об успешном выполнении. При успешном выполнении содержит сообщение "activity_search_error_2: [количество найденных дел]".

Примеры использования возвращаемых параметров:
- Использовать search_results_array в итераторе для обработки каждого дела отдельно;
- Использовать search_result_first_string для получения первого дела без итерации;
- Проверить count_search для определения количества найденных дел перед выполнением операций;
- Использовать math_search_results в условиях для проверки наличия дел;
- Передать search_results_string в следующее активити (робот) для дальнейшей обработки;
- Использовать search_result_last_string для получения последнего дела из списка.

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

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

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

Автоматическое определение типа сущности:
Если указан ID сущности без указания типа сущности, активити (робот) автоматически определит тип сущности по ID. Для этого проверяются лиды, сделки, контакты, компании и смарт-процессы. Это позволяет упростить настройку активити (робота), но может замедлить выполнение при большом количестве проверок.

Множественный выбор типа сущности:
Параметр "Тип сущности" поддерживает множественный выбор. Можно указать несколько типов сущностей для поиска дел в нескольких типах одновременно. Например, можно искать дела в сделках и контактах одновременно.

Работа со смарт-процессами:
Активити (робот) автоматически определяет смарт-процессы, доступные на вашем портале, и добавляет их в список типов сущностей. Список формируется автоматически на основе настроек портала. Для работы со смарт-процессами необходимо указать тип сущности "СМАРТ: [название]" и ID элемента смарт-процесса.

Поиск звонков с альтернативными провайдерами:
При поиске звонков (тип дела = VOXIMPLANT_CALL) активити (робот) автоматически ищет дела с альтернативными провайдерами (CALL_LIST, CRM_CALL, TELEPHONY, PHONE) для более полного результата. Это позволяет найти все звонки, независимо от провайдера.

Обработка больших объёмов данных:
Активити (робот) автоматически обрабатывает случаи, когда результатов больше 50 дел, используя специальную структуру данных (many50). Все дела будут корректно обработаны и возвращены в результатах.

Операторы сравнения для полей:
Для полей типа "datetime" и "date" поддерживаются операторы сравнения: =, !, >=, <=, >, <. Для полей типа "string" поддерживаются операторы: =, !, %, !%. Операторы можно указывать в начале значения поля (например, ">=2024-01-01").

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

Обработка ошибок:
Если дела не найдены, параметр math_search_results будет равен N, а count_search будет равен 0. Активити (робот) не завершится с ошибкой, но вернёт пустые результаты. Всегда проверяйте значение параметра math_search_results перед использованием результатов в дальнейших шагах бизнес-процесса.

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

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

Поиск дел