# Endpoints

Endpoints are interfaces to executable ONE DATA resources - such as Workflows, Production Lines or Functions. They can be invoked based on an event, such as a button click. These resources are defined in the Processing Library and can afterwards be used in Apps. This article provides information about the different Endpoint types that are available and shows their usage.

# Configuration Overview

{
  "endpoints": [
    {
      "id": "TestEndpoint",
      "type": "workflow",
      "async": true,
      "config": {
        "workflowId": "275405f6-9371-4829-8049-3d64751021eb",
        "projectId": "2b8398b6-8489-464a-b9cb-97919ea127f2",
        "version": 1,
        "endpointParameters": [
          {
            "name": "variable_27S",
            "type": "STRING",
            "value": "Test Value"
          },
          {
            "name": "variable_28S",
            "type": "STRING",
            "valueFromVariable": "test_variable"
          }
        ]
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

variableAssignments deprecated

variableAssignments have been deprecated in favour of endpointParameters. Read more about it below.

# Properties

# id

Property: id

Type: string

Description: The unique ID assigned to the Endpoint.

"id": "TestEndpoint",
1

# type

Property: type

Type: string

Description: The type of the Endpoint. Available types are workflow, productionLine and function.

"type": "workflow"
1

# async

Property: async

Type: boolean

Description: Defines the way the data will be updated. The data update callback is currently available only for FRTs.

"async": true,
1

# Config for Workflows

Property: config

Type: object

Description: The configuration of the Endpoint version must be set to the current App version ( can be found in the URL "...versionNumber=3..." ). If no version is provided the latest version will be executed.

Usage of target project ID for Workflow execution

Workflow Endpoint configuration allows setting the projectId. This may be necessary in some cases. More information on when and why it should be set can be found here.

"config": {
    "workflowId": "",           // Workflow ID.
    "projectId": "",            // Project ID.
    "version": 0,               // (Optional) Version of the Workflow to execute.
    "endpointParameters": [     // List of parameters.
      {
        "name": "variable_27S", // (Technical) Name of the Variable.
        "type": "STRING",       // Type of the Variable.
        "value": "Test Value"   // Value of the Variable.
      }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12

# Config for Production Lines

Property: config

Type: object

Description: TThe configuration of the Endpoint version must be set to the current App version ( can be found in the URL "...versionNumber=3..." ). If no version is provided the latest version will be executed.

"config": {
    "productionLineId": "",     // Production Line ID.
    "version": 0,               // (Optional) Version of the Production Line to execute.
    "endpointParameters": [     // List of parameters.
      {
        "name": "variable_27S", // (Technical) Name of the Variable.
        "type": "STRING",       // Type of the Variable.
        "value": "Test Value"   // Value of the Variable.
      }
    ]
}
1
2
3
4
5
6
7
8
9
10
11

# Config for Functions

With Functions, it is possible to implement complex logic in simple, single-purpose units that can be invoked by the App. They can, for example, be used to communicate with external services or execute short-lived, logically complex computations. Functions can be created in the Processing Library or Use Cases module of ONE DATA and can be currently written in Python. This section shows how Functions can be defined as an Endpoint in Apps. For information on how to trigger a Function endpoint and how to use it to customize user-facing messages, read on here.

In order to define an Endpoint for a Function, create an Endpoint with "type": "function". Its config can look like this:

"config": {
    "functionId": "f7969880-70e9-4a76-8216-9f2ba05b09e8",
    "payload": {
      "input": {
        "name": "",
        "$name": {
          "value": "{{user_name}}"
        }
      }
    },
    "datasourceToBePopulated": {
      "datasourceId": "my_dynamic_datasource",
      "dataPath": "results.data",
      "tableSchemaPath": "results.schema"
    },
    "endpointParameters": [         // List of parameters. 
        {
            "name": "variable_27S", // (Technical) Name of the Variable.
            "type": "STRING",       // Type of the Variable.
            "value": "Test Value"   // Value of the Variable.
        }
    ]
  }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

The payload.input defines the argument that should be passed to the Function as argument. Parts of the input can be parameterized with variables to make the invocation dynamic based on the Apps state. In the above example, the Variable user_name is used as value of the field name of the Functions input object. The Function can be called with the resulting object by calling it via an execute button.

The configuration options relevant in this example are:

# config.functionId

Property: functionId

Type: string

Description: The ID of the Function that should be invoked via the Endpoint.

# config.payload.input

Property: payload.input

Type: any

Description: The argument that should be passed to the Function. It can be of any type (object, string, number, ...) and may be omitted if the Function does not expect parameters.

# config.datasourceToBePopulated

Description: An optional configuration to populate a datasource with parts of the function result payload.

# config.datasourceToBePopulated.datasourceId

Property: datasourceId

Type: string

Description: The id of a dynamic datasource to be populated.

The results of a FAAS-function can be used to populate a dynamic datasource. This property links the endpoint to the datasource. The datasource origin must be set to "dynamic".#### config.datasourceToBePopulated

Description: An optional configuration to populate a datasource with parts of the function result payload.

# config.datasourceToBePopulated.dataPath

Property: dataPath

Type: string

Description: A JSON path that specifies the location of the data to populate the datasource.

The results of a FAAS-function must be returned in a JSON object. This property specifies the location of the data to populate the datasource.

# config.datasourceToBePopulated.dataPath

Property: tableSchemaPath

Type: string

Description: A JSON path that specifies the location of the table schema to override the datasource's table schema.

The results of a FAAS-function must be returned in a JSON object. This property specifies the location of the new table schema to override the original schema.

# config.endpointParameters

Endpoint parameters allow to send data from the App to a Function, Workflow or Production Line execution. There are a few handy ways how to gather different information from the App and pass them on.

"endpointParameters": [
    {
        "name": "variable_27S",
        "type": "STRING",       
        "value": "Test Value"   // The value of the Variable.
    },
    {
        "name": "variable_28S", 
        "type": "STRING",       
        "valueFromVariable": "test_var1"   // The Variable that refers to the defined Variable or system Variable.
    },
    {
        "name": "variable_29S",
        "type": "STRING",
        "valueFromColumn": "Country"   // The column name on a Table, only works with actions within the Table.
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

The following python script represents a small usage example of endpointParameters. The script

  1. validates that the params are set (that is taken care of by apps itself, you do not need to worry),
  2. validates that at least one endpointParameter is set, and
  3. returns the value of the endpointParameter
def handle(req):

    request_args = req['args']
    
    # Validate that the params have been set
    if 'params' not in request_args or not request_args['params']:
        raise Exception('No idea how you did that, but we need params here')
        
    endpoint_parameters = request_args['params']

    # Validate that at least one endpointParameter is set
    if not endpoint_parameters[0] or not endpoint_parameters[0]['value']:
        raise Exception('You need to supply at least one endpointParameter')
        
    # Return the received value of the first endpointParameter
    return endpoint_parameters[0]['value']
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# config.endpointParameters.type

Property: type

Type: string

Description: Specifies the type of the Variable passed to the target Endpoint.

These types map directly to the types in the ONE DATA Variable Manager.
In addition to the standard types, Endpoints also support:

  • Dataset: a UUID string to identify a Dataset. (Data Table in ONE DATA)
  • TIMESTAMPS: a string adhering to the ISO-8601 standard. (DateTime in ONE DATA)

# config.endpointParameters.value

Property: value

Type: string | number | boolean | null

Description: Specifies the value of the Variable passed to the target Endpoint.

The given value is always parsed according to the specified type. For example, the string value "true" is valid for a Variable of the type boolean, because the value will be parsed as boolean.

Independent of the type of the Variable, the values null, "null" or "" are passed to the Endpoint as empty.

# config.endpointParameters.valueFromVariable

Property: valueFromVariable

Type: string

Description: Inserts the current value for the Variable defined in the Variables and System Variables.

See Variables and System Variables for more information how variables work.

Null values

If the value of the Variable is null or empty, the assignment will not be passed to the Endpoint at all!

value from Variable object

It is possible to traverse an object with valueFromVariable.

For example, if the Global Variable is defined as the following one can use "valueFromVariable": "recipe.ingredients[0] to get flour as the Variable to pass on.

"variables": [
  {
      "name": "recipe",
      "type": "object",
      "default": {
          "name": "bread",
          "ingredients": ["flour", "yeast", "sugar", "butter"]
      }
  }
]
1
2
3
4
5
6
7
8
9
10

# config.endpointParameters.valueFromColumn

Property: valueFromColumn

Type: string

Description: Inserts the value that is present in a Table column into an Endpoint execution. The column which contains the values does not need to be shown in the Table but needs to be selected via, for example, SQL.

It is advised, but not required to define valueFromColumn Endpoint parameters at the action where it's executed. See the Table column actions for an example.

# config.variableAssignments deprecated

variableAssignments (deprecated)

variableAssignments are replaced by endpointParameters. For legacy purposes, variableAssignments are still available but will be removed in 2022.

"variableAssignments": [
    {
        "variableName": "user_name",      // Technical Variable name.
        "variableType": "STRING",         // Variable value type.
        "variableValueColumn": "Name"     // Column in the Table Element in which the value is present that should be passed to ONE DATA.
    },
    {
        "variableName": "user_role",      // Technical Variable name.
        "variableType": "STRING",         // Variable value type.
        "variableValue": "app_client"     // The defined Variable value.
    },
1
2
3
4
5
6
7
8
9
10
11