API docs by Redocly

Boomi Flow (v1)

Boomi Flow API

This API reference provides information on the available endpoints in the Boomi Flow REST API, including parameters and response data format.

As Boomi Flow is based on an API-first architecture, many of the operations performed within Boomi Flow can be accessed through this API.

Before you can start using the API, you will need to create a Boomi Flow account.

Making a request to the API

API endpoint requests should be appended to the Boomi Flow API Host at:

  • flow.boomi.com

For example:

GET https://flow.boomi.com/api/draw/1/flow

NOTE: The API tool in Boomi Flow allows you to automatically authorize and interact with the API within the Boomi Flow application.

Authentication

The API supports authorization using an API Key .

API keys are specific to a tenant, meaning that each API key only authenticates you for the tenant selected when generating the API key.

You can manage your API keys on the Boomi Flow User Settings page.

Authentication using an API Key

To use an API Key to authenticate requests to the Boomi Flow API:

  1. Generate an API Key in Boomi Flow, or by sending a POST request to the api/admin/1/users/me/keys endpoint.

  2. Add a x-boomi-flow-api-key header to your API requests instead of an Authorization header, to authenticate as yourself. This header should contain only the apiKey value of the API Key.

  3. If required, add a manywhotenant header referencing the tenant ID value that the API key is associated with.

Provisioning

Provision a Tenant

This endpoint requests the provisioning of a new tenant, and also creates a new user if one doesn't exist with the given email address. If a value is given for the notification object, then the provisioning email sent to the user will be overridden with the provided message.

Request Body schema:
firstName
string or null

The first name of the user

lastName
string or null

The last name of the user

email
string or null

The email of the user

tenantName
string or null

The name of the tenant to create

apiKeyName
string or null

Responses

Request samples

Content type
No sample

Provision a Tenant

This endpoint requests the provisioning of a new tenant, and also creates a new user if one doesn't exist with the given email address. If an apiKeyName is provided an API Key will also be created for the new tenant.

Request Body schema:
firstName
string or null

The first name of the user

lastName
string or null

The last name of the user

email
string or null

The email of the user

tenantName
string or null

The name of the tenant to create

apiKeyName
string or null

Responses

Request samples

Content type
No sample

Runtimes

List Runtimes

Returns a list of runtimes associated with the current organization.

Responses

Response samples

Content type
[
  • {
    }
]

Create Runtime

Creates a new runtime inside the current organization.

Request Body schema:

Details to use when creating the organization

developerName
string or null

The name to use for the created runtime

Array of objects or null (RuntimeCreateRequestTenant)

Any tenants to associate with the runtime

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "developerName": "string",
  • "installationToken": "string",
  • "status": 0,
  • "tenants": [
    ]
}

Load Runtime

Loads an associated runtime by ID in the current organization.

path Parameters
id
required
string <uuid>

The ID of the runtime to find

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "developerName": "string",
  • "nodes": [
    ],
  • "reportedAt": "2019-08-24T14:15:22Z",
  • "status": 0,
  • "tenants": [
    ],
  • "uri": "string"
}

Update Runtime

Updates a runtime by ID in the current organization.

Runtimes can be associated with one or more tenants, and any changes to properties take effect globally, and are reflected across all associated tenants.

path Parameters
id
required
string <uuid>

The ID of the runtime to update

Request Body schema:

The fields to update in the runtime

developerName
string or null

The new name to use for the runtime

Array of objects or null (RuntimeUpdateRequestTenant)

Any tenants to associate with the runtime

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "developerName": "string",
  • "nodes": [
    ],
  • "reportedAt": "2019-08-24T14:15:22Z",
  • "status": 0,
  • "tenants": [
    ],
  • "uri": "string"
}

Delete Runtime

Deletes a runtime by ID in the current organization.

Runtimes can be associated with one or more tenants, and deleting a runtime will take effect globally, removing access from all associated tenants.

path Parameters
id
required
string <uuid>

The ID of the runtime to delete

Responses

List Runtime Failures

If the Flow cloud encounters an error communicating with a local runtime, details about the failure will be available from this endpoint.

path Parameters
id
required
string <uuid>

The ID of the runtime

query Parameters
pageSize
integer <int32>
Default: 50

The number of states to return

page
integer <int32>
Default: 1

The current page of states

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

States

The flow state object provides data about a specific instance of a running flow

A flow state provides in-depth information about how users have interacted with a flow, from the data that has been collected in values, to the path of map elements that were travelled, to the users who have interacted with the flow at the various stages of its execution. Flow state data is only available for active flows that have not yet completed.

This API should also not be used for reporting purposes as we have a separate reporting API and reporting infrastructure.

List States

Get a listing of all the flow states in the current tenant.

query Parameters
pageSize
integer <int32>
Default: 10

The number of states to return

page
integer <int32>
Default: 1

The current page of states

status
string

The status of the states to filter by

from
string <date-time>

An ISO 8601 datetime to filter states from

to
string <date-time>

An ISO 8601 datetime to filter states until

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Delete Multiple States

Delete multiple flow states

Request Body schema:

An array of IDs of the states to delete

Array
string <uuid>

Responses

Request samples

Content type
No sample

Load State

Load an individual flow state

path Parameters
id
required
string <uuid>

The ID of the state to load

Responses

Response samples

Content type
{
  • "id": "string",
  • "parentId": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "currentFlowId": {
    },
  • "currentFlowDeveloperName": "string",
  • "currentMapElementId": "string",
  • "currentMapElementDeveloperName": "string",
  • "entryOutcomeId": "string",
  • "entryOutcomeDeveloperName": "string",
  • "currentStreamId": "string",
  • "currentRunningUserId": "string",
  • "currentRunningUserEmail": "string",
  • "currentRunningUserExternalId": "string",
  • "externalIdentifier": "string",
  • "manywhoTenantId": "string",
  • "annotations": {
    },
  • "stateEntries": [
    ],
  • "precommitStateEntry": {
    },
  • "values": [
    ],
  • "authorizationHeader": "string",
  • "isDone": true,
  • "isExpired": true,
  • "log": {
    },
  • "joinUri": "string",
  • "rootFaults": {
    },
  • "hasRootFaults": true,
  • "storeId": "string",
  • "frames": [
    ],
  • "archivedFrames": [
    ],
  • "waitExpiresAt": "2019-08-24T14:15:22Z",
  • "isPageWait": true
}

Delete State

Delete an individual flow state

path Parameters
id
required
string <uuid>

The ID of the state to delete

Responses

List States by Flow

Get a listing of all the flow states grouped by flow in the current tenant.

query Parameters
pageSize
integer <int32>
Default: 10

The number of flow states to return

page
integer <int32>
Default: 1

The current page of flow states

orderBy
string
Default: "developerName"

The column to order the results by

orderDirection
string
Default: "ASC"

The direction the order will use

status
string

The status of the state to filter by

from
string <date-time>

An ISO 8601 datetime to filter results from

to
string <date-time>

An ISO 8601 datetime to filter results until

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

List States for a Flow

Get a listing of all the flow states for a specific flow in the current tenant.

path Parameters
id
required
string <uuid>

The ID of the flow

query Parameters
pageSize
integer <int32>
Default: 10

The number of flow states to return

page
integer <int32>
Default: 1

The current page of flow states

status
string

The status of the state to filter by

from
string <date-time>

An ISO 8601 datetime to filter results from

to
string <date-time>

An ISO 8601 datetime to filter results until

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

List States for a Flow Version

Get a listing of all the flow states for a specific flow version in the current tenant.

path Parameters
id
required
string <uuid>

The ID of the flow

version
required
string <uuid>

The version ID of the flow

query Parameters
pageSize
integer <int32>
Default: 10

The number of flow states to return

page
integer <int32>
Default: 1

The current page of flow states

status
string

The status of the state to filter by

from
string <date-time>

An ISO 8601 datetime to filter results from

to
string <date-time>

An ISO 8601 datetime to filter results until

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Tenants and Subtenants

A tenant provides a central place for flow builders to build, manage and deploy flows.

Once a tenant has been provisioned, there are various settings available to ensure security is correctly configured and data is properly managed for reporting purposes. The APIs below work for both tenants and subtenants. The only difference between a tenant and and subtenant is that flow builders can move between them using and the tenants are grouped together to ease management.

Load Tenant

Used to get the tenant object for the current tenant. Tenants provide a central place for flow builders to build, manage and deploy flows.

query Parameters
includeSubTenants
boolean
Default: false

Whether to include subtenants in the response

Responses

Response samples

Content type
{
  • "developerName": "string",
  • "developerSummary": "string",
  • "securitySettings": {
    },
  • "subdomain": "string",
  • "stateSettings": {
    },
  • "observabilitySettings": {
    },
  • "tenantSettings": {
    },
  • "externalStorageSettings": {
    },
  • "featureFlags": [
    ],
  • "id": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "subTenants": [
    ],
  • "organization": {
    },
  • "parentTenant": { },
  • "hasMcr": true
}

Update Tenant

Used to update the tenant object for the current tenant. Tenants provide a central place for flow builders to build, manage and deploy flows.

Request Body schema:
developerName
string or null

The unique developer name for the tenant. The developer name is related to the domain information provided in the builder username.

developerSummary
string or null

A summary of the tenant. This is typically additional information that will help explain the purpose of the tenant

object (SecuritySettingsAPI)

Specific security settings that should be applied to this tenant, beyond the defaults (excluding subtenants)

subdomain
string or null

The requested subdomain to register for this tenant. If provided, the subdomain must be unique for the entire platform

object (StateSettingsAPI)

Settings used for state persistence and reporting

object (ObservabilitySettingsAPI)

Settings used for runtime observabillity

object (TenantSettingsAPI)

Settings that are specific to features used in the tenant

object (ExternalStorageSettingsAPI)
Array of objects or null (FeatureFlagAPI)

Feature Flags related to the tenant

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "developerName": "string",
  • "developerSummary": "string",
  • "securitySettings": {
    },
  • "subdomain": "string",
  • "stateSettings": {
    },
  • "observabilitySettings": {
    },
  • "tenantSettings": {
    },
  • "externalStorageSettings": {
    },
  • "featureFlags": [
    ],
  • "id": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "subTenants": [
    ],
  • "organization": {
    },
  • "parentTenant": { },
  • "hasMcr": true
}

Delete Tenant

Responses

Delete Tenant Data

Request Body schema:
cultures
boolean

Indicates if all non-default cultures should be deleted

flows
boolean

Indicates if all flows should be deleted

pages
boolean

Indicates if all page elements should be deleted

values
boolean

Indicates if all value elements should be deleted

types
boolean

Indicates if all type elements should be deleted

services
boolean

Indicates if all service elements should be deleted

tags
boolean

Indicates if all tag elements should be deleted

snapshots
boolean

Indicates if all flow snapshots should be deleted

states
boolean

Indicates if all flow states should be deleted

macros
boolean

Indicates if all macro elements should be deleted

identityProviders
boolean
openApiSchemas
boolean

Indicates if all cached OpenAPI Schemas should be deleted

customPageComponents
boolean
releases
boolean
environmentVariables
boolean

Responses

Request samples

Content type
No sample

Update Expiry Date on Tenant

Used to set the Expires At date of a tenant.

Request Body schema:
newExpiryDate
string or null <date-time>

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "developerName": "string",
  • "developerSummary": "string",
  • "securitySettings": {
    },
  • "subdomain": "string",
  • "stateSettings": {
    },
  • "observabilitySettings": {
    },
  • "tenantSettings": {
    },
  • "externalStorageSettings": {
    },
  • "featureFlags": [
    ],
  • "id": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "subTenants": [
    ],
  • "organization": {
    },
  • "parentTenant": { },
  • "hasMcr": true
}

Load Subtenants

Used to list all the subtenants of the current tenant.

Responses

Response samples

Content type
[
  • {
    }
]

Create Subtenant

Used to create a new subtenant underneath the current tenant. The developerName must be unique, and can only contain letters and numbers, with no spaces.

Request Body schema:
developerName
string or null
developerSummary
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "developerName": "string",
  • "userCount": 0
}

List the Runtimes for a Tenant

Used to get the list of runtimes for the current tenant.

Responses

Response samples

Content type
[
  • {
    }
]

Users

Users provide basic information about flow builders and running users in a tenant

Users on the platform are identified via their email. As a result, the email address determines who the user is. The email address is the unique identifier across the entire platform. When running users access a flow, a user is provisioned into the tenant on-demand. In addition, flow builders are included in the user listing.

List Users

Get a listing of all users inside the current tenant.

query Parameters
pageSize
integer <int32>
Default: 30
page
integer <int32>
Default: 1

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Add User to Tenant

Request Body schema:
id
string <uuid>
firstName
string or null
lastName
string or null
email
string or null
createdAt
string or null <date-time>
Array of objects or null (OrganizationMinimal)
Array of objects or null (UserTenantAPI)
object (Role)
isSso
boolean
Array of objects or null (UserTokenAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "organizations": [
    ],
  • "tenants": [
    ],
  • "role": {
    },
  • "isSso": true,
  • "tokens": [
    ]
}

List Users

Get a listing of all users inside the a specified tenant.

path Parameters
tenantId
required
string <uuid>
query Parameters
pageSize
integer <int32>
Default: 30
page
integer <int32>
Default: 1

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Load User

Load an individual user from the current tenant.

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "organizations": [
    ],
  • "tenants": [
    ],
  • "role": {
    },
  • "isSso": true,
  • "tokens": [
    ]
}

Update User

Update information for an individual user in the current tenant.

path Parameters
id
required
string <uuid>
Request Body schema:
id
string <uuid>
firstName
string or null
lastName
string or null
email
string or null
createdAt
string or null <date-time>
Array of objects or null (OrganizationMinimal)
Array of objects or null (UserTenantAPI)
object (Role)
isSso
boolean
Array of objects or null (UserTokenAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "organizations": [
    ],
  • "tenants": [
    ],
  • "role": {
    },
  • "isSso": true,
  • "tokens": [
    ]
}

Remove User from Tenant

path Parameters
id
required
string <uuid>

Responses

Load the Current User

Get the currently-authenticated user's information

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "organizations": [
    ],
  • "tenants": [
    ]
}

Update the Current User

Update the currently-authenticated user's information

Request Body schema:
firstName
string or null
lastName
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "organizations": [
    ],
  • "tenants": [
    ]
}

Load the Current User's Tenant settings

Load the tenant user settings for the currently-authenticated user

Responses

Response samples

Content type
{
  • "notifications": {
    },
  • "enabledSSO": true,
  • "apiKeys": [
    ]
}

Update the Current User's Tenant settings

Update the tenant user settings for the currently-authenticated user

Request Body schema:
object (UserTenantSettingsNotificationsAPI)
enabledSSO
boolean
Array of objects or null (UserTenantAPIKey)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "notifications": {
    },
  • "enabledSSO": true,
  • "apiKeys": [
    ]
}

Get API Keys

Get the API Keys for the currently-authenticated user

Responses

Response samples

Content type
[
  • {
    }
]

Create a new API Key

Add a new API Key for a specific tenant for the currently-authenticated user

Request Body schema:
name
string or null
apiKey
string or null
createdAt
string <date-time>
tenantId
string or null <uuid>

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "name": "string",
  • "apiKey": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0"
}

Delete an API Key

Delete an API Key for a specific tenant for the currently-authenticated user

path Parameters
name
required
string

Responses

/api/admin/1/users/me/user-settings

Responses

Response samples

Content type
{
  • "canvasSettings": {
    }
}

Update the Current User's settings

Update the settings for the currently-authenticated user

Request Body schema:
object (CanvasSettings)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "canvasSettings": {
    }
}

Audit

/api/audit/1/search

query Parameters
type
Array of strings
from
string <date-time>
to
string <date-time>
user
Array of strings <uuid>
page
integer <int32>
pageSize
integer <int32>

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Dashboard

List number of launches (States) for a Flow

path Parameters
id
required
string <uuid>
query Parameters
interval
string

Responses

Response samples

Content type
{
  • "flowId": "ccd52024-9c9c-4751-993a-9d75a778bf9d",
  • "flowName": "string",
  • "flowLaunchTotal": 0,
  • "flowLaunchData": [
    ]
}

Assets

List Assets

Get a listing of all the assets in the current tenant

Responses

Response samples

Content type
[
  • {
    }
]

Delete Asset

Delete an individual asset (or folder)

Request Body schema:
contentType
string or null
key
string or null
name
string or null
modifiedAt
string <date-time>
publicUrl
string or null
size
integer <int64>

Responses

Request samples

Content type
No sample

Move Asset

Move an asset from one location to another (can also be used to rename an asset).

Request Body schema:
oldKey
string or null

The key of the asset to move

newKey
string or null

The key to move the asset to

Responses

Request samples

Content type
No sample

Create Folder

Create an empty "folder" in the current tenant's asset storage

Request Body schema:
contentType
string or null
key
string or null
name
string or null
modifiedAt
string <date-time>
publicUrl
string or null
size
integer <int64>

Responses

Request samples

Content type
No sample

Generate Upload URL

Generate a signed upload URL, which should be used to submit the asset to (using PUT). A contentType is required in this request.

Request Body schema:
contentType
string or null
key
string or null
name
string or null
modifiedAt
string <date-time>
publicUrl
string or null
size
integer <int64>

Responses

Request samples

Content type
No sample

Response samples

Content type
"string"

Custom Page Component Element

/api/draw/1/element/customPageComponent

query Parameters
overwriteExisting
boolean
Default: true
Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
key
string or null
legacyScriptURL
string or null
scriptURL
string or null
legacyStyleSheetURL
string or null
styleSheetURL
string or null
icon
string or null
object or null
configurationEditors
Array of strings or null
designTimeImageURL
string or null
designTimeRenderType
string or null
dateCreated
string <date-time>
dateModified
string <date-time>

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "key": "string",
  • "legacyScriptURL": "string",
  • "scriptURL": "string",
  • "legacyStyleSheetURL": "string",
  • "styleSheetURL": "string",
  • "icon": "string",
  • "attributes": {
    },
  • "configurationEditors": [
    ],
  • "designTimeImageURL": "string",
  • "designTimeRenderType": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z"
}

/api/draw/1/element/customPageComponent

query Parameters
filter
string
page
integer <int32>
Default: 1
pageSize
integer <int32>
Default: 20
orderBy
string
Default: "dateModified"
orderDirection
string
Default: "DESC"

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

/api/draw/1/element/customPageComponent/{id}

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "key": "string",
  • "legacyScriptURL": "string",
  • "scriptURL": "string",
  • "legacyStyleSheetURL": "string",
  • "styleSheetURL": "string",
  • "icon": "string",
  • "attributes": {
    },
  • "configurationEditors": [
    ],
  • "designTimeImageURL": "string",
  • "designTimeRenderType": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z"
}

/api/draw/1/element/customPageComponent/{id}

path Parameters
id
required
string <uuid>

Responses

List Component Key Dependents

List all of the elements that depend on the specified component key.

path Parameters
key
required
string

The key of the component to list dependents of

Responses

Response samples

Content type
[
  • {
    }
]

Draw

Get Custom Styles

path Parameters
tenantId
required
string

Responses

List Element Dependents

List the flattened tree of elements that depends on a specific element.

path Parameters
id
required
string <uuid>

The ID of the element to list dependents of

query Parameters
pageSize
integer <int32>
Default: 50

The number of dependents to return per page

page
integer <int32>
Default: 1

The current page number of dependents

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

List Element Dependencies

List the flattened tree of elements that a specific element depends on, including all registered dependencies of dependencies.

path Parameters
id
required
string <uuid>

The ID of the element to list dependencies of

query Parameters
pageSize
integer <int32>
Default: 50

The number of dependencies to return per page

page
integer <int32>
Default: 1

The current page number of dependencies

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Flow

Flows represent an entire application

Flows represent an atomic package of elements that when run, are fully versioned. Flows can reference other flows using a "flow out" or by messaging other flows in the tenant using the Runtime Service. When referencing flows (parent or subflows), the platform will always take the latest activated and default version of the flow.

When editing elements in a flow, you do not do this through this section of the APIs. Each element type has its own API endpoint for managing objects, etc.

As with group elements, a flow can also have permissions. However, unlike the group element, if a user cannot authenticate to a flow, they cannot access any part of the flow state. Effectively, the flow authorization protects your flow application from any access by running users that cannot successfully authenticate with the provided authorization criteria. Therefore any group elements act as a subset of authorization. The running users must first authenticate successfully into the flow and subsequently authenticate into any group elements. Further to this, there's no requirement that the flow and group elements use the same service for authentication. Flow builders can build flows that authenticate across multiple systems, move from unauthenticated to authenticated access, etc.

Create/Update Flow

Used to create new flows or update existing ones. The flow object represents an entire flow application.

Request Body schema:
editingToken
string or null <uuid>

A unique token for this particular editing session

object (FlowIdAPI)

A composite unique identifier assigned by the platform, which should not be included for new flows.

developerName
string or null

The developer name for the flow. When referencing flows by name, this is the name you should use in your referencing.

developerSummary
string or null

The developer summary the author provided to give more information about the Flow.

startMapElementId
string or null

The unique identifier for the first element in the flow. This element is always of the START map element type.

allowJumping
boolean

Indicates that the builder of the flow will allow users to jump to any position in the Flow regardless of outcomes and/or navigation.

enableHistoricalNavigation
boolean

Indicates that the builder of the flow wants to enable/disable both the UI and api for historical navigation.

stateExpirationLength
integer <int32>
idleStateExpirationLength
integer <int32>
object (GroupAuthorizationAPI)
object (FlowIdentityProviderAPI)
tags
Array of strings or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string"
}

List Flows

Used to list and filter existing flows.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of flows where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of flows where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter for querying flows

Responses

Response samples

Content type
[
  • {
    }
]

Get Flow

Used to get an existing flow by ID.

path Parameters
id
required
string <uuid>

The unique identifier for the Flow

Responses

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string"
}

Delete Flow

Used to delete an existing flow

path Parameters
id
required
string

The unique identifier for the flow

Responses

List Elements in Flow

Used to list all the elements of a type used in a flow

path Parameters
flow
required
string <uuid>

The unique identifier for the flow

elementType
required
string

The element type to list

Responses

Response samples

Content type
[
  • {
    }
]

Import Element into Flow

Used to import an existing element into a flow

path Parameters
flow
required
string <uuid>

The unique identifier for the flow

elementType
required
string

The element type to import

id
required
string <uuid>

The ID of the element to import

Responses

Remove Element from Flow

Used to remove an imported element from a flow

path Parameters
flow
required
string <uuid>

The unique identifier for the flow

elementType
required
string

The element type to remove

id
required
string <uuid>

The ID of the element to remove

Responses

Flow Graph

The Flow Graph object provides the coordinate and basic configuration information of map and group elements.

The Flow Graph object is typically used for editing the layout of the flow for flow builders. This API should not be used for creating new flows, but rather to manage map and group elements in an existing flow. The focus of this API is to allow flow builders to make coordinate changes to these elements while ensuring other flow builders are notified of these changes and can be updated in realtime.

Update Flow Graph

Used to update a flow graph.

Request Body schema:
editingToken
string or null <uuid>

A unique token for this particular editing session

object (FlowIdAPI)

A composite unique identifier assigned by the platform, which should not be included for new flows.

developerName
string or null

The developer name for the flow. When referencing flows by name, this is the name you should use in your referencing.

developerSummary
string or null

The developer summary the author provided to give more information about the Flow.

startMapElementId
string or null

The unique identifier for the first element in the flow. This element is always of the START map element type.

allowJumping
boolean

Indicates that the builder of the flow will allow users to jump to any position in the Flow regardless of outcomes and/or navigation.

enableHistoricalNavigation
boolean

Indicates that the builder of the flow wants to enable/disable both the UI and api for historical navigation.

stateExpirationLength
integer <int32>
idleStateExpirationLength
integer <int32>
object (GroupAuthorizationAPI)
object (FlowIdentityProviderAPI)
tags
Array of strings or null
Array of objects or null (MapElementAPI)

An array of map elements that are part of the flow graph.

Array of objects or null (GroupElementAPI)

An array of group elements that are part of the flow graph.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "mapElements": [
    ],
  • "groupElements": [
    ],
  • "tenantId": "string",
  • "dateModified": "2019-08-24T14:15:22Z"
}

Get Flow Graph

Used to get an existing flow graph. The flow graph provides the coordinate and basic configuration information of map and group elements.

path Parameters
flow
required
string

The unique identifier for the flow

Responses

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "mapElements": [
    ],
  • "groupElements": [
    ],
  • "tenantId": "string",
  • "dateModified": "2019-08-24T14:15:22Z"
}

Get Flow Elements

Used to get map or group elements within the flow graph. The response will contain all information about the map and group elements, not just basic configuration information.

path Parameters
flow
required
string

The unique identifier for the flow

Request Body schema:

The list of map or group element ids to load

mapElementIds
Array of strings or null

An array of map elements ids that exist in the flow graph.

groupElementIds
Array of strings or null

An array of group elements ids that exist in the flow graph.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "mapElements": [
    ],
  • "groupElements": [
    ]
}

Save Flow Elements

Used to save map or group elements within the flow graph. It is expected that all the information about the map and group elements has been given, not just basic configuration information.

path Parameters
flow
required
string

The unique identifier for the flow

Request Body schema:

The list of map or group elements to save

Array of objects or null (MapElementRequestAPI)

An array of map elements that are part of the flow graph.

Array of objects or null (GroupElementRequestAPI)

An array of group elements that are part of the flow graph.

Responses

Request samples

Content type
No sample

/api/draw/2/graph/flow/{id}

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "mapElements": [
    ],
  • "groupElements": [
    ]
}

/api/draw/2/graph/flow

Request Body schema:
id
string <uuid>
Array of objects or null (FlowGraphMapElementResponseAPI)
Array of objects or null (FlowGraphGroupElementResponseAPI)

Responses

Request samples

Content type
No sample

Flow Snapshot

The flow snapshot is the package that is sent to the platform runtime engine.

Without a flow snapshot, a flow cannot be accessed by running users. The flow snapshot contains all the fully versioned elements that are needed for the flow to execute (excluding subflows). In the tooling, each time a flow is run or published, a flow snapshot is taken. This means you then have a version of the flow that can also be reverted if flow builders make a range of mistakes and would like to go back to a previous snapshot.

The flow snapshot also acts as a version system as all metadata for the flow can be accessed, and external tools can be used to diff for changes. Equally, for compliance, a customer can access the flow snapshots to get a complete picture of which flow the running user(s) were running at any particular point in time.

Activate a Flow Snapshot

Used to activate and/or make default a flow snapshot version

path Parameters
flow
required
string

The unique identifier for the flow

version
required
string

The unique identifier for the flow version

isDefault
required
boolean

If this snapshot should be the default version for running users

isActivated
required
boolean

If this snapshot should be accessible to running users to run

Responses

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string"
}

Revert a Flow Snapshot

Used to take an flow snapshot and apply it to the current flow being modelled. This is equivalent to undoing changes to a flow for all flow builders.

To revert a flow snapshot for running users, simply activate and make default the appropriate previous flow snapshot version.

path Parameters
flow
required
string

The unique identifier for the flow

version
required
string

The unique identifier for the flow version

Responses

Create Flow Snapshot

Used to create a flow snapshot.

path Parameters
flow
required
string <uuid>

The unique identifier for the flow

Request Body schema:
string

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string"
}

List Flow Snapshots

Used to get the list of all snapshots for a particular flow.

path Parameters
flow
required
string <uuid>
query Parameters
filter
string

Responses

Response samples

Content type
[
  • {
    }
]

Add flow

Adds a flow to a release

Request Body schema:
flowId
string or null <uuid>

The Flow unique identifier you want to build

releaseId
string or null <uuid>

The unique identifier of the release you want to add the built flow to

releaseName
string or null

The name for the new release

comment
string or null

The build comment/description for the flow

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string"
}

Get Flow Snapshot

Used to get a single flow snapshot.

path Parameters
flow
required
string

The unique identifier for the flow

version
required
string

The unique identifier for the flow version

Responses

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string",
  • "navigationElements": [
    ],
  • "mapElements": [
    ],
  • "groupElements": [
    ],
  • "pageElements": [
    ],
  • "valueElements": [
    ],
  • "macroElements": [
    ],
  • "serviceElements": [
    ],
  • "typeElements": [
    ],
  • "tagElements": [
    ]
}

Group Element

The group element object represents any group or element in your flow that can contain map elements.

Group elements are used to add additional behavior to map elements in your flow. The group element currently only supports the ability to change the authentication context of the map elements it contains. This allows builders to change the permissions for map elements contained in the group element and restrict the ability for running users to edit or take action on any outcomes.

Create/Update Group Element

Used to create new group elements or update existing ones.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

Unique identifier for the flow containing the group element

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
groupElementId
string or null

The unique identifier for the group element that holds this group element.

x
integer <int32>

The x location of the Group on the Flow diagram.

y
integer <int32>

The y location of the Group on the Flow diagram.

height
integer <int32>

The height of the Group on the Flow diagram.

width
integer <int32>

The width of the Group on the Flow diagram.

object (GroupAuthorizationAPI)
isOpen
boolean

Is the Group open in the buildtime editor. default: true

object (FlowIdentityProviderAPI)
updateByName
boolean

Indicates if the platform should attempt to find a group with the same developer name as the one provided and match them up by name as opposed to by ID.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "groupElementId": "string",
  • "x": 0,
  • "y": 0,
  • "height": 0,
  • "width": 0,
  • "authorization": {
    },
  • "isOpen": true,
  • "identityProvider": {
    },
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

List Group Elements

Used to list and filter existing group elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the group element

query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

Get Group Element

Used to get an existing group element.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the group element

id
required
string <uuid>

The unique identifier for the group element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "groupElementId": "string",
  • "x": 0,
  • "y": 0,
  • "height": 0,
  • "width": 0,
  • "authorization": {
    },
  • "isOpen": true,
  • "identityProvider": {
    },
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

Delete Group Element

Used to delete an existing group element.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the group element

id
required
string <uuid>

The unique identifier for the group element

Responses

Identity Provider

/api/draw/1/element/identityprovider

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
type
integer <int32> (IdentityProviderType)
Enum: 0 1 2
dateCreated
string <date-time>
dateModified
string <date-time>

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "type": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z"
}

/api/draw/1/element/identityprovider

query Parameters
filter
string
limit
integer <int32>
Default: 20
page
integer <int32>
Default: 1
orderBy
string
Default: "dateModified"
orderDirection
string
Default: "DESC"

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

/api/draw/1/element/identityprovider/{id}

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "type": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z"
}

/api/draw/1/element/identityprovider/{id}

path Parameters
id
required
string <uuid>

Responses

/api/identityprovider/1/{tenantId}/{id}/saml/metadata

path Parameters
tenantId
required
string <uuid>
id
required
string <uuid>

Responses

Macro Element

Create/Update Macro Elements

Used to create new macro elements or update existing ones.

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
code
string or null

The JavaScript code for the Macro.

updateByName
boolean

Indicates if the platform should attempt to find a Macro with the same developer name as the one provided and match them up by name as opposed to 'id'. This is useful when creating scripts to create Flows - as you can use the developerName property as the reference as opposed to needing to know the ids of all created Elements.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "code": "string",
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

List Macro Elements

Used to list and filter existing macro elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

Get Macro Element

Used to get an existing macro element.

path Parameters
id
required
string <uuid>

The unique identifier for the macro element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "code": "string",
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

Delete Macro Element

Used to delete an existing macro element.

path Parameters
id
required
string <uuid>

The unique identifier for the macro element

Responses

Map Element

The map element object represents any node or element in your flow diagram.

Map elements are used to set out the actions and journey of your flow. Each map element performs an action, which may be to present the user with information, collect information, or perform logical actions such as inserting records into a database, executing business rules, or sending messages to a 3rd party application.

There's a lot of functionality packed into map elements, and that has been separated out in the sections below.

Data Actions

A data action is used to perform create, read, update, or delete (CRUD) type operations on a service. There are a number of features that make data actions particularly powerful:

  • You do not need to manage ```INSERT``` vs. ```UPDATE``` operations. We automatically track the objects in your flow and know if it is a new object to be inserted or an update to an existing object. This is done using our ```SAVE``` operation. We do not separate ```INSERT``` and ```UPDATE```.
  • You can configure filters using our common metadata. This means you do not need to understand the query language of the underlying service - you can create queries using a standard notation and we automatically translate this notation into SQL (RDBMS), SOQL (Salesforce), ZOQL (Zuora), etc.
  • The data action automatically knows where the data needs to go. There is no need to map fields into the database as this is already configured in the type. In addition, a number of services also support “smart save” which does a smart merge of data collected/changed in the flow with data already stored in the service.
  • If you need advanced data management capabilities such as summary roll-ups or joined tables, you can configure this using "commands" (as supported by the underlying service implementation).

Listeners

A Listener is used to listen to events on objects stored or managed by a service. When an event occurs (e.g. a record is updated) in the underlying application (e.g. Salesforce), the platform will inform the executing flow of the event so it can take appropriate action.

Listeners work as follows:

  1. You send the service the objects you want to listen to (referencing the appropriate value). In addition, you specify the type of event you’re interested in (e.g. record created).
  2. The service will notify the platform when that event has happened on the associated object(s). This will populate the referenced value with the latest data from the service.
  3. You specify the outcomes (with comparisons/rules) under which you "accept" the event and the path the flow should follow. If those comparisons/rules are met, the flow will proceed to the next map element in the flow as defined by the matching outcome. If not, the flow will continue to wait until the appropriate event occurs.

Message Actions

A Message Action is used to perform general API operations on a Service. There are a number of features that make Message Actions particularly powerful:

  • Multiple inputs/multiple outputs: When executing a message action, the service can specify multiple inputs and multiple outputs post processing. E.g. you might have a service that moves a file from one folder to another (in Box). For this you’d specify the file that needs to be moved and the location you’d like to move it from and to (these would be the inputs). The outputs might be the file with revised information regarding its location and permissions.
  • They can "wait": When executing a message action, it can sometimes take some time to complete the request. Alternatively, the request may need to wait for a response. E.g. if you are sending a text message via Twilio and you want to have the flow wait for the response before proceeding. Other services may be used precisely to cause the flow to wait, e.g. our Timer service that allows you to stop or wait the flow for a timer interval or until a specific date. A "wait" can be created by building comparison/rules (e.g. the rules under which the flow will proceed down a particular path). The flow will only follow an outcome until the rules are satisfied.

It's important to note that message actions are described in the service definition. The purpose of the message actions is to map values in the flow to the inputs and outputs specified by the service.

A navigation override is used to alter the functionality of navigation in your flow. As running users go through a flow, it is often useful to alter how the navigation works. As a result, when the user gets to a particular map element, you can execute changes to the navigation. These changes will persist until altered by another map element. This can be useful in a variety of use-cases:

  • Certain parts of the navigation should only be functional once a certain portion of the flow has been completed. You can either disable or only make visible these parts of the navigation when ready. For example, you might want to disable navigation steps 3-5 until step 2 in your Flow has been completed.
  • You want the navigation to remember where the user was in a particular section of your flow. For example, the user might be going through a sequence of diagnostic steps under a "Diagnose" navigation item. If the user then clicks on an "FAQ" navigation item to answer a quick question, by default when they click back on "Diagnose" it will restart the diagnostic section. If each map element in the "Diagnose" section overrides the navigation to point to that particular map element, when the user clicks on the "Diagnose" navigation item, it will take them to that particular map element, not back to the start.

Operations

An operation is used to make a change to a value or execute a macro in your flow. Each operation can be ordered allowing builders to do operations in a particular sequence - as individual commands performed on values. Here are some examples of operations:

  • You want to assign the content of a value so the user doesn’t need to do it manually.
  • You want to get the next object from a list of objects in your flow.
  • You want to execute a macro that performs complex logic and business rules on values in your flow.

In mathematics, an operation would be something like: x = 3

Outcomes

An outcome is used to make move the running user(s) from one map element in the flow to another or from one map element into another flow. An outcome can represent a button the running user(s) can click, or it can represent a path the executing flow should follow based on logical operations in the flow. Outcomes can be combined with business rules (provided by comparison/rules) to determine the path of execution based on pre-determined logic.

Vote

The vote object is used to configure voting or multi-user approval options on an outcome. By configuring the vote, you can determine if a set number of running users or a percentage of running users (within the authentication context of the map element) must click on a particular outcome before the flow will proceed down that path. For example, before the approval is accepted, more than two running users must click on the “Approve” outcome before the flow will progress.

The implementation of the vote algorithm is determined by the service. Builders should refer to the documentation of the service being used. The first running user to click on an outcome contained in a voting map element will force the platform to “lock” the page from any further user inputs. Effectively the map element becomes read-only until the vote is completed.

Create/Update Map Elements

Used to create new map elements or update existing ones.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the map element

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
groupElementId
string or null

The unique identifier for the Group that contains this Map Element. If a Map Element is inside a Group, it inherits certain behaviors of the parent Group. For example, a Swimlane Group wraps all child Map Elements in a security context.

x
integer <int32>

The x location of the Map Element on the Flow diagram.

y
integer <int32>

The y location of the Map Element on the Flow diagram.

pageElementId
string or null
pageElementDeveloperName
string or null
Array of objects or null (OutcomeAPI)

The list of outcomes that are available for this Map Element. An Outcome is used to connect the flow of execution from one Map Element in the Flow to another. An Outcome can take the form of a Page button, but also define system steps such as rules.

object (SubflowAPI)
object (WaitAPI)
Array of objects or null (WaitAPI)

Waits configured on a page (input) map element, these will be triggered when the page map element is reached and on completion may trigger an outcome.

Array of objects or null (OperationAPI)

The list of operations that should be performed when this Map Element executes. Operations are used to change the value of Values in the executing Flow (State).

Array of objects or null (ListenerAPI)

The list of listeners that should be registered when this Map Element executes.

object (MessageActionAPI)
Array of objects or null (MessageActionAPI)

The list of message actions that should be executed when this Map Element executes. The message action objects define the interface of inputs/outputs for calling against each Service message.

Array of objects or null (DataActionAPI)

The list of data actions that should be executed when this map element executes. The data action objects define the values and bindings that should be used to perform CRUD operations against each service and value.

Array of objects or null (NavigationOverrideAPI)

The list of navigation overrides that should be applied when this Map Element executes.

object (VoteAPI)
clearNavigationOverrides
boolean
postUpdateToStream
boolean

Indicates if this Map Element should post an update to the collaboration stream.

userContent
string or null

The content that should be shown to the user at this step in the Flow. This property should only be used for very simple Flows and informational UI. For anything more than simple messaging, use the Page and associate it with this Map Element using the pageElementId property.

userContentDateModified
string or null <date-time>

The date the Map Elements usercontent was modified.

statusMessage
string or null

The content that should be shown to the user while waiting for a system step to complete.

postUpdateMessage
string or null

The content of the message that should be posted to the collaboration stream.

notAuthorizedMessage
string or null

The content that should be shown to the user if they are not authorized to take action on this Map Element.

postUpdateWhenType
string or null

The point at which the post should be made to the collaboration stream.

updateByName
boolean

Indicates if the platform should attempt to find a Type with the same developer name as the one provided and match them up by name as opposed to 'id'. This is useful when creating scripts to create Flows - as you can use the developerName property as the reference as opposed to needing to know the ids of all created Elements.

title
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "groupElementId": "string",
  • "x": 0,
  • "y": 0,
  • "pageElementId": "string",
  • "pageElementDeveloperName": "string",
  • "outcomes": [
    ],
  • "subflow": {
    },
  • "wait": {
    },
  • "waits": [
    ],
  • "operations": [
    ],
  • "listeners": [
    ],
  • "viewMessageAction": {
    },
  • "messageActions": [
    ],
  • "dataActions": [
    ],
  • "navigationOverrides": [
    ],
  • "vote": {
    },
  • "clearNavigationOverrides": true,
  • "postUpdateToStream": true,
  • "userContent": "string",
  • "userContentDateModified": "2019-08-24T14:15:22Z",
  • "statusMessage": "string",
  • "postUpdateMessage": "string",
  • "notAuthorizedMessage": "string",
  • "postUpdateWhenType": "string",
  • "updateByName": true,
  • "title": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

List Map Elements

Used to filter existing map elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the map elements

query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

Get Map Element

Used to get an existing map element.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the map element

id
required
string <uuid>

The unique identifier for the map element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "groupElementId": "string",
  • "x": 0,
  • "y": 0,
  • "pageElementId": "string",
  • "pageElementDeveloperName": "string",
  • "outcomes": [
    ],
  • "subflow": {
    },
  • "wait": {
    },
  • "waits": [
    ],
  • "operations": [
    ],
  • "listeners": [
    ],
  • "viewMessageAction": {
    },
  • "messageActions": [
    ],
  • "dataActions": [
    ],
  • "navigationOverrides": [
    ],
  • "vote": {
    },
  • "clearNavigationOverrides": true,
  • "postUpdateToStream": true,
  • "userContent": "string",
  • "userContentDateModified": "2019-08-24T14:15:22Z",
  • "statusMessage": "string",
  • "postUpdateMessage": "string",
  • "notAuthorizedMessage": "string",
  • "postUpdateWhenType": "string",
  • "updateByName": true,
  • "title": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

Delete Map Element

Used to delete an existing map element.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the map element

id
required
string <uuid>

The unique identifier for the map element

Responses

Navigation Element

The navigation element object provides a menu or navigation structure allowing users to move around your flow application in an unstructured way.

Navigation elements are used to set out the structure and map element locations which users can jump to directly. As a result, your map elements act more like web pages on a website than steps in a process. The base properties of the navigation element are outlined here.

Create/Update Navigation Elements

Used to create new navigation elements or update existing ones.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the navigation element

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
label
string or null

The label to display to the user.

Array of objects or null (NavigationItemAPI)

The navigation items that are available for this navigation. The navigation items are the "links" the user can use to navigate around your flow.

Array of objects or null (PageTagAPI)

The list of tags that are associated with this navigation.

updateByName
boolean

Indicates if the platform should attempt to find a navigation with the same developer name as the one provided and match them up by name as opposed to by ID. This is useful when creating scripts to create flows, as you can use the developerName property as the reference as opposed to needing to know the IDs of all created elements.

persistState
boolean

Indicates if the platform should save state when navigating between elements

persistValues
boolean

Indicates if the platform should save values when navigating between elements

position
integer <int32> (NavigationPosition)
Enum: 0 1

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "label": "string",
  • "navigationItems": [
    ],
  • "tags": [
    ],
  • "updateByName": true,
  • "persistState": true,
  • "persistValues": true,
  • "position": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

List Navigation Elements

Used to filter existing navigation elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the navigation elements

query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

Get Navigation Element

Used to get an existing navigation element.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the navigation element

id
required
string <uuid>

The unique identifier for the navigation element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "label": "string",
  • "navigationItems": [
    ],
  • "tags": [
    ],
  • "updateByName": true,
  • "persistState": true,
  • "persistValues": true,
  • "position": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

Delete Navigation Element

Used to delete an existing navigation element.

path Parameters
editingToken
required
string <uuid>

The active editing token for the flow being edited

flow
required
string <uuid>

The unique identifier for the flow containing the navigation element

id
required
string <uuid>

The unique identifier for the navigation element

Responses

Page Element

The page element object provides the structure of your pages or screens.

The purpose of the page element is to allow flow builders to lay out the structure of the pages the users will interact with as part of the flow application. The page element is extremely extensible and allows developers to create their own components and containers as needed to give users the best possible experience using your flow application. The base properties of the page element are outlined here.

Page Containers

A page container is used to determine the scaffolding of your page. Page containers allow flow builders to set out the relative position of page components on the page. In comparison with HTML5, a page container would be equivalent to a div tag. As a result, page containers do not have any value or input, they are simply used to determine the layout or scaffolding aspects of the page.

The type of page container is determined by the containerType property and developers looking to build custom containers should use a unique containerType name to identify their container implementation. The properties outlined here are the common attributes for typical containers, however, if these do not suffice, developers should use the attributes to extend the attributes for their own specific needs. It’s important to note that each of the properties here provides features and the engine does not have any understanding of one container type from another.

Page Components

A page component is used to show or edit information on your page. In comparison with HTML5, a page component would be equivalent to an input, textarea, or similar tag. As a result, page components typically do have a value or input, and are used to prompt the user for some form or input or to view a particular piece of information on the page.

The type of page component is determined by the componentType property and developers looking to build custom components should use a unique componentType name to identify their component implementation. The properties outlined here are the common attributes for typical components, however, if these do not suffice, developers should use the attributes to extend the attributes for their own specific needs. It’s important to note that each of the properties here provides features and the engine does not have any understanding of one component type from another.

Page Conditions

Page conditions are used to make your pages dynamic. Based on a set of page rules, the page conditions can assign values to your page components but also change various properties on your page components and containers such as: required, editable, visible. Page components can also have data refreshed and objectDataRequest information dynamically assigned so you can, for example, change table filters. This gives flow builders the ability to provide single pages that can provide the running user(s) with a very dynamic experience.

Page Operation Assignment

The assignment object should be used when a value or piece of metadata for a component or container needs to be changed. For example, a page component should be set as required under a specific set of conditions. Or a page container should no longer be visible under another set of conditions.

Page Operation Filter

The filter object should be used when applying filters based on conditions. For example, the list of options in a combobox should be limited based on a checkbox being checked. The filter object can be applied to lists as well as objectDataRequests.

Page Object Reference

The page object reference is a general purpose object for referencing data and metadata on the page. It can be configured to reference data that is not formally stored into the flow state and also value elements that are.

Create/Update Page Elements

Used to create new page elements or update existing ones.

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
label
string or null

The label for the page element. This is usually used as the title of the page.

Array of objects or null (PageContainerAPI)

The tree hierarchy of page containers that define the scaffolding of the page layout. Conceptually, page containers are similar to HTML5 div tags. If no page containers are provided, it is assumed that all components will be oriented in a vertical flow layout.

Array of objects or null (PageComponentAPI)

The list of components to be embedded on the page. Each component is associated with a page container for relative positioning information. Conceptually, page containers are similar to HTML5 form controls and/or specific layout blocks containing images or content.

Array of objects or null (PageConditionAPI)

The list of page conditions that set out the rules that should be evaluated and the actions that should be taken if those rules evaluate to true. Page conditions make it possible to define complex UI event models.

stopConditionsOnFirstTrue
boolean

Indicates if the engine should continue to execute rules and actions on the page if a condition evaluates to true. This makes it possible to deal with page rules that may conflict if all run for all events on the page.

saveHiddenInputs
boolean

Indicates if page components that are not visible should still save their input to state

object or null

Key value pairs that provide additional information for the page layout to be rendered. Builders should refer to the documentation of the UI code being used.

Array of objects or null (PageTagAPI)

The list of page tags that allow additional metadata to be applied to various page objects: components, controls and the overall page. Conceptually tags can be used to mimic HTML and CSS but can also be used to provide data to enrich functionality on the page.

updateByName
boolean

Indicates if the platform should attempt to find a page element with the same developer name as the one provided and match them up by name as opposed to by ID. This is useful when creating scripts to create flows, as you can use the developerName property as the reference as opposed to needing to know the IDs of all created elements.

modernPageLayout
boolean

Indicates if the page is using the modern layout based on the CSS grid.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "label": "string",
  • "pageContainers": [
    ],
  • "pageComponents": [
    ],
  • "pageConditions": [
    ],
  • "stopConditionsOnFirstTrue": true,
  • "saveHiddenInputs": true,
  • "attributes": {
    },
  • "tags": [
    ],
  • "updateByName": true,
  • "modernPageLayout": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

List Page Elements

Used to list and filter existing page elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

Get Page Element

Used to get an existing page element.

path Parameters
id
required
string <uuid>

The unique identifier for the page element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "label": "string",
  • "pageContainers": [
    ],
  • "pageComponents": [
    ],
  • "pageConditions": [
    ],
  • "stopConditionsOnFirstTrue": true,
  • "saveHiddenInputs": true,
  • "attributes": {
    },
  • "tags": [
    ],
  • "updateByName": true,
  • "modernPageLayout": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

Delete Page Element

Used to delete an existing page element.

path Parameters
id
required
string <uuid>

The unique identifier for the page element

Responses

Service Element

Describe Service Element

Used to obtain a describe response for a service element.

Request Body schema:

The details required to describe the service element

object (CultureAPI)
uri
string or null

The Uri for the service to describe.

httpAuthenticationUsername
string or null
httpAuthenticationPassword
string or null
httpAuthenticationClientCertificate
string or null
httpAuthenticationClientCertificatePassword
string or null
version
string or null
Array of objects or null (EngineValueAPI)

Configuration values provided by the end user to help the describe.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "configurationValues": [
    ],
  • "providesLogic": true,
  • "providesViews": true,
  • "providesDatabase": true,
  • "providesIdentity": true,
  • "providesSocial": true,
  • "providesFiles": true,
  • "providesAutoBinding": true
}

Install Service Element

Used to obtain an install response for a service element.

Request Body schema:

The details required to install the service element

object (CultureAPI)
uri
string or null

The Uri for the service to describe.

httpAuthenticationUsername
string or null
httpAuthenticationPassword
string or null
httpAuthenticationClientCertificate
string or null
httpAuthenticationClientCertificatePassword
string or null
version
string or null
Array of objects or null (EngineValueAPI)

Configuration values provided by the end user to help the describe.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "actions": [
    ],
  • "types": [
    ],
  • "version": "string"
}

Create/Update Service Elements

Used to create new service elements or update existing ones.

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
uri
string or null

The location of the Service implementation for the platform to callout against.

format
string or null

The REST messaging format to use to communicate with this service. Currently the only valid value for this property is: JSON

Array of objects or null (ServiceValueRequestAPI)

The list of configuration value mappings the service needs to function. Each entry provides a reference to a Value in the Flow that contains the configuration value needed by the service plugin.

providesLogic
boolean

Indicates if the Service provides functionality for 'logic'. Logic allows authors to make API calls as part of elements that support messaging: 'Message', 'Page', and 'Remote Page' currently. Messaging is used for asynchronous and synchronous use-cases.

providesViews
boolean

Indicates if the Service provides functionality for 'views'. A View allows authors to build Flows that include 'Remote Page' elements - e.g. the UI of the page is not actually hosted on the ManyWho platform, but rather the UI is provided by the external service.

providesFiles
boolean

Indicates if the Service provides functionality for 'files'. Files allows the author to reference files and content from the service as dynamic references - meaning that the files and content can be managed outside of ManyWho, but embedded in your Flows.

providesDatabase
boolean

Indicates if the Service provides functionality for 'database'. Database functionality allows the author to map their Typed Objects and Lists back to this service for storage. The service then acts as the persistence implementation to store and retrieve the data as neede by the Flow.

providesIdentity
boolean

Indicates if the Service provides functionality for 'identity'. Identity functionality allows the author to manage permissions to their Flows and sections of their Flows (via Swimlanes) using this service as the directory. This also allows users to login to the Flows using the information stored in this service directory.

providesSocial
boolean

Indicates if the Service provides functionality for 'social'. Social allows the author to add features for feed, file and user collaboration to their Flows using this service as the underlying social network.

providesLocation
boolean

Indicates if the Service provides functionality for 'location'. ManyWho optionally collects location information about the user when running a Flow. This information can be used to make decisions about permissions and also data filtering - though it is up to the service to implement this functionality.

providesAutoBinding
boolean
Array of objects or null (ServiceActionRequestAPI)

The list of 'logic' operations that are available for the service. If the underlying service 'providesLogic', this is where the 'interface' for those logic operations should be stored. This allows the author to know what inputs and outputs are provided by the actions provided by this Service.

object (ServiceInstallRequestAPI)
updateByName
boolean

Indicates if the platform should attempt to find a Service with the same developer name as the one provided and match them up by name as opposed to 'id'. This is useful when creating scripts to create Flows - as you can use the developerName property as the reference as opposed to needing to know the ids of all created elements.

sendDecryptedValues
boolean
httpAuthenticationUsername
string or null
httpAuthenticationPassword
string or null
httpAuthenticationClientCertificateReference
string or null
httpAuthenticationClientCertificatePasswordReference
string or null
version
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "uri": "string",
  • "format": "string",
  • "configurationValues": [
    ],
  • "providesLogic": true,
  • "providesViews": true,
  • "providesFiles": true,
  • "providesDatabase": true,
  • "providesIdentity": true,
  • "providesSocial": true,
  • "providesLocation": true,
  • "providesAutoBinding": true,
  • "actions": [
    ],
  • "install": {
    },
  • "updateByName": true,
  • "sendDecryptedValues": true,
  • "httpAuthenticationUsername": "string",
  • "httpAuthenticationPassword": "string",
  • "httpAuthenticationClientCertificateReference": "string",
  • "httpAuthenticationClientCertificatePasswordReference": "string",
  • "version": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

List Service Elements

Used to list and filter existing service elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

Get Service Element

Used to get an existing service element.

path Parameters
id
required
string <uuid>

The unique identifier for the service element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "uri": "string",
  • "format": "string",
  • "configurationValues": [
    ],
  • "providesLogic": true,
  • "providesViews": true,
  • "providesFiles": true,
  • "providesDatabase": true,
  • "providesIdentity": true,
  • "providesSocial": true,
  • "providesLocation": true,
  • "providesAutoBinding": true,
  • "actions": [
    ],
  • "install": {
    },
  • "updateByName": true,
  • "sendDecryptedValues": true,
  • "httpAuthenticationUsername": "string",
  • "httpAuthenticationPassword": "string",
  • "httpAuthenticationClientCertificateReference": "string",
  • "httpAuthenticationClientCertificatePasswordReference": "string",
  • "version": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

Delete Service Element

Used to delete an existing service element.

path Parameters
id
required
string <uuid>

The unique identifier for the service element

Responses

List Service Elements v2

Used to list and filter existing Service elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

page
integer <int32>
Default: 1

Optional. The current page of Services

limit
integer <int32>
Default: 20

Optional. Restrict the number of returned results. Zero is no limit. 20 is the default

orderBy
string
Default: "dateModified"

Optional. Specify which field to order results by. Default is dateModified

orderDirection
string
Default: "DESC"

Optional. Specify which direction results should be ordered by. Can either be ASC or DESC. Default is DESC.

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Tag Element

The tag element object provides additional runtime data to your page element containers/components and navigation elements/items.

The purpose of the tag element is to add flexibility to your flow application user experience. The components, containers and navigation items in your flow can benefit from having access to the flow state to get more contextual information. For example, if you have a numeric input field, it may be useful to know the possible range or numeric values that can be provided by the end user - where that range depends on logic in the flow. The components, containers and navigation items also supports attributes and these are often sufficient for many use-cases. As a result, only use the tag element if you need information that is very specific to the flow state for particular running user(s).

Create/Update Tag Elements

Used to create new tag elements or update existing ones.

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
contentType
string or null

The type of Value the Tag holds. As part of the Page layout creation, the Tag will be associated with a Value. The Value bound to this Tag must be of the same content type.

typeElementId
string or null

The unique identifier for the Type and object or list data must adhere to in structure (the Type basically defines the 'interface' that all objects and lists stored in this Value must implement). This property is only applicable for ContentObject and ContentList content types. As part of the Page layout creation, the Tag will be associated with a Value. The Value bound to this Tag must be of the same Type.

updateByName
boolean

Indicates if the platform should attempt to find a Tag with the same developer name as the one provided and match them up by name as opposed to 'id'. This is useful when creating scripts to create Flows - as you can use the developerName property as the reference as opposed to needing to know the ids of all created Elements.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentType": "string",
  • "typeElementId": "string",
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

List Tag Elements

Used to list and filter existing tag elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

Get Tag Element

Used to get an existing tag element.

path Parameters
id
required
string <uuid>

The unique identifier for the tag element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentType": "string",
  • "typeElementId": "string",
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

Delete Tag Element

Used to delete an existing tag element.

path Parameters
id
required
string <uuid>

The unique identifier for the tag element

Responses

Type Element

The type element object defines the structure of objects and lists in the flow.

The purpose of the type element is to allow flow builders to determine the business objects that will be used in the flow. Often the type elements are provided when the flow builder installs a new service element, however, flow builders can define their own type elements as needed to support the objectives of the flow. The type element also provides the bindings back to the service elements that can save, read or delete data of the same structure. As a result, the type element maps from friendly business objects to underlying storage implementations as provided by the service element. The base properties of the type element are outlined here.

Bindings

A binding is used to map properties in the type to database fields in the service. The mapping does not need to be directly to database tables in the service, however, the binding should provide unique identifier information necessary for the service element to put the provided values back to the correct storage locations. The binding is typically pre-configured as part of the type installation process. However, it is possible for flow builders to define bindings manually.

Create/Update Type Elements

Used to create new type elements or update existing ones.

query Parameters
overrideService
boolean
Default: false

Whether to allow updates to a type that is associated with a service

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
serviceElementId
string or null
serviceElementDeveloperName
string or null
Array of objects or null (TypeElementPropertyAPI)

The list of properties for this Type. A property is very similar to a field in a table - it represents the structure of the data that will be stored in Values that use this Type.

Array of objects or null (TypeElementBindingAPI)

The list of bindings for the Type. A binding holds the mapping of properties to tables and fields in an underlying Service. A binding is not required for a Type if there is no plan to save the data in an external data store. When creating a binding, you will need to have saved the initial Type first so you have the identifiers for the various properties in the Type that need to be bound.

updateByName
boolean

Indicates if the platform should attempt to find a Type with the same developer name as the one provided and match them up by name as opposed to 'id'. This is useful when creating scripts to create Flows - as you can use the developerName property as the reference as opposed to needing to know the ids of all created Elements.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "serviceElementId": "string",
  • "serviceElementDeveloperName": "string",
  • "properties": [
    ],
  • "bindings": [
    ],
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

List Type Elements

Used to list and filter existing type elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

limit
integer <int32>
Default: 0

Optional. Restrict the number of returned results. Zero is no limit

offset
integer <int32>
Default: 0

Optional. Specify which row to start. Zero is the first row

Responses

Response samples

Content type
[
  • {
    }
]

Get Type Element

Used to get an existing type element.

path Parameters
id
required
string <uuid>

The unique identifier for the type element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "serviceElementId": "string",
  • "serviceElementDeveloperName": "string",
  • "properties": [
    ],
  • "bindings": [
    ],
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    }
}

Delete Type Element

Used to delete an existing type element.

path Parameters
id
required
string <uuid>

The unique identifier for the type element

Responses

List Type Elements

Used to list and filter existing type elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
id
Array of strings <uuid>
filter
string

The filter used for querying

limit
integer <int32>
Default: 20

Optional. Restrict the number of returned results. Zero is no limit

page
integer <int32>
Default: 1

Optional. The current page of types

orderBy
string
Default: "dateModified"

Optional. Specify which field to order results by. Default is dateModified

orderDirection
string
Default: "DESC"

Optional. Specify which direction results should be ordered by. Can either be ASC or DESC. Default is DESC.

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Value Element

The value element object stores data collected in the flow state.

The purpose of the value element is to allow flow builders to determine how data collected from running user(s) or external services will be stored and used. The value element represents the memory for the flow application so data gathered can be later saved, updated, or viewed. The base properties of the value element are outlined here.

Create/Update Value Elements

Used to create new value elements or update existing ones.

Request Body schema:
id
string or null

The unique identifier for the element. The id should be null for "insert" requests and a valid identifier for "update" requests.

elementType
string or null

The type of element this metadata represents.

developerName
string or null

The developer name for the element. This is useful for keeping track of the element in the modelling tool and the API.

developerSummary
string or null

The developer summary the author provided to give more information about the element

object (BuilderWhoAPI)
object (BuilderWhoAPI)
object (BuilderWhoAPI)
isFixed
boolean

Indicates if the value of the Value can be changed by operations in the Flow or from outside systems. If this property is set to 'true', the Value will act like a 'constant' - i.e. it can't be changed by anyone except the Flow author at design time.

isEncrypted
boolean
isVersionless
boolean
access
string or null

Sets the level of access this Value has to change. In many situations, Values can only be changed by the operations defined in your Flow and the value is not exposed outside of the Flow. Alternatively, you may wish to allow the value of the Value to be assigned at initialization.

contentType
string or null

The type of content the Value holds.

contentFormat
string or null
defaultContentValue
string or null

The default content value for the Value before any operations have been performed. This is for primitive Values.

Array of objects or null (ObjectAPI)

The default object data for the Value before any operations have been performed. This is for Object and List Values.

Array of objects or null (OperationAPI)

The operations that should be performed when the object is initialized. Initialization operations are only appropriate for Values of content type ContentObject.

typeElementId
string or null

The unique identifier for the Type and object or list data must adhere to in structure (the Type basically defines the 'interface' that all objects and lists stored in this Value must implement). This property is only applicable for ContentObject and ContentList content types.

typeElementDeveloperName
string or null
updateByName
boolean

Indicates if the platform should attempt to find a Value with the same developer name as the one provided and match them up by name as opposed to 'id'. This is useful when creating scripts to create Flows - as you can use the developerName property as the reference as opposed to needing to know the ids of all created Elements.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "isFixed": true,
  • "isEncrypted": true,
  • "isVersionless": true,
  • "access": "string",
  • "contentType": "string",
  • "contentFormat": "string",
  • "defaultContentValue": "string",
  • "defaultObjectData": [
    ],
  • "initializationOperations": [
    ],
  • "typeElementId": "string",
  • "typeElementDeveloperName": "string",
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z"
}

List Value Elements

Used to list and filter existing value elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

contentType
Array of strings

Optional. One or more content types to filter by

Responses

Response samples

Content type
[
  • {
    }
]

Get Value Element

Used to get an existing value element.

path Parameters
id
required
string <uuid>

The unique identifier for the value element

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "isFixed": true,
  • "isEncrypted": true,
  • "isVersionless": true,
  • "access": "string",
  • "contentType": "string",
  • "contentFormat": "string",
  • "defaultContentValue": "string",
  • "defaultObjectData": [
    ],
  • "initializationOperations": [
    ],
  • "typeElementId": "string",
  • "typeElementDeveloperName": "string",
  • "updateByName": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z"
}

Delete Value Element

Used to delete an existing value element.

path Parameters
id
required
string <uuid>

The unique identifier for the value element

Responses

List Value Elements

Used to list and filter existing value elements.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

contentType
Array of strings

Optional. One or more content types to filter by

limit
integer <int32>
Default: 20

Optional. Restrict the number of returned results. Zero is no limit

page
integer <int32>
Default: 1

Optional. The current page of types

orderBy
string
Default: "dateModified"

Optional. Specify which field to order results by. Default is dateModified

orderDirection
string
Default: "DESC"

Optional. Specify which direction results should be ordered by. Can either be ASC or DESC. Default is DESC.

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

List Value Element References

Used to list and filter value element references, which are in a condensed format to help flow builders create merge fields in content.

Supported Element Types

VARIABLE: A reusable value containing data of the specified content type LITERAL: A simple, often single use value type containing a text or numeric value

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of elements where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of elements where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
contentType
Array of strings

Optional. One or more content types to filter by

elementType
Array of strings

Optional. One or more element types to filter by

id
Array of strings <uuid>

Optional. The ID of a value to filter by

typeElementId
Array of strings <uuid>

Optional. The ID of a type to filter by

access
Array of strings

Optional. The access type to filter by

filter
string

The filter used for querying

isFixed
boolean
Default: false

Optional. Whether to filter by fixed values

includeSystemValues
boolean
Default: true

Optional. Whether to include system values

search
string

Optional. A search term to filter the results by

flow
string <uuid>

Optional. The ID of a flow to filter by

limit
integer <int32>
Default: 0

Optional. Restrict the number of returned results. Zero is no limit

offset
integer <int32>
Default: 0

Optional. Specify which row to start. Zero is the first row

Responses

Response samples

Content type
[
  • {
    }
]

Environment

A controller to be consumed by the tooling to access environments

Saves an environment

Edits an existing environment

Request Body schema:
id
string <uuid>
name
string or null
isDefault
boolean
classificationType
string or null
nextEnvironmentId
string or null <uuid>
tenantId
string <uuid>
description
string or null
defaultPlayerName
string or null
lastDeployed
string or null <date-time>

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "isDefault": true,
  • "classificationType": "string",
  • "nextEnvironmentId": "bebe8659-804e-45b3-a90d-695ca6033bf7",
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  • "description": "string",
  • "defaultPlayerName": "string",
  • "lastDeployed": "2019-08-24T14:15:22Z"
}

Get environments

Gets all environments for the tenant the user is logged into

Responses

Response samples

Content type
[
  • {
    }
]

Get environment

Gets an environment by Id

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "isDefault": true,
  • "classificationType": "string",
  • "nextEnvironmentId": "bebe8659-804e-45b3-a90d-695ca6033bf7",
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  • "description": "string",
  • "defaultPlayerName": "string",
  • "lastDeployed": "2019-08-24T14:15:22Z"
}

Get environment

Gets an environment by type

path Parameters
type
required
integer <int32> (EnvironmentClassificationType)
Enum: 0 1 2

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "isDefault": true,
  • "classificationType": "string",
  • "nextEnvironmentId": "bebe8659-804e-45b3-a90d-695ca6033bf7",
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  • "description": "string",
  • "defaultPlayerName": "string",
  • "lastDeployed": "2019-08-24T14:15:22Z"
}

Save environment variable

Save an edited environment or create a new one if the id is not included

path Parameters
environmentId
required
string <uuid>
Request Body schema:
id
string or null <uuid>
name
string or null
value
string or null
environmentId
string <uuid>
tenantId
string <uuid>

Responses

Request samples

Content type
No sample

Get environment variables

Gets the environment variables for a specified environment

path Parameters
environmentId
required
string <uuid>
Request Body schema:
searchTerm
string or null
pageSize
integer <int32>
_page
integer <int32>
page
integer <int32>
_orderBy
string or null
orderBy
string or null
_orderDirection
string or null
orderDirection
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Delete environment variable

Deletes the environment variable by id

path Parameters
environmentId
required
string <uuid>
environmentVariableId
required
string <uuid>

Responses

Features

A controller to be consumed by the tooling to access developer/pm/po driven feature flags.

Lists Feature Flags

Retrieves a list of all the feature flags that are applied globally across all tenants.

Responses

Response samples

Content type
[
  • {
    }
]

/api/features/1/tenant

Responses

Response samples

Content type
[
  • {
    }
]

Updates Feature Flag Tenant

Update feature flags for a specific tenant. The selected feature flag is only enabled for the specified tenant.

Request Body schema:
featureFlagId
string <uuid>
enabled
boolean

Responses

Request samples

Content type
No sample

Notifications

The notifications API allows you to view any notifications sent to your or inside your tenant.

List Notifications

Get all the notifications that have been sent from inside a tenant

query Parameters
type
string

Filter by type, currently supports: delete_all, delete_tenant, fault, password_reset, tenant_creation, warning

Responses

Response samples

Content type
[
  • {
    }
]

List Notifications for User

Get all the unread notifications that have been sent to the currently logged in user, across all tenants

query Parameters
type
string

Filter by type, currently supports: delete_all, delete_tenant, fault, password_reset, tenant_creation, warning

includeRead
boolean
Default: false

Also include read eamil.

Responses

Response samples

Content type
[
  • {
    }
]

Finds a notification for the current user

Finds the notification and marks it as read

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "isRead": true,
  • "tenant": {
    },
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "content": "string",
  • "subject": "string",
  • "type": "string",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Mark all notifications as read for the current user

Marks all the notifications for the current user as read

Responses

Package

The packaging API allows you to move a Flow from one tenant to another. This can be handy for a few example reasons:

  • You have Sub-Tenants that you use for testing or team based development of Flows. You then have a master tenant for all “production” Flows.
  • You have a library of useful Flows that you want to distribute as templates.
  • You want to create a “store” of Flows that can be used by your customers to help them leverage and adapt your existing intellectual property.
A few things to consider with packaging:
  1. The source Tenant should be used for editing. If you make changes in the target Tenant and attempt to apply those back to the source, you can accidentially overwrite changes in the source, not applied in the target.
  2. Packaging overwrites the existing Flow with the same Flow identifier. As a result, you can apply upgrades to a target Tenant.
  3. If you plan to use a Service in multiple Tenants, make sure you create the Service in the source Tenant and distribute a Flow package for all target Tenants. If a Service is installed in each Target Tenant, it will be duplicated as we do not “merge” Services even if they point to the same Service end-point.
  4. Do not refresh the Service in the Target Tenant if you are simply changing the endpoint URL. Packaging only pulls in the Types that are used by the Flow. If you refresh the whole Service in the Target Tenant, you can end up with duplicate Types.
  5. When you export a Flow Package, you will receive a String that contains all the information needed to execute your Flow.
  6. We do not automatically Package sub-Flows.
  7. You can only export a package of the Flow if that Flow has a SnapShot (generated by either Running or Publishing the Flow).
The package file should never be altered. Please refer to the SnapShot APIs if you need to get information about your Flows.

Create Package for Flow

Create a package of the latest version of a flow snapshot

path Parameters
id
required
string

The ID of the flow

query Parameters
nullPasswords
boolean
Default: false

Whether the package should include password values.

Responses

Response samples

Content type
"string"

/api/package/1/runtime/flow/{id}/{version}

path Parameters
id
required
string
version
required
string

Responses

Response samples

Content type
"string"

/api/package/1/tenant

query Parameters
nullPasswords
boolean
Default: false

Responses

Response samples

Content type
"string"

/api/package/1/tenant

Request Body schema:
string

Responses

Request samples

Content type
No sample

Create Package for Flow Version

Get the package of a specific version of a Flow Snapshot

path Parameters
id
required
string

The ID of the flow

version
required
string

The version of the flow

query Parameters
nullPasswords
boolean
Default: true

Whether the package should include password values.

Responses

Response samples

Content type
"string"

Import Package

This allows you to import a flow package into a Tenant. It’s important to note that this is not the same as cloning a flow. If you import a flow package into a tenant that contains a flow with the same flow ID, the flow in the target tenant will be overwritten with the flow package being imported.

query Parameters
isSnapshot
boolean
Default: false

Optional. Whether the package should be imported directly as a snapshot, and not modelling data

isActive
boolean
Default: false

Optional. Whether the package should be imported as an active snapshot (isSnapshot must be true to take effect)

isDefault
boolean
Default: false

Optional. Whether the package should be immediately made the default version (isSnapshot must be true to take effect)

Array of objects (UriMapping)
overwriteExisting
boolean
Default: true

Whether to overwrite any elements that already exist in the tenant with the versions included in the package. Enabled by default.

Request Body schema:

The package content

string

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string"
}

Import Package with Flow Sharing Token

Import a flow via a unique sharing token

query Parameters
isSnapshot
boolean
Default: false

Optional. Whether the package should be imported directly as a snapshot, and not modelling data

isActive
boolean
Default: false

Optional. Whether the package should be imported as an active snapshot (isSnapshot must be true to take effect)

isDefault
boolean
Default: false

Optional. Whether the package should be immediately made the default version (isSnapshot must be true to take effect)

overwriteExisting
boolean
Default: true

Whether to overwrite any elements that already exist in the tenant with the versions included in the package. Enabled by default.

Request Body schema:
token
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "allowJumping": true,
  • "enableHistoricalNavigation": true,
  • "stateExpirationLength": 0,
  • "idleStateExpirationLength": 0,
  • "authorization": {
    },
  • "identityProvider": {
    },
  • "tags": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string"
}

Get Flow Sharing Token

Get the sharing token for the last published version of a flow

path Parameters
flow
required
string <uuid>
query Parameters
nullPasswords
boolean

Whether the shared package should include password values.

Responses

Response samples

Content type
{
  • "token": "string"
}

Get Flow Version Sharing Token

Get the sharing token for a specific version of a flow

path Parameters
flow
required
string <uuid>
version
required
string <uuid>
query Parameters
nullPasswords
boolean

Whether the shared package should include password values.

Responses

Response samples

Content type
{
  • "token": "string"
}

Play

Delete Player

Delete a player by name

path Parameters
name
required
string
tenantId
required
string

Responses

Update Player

The player content should be sent as application/x-www-form-urlencoded; charset=UTF8 request with the body of the request set to =player content goes here

path Parameters
tenantId
required
string <uuid>
playerName
required
string
Request Body schema: application/x-www-form-urlencoded
player
string

Responses

Get Player

Get the contents of a player by name

path Parameters
playerName
required
string
tenantId
required
string <uuid>

Responses

Get Players

Get the names of all the players available in this tenant

path Parameters
tenantId
required
string

Responses

Response samples

Content type
[
  • "string"
]

Get Players

Get the names of all the players available in this tenant

path Parameters
tenantId
required
string

Responses

Response samples

Content type
[
  • "string"
]

Release

A controller to be consumed by the tooling to access releases

Get release

Gets a release by Id

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  • "summary": "string",
  • "flows": [
    ],
  • "currentEnvironmentId": "745f2c68-a57c-4444-9d0a-c36c5ce32199",
  • "canRollback": true,
  • "lastDeployed": "2019-08-24T14:15:22Z"
}

Delete a release

Deletes a release with the given Id

path Parameters
id
required
string <uuid>

Responses

Get releases

Gets all releases for the tenant the user is logged into

Request Body schema:
environmentId
string or null <uuid>
environmentClassificationTypes
Array of strings or null
fromDateTimeOffset
string or null <date-time>
searchTerm
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
[
  • {
    }
]

Delete release flow

Removes the flow from the release

path Parameters
id
required
string <uuid>
flowId
required
string <uuid>

Responses

Deploys a release

Deploys the release to the chosen environment

path Parameters
id
required
string <uuid>
environmentId
required
string <uuid>

Responses

Rollback a release

Removes the release from the environment so the previous release is executed

path Parameters
id
required
string <uuid>
environmentId
required
string <uuid>

Responses

Data

Load Data from Service

Request Body schema:
stateId
string or null

The state id that allows us to make the correct version references.

token
string or null

The unique token for this data job. The token can be used to help the plugin cache multiple data calls. If the token is provided, we can match it up with a previous data request - if we choose to cache it.

typeElementBindingId
string or null

The Id for the service element associated with this object data. The service element will give us the connection settings and allow us to validate various info around the type.

object (AuthorizationAPI)
Array of objects or null (EngineValueAPI)

The configuration information that comes from the service element.

object (CommandRequestAPI)
object (CultureAPI)
object (ListFilterAPI)
object (ObjectDataTypeAPI)
Array of objects or null (ObjectAPI)

The list of objects to insert, update or delete.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "culture": {
    },
  • "objectData": [
    ],
  • "hasMoreResults": true,
  • "offsetToken": "string",
  • "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa"
}

Files

Load Files from Service

Request Body schema:
stateId
string or null

The state id that allows us to make the correct version references.

serviceElementId
string or null

The service to grab the files from.

token
string or null

The unique token for this data job. The token can be used to help the plugin cache multiple data calls. If the token is provided, we can match it up with a previous data request - if we choose to cache it.

object (AuthorizationAPI)
Array of objects or null (EngineValueAPI)

The configuration information that comes from the service element.

object (CultureAPI)
resourcePath
string or null

The resouce path to use when sourcing the files.

resourceFile
string or null

The resouce path to use when sourcing a specific file.

object (FileListFilterAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "culture": {
    },
  • "objectData": [
    ],
  • "hasMoreResults": true,
  • "offsetToken": "string",
  • "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa"
}

Upload File to Service

Responses

Response samples

Content type
{
  • "culture": {
    },
  • "objectData": [
    ],
  • "hasMoreResults": true,
  • "offsetToken": "string",
  • "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa"
}

Delete File from Service

Request Body schema:
stateId
string or null

The state id that allows us to make the correct version references.

serviceElementId
string or null

The service to grab the files from.

token
string or null

The unique token for this data job. The token can be used to help the plugin cache multiple data calls. If the token is provided, we can match it up with a previous data request - if we choose to cache it.

object (AuthorizationAPI)
Array of objects or null (EngineValueAPI)

The configuration information that comes from the service element.

object (CultureAPI)
resourcePath
string or null

The resouce path to use when sourcing the files.

resourceFile
string or null

The resouce path to use when sourcing a specific file.

object (FileListFilterAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "culture": {
    },
  • "objectData": [
    ],
  • "hasMoreResults": true,
  • "offsetToken": "string",
  • "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa"
}

Flow

Load Flow by Name

path Parameters
name
required
string

The name of the flow to load

Responses

Response samples

Content type
{
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string",
  • "startMapElementId": "string"
}

Load Flow by ID

path Parameters
id
required
string <uuid>

The ID of the flow to load

Responses

Response samples

Content type
{
  • "id": {
    },
  • "developerName": "string",
  • "developerSummary": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "alertEmail": "string",
  • "isActive": true,
  • "isDefault": true,
  • "comment": "string",
  • "startMapElementId": "string"
}

List Flows

Used to list and filter existing snapshotted flows.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of flows where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of flows where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

List custom page components used in flow

path Parameters
id
required
string <uuid>

The ID of the flow to load

version
required
string <uuid>

The version ID of the flow to load

Responses

Response samples

Content type
[
  • { }
]

Log

Get Log

Get the execution log of a state

path Parameters
stateId
required
string
query Parameters
flowId
string

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "whoCreated": {
    },
  • "whoModified": {
    },
  • "whoOwner": {
    },
  • "stateId": "string",
  • "flowId": "string",
  • "flowDeveloperName": "string",
  • "entries": {
    }
}

Run

Authenticate (OAuth 1.0a)

Used to authenticate with OAuth 1.0a.

query Parameters
oauth_token
string

The OAuth authentication token to authenticate with.

oauth_verifier
string

The OAuth authentication verifier to authenticate with.

oauth_error
string

Responses

Authenticate (OAuth 2.0)

Used to authenticate with OAuth 2.0.

query Parameters
code
string

The OAuth authentication code the authenticate with.

state
string

The OAuth authentication state the authenticate with.

error
string

Provide an error code to throw an error with that code.

error_description
string

The error description to throw with the error code.

Responses

Authenticate (SAML)

Used to authenticate with SAML

Request Body schema: multipart/form-data
SAMLResponse
string
RelayState
string

Responses

/api/run/2/saml

Request Body schema: multipart/form-data
SAMLResponse
string
RelayState
string

Responses

/api/run/1/oidc

query Parameters
state
string
code
string

Responses

/api/run/2/oauth2

query Parameters
state
string
code
string

Responses

Get Authentication Context

When you initialize a Flow, you are provided with the authentication context in the response.

However, you can also retrieve and login to Services individually.

It’s important to note that despite authentication being done against a Flow state, the returned Runtime Authentication Token is valid across all Flow States.

path Parameters
stateId
required
string

The unique identifier of the Flow state.

query Parameters
serviceElementId
string

The serviceElmentId of the Service to get the authentication context of.

Responses

Response samples

Content type
{
  • "directoryName": "string",
  • "directoryId": "string",
  • "loginUrl": "string",
  • "authenticationType": "string"
}

Authenticate

Authenticate with the given authentication credentials to the given state

path Parameters
stateId
required
string

The unique identifier of the Flow state to authenticate to.

query Parameters
serviceElementId
string

The Service element id of the Service to authenticate to.

Request Body schema:
Array of objects or null (EngineValueAPI)

Any additional configuration values that may have been applied by the engine to help with authentication.

authenticationType
string or null

The type of authentication being performed

username
string or null

The username for your account in the directory

password
string or null

The password for your account in the directory

token
string or null

The account token for the directory. For OAuth2 integration, this the access token

code
string or null

The OAuth2 code

sessionToken
string or null

The session token for the directory. For services such as salesforce.com, this is the sessionId

sessionUrl
string or null

The session URL for the directory. For services such as salesforce.com, this is the pod instance you are currently logged into

loginUrl
string or null

The REST endpoint for the plugin providing the identity

redirectUri
string or null

The OAuth2 redirect URI

instanceUrl
string or null

The particular instance of the directory. For services such as salesforce.com, this is either "https://login.salesforce.com" (default) or "https://test.salesforce.com".

platformUri
string or null

The URI of the Flow platform that sent the request

tenantId
string or null
verifier
string or null

The OAuth1.0 verifier

Responses

Request samples

Content type
No sample

Response samples

Content type
"string"

Authorization Check

Check if the currently authenticated user has permission to access the state at its current position

path Parameters
state
required
string <uuid>

The unique identifier of the Flow state to check the current user against.

Responses

Get Navigation

Activate a navigation and if the current Flow state is on a navigation item, then that item is highlighted.

path Parameters
stateId
required
string

The unique identifier of the Flow state.

Request Body schema:

The details of the navigation to activate.

object (CultureAPI)
stateId
string or null
stateToken
string or null
navigationElementId
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "culture": {
    },
  • "developerName": "string",
  • "label": "string",
  • "navigationItemResponses": [
    ],
  • "navigationItemDataResponses": [
    ],
  • "tags": [
    ],
  • "isVisible": true,
  • "isEnabled": true,
  • "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa",
  • "persistState": true,
  • "persistValues": true,
  • "position": 0
}

Flow Out

Initiate a flow out from an Outcome that is configured with a Flow Out.

path Parameters
stateId
required
string

The unique identifier of the Flow state.

selectedOutcomeId
required
string

The outcome to Flow Out through.

Responses

Response samples

Content type
{
  • "culture": {
    },
  • "stateId": "string",
  • "stateToken": "string",
  • "currentMapElementId": "string",
  • "currentStreamId": "string",
  • "statusCode": "string",
  • "authorizationContext": {
    },
  • "navigationElementReferences": [
    ],
  • "isHistoricalNavigationEnabled": true
}

Initialize a Flow

Used to initialize a flow

Request Body schema:
object (FlowIdAPI)

A composite unique identifier assigned by the platform, which should not be included for new flows.

stateId
string or null

The unique identifier for an existing State. This parameter should be used if the first initialization request was rejected due to access being denied due to authentication. If you do not re-use this stateId property, your inputs will not be correctly assigned.

parentStateId
string or null

The unique identifier for the parent State that "spawned" this State. This property is assigned when a Flow calls a Sub-Flow. The Sub-Flow will have this property assigned referencing the parent Flow.

externalIdentifier
string or null

An arbitrary external identifier that can be used to query for a State.

object or null

Annotations take the form of {"mykey":"myvalue"}. Any annotations added to the State will be persisted for the duration of the Flow. Annotations are passed to the executing player and also through to Services. Annotations can be changed at any time through the execution of the Flow.

Array of objects or null (EngineValueAPI)

An array of engine value objects that will be used to assign values in the flow at initialization.

playerUrl
string or null

The location of the player that should be used for sharing and notifications when first running the flow. The service will automatically append the "flow-id" parameter to this url so the player knows which flow it is playing.

joinPlayerUrl
string or null

The location of the player that should be used for sharing and notifications when joining a running flow. The service will automatically append the "join" parameter to this url so the player knows which flow and state it is playing (the "join" parameter is the state identifier).

mode
string or null

The mode you wish to run the flow in. The mode is mainly useful for debugging purposes as you can step through the flow and also view state information to check everything is working as expected.

reportingMode
string or null

The reporting mode under which you want to run this State of a Flow.

environmentId
string or null

The environment where we want to run the flow in

object (IdentityProviderCredentialsAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "culture": {
    },
  • "stateId": "string",
  • "stateToken": "string",
  • "currentMapElementId": "string",
  • "currentStreamId": "string",
  • "statusCode": "string",
  • "authorizationContext": {
    },
  • "navigationElementReferences": [
    ],
  • "isHistoricalNavigationEnabled": true
}

Initialize a Flow (Simple)

Used to initialise a flow and authenitcate into it.

Request Body schema:

The details of the Flow with a username and password to authenticate with.

id
string or null <uuid>
versionId
string or null <uuid>
developerName
string or null
Array of objects or null (EngineValueAPI)
username
string or null
password
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "culture": {
    },
  • "stateId": "string",
  • "parentStateId": "string",
  • "stateToken": "string",
  • "alertEmail": "string",
  • "waitMessage": "string",
  • "notAuthorizedMessage": "string",
  • "flowId": "string",
  • "flowName": "string",
  • "flowVersion": "string",
  • "currentMapElementId": "string",
  • "currentStreamId": "string",
  • "invokeType": "string",
  • "annotations": {
    },
  • "mapElementInvokeResponses": [
    ],
  • "voteResponse": {
    },
  • "stateLog": {
    },
  • "preCommitStateValues": [
    ],
  • "stateValues": [
    ],
  • "outputs": [
    ],
  • "frames": [
    ],
  • "statusCode": "string",
  • "runFlowUri": "string",
  • "joinFlowUri": "string",
  • "authorizationContext": {
    },
  • "navigationElementReferences": [
    ],
  • "isHistoricalNavigationEnabled": true,
  • "waitExpiresAt": "2019-08-24T14:15:22Z",
  • "isPageWait": true,
  • "pageType": 0,
  • "title": "string"
}

Invoke Flow State

Used to invoke a flow state

path Parameters
stateId
required
string

The unique identifier of the Flow state.

Request Body schema:
object (CultureAPI)
stateId
string or null

The unique identifier for the initialized flow state. The state identifier is needed throughout the execution of the flow as it is the pointer that points the engine to the correct running instance of a flow.

stateToken
string or null

The unique identifier for the token response from the state. The state token identifier changes with every cycle of request/response. The token is needed as it tells the engine how in-sync your request is with the current service side state.

currentMapElementId
string or null

The unique identifier for the map element the user is currently executing against.

navigationElementId
string or null

The unique identifier for the navigation element that's being used to drive the navigation scheme.

selectedNavigationItemId
string or null

When executing using an InvokeType of 'NAVIGATE', this is the selected navigation item the user wishes to move to in the Flow.

selectedMapElementId
string or null

When executing a Flow that has the allowJumping property set to 'true', the user can move to any Map Element in the Flow regardless of navigation or outcomes. This is the unique identifier of the Map Element the user wishes to navigate to and must be used with an InvokeType of 'NAVIGATE'.

selectedStateEntryId
string or null

When executing a Flow that has the allowJumping property set to 'true', the user can move to any Map Element regardless of navigation or outcomes. This is the Id of the State Entry that the user wishes to navigate to and must be used with an InvokeType of 'NAVIGATE'. The engine will calculate the Map Element from the previous State Entry and execute a jump to it. This is an alternative to using 'selectedMapElementId' jumping, with this method offering an added capability to navigate between different flows.

invokeType
string or null

The way you want to invoke the engine as part of this request. The user may be navigating forward, or you may be wanting to perform a sync operation to update the UI due to another user making a change.

object or null

Key value pairs you wish to annotate to the flow. Annotations take the form of {"mykey":"myvalue"}. Any annotations added to the state will be persisted for the duration of the flow. Annotations are passed to the executing player and also through to plugin services. Annotations can be changed at any time through the execution of the flow.

object (GeoLocationAPI)
object (MapElementInvokeRequestAPI)
mode
string or null

The mode you wish to run the flow in. The mode is mainly useful for debugging purposes as you can step through the flow and also view state information to check everything is working as expected.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "culture": {
    },
  • "stateId": "string",
  • "parentStateId": "string",
  • "stateToken": "string",
  • "alertEmail": "string",
  • "waitMessage": "string",
  • "notAuthorizedMessage": "string",
  • "flowId": "string",
  • "flowName": "string",
  • "flowVersion": "string",
  • "currentMapElementId": "string",
  • "currentStreamId": "string",
  • "invokeType": "string",
  • "annotations": {
    },
  • "mapElementInvokeResponses": [
    ],
  • "voteResponse": {
    },
  • "stateLog": {
    },
  • "preCommitStateValues": [
    ],
  • "stateValues": [
    ],
  • "outputs": [
    ],
  • "frames": [
    ],
  • "statusCode": "string",
  • "runFlowUri": "string",
  • "joinFlowUri": "string",
  • "authorizationContext": {
    },
  • "navigationElementReferences": [
    ],
  • "isHistoricalNavigationEnabled": true,
  • "waitExpiresAt": "2019-08-24T14:15:22Z",
  • "isPageWait": true,
  • "pageType": 0,
  • "title": "string"
}

Join Flow State

Used to join the state provided

path Parameters
stateId
required
string

The unique identifier of the Flow state.

query Parameters
mode
string

The mode in which to join the state.

Responses

Response samples

Content type
{
  • "culture": {
    },
  • "stateId": "string",
  • "parentStateId": "string",
  • "stateToken": "string",
  • "alertEmail": "string",
  • "waitMessage": "string",
  • "notAuthorizedMessage": "string",
  • "flowId": "string",
  • "flowName": "string",
  • "flowVersion": "string",
  • "currentMapElementId": "string",
  • "currentStreamId": "string",
  • "invokeType": "string",
  • "annotations": {
    },
  • "mapElementInvokeResponses": [
    ],
  • "voteResponse": {
    },
  • "stateLog": {
    },
  • "preCommitStateValues": [
    ],
  • "stateValues": [
    ],
  • "outputs": [
    ],
  • "frames": [
    ],
  • "statusCode": "string",
  • "runFlowUri": "string",
  • "joinFlowUri": "string",
  • "authorizationContext": {
    },
  • "navigationElementReferences": [
    ],
  • "isHistoricalNavigationEnabled": true,
  • "waitExpiresAt": "2019-08-24T14:15:22Z",
  • "isPageWait": true,
  • "pageType": 0,
  • "title": "string"
}

Invoke Flow State

Used to invoke a flow state

path Parameters
stateId
required
string

The unique identifier of the Flow state.

Request Body schema:
object (CultureAPI)
stateId
string or null

The unique identifier for the initialized flow state. The state identifier is needed throughout the execution of the flow as it is the pointer that points the engine to the correct running instance of a flow.

stateToken
string or null

The unique identifier for the token response from the state. The state token identifier changes with every cycle of request/response. The token is needed as it tells the engine how in-sync your request is with the current service side state.

currentMapElementId
string or null

The unique identifier for the map element the user is currently executing against.

navigationElementId
string or null

The unique identifier for the navigation element that's being used to drive the navigation scheme.

selectedNavigationItemId
string or null

When executing using an InvokeType of 'NAVIGATE', this is the selected navigation item the user wishes to move to in the Flow.

selectedMapElementId
string or null

When executing a Flow that has the allowJumping property set to 'true', the user can move to any Map Element in the Flow regardless of navigation or outcomes. This is the unique identifier of the Map Element the user wishes to navigate to and must be used with an InvokeType of 'NAVIGATE'.

selectedStateEntryId
string or null

When executing a Flow that has the allowJumping property set to 'true', the user can move to any Map Element regardless of navigation or outcomes. This is the Id of the State Entry that the user wishes to navigate to and must be used with an InvokeType of 'NAVIGATE'. The engine will calculate the Map Element from the previous State Entry and execute a jump to it. This is an alternative to using 'selectedMapElementId' jumping, with this method offering an added capability to navigate between different flows.

invokeType
string or null

The way you want to invoke the engine as part of this request. The user may be navigating forward, or you may be wanting to perform a sync operation to update the UI due to another user making a change.

object or null

Key value pairs you wish to annotate to the flow. Annotations take the form of {"mykey":"myvalue"}. Any annotations added to the state will be persisted for the duration of the flow. Annotations are passed to the executing player and also through to plugin services. Annotations can be changed at any time through the execution of the flow.

object (GeoLocationAPI)
object (MapElementInvokeRequestAPI)
mode
string or null

The mode you wish to run the flow in. The mode is mainly useful for debugging purposes as you can step through the flow and also view state information to check everything is working as expected.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  • "rootElement": {
    },
  • "navigations": [
    ],
  • "outcomes": [
    ],
  • "stateId": "string",
  • "stateToken": "string",
  • "waitMessage": "string",
  • "notAuthorizedMessage": "string",
  • "flowId": "string",
  • "flowName": "string",
  • "flowVersion": "string",
  • "currentMapElementId": "string",
  • "invokeType": "string",
  • "statusCode": "string",
  • "joinFlowUri": "string",
  • "authorizationContext": {
    },
  • "waitExpiresAt": "2019-08-24T14:15:22Z",
  • "isPageWait": true,
  • "rootFaults": {
    },
  • "pageComponentDataResponses": [
    ],
  • "pageContainerDataResponses": [
    ],
  • "pageType": 0,
  • "title": "string"
}

/api/run/2/state/{stateId}

path Parameters
stateId
required
string
query Parameters
mode
string

Responses

Response samples

Content type
{
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  • "rootElement": {
    },
  • "navigations": [
    ],
  • "outcomes": [
    ],
  • "stateId": "string",
  • "stateToken": "string",
  • "waitMessage": "string",
  • "notAuthorizedMessage": "string",
  • "flowId": "string",
  • "flowName": "string",
  • "flowVersion": "string",
  • "currentMapElementId": "string",
  • "invokeType": "string",
  • "statusCode": "string",
  • "joinFlowUri": "string",
  • "authorizationContext": {
    },
  • "waitExpiresAt": "2019-08-24T14:15:22Z",
  • "isPageWait": true,
  • "rootFaults": {
    },
  • "pageComponentDataResponses": [
    ],
  • "pageContainerDataResponses": [
    ],
  • "pageType": 0,
  • "title": "string"
}

Response From Service

Used to get the invoke type of the service response provided

Request Body schema:
token
string or null

The execution token needed for any callback responses from the Service.

tenantId
string or null

The unique identifier for the tenant that made the request to the Service.

object (CultureAPI)
object or null

Any runtime annotations that were provided to the State plus any additional annotations the Service may be providing.

invokeType
string or null

Tells the engine what this service would like it to do. At the moment, there are really only two possible commands: WAIT (to tell the engine to wait for a completed response) or DONE (to tell the engine that it has completed its work.

waitMessage
string or null

The "wait" message that should be provided to users waiting for the Service to complete its tasks.

Array of objects or null (EngineValueAPI)

The output values from the Service being sent back to the Flow State. Outputs will be applied to the Flow State even if the InvokeType is set to WAIT.

selectedOutcomeId
string or null

The Outcome the Service would like the Flow to follow. If the Outcome has Rules, the Service request for this outcome will be ignored unless the Rules are also satisfied.

object or null

Any faults that have happened in the Service that should be reported up to the Flow State.

Array of objects or null (ValueFaultAPI)

Any faults that are directly attributed to an input value provided in the ServiceRequest. If a ValueFault is specified, ManyWho will attempt to match this error with any input fields that are bound to that Value.

mode
string or null

The mode which the Service would like the Flow State to execute under.

Responses

Request samples

Content type
No sample

Response samples

Content type
"string"

Event

Used to get the invoke type of the service event provided

Request Body schema:
token
string or null

The execution token needed for any callback responses from the Service.

tenantId
string or null

The unique identifier for the tenant that made the request to the Service.

object (CultureAPI)
object or null

Any runtime annotations that were provided to the State plus any additional annotations the Service may be providing.

object (EngineValueAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
"string"

Add Listener

Used to add a listener to the state stateId from the details in the request body

path Parameters
stateId
required
string
Request Body schema:

The details of the state listener used to set up the new listener

listenType
string or null
stateId
string or null
callbackUri
string or null
object or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "listenType": "string",
  • "stateId": "string",
  • "callbackUri": "string",
  • "annotations": {
    },
  • "id": "string"
}

Remove Listener

Used to remove the listener on the state stateId with the id listenerId

path Parameters
stateId
required
string

The unique identifier of the Flow state.

listenerId
required
string

The unique identifier of the listener.

Responses

Import State

Used to import a state into the tenant from JSON

Request Body schema:

The JSON of the state to be imported.

string

Responses

Request samples

Content type
No sample

Export State

Used to export a state from the tenant into JSON.

path Parameters
stateId
required
string

The unique identifier of the Flow state.

Responses

Response samples

Content type
"string"

Check Flow State Changes

Used to check if a change has occurred to the state, by comparing the current state token of the state with the provided one

path Parameters
stateId
required
string <uuid>

The unique identifier of the Flow state.

stateToken
required
string <uuid>

The state token to compare to the current state token of the Flow state

Responses

Response samples

Content type
true

Get Flow State Value

Used to get the value for the id provided in the flow state

path Parameters
stateId
required
string <uuid>

The unique identifier of the Flow state.

id
required
string <uuid>

The unique identifier of the Flow value.

Responses

Response samples

Content type
{
  • "valueElementId": "string",
  • "typeElementId": "string",
  • "typeElementPropertyId": "string",
  • "developerName": "string",
  • "typeElementDeveloperName": "string",
  • "typeElementPropertyDeveloperName": "string",
  • "contentValue": "string",
  • "contentType": "string",
  • "objectData": [
    ]
}

Get Flow State Value by Name

Used to get the value for the name provided in the flow state

path Parameters
stateId
required
string <uuid>

The unique identifier of the Flow state.

name
required
string

The name of the Flow value.

Responses

Response samples

Content type
{
  • "valueElementId": "string",
  • "typeElementId": "string",
  • "typeElementPropertyId": "string",
  • "developerName": "string",
  • "typeElementDeveloperName": "string",
  • "typeElementPropertyDeveloperName": "string",
  • "contentValue": "string",
  • "contentType": "string",
  • "objectData": [
    ]
}

Get Flow State Values

Used to get all the values in the flow state. This endpoint requires a runtime authentication token, which means it can only be used with non-public flows.

path Parameters
stateId
required
string <uuid>

The unique identifier of the Flow state.

Responses

Response samples

Content type
[
  • {
    }
]

Set Flow State Values

Used to set values in the flow state with the given data. This endpoint requires a runtime authentication token, which means it can only be used with non-public flows.

path Parameters
stateId
required
string <uuid>

The unique identifier of the Flow state.

Request Body schema:

The new details for a list of values.

Array
valueElementId
string or null

The unique identifier for the value in the flow being assigned. Using the id to reference the value ensures that your player is guaranteed to be assigning the correct value. If you reference a value by developerName, it is possible for the author to break integration points simply by changing the name of the value. You must provide an 'id' or a 'developerName'.

typeElementId
string or null

The unique identifier for the object type of the value in the flow being assigned. Using the typeElementId ensures that your player is guaranteed to be referencing the correct object type. If you use the typeElementDeveloperName property, a change in the type name can break the integration. We ask that you specify the type as we may in future support type casting and we therefore want to know the type you're passing in so we can validate it is correct before mapping to the super type.

typeElementPropertyId
string or null

The unique identifier for the object property of the value in the flow being assigned. Typed objects all have properties. Using the typeElementPropertyId allows you to assign a property in an object value as opposed to the whole value. As with the other identifier references, using the typeElementPropertyId ensures that your player is guaranteed to be assigning the correct value. Using the typeElementPropertyDeveloperName makes it possible to break the integration if the author changes the developerName of a property in the type.

developerName
string or null
typeElementDeveloperName
string or null

The developer name for the object type of the value in the flow being assigned.

typeElementPropertyDeveloperName
string or null

The developer name for the object property of the value in the flow being assigned.

contentValue
string or null

The actual content value being assigned to the value in the flow. This property should be used for all "primitive", non-typed values in your flow. For example, if you are referencing a value called "First Name", this would be the value you actually want to assign to it: e.g. "Steve".

contentType
string or null

The content type of the value you are passing into the flow. The content types are specified by the ContentType enumeration.

Array of objects or null (ObjectAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
[
  • {
    }
]

Get Flow State History

Returns a sequence of visited map elements (excluding the current one) in the order of visiting them

path Parameters
stateId
required
string <uuid>

The unique identifier of the Flow state.

query Parameters
onlyUIMapElements
boolean
Default: false

The flag indicating that only the UI map elements should be returned

Responses

Response samples

Content type
{
  • "entries": [
    ]
}

Download document

Downloads the octet stream of a document stored in the Flow internal storage

path Parameters
stateId
required
string <uuid>

The unique identifier of the Flow state.

fileId
required
string

The id of the document

filename
required
string

The chosen name of the document that is returned

Responses

Invoker

List Invoker Requests

Get the metadata for every request sent to a Service

query Parameters
pageSize
integer <int32>
Default: 10

The number of service requests to return

page
integer <int32>
Default: 1

The current page of service requests

orderBy
string
Default: "createdAt"

Property to order service requests by, defaults to "createdAt"

orderDirection
string
Default: "DESC"

ASC or DESC, defaults to DESC

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Get Invoker Requests

Get the metadata for a specific request sent to a service

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  • "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa",
  • "content": "string",
  • "method": "string",
  • "uri": "string",
  • "authorizationHeader": "string",
  • "mapElementId": "e181eea5-224a-46ff-9a23-0fd2213ec8f6",
  • "sequenceNumber": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "failures": [
    ],
  • "attributes": {
    }
}

List Flow Invoker Requests

Get the metadata for every request sent to a Service from a specific Flow

path Parameters
id
required
string <uuid>

The flow ID

query Parameters
pageSize
integer <int32>
Default: 10

The number of service requests to return

page
integer <int32>
Default: 1

The current page of service requests

orderBy
string
Default: "createdAt"

Property to order service requests by, defaults to "createdAt"

orderDirection
string
Default: "DESC"

ASC or DESC, defaults to DESC

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

List Flow Version Invoker Requests

Get the metadata for every request sent to a Service from a specific version of a Flow

path Parameters
id
required
string <uuid>

The flow ID

version
required
string <uuid>

The flow version

query Parameters
pageSize
integer <int32>
Default: 10

The number of service requests to return

page
integer <int32>
Default: 1

The current page of service requests

orderBy
string
Default: "createdAt"

Property to order service requests by, defaults to "createdAt"

orderDirection
string
Default: "DESC"

ASC or DESC, defaults to DESC

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

List State Invoker Requests

Get the metadata for every request sent to a Service from a specific State

path Parameters
id
required
string <uuid>

The state ID

query Parameters
pageSize
integer <int32>
Default: 10

The number of service requests to return

page
integer <int32>
Default: 1

The current page of service requests

orderBy
string
Default: "createdAt"

Property to order service requests by, defaults to "createdAt"

orderDirection
string
Default: "DESC"

ASC or DESC, defaults to DESC

Responses

Response samples

Content type
{
  • "meta": {
    },
  • "links": {
    },
  • "items": [
    ]
}

Cultures

The content value culture object represents a language or brand supported by the tenant.

Content value cultures are used to specify the language/brand options that are available for the tenant. By default all tenants have a content value culture for USA (English). However, for multi-national/language use-cases, others can be specified. They follow the ISO conventions for language. However, the platform also supports a fourth variation on the standard ISO properties; this is brand. As a result, content value culture objects can also be used to specify white-labelling or single language variations on flow content.

Create/Update Content Value Culture

Used to create new content value cultures or update existing ones.

Request Body schema:
id
string or null

The id for the culture.

developerName
string or null

The developer name for the culture.

developerSummary
string or null

The developer summary for the culture.

brand
string or null

The brand for the culture.

language
string or null

The language for the culture.

country
string or null

The country for the culture.

variant
string or null

The variant for the culture.

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "brand": "string",
  • "language": "string",
  • "country": "string",
  • "variant": "string"
}

List Content Value Cultures

Used to get existing content value cultures.

Responses

Response samples

Content type
[
  • {
    }
]

Get Content Value Culture

Used to get an existing content value culture.

path Parameters
id
required
string <uuid>

The unique identifier for the content value culture

Responses

Response samples

Content type
{
  • "id": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "brand": "string",
  • "language": "string",
  • "country": "string",
  • "variant": "string"
}

Delete Content Value Culture

Used to delete an existing content value culture.

path Parameters
id
required
string <uuid>

Responses

Flow

The flow translation object provides all of the content elements and properties in a flow that can be translated.

The flow translation object provides every element in the flow that is available for translation. It therefore provides all of the content in the flow, regardless of whether or not the elements are shared (such as value and page elements) or specific to the flow (such as map or navigation elements). The flow translation object also includes additional properties to help translators identify the purpose/location of the content being translated.

List Flow Translations

Used to filter existing flow objects that are available for translation.

Filter

The filter can take the following formats:

  • developerName eq '{developer_name}': Filter the list of flows where the developerName property exactly matches the provided developer name (case insensitive)
  • substringof(developerName, '{developer_name}'): Filter the list of flows where the developerName property partially matches the provided developer name (case insensitive)
query Parameters
filter
string

The filter used for querying

Responses

Response samples

Content type
[
  • {
    }
]

Get Flow Translation

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "editingToken": "4f2b41cf-03fb-4bbd-ab0e-8a28d1bb43cf",
  • "id": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "startMapElementId": "string",
  • "navigationElements": [
    ],
  • "mapElements": [
    ],
  • "pageElements": [
    ],
  • "typeElements": [
    ],
  • "valueElements": [
    ]
}

Map Element

The map element translation object provides all of the content properties in a map element that can be translated.

The map element translation object also includes additional properties to help translators identity the purpose/location of the content being translated.

Update Map Element Translation

path Parameters
editingToken
required
string <uuid>
flow
required
string <uuid>
Request Body schema:
id
string or null
elementType
string or null
developerName
string or null
developerSummary
string or null
object (ContentValueDocumentAPI)
userContentContentValueId
string or null
statusMessageContentValueId
string or null
postUpdateMessageContentValueId
string or null
notAuthorizedMessageContentValueId
string or null
labelContentValueId
string or null
Array of objects or null (OutcomeTranslationResponseAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "userContentContentValueId": "string",
  • "statusMessageContentValueId": "string",
  • "postUpdateMessageContentValueId": "string",
  • "notAuthorizedMessageContentValueId": "string",
  • "labelContentValueId": "string",
  • "outcomes": [
    ]
}

Get Map Element Translation

path Parameters
editingToken
required
string <uuid>
flow
required
string <uuid>
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "userContentContentValueId": "string",
  • "statusMessageContentValueId": "string",
  • "postUpdateMessageContentValueId": "string",
  • "notAuthorizedMessageContentValueId": "string",
  • "labelContentValueId": "string",
  • "outcomes": [
    ]
}

Navigation Element

This element allow you to have one or more translations for the element navigation. The navigation element translation will show the information in runtime depending on which culture is choose when the flow runs.

Update Navigation Translation

path Parameters
editingToken
required
string <uuid>
flow
required
string <uuid>
Request Body schema:
id
string or null
elementType
string or null
developerName
string or null
developerSummary
string or null
object (ContentValueDocumentAPI)
labelContentValueId
string or null
Array of objects or null (NavigationItemTranslationResponseAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "labelContentValueId": "string",
  • "navigationItems": [
    ]
}

Get Navigation Translation

path Parameters
editingToken
required
string <uuid>
flow
required
string <uuid>
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "labelContentValueId": "string",
  • "navigationItems": [
    ]
}

Page Element

The page element translation object provides all of the content properties in a page element that can be translated.

The page element translation object also includes additional properties to help translators identify the purpose/location of the content being translated.

Update Page Translation

Request Body schema:
id
string or null
elementType
string or null
developerName
string or null
developerSummary
string or null
object (ContentValueDocumentAPI)
labelContentValueId
string or null
Array of objects or null (PageContainerTranslationResponseAPI)
Array of objects or null (PageComponentTranslationResponseAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "labelContentValueId": "string",
  • "pageContainers": [
    ],
  • "pageComponents": [
    ]
}

Get Page Transation

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "labelContentValueId": "string",
  • "pageContainers": [
    ],
  • "pageComponents": [
    ]
}

Type Element

The type element translation object provides all of the content properties in a type element that can be translated.

The type element translation object also includes additional properties to help translators identify the purpose/location of the content being translated.

Update Type Translation

Request Body schema:
id
string or null
elementType
string or null
developerName
string or null
developerSummary
string or null
object (ContentValueDocumentAPI)
Array of objects or null (PropertyTranslationResponseAPI)

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "properties": [
    ]
}

Get Type Translation

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "properties": [
    ]
}

Value Element

The value element translation object provides all of the content properties in a value element that can be translated.

The value element translation object also includes additional properties to help translators identify the purpose/location of the content being translated.

Update Value Translation

Request Body schema:
id
string or null
elementType
string or null
developerName
string or null
developerSummary
string or null
object (ContentValueDocumentAPI)
contentType
string or null
contentFormatContentValueId
string or null
defaultContentValueContentValueId
string or null

Responses

Request samples

Content type
No sample

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "contentType": "string",
  • "contentFormatContentValueId": "string",
  • "defaultContentValueContentValueId": "string"
}

Get Value Translation

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
{
  • "id": "string",
  • "elementType": "string",
  • "developerName": "string",
  • "developerSummary": "string",
  • "contentValueDocument": {
    },
  • "contentType": "string",
  • "contentFormatContentValueId": "string",
  • "defaultContentValueContentValueId": "string"
}