User Manual

User Manual  /  Automation  /  2. Rest API Documentation – Workflow

2.8 Subscriptions and Status Callback

Updated on

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 2.7 Substrates
Next Article 2.9 Ink Cost Calculation

Automation

1. Integration Possibilities 1
2. Rest API Documentation – Workflow 18
3. Rest API Documentation – Durst Analytics 10

Other Resources
Print Article
Still Need Help? Contact Us