Поиск визитов в сущности

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

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

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

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

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

Название поля	Описание и примеры использования
ID визитов (если заполнено, то учитывается только статус)	В данном поле указывается идентификатор визита для проверки его статуса. Это необязательный параметр, но если он указан, то другие параметры поиска (тип сущности, ID сущности и фильтры) не учитываются. Активити (робот) проверит соответствие визита указанным условиям (статус визита). Важно: Если указан ID визита, активити (робот) работает в режиме проверки условий. Параметры "Тип Сущности", "ID сущности" и все фильтры игнорируются. Результат будет возвращён в параметре math_search_results (Y - соответствует условиям, N - не соответствует). Примеры: - {=Variable:VISIT_ID} - проверить визит с ID из переменной предыдущего активити (робота); - 12345 - проверить визит с ID 12345; - {=A1988_22222_92566_99999:search_results_array} - использовать ID визита из результата предыдущего поиска. Режим проверки условий: При указании ID визита активити (робот) проверяет соответствие визита указанным условиям: - Статус визита (если указан) - проверяется соответствие статуса (выполнено/не выполнено). Если все указанные условия выполнены, возвращается math_search_results = Y, иначе math_search_results = N.
Тип Сущности	В данном поле указывается тип сущности CRM, в которой будет осуществлён поиск визитов. Это необязательный параметр, используется только если не указан "ID визитов". Выбирается из выпадающего списка. Варианты выбора: - LEAD - Лид; - DEAL - Сделка; - CONTACT - Контакт; - COMPANY - Компания; - QUOTE - Предложение; - SMART_INVOICE - Счёт; - ORDER - Заказ; - СМАРТ: [название смарт-процесса] - для поиска визитов в смарт-процессах (список формируется автоматически на основе настроек вашего портала, формат: TYPE_ID:OWNER_TYPE_ID). Примеры: - CONTACT - искать визиты в контактах; - COMPANY - искать визиты в компаниях; - DEAL - искать визиты в сделках; - СМАРТ: Заявки - искать визиты в смарт-процессе "Заявки". Важно: Этот параметр используется только если не указан "ID визитов". Если указан "ID визитов", то этот параметр игнорируется. Для работы этого параметра также рекомендуется указать "ID сущности".
ID сущности	В данном поле указывается идентификатор сущности CRM, в которой будет осуществлён поиск визитов. Это необязательный параметр, используется только если не указан "ID визитов". Примеры: - {=Document:ID} - искать визиты в текущей сущности из документа (контакт, компания, лид, сделка); - 123 - искать визиты в сущности с ID 123; - {=Variable:CONTACT_ID} - использовать ID из переменной предыдущего активити (робота); - {=A1988_22222_92566_99999:search_results} - использовать ID из результата поиска (первый элемент массива); - {=Iterator:Value} - использовать ID для каждого элемента в итераторе. Особенности работы: - Если указан ID сущности без указания ID визита, активити (робот) вернёт массив ID найденных визитов; - Если указан ID сущности и ID визита, ID сущности игнорируется (приоритет у ID визита); - Для работы этого параметра рекомендуется указать "Тип Сущности".
Статус визита	В данном поле можно указать статус визита для фильтрации результатов или для проверки условий при указании ID визита. Это необязательный параметр. Варианты выбора: - Не завершена (1) - визит не выполнен (COMPLETED = N); - Завершена (2) - визит выполнен (COMPLETED = Y). Примеры использования: - Не завершена (1) - найти только невыполненные визиты; - Завершена (2) - найти только выполненные визиты; - При указании ID визита - проверить, соответствует ли статус визита указанному значению. Когда использовать: - Для фильтрации визитов по статусу при поиске в сущности; - Для проверки статуса конкретного визита при указании ID визита; - Для анализа выполненных или невыполненных визитов.
Выбрать визиты от указанной даты	В данном поле можно указать дату и время, начиная с которой будет осуществлён поиск визитов. Это необязательный параметр, используется как дополнительный фильтр при поиске визитов. Примеры: - {=System:NowLocal} - искать визиты с текущей даты и времени; - ={{=dateadd({=System:Now}, "-7d")}} - искать визиты за последние 7 дней; - ={{=dateadd({=System:Now}, "-1m")}} - искать визиты за последний месяц; - 01.01.2025 00:00:00 - искать визиты с указанной даты; - {=Variable:START_DATE} - использовать дату из переменной предыдущего активити (робота). Когда использовать: - Для поиска визитов за определённый период; - Для анализа визитов за последние дни/месяцы; - Для фильтрации визитов по дате создания.
Выбрать визиты до указанной даты	В данном поле можно указать дату и время, до которой будет осуществлён поиск визитов. Это необязательный параметр, используется как дополнительный фильтр при поиске визитов. Примеры: - {=System:NowLocal} - искать визиты до текущей даты и времени; - ={{=dateadd({=System:Now}, "1d")}} - искать визиты до завтрашнего дня; - 31.12.2025 23:59:59 - искать визиты до указанной даты; - {=Variable:END_DATE} - использовать дату из переменной предыдущего активити (робота). Когда использовать: - Для поиска визитов за определённый период (в паре с параметром "Выбрать визиты от указанной даты"); - Для анализа визитов до определённой даты; - Для фильтрации визитов по дате окончания периода поиска.
Тема визита содержит	В данном поле можно указать текст, который должен содержаться в теме визита. Это необязательный параметр, используется как дополнительный фильтр при поиске визитов. Примеры: - Важное - найти визиты, тема которых содержит слово "Важное"; - Консультация - найти визиты, тема которых содержит слово "Консультация"; - {=Variable:SEARCH_TEXT} - использовать текст из переменной предыдущего активити (робота). Когда использовать: - Для фильтрации визитов по теме; - Для поиска визитов с определёнными ключевыми словами в теме; - Для анализа визитов по тематике.
Содержание визита содержит	В данном поле можно указать текст, который должен содержаться в описании визита. Это необязательный параметр, используется как дополнительный фильтр при поиске визитов. Примеры: - Демонстрация - найти визиты, описание которых содержит слово "Демонстрация"; - Продукт - найти визиты, описание которых содержит слово "Продукт"; - {=Variable:SEARCH_TEXT} - использовать текст из переменной предыдущего активити (робота). Когда использовать: - Для фильтрации визитов по содержанию; - Для поиска визитов с определёнными ключевыми словами в описании; - Для анализа визитов по содержанию.
Делать отладочные сообщения в журнал БП	Варианты: да/нет. Позволяет выбрать, нужно ли создавать отладочные сообщения в журнал БП или нет. Это поле нужно использовать только по необходимости из-за большого расхода запросов и уменьшенной скорости срабатывания активити (робота).
Запускать от имени	Данное поле необходимо для того, чтобы установить сотрудника, с правами которого выполнять действие данного активити (робота). Если у сотрудника не будет прав на выполнение действия, то активити (робот) не сработает. Рекомендуем выбирать всегда сотрудника с правами администратора системы.
Устанавливать текст статуса	Данное поле позволяет включать возможность установки статуса бизнес-процесса. Это необходимо для того, чтобы во время работы активити (робота) информировать пользователя в истории о том, что бизнес-процесс остановился на конкретном шаге. Это особенно важно в момент отладки и выяснения причин неполадок в работе механизма.
Текст статуса	В данном поле указывается текстовый вариант статуса, который Вы можете изменять. Используется только при включённом параметре "Устанавливать текст статуса".
Ожидать ответа	Данное поле Вами не управляется. Оно необходимо для того, чтобы определить, нужно ли ожидать реакции от нашего активити (робота) после запуска.
Период ожидания. Время ожидания ответа от приложения	Указывается в секундах, минутах, часах, днях, но не менее 5 минут и желательно не более 1 часа. Это поле нужно для аварийного завершения активити (робота), и если ответ не получен в течении того количества времени, то активити (робот) завершается.

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

Описание примера	Решение
Проверка статуса визита по ID	Параметры: ID визитов - {=Variable:VISIT_ID}, Статус визита - Завершена (2). Активити (робот) проверит, является ли визит выполненным. Результат будет возвращён в параметре math_search_results (Y или N).
Поиск всех визитов контакта	Параметры: Тип Сущности - CONTACT, ID сущности - {=Document:ID}, ID визитов - не указывается, Статус визита - не указывается, Выбрать визиты от указанной даты - не указывается, Выбрать визиты до указанной даты - не указывается, Тема визита содержит - не указывается, Содержание визита содержит - не указывается. Активити (робот) найдёт все визиты контакта.
Поиск выполненных визитов сделки	Параметры: Тип Сущности - DEAL, ID сущности - {=Document:ID}, ID визитов - не указывается, Статус визита - Завершена (2), Выбрать визиты от указанной даты - не указывается, Выбрать визиты до указанной даты - не указывается, Тема визита содержит - не указывается, Содержание визита содержит - не указывается. Активити (робот) найдёт все выполненные визиты сделки.
Поиск визитов за последний месяц	Параметры: Тип Сущности - CONTACT, ID сущности - {=Document:ID}, ID визитов - не указывается, Статус визита - не указывается, Выбрать визиты от указанной даты - ={{=dateadd({=System:Now}, "-1m")}}, Выбрать визиты до указанной даты - {=System:NowLocal}, Тема визита содержит - не указывается, Содержание визита содержит - не указывается. Активити (робот) найдёт все визиты контакта за последний месяц.
Поиск визитов по теме	Параметры: Тип Сущности - COMPANY, ID сущности - {=Document:ID}, ID визитов - не указывается, Статус визита - не указывается, Выбрать визиты от указанной даты - не указывается, Выбрать визиты до указанной даты - не указывается, Тема визита содержит - Консультация, Содержание визита содержит - не указывается. Активити (робот) найдёт все визиты компании, тема которых содержит слово "Консультация".
Поиск невыполненных визитов за период	Параметры: Тип Сущности - DEAL, ID сущности - {=Document:ID}, ID визитов - не указывается, Статус визита - Не завершена (1), Выбрать визиты от указанной даты - ={{=dateadd({=System:Now}, "-7d")}}, Выбрать визиты до указанной даты - {=System:NowLocal}, Тема визита содержит - не указывается, Содержание визита содержит - не указывается. Активити (робот) найдёт все невыполненные визиты сделки за последние 7 дней.
Поиск визитов через итератор	Параметры: Тип Сущности - CONTACT, ID сущности - {=Iterator:Value}, ID визитов - не указывается, Статус визита - не указывается, Выбрать визиты от указанной даты - не указывается, Выбрать визиты до указанной даты - не указывается, Тема визита содержит - не указывается, Содержание визита содержит - не указывается. Для каждого ID контакта из итератора активити (робот) найдёт все визиты этого контакта.
Поиск визитов смарт-процесса	Параметры: Тип Сущности - СМАРТ: Заявки, ID сущности - {=Document:ID}, ID визитов - не указывается, Статус визита - не указывается, Выбрать визиты от указанной даты - не указывается, Выбрать визиты до указанной даты - не указывается, Тема визита содержит - не указывается, Содержание визита содержит - не указывается. Активити (робот) найдёт все визиты, привязанные к указанному элементу смарт-процесса "Заявки".
Поиск визитов по содержанию	Параметры: Тип Сущности - CONTACT, ID сущности - {=Document:ID}, ID визитов - не указывается, Статус визита - не указывается, Выбрать визиты от указанной даты - не указывается, Выбрать визиты до указанной даты - не указывается, Тема визита содержит - не указывается, Содержание визита содержит - Демонстрация. Активити (робот) найдёт все визиты контакта, описание которых содержит слово "Демонстрация".
Комплексный поиск визитов	Параметры: Тип Сущности - DEAL, ID сущности - {=Document:ID}, ID визитов - не указывается, Статус визита - Завершена (2), Выбрать визиты от указанной даты - ={{=dateadd({=System:Now}, "-30d")}}, Выбрать визиты до указанной даты - {=System:NowLocal}, Тема визита содержит - Важное, Содержание визита содержит - не указывается. Активити (робот) найдёт все выполненные визиты сделки за последние 30 дней, тема которых содержит слово "Важное".

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

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

Особенности возвращаемых параметров:
- При указании ID визита: возвращается только параметр math_search_results (Y или N), другие параметры не заполняются;
- При поиске визитов: возвращаются все параметры, включая массивы ID визитов;
- Если найден один визит: search_results_array содержит одно значение (не массив);
- Если найдено несколько визитов: search_results_array содержит массив ID визитов.

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

Важно о возвращаемых параметрах: Если вы хотите использовать результат работы активити (робота) в другом активити (роботе), в котором параметр - простое число, то несколько чисел, разделённых запятыми, работать не будут, так как параметр ждёт только одно число. Если параметр простой - строка, то туда не нужно вставлять результат работы в виде массива для итератора, так как данный параметр предназначен для полей с типом заполнения "множественное".

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

Два режима работы:
Активити (робот) поддерживает два режима работы:
- Режим 1: Проверка условий по ID визита (если указан ID визита) - проверяет соответствие визита указанным условиям (статус);
- Режим 2: Поиск визитов в сущности (если не указан ID визита) - ищет визиты по заданным фильтрам в указанной сущности.

Приоритет ID визита:
Если указан ID визита, все остальные параметры поиска (тип сущности, ID сущности и фильтры) игнорируются. Активити (робот) работает только в режиме проверки условий. Для поиска визитов необходимо оставить поле "ID визитов" пустым.

Проверка типа дела:
Активити (робот) проверяет, что указанное дело действительно является визитом (PROVIDER_TYPE_ID = 'VISIT' и PROVIDER_ID = 'VISIT_TRACKER'). Если дело не является визитом, активити (робот) завершится с ошибкой "Дело не является визитом".

Работа со смарт-процессами:
Активити (робот) автоматически определяет смарт-процессы, доступные на вашем портале, и добавляет их в список типов сущностей. Список формируется автоматически на основе настроек портала. Для смарт-процессов используется формат TYPE_ID:OWNER_TYPE_ID (например, 6:135).

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

Проверка условий при указании ID визита:
При указании ID визита активити (робот) проверяет соответствие визита указанным условиям:
- Статус визита (если указан) - проверяется соответствие статуса (выполнено/не выполнено).
Если все указанные условия выполнены, возвращается math_search_results = Y, иначе math_search_results = N.

Фильтрация при поиске визитов:
При поиске визитов (без указания ID визита) все указанные фильтры работают как условия поиска:
- Статус визита фильтрует визиты по статусу выполнения;
- Даты работают как диапазон "от и до";
- Тема и содержание работают как поиск по подстроке (содержит указанный текст).

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

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

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

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

Поиск визитов в сущности