Actions app

Scope of functions

The Actions app gathers together the actions from all purchased/registered apps and makes them available to other apps from a central location.

Providing actions

To provide your app’s actions via the Actions app, your app must deliver an actions link relation when the base address is called.

Request

GET /myapp
Accept: application/hal+json

Response

{
  "_links": {
    ...
    "actions": {
      "href": "/<app name>/actions"
    },
    ...
  },
  ...
}

You can call the URI specified in the link relation with the GET request method and the request header Accept: application/hal+json. When the link relation is called, a JSON object with a list of action definitions is expected. The JSON object must have the structure described below.

Action definition for provided actions

Use the following structure to construct the JSON object that offers actions from other apps:

{
  "actions": [
    {
      "id": string <id of your action>, //Mandatory
      "display_name": map[string]string <display name of the action - multilangual>, //Mandatory
      "tags": map[string][]string <tags to describe the action - multilangual>,
      "description": map[string]string <description of the action - multilangual>, //Mandatory
      "endpoint": string <url for the execution of the action>, //Mandatory
      "deprecation" :
      {
        "description": map[string]string <description of the deprecation - multilangual>, //Mandatory, if deprecation is filled at all
        "url": string <url to further information>,
        "alternative_action_id": string <id of an alternative action>,
        "terminated_on": string <date when the termination becomes effective> //The timestamp must be a quoted string in the RFC 3339 format
      },
      "execution_mode": enum[string] <type of execution>, //Mandatory; Values: Synchron, Asynchron_callback, currently only Synchron is supported
      "volatile": boolean, //Optional, defaults to false
      "input_properties": [ //Optional, if included some values are mandatory
      {
        "id": <id of your property>, //Mandatory
        "type": enum[string] <type of your property>, //Mandatory; String, Date, DateTime, Base64Blob, Int64, Double, Boolean, Object => + []*
        "title": map[string]string <title of your property>, //Mandatory
        "description":map[string] <description of your property>, //Mandatory
        "required": boolean <indicates whether the specification is required>, //Optional, defaults to false
        "visibility": enum[string] <visibility of the property>, //Optional, defaults to Standard; Standard,Advanced
        "initial_value": native type <initial value of your property>,
        "object_properties": <array of input_properties, if the type object or []object is used>,
        "fixed_value_set": [
          {
            "value": string <value of the fixed value>,
            "display_name": map[string]string <display name of the fixed value - multilangual>
          },
          {...}
        ] <array of fixed value set> ,
        "data_query_url": string <url for dynamic value set requests>,
        "data_query_parameter": map[string] string <query parameter for the data_query_url>
      },
      {...}
    ],
    "output_properties": [
      {
        "id": string <id of your property>, //Mandatory
        "type": enum[string] <type of your property>, //Mandatory; String, Date, DateTime, Base64Blob, Int64, Double, Boolean, Object => + []*
        "title": map[string]<title of your property>, //Mandatory
        "description": map[string]string <description of your property>, //Mandatory
        "object_properties": <array of output_properties, if the type object or []object is used>,
      },
      {...}
    ]
  },
    {...}
  ]
}

info: To make d.velop cloud as smooth for users as possible, querying of the action and the dynamic value sets should take place in a few milliseconds if possible, but in a maximum of three seconds.

Expected behavior of the endpoint

You can call the endpoint to perform an action as follows:

Request In the body, enter an object corresponding to the input_properties described in the action definition.

POST <endpoint>
Content-Type: application/json
Accept: application/hal+json

  {
    <input_properties>
  }

• The endpoint must respond with a status code between 200 and 299 if successful.
• If the endpoint is called without having logged in or if the login is invalid, the endpoint must respond with the status code 401.
• If the user making the call lacks the necessary permissions, the endpoint must answer the request with 403.

Lifetime of actions

The app distinguishes between two basic types of action: volatile and stable actions.

Volatile actions

Volatile actions are created dynamically with different user interfaces. For example, you can provide scripts as an action. The important thing here is that the customer must ensure that the action is available. Discontinuations of volatile actions are not explicitly announced. You can recognize volatile actions by the fact that the value for volatile in the action description is true.

Stable actions

Actions provided by d.velop products are kept stable over a long period of time. Stable actions are considered public user interfaces and follow the same discontinuation process. You can recognize stable actions by the fact that the value for volatile in the action description is false.

Reserved input parameters

In general, you are free to choose the input parameter. However, the Actions app reserves the identifier dv_actions_app for technical reasons.

Dynamic value sets

You can use dynamic value sets for the input parameter. For dynamic value sets, enter a URL in the data_query_url parameter and, if necessary, add defined query parameters (see Parameters for dynamic value sets)).

When this URL is called, a response in the format FixedValueSet is expected. The value display_value should follow the language of the user context.

Request

GET <data_query_url>(?<data_query_parameter>)
Accept: application/hal+json

Response

//FixedValueSet
[
  {
    "value": "value1", //string
    "display_name": "displayName" //string
  },
  ...
]

Parameters for dynamic value sets

If the URL call expects query parameters for determining the dynamic value set, you can define these parameters in the data_query_parameter parameter.

You can define fixed values in order to offer different value sets via a single route, for example. You can also enter placeholders in the format {$input_parameter_id} to make a value set dependent on other input parameters.

  {
    "parameter1": "ParameterWert1",
    "parameter2": "{$input_parameter_id}" 
  }

Retrieving actions

To retrieve all available actions, execute the following query:

Request

GET /actions/api/actions
Accept: application/json
Accept-Language: de

The JSON object in the response contains a list of all available actions with the following structure:

{
  "actions": [
    {
      "id": string <id of the action, includes appname>,//Mandatory
      "display_name": string <display name of the action>,//Mandatory
      "tags": []string <tags to describe the action >,
      "description": string <description of the action>,//Mandatory
      "endpoint": string <url for the execution of the action>,//Mandatory
      "deprecation":
      {
        "description": string <description of the deprecation>,//Mandatory, if deprecation is filled at all
        "url": string <url to further information>,
        "alternative_action_id": string <id of an alternative action>,
        "terminated_on": string <date when the termination becomes effective> // The timestamp must be a quoted string in the RFC 3339 format
      },
      "execution_mode": enum[string] <type of execution>, //Mandatory. Values: Synchron, Asynchron_callback, currently only synchron is supported
      "volatile": boolean, //Optional, defaults to false
      "input_properties": [ //Optional, if included some values are mandatory
      {
        "id": <id of your property>,//Mandatory
        "type": enum[string] <type of your property>, //Mandatory String, Date, DateTime, Base64Blob, Int64, Double, Boolean, Object => + []*
        "title": string <title of your property>,//Mandatory
        "description":string <description of your property>,
        "required": boolean <indicates whether the specification is required>,//Optional, defaults to false
        "visibility": enum[string] <visibility of the property>, //Optional, defaults to Standard. Standard,Advanced
        "initial_value": native type <initial value of your property>,
        "object_properties": <array of input_properties, if the type object or []object is used>,
        "fixed_value_set": [
        {
          "value": string <key of the fixed value>,
          "display_name": string <display name of the fixed value>
        },
        {...}
      ] <array of fixed value set> ,
      "data_query_url": string <url for dynamic value set requests>,
      "data_query_parameter": map[string] string <query parameter for the data_query_url>
      },
      {...}
    ],
    "output_properties": [
      {
        "id": string <id of your property>,//Mandatory
        "type": enum[string] <type of your property>, //Mandatory. String, Date, DateTime, Base64Blob, Int64, Double, Boolean, Object => + []*
        "title": string <title of your property>,//Mandatory
        "description": string <description of your property>,
        "object_properties": <array of output_properties, if the type object or []object is used>,
      },
      {...}
    ]
  },
    {...}
  ]
}

Updating actions

From time to time, it may be necessary to update the list of actions, e.g. if you have provided a new action.

• In the cloud, updating is limited to five calls within one hour. This is based on the oldest of the five calls.
• On local systems, the number of updates is unlimited.

Update the actions using the following request:

Request

POST /actions/api/actions/refresh
Content-Type: application/json

If the update is successful, you receive a response with the status code 204. If the five call limit has been exceeded in the cloud, you receive a response with the status code 429 and a Retry-After header containing the time of the next possible update.

Executing actions

To execute an action, use the following request:

POST <endpoint>
Content-Type: application/json
Accept: application/hal+json

  {
    <input_properties>
  }

The request text must match the action definition of the input_properties property. It is forwarded to the action to be performed. It is not checked for correctness.

• If an error occurs in the Actions app that was not triggered by the action destination, the header x-dv-action-app-response is always returned with the value true. The listed errors only apply if the value is true; otherwise, consult the error description from the action providers.
• If the action could not be found, the request returns the status code 404.
• If the action has been discontinued and the discontinuation date is in the past, the request returns the status code 410.
• If an internal error occurs when calling the destination address, the request returns the status code 500.
• In all other cases, the response of the action is forwarded.

Determining dynamic value sets

Input parameters with a data_query_url property contain dynamic value sets. If further query parameters are required to query the value set, they are listed in the data_query_parameter parameter. The listed request parameters can be both parameters with fixed values and parameters whose placeholders (format: {$input_parameter_id}) must be replaced by the value of the named input parameter.

Example

An input parameter for color codes is to receive a dynamic value set from a pre-selected theme. Since multiple dynamic value sets are offered via one URL, a request parameter is expected that specifies the type of value set queried. The definition of the input parameters looks as follows:

  ...
  "input_properties" : [
    {
       "id": "theme",
       "type": "string",
       "fixed_value_set": [{value:"dark", display_name: {"de":"dunkel", "en":"dark"}}, {value:"light", display_name: {"de":"hell", "en":"light"}}],
       ...
    },
      "id": "primary_color_code",
      "type": "string",
      "data_query_url" : "<baseUri>/myAction/dynamicvalues",
      "data_query_parameter" :
      {
        "type": "colors",
        "theme": "{$theme}"
      },
    },
    ...
  ], 
...

When selecting the dark theme in this example, use the following request to query the dynamic value set:

Request

GET <baseUri>/myAction/dynamicvalues?type=colors&theme=dark
Content-Type: application/json
Accept-Language: en

Response The query of the dynamic value set returns a response in the translated format FixedValueSet.

//FixedValueSet
[
  {
    "value": "#121212",
    "display_name": "Dark gray" 
  },
  {
    "value": "#000000",
    "display_name": "Black"
  },
  ...
]

Translation code

The translation code must match the “language code” or the “primary language subtag” (see https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.1). Examples: “de”, “en”, “nl”