В ELMA365 авторы модулей могут создавать свои собственные методы и использовать их в web API, в сценариях виджетов, страниц и процессов или при настройке шаблона документа. Например, можно создать методы для запуска бизнес-процесса, сложной выборки данных или организовать методы для промежуточного взаимодействия с внутренней или внешней системой.
Можно создавать функции общего назначения и использовать их повторно в разных местах.
Создание метода
Чтобы создать метод, выполните следующие действия:
- Перейдите в Администрирование > Модули.
- Наведите курсор на модуль и нажмите на появившийся значок шестерёнки.
- Перейдите на вкладку Методы API.
- Нажмите Редактировать. Откроется редактор методов.
- Нажмите кнопку +Добавить. В открывшемся окне внесите нужную информацию.
- Название* — укажите название метода;
- Адрес* — в выпадающем списке выберите один или несколько методов HTTP запроса. Доступны следующие методы:
GET
,POST
,PUT
,PATCH
,DELETE
. Укажите адрес, по которому будет доступен метод. В адресе с помощью знака / можно обозначить путь к вложенным методам. Например,/main/email_dispatch
. Количество уровней вложенности неограниченно. Путь к методу может заканчиваться знаком /, например,call_events/route/
; - Функция* — создайте функцию, которая будет выполняться при получении запроса;
- Авторизация — выберите тип авторизации, который будет применяться при получении запроса:
- Внутренняя авторизация — метод можно вызывать только внутри модуля, например, в других методах, виджетах, действиях в бизнес-процессах, обработчиках событий с помощью команды
Namespace.api.название_метода
. Подробнее об этом мы написали ниже. Пользователь, от имени которого исполняется сценарий, должен быть авторизован в ELMA365; - Внешняя авторизация — при выборе этой опции метод будет доступен из внешней системы по токену;
- Внутренняя авторизация — метод можно вызывать только внутри модуля, например, в других методах, виджетах, действиях в бизнес-процессах, обработчиках событий с помощью команды
- Асинхронный запуск — опция позволяет продолжить работу, не дожидаясь окончания выполнения метода;
- Описание — укажите подробное описание метода.
- Перейдите на вкладку Сценарии и напишите метод. Для этого используется язык программирования TypeScript. Более подробно про принципы написания сценариев в ELMA365 читайте в справке ELMA365 TS SDK.
- Сохраните и опубликуйте метод.
Доступ к глобальным константам
При написании методов можно использовать константу Global. Она даёт доступ к переменным, содержащимся в разделах, и к глобальным параметрам. Использование этого объекта препятствует дальнейшей выгрузке модуля. То есть, если использовать константу Global
для написания метода API, то этот модуль с этим методом нельзя будет экспортировать.
Чтобы разрешить доступ к константе Global
:
- В редакторе методов перейдите на вкладку Сценарии.
- В верхнем меню нажмите Настройки.
- В открывшемся окне выберите опцию Global.
Использование файлов в сценариях
В сценариях модуля вы можете использовать изображения, шаблоны документов, инструкции и т. д. Для этого в редакторе методов перейдите на вкладку Файлы и загрузите необходимый документ.
Откройте файл в режиме просмотра и скопируйте его идентификатор в URL-адресе страницы. С помощью идентификатора вы можете обратиться к загруженному файлу в любых сценариях модуля.
Серверные зависимости
В ELMA365 On-Premises вы можете добавлять на вкладке Файлы npm-пакеты с серверными зависимостями. Подробнее об этом читайте в статье «Серверные зависимости пакетов npm».
Вызов метода API из кода сценария
После создания метода API в модуле вы можете вызвать его в любом сценарии этого модуля. Для этого в глобальной переменной Namespace
есть свойство api:
let response = await Namespace.api.some_method.call({
method: "POST",
headers: {
"X-My-CutomHeader": "Some header data"
},
query: {
"skip": "0",
"take": "10"
},
body: "Any body here"
});
В этот метод передаётся тип FetchRequest
, он же используется в методе fetch
.
При вызове этого метода происходит веб-вызов метода API через стандартный протокол HTTP. Поэтому ответ от метода приходит в виде стандартного объекта FetchResponse
.
Также для разработки модулей с вебхуками можно получить адрес метода API с помощью команды Namespace.api.some_method.getUrl()
, которая вернёт строку с полным адресом этого метода для дальнейшего вызова. Этот метод бывает полезен, когда во время работы сторонний сервис требует указать обратный адрес для вызова.
Служебные заголовки
В методах API в каждом объекте запроса, который передаётся в сценарий, содержатся заголовки, хранящие информацию о вызванном методе:
:method
— http-метод;:path
— часть URL-адреса метода, которая приводится после домена, вместе с query-параметрами, например,/test1/test2?q=12345&n=aaa
;:scheme
— используемый в методе протокол: http или https;:authority
— домен и порт (кроме 80 и 443), с которого пришёл запрос, например,elma365.ru
илиlocal.elma365.dev:4200
.