4.8 Subscriptions and Status Callback

Updated on Oct 18, 2023

1. Quick Overview

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

The Workflow Subscribers and Subscriptions allows to send status updates for certain entities from Durst Workflow to any external system. Durst Workflow sends a callback including Payload to any http/https capable Webhook. The included information can be parsed and used for further automation processes, or just to also have the current status of a Print Item, Article, Print Order or Production Job available in the leading system

First you have to prepare a Webhook Service. This service will be receiving the information from Durst Workflow. The service will consist of a host (the hostname or IP adress the service is available at) and path.

Create a subscriber using

POST /api/v1/subscribers/create

with the Request Body

{
  "externalAuthType": "NONE",
  "hostUri": "localhost:1234"
}

externalAuthType is only needed if the Webhook requires authentication
hostUri describes the host of the service running the Webhook.

You’ll receive a {id} for the Subscriber

In the next step, it's needed to create a Subscription based on the previously created Subscriber

POST /api/v1/subscribers/{id}/subscriptions

with the Request defining the Subscription itself eg. a subscription to the Status of all Production Jobs

{
  "path": "path/to/webhook",
  "status": "ACTIVE",
  "topic": "STATUS/PRODUCTION_JOB/*"
}

or to the status of a single Job with its {jobid}

{
  "path": "path/to/webhook",
  "status": "ACTIVE",
  "topic": "STATUS/PRODUCTION_JOB/{jobid}",
  "publishInitialState": true
}

path the full path to the Webhook Service
status setting the subscription to active
topic the topic which should be covered
publishInitialState is used to provide the current status of a defined entity (article, motif, print order, productionjob) immediately after creating the subscription.

To disable a Subscription just send a

PUT api/v1/subscribers/{subscriberid}/subscriptions/{subscriptionid}

with

{
  "path": "path/to/webhook",
  "status": "INACTIVE",
  "topic": "STATUS/PRODUCTION_JOB/{jobid}",
  "publishInitialState": true
}

status setting the subscription to inactive

Some Callback examples:

If configured correctly Durst Workflow will call the Webhook at localhost:1234/path/to/webhook and send a payload as follows (depending on Subscription definition.

Subscription to a Motif/Print Item Status

{
  "entityType": "MOTIF",
  "entityId": 11094,
  "created": "2023-05-01T06:28:41.9243364+02:00",
  "oldStatus": "CREATED",
  "newStatus": "CHECKED_IN"
}

The status of the Print Item with id 11094 changed from Created to Checked In on May 1st at 06:28:41.

{
  "entityType": "MOTIF",
  "entityId": 11079,
  "created": "2023-05-01T06:28:37.75934+02:00",
  "oldStatus": "CHECK_REQUIRED",
  "newStatus": "WAITING_FOR_APPROVAL"
}

The status of the Print Item with id 11079 changed from Data Check to Waiting for Approval.

Subscription to a Workflow (a calculation process needing some time to be completed, eg. CheckIn, Ink Cost Calculation, applying Fixup or Fixup Chain)

{
  "id": 12842,
  "name": "motif-checkin",
  "status": "SUCCESS",
  "progress": 100,
  "currentStep": "Update Sub/Workflow Status",
  "stateMessage": "Render To Buffer Page 1",
  "startTimestamp": "2023-05-01T06:27:58.670862+02:00",
  "endTimestamp": "2023-05-01T06:28:32.751814+02:00",
  "executionTime": 34
}

The checkin workflow (process) with id 12842 has been successful.

{
  "id": 12835,
  "name": "production-job-calculate-ink-usage",
  "status": "SUCCESS",
  "progress": 100,
  "currentStep": "Update Workflow Status",
  "stateMessage": "Painting (Black - 100%)",
  "startTimestamp": "2023-05-01T06:27:04.972614+02:00",
  "endTimestamp": "2023-05-01T06:27:35.462578+02:00",
  "executionTime": 30
}

The calculation of ink usage for a Production Job workflow (process) with id 12835 has been successfully completed.

Subscription to a Production Jobs Status

{
  "entityType": "PRODUCTION_JOB",
  "entityId": 2068,
  "created": "2023-05-01T06:24:28.3312992+02:00",
  "newStatus": "CREATED",
  "printer": {
    "id": 5,
    "name": "P5 500",
    "serialNumber": "123 4567"
  }
}

The status of the Production Job with id 2068 has been changed to created. There was no previous status, because it is a new job. The assigned Printer is the P5 500 with printer id 5

{
  "entityType": "PRODUCTION_JOB",
  "entityId": 2063,
  "created": "2023-05-01T06:24:50.6216987+02:00",
  "oldStatus": "OUTPUT_CONFIG_ASSIGNED",
  "newStatus": "IMPOSED",
  "printer": {
    "id": 3,
    "name": "P5 TEX iSUB"
  }
}

The status of the Production Job with id 2063 has been from Output Configuration Assigned to Created. The assigned Printer is the P5 Tex iSUB with printer id 3

2. Create a Subscriber

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

The following steps specify how to create a Subscriber and Subscriptions in the Durst Workflow to receive status updates via callback URLs. The first step is to create a Subscriber as mentioned below. To create a Subscription to a topic see the following chapters.

Both objects can be updated (changing the password of the Subscriber / changing status of the Subscription (INACTIVE - unsubscribe).

The response contains the id of the Subscriber to be used for creating a Subscription.

POST /api/v1/subscribers/create

2.1. Parameters

Type	Name	Description	Schema
Body	subscriberApi required	Create a Subscriber	SubscriberApi
Body	JWTSigningInfo optional	signs the message with a JWT hash	JWTSigningInfo
Body	XAuthInfo optional	x-auth token	XAuthInfo

2.2. Responses

HTTP Code	Description	Schema
201	Created	SubscriberApi
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

2.3. Consumes

application/json

2.4. Produces

*/*

2.5. Tags

Subscriber Controller Api

2.6. Example HTTP request with x Auth

Request path

/api/v1/subscribers/create

Request body

{
  "externalAuthType": "XAUTH",
  "hostUri": "https://domain.at:443/base/path/",
  "xAuthInfo": {
    "password": "password",
    "user": "user"
  }
}

2.7. Example HTTP response with x Auth

Response 201

{
  "id": 17,
  "hostUri": "https://domain.at:443/base/path/",
  "externalAuthType": "XAUTH",
  "xAuthInfo": {
    "user": "user",
    "password": "FbSSYRbd9QpUBtyvVOr52A=="
  }
}

2.8. Example HTTP request without Authentification

Request path

/api/v1/subscribers/create

Request body

{
  "externalAuthType": "NONE",
  "hostUri": "https://domain.at:443/base/path/"
}

2.9. Example HTTP response without Authentification

Response 201

{
  "id": 20,
  "hostUri": "https://domain.at:443/base/path/",
  "externalAuthType": "NONE"
}

2.10. Example HTTP request with JWT Signing

Request path

/api/v1/subscribers/create

Request body

{
  "externalAuthType": "JWT_SIGNING",
  "hostUri": "https://domain.at:443/base/path/",
  "jwtSigningInfo": {
    "httpHeaderName": "x-jwt-token",
    "key": "string",
    "method": "HS256"
  }
}

2.11. Example HTTP response with JWT Signing

Response 201

{
  "id": 35,
  "hostUri": "https://domain.at:443/base/path/",
  "externalAuthType": "JWT_SIGNING",
  "jwtSigningInfo": {
    "httpHeaderName": "x-jwt-token",
    "method": "HS256",
    "key": "3IgPH7Gok2F+z9ZJ9zItbw=="
  }
}

3. Update a Subscriber

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

Update parameters for a Subscriber with a corresponding ID

PUT /api/v1/subscribers/{id}

3.1. Parameters

Type	Name	Description	Schema
Path	id required	The ID of the Subscriber	integer (int32)
Body	subscriberApi required	Create a Subscriber	SubscriberApi
Body	JWTSigningInfo optional	Signs the message with a JWT hash	JWTSigningInfo
Body	XAuthInfo optional	x-auth token	XAuthInfo

3.2. Responses

HTTP Code	Description	Schema
201	Created	SubscriberApi
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

3.3. Consumes

application/json

3.4. Produces

*/*

3.5. Tags

Subscriber Controller Api

3.6. Example HTTP request with x Auth

Request path

/api/v1/subscribers/{id}

Request body

{
  "externalAuthType": "XAUTH",
  "hostUri": "https://domain.at:443/base/path/",
  "xAuthInfo": {
    "password": "password",
    "user": "user"
  }
}

3.7. Example HTTP response with x Auth

Response 201

{
  "id": 17,
  "hostUri": "https://domain.at:443/base/path/",
  "externalAuthType": "XAUTH",
  "xAuthInfo": {
    "user": "user",
    "password": "FbSSYRbd9QpUBtyvVOr52A=="
  }
}

3.8. Example HTTP request without Authentification

Request path

/api/v1/subscribers/{id}

Request body

{
  "externalAuthType": "NONE",
  "hostUri": "https://domain.at:443/base/path/"
}

3.9. Example HTTP response without Authentification

Response 201

{
  "id": 20,
  "hostUri": "https://domain.at:443/base/path/",
  "externalAuthType": "NONE"
}

3.10. Example HTTP request with JWT Signing

Request path

/api/v1/subscribers/create

Request body

{
  "externalAuthType": "JWT_SIGNING",
  "hostUri": "https://domain.at:443/base/path/",
  "jwtSigningInfo": {
    "httpHeaderName": "x-jwt-token",
    "key": "string",
    "method": "HS256"
  }
}

3.11. Example HTTP response with JWT Signing

Response 201

{
  "id": 35,
  "hostUri": "https://domain.at:443/base/path/",
  "externalAuthType": "JWT_SIGNING",
  "jwtSigningInfo": {
    "httpHeaderName": "x-jwt-token",
    "method": "HS256",
    "key": "3IgPD8kok2F+z9ZJ9zItbw=="
  }
}

4. Get a Subscriber by ID

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

Get information stored for a specific Subscriber

GET /api/v1/subscribers/{id}

4.1. Parameters

Type	Name	Description	Schema
Path	id required	The id of the Subscriber	integer (int32)

4.2. Responses

HTTP Code	Description	Schema
200	OK	SubscriberApi
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

4.3. Consumes

application/json

4.4. Produces

*/*

4.5. Tags

Subscriber Controller Api

4.6. Example HTTP request

Request path

/api/v1/subscribers/{id}

4.7. Example HTTP response

Response 200

{
  "id": 35,
  "hostUri": "https://domain.at:443/base/path/",
  "externalAuthType": "JWT_SIGNING",
  "jwtSigningInfo": {
    "httpHeaderName": "x-jwt-token",
    "method": "HS256",
    "key": "3IgPD8kok2F+z9ZJ9zItbw=="
  }
}

5. Subscribe to a topic with an existing Subscriber

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

A Subscriber can subscribe to different topics, which might be explicit jobs (identified by its id) or all Production Jobs. By using STATUS/* every status update (motif, article, production_job and print_order) will be sent to the subscriber. With STATUS/PRODUCTION_JOB/* the status updates of all Production Jobs will be sent to the Subscriber. You can also Subscribe to a specific Production Job by adding the corresponding ID e.g. STATUS/PRODUCTION_JOB/122

The value "path" is optional, if null - the status update will be sent to the host-uri

The response contains the subscriptionID.

Possible Subscriptions can be

From 1.7.6

STATUS/* - Get all status changes for Articles, Motifs, Print Orders and Production Jobs
STATUS/PRODUCTION_JOB/* - Get status changes for all Production Jobs
STATUS/PRODUCTION_JOB/{jobid} - Get status changes for a certain Production Job
STATUS/ARTICLE/* - Get status changes for all Articles
STATUS/ARTICLE/{articleid} - Get status changes for a certain Article
STATUS/MOTIF/* - Get status changes for all Motifs
STATUS/MOTIF/{motifid} - Get status changes for a certain Motif
STATUS/PRINT_ORDER/* - Get status changes for all Print Orders
STATUS/PRINT_ORDER/{orderid} - Get status changes for a certain Print Order
WORKFLOW/* - Get the progress of all Workflows
WORKFLOW/{workflowid}/* - Get the progress of a certain Workflow

From 1.8.2

WORKFLOW/motif-split-pages/* - Get the progress of Split Pages Processes including the IDs of the split Articles or Motifs
WORKFLOW/production-job-calculate-ink-usage/* - Get the progress of Ink Calculation Processes for Production Jobs
WORKFLOW/motif-calculate-ink-usage/* - Get the progress of Ink Calculation Processes for Motifs
WORKFLOW/motif-apply-ptb-chain/* - Get the progress of Apply Fixup Chain Processes
WORKFLOW/motif-checkin/* - Get the progress of Check-In Processes
WORKFLOW/generate-report-approval/* - Get the progress of Report Generation Processes
WORKFLOW/calculate-ink-usage/* - Get the progress of Ink Calculation Processes
WORKFLOW/motif-apply-profile/* - Get the progress of Apply Fixup Processes

From 1.10.0

REPO/* - Get Updates and deletions of Substrate Categories, Substrates and Substrate Shapes

POST /api/v1/subscribers/{id}/subscriptions/create

5.1. Parameters

Type	Name	Description	Schema
Path	id required	The id of an existing Subscriber	integer (int32)
Body	SubscriptionApi required	Parameters for Subscription	SubscriptionApi

5.2. Responses

HTTP Code	Description	Schema
201	Created	SubscriptionApi
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

5.3. Consumes

application/json

5.4. Produces

*/*

5.5. Tags

Subscription Controller Api

5.6. Example HTTP

Request path

/api/v1/subscribers/{id}/subscriptions/create

Request body

{
  "path": "path/after/baseUri",
  "status": "ACTIVE",
  "topic": "STATUS/*"
}

5.7. Example HTTP response

Response 201

{
    "id": 4,
    "path": "path/after/baseUri/",
    "topic": "STATUS/*",
    "status": "ACTIVE"
}

6. Update a Subscription

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

Use the Update a Subscription to e.g. set an existing Subscription to inactive or to subscribe to another topic.

PUT /api/v1/subscribers/{id}/subscriptions/{subscriptionId}

6.1. Parameters

Type	Name	Description	Schema
Path	id required	The id of an existing Subscriber	integer (int32)
Path	subscriptionId required	The id of an existing Subscription	integer (int32)
Body	SubscriptionApi required	Parameters for Subscription	SubscriptionApi

6.2. Responses

HTTP Code	Description	Schema
201	Created	SubscriptionApi
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

6.3. Consumes

application/json

6.4. Produces

*/*

6.5. Tags

Subscription Controller Api

6.6. Example HTTP

Request path

/api/v1/subscribers/{subscriberId}/subscriptions/{subscriptionId}

Request body

{
  "path": "path/after/baseUri",
  "status": "INACTIVE",
  "topic": "STATUS/*"
}

6.7. Example HTTP response

Response 201

{
    "id": 4,
    "path": "path/after/baseUri/",
    "topic": "STATUS/*",
    "status": "INACTIVE"
}

7. Fetch existing Subscriptions for an existing Subscriber

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

Get a list of existing Subscriptions for an existing Subscriber

GET /api/v1/subscribers/{id}/subscriptions

7.1. Parameters

Type	Name	Description	Schema
Path	id required	The id of an existing Subscriber	integer (int32)

7.2. Responses

HTTP Code	Description	Schema
200	OK	SubscriberApi
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

7.3. Consumes

application/json

7.4. Produces

*/*

7.5. Tags

Subscription Controller Api

7.6. Example HTTP request

Request path

/api/v1/subscribers/{subscriberId}/subscriptions

7.7. Example HTTP response

Response 200

{
  {
    "id": 4,
    "path": "path/after/baseUri/",
    "topic": "STATUS/*",
    "status": "ACTIVE"
  },
  {
    "id": 3,
    "path": "path/after/baseUri/",
    "topic": "STATUS/PRODUCTION_JOB/*",
    "status": "ACTIVE"
  }
]

8. Fetch an existing Subscription for an existing Subscriber

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

Get an existing Subscription for a specific Subscriber

GET /api/v1/subscribers/{id}/subscriptions/{subscriptionId}

8.1. Parameters

Type	Name	Description	Schema
Path	id required	The id of an existing Subscriber	integer (int32)
Path	subscriptionId required	The id of an en existing Subscription	integer (int32)

8.2. Responses

HTTP Code	Description	Schema
200	OK	SubscriberApi
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

8.3. Consumes

application/json

8.4. Produces

*/*

8.5. Tags

Subscription Controller Api

8.6. Example HTTP request

Request path

/api/v1/subscribers/{subscriberId}/subscriptions

8.7. Example HTTP response

Response 200

{
  {
    "id": 4,
    "path": "path/after/baseUri/",
    "topic": "STATUS/*",
    "status": "ACTIVE"
  },
  {
    "id": 3,
    "path": "path/after/baseUri/",
    "topic": "STATUS/PRODUCTION_JOB/*",
    "status": "ACTIVE"
  }
]

9. Testresponse for Subscriptions

Compatibility: from Durst Workflow v1.7.6

Available in
Durst Workflow Print Label / Durst Workflow Print Label +
Durst Workflow Print / Durst Workflow Print +

For Development Purposes: Sends a callback to the defined hostUris with a fake status change of the Production Job to all active Subscribers.

GET /api/v1/subscribers/testresponse/{productionJobId}

9.1. Parameters

Type	Name	Description	Schema
Path	productionJobId required	The id of an existing ProductionJob	integer (int32)

9.2. Responses

HTTP Code	Description	Schema
200	OK	SubscriberApi
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

9.3. Consumes

application/json

9.4. Produces

*/*

9.5. Tags

Subscriber Controller Api

9.6. Example HTTP request

Request path

/api/v1/subscribers/{subscriberId}/subscriptions

9.7. Example HTTP response

Response 200

no content

Previous Article 4.7 Substrates

Next Article 4.9 Ink Cost Calculation

4.8 Subscriptions and Status Callback

Heading anchor 2.1. Parameters

Heading anchor 2.2. Responses

Heading anchor 2.3. Consumes

Heading anchor 2.4. Produces

Heading anchor 2.5. Tags

Heading anchor 2.6. Example HTTP request with x Auth

Heading anchor 2.7. Example HTTP response with x Auth

Heading anchor 2.8. Example HTTP request without Authentification

Heading anchor 2.9. Example HTTP response without Authentification

Heading anchor 2.10. Example HTTP request with JWT Signing

Heading anchor 2.11. Example HTTP response with JWT Signing

Heading anchor 3.1. Parameters

Heading anchor 3.2. Responses

Heading anchor 3.3. Consumes

Heading anchor 3.4. Produces

Heading anchor 3.5. Tags

Heading anchor 3.6. Example HTTP request with x Auth

Heading anchor 3.7. Example HTTP response with x Auth

Heading anchor 3.8. Example HTTP request without Authentification

Heading anchor 3.9. Example HTTP response without Authentification

Heading anchor 3.10. Example HTTP request with JWT Signing

Heading anchor 3.11. Example HTTP response with JWT Signing

Heading anchor 4.1. Parameters

Heading anchor 4.2. Responses

Heading anchor 4.3. Consumes

Heading anchor 4.4. Produces

Heading anchor 4.5. Tags

Heading anchor 4.6. Example HTTP request

Heading anchor 4.7. Example HTTP response

Heading anchor 5.1. Parameters

Heading anchor 5.2. Responses

Heading anchor 5.3. Consumes

Heading anchor 5.4. Produces

Heading anchor 5.5. Tags

Heading anchor 5.6. Example HTTP

Heading anchor 5.7. Example HTTP response

Heading anchor 6.1. Parameters

Heading anchor 6.2. Responses

Heading anchor 6.3. Consumes

Heading anchor 6.4. Produces

Heading anchor 6.5. Tags

Heading anchor 6.6. Example HTTP

Heading anchor 6.7. Example HTTP response

Heading anchor 7.1. Parameters

Heading anchor 7.2. Responses

Heading anchor 7.3. Consumes

Heading anchor 7.4. Produces

Heading anchor 7.5. Tags

Heading anchor 7.6. Example HTTP request

Heading anchor 7.7. Example HTTP response

Heading anchor 8.1. Parameters

Heading anchor 8.2. Responses

Heading anchor 8.3. Consumes

Heading anchor 8.4. Produces

Heading anchor 8.5. Tags

Heading anchor 8.6. Example HTTP request

Heading anchor 8.7. Example HTTP response

Heading anchor 9.1. Parameters

Heading anchor 9.2. Responses

Heading anchor 9.3. Consumes

Heading anchor 9.4. Produces

Heading anchor 9.5. Tags

Heading anchor 9.6. Example HTTP request

Heading anchor 9.7. Example HTTP response

Automation

Other Resources

2.1. Parameters

2.2. Responses

2.3. Consumes

2.4. Produces

2.5. Tags

2.6. Example HTTP request with x Auth

2.7. Example HTTP response with x Auth

2.8. Example HTTP request without Authentification

2.9. Example HTTP response without Authentification

2.10. Example HTTP request with JWT Signing

2.11. Example HTTP response with JWT Signing

3.1. Parameters

3.2. Responses

3.3. Consumes

3.4. Produces

3.5. Tags

3.6. Example HTTP request with x Auth

3.7. Example HTTP response with x Auth

3.8. Example HTTP request without Authentification

3.9. Example HTTP response without Authentification

3.10. Example HTTP request with JWT Signing

3.11. Example HTTP response with JWT Signing

4.1. Parameters

4.2. Responses

4.3. Consumes

4.4. Produces

4.5. Tags

4.6. Example HTTP request

4.7. Example HTTP response

5.1. Parameters

5.2. Responses

5.3. Consumes

5.4. Produces

5.5. Tags

5.6. Example HTTP

5.7. Example HTTP response

6.1. Parameters

6.2. Responses

6.3. Consumes

6.4. Produces

6.5. Tags

6.6. Example HTTP

6.7. Example HTTP response

7.1. Parameters

7.2. Responses

7.3. Consumes

7.4. Produces

7.5. Tags

7.6. Example HTTP request

7.7. Example HTTP response

8.1. Parameters

8.2. Responses

8.3. Consumes

8.4. Produces

8.5. Tags

8.6. Example HTTP request

8.7. Example HTTP response

9.1. Parameters

9.2. Responses

9.3. Consumes

9.4. Produces

9.5. Tags

9.6. Example HTTP request

9.7. Example HTTP response