Layer 1: Core

Layer 1 contains the specification for basic logical blocks that can be used without reference to any mobile channels. These blocks provide basic flow control for Flows. They make use of the Expression Specification for generating content and evaluating decisions.

Namespace: Core

Log Block

Type: Core.Log
Suggested number of exits: 1
Supported channels: all

This block appends a low-level message to the Context's log.

Block `config`

Key

Description

message (string or resource)

The content to be output. This can be a string or a localized resource; it supports parsing of expressions in rendering

Detailed Behaviour

The Context for a Flow shall have a log key, which preserves a mapping of timestamps and log messages for debugging. These logs must be maintained for the duration of the Run, and may be maintained for a longer period. The Log Block provides one way for a Flow to write to this log. On executing this block, the platform will append a key/value pair to the log object within the Context as below, and then proceed to the next block.

e.g.,

"2017-03-05T12:30:42.123+00:00":"This is a sample log message."

Example

{
  "type": "Core.Log",
  "name": "test_log_block",
  "label": "Test Log Block",
  "exits": [
    {
      "uuid": "572f6e0d-6fd7-42f2-b5d4-fdcce49a1a12",
      "name": "Default",
      "default": true,
      "config": {}
    }
  ],
  "config": {
    "message": "bdd02d17-2baa-428e-8159-8d075b571d2d"
  }
}

Case Block

Type: Core.Case
Suggested number of exits: variable
Supported channels: all

This block evaluates a list of expressions, one for each exit, and terminates through the first exit where the corresponding expression evaluates to a "truthy" result.

Block `config`

Key

Description

none

Keys for each exit are:

Key

Description

test

The expression to be evaluated. If the expression evalutes to a "truthy" value, the block will terminate through this exit.

default (boolean)

If this key is present and true, the exit is treated as the flow-through default in a case evaluation. The block will terminate through this exit if no test expressions in other exits evaluate true.

Each exit must specify one of either test or default. Each Case block must have exactly one default exit. Conventionally the default exit is listed last in the list.

Detailed Behaviour

This block will sequentially evaluate the test expressions in each exit (passing over any default exit), in order. If the test expression evaluates to a truthy value using the Context and Expressions framework, flow proceeds through the corresponding exit (and no further exits are evaluated). If no test expressions are found truthy, the flow proceeds through the default exit.

Truthy values include all values that are not 0, false, null, or undefined.

Example

{
  "type": "Core.Case",
  "name": "patient_age_decision",
  "label": "Patient Age Decision",
  "exits": [
    {
      "uuid": "4c0dd2c8-a08f-45f7-9bf6-82bbff3fa968",
      "name": "under_18",
      "test": "contact.patient_age < 18",
      "destination_block": "338d216f-996c-4c6a-a1f5-fa2d1abe67a3"
    },
    {
      "uuid": "8968deb6-c4f3-4163-b3fc-d518bea14332",
      "name": "over_18",
      "test": "contact.patient_age >= 18",
      "destination_block": "7e0cded0-4bb2-49d7-8001-8eedd9d14f3b"
    },
    {
      "uuid": "4cfbab2d-132e-4583-8974-85424bff2424",
      "name": "default",
      "default": true,
    }
  ]
},

Run Another Flow Block

Type: Core.RunFlow
Suggested number of exits: 1 + default exit (used in case of error or invalid input)
Supported channels: all

This block starts and runs another Flow, and returns execution to the current Flow when finished.

Block `config`

Key

Description

flow_id (uuid)

The UUID of the other Flow to run.

Detailed behaviour

Entry:

On entry to this block, control proceeds into the other Flow given by flow_id. The Context for the outer flow is saved and stored within the new inner Flow's Context under the parentFlowContext key.

Exit:

Multiple levels of nested Flows shall be supported. When an inner Flow terminates, this block resumes execution in the outer Flow. The Context for the inner flow is saved and stored under the childFlowContext key, and flow proceeds through the next block. If an exception exit is triggerred within an inner flow causing the inner flow to terminate, flow proceeds through the error exit.

Example

    [...]
    "type": "Core.RunFlow",
    "name": "RunAnotherFlow",
    "label": "Another Flow",
    "config": {
      "flow_id": "ea5d7659-16cd-4e9a-86dc-28398cb41aed"
    },
    "exits": [...]

Output Block

Type: Core.Output
Suggested number of exits: 1
Supported channels: all

This block provides a connection to the Flow Results specification, by storing a named Output variable.

Block `config`

Key

Description

value (expression)

The expression that will be evaluated and written to the Results.

Detailed Behaviour

Not all block interactions and low-level logs are important to users; most users are concerned with a subset of results that have specific meaning -- the "Flow Results". (See Flow Results specification.) Any block type, as part of its specified runtime behaviour, may write to the Flow Results. The Output Block is a low-level block that does just simply one thing: write a named variable corresponding to the name of the block to the Flow Results, determined by the value expression.

Example

TODO

Set Contact Property

Type: Core.SetContactProperty
Suggested number of exits: 1
Supported channels: all

A common use-case for platforms that run flows on Contacts is to modify the Contact's properties based on the interactions within a flow. To simplify this common use-case, all blocks have a standard capability to specify how a contact property should be updated. The SetContactProperty block is a simple block that performs only this single operation, and is consistent with the standard block specification.

Block `config`

Key

Description

set_contact_property (array, required)

See below

`set_contact_property` array items

Key

Description

property_key (string)

The attribute of the Contact that will be set (or updated if it already has a value set).

property_value (expression)

The expression that will be evaluated and stored.

Detailed Behaviour

The property update shall be evaluated and stored immediately prior to following the exit node out of the block.

The property_key is a string attribute within the context of the Contact, and is not further restricted by this specification. For complete block interoperability across vendors, vendors would need to agree on the format and identity of property_key. (For instance, property_key could be "gender" , or it could be a UUID referenced to an external taxonomy service.)

Example

{
    "type": "Core.SetContactProperty",
    "name": "test_contact_property",
    "label": "Test Contact Property",
    "config": {
      "set_contact_property": [
        {
          "property_key": "gender",
          "property_value": "male"
        },
        {
          "property_key": "age_range",
          "property_value": "18_to_30"
        }
      ]
    },
    "exits": [
      {
        "uuid": "15e38cd1-0ed1-49ce-93d3-96b9e33a965a",
        "name": "Default",
        "default": true,
      }
    ]
}

Set Group Membership

Type: Core.SetGroupMembership
Suggested number of exits: 1
Supported channels: all

Another common operation for platforms that run flows on Contacts is to organize Contacts into groups based on the results of flow interactions. (Examples include managing sign-ups for opt-in campaigns, organizing Contacts into demographic groups, etc.) This block adds or removes the Contact from one or more groups. It can also clear all existing group memberships.

Block `config`

Key

Description

groups (array, optional)

A list of groups to add or remove the Contact from. (See below)

is_member (boolean, optional)

Determines the membership state: false to remove the contact from the group, true to add.

clear (boolean, optional)

Used instead of groups and is_member, to remove a Contact from all the groups they are in. This is useful to clear group membership without needing to know all of the Contact's existing groups.

`groups` array items

Key

Description

group_key (string)

An identifier for the group that membership will be set within.

group_name (string, optional)

A human-readable label in addition to the group_key, in cases where the group_name needs to be displayed to the Contact.

Detailed Behaviour

When groups and is_member is provided: The Contact will be added to the groups when is_member is true, and removed from the groups (if present) when is_member is false. This is done immediately before following the exit node out of the block.
When clear is provided and set to true: The Contact is removed from all of their existing groups.

The group_key is a string and is not further restricted by the spec. For complete block interoperability across vendors, vendors would need to agree on the format and identity of group_key.

Example

Adding a Contact to a group:

{
  "type": "Core.SetGroupMembership",
  "name": "ContactGMBlock",
  "label": "Test Group Membership",
  "config": {
    "groups": [
      {
        "group_key": "7294",
        "group_name": "Healthcare workers",
      }
    ],
    "is_member": true,
  },
  "exits": [
    {
      "uuid": "c43106ba-be75-4a86-8da4-837de8348a22",
      "name": "Default",
      "default": true,
      "destination_block": "338d216f-996c-4c6a-a1f5-fa2d1abe67a3"
    }
  ]
}

Removing a Contact from all their existing groups:

{
  "type": "Core.SetGroupMembership",
  "name": "ContactGMBlock",
  "label": "Remove all Group Memberships",
  "config": {
    "clear": true,
  },
  "exits": [
    {
      "uuid": "c43106ba-be75-4a86-8da4-837de8348a22",
      "name": "Default",
      "default": true,
      "destination_block": "338d216f-996c-4c6a-a1f5-fa2d1abe67a3"
    }
  ]
}

Webhook Block

Type: Core.Webhook
Suggested number of exits: 2 (Successful operation, and default exit on failure)
Supported channels: all

This block is used to connect flows to external API services: to notify external services of events during flows, and/or to retrieve personalized content to display to Contacts. The block can be used in two modes: in synchronous mode (wait_for_response=true), the block will wait for a response from the external service, parse the response, and make the response content available within Expressions. In asynchronous mode (wait_for_response=false), the Flow does not need to wait for a response from the external service before proceeding to the next block. This is useful for "notification only" use-cases where there might be high latency or unreliability in reaching the external service.

Block `config`

Key

Description

method (string)

The HTTP method to use, e.g.: "GET", "POST", "PUT", etc.

url (string, expression)

The destination endpoint of the external service. Supports expressions evaluated at runtime.

query_params (object, optional)

Query-string parameters that are appended to the url. The value of each parameter supports expressions evaluated at runtime.

headers (object, optional)

Headers to set in the HTTP request. The value of each key supports expressions evaluated at runtime.

auth (object, optional)

Used for HTTP basic authentication. This will set an Authorization header, overwriting any existing Authorization custom headers you have set within headers. Values support expressions evaluated at runtime.

max_content_length (integer, optional)

Defines the max size of the http response content in bytes allowed. Designed to prevent external endpoints from overloading runtimes. Default 10000 bytes.

body (string, optional)

The contents of the request body. Supports expressions evaluated at runtime. This should be pre-encoded properly for the destination endpoint; the block does not perform any additional encoding.

timeout (integer, optional)

Specifies the number of milliseconds before the request times out. If the request takes longer than timeout, the request will be aborted, the status (block.value) will be 408 and the raw block.response will be null. Default 10000.

wait_for_response (boolean, optional)

If false, the flow execution does not need to wait for a response from the endpoint to proceed on with the flow. (Used for "asynchronous" webhook blocks, to share flow results/contact updates with an external system, waiting for network availability if needed). When specified false, the block.value will be 202 (Accepted), and the raw block.response will be null. Default true.

Detailed Behaviour

In synchronous mode (wait_for_response=true), the block will:

Reach the external webhook service on url with method, query_params, and body.
Wait up to timeout milliseconds for the response
Make the response available to expressions as indicated:
- block.value: the HTTP response integer status code (e.g.: 200, 404, etc.)
- block.response: the response body received from the endpoint. If the response Content-type is "application/json", the response is parsed as JSON and stored as an object under block.response. In other cases, the raw response bytes are made available as a string in block.response.
- block.response_headers: the headers of the response received from the endpoint, stored as an object.

(As always, these are available via @results.<block.name>.value everywhere, and @block.value inside the current block.)

In asynchronous mode (wait_for_response=false), the block will

Reach the external webhook service on url with method, query_params, and body, although not necessarily before proceeding through the exit.
Set the block results as indicated:
- block.value will be 202 (Accepted)
- block.response will be null.

Example

{
  "type": "Core.Webhook",
  "name": "WebhookBlock1",
  "label": "Webhook BLock Test",
  "config": {
    // string.
    "method": "GET",

    // string. Supports expressions evaluated at runtime.
    "url": "https://this.isanexample.com/v1/test?user=@contact.user_id",

    // object, optional. Query-string parameters appended to the URL. Values support expressions evaluated at runtime.
    "query_params": {
      "contact_name": "@contact.name",
      "contact_pin": "@contact.pin"
    },
    
    // object, optional. Values support expressions evaluated at runtime.
    "headers": {     
      "Authorization": "Token AAFFZZHH"
    },

    // object, optional.  For HTTP basic authentication. This will set an `Authorization` header, overwriting any existing `Authorization` custom headers you have set within `headers`.  Keys support expressions evaluated at runtime.
    "auth": {
        "username": "janedoe",
        "password": "s00pers3cret"
    },

    // integer, optional, default 10000.  Defines the max size of the http response content in bytes allowed.
    "max_content_length": 20000,

    // string, optional. Request body. Supports expressions evaluated at runtime.
    "body": "\{
        \"operation\": \"new\",
        \"date\": \"2021-03-06\",
        \"person_id\": \"@contact.national_id\",
      \}",

    // integer, optional, default 10000.  Specifies the number of milliseconds before the request times out.  If the request takes longer than `timeout`, the request will be aborted, the status (`block.value`) will be 408 and the raw `block.response` will be null.
    "timeout": 30000,

    // boolean, optional, default true.  If false, the flow execution does not need to wait for a response from the endpoint to proceed on with the flow. ("asynchronous" webhook block, used to share flow results/contact updates with a 3rd party system, waiting for network availability if needed).  The `block.value` will be  202 (Accepted), and the raw `block.response` will be null.
    "wait_for_response": true
  },
  "exits": [
    {
      "uuid": "9b5c0eb4-46ca-4b54-86c5-f9d3d4e30538",
      "name": "Success",
      "test": "AND(block.value >= 200, block.value < 300)",
      "destination_block": "338d216f-996c-4c6a-a1f5-fa2d1abe67a3"
    },
    {
      "uuid": "c43106ba-be75-4a86-8da4-837de8348a22",
      "name": "Fail",
      "default": true,
      "destination_block": "338d216f-996c-4c6a-a1f5-fa2d1abe67a3"
    }
  ]
}

PreviousLayers NextLayer 2: Mobile Primitives

Last updated 2 years ago

Contents

Log Block

Block config

Detailed Behaviour

Example

Case Block

Block config

Detailed Behaviour

Example

Run Another Flow Block

Block config

Detailed behaviour

Example

Output Block

Block config

Detailed Behaviour

Example

Set Contact Property

Block config

set_contact_property array items

Detailed Behaviour

Example

Set Group Membership

Block config

groups array items

Detailed Behaviour

Example

Adding a Contact to a group:

Removing a Contact from all their existing groups:

Webhook Block

Block config

Detailed Behaviour

Example

Block `config`

Block `config`

Block `config`

Block `config`

Block `config`

`set_contact_property` array items

Block `config`

`groups` array items

Block `config`