Skip to main content

Documentation Index

Fetch the complete documentation index at: https://platform.docs.zenoo.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
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' ])