First steps with automation

A workflow is a list of instructions called Step objects. Each Step has an APISpec field which defines how the HTTP call must be made. This way it would be easy for you to create your OWN workflow automation and publishing modal!

Workflow Syntax

There are 4 parts

  • step
  • APISpec
  • retry
  • workflow

Every workflow is made of a set of steps. Each step has n APISpec, that can be associated with additional configurations and retries.

The step

fieldtypedescriptionvalid values
concurrencyintdefined the number of workers this task will need.integer
apispecAPISpecas defined above-
inputstrinput for the stepoptional string
outputstroutput from the stepoptional string
namestrstep name fro identification# names of all the steps in a workflow must be unique
retryRetryas defined aboveoptional

The APISpec

fieldtypedescriptionvalid values
urlstrdefine the URL to hit-
methodstrdefine REST API methods hereAll HTTP verbs (gfet, put, post
data[Union[dict, str]]-Optional
The field value can be dict, str or None
headersOptional[Union[dict, str]]-Optional
The field value can be dict, str or None
paramsOptional[Union[dict, str]]-Optional
The field value can be dict, str or None
json_bodyOptional[Union[dict, str]]-Optional
The field value can be dict, str or None
timeoutintset a timeout for your APIinteger

The retry

fieldtypedescriptionvalid values
totalintTotal number of retries to allow. Takes precedence over other countsany integer
connectintHow many connection-related errors to retry onany integer
readintHow many times to retry on read errors.any integer
redirectintHow many redirects we allowany integer
statusintHow many times to retry on bad status codesany integer
otherintHow many times to retry on other errorsany integer
allowed_methodsList[str]HTTP verbs to retry oneg: ['GET', 'PUT', 'DELETE']
status_forcelistList[int]HTTP status codes to retry [413, 429, 503]
backoff_factorfloatbackoff factor to apply between attempts after second tryany float number
raise_on_redirectbool-True/ False
raise_on_statusbool-True/ False
respect_retry_after_headerboolWhether to respect Retry-After header on status codes - [413, 429, 503]True/False

The workflow

fieldtypedescriptionvalid values
uidOptional[UUID]a unique numeral identifier-
namestrplain text english identifier, name the workflow-
scopeScopeEnumthis will be of type ScopeEnum (discussed below)values can be 'workspace' or 'global'
stepsList[Step]defines what happens in the workflow-
workspace_idUUIDMason workspace id-
user_idEmailStremail id of the user-
deletedbool-True/ False
default_retry defines the default retry configuration for steps. It can be overriden by the retry field inside Step
class ScopeEnum(str, Enum):
  workspace_scope = 'workspace'
  global_scope = 'global'

Flow & Steps

The main field of interest in a workflow definition is flow. It contains a list of one or more steps to be executed. In this case, we have a single step. Each step is named (in this case the name is auth). The name can be any unicode string chosen by the workflow author. The name of each step in the flow must be unique.

Workflow state

Each workflow has a global "state" available which is pre-populated with a set of fields. A step in the workflow can also populate different fields in the global state which other steps will have access to. These fields can be accessed in jinja templates. In the above workflow, you can see the following state fields in action -

SYSTEM_APIS - this will have a set of mason api urls prepopulated for use in the workflow. For example SYSTEM_APIS.credentials will resolve accordingly.
USER - this field will have information about the caller such as token, workspace_id, userid etc.
CURRENT_STEP - this is a transient field whose value depends on the state of the step under execution. It will have sub fields which are specific to the current step such as response & input.
The full list of all the fields available in the global state is in the Workflow State doc.


A default retry configuration can be set at the top level. It can also be overridden at the level of each step.

What’s Next

Let's put this to action, in the user guide below you will find step-wise examples of making automation workflows.