Automations

Definitions

In simple words, automations describes what to do and when.
The what is described as a sequence of instructions, and the when is defined with triggers.

Example :

A HubspotDealsOnSlack automation might send a notification message on Slack every time a new Hubspot deal is created by sales teams.
Technically, the what would be a fetch instruction calling Slack API to send a message.
On the other side, the when would be an URL (i.e webhook) trigger that Hubspot will call everytime a new deal is opened.

Triggers

Inside the automation graph, the triggers can be configured with the very first block at the screen top.

URL

When an automation activates its URL trigger, it becomes publicly available through an URL which you can copy from your Workspace graph or source code. At this point, you might paste the URL inside whatever external service (i.e Hubspot) configuration with webhooks capabilities.

From inside the automation defining an URL triger, 4 variables give access to input HTTP requests :

• body
• headers
• method
• query

Events

An automation can also listen to a list of events.
Whenever such events are received, the automation is executed & can access event payload with payload variable, and event source (source IP, correlationId, userId, automation, ...) with source variable.

These events can be :

• Native events
• Emitted from the same workspace
• Emitted from an AppInstance

Supported native events

Workspaces can only listen to a limited subset of the available native events :

Event name	Description	Payload fields
workspaces.configured	Workspace config has been updated	{ "config": Config object from workspace.config }
workspaces.apps.configured	Some AppInstance config has been updated	{ "appInstance": AppInstance object from workspace.imports, "slug": AppInstance slug }
workspaces.apps.installed	Some AppInstance has been installed	{ "appInstance": AppInstance object from workspace.imports, "slug": AppInstance slug }
workspaces.apps.uninstalled	Some AppInstance has been uninstalled	{ "appInstance": AppInstance object from workspace.imports, "slug": AppInstance slug }
workspaces.deleted	Workspace deleted	{ "workspaceId": workspace id }
apps.published	Workspace published as an app	{ "app": App object }
apps.deleted	Workspace app unpublished	{ "appSlug": Unpublished app slug }
runtime.fetch.failed	A fetch received a 4xx or 5xx HTTP status	{ "request": fetchInstructionBody, "response": { "status": 500, "body": {...}, "headers": {...} } }
runtime.webhooks.triggered	A webhook has been called	{ "request": fetchInstructionBody, "response": { workspaceId: "workspace id", automationSlug: "webhook slug", method: "httm method" } }

All of these events and object types indicated by Payload fields column are fully described inside the Schemas section at the bottom of our API Swagger.

Instructions

Once triggered, the automation will execute every defined instruction one after another, as configured from your automation graph.
Native instructions like set, conditions or repeat help structuring the execution flow and leveraging persistent contexts, while fetch and emit provide 2 ways of communicating with external services.
fetch instruction sends an HTTP request and wait for its response before moving forward, and emit sends an event without expecting any response.

Finally, automations can also directly call each others and retrieve their respective output.

More details on available instructions

Arguments

When calling a native instruction or another automation, differents arguments can be transmitted :

And there is the corresponding source code :

- set:
    name: slotFilling
    value:
      field: '{{field}}'
      question: '{{question}}'

However, these graphical inputs are not reserved to native instructions, but can also be configured for your own custom automations. This is achieved by specifying the name of the expected arguments, alongside their expected type.

For now, specifying these expected arguments must be done from the arguments field inside the automation source code, which follows JSON Schema standard.

Here is the source code for an automation leveraging every supported graphical input :

  testArguments:
    name: testArguments
    arguments:
      someString:
        type: string
      someNumber:
        type: number
      someObject:
        type: object
        properties:
          someStringField:
            type: string
      someOtherObject:
        type: object
        properties:
          nestedObject:
            type: object
            properties:
              someField:
                type: number
      someStringArray:
        type: array
        items:
          type: string
      someObjectArray:
        type: array
        items:
          type: object
          properties:
            fieldA:
              type: string
      someRawJSON:
        type: object
        additionalProperties: true          
      someToken:
        type: string        
        secret: true
    do:
      ...

When calling this automation, this form will show up :

... producing the following source code :

    - testArguments:
        someString: Hello world
        someNumber: '24'
        someObject:
          someStringField: My object field
        someOtherObject:
          nestedObject:
            someField: '1'
        someStringArray:
          - This is the first value of my array argument
        someObjectArray:
          - fieldA: foo
        someRawJSON:
          custom: JSON

The last someToken argument defined with secret: true does not differ visually, but is automatically redacted from native runtime events (i.e runtime.automations.executed, runtime.contexts.updated, ...). This avoids accidental leaks of sensitive information through native Prisme.ai events.

Output

Native instructions & automations can return some data that will be :

• Answered to the calling URL trigger
• Transferred to the calling automation, if any

Inside the automation graph, the output can be configured with the latest block at the screen bottom.

Variables

Inside your automation instructions, dynamic data can be injected by surrounding a variable name with double braces : {{some.variable.name}}. Here, the double braces indicate that this word will be replaced with the corresponding variable value.

As soon as your automation is created, a few variables is natively provided and ready to use (see contexts), but more variables can be created/removed using set and delete instructions.

In case of objects or array variables, it is even possible to access a specific sub key using another variable, like this :

{{session.myObjectVariable[{{item.field}}]}}

If session.myObjectVariable equals to {"mickey": "house"} and item.field equals to mickey, the entire expression will resolve to house.

Contexts

Contexts are special variables maintained accross executions in order to provide a persistent memory.

6 contexts are available :

• global : this context is shared by all authenticated users for the same workspace.
• user : this context holds user-specific data and spans accross sessions
• session : this context holds session-specific data. It is automatically removed when the user session expires, as defined by Gateway API.
• run : this context holds some technical information about current run, and is automatically removed 60 seconds after the initial trigger (configurable with CONTEXT_RUN_EXPIRE_TIME env var)
• config : this context holds current workspace or AppInstance config
• $workspace : this read-only context holds current workspace definition, allowing to read any of its sections like installed apps config (i.e $workspace.imports.myApp.config)

Except for $workspace, all of these contexts might be written to using set instruction.

However, note that user and session contexts rely on an authenticated user id for being persisted.
In case the automation is triggered from a webhook without any session cookie / token, user and session will not be persisted, making any variable set not visible from subsequent requests (and possibly silently breaking some workspace functionnality).

Detailed contexts

Global

Variable name	Description
global.workspaceId	Current workspaceId
global.apiUrl	Current API instance public url (fulfilled by runtime **PUBLIC_API_URL** variable)
global.endpoints	Map of available endpoint slugs to the corresponding public url

User

Variable name	Description
user.id	Current user id
user.email	If available, current user email
user.authData	For now, basic & empty object containing either prismeai or anonymous key, depending on user authentication mode

When an automation sets session.id field, user and session contexts are automatically reloaded with values from the targeted user contexts.
This allows unauthenticated webhooks to retrieve persisted user / sessions contexts identified by custom webhook fields (i.e a facebook userId, ...).

Session

Variable name	Description
session.id	Current session id

If current user has been authenticated through the Gateway API (whether anonymously or not), the session context expiration depends on the value configured in the Gateway API (1 month by default).
If current user comes from an unauthenticated endpoint call, its session context will expire after 1 hour, configurable from CONTEXT_UNAUTHENTICATED_SESSION_EXPIRE_TIME environment variable.

Run

Variable name	Description
run.depth	Current automation depth in the stacktrace
run.correlationId	Current run correlationId
run.appSlug	If running from an appInstance, current app slug
run.appInstanceSlug	If running from an appInstance, current appInstance slug
run.parentAppSlug	If parent is also an appInstance, parent app slug
run.date	Current ISO8601 date
run.trigger.type	Trigger type of the current automation run (event, endpoint, automation)
run.trigger.value	Trigger value of the current automation run (event/endpoint/ automation name)

Custom run variables (defined through set instruction) are automatically synchronized between concurrent automations running for the same correlationId (i.e cascading automations triggered by events)