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

Все воркфлоу с этой страницы экспортируются из корня пакета, @gorgo/medusa-integration, вместе с типами их входных данных, например UpsertIntegrationWorkflowInput. Из шагов корень пакета экспортирует только getResolvedIntegrationOptionsStep. Все воркфлоу и шаги с этой страницы экспортируются из подпути @gorgo/medusa-integration/workflows.

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

src/workflows/disable-my-integration.ts
1import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
2import { setIntegrationEnabledWorkflow } from "@gorgo/medusa-integration"
3
4export const disableMyIntegrationWorkflow = createWorkflow(
5  "disable-my-integration",
6  () => {
7    const integration = setIntegrationEnabledWorkflow.runAsStep({
8      input: { provider_id: "int_my", is_enabled: false },
9    })
10
11    return new WorkflowResponse(integration)
12  }
13)

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

---

Каждый воркфлоу ниже, кроме getResolvedIntegrationOptionsWorkflow, заканчивается шагом emitIntegrationEventStep, который отправляет событие воркфлоу, когда выполнились все предыдущие шаги. Если запуск падает раньше, например с ошибкой not_found или invalid_data, событие не отправляется, а откат не отправляет второе событие.

Сохраняет значения параметров инстанса интеграции. При первом сохранении создаёт запись, а дальше обновляет её. Именно этот воркфлоу выполняется, когда в Admin сохраняют секцию. Шаги идут в таком порядке.

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

Воркфлоу проверяет записываемые параметры по сохранённой конфигурации с наложенными новыми значениями, шифрует секреты и сохраняет запись. Затем он записывает в историю изменение created или updated, если что-то изменилось, и отправляет событие integration.updated. Возвращает сохранённую запись Integration, в options которой секреты зашифрованы.

Воркфлоу завершается ошибкой not_found, если под provider_id не зарегистрирован ни один провайдер, и ошибкой invalid_data для неизвестного section_id или значений, которые не прошли валидацию.

Включает или выключает настроенную интеграцию. Шаги идут в таком порядке.

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

Воркфлоу меняет is_enabled у сохранённой записи, записывает в историю изменение enabled или disabled, если интеграция ещё не была в этом состоянии, и отправляет событие integration.updated. Возвращает обновлённую запись. Завершается ошибкой not_found, если у интеграции ещё нет сохранённой записи, потому что до первого сохранения включать нечего. Если следующий шаг падает, прежнее состояние восстанавливается.

Удаляет сохранённые настройки инстанса интеграции. Провайдер остаётся зарегистрированным, а интеграция снова показывается как ненастроенная. Шаги идут в таком порядке.

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

Воркфлоу удаляет сохранённую запись, записывает в историю изменение deleted со снимком настроенных значений и отправляет событие integration.updated. Возвращает { deleted, diff }, где deleted равно false, если удалять было нечего. Сохранённые секреты он не расшифровывает, поэтому работает даже после смены ключа шифрования.

Запускает проверку соединения, которую объявляет дескриптор провайдера. Шаги идут в таком порядке.

Шаг проверки сохраняет last_test_status, только если у интеграции есть сохранённая запись, а событие отправляется при любом результате.

Воркфлоу выполняет проверку с итоговыми параметрами и возвращает { status, message? }. Кроме того, что возвращает ваш testConnection, модуль сам формирует такие результаты, и воркфлоу не бросает исключение ни в одном из них:

• { status: "skipped", message: "No test configured" }, если в дескрипторе нет testConnection.
• failed с сообщением Unknown integration provider "<id>", если под provider_id не зарегистрирован ни один провайдер.
• failed с сообщением Not configured, если дескриптор объявляет проверку, а интеграция не настроена, выключена или не заполнена. В этом случае модуль не вызывает testConnection.
• failed с сообщением из ошибки, если testConnection бросает исключение или параметры не удаётся прочитать, например сохранённый секрет не расшифровывается, и с сообщением Test failed, если у ошибки сообщения нет.

Для каждого из этих результатов воркфлоу отправляет событие integration.tested. Что Admin показывает для каждого статуса, описано в разделе Проверка соединения.

Запланированная задача модуля test-integration-connections-daily запускает этот воркфлоу каждый день в 03:00 для каждой включённой интеграции, провайдер которой объявляет проверку, с автором { type: "job", id: "test-integration-connections-daily" }. В их число входит и включённая, но ещё не завершённая интеграция, которая получает failed с текстом Not configured.

Получает параметры инстанса интеграции так же, как resolveIntegrationOptions и метод сервиса getResolvedOptions.

Воркфлоу возвращает { options, meta } или null, если интеграция не настроена, выключена или не заполнена. Если под этими идентификатором и инстансом не зарегистрирован ни один провайдер, он бросает исключение. Когда его использовать, читайте в руководстве Чтение параметров.

---

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