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

repo

object

The repository of the workflow where workflow constants are stored.

functions

object

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

wfIds

object

A map between the workflow label and its id.

env

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.

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

workflowId

string

required

The id of the target workflow.

traceId

string

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

action

string

required

The action that will be done.

formData

object

required

The form data to be used in the action.

groupLabel

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'.

createdAt

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

workflowId

string

required

The id of the workflow to search traces in.

filters

JSONDeepFilterValue[]

The filters to apply to the search.

Show JSONDeepFilterValue type

TextFilterValue
NumberFilterValue
DateFilterValue

type

literal

required

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

path

JMESPath

required

The JMESPath to apply to the filter.

value

string

required

The value to filter on.

exact

boolean

Whether the filter should be an exact match.

not

boolean

Whether the filter should be a negative match.

type

literal

required

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

path

JMESPath

required

The JMESPath to apply to the filter.

value

string

required

The value to filter on.

type

literal

required

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

path

JMESPath

required

The JMESPath to apply to the filter.

value

string

required

The value to filter on.

format

string

The format of the stored date to filter on.

inputFormat

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

name

string

required

The unique name of the scheduler.

data

object

The data that will be used by the scheduler.

cron_expression

string

required

The cron expression that defines the schedule.

created_by

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,
});

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: Statement[] = [execJs(orderMealEffect)];

Workflow configuration

​What are the effects?

​Workflow definitions

​Notifications

​External functions

​Example - Order a meal

What are the effects?

Workflow definitions

Notifications

External functions

Example - Order a meal