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

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

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

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

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

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

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

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

{
    schema: 1,
    meta: {
        key: 'intg',
        name: 'Интеграция',
        description: 'null'
    },
    blocks: [
    ],
    connections: [
    ]
}

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

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

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

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

2. Укажем поля ввода для настройки подключения по ключу API. Нам необходимо следующее:
   • Поля для ввода ключа API
   • Поле для ввода хоста подключения
   • Поле для ввода порта подключения
   • Кнопка для автоматического заполнения поля Хост подключения из URL
   inputFields:[
       {
           key:"connection_key",
           type:"password",
           label:"Ключ API",
           required:true
       },
       {
           key:"connection_host",
           type:"textPlain",
           label:"Хост подключения",
           required:true
       },
       {
           key:"connection_port",
           type:"textPlain",
           label:"Порт подключения",
           required:true
       },
       {
           key:"connection_button",
           type:"button",
           label:"Автоопределение хоста",
           required:false,
           executeWithSaveFields:(service,bundle)=>{
               var url = bundle.authData.BASE_URL
               return {
                   connection_host: url.substring(8).replace("/webhook/" + bundle.authData.GUID, "")
               }
           }
       }
   ]
   

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: [
       {
           meta:{
               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. В выходных данных блока отображается результат выполнения.