Create Callback Actions¶

Introduction¶

The seal-co-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.

Hint - reliability

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

CALLBACK_NOTIFICATIONS_INTERVAL specifies the time after which the seal-co-notifier service will send previously failed callback notifications again.

Create a Callback Action¶

Hint - using Consul

The following example describes the creation of a callback action via SEAL PLOSSYS 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/co-notifier/tag/any/NOTIFICATION_CALLBACKS

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

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

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

Save the <filename>.yml file.

Re-import it to Consul.

plossys 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_JOB": [
    {
    "key": "status",
    "value": ".*",
    "action": "https://external.web.site.com/update?status={{{status}}}&jobId={{{jobId}}}&userId={{{userName}}}"
    "method": "GET"
    }
    ]
}
```

Optional¶

entireItem: boolean

false Default. Only essential object data (like jobId, jobName, userName) and changed object data (status) will be sent.

true The entire object (job) will be sent.
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 parameters action, value and headers entries can contain placeholders that will be replaced by the corresponding values of the job object.

Message Types¶

The supported message types are:

UPDATE_JOB

Configuration Examples¶

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

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

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

{
    "UPDATE_JOB": [
        {
            "action": "http://external.web.site.com/",
            "headers":
                {
                    "My-Header1": "Foo",
                    "My-Header2": "{{{status}}}"
                }
        }
    ]
}

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

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

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

Example - callback action using the GET method and using placeholders

{
    "UPDATE_JOB": [
        {
            "key": "status",
            "value": ".*",
            "action": "https://external.web.site.com/update?status={{{status}}}&JobId={{{jobId}}}&userId={{{userName}}}"
            "method": "GET"
        }
    ]
}

Example - callback action if a job status for a printer starting with hplaser is changed

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

Structure of Notification Messages¶

The structure of a notification message looks like this.

{
    source: '<Service Name>',
    type: '<Message Type>',
    parameters:
        {
            '<key-value pairs depending on the message type>'
        }
}

Example - UPDATE_JOB notification message

{
    source: 'co-notifier',
    type: 'UPDATE_JOB',
    parameters:
        {
            status: 'processed',
            jobId: 'b79a4d60-f34e-4435-b222-b47273f5c033',
            jobName: 'My Print Job',
            userName: 'user1'
        }
}