Trace - Stratumn

State

Each trace has a state object which contains the business data but also metadata about the trace’s lifecycle. The state object can be accessed in the effects via dsl.$variables.state and has the following properties:

data

object

The business data of the trace.

nextActions

object

A mapping between a group label and it’s next possible actions.

tasks

object

The most relevant next actions for each group.

notifications

object

The notifications that will be sent to the user.

Data

The dsl.$variables.state.data property is an object that holds the business data for the trace, structured according to the workflow’s specifications. The data are updated by the effects of each action and is usually used to display the trace’s data in the workflow overview table and trace infos.

Next actions

Description
Type
Example

The dsl.$variables.state.nextActions property defines which actions are available for each group. It is defined as a map between a group label and a list of actions keys.

Typescript

type NextActions<
  GroupLabel extends string, 
  ActionKey extends string
> = {
  [key in GroupLabel]?: ActionKey[];
};

Example

{
  "cook": ["prepareOrder", "comment"],
  "client": ["comment"]
}

Tasks

The dsl.$variables.state.tasks property, also referred to as priorities, defines which next actions are the most relevant for a group. When a group has a next priority action defined, it will be displayed in the Trace UI homepage.

{
  ...
  tasks: {
    groups: {
      cook: { // the group label
        responsibility: 1,
        todo: ['cookOrder'] // the next priority
      }
    },
    deadlines: [
      {
        date: '2025-11-20' // optional deadline
      }
    ]
  }
  ...
};

A deadline can be optionally defined for a task.

Meta

Description
Documentation
Type
Example

The read-only dsl.$variables.meta object contains metadata about the trace, as well as the last performed action. It is automatically generated before effects are applied and can not be modified.It’s usually used to get context about the trace in the effects or to display information using widgets.

createdAt

string datetime

The date of creation of the last or current link.

action

object

Informations about the last performed action.

Show action's properties

action.key

string

The key of the action.

action.title

string

The title of the action.

action.icon

string

The name of the icon of the action.

createdBy

object

Informations about the user who submitted the last link.

Show createdBy's properties

createdBy.id

string

The id of the user.

createdBy.email

required

The email of the user, it also acts as an user identifier.

createdBy.avatar

URL | null

The avatar’s url of the user.

createdBy.name

string

required

The full name of the user.

createdBy.firstName

string

The first name of the user.

createdBy.lastName

string

The last name of the user.

createdBy.type

literal

required

The type of the user.

group

object

Informations about the group of the user that submitted the last link.

Show group's properties

group.id

string

required

The id of the group.

group.label

string

required

The label of the group, it also acts as a group identifier.

group.name

string

required

The name of the group.

group.avatar

URL | null

The avatar’s url of the group.

process

object

Informations about the workflow.

Show process's properties

group.name

string

required

The id of the workflow. For example: "12".

process.state

'FREE' | 'DRAFT'

required

The state of the workflow.

traceCreatedAt

string datetime

The date of creation of the trace.

traceName

string

The name of the trace. Automatically generated using the workflow’s name and the index of the trace in the workflow. Example: ORDER-21

traceId

UUID

The id of the trace.

traceShortId

string

The first 6 characters of the trace id.

Typescript

type LinkMetaData = {
  createdAt: string;
  action: {
    key: string;
    title: string;
    icon: string;
  };
  createdBy: {
    type?: string;
    accountId?: string;
    name: string;
    firstName?: string;
    lastName?: string;
    avatar: string | null;
    email?: string;
    id?: string;
  };
  group: {
    label: string;
    id: string;
    name: string;
    avatar: string | null;
  };

  traceCreatedAt: string;
  traceName: string;
  traceId: string;
  traceShortId: string;
  process: {
    name: string;
    state: string;
  };
  /** @deprecated */
  owner: {
    id: string;
    name: string;
    avatar: string | null;
  };

  /** @deprecated */
  inputs: string[];
};

Example

{
"head": {
  "action": {
    "icon": "lucide_CookingPot",
    "key": "prepareOrder",
    "title": "Prepare order"
  },
  "createdAt": "2024-10-09T15:14:42.973Z",
  "createdBy": {
    "avatar": "https://media-api.stratumn.com/files/111439687e669296785751469eeece665882021e1ea6",
    "email": "[email protected]",
    "firstName": "Jane",
    "id": "888",
    "lastName": "Doe",
    "name": "Jane Doe",
    "type": "User"
  },
  "group": {
    "avatar": "https://media-api.stratumn.com/files/111439687e669296785751469eeece665882021e1ea6",
    "id": "999",
    "label": "cooks",
    "name": "The cooks"
  },
  "inputs": [],
  "owner": {
    "avatar": "https://media-api.stratumn.com/files/111439687e669296785751469eeece665882021e1ea6",
    "id": "999",
    "name": "The cooks"
  },
  "process": {
    "name": "12",
    "state": "FREE"
  }
},
"links": {
  "totalCount": 9
},
"traceCreatedAt": "2024-05-03T08:33:58.533Z",
"traceId": "1f242572-3eb9-4341-986b-9cccf4121dc1",
"traceName": "ORDER-20",
"traceShortId": "1f2425"
},

If the query context is a widget, properties related to the last link are nested under the head property.

Formdata

The dsl.$variables.formData object is the data submitted by the user in the current action.

{
  "data": {
    "order": {
      "name": "Pineapple pizza",
      "date": "2024-04-24T09:16:56.316Z",
      "price": 10
    },
    "isPaid": true,
    "status": {
      "progress": 0.5,
      "value": "Pizza is being prepared"
    },
    "isTraceClosed": false,
    "comments": [...],
  },
  "nextActions": {
    "cook": ["prepareOrder", "comment"],
    "client": ["comment"]
  },
  "tasks": {
    "groups": {
      "cook": {
        "responsibility": 1,
        "todo": ["prepareOrder"]
      }
    }
  },
  "notifications": {...}
}

Workflow configuration

​State

​Data

​Next actions

​Tasks

​Meta

​Formdata

State

Data

Next actions

Tasks

Meta

Formdata