Hub Domain Specific Language (DSL)

The Hub DSL provides an implementation model for expressing digital onboarding solutions in a concise manner without superfluous details. Letting developers focus on the business logic. In addition to the main purpose Hub DSL supports these objectives:

enables transparent handling of failures,
facilitates working with data payloads, data mapping and transformation,
bridges the gap between developers and domain experts using a common language.

The Hub DSL provides the following features

Context attributes for storing and working with JSON-like data
DSL commands implement the basic building blocks of a digital onboarding
- route represents user interactions
- exchange makes external calls using connectors
- http makes external calls using connectors
- workflow executes child workflows
- function executes child functions
- mapper used for data mappings and transformations
- sharable generates and manages sharable links
- success / error / decision / response terminates the current execution
- logging for DSL logging
- Flow control commands allow for conditional execution
- Logging and metrics logging from DSL and support metrics events

DSL Commands

Route

A route represents an interaction with a user. Typically, the goal is to display route-specific information and gather input from the user. A route is rendered by a Hub Client as a web page or mobile app screen, depending on the Hub Client implementation. A route is identified by its name and can be used in a workflow definition. A minimal definition specifies a route uri intended for a Hub Client.

route('name') {
    uri '/uri'
}

Definition and usage

It is possible provide a route definition inline within a workflow definition.

worklfow('test') {
    route('name') {
        uri '/uri'
    }
}

Another option is to define a route as part of a Hub component and use it in a workflow by referencing the route name. This approach facilitates route reusability and separation of concerns.

route('name') {
    uri '/uri'
}

worklfow('test') {
    route('name')
}

Additionally, it is possible to reference a route by name and provide additional details when used in a workflow. This allows for separating a route definition (uri, data constrains) and usage (export, namespace, checkpoint).

route('client') {
    uri '/client'
    validate {
        firstname
        lastname
    }
}

worklfow('test') {
    route('client') {
        export documents
        namespace application.client
    }
}

Route Result

A route result is stored using a namespace attribute key.

route('client-info') {
  uri '/client-info'
  namespace client
}

If a validate block is specific, a route result is validated before storing the result and resuming the execution. The route submit request results in a validation error if the validation fails.

route('client-info') {
    uri '/client-info'
    namespace client
    validate {
      firstname
      lastname
      idFront { file 'image'}
    }
}

Exporting data

In order to pass route data, the export is used. Any JSON-like data can be exported, using context attributes or serializable values.

products << [product1: "Product1", product2: "Product2"]
route('products') {
    uri '/products'
    export products
}

route('greeting') {
    uri '/greeting'
    export message: "Hello world!"
}

Route check-point

A route can be marked as a check-point, meaning it is disabled to go back to the previous route.

route('finish') {
    uri '/finish'
    checkpoint()
}

Terminal route

A terminal route marks the end of a workflow execution. The corresponding execution is terminated when a terminal route is executed. Also, a terminal route is marked as a check-point.

route('finish') {
    uri '/finish'
    terminal()
}

In addition, it is possible to set an execution result payload using a terminal route.

route('finish') {
    uri '/finish'
    terminal(payload)
}

Route functions

A route function allows a Hub Client to execute functions in the context of the given route. A Hub client executes a route function via Hub Client API. Some use-cases of route functions:

dynamic queries based on user input, like auto-complete,
asynchronous data processing, like document OCR,
communication between different execution.

route('name') {
    uri '/uri'
    function('fnc1') {
      context initial
      namespace fnc1
    }
}

initial execution context for corresponding function execution
namespace stores the result of a route function execution

It is possible to specify one or more route functions. See route examples for more details.

Exchange

An exchange is a connector proxy. It makes external (API) calls using an HTTP connector or a custom connector. It provides the following tools for handling connector failures:

timeout, an exchange fails with an error if the connector does not respond within the specified timeout
retry strategy, retries failed connector requests

An exchange is executed asynchronously when marked with async().

HTTP connector

It is possible to use built-in HTTP connector to make external calls, see more details.

http {
  definition
}

Custom connector

Optionally, an exchange can use a custom connector with config.

exchange('name') {
  connector('custom')
  config input
}

Connector Development Guide For comprehensive guidance on developing custom connectors, see the Custom Connector Development Guide and Plugin Connector Development Guide.

Exchange Result

An exchange result is stored using a namespace attribute key.

http('localhost-api') {
    url "https://localhost:8080/api"
    namespace api
}

Result handlers

An exchange command can specify one on more result handlers

onError() executed when the result is error
onSuccess() executed when the result is success

In functions, each result handler can define an inline function that is executed when the handler condition is match. In workflows, each result handler can define an inline workflow. E.g. handling an exchange error in a workflow

exchange('idv') {
  connector 'idv'
}.onError {
    error ->
      route('error') {
        export error
      }
}

E.g. handling an exchange error in a function

exchange('idv') {
  connector 'idv'
}.onError {
  error ->
    function('store-error') {
      input error
      async()
    }
    error(it.message)
}

The built-in http connector provides additional handlers

onStatus(status) executed when response status code matches the given status, the response body is passed as input
onResponse() executed for any response, the response entity (headers, status, payload) is passed as input

E.g. handling an http responses

http {
  url "${url}/create"
  method 'POST'
  jsonBody request
}.onStatus(400) {
    match(it.header.code_error in [1108, 2001, 3001, 3020]) {
        decision('INCORECT_CPF', it)
    }
    error(it)
}.onResponse {
  match(it.status == 201) {
      success(it.headers.Location)
  }
  error(it.payload)
}

Exchange Timeout

It is possible to set an exchange timeout in seconds. The default value is 30 seconds. An exchange fails with an error if the underlying connector doesn’t respond within the specified timeout

exchange('status-api') {
  connector('custom')
  timeout 10
}

Exchange Retry strategies

An exchange uses a retry strategy to retry when a connector request fails. The default strategy uses fixed delays between retry attempts. The following retry strategies are available:

Fixed backoff

Uses fixed delays between retry attempts, given a number of retry attempts and the backoff delay in seconds.

retry a number of retry attempts, the default is 5
backoff a number of seconds between retries, the default is 5

exchange('fixed-default') {
    http {
      url config.api.url
    }
    fixedBackoffRetry()
}

exchange('fixed-custom') {
    http {
      url config.api.url
    }
    fixedBackoffRetry {
     retry 10
     backoff 2
    }
}

Exponential backoff

Uses a randomized exponential backoff strategy, given a number of retry attempts and minimum and maximux backoff delays in seconds.

retry a number of retry attempts, the default is 5
backoff a minimum delay between retry attempts, the default is 5
maxBackoff a maximum delay between retry attempts, the default is 50

exchange('exp-default') {
  http {
    url config.api.url
  }
  exponentialBackoffRetry()
}

exchange('exp-custom') {
    http {
      url config.api.url
    }
    exponentialBackoffRetry {
     retry 3
     backoff 5
     maxBackoff 10
    }
}

No retry

Does not retry when a connector request fails.

exchange('name') {
    http {
      url config.api.url
    }
    noRetry()
}

function

like workflow but without user interactions (route, workflow)
can be executed asynchronously
separate execution with different UUID, data passed using context and input

A function makes it possible to query dynamic data, perform complex calculations or make external calls using exhange(). Functions can be executed from a workflow or from another function.

name a function name
input a function input
context execution context for function execution
namespace a namespace to store function result
async() the function will be executed asynchronously

function('mobile.lookup') {
 input mobile: '325-135856984'
 context retry: 3
 namespace lookup
 async()
}

workflow

Executes a sub-workflow synchronously as a separate workflow execution with different UUID. Data is passed using context and input. Execution is terminated if sub-workflow terminates with terminal route.

name a workflow name
input a workflow input
context execution context for workflow execution
namespace a namespace to store workflow result

workflow('otp') {
 input mobile: '325-135856984'
 context retry: 3
 namespace otp
}

mapper

An attribute mapper transforms an input into an attribute output using mapper expression, see Mapper. The output gets stored in a namespace if specified. Can be used for data transformations, calculations and providing default values etc.

mapper('name') {
  input input
  namespace namespace
}

path

Executes a path (workflow snippet) specified by a name. A path is executed as part of the current execution and shares the same execution context. It is only possible to reference a path defined within the same component as a workflow being executed.

path 'name'

Execution result

There are several ways of terminating an execution and specifying an execution result

success() for a success result with payload
error() for an error result with payload
decision() for a success result with a decision and payload
response for exposed function response
the result of the last command or expression

Terminates an execution successfully with a payload

success(application)
success firstName: checkIdp.firstName, lastName: checkIdp.lastName

or with an empty payload

success()

Terminates an execution with an error using the specified payload

error "Boom"
error otp

or with an empty error payload

error()

If more granularity in needed, it is possible to terminate an execution successfully using decision(). Terminates an execution successfully with a decision and payload

decision('ACCEPTED', idp)

or with an empty error payload

decision('DENIED')

Exposed function response

Exposed functions can specify an HTTP response details, including body, headers and status code.

response {
    status HttpStatus.ACCEPTED
    header HttpHeaders.LOCATION, 'http://localhost'
    body payload
}

response {
    status 201
    header 'location', "http://localhost"
    header 'x-correlation-id', "345lkigzdf90234as"
}

Execution result handlers

Each function and workflow command can specify one on more result handlers

onError() executed when the result is error
onSuccess() executed when the result is success or any decision
onDecision() executed when the result is a given decision

Only the first matching handler is executed. When a handler is executed, the result payload is passed as an input. E.g. handling a workflow error

workflow('idv')
    .onError {
      error ->
        route('error') {
          export error
        }
    }

E.g. handling a workflow decision result

workfow('liveness')
    .onDecision('LIVE') {
      payload ->
        workflow('payment') {
          input payload
        }
    }
    .onSuccess {
        workflow('try-again')
    }
    .onError {
      error ->
        route('error') {
          export error
        }
    }

sharable

Generates a sharable token or a link with the token. A sharable token can be used for starting a new workflow or function execution. It is possible to specifies a sharable token manually. Otherwise, it is generated as 6 random alpha numerical characters.

For comprehensive documentation on sharables including use cases, integration patterns, and API reference, see the Sharables Guide

A token expires when a corresponding execution is terminated, unless the token is marked as reusable().

url if provided generates a link using the sharable token
payload an attribute/payload to be shared
function a name of function to execute, optionally execution input and context can be provided
workflow a name of workflow to execute, optionally execution input and context can be provided
latest() a workflow or function reference revision is resolved when sharable token is used (rather than fixed)
expired() expires specified token
reusable() the token does not expire after corresponding execution terminates
namespace asynchronously stores the function or workflow execution result
expireIn token will expire after specified duration (use ISO-8601 duration format, default is 24 hours)

Examples of usage are following:

token << sharable { function 'function-name' }

sharable {
   reusable()
   function 'function-name'
   namespace result
}

Generates a sharable token to execute a function named function-name. The token gets stored in the token namespace.

link << sharable {
   url "http://localhost:1234/sharable/$token"
   workflow('workflow-name') {
      context url: 'http://localhost'
      input userId: 'dummy123'
   }
   expireIn 'PT30M'
}

Generates a sharable link to execute a workflow named workflow-name with input and context. The link gets stored in the link namespace. The link will expire in 30 minutes.

sharable(input.token) {
   payload application
}

Generates a sharable payload that stores application attribute and can be accessed using input.token token.

sharable('vJRRTX') {
   expired()
}

Expires a specific sharable token.

sharable(execution.sharable) {
   expired()
}

Expires a sharable token that was used to execute the current execution.

Exporting namespaces

A context attribute namespace can be exported and queried using Execution API

export config

Logging

It is possible to generate application logs from the DSL using the log command

log "message"

The log message is logged using com.zenoo.hub.dsl.executor.DSLLogger class with the following format

{uuid}: DSL logger {executable}: {message}

Example: a log message using context attributes

log "request.id=${request.request_id}"

Flow control

await

Blocks the current execution and waits until an attribute is set, e.g. by an asynchronous function, exchange or sharable token.

await attribute

match

Executes a DSL script definition when an expression evaluates as true. The expression can contain context attributes.

match (expression) {
    definition
}

exist

Executes a DSL script definition when an attribute is set.

exist (attribute) {
    definition
}

switch / case

The switch statement matches expression with cases and executes the matching case. It’s a fallthrough switch-case. You can share the same code for multiple matches or use the break command. It uses different kinds of matching like, collection case, regular expression case, closure case and equals case.

switch (expression) {
    case "bar":
        route "Bar"
        break

    case ~/fo*/:
        route "Foo"
        break

    case [4, 5, 6, 'inList']:
        route "Matched"
        break

    default:
        route "Default"
}

loop-until

Executes a DSL script definition until an expression evaluates as true.

loop {
    definition
} until { expression }

The maximum number of attempts can be specified.

loop(3) {
  workflow
} until { expression }

In addition, the attempt counter can be accessed as follows:

loop(3) {
  attempt ->
    route('test') {
      export attempt
    }
} until { expression }

Logging and metrics

Logging

It is possible to produce logging messages in the DSL for the purpose of tracking and trouble-shooting. The logging messages are logged as DEBUG messages via com.zenoo.hub.dsl.executor.DSLLogger. In addition, the log messages are stored as part of execution events.

log "Request ID:${response.id}"

Metrics

You can use the following commands in order for tracking visited interactions and their outputs.

interactionStart(String id, Map<String, String> tags)
interactionOutput(String id, String output, Map<String, String> tags)

e.g.

interactionStart('x23vzt5', [ uri: 'welcome', type: 'PageInteraction', name: 'Welcome page one' ])
interactionOutput('x23vzt5', 'default', [ uri: 'welcome', type: 'PageInteraction', name: 'Welcome page one' ])

Meters

You can use the meter command to record named measurements with numeric values. Meters are useful for tracking usage, billing, and custom metrics. The execution context UUID is automatically included in the event.

meter(String name, Number value, Map<String, String> tags)
meter(String name, Number value)
meter(String name)

The value defaults to 1 and tags defaults to an empty map when omitted. e.g.

meter('api-calls')                                                          // counter: value=1, no tags
meter('data-transferred', 2048.5)                                           // value without tags
meter('api-calls', 1, [ type: 'ApiUsage', name: 'External API Calls' ])    // full form with tags
meter('loan-value', 15000.00, [ type: 'LoanMetric', currency: 'USD' ])

​Hub Domain Specific Language (DSL)

​DSL Commands

​Route

​Definition and usage

​Route Result

​Exporting data

​Route check-point

​Terminal route

​Route functions

​Exchange

​HTTP connector

​Custom connector

​Exchange Result

​Result handlers

​Exchange Timeout

​Exchange Retry strategies

Fixed backoff

Exponential backoff

No retry

​function

​workflow

​mapper

​path

​Execution result

​Exposed function response

​Execution result handlers

​sharable

​Exporting namespaces

​Logging

​Flow control

​await

​match

​exist

​switch / case

​loop-until

​Logging and metrics

​Logging

​Metrics

​Meters

Hub Domain Specific Language (DSL)

DSL Commands

Route

Definition and usage

Route Result

Exporting data

Route check-point

Terminal route

Route functions

Exchange

HTTP connector

Custom connector

Exchange Result

Result handlers

Exchange Timeout

Exchange Retry strategies

function

workflow

mapper

path

Execution result

Exposed function response

Execution result handlers

sharable

Exporting namespaces

Logging

Flow control

await

match

exist

switch / case

loop-until

Logging and metrics

Logging

Metrics

Meters