Effects - Stratumn

What are the effects?

Effects are the business logic written in TypeScript that is executed by Trace API after an action is submitted. The effects declared in the configuration project are stringified functions that are stored in the database, so they can be interpreted at runtime by Trace API.

No external constants or functions can be used in the effects.

Workflow definitions

The dsl.$definitions object is the read-only storage of the workflow. It can be used to store constants, environment variables, workflow ids and stringified functions that will be accessible in the effects. The definitions can be of any shape, but by convention, it’s shape is the following:

Documentation
Example
Usage

object

The repository of the workflow where workflow constants are stored.

object

An object where each key is the name of the function and the value is the stringified function.

object

A map between the workflow label and its id.

object

A map between the environment variable name and its value.

Example of a workflow definitions

{
  repo: {
    prices: {
      pizza: 10,
      salad: 5,
    }
  },
  functions: {
    clone: 'function clone(value) { return JSON.parse(JSON.stringify(value)); }',
  },
  wfIds: {
    restaurant: '10'
  },
  env: {
    STRATUMN_API_URL: 'https://api.stratum.com',
    STAGE: 'release',
    ...
  },
}

Usage in effects

const { repo, functions, wfIds, env } = dsl.$definitions;
const { clone } = functions;

const pizzaPrice = repo.prices.pizza;
const clonedPrices = clone(repo.prices);

Notifications

Notifications (usually emails) are sent to a user (could be a single user, or a group) when performing an action. They are sent when the state.notifications is updated. Thus, notifications are usually built and sent inside the effects of an action. There is 3 steps to send a notification through configuration :

Create a function inside workflowDefinitions to build the template of the email, and manipulate data derived from the state (because no external constants or functions can be used in the effects.)

create a custom function in the workflow /definitions/functions

export const createNotification = (data, meta) => {
  return {
    title: '',
    channel: 'EMAIL',
    groupLabel: data.entityLabel,
    template: {
      // etc..
    }
  };
};

Inside the effects, import this function.

Usage in effects

const { state, formData, meta } = dsl.$variables;
const { createNotification } = dsl.$functions;

const notificationPayload = createNotification(state.data, meta);

Updating state.notifications by pushing the template object with the correct data.

Update state

state.notifications.push(notificationPayload);

To see more details about it, go to the notification page.

The `Stratumn` constant

You can use the Stratumn constant to get access to Sentry, a Pino logger and the StratumnError class. Unlike other variables, this constant does not need to be created or imported, it is accessible globally in the effects.

Sentry

The Sentry SDK, allowing you to capture errors, wrap functions with spans, add context, set tags, add metrics etc.This variable is the same as if you did import * as Sentry from "@sentry/node"; in your code.

Usage your effect function

const { Sentry } = Stratumn;

try {
  aFunctionThatMightFail();
} catch (error: unknown) {
  Sentry.captureException(error);
}

Pino logger

A Pino logger instance, allowing you to log messages with different levels.

Usage your effect function

const { logger } = Stratumn;

logger.info('Hello, world!');
logger.info({name: 'John Doe'}, 'Hello, John Doe!');

logger.warn('This is a warning');
logger.error({ error: error }, error instanceof Error ? error.message : 'Unknown error');
logger.fatal('This is a fatal error');
logger.debug('This is a debug message');

Stratumn Error

The Stratumn Error class, allowing you to create custom errors with a code and a message.

Parameters
Example

string

required

The name of the error.

string

required

The code of the error.

string literal

required

The status of the error.

Show Status values

Status	Code	Description
BAD_REQUEST	400	Bad request.
UNAUTHORIZED	401	Unauthorized error.
FORBIDDEN	403	Forbidden error.
NOT_FOUND	404	Not found error.
NOT_IMPLEMENTED	501	Not implemented error.
INTERNAL_SERVER_ERROR	500	Internal server error.

string

required

The message of the error.

object

required

The context of the error. It can be used to add additional data to the error.

Usage your effect function

const { StratumnError } = Stratumn;

throw new StratumnError(
  'execJs/my-custom-error',
  'fc6d0328', // <-- A random error code
  'BAD_REQUEST',
  'My custom error message',
  {
    // ... any additional data you want to add to the error
  }
);

Batch context

When a user applies the same action to many traces at once (a batch action), each trace still runs the action’s effects on its own. The dsl.$variables.batch object lets an effect know that it is running as part of a batch, and where it sits in that batch. dsl.$variables.batch is always present. Outside a batch it holds the not-in-batch default, so you never have to guard against it being undefined.

Requires @stratumn/dsl 1.24.0 or above.

Documentation
Example
Usage

boolean

required

true when the action is executing as part of a batch action, false otherwise.
This is the discriminant: the two fields below are only reachable once you have narrowed on it.

number

The 1-based position of the current trace within the batch (1 to totalActionInBatch).
Only available when isBatchAction is true.

number

The total number of traces the batch will act upon.
Only available when isBatchAction is true.

Inside a batch of 250 traces, on the 42nd trace

{
  isBatchAction: true,
  actionPositionInBatch: 42,
  totalActionInBatch: 250
}

Outside a batch (single action)

{
  isBatchAction: false
}

At runtime the not-in-batch default also carries actionPositionInBatch: 0 and totalActionInBatch: 0, so that is what you will see if you log the whole object. The type deliberately hides them so that no logic can be built on those zeros — treat isBatchAction: false as the only meaningful information on this branch.

Usage in effects

const { batch } = dsl.$variables;

if (batch.isBatchAction) {
  // ✅ Narrowed: position and total are available here
  Stratumn.logger.info(
    `Processing ${batch.actionPositionInBatch} of ${batch.totalActionInBatch}`
  );
} else {
  // Single action: only `isBatchAction` exists on this branch
  Stratumn.logger.info('Processing a single action');
}

batch is a discriminated union on isBatchAction. You must narrow on the flag before reading actionPositionInBatch or totalActionInBatch — reading them directly is a compile error:

const { batch } = dsl.$variables;

batch.actionPositionInBatch; // ✗ compile error — not narrowed
if (batch.isBatchAction) {
  batch.actionPositionInBatch; // ✅ number
}

Only actions executed by the batch engine receive a batch context. Every other execution path — a single action submitted from the UI, an automated action, a link created from another effect via dsl.$modules.createLink, or the public API — sees the not-in-batch default.

Ordering is not guaranteed

actionPositionInBatch identifies which trace you are on, not when it runs. The batch engine processes traces in parallel chunks, so positions do not complete in order: position 250 may well finish before position 3.

Do not use actionPositionInBatch === totalActionInBatch as an “end of the batch” hook to fire a summary email or a final computation. It only means “the numerically last trace”, not “the last one to finish” — and if that trace fails, the effect never runs at all. The platform already sends a single digest notification once the whole batch settles, so per-trace effects don’t need to reproduce it.

A safe use of the batch context is to make a per-trace effect lighter or better labelled when it runs at scale — for example, skipping a per-trace notification that would otherwise be sent hundreds of times:

Skip per-trace notifications when running in a batch

function orderMealEffect(dsl: RestaurantWorkflowContext<FormData>) {
  const { state, formData, batch } = dsl.$variables;
  const { createNotification } = dsl.$functions;

  state.data.meal = formData.meal;

  // In a batch, one email per trace would flood the recipient: rely on the
  // batch digest instead and only notify for single actions.
  if (!batch.isBatchAction) {
    state.notifications.push(createNotification(state.data, dsl.$variables.meta));
  }
}

External functions

Some functions are declared directly in Trace API, and can be accessed direcly in the effects using dsl.$modules.

createLink

An asynchronous function designed to create a new link, enabling Trace to automatically perform an action. This action can be executed within any workflow, either by creating a new trace or targeting an existing one.

Body
Example

string

required

The id of the target workflow.

string

The id of the target trace.
If not provided, the link will be created in a new trace.

string

required

The action that will be done.

object

required

The form data to be used in the action.

string

required

The label of the group that will do the automatic action.
Since createLink makes an automated action, the group label is usually the 'traceBot'.

string

required

The date of creation of the link.

const newLink = await dsl.$modules.createLink({
  action: 'orderMeal',
  workflowId: dsl.$definitions.wfIds.restaurant,
  formData: {
    meal: 'Pizza'
  },
  groupLabel: 'traceBot',
});

searchTraces

An asynchronous function that searches for traces, allowing optional filters to be applied based on the traces’ data.

Body
Example

string

required

The id of the workflow to search traces in.

JSONDeepFilterValue[]

The filters to apply to the search.

Show JSONDeepFilterValue type

TextFilterValue
NumberFilterValue
DateFilterValue

literal

required

The type of the filter, must be equal to 'text'.

JMESPath

required

The JMESPath to apply to the filter.

string

required

The value to filter on.

boolean

Whether the filter should be an exact match.

boolean

Whether the filter should be a negative match.

literal

required

The type of the filter, must be equal to 'number'.

JMESPath

required

The JMESPath to apply to the filter.

string

required

The value to filter on.

literal

required

The type of the filter, must be equal to 'date'.

JMESPath

required

The JMESPath to apply to the filter.

string

required

The value to filter on.

string

The format of the stored date to filter on.

string

The format of the provided date value.

Get all traces where the meal is

const res = await dsl.$modules.searchTraces({
  workflowId: dsl.$definitions.wfIds.restaurant,
  filters: [
    {
      type: 'text',
      path: 'data.meal',
      value: 'Pizza'
    }
  ]
});

createScheduler

An asynchronous function used to create a new scheduler.
The scheduler can be for example used to create links at a specific interval.

Body
Example

string

required

The unique name of the scheduler.

object

The data that will be used by the scheduler.

string

required

The cron expression that defines the schedule.

string

required

Any string to identify the creator of the scheduler.

Creates a link in the current trace every day

const scheduler = await dsl.$modules.createScheduler({
  name: `restaurant-${meta.traceName}`,
  data: {
    webhook_url: `${STRATUMN_API_URL}/v2/traces/${meta.traceId}/links`,
    webhook_payload: {
      groupLabel: 'traceBot',
      actionKey: 'orderMeal',
      traceInput: {
        meal: 'Pizza'
      },
      workflowId: dsl.$definitions.wfIds.restaurant
    }
  },
  cron_expression: '0 0 * * *',
  created_by: `restaurant` satisfies WorkflowLabel
});
// We store the scheduler infos in the state to be able to stop it later
state.data.scheduler = scheduler;

stopScheduler

An asynchronous function that stops a scheduler using its id.

Body
Example

string

required

The id of the scheduler to stop.

stopScheduler example

await dsl.$modules.stopScheduler({
  id: data.scheduler.infos.id
});

moment

Exposes the moment function from the moment library (v2.29.1).
See the moment documentation for more information.

Example

const { moment } = dsl.$modules;
const now = moment();
const tomorrow = moment().add(1, 'day');
const yesterday = moment().subtract(1, 'day');

zod

Exposes z from the zod library (v3.24.0).
See the zod documentation for more information.

Example

const { z } = dsl.$modules;

const isAdultSchema = z.object({
  name: z.string().min(2),
  age: z.number().min(18),
}).strict();

const myData = mySchema.parse({
  name: 'John',
  age: 30,
});

generatePdf

An asynchronous function that generates a PDF or a DOCX, PPTX, Excel based on a template and provided data.

Body
Example (pdf-lib)
Example (docx-templater)

string

required

The name of the generated PDF file.

string

required

The key of the PDF template to use, as defined in the workflow configuration.

string

required

The id of the trace where the PDF will be stored.

PdfFieldData[] | Record<string, unknown>

required

The data to fill the PDF template with.

'pdf-lib' | 'docx-templater'

required

The engine to use for PDF generation.

const { generatePdf } = dsl.$modules;

const { generatedFileInfo } = await generatePdf({
  generatedFileName: 'my-generated-pdf.pdf',
  templateKey: 'simpleExampleTemplate',
  traceId: dsl.$variables.meta.traceId,
  fillData: {
    name: 'Name',
    value: 'Stratumn',
    type: 'text',
  },
  version: 'pdf-lib',
});

const { generatePdf } = dsl.$modules;
const { meta } = dsl.$variables;

// fillData can be a Record<string, unknown> with docx-templater
const fillData = {
  candidateName: 'John Doe',
  experience: '5 years',
  skills: ['TypeScript', 'React', 'Node.js'],
};

const { generatedFileInfo } = await dsl.$modules.generatePdf({
  generatedFileName: `CV_John_Doe_SIA_en.pptx`,
  templateKey: 'superSiaTemplatePptx',
  traceId: meta.traceId,
  fillData,
  version: 'docx-templater'
});

Example - Order a meal

Let’s imagine a restaurant workflow where a client can order a meal. The workflow has two groups: cook and client. In the first action, the client will select a meal to order and submit the form. The goal of the effect is to:

store the selected meal in the trace’s data,
add the 'Order received' status to the trace with a progress of 20%,
and update the next available actions for each group:
the cook group should be able to do the prepareOrder action and comment,
the client group should only be able to do the comment action.

orderMealEffect

async function orderMealEffect(dsl: RestaurantWorkflowContext<FormData>) {
// We destructure the DSL variables for readability
  const { state, formData } = dsl.$variables;
  const { data, nextActions } = state;

  // The chosen meal is retrieved from the form data and stored in the data
  data.meal = formData.meal;

  data.status = {
    status: 'Order received',
    progress: 0.2
  };

  // Now, we update the next actions
  nextActions = {
    cook: ['prepareOrder', 'comment'],
    client: ['comment']
  };
}

const effects = [execJs(orderMealEffect)] satisfies Statement[];

​What are the effects?

​Workflow definitions

​Notifications

​The Stratumn constant

​Batch context

​Ordering is not guaranteed

​External functions

​Example - Order a meal

What are the effects?

Workflow definitions

Notifications

The `Stratumn` constant

Batch context

Ordering is not guaranteed

External functions

Example - Order a meal