Введение

TypeScript SDK — это библиотека для работы с системой из пользовательских скриптов.

Что такое скрипты

Скрипты — это мощный и гибкий инструмент настройки системы под нужды компании. С помощью скриптов можно реализовать сложную логику работы с объектами системы. Скрипт представляет собой набор функций, написанных на языке TypeScript. Каждый скрипт имеет контекст запуска, а также доступ к другим глобальным константам.

Типы скриптов и их использование

Скрипты могут быть:

  • серверными — исполняться на серверной стороне сервиса;
  • клиентскими — исполняться в браузере пользователя.

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

Серверные

Серверные скрипты доступны:

  • в бизнес-процессах как отдельный шаг Скрипт и в настройках шлюза для вычисления служебной переменной;
  • в модулях при настройке действия БП типа Скрипт, метода API типа Скрипт, обработчика событий;
  • в виджетах страниц и форм.

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

Клиентские

Клиентские скрипты доступны в виджетах страниц и форм. Подробнее об использовании серверных и клиентских скриптов читайте в статье справки «Скрипты на TypeScript».

Что можно сделать с помощью скриптов

С помощью скриптов можно создавать, запрашивать, изменять и удалять элементы приложений, а также взаимодействовать с внешними системами по протоколу HTTP.

async function createOrder() {
    // Корзина заказа
    const items = await Context.fields.items.fetchAll();
    // Стоимость корзины
    const total = items
        .map(item => item.price)
        .reduce((acc, price) => acc.add(price));
    // Создадим заказ
    const order = Context.fields.order.app.create();
    order.data.agent = Context.data.__createdBy;
    // Применим скидку
    order.data.total = total.multiply(0.75);
    // Сохраним заказ
    await order.save();
    Context.data.order = order;
    // Отправим идентификатор заказа на сайт
    await fetch(`https://my-store.ru/orders/${ Context.data.storeId }`, {
        method: 'PATCH',
        headers: {
            Authorization: 'bearer MY-SECRET-TOKEN',
        },
        body: JSON.stringify({
            QBPMOrderId: order.data.__id,
        }),
    });
}

Как выполняется скрипт

Скрипт — это файл с кодом на TypeScript. Работа над скриптом производится во встроенном редакторе, основанном на Monaco, в котором добавляются файлы определения TypeScript SDK для автодополнения. При публикации процесса или виджета скрипты валидируются и преобразуются в JavaScript, который исполняется в дальнейшем.

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

Асинхронное выполнение (async / await)

Многие операции в скриптах асинхронные: получение элемента приложения по ссылке, сохранение элемента приложения, работа с внешним сервисом. Такие методы возвращают Promise. Promise (в переводе с англ. «Обещание») является обещанием того, что мы получим результат нашей операции. Если результат операции нужен для совершения других действий, дождитесь «обещания». Для лучшей читаемости кода мы рекомендуем использовать синтаксис async/await:

  • async обозначает, что в функции выполняются асинхронные операции;
  • await гарантирует, что promise («Обещание») выполнится и мы получим результат нашей асинхронной операции.

Рассмотрим, как из переданных в контексте пользователей получить текущего по указанной электронной почте:

// Ставим перед нашей функцией async, обозначая, что в ней будут происходить асинхронные операции
async function getUsers(): Promise<UserItem> {
    // Метод `fetchAll` является асинхронным методом, поэтому ставим `await`, чтобы дождаться результата
    // Если не дождаться результата, то скрипт будет выполняться дальше
    // и вернёт нам объект типа `Promise`, а не массив пользователей
    const users = await Context.fields.users.fetchAll();
    const currentUser = users.find((user: UserItem) => user.data.email === Context.data.email);
    return currentUser;
}

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

async function getUsers(): Promise<UserItem> {
    const users = await Context.fields.users.fetchAll();
    
    // В этом случае мы не ждём ответа сервера и никак не обрабатываем ошибки,
    // так как для нашей логики выполнение этого метода не имеет критичного значения
    fetch('https://my-log-server/?log=' + `getUsers:users_count = {users.length}`);

    const currentUser = users.find((user: UserItem) => user.data.email === Context.data.email);
    return currentUser;
}

Массовая обработка (Promise.all)

Promise.all преобразует массив «обещаний» в «обещание» массива результатов. Другими словами, позволяет дождаться, пока все promise, переданные в эту конструкцию, завершатся, и возвращает массив результатов их выполнения.

Допустим, нужно скачать несколько файлов со сторонних ресурсов:

async function loadFiles(): Promise<Array<ApplicationItem<T>>> {
    // Получаем массив параметров для загрузки файлов типа Приложение
    const filesParams = await Context.fields.filesParams!.fetchAll();
    // Посредством метода массива map получаем массив промисов
    const promises = filesParams.map(async (fileParams: Array<ApplicationItem<T>>) => {
        // В соответствующие переменные записываем соответствующие значения массива,
        // которые возвращает `Promise.all`
        const [name, link] = await Promise.all([
            fileParams.data.name!.fetch(),
            fileParams.data.link!.fetch()
        ]);
        // Создаём файл в контексте процесса с именем по индексу
        Context.fields.file.createFromLink(`${ name }`, `${ link }`);
    });
    // Для получения загруженных файлов в конструкцию `Promise.all` помещаем полученный массив промисов
    // Дожидаемся получения результата
    const files = await Promise.all(promises);
    // Возвращаем массив загруженных файлов для дальнейшего использования
    return files;
}

Если нужно получить данные несколькими запросами, и при этом нет необходимости ждать результаты друг друга, рекомендуем выполнять такие запросы параллельно через метод Promise.all().

Рассмотрим пример. До оптимизации запросы выполняются последовательно, и каждый последующий ждёт окончания выполнения предыдущего:

const teams = await Namespace.app.teams.search().all();
const areas = await Namespace.app.responsibility_areas.search().all();
const issues = await Namespace.app.issue.search().all();

После оптимизации запросы выполнятся параллельно:

const [teams, areas, issues] = await Promise.all([
    Namespace.app.teams.search().all(),
    Namespace.app.responsibility_areas.search().all(),
    Namespace.app.issue.search().all(),
]);

Также метод Promise.all() можно использовать для параллельного массового сохранения элементов приложений:

await Promise.all(teams.map(t => t.save()))

Non-Null Assertion Operator (!)

Это постфикс-оператор, который в дословном переводе означает «оператор ненулевого утверждения». При установке данного оператора после выражения мы утверждаем, что это выражение не может быть null и undefined. В связи с этим используйте оператор ! при моделировании решения с осторожностью: только когда точно известно, что к моменту выполнения скрипта поле не будет null или undefined. Иначе на этой строчке скрипт завершится с ошибкой.

Пример:

// Посмотрим на стандартный пример получения элемента приложения
// Конструкция `app!` означает, что мы даём компилятору гарантию, что значение `app` не может быть `null` или `undefined`, 
// и можно его использовать
const app = await Context.data.app!.fetch();
app.data.file = Context.data.file;
await app.save();
// Если есть вероятность, что поле будет `null` или `undefined` к моменту выполнения скрипта,
// лучше добавлять проверки с помощью условий
deal.data.outstanding = (deal.data.contract_amount || new Money(0, 'RUB')).add(deal.data.received_payments.multiply(-1));
// Без проверки такая строчка была бы написана вот так:
deal.data.outstanding = new Money(deal.data.contract_amount!.asFloat() - deal.data.received_payments.asFloat(), 'RUB' );

Elvis Operator (?.)

Оператор опциональной последовательности ?. позволяет получить значение свойства, находящегося на любом уровне вложенности в цепочке связанных между собой объектов. При этом не нужно проверять каждое из промежуточных свойств в этой цепочке на существование. Оператор ?. работает подобно оператору ., за исключением того, что не выбрасывает исключение, если объект, к свойству или методу которого идёт обращение, равен null или undefined. В этих случаях он возвращает undefined.

Таким образом, мы получаем более короткий и понятный код при обращении к вложенным по цепочке свойствам объекта, когда есть вероятность, что какое-то из них отсутствует.

// Посмотрим на стандартный пример получения элемента приложения
// Конструкция `Context.data.app?.fetch()` вернёт `undefined`, если само значение `app` пустое, 
// а значит, мы можем упростить код проверки
const appItem = await Context.data.app?.fetch();
if (appItem) {
    // Тут уже точно `appItem` существует
}

Диагностика и отладка скриптов

Как проверить скрипт, провести поиск ошибок и медленное выполнение, читайте в статье справки «Диагностика и отладка скриптов».

Структура справки

Справка содержит руководства по работе со скриптами в системе и описание доступных типов данных, объектов, свойств и методов.

Основные разделы справки:

  • Типы данных — раздел, посвящённый базовым типам системы;
  • Типы объектов — раздел, в котором описываются интерфейсы объектов, доступные из скриптов;
  • Глобальные константы — список глобальных констант, доступных в рамках скриптов;
  • Работа с приложениями — раздел, в котором рассматриваются способы работы с элементами приложений, такие как создание, поиск, изменение и удаление;
  • Работа с внешними сервисами — описание функции fetch, с помощью которой можно отправлять HTTP-запросы во внешние системы.