Create Callback Actions¶

Introduction¶

The seal-operator-notifier service listens for notifications at the NATS message broker. The environment key NOTIFICATION_CALLBACKS specifies the criteria for which message types callback actions will be executed. At the current state, only callback URLs are implemented.

The value of NOTIFICATION_CALLBACKS is a JSON string containing for every message type of interest an array of callback actions.

Reliability

If a callback can't be executed because of network failures for example, it will be scheduled for a later execution until successful.

Create a Callback Action¶

Using Consul

The following example describes the creation of a callback action via SEAL Operator CLI. Due to the complex nature of the NOTIFICATION_CALLBACKS key, it might be better to use Consul instead. In Consul, the key is specified here. If the key does not exist yet, you have to create it: dc/home/env/service/operator-notifier/tag/any/NOTIFICATION_CALLBACKS

Open a Command Prompt or PowerShell. the
Export the complete configuration of SEAL Operator from Consul to a YAML file with the following command. So you're making sure current configuration settings are being used.
```
operator config export <filename>.yml --insecure
```
Edit the exported file .yml.

In the env section, specify the key NOTIFICATION_CALLBACKS for the operator-notifier service:

...
env:
  service:
    operator-notifier:
      tag:
        any:
          NOTIFICATION_CALLBACKS: |
            {
              "UPDATE_TASK": [
              {
                "action": "http://external.web.site.com/"
              }
              ]
            }
...

Save the <filename>.yml file.

Re-import it to Consul.

operator config import <filename>.yml --insecure

Action Parameters¶

Every action has the following parameters:

Mandatory¶

action: string

Mandatory, contains the callback URI. If the specified protocoll is a valid URL protocoll like http or https, the specified callback URI will be taken as a URL and a POST request will be generated per default. If another HTTP request method like GET, PUT or PATCH should be used instead, the method parameter has to be set as well. The notification message will be sent as request body (as long as the request method is not GET). The URL can contain placeholders that will be replaced by message parameters. For further information, which message parameters are available, refer to Structure of Notification Messages.
Example - callback action via GET method
```
{
"UPDATE_TASK": [
    {
    "key": "status",
    "value": ".*",
    "action": "https://external.web.site.com/update?status={{{parameters.status}}}&taskId={{{scope}}}&userId={{{sub}}}"
    "method": "GET"
    }
    ]
}
```

Optional¶

entireItem: boolean

false Default. Only essential message data (like scope, source, sub) and changed object data will be sent.

true The entire object (task, document) will be sent.

Hint

Many message types, like UPDATE_TASK, UPDATE_DOCUMENT, contain only essential message data and changed parameters of the object. If all parameters of the object should be sent or if unchanged object parameters have to be used in placeholders, entireItem has to be set to true.
key: string

A specific parameter key that has to be contained in the data object, f.e. status. Only in combination with the value parameter.
value: string

Specific parameter value, that has to be set as value for the specified key parameter. Can be a regular expression, f.e. .*p402.*.
method: string

HTTP request method to be used, default: POST.
headers: JSON object

Additional HTTP headers to be sent with the request. The header values can contain placeholders that will be replaced by message parameters.

Message Types¶

The supported message types are:

ADD_TASK
UPDATE_TASK
REMOVE_TASK
UPDATE_DOCUMENT

Configuration Examples¶

Example - for every UPDATE_TASK event a POST request is sent to an external URL

{
"UPDATE_TASK": [
    {
    "action": "http://external.web.site.com/"
    }
    ]
}

Example - for every UPDATE_TASK event a POST request with additional headers is sent to an external URL

{
"UPDATE_TASK": [
    {
    "action": "http://external.web.site.com/",
    "headers": {
        "My-Header1": "Foo",


        "My-Header2": "{{{parameters.status}}}"
    }
    }
    ]
}

Example - depending on the task status in an UPDATE_TASK event a POST request is sent to a specific external URL

{
"UPDATE_TASK": [
    {
    "key": "status",
    "value": "processing",
    "action": "http://external.web.site.com/running"
    },
    {
    "key": "status",
    "value": "completed",
    "action": "http://external.web.site.com/success"
    },
    {
    "key": "status",
    "value": "failed",
    "action": "http://external.web.site.com/error",
    "entireItem": true
    }
    ]
}

Only in case of a failed task the usage of entireItem causes the entire task data to be sent.

Example of a callback action using the GET method and using placeholders

{
"UPDATE_TASK": [
    {
    "key": "status",
    "value": ".*",
    "action": "https://external.web.site.com/update?status={{{parameters.status}}}&taskId={{{scope}}}&userId={{{sub}}}"
    "method": "GET"
    }
    ]
}

Example of a callback action if a task for a printer starting with hplaser is added

{
"ADD_TASK": [
    {
    "key": "metadata.Printer",
    "value": "hplaser.*",
    "action": "http://external.web.site.com/huhu"
    }
    ]
}

For a complete list of parameters included in an ADD_TASK notification message, refer to the examples in the Structure of Notification Messages section.

Structure of Notification Messages¶

The structure of a notification message looks like this.

{
    source: '<service name>',
    type: '<message type>',
    scope: '<object ID within the Operator>',
    sub: '<user ID = subject in JWT>',
    parameters: {
    '<key-value pairs depending on the message type>'
    }
}

Example of an ADD_TASK notification message

{
    type: 'ADD_TASK',
    scope: 'b2dab4b2-cf47-4499-9320-610d6118f2e4',
    source: 'operator-p4',
    sub: 'ea5f9786-04e5-4a3d-b4f1-d4544e400f6d',
    parameters: {
        metadata: {
            Capabilities: { Color: true, Format: true, Duplex: true, TrayFormats: { oneOf: [] } },
            Printer: 'hp402-3011@Ouoi',
            Duplex: 'NONE',
            Quality: 'NORMAL',
            Color: 'gray',
            Copies: 1,
            Format: 'undefined',
            dirty: ['dirty'],
            PLS_FOLD_TYPE: 'undefined',
            PLS_PUNCH_TYPE: 'undefined',
            PLS_SORT_TYPE: 'undefined',
            PLS_STAPLE_TYPE: 'undefined',
            PLS_SCALE_TYPE: 'undefined'
            },
        name: 'PLOSSYS 4',
        type: 'print',
        tid: 'b2dab4b2-cf47-4499-9320-610d6118f2e4',
        sid: 'operator-p4',
        created: 1688732877737,
        status: 'open',
        runtime: {},
        links: { self: { href: '/v1/services/operator-p4/tasks/b2dab4b2-cf47-4499-9320-610d6118f2e4' } },
        inputListLength: 1,
        outputListLength: 0
    }
}

Example of an UPDATE_TASK notification message

{
    type: 'UPDATE_TASK',
    scope: 'b2dab4b2-cf47-4499-9320-610d6118f2e4',
    source: 'operator-p4',
    sub: 'ea5f9786-04e5-4a3d-b4f1-d4544e400f6d',
    parameters: {
        tid: 'b2dab4b2-cf47-4499-9320-610d6118f2e4',
        status: 'failed',
        finished: 1688733087807
    }
}

Handle Failing Callback Actions¶

If a callback action fails (network outages, callback server outages ...) the callback action is postponed for 30 seconds and then executed again. Within these 30 seconds other waiting callback actions are executed. This is done until the callback action finally succeeds. This default behaviour is adjustable by these environment variables: