Actor

An actor is a person, team, or system that participates in a process.

Items in the actors property of the scenario aren't actor objects, but JSON schemas defining the properties available for the actor once instantiated in the process.

YAML

actors:
  organization:
    title: Employer
    role: manager
    properties:
      name: string
      email: !format email
  employee:
    title: Employee
    $ref: "https://schemas.example.com/actors/employee.json"

JSON

{
  "actors": {
    "organization": {
      "title": "Employer",
      "role": "manager",
      "properties": {
        "name": "string",
        "email": {
          "type": "string",
          "format": "email"
        }
      }
    },
    "employee": {
      "title": "Employee",
      "$ref": "https://schemas.example.com/actors/employee"
    }
  }
}

The actor schema always defines an object type. This is implicit. Actors can't be a composite type (using oneOf, allOf, or anyOf).

Schema

https://schemas.letsflow.io/v1.0.0/actor

The actor schema extends a JSON Schema. Other JSON Schema properties are also allowed.

Properties

title

The title of the actor. If omitted, this is created from the actor key.

role

string or array of strings

Use for access control. Any user that has this role can perform as this actor. If multiple roles are specified, the user must have at least one of these roles.

organization:
 role: manager

If the role of an actor is defined in the scenario, it can't be changed with start instructions or during the process.

properties

map of schemas

By default, a process actor only has an id, title, and role. Other properties must be specified in the actor schema.

participant:
  properties:
    name: string
    email: !format email
    age:
      type: number
      min: 16
    active: !default true

Schema

additionalProperties

boolean or schema

By default, it's not allowed to set properties of an actor that aren't defined in the schema. In other words; the JSONSchema additionalProperties value default to false.

You may set this property to true to allow additional properties to be set for the process actor. Alternatively, you can specify a schema to which all additional properties need to comply.

External schema

Instead of defining the schema within the scenario, you can reference an external schema for reusability.

The title and role property of external schema is ignored. They should be specified in the scenario.

client:
  title: Support desk
  role: support
  $ref: "https://schemas.example.com/actors/support.json"

Read more about using custom schemas in the validation chapter.

Wildcard actors

Wildcard actors allow for defining a flexible number of participants in a process without explicitly naming or enumerating them. This is achieved by using a wildcard pattern in the actor key, such as person_*. For example:

actors:
  person_*:
    title: Participant
    properties:
      name: string
      email:
        type: string
        format: email

In this example, each actor with a key like person_1, person_2, and so on will share the same schema.

Start instructions

When the process is instantiated, actors matching this pattern in the start instructions will be dynamically created, each with the same schema.

{
  "scenario": "76261ffa-76e9-49c8-be38-2ba660dd2f5b",
  "actors": {
    "person_1": {
      "id": "b7800456-58c2-4b03-85f6-d4a2e48450e3",
      "name": "Alice",
      "email": "[e-mail]"
    },
    "person_2": {
      "id": "b76c2747-c3c2-4cc8-8509-acc5cf038ca1",
      "name": "Bob",
      "email": "[e-mail]"
    },
    "person_3": {
      "id": "fdeac62e-2451-4e95-a8c1-cf1234cd0745",
      "name": "Charlie",
      "email": "[e-mail]"
    }
  }
}

Creation at runtime

Alternatively, actors can be added at runtime using update instructions.

actions:
  invite:
    response:
      type: array
      items:
        properties:
          id: !format uuid
          name: string
          email: !format email
     update:
       set: actors
       mode: merge
       value: !ref current.response | to_object(zip(range(1, length(@) + 1, 'person_'), @))