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

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

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

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

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

Для работы блока необходимо настроить подключение к сервису Microsoft Exchange.

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

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

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

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

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

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

• Идентификатор календаря (заполняется вручную или с помощью маппинга)
• Электронная почта пользователя, которому принадлежит календарь (заполняется вручную или с помощью маппинга, доступно только для подключения MS Exchange Online)
• Сбор событий (по дате или с последней выгрузки)

Если события собираются:

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

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

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

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

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

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

Для сбора событий по дате необходимо указать:

• Начало периода сбора (заполняется вручную или с помощью маппинга)
• Окончание периода сбора (можно заполнить вручную или с помощью маппинга, а также оставить пустым — в этом случае события будут собираться до момента запуска блока)

При необходимости вы можете конвертировать указанные вручную даты в формат UNIX timestamp. Для этого нажмите fx.

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

После успешного запроса система возвращает уникальный идентификатор состояния синхронизации — значение SyncState.

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

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

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

При запуске блока система проверяет наличие сохраненного SyncState:

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

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

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

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

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

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

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

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

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

При сборе событий по дате:

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

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

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

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

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

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

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

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

Пример записи в логах агента автоматизации для подключения MS Exchange Online:

2025-12-04 08:31:42.063+0000 [00000002] [X] DEBUG c.i.s.a.b.e.e.g.AppointmentIteratorItem:112 - Exchange ignoreExceptions mode enabled. All records skipped for email:test_email@test.com, id:AAMkADUzNzRlNGY4LWI2ZGYtNDAxNi04NjQzLWNjMDU4MDhmMzU0NQAuAAAAAADL1UNdG4VXQpdOu7VIXn54AQDOQMOIMUN8SZd38W5ucEDjAAAAAAENAAA=
com.infomaximum.platform.exception.PlatformException: The folder to be synchronized could not be found.,

Где:

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

Настройка автоматических повторных запросов

Во время работы блоков MS Exchange могут возникать ошибки. В таких случаях система пытается выполнить действие повторно, чтобы выполнение скрипта не прерывалось. По умолчанию выполняется до 25 попыток. Для отдельных типов ошибок это значение можно изменить.

Количество возможных повторных выполнений настраивается в конфигурационном файле com.infomaximum.subsystem.automation.json с помощью параметра exchange_retry_count.

Ошибки, для которых доступна настройка количества попыток:

• Try again later
• The mailbox database is temporarily unavailable
• Exceeds the throttling budget
• An internal server error occurred
• Read timed out
• Connection reset
• Connection has closed
• Connection not obtained from this manager
• The element at position

Поведение блоков в зависимости от значения exchange_retry_count описано в таблице ниже.

Пример работы с MS Exchange

Пример использования блоков MS Exchange приведен в разделе Регулярное получение событий из календарей с помощью временной метки SyncState.

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

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

Параметры:

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

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

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

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

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

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

Пример:

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

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

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

Параметры:

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

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

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

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

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

Пример:

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

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

В этом примере показано, как один скрипт автоматизации запускает другой скрипт с помощью GraphQL-запроса. Для этого в основном скрипте настраивается блок Отправить запрос, который отправляет HTTP POST-запрос к GraphQL-эндпоинту. В теле HTTP-запроса передается GraphQL-мутация, запускающая целевой скрипт по его GUID.

Для запуска скрипта требуются его GUID и ID рабочего пространства. Чтобы получить их, добавим блок Отправить запрос с GraphQL-запросом:

1. В блоке Отправить запрос введем URL-адрес сервера GraphQL с ключом API в формате https://{адрес_сервера}/graphql?api_key=ключ.
2. Выберем метод POST.
3. В поле Тело запроса введем GraphQL-запрос на получение GUID скрипта и ID пространства:

   {"query":"
     {
     automation {
       script {
         script_general(id: <id_скрипта>) {
           id
           guid
           workspace {
             id
           }
         }
       }
     }
   }"
   }
   

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

Теперь добавим блок для выполнения целевого скрипта:

1. Во втором блоке Отправить запрос введем URL-адрес сервера GraphQL с ключом API в формате https://{адрес_сервера}/graphql?api_key=ключ.
2. Выберем метод POST.
3. В поле Тело запроса введем GraphQL-запрос и добавим поля с полученными данными через редактор кода:

   {"query":"mutation{
     automation{
       script{
         execute_by_guid(guid:\"<полученный_GUID_скрипта>\", workspace_id:<полученный_id_пространства>){
           guid
         }
       }
     }
   }"
   }
   

   • Важно: GUID скрипта необходимо экранировать.
   
4. Нажмем Тестировать.
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 = "key";
   const url = "URL";
   const body = {
    id: 3311,
    username: "string",
    firstName: "string",
    lastName: "string",
    email: "string",
    password: "string",
    phone: "string",
    userStatus: 0,
   };
   const response = z.request({
    url: url,
    method: "POST",
    jsonBody: JSON.stringify(body),
    headers: {
    Authorization: `Bearer ` + apiKey,
    },
   });
   if (response.status < 200 || response.status >= 300) {
    const errorText = new TextDecoder().decode(response.response);
    z.stringError("Ошибка запроса" + errorText);
   }
   if (response.status === 204) {
    z.stringError(
    `Нет записей. Проверьте содержимое фильтра или корректность запроса:` + url
    );
   }
   function normalize(response) {
    const template = {
    code: response.code,
    type: response.type,
    message: response.message,
    };
    return [template.code, template.type, template.message];
   }
   const headersObj = Object.fromEntries(
    Array.from(response.headers.entrySet().toArray()).map((e) => {
    const key = String(e.getKey());
    const val = String(e.getValue()).replace(/^\[|\]$/g, "");
    return [key, val];
    })
   );
   const response_header = JSON.stringify(headersObj);
   const app = {
    output: () => ({
    response_body: normalize(
    JSON.parse(new TextDecoder().decode(response.response))
    ),
    response_header: response_header,
    response_status: response.status,
    ["var-with-hard-name-1"]: headersObj.date,
    ["var-with-hard-name-2"]: headersObj["access-control-allow-headers"],
   content_type: headersObj["content-type"],
    methods: headersObj["access-control-allow-methods"],
    }),
   };
   

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

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

1. Введем код в поле JavaScript:

   const url =
    "https://jira.server.com/secure/attachment/76158/Screenshot_1.jpg";
   const login = "Логин";
   const password = "Пароль";
   const auth = z.base64Encode(login + ":" + password);
   const response = z.request({
    url: url,
    method: "GET",
    headers: {
    Authorization: "Basic " + auth,
    },
   });
   if (response.status < 200 || response.status >= 300) {
    const errorText = new TextDecoder().decode(response.response);
    z.stringError("Ошибка запроса" + errorText);
   }
   if (response.status === 204) {
    z.stringError(
    `Нет записей. Проверьте содержимое фильтра или корректность запроса:` + url
    );
   }
   const headersObj = Object.fromEntries(
    Array.from(response.headers.entrySet().toArray()).map((e) => {
    const key = String(e.getKey());
    const val = String(e.getValue()).replace(/^\[|\]$/g, "");
    return [key, val];
    })
   );
   const app = {
    output: () => ({
    response_body: JSON.stringify(new TextDecoder().decode(response.response)),
    response_header: JSON.stringify(headersObj),
    resp_1_status: response.status,
    file_content: response.response, //this ArrayBuffer
    ["var-with-hard-name-1"]: headersObj.date,
    ["var-with-hard-name-2"]: headersObj["cache-control"],
    content_type: headersObj["content-type"],
    content_length: headersObj["content-length"],
    }),
   };
   

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