Пример создания пользовательской интеграцииBETA

В этом разделе показано, как шаг за шагом создать пользовательскую интеграцию, настроить подключение к внешнему сервису и использовать ее в сценарии автоматизации.

Создание интеграции в рабочем пространстве

Proceset предоставляет возможность воспользоваться редактором кода для написании интеграции, но сначала необходимо создать интеграцию в рабочем пространстве.

В качестве примера добавим в пространство интеграцию с системой Proceset:

1. В Панели управления в пространстве нажмем + Добавить и выберем Интеграцию.
2. В открывшемся окне зададим:
   • Название Интеграция
   • Логотип
3. Нажмем Создание.

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

• Номер версии структуры интеграции schema
• Версия интеграции version
• Название интеграции label
• Описание интеграции description
• Раздел blocks для описания блоков интеграции, которые будут выполнять определенные действия
• Раздел connections для описания подключений, которые обеспечат связь с интегрируемой системой

app = {
    schema: 2,
    version: '0.0.1',
    label: 'Интеграция',
    description: '',
    blocks: [],
    connections: []
}

Добавление подключения

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

В качестве примера добавим в интеграцию подключение к системе Proceset по ключу API:

1. Укажем данные подключения.
   connections: [
       {
           key: 'connections',
           name: 'Подключение по ключу API',
           description: 'Подключение к Proceset'
       }
   ]
   

2. Укажем поля ввода для настройки подключения по ключу API. Нам необходимо следующее:
   • Поле для ввода URL Jira — используется как основа для формирования хоста и выполнения запросов к API
   • Поле для ввода логина — имя пользователя для аутентификации в Jira
   • Поле для ввода пароля — пароль для аутентификации
   • Кнопка для проверки подключения — при нажатии формирует базовую аутентификацию (Base64-кодированный логин:пароль) и отправляет тестовый запрос к Jira для проверки корректности данных
     import {
         IntegrationConnection
     } from "@infomaximum/integration-sdk";
     import {
         CommonBasicConnect
     } from "../types/common";
     
     export const BasicAuthConnect: IntegrationConnection < CommonBasicConnect > = {
         label: "Подключение к Atlassian Jira (Basic)",
         description: "Подключение по логину/паролю к Jira",
         inputFields: [{
                 key: "connection_base_url",
                 type: "text",
                 label: "URL Jira",
             },
             {
                 key: "connection_login",
                 type: "text",
                 label: "Логин",
             },
             {
                 key: "connection_password",
                 type: "password",
                 label: "Пароль",
             },
             {
                 key: "authorize_button",
                 type: "button",
                 label: "Проверить подключение",
                 typeOptions: {
                     saveFields: (service, bundle) => {
                         const build_token = service.base64Encode(
                             bundle.authData.connection_login + ":" + bundle.authData.connection_password
                         );
                         const response: any = service.request({
                             url: bundle.authData.connection_base_url + "/rest/api/2/project",
                             method: "GET",
                             headers: {
                                 Authorization: "Basic " + build_token,
                             },
                         });
                         const decode = JSON.parse(new TextDecoder().decode(response.response));
                         if (response.status !== 200) {
                             throw new Error("Ошибка подключения к Jira: " + decode);
                         }
                         return {
                             connect_status: 200,
                             api_key: build_token,
                         };
                         },
                         message: (service, bundle) => {
                         if (bundle.authData.connect_status && bundle.authData.connect_status === 200)
                             return "Успешно авторизован!";
                         throw new Error("Не удалось авторизоваться!");
                         },
                         },
                         },
                         ],
                         execute: () => {},};
     

3. Теперь добавим в код интеграции в раздел connections обработчик execute, который будет формировать URL подключения к GraphQL API на основе введенных в поля ввода параметров:
   execute:(service,bundle)=>{
       function createUrl(host,port,key){
           var res = "https://";
           if(host === "localhost"){
               res = "http://";
           }
           if(port === undefined || port === ""){
               res + host + "/graphql?api_key=" + key
           }
           return res + host + port + "/graphql?api_key=" + key
       }
       return{
           url: createUrl(bundle.inputFields.connection_host, bundle.inputFields.connection_port, bundle.inputFields.connection_key)
       }
   }
   

Добавление блоков интеграции

Далее необходимо добавить блоки интеграции.

Для примера добавим в интеграцию блок для запуска скрипта по его ID:

1. Добавим данные блока.
   blocks: [
       {
           key:"block_run_script",
           name:"Запустить скрипт",
           description:"Запускает скрипт по его ID"
       }
   ]
   

2. Добавим обязательное поле для ввода идентификатора скрипта.
   inputFields:[
       {
           key:"script_id",
           type:"textPlain",
           label:"ID скрипта",
           required:true
       }
   ]
   

3. Добавим функцию, которая выполняет GraphQL-мутацию для включения скрипта по указанному ID и возвращает информацию о нем. Полученные данные могут быть использованы в других блоках скрипта.
   executePagination:(service,bundle,context)=>{
       if(bundle.authData && bundle.authData.url){
           service.error.stringError("невозможно выполнить блок")
       }
       function mutationDisableScript(request_url) {
           var response = service.request({
               url: request_url,
               method: "POST",
               jsonBody: JSON.stringify({
               query: `mutation UpdateScript { automation { script { update(id: "${bundle.inputData.scriptId}", is_enabled: true){id} } } }`
               })
           });
           if (~~response.status < 200 || ~~response.status > 300)
               service.error.stringError(`Невозможно выполнить блок.\n${JSON.stringify(response.response)}`);
           return response.response;
           }
           function parseScriptDisableResponse(response) {
           if (
               response.data &&
               response.data.automation &&
               response.data.automation.script &&
               response.data.automation.script.update
           ) {
               var item = response.data.automation.script.update;
               return {
               name: item.name ? item.name : "unknown",
               id: item.id ? item.id : 0,
               enabled: item.enabled ? item.enabled : false
               };
           }
           return {};
           }
           var response = mutationDisableScript(bundle.authData.url);
           var script  = parseScriptDisableResponse(response)
           return{
           output:[script],
           output_variables:[
               {type:"String",name:"script_id"}
           ],
           state:{},
           hasNext:false
           }
   }
   

4. Сохраним изменения.

Использование интеграции

Теперь добавленную интеграцию можно использовать в рабочем пространстве.

Настроим подключение к Proceset по ключу API:

1. Во вкладке Панель управления нажмем Добавить и выберем Подключение.
2. В открывшемся окне выберем подключение интеграции.
3. Зададим название подключения и нажмем Создать.
4. На открывшейся странице введем параметры подключения и нажмем Сохранить.

Добавим скрипт, в котором используем блок интеграции:

1. Во вкладке Панель управления нажмем Добавить и выберем Скрипт.
2. Зададим название скрипта и нажмем Добавить.
3. Добавим триггер Ручной запуск.
4. Добавим блок действий и на открывшейся слева панели выберем категорию Установлено.
5. Выберем интеграцию и блок Запустить скрипт.
6. В параметрах блока укажем идентификатор скрипта в рабочем пространстве, который необходимо запустить.
7. Протестируем скрипт.
8. В выходных данных блока отображается результат выполнения.