# Execute Button

# type: executeButton

With this Element a Workflow, a Production Line or a Function can be executed.

Execute-Button-Element

# Configuration Overview

{
  "type": "executeButton",
  "id": "execButton1",
  "config": {
    "endpoint": "TestEndpoint",
    "icon": "",
    "disabled": false,
    "label": "Execute Test Workflow",
    "messages": {
      "started": {
        "headline": "Started",
        "message": "Workflow was started"
      },
      "error": {
        "headline": "Error",
        "message": "Workflow returned an error"
      },
      "failed": {
        "headline": "Failed",
        "message": "Workflow execution failed"
      },
      "aborted": {
        "headline": "Aborted",
        "message": "Workflow execution was aborted"
      },
      "success": {
        "headline": "Success",
        "message": "Workflow execution was successful"
      },
      "hideAfterSeconds": 4,
      "disabled": false
    },
    "variablesToBeUpdated": [
      {
        "state": "STARTED",
        "name": "test_var1",
        "value": "New value"
      }
    ],
    "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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# Properties

# id

Property: id

Type: string

Description: The unique ID assigned to the Element.

"id": "execButton1"
1

# type

Property: type

Type: string

Description: The type of the Element.

"type": "executeButton"
1

# config

Property: config

Type: object

Description: The configuration of the Element.

"config": {
   "endpoint": "TestEndpoint",         // ID of the Endpoint
   "icon": "",                         // Button Icon -> default is a play button
   "label": "Execute Test Workflow"    // Label of the button
   "disabled": true | false           // Disable the Execute Button
    "disableExecuteButton": {          
      "untilFinished": true           // Disable the Execute Button until Workflow/Production Line is finished
      "forTime": 5                    // Disable the Execute Button for a specific amount of time
      },
 }
1
2
3
4
5
6
7
8
9
10

# config.messages

When executing a Function, a toast message is shown in the top-right corner. This message can be customized by defining messages for the different states of an execution in config.messages.

Property: config.messages

Type: object

Description: Configuration of the displayed execution messages. Each of the properties can be left empty as there are default values available.

{
  "started": {
    "headline": "Started", // Headline Text
    "message": "The execution was started successfully." // Message text
  },
  "success": {
    "headline": "Success",
    "message": "The execution successfully terminated."
  },
  "failed": {
    "headline": "Failed",
    "message": "The execution failed with an error."
  },
  "aborted": {
    "headline": "Aborted",
    "message": "The execution was aborted externally."
  },
  "error": {
    "headline": "Error",
    "message": "An error in the ONE DATA platform occurred before or after the actual execution, or the app configuration is invalid."
  },
  "hideAfterSeconds": 4,
  "disabled": false
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# config.messages.started

The above example shows how different messages and headlines can be defined depending on the state of the Endpoint execution. The various states are defined as:

Property: config.messages.started

Type: object

Description: Allows to customize the toast messages shown when the execution was started, e.g., when the execution of a Workflow (or Production Line) was successfully initialized by ONE DATA. Since Functions are intended to have a short run-time, no message is shown once they are started.

# config.messages.success

Property: config.messages.success

Type: object

Description: Allows to customize the toast messages shown when the execution successfully terminated.

# config.messages.failed

Property: config.messages.failed

Type: object

Description: Allows to customize the toast messages shown when the actual execution failed, e.g., because a Function threw an exception or an assertion in a Workflow failed.

# config.messages.aborted

Property: config.messages.aborted

Type: object

Description: Allows to customize the toast messages shown when the execution was aborted, e.g., because the Workflow Job was aborted in the Processing Library by another user. This does not apply to Functions.

# config.messages.error

Property: config.messages.error

Type: object

Description: Allows to customize the toast messages shown when the execution failed due to an error before or after the actual execution. The cause for this could be an error in the ONE DATA platform or an error in the Apps configuration.

# config.messages.hideAfterSeconds

Property: config.messages.hideAfterSeconds

Type: number

Description: The message will not be hidden after a certain amount of seconds by default and has to be closed by the Viewer. When this property is set, toast messages will auto-hide after the specified number of seconds. This can also be configured globally, see Global Messages.

{
  "hideAfterSeconds": 4,
}
1
2
3

# config.messages.disabled

Property: config.messages.disabled

Type: boolean

Description: Disables the config message altogether, hiding it from the Viewer. Defaults to false. This can also be configured globally, see Global Messages.

{
  "disabled": false,
}
1
2
3

# config.variablesToBeUpdated

Property: config.variablesToBeUpdated

Type: array

Description: Allows defining values for local (App) Variables that will be set on execution. If the "value" is omitted and a Function is used, the Function result will be written to the Variable. If one wants to reset a Variable on a Function FAILURE to a specific value, use the state "FAILED" and define a "value".

// Example for a Variable configured to be updated after a Workflow execution started.
"variablesToBeUpdated": [
    {
      "state": "STARTED",
      "name": "test_var1",
      "value": "New value"
    }
]
1
2
3
4
5
6
7
8
// Example for a Variable configured to receive the result of a Function after it finished and to be reset to an empty string if the Function fails.
"variablesToBeUpdated": [
    {
      "state": "SUCCESS",
      "name": "var_to_contain_result"
    },
    {
      "state": "FAILED",
      "name": "var_to_contain_result",
      "value": ""
    }
]
1
2
3
4
5
6
7
8
9
10
11
12

# config.variablesToBeUpdated.state

Property: config.variablesToBeUpdated.state

Type: string

Description: Defines the execution state at which the Variable value will be set. Possible values are "STARTED" (not available for Function Endpoints), "SUCCESS", "FAILED", "ABORTED" and "ERROR".

# config.variablesToBeUpdated.name

Property: config.variablesToBeUpdated.name

Type: string

Description: The name of the target Variable.

# config.variablesToBeUpdated.value

Property: config.variablesToBeUpdated.value

Type: should be the type of the target Variable

Description: The new value of the Variable.

# config.ShowSpecificErrorMessages

Property: config.showSpecificErrorMessages

Type: boolean

Description: Enable specific ONE DATA Error or Warning messages.

"showSpecificErrorMessages": true,
1

# config.disabled

Property: config.disabled

Type: boolean

Description: Property to disable the Execute Button.

"disabled": true,
1

# config.disableExecuteButton

The Execution Button can be disabled once clicked to prevent unintentional retriggering by the Viewer.

# config.disableExecuteButton.untilFinished

Property: config.disableExecuteButton.untilFinished

Type: boolean

Description: Property to disable the Execute Button until the Workflow / Production Line has finished.

"untilFinished": true,
1

# config.disableExecuteButton.forTime

Property: config.disableExecuteButton.forTime

Type: number

Description: Property to disable the Execution Button for the provided number of seconds after it was clicked. Floating point numbers such as 1.2 are also valid.

"forTime": 5 
1

# config.endpointParameters

Property: actions.endpointParameters

Type: array

Description: Used to pass values to an Endpoint execution.

"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

Endpoint Parameters will pass on data to Endpoint executions to work with. On an Execute Button, the properties value and valueFromVariable are allowed. valueFromColumns isn't possible.

See Endpoint Parameters for more information.

# Executing Functions with customizable messages

When triggering Endpoints of type function, additional possibilities for customizing Viewer-facing messages are available. This section explains additional possibilities for customizing the toast messages in both success and error cases.

The examples in this section assume that the following Python-function was already created in the Processing Library or Use Cases module of ONE DATA. It accepts a dictionary with a name field as parameter, validates that the name is not empty and returns an object containing a greeting.

# Python function at endpoint

def handle(req):
    # Get the function payload
    user = req['args']
    # Validate that a name is provided
    if 'name' not in user or not user['name']:
        raise Exception('No name was provided')
    # Generate and return the message
    return {
      'greeting': {
        'text': 'Welcome to Apps, %s!' % user['name']
      }
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Given this Function, a function endpoint can be defined and used for the Execute button. In this configuration, it is possible to customize the toast message shown to the Viewer using a value that is returned from the Function. The property messages.success.messagePath allows to specify a JSONPath expression pointing to any string value in the Functions return value which should be used as text for the toast. The following example shows how the greeting generated by the above Function can be shown to the Viewer when the Function was successfully executed.

"messages": {
  "success": {
    "headline": "Greetings",
    "messagePath": "greeting.text"
  }
}
1
2
3
4
5
6

Property: messages.success.messagePath

Type: string

Description: A JSONPath expression defining where to find the text of the message in the object returned by the Function. If this is omitted or the respective field does not exist in the Function response, the text from 'message' will be shown.

The above example did not yet consider error handling. By defining messages for messages.error (in case of an error of the ONE DATA platform) and messages.failed (in case the Function fails due to an exception) the text shown to the Viewer can be customized. In order to give the Viewer better feedback on what actually went wrong, it is possible to show the message of the exception that caused the Function to fail. This can be done by setting the property showSpecificErrorMessages to true. This will display the exception error message in the toast. In the above Function, an exception with a respective message is thrown if the provided name is empty. If showSpecificErrorMessages is set, a toast with the message "No name was provided" will be displayed, giving the Viewer a hint on what went wrong. Please note that the message of every exception will be displayed to the Viewer in this case, which may leak internal details or sensitive information. It thus is recommended to catch all exceptions in the Functions code and only rethrow those that are known to have a message that should be Viewer-facing (this is omitted in the above example for simplicity). The messages of any other error can be masked with a generic error message.