Работа с сервисами

Работа с сервисами осуществляется с помощью блоков:

• Получить календари
• Получить события календаря
• Отправить письмо
• Отправить запрос
• Выполнить код

Получить календари

С помощью блока можно получить список календарей сотрудников.

В параметрах блока введите домен или логин пользователя или добавьте его с помощью маппинга в поле Домен\логин.

После выполнения блок возвращает список календарей пользователя, которые можно использовать в блоке Получить события календаря.

Блок возвращает следующие поля:

Получить события календаря

Блок позволяет извлечь список событий календаря, полученного в блоке Получить календари.

Параметры блока:

• Идентификатор календаря (заполняется вручную или с помощью маппинга)
• Условие сбора событий (заполнить поле можно значением даты в миллисекундах или значением SyncState)

Если поле Условие сбора событий:

• Заполнить значением даты в миллисекундах, то в выходных данных отобразятся только те события, которые начинаются с этой даты. Значение даты ориентируется на время начала события. В этом случае в выходных данных отобразятся неповторяющиеся события, а повторяющиеся события разобьются на отдельные встречи. Отмененные события отображаться не будут
• Заполнить значением SyncState, то в выходных данных отобразятся все повторяющиеся, неповторяющиеся и отмененные события, которые были созданы или обновлены с момента времени последнего выполнения скрипта. Значение SyncState уникально для каждого события и опирается на дату последнего изменения события. Специально объединять новые и старые данные вручную не требуется — использование SyncState обеспечивает автоматическую актуализацию событий

Подробные инструкции по первичной синхронизации и использованию SyncState представлены ниже.

Блок выводит данные событий указанного календаря. На основе полученных данных можно создать таблицу и построить процесс.

Блок возвращает следующие поля:

Первичная синхронизация

Первичная синхронизация выполняется при первом запуске блока Получить события календаря, когда значение параметра SyncState еще отсутствует:

1. В поле Условие сбора событий укажите дату начала сбора в формате Unix-времени (в миллисекундах). Например: 1609459200000 (1 января 2021 г.). Система соберет все события, начиная с указанной даты до момента выполнения запроса. Этот шаг необходим для того, чтобы получить начальное значение SyncState, которое в дальнейшем будет использоваться для синхронизации событий. Выбор короткого диапазона (например, один день) позволяет минимизировать нагрузку на систему при первичной синхронизации.
2. После успешного запроса система возвращает значение SyncState. Это уникальный идентификатор состояния синхронизации, который можно сохранить в отдельной таблице. В таблице следует сохранять идентификатор календаря (unique_id), идентификатор события (id_meeting) и соответствующий ему SyncState.

Использование параметра SyncState при повторных запусках

Параметр SyncState — это временная метка, которая автоматически генерируется сервисом Microsoft Exchange при выполнении запроса к календарю. Она позволяет исключить из результатов уже обработанные события и получить только новые или измененные с момента последней синхронизации.

Для повторного запуска скрипта необходимо подставить поле SyncState в поле Условие сбора событий. При запуске блока система проверяет наличие сохраненного SyncState:

• Если значение найдено, система вернет только новые или измененные события с момента, зафиксированного в SyncState
• Если значение не найдено, выполнение блока для этого календаря будет прекращено, и скрипт перейдет к обработке следующего календаря. Если сохраненные значения SyncState отсутствуют для всех календарей, скрипт завершит выполнение

SyncState обновляется и возвращается системой только после успешной обработки всех запрашиваемых календарей.

Если в процессе синхронизации происходит ошибка и выполнение блока прерывается, новый SyncState не формируется. В этом случае при следующем запуске будет использовано ранее сохраненное значение SyncState, что позволит загрузить данные, которые не были получены из-за прерывания.

Если в конфигурации включен режим игнорирования ошибок, блок продолжает выполнение при возникновении ошибок в отдельных календарях. В этом случае:

• Для успешно обработанных календарей события сохраняются, и их SyncState обновляется
• Для календарей с ошибками данные не сохраняются, SyncState остается прежним, а информация об ошибке записывается в лог агента автоматизации

При следующем запуске календари с ошибками будут обработаны повторно, поскольку их SyncState не был обновлен.

Преимущества использования SyncState:

• Обрабатываются только новые или измененные события, что снижает нагрузку на систему
• Учитываются только события, измененные после последнего запроса, что исключает дублирование информации
• Пользователю не требуется вручную отслеживать изменения — начальная временная метка (Unix-время) используется для первого запроса, а обновленный SyncState — для следующих запросов, что обеспечивает непрерывность и актуальность собираемых данных

Обработка событий календаря

При использовании временной метки в миллисекундах:

• Неповторяющиеся события возвращаются в обычном виде, начиная с заданной даты
• Повторяющиеся события разбиваются на отдельные встречи, что позволяет детально анализировать каждое повторение
• Отмененные события не включаются в выходные данные

При использовании SyncState:

• Если встреча не изменилась (т. е. ее last_modified_time осталось прежним) с момента предыдущей выгрузки, то при использовании параметра SyncState такая встреча не будет возвращена в ответе. Это позволяет избежать повторной обработки неизмененных событий. Значение самого SyncState остается прежним
• Если между выгрузками в повторяющемся событии произошли изменения (например, обновились сведения о проведении встречи), в ответе будут возвращены обновленные данные этого события
• Если за период между выгрузками во встрече появилось несколько изменений, то в выходных данных будет возвращено событие с последним значением last_modified_time. Таким образом, промежуточные изменения не приводят к множественной выгрузке — учитывается только финальное состояние события

Режим игнорирования ошибок

Блок Получить события календаря может работать в режиме игнорирования ошибок, который позволяет продолжить выполнение скрипта, даже если отдельные календари вызывают ошибки. Если ошибка не входит в перечень перезапрашиваемых или игнорируемых, календарь, в котором она возникла, не обрабатывается. Информация об этом фиксируется в логах агента автоматизации и может быть проанализирована позднее. Остальные календари продолжают обрабатываться в штатном режиме.

Режим игнорирования ошибок можно включить и выключить в конфигурационном файле com.infomaximum.subsystem.automation.json с помощью параметра exchange_ignore_exceptions:

• Если указано true — режим игнорирования ошибок включен
• Если указано false — режим игнорирования ошибок выключен (значение по умолчанию)

Если ошибка повторяется неоднократно, рекомендуется запустить скрипт в режиме игнорирования ошибок. В логах агента автоматизации будут зафиксированы ошибки и идентификаторы календарей, в которых они возникли. Эту информацию можно использовать для проведения детального анализа/ После устранения причины ошибки рекомендуется отключить режим игнорирования ошибок и перезапустить центральный сервер, чтобы вернуться к стандартному режиму работы.

Пример записи в логах агента автоматизации:

2025-04-07 12:48:50.885+0300 [00000002] [X] DEBUG c.i.s.a.b.e.e.g.AppointmentIteratorItem:64 - Exchange ignoreExceptions mode enabled. All records skipped for id:AAMkAGQ4ZGFlMTU1LWYxYzEtNGQ4Ni1iMDFjLTNmZjAxMTk2YzI4ZgAuAAAAAADfJqMIbKSgS5+alO5Y+noFAQCU/9Lman9lR5EXIo0RRpHGAAAAAAENAAA=
com.infomaximum.platform.exception.PlatformException: The folder to be synchronized could not be found.,

Где:

• id — идентификатор пропущенного календаря
• PlatformException — ошибка, из-за которой был пропущен календарь

Пример использования пакета Microsoft Exchange

Чтобы получить список календарей и перенести их в базу данных, необходимо построить скрипт:

1. В качестве блока-триггера выберите Планировщик и настройте расписание, когда необходимо получать список календарей и их события.
2. Настройте блок Выбрать строки через SQL-запрос нужной базы данных, чтобы получить список электронных адресов пользователей (логин), календари которых необходимо получать.
3. Настройте блок Получить календари. В поле Домен\логин с помощью маппинга подставьте колонку, в которой указаны почты пользователей, полученные в блоке Выбрать строки через SQL-запрос на предыдущем шаге. Обратите внимание, что при использовании символа \ в имени домена может не пройти авторизация. Чтобы авторизация прошла, используйте только имя технической учетной записи.
4. Чтобы получить события календаря, настройте соответствующий блок, указав в поле Идентификатор календаря с помощью маппинга тег unique_id. Чтобы получить события конкретного календаря, укажите идентификатор вручную. Для этого вернитесь в выходные данные предыдущего блока и скопируйте значение unique_id необходимого календаря. Для первого сбора событий заполните поле Условие сбора событий временной меткой в миллисекундах.
5. Чтобы внести в таблицу актуальные значения SyncState, полученные в предыдущем пункте, добавьте в скрипт блок Добавить строки из нужного пакета. В поле Таблица выберите таблицу, в которую необходимо внести данные. Если потребуется добавить новую колонку, нажмите Добавить колонку.
6. Протестируйте весь скрипт, нажав соответствующую кнопку в правом верхнем углу. Если скрипт успешно протестирован, опубликуйте и активируйте его.

Отправить письмо

Блок позволяет отправлять письма на указанный адрес электронной почты.

Параметры:

• Подключение (выбор существующего подключения или добавление нового)
• Адрес получателя
• Тема письма
• Сообщение (формат: Текст или HTML)
• Вложение
• Копия
• Скрытая копия

Все параметры блока, кроме подключения, можно указать с помощью маппинга.

Отправить письмо можно с адреса, указанного при настройке подключения SMTP, или из системы, выбрав блок Отправить письмо в пакете Системная почта.

Для отправки письма из пакета Системная почта необходимо настроить сервер исходящей почты.

Особенности работы блока:

• В блоке можно использовать значения только одного блока-источника. Например, перед блоком «4. Отправить письмо» есть еще 2 блока. Данные можно получить только из одного из них. Если указываются значения из обоих блоков, появляется ошибка
• Перед блоком обязательно должен быть другой. Количество отправленных писем будет зависеть от количества возвращенных записей. Например, предыдущий блок вернул 5 записей, значит, будет отправлено 5 писем
• В поле Адрес получателя можно указать нескольких пользователей текстом через запятую

Пример:

1. Добавляем блок Отправить письмо и вводим адрес получателя. Если получателей несколько, указываем все адреса в поле Адрес получателя текстом через запятую. Заполняем другие поля блока и нажимаем Тестировать.
2. Когда тест завершится, письмо будет отправлено на указанные адреса.

Отправить запрос

Блок позволяет отправлять HTTP-запрос на указанный адрес.

Параметры:

• Подключение (выбор существующего подключения или добавление нового)
• URL
• Метод (GET, POST)
• Заголовок (ключ и значение)
• Тело запроса (при методе POST)
• Пакетная обработка (при методе POST, позволяет ускоренно отправлять данные)

Метод выбирается из списка, все остальные параметры могут быть заданы вручную или с помощью маппинга.

Если для выполнения запроса к сервису требуется аутентификация, настройте подключение:

1. Перейдите во вкладку Подключение.
2. Нажмите кнопку + Новое подключение и заполните поля:
   • Название
   • Имя пользователя
   • Пароль
3. Нажмите кнопку Создать.

Подключение также можно настроить в Панели управления рабочего пространства.

Пример:

1. Вводим URL и тестируем по нажатию кнопки Тестировать.
2. Когда тест завершен, получаем выходные данные во вкладке Тест.

Запуск скрипта с помощью GraphQL-запроса

1. Получите GUID скрипта и ID рабочего пространства, выполнив следующий запрос в GraphiQL:
   query{
     automation{
       script{
         script_general(id: <id_скрипта>){
           id
           guid
           workspace{
             id
           }
         }
       }
     }
   }
   

   ID пространства можно также получить в системной таблице workspace, если подключена привилегия Системные таблицы.
2. В блоке HTTP-запрос введите URL-адрес вашего сервера GraphQL с ключом API в формате https://{адрес_сервера}/graphql?api_key=ключ.
3. Выберите метод POST.
4. В поле Тело запроса введите запрос:
   {"query":"mutation{
     automation{
       script{
         execute_by_guid(guid:\"<полученный_GUID_скрипта\", workspace_id:<полученный_id_пространства>){
           guid
         }
       }
     }
   }"}
   

   
5. Нажмите Тестировать.
6. Когда тест завершится, выходные данные отобразятся во вкладке Тест.

Выполнить код

Блок позволяет обрабатывать данные с помощью JS-кода.

Используйте блок, чтобы:

• Выполнять множественные/связанные HTTP-запросы
• Выгружать/загружать файлы с помощью HTTP-запросов
• Совершать математические действия над данными (переменными)
• Обрабатывать строки в JSON и фильтровать значения

Чтобы выполнить действие, введите JS-код в поле JavaScript в параметрах блока. С помощью маппинга в код можно подставить переменные.

Блок может содержать z-метод для хеширования и обработки ошибок. Возможные методы для выполнения в JS-среде:

• z.base64Encode() — производит base64-кодирование входной строки. Например: const auth = z.base64Encode(login + ':' + password);
• z.base64Decode() — производит base64-декодирование входной строки. Например: const originalText = z.base64Decode(encodedText);
• z.request() — выполняет HTTP-запрос. Ожидает на вход объект с конфигурацией запроса. Параметры:
  • url — адрес, куда будет отправлен запрос
  • method — по умолчанию GET. Возможные значения: GET, POST, DELETE, PUT
  • headers — список заголовков HTTP-запроса
  • jsonBody/multipartBody — тело запроса. Обязательный параметр для методов POST и PUT
  • timeout — индивидуальное время ожидания ответа от сервера в миллисекундах

Запуск скрипта с помощью JS-кода

1. Введите код в поле JavaScript:
   const apiKey = 'ключ';
   const scriptGuid = 'GUID_скрипта';
   const workspaceId = 1;
   
   var resp1 = z.request({
       url: 'https://адрес_сервера/graphql?api_key=' + apiKey,
       method: 'POST',
       jsonBody: '{"query":"mutation{automation{script{execute_by_guid(guid:\\"' +     scriptGuid + '\\", workspace_id:' + workspaceId + '){guid}}}}"}'
   });
   
   const app = {
       output: () => ({
               resp_1_body: JSON.stringify(resp1.response),
               resp_1_header: JSON.stringify(resp1.headers),
               resp_1_status: resp1.status,
               ["var-with-hard-name-1"]: resp1.headers.date,
               ["var-with-hard-name-2"]: resp1.headers["cache-control"],
               content_type: resp1.headers["content-type"],
               content_length: resp1.headers["content-length"]
           }
       )
   }
   

2. Нажмите Тестировать.
3. Когда тест завершится, выходные данные отобразятся во вкладке Тест.

Получение файла с Jira

1. Введите код в поле JavaScript:
   const login = 'логин';
   const password = 'пароль';
   const auth = z.base64Encode(login + ':' + password);
   
   var resp1 = z.request({
       url: 'https://jira.office.infomaximum.com/secure/attachment/76158/Screenshot_1.jpg',
       method: 'GET',
       headers: {
           Authorization: 'Basic ' + auth
       }
   });
   
   const app = {
       output: () => ({
               resp_1_body: JSON.stringify(resp1.response),
               resp_1_header: JSON.stringify(resp1.headers),
               resp_1_status: resp1.status,
               file_content: resp1.response,
               ["var-with-hard-name-1"]: resp1.headers.date,
               ["var-with-hard-name-2"]: resp1.headers["cache-control"],
               content_type: resp1.headers["content-type"],
               content_length: resp1.headers["content-length"]
           }
       )
   }
   

2. Нажмите Тестировать.
3. Когда тест завершится, выходные данные отобразятся во вкладке Тест.