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
By default, these HTTP requests will receive the automation output as a response body.
However, an $http variable available inside the automation gives full control over the response status code or headers :
- set:
name: $http
value:
headers:
foo: bar
status: 400
- set:
name: $http
value:
headers:
foo2: bar2 # More headers
This variable also allows writing SSE events in order to stream response chunks in real time :
- set:
name: $http
value:
chunk: # A custom data object that will be stringified & injected in SSE events
foo2: bar2
- set:
name: $http
value:
chunk: # Another chunk
foo2: bar2
- $http is only available in the URL triggered automation & not from children calls (unless explicitly passed as a parameter)
- headers cannot be set after the first chunk set
- When using SSE events (i.e with chunk), the automation output will also be sent as a last event
- Sending SSE events automatically sets the following headers :
Content-Type: "text/event-stream" Cache-Control: "no-cache" Connection: "keep-alive"
When developing long running SSE endpoints, you can configure a keep-alive to avoid timeouts :
- set:
name: $http
value:
sseKeepAlive: 5000 # Keep alive interval in millisecond, minimum 5000ms
data: {"keepAlive": true} chunk will be regularly emitted until the connection ends.
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
Schedules¶
An automation can be regularly triggered, based on a list of cron schedules.
An automation can be schedule at most every 15 minutes.
Here is a valid example of schedule :
when:
schedules:
- '* * * * *'
Whenever an automation is successfully planned a runtime.automations.scheduled event is emitted within the workspace, you can observe it on the workspace's Activity Feed.
The automation will be scheduled "on the hour", that means if you schedule it to repeat every 20 minutes at 3:14, the job will first run at 3:20, then 3:40, and so on.
Also, when you schedule your automation keep in mind that it will be executed based on the UTC timezone.
The following schedule : 0 5 * * * means it will be run every day at 5:00 UTC.
If you need help creating your cron, here is a little tool that can help writing one.
Here is a video walkthrough about scheduling:
🕑 Schedule an automation · Prisme.ai - 3 February 2023 - Watch Video
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 |
|
| workspaces.apps.configured | Some AppInstance config has been updated |
|
| workspaces.apps.installed | Some AppInstance has been installed |
|
| workspaces.apps.uninstalled | Some AppInstance has been uninstalled |
|
| workspaces.deleted | Workspace deleted |
|
| apps.published | Workspace published as an app |
|
| apps.deleted | Workspace app unpublished |
|
| runtime.fetch.failed | A fetch received a 4xx or 5xx HTTP status |
|
| runtime.webhooks.triggered | A webhook has been called |
|
| runtime.schedules.triggered | A schedule has been triggered |
|
| runtime.automations.scheduled | An automation has been succesfully scheduled following its schedules |
|
| workspaces.pages.permissions.shared | Some page has been shared with someone |
|
| workspaces.pages.permissions.deleted | Someone's access to the page has been removed |
|
| workspaces.versions.published | A new workspace version has been committed |
|
| workspaces.versions.rollback | A previous version has been rolled-back |
|
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.
Arguments validation¶
Automation arguments types can also be used to automatically validate input arguments during execution.
Arguments validation can be enabled with a validateArguments: true option at the automation's root.
For example, take the following HTTP automation :
slug: test
name: test
do: []
when:
endpoint: true
output: '{{body}}'
arguments:
body:
type: object
required:
- str
properties:
str:
type: string
uri:
type: string
format: uri
obj:
type: object
required:
- un
properties:
un:
type: string
pattern: '^[a-z]+$'
validateArguments: true
With the following (invalid) curl :
curl -X POST -H "content-type: application/json" http://<API_URL>/v2/workspaces/<WORKSPACE_ID>/webhooks/test -d '{"str": "ola2", "obj": {"un": "test 1"}}'
The following HTTP error would be returned :
{
"error":"InvalidArgumentsError",
"message":"Invalid arguments",
"details":[
{
"keyword":"pattern",
"dataPath":".body.obj.un",
"schemaPath":"#/properties/body/properties/obj/properties/un/pattern",
"params":{"pattern":"^[a-z]+$"},
"message":"should match pattern \"^[a-z]+$\""
}
]
}
Notes :
* Arguments validation is not reserved to HTTP automations & is also applied during direct calls or through events.
* Arguments support different well-known formats (date, url, time, password, ...) described here
* Validation errors immediately stop current and parent automations.
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. In case of a manually set session, it expires 1 hour after the last set (configurable with CONTEXT_UNAUTHENTICATED_SESSION_EXPIRE_TIME env var)
- run : this context holds some technical information about current run, and is automatically removed 60 seconds after the last automation run (configurable with CONTEXT_RUN_EXPIRE_TIME env var)
- socket : If user is connected through an events websocket, this context holds a temporary state local to this websocket, useful to separate state between multiple browser tabs for example. This context automatically expires after 6h without any set
- 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, in which case written data would be persisted and made available in subsequent requests. The only exception is when setting variables inside session/user contexts from an unauthenticated webhook, user and session will not be persisted.
However, sessions can be manually created or switched by setting the session.id field ; user and session contexts are then automatically reloaded with values from the targeted user contexts (or initialized, if the sessionId does not exist).
This allows unauthenticated webhooks to retrieve persisted user / sessions contexts identified by custom webhook fields (i.e a facebook userId, ...).
Any set variable to one of these contexts is automatically synchronized with parents or child automations triggered for the same run (i.e correlationId), making the freshly set variable visible in these parallel automations.
Detailed contexts¶
Global¶
| Variable name | Description |
| global.workspaceId | Current workspaceId |
| global.workspaceName | Current workspace name |
| global.apiUrl | Current API instance public url (fulfilled by runtime **API_URL** variable) |
| global.endpoints | Map of available endpoint slugs to the corresponding public url |
| global.studioUrl | Current studio instance public url (fulfilled by runtime **STUDIO_URL** variable) |
| global.pagesUrl | Current workspace pages public url (built from workspace slug and runtime **PAGES_HOST** variable) |
| global.pagesHost | Current pages instance base domain (fulfilled by runtime **PAGES_HOST** variable) |
| global.workspacesRegistry | Map public workspaces' slug to their id & name |
User¶
| Variable name | Description |
| user.id | Current user id |
| user.email | If available, current user email |
| user.authData | Detailed authentication data from various auth providers this user logged in with |
| user.role | If any, current user role |
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.socketId | Current socket id, if connected by websocket |
| 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) |
| run.automationSlug | Current automation slug |
| run.ip | Source event or HTTP request IP |