User Manual

Articles

Updated on

1. Create an Article

Articles can be stored in the Workflow without using an existing job or creating a new Production Job. The data is structured and can be prepared for production, customer-specific mapping of colors can also be implemented and applied. The end product is assembled and output in the form of an Order or Production Job on demand.

POST /api/v1/articles/create

1.1. Parameters

Type Name Description Schema
Body articleApi required Defining Article attributes articleApi
Body FileLinkApi required Defining the path to the File FileLinkApi
Body ReferencedArticleCollectionApi optional Link to an Article Collection ReferencedArticleCollectionApi
Body ReferencedProcessingStepApi optional Link to a Processing Step ReferencedProcessingStepApi
Body ReferencedCustomerApi optional Link to a Customer ReferencedCustomerApi
Body ReferencedSubstrateApi optional Link to a Substrate ReferencedSubstrateApi
Body ProcessingOptionsApi optional Apply a Fixup Chain ProcessingOptionsApi

1.2. Responses

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

1.3. Consumes 

application/json

1.4. Produces 

*/*

1.5. Tags

Article Controller Api

1.6. Example HTTP request

Request path

/api/v1/articles/create

Request body

{
  "name": "Article 123",
  "comment": "Comment für Article",
  "externalId": "EXTNR123",
  "widthMm": 225,
  "heightMm": 60,
  "customfield": "This is a custom field for articles",
  "checkinTemplateGuid": "47e8e6c4-2ebc-412f-b427-e6393e66b67e",
  "pages": 1,
  "pdfFileLink": {
    "uri": "smb://data/files/article123.pdf"
  },
  "substrateReference": {
    "id": 2
  },
  "customerReference": {
    "id": 55
  },
  "additionalFilesList": [
    {
      "uri": "{{https://example.com/additionaldata.csv}}"
    }
  ],
  "articleCollectionReferenceList": [
    {
      "id": 8
    }
  ],
  "articleProcessingStepList": [
    {
      "id": 1
    }
  ]
}

1.7. Example HTTP response

From the Workflow Version 1.8.1 and later the Response also includes the Color Policy used for the defined Substrate.

Response 201

{
  "id": 10874,
  "name": "Article 123",
  "externalId": "EXTNR123",
  "status": "CREATED",
  "customfield": "This is a custom field for articles",
  "comment": "Comment für Article",
  "widthMm": 225,
  "heightMm": 60,
  "pages": 1,
  "customerReference": {
    "id": 55
  },
  "substrateReference": {
    "id": 2
  },
  "colorPolicyReference": {
    "id": 3
  },
  "articleCollectionReferenceList": [
    {
      "id": 1
    }
  ],
  "articleProcessingStepList": [
    {
      "id": 1
    }
  ]
}
2. Create an Article and Apply Fixup Chain

It is now possible to create an Article and submit the required attributes for a Fixup Chain within the same Request. A Fixup Chain has to be configured in the Workflow before it can be applied.

POST /api/v1/articles/create

2.1. Parameters

Type Name Description Schema
Body articleApi required Defining Article attributes articleApi
Body FileLinkApi required Defining the path to the File FileLinkApi
Body ReferencedArticleCollectionApi optional Link to an Article Collection ReferencedArticleCollectionApi
Body ReferencedProcessingStepApi optional Link to a Processing Step ReferencedProcessingStepApi
Body ReferencedCustomerApi optional Link to a Customer ReferencedCustomerApi
Body ReferencedSubstrateApi optional Link to a Substrate ReferencedSubstrateApi
Body ProcessingOptionsApi optional Apply a Fixup Chain ProcessingOptionsApi

2.2. Responses

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

2.3. Consumes 

application/json

2.4. Produces 

*/*

2.5. Tags

Article Controller Api

2.6. Example HTTP request

Request path

/api/v1/articles/create

Request body

{
  "name": "Article 123",
  "comment": "Comment für Article",
  "externalId": "EXTNR123",
  "widthMm": 225,
  "heightMm": 60,
  "customfield": "This is a custom field for articles",
  "pages": 1,
  "pdfFileLink": {
    "uri": "smb://data/files/article123.pdf"
  },
  "processingOptions": {
    "fixupChain": {
      "id": 132,
      "name": "Banner with Grommets",
      "automationKey": "BANNER_WITH_GROMMETS"
    }
  },
  "substrateReference": {
    "id": 2
  },
  "customerReference": {
    "id": 55
  },
  "additionalFilesList": [
    {
      "uri": "https://example.com/additionaldata.csv"
    }
  ],
  "articleCollectionReferenceList": [
    {
      "id": 8
    }
  ],
  "articleProcessingStepList": [
    {
      "id": 1
    }
  ]
}

2.7. Example HTTP response

Response 201

{
  "id": 7019,
  "externalId": "EXTNR123",
  "status": "CREATED",
  "name": "Article 123",
  "comment": "Comment für Article",
  "widthMm": 225,
  "heightMm": 60,
  "pages": 1,
  "customerReference": {
    "id": 55
  },
  "substrateReference": {
    "id": 2
  },
  "articleCollectionReferenceList": [
    {
      "id": 8
    }
  ],
  "articleProcessingStepList": [
    {
      "id": 1
    }
  ],
  "additionalFilesList": []
}
3. Validate Article

Validation checks if:

  • all required fields are set
  • all required Collections contain at least one element
  • all enum fields contain an allowed value
  • all required methods are returning a non-null value, use that annotation
  • files (URI) are available
  • all used User-defined Fields are set correctly and have the correct parameters
  • A validation is also made when an Article is created.
POST /api/v1/articles/validate

3.1. Parameters

Type Name Description Schema
Body articleApi required Defining Article attributes articleApi
Body FileLinkApi required Defining the path to the File FileLinkApi
Body ReferencedArticleCollectionApi optional Link to an Article Collection ReferencedArticleCollectionApi
Body ReferencedProcessingStepApi optional Link to a Processing Step ReferencedProcessingStepApi
Body ReferencedCustomerApi optional Link to a Customer ReferencedCustomerApi
Body ReferencedSubstrateApi optional Link to a Substrate ReferencedSubstrateApi

3.2. Responses

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

3.3. Consumes 

application/json

3.4. Produces 

*/*

3.5. Tags

Article Controller Api

3.6. Example HTTP request

Request path

/api/v1/articles/validate

Request body

{
  "name": "Article 123",
  "comment": "Comment für Article",
  "externalId": "EXTNR123",
  "widthMm": 225,
  "heightMm": 60,
  "checkinTemplateGuid": "47e8e6c4-2ebc-412f-b427-e6393e66b67e",
  "customfield": "This is a custom field for articles",
  "pages": 1,
  "pdfFileLink": {
    "uri": "smb://data/files/article123.pdf"
  },
  "substrateReference": {
    "id": 2
  },
  "customerReference": {
    "id": 55
  },
  "additionalFilesList": [
    {
      "uri": "https://example.com/additionaldata.csv"
    }
  ],
  "articleCollectionReferenceList": [
    {
      "id": 8
    }
  ],
  "articleProcessingStepList": [
    {
      "id": 1
    }
  ]
}

3.7. Example HTTP response

Response 201

{
    "ok": true,
    "validationFailures": []
}
4. Get Article by ID

Get Article and stored information on the Article by ID

GET /api/v1/articles/{id}

4.1. Parameters

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

4.2. Responses

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

4.3. Consumes 

application/json

4.4. Produces 

*/*

4.5. Tags

Article Controller Api

4.6. Example HTTP request

Request path

/api/v1/articles/{id}

4.7. Example HTTP response

Response 200

{
  "id": 7019,
  "externalId": "EXTNR123",
  "status": "CHECKED_IN",
  "name": "Article 123",
  "comment": "Comment für Article",
  "widthMm": 225,
  "heightMm": 60,
  "customfield": "This is a custom field for articles",
  "pages": 1,
  "customerReference": {
    "id": 55
  },
  "substrateReference": {
    "id": 2
  },
  "articleCollectionReferenceList": [
    {
      "id": 8
    }
  ],
  "articleProcessingStepList": [
    {
      "id": 1
    }
  ],
  "additionalFilesList": []
}
5. Get active User-defined Fields available for Articles

Get all active User-defined Fields available for articles

GET /api/v1/articles/customFields

5.1. Responses

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

5.2. Consumes 

application/json

5.3. Produces 

*/*

5.4. Tags

Article Controller Api

5.5. Example HTTP request

Request path

/api/v1/articles/customFields

5.6. Example HTTP response

Response 201

[
  {
    "id": 100
    "key": "custom_field_1",
    "entityType": "article",
    "label": "Name of the field",
    "valueTypeKey": "NUMERIC",
    "status": "ACTIVE",
    "mandatory": true
  },
  {
    "id": 102,
    "key": "custom_field_2",
    "entityType": "article",
    "label": "Name of the field",
    "valueTypeKey": "STRING",
    "status": "ACTIVE",
    "mandatory": false
  }
]
6. Apply Fixup to Article(s)

Fixups can be either applied to Articles or Motifs within Print Orders and Production Jobs. Find out more on how to fetch available Fixups here Chapter (Fixups).

POST /api/v1/articles/{id}/applyFixup

6.1. Parameters

Type Name Description Schema
Path id required The id of the Article integer (int32)
Body fixupRequestOptionsApi required Options and Parameters of the Fixup to be applied fixupRequestOptionsApi

6.2. Responses

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

6.3. Consumes 

application/json

6.4. Produces 

*/*

6.5. Tags

Article Controller Api

6.6. Example HTTP request

Request path

/api/v1/articles/{id}/applyFixup

Request body

{
  "fixupApiParameter": {
    "VAR_NAME_Rotate": "90"
  },
  "fixupApiReference": {
    "automationKey": "ROTATE_PAGE"
  }
}

6.7. Example HTTP response

The response contains an workflow-controller output listin progress and current steps. Refer to this Chapter to learn about the Workflow Controller.

Response 201

{
  "id": 7499,
  "name": "motif-apply-profile",
  "progress": 0,
  "status": "RUNNING",
  "currentStep": "preFlight",
  "startTimestamp": "2019-09-25T14:27:49.406",
  "executionTime": 0
}
7. Apply Fixup Chain to Article(s)

Fixups can be either applied to Articles or Motifs within Print Orders and Production Jobs. Find out more on how to fetch available Fixups here Chapter (Fixups).

POST /api/v1/articles/{id}/applyFixupChain

7.1. Parameters

Type Name Description Schema
Path id required The id of the Article integer (int32)
Body fixupChainApi required Name, Automation Key and ID of the Fixup Chain to be used fixupChainApi

7.2. Responses

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

7.3. Consumes 

application/json

7.4. Produces 

*/*

7.5. Tags

Article Controller Api

7.6. Example HTTP request

Request path

/api/v1/articles/{id}/applyFixupChain

Request body

{
  "automationKey": "FIXUP_ROUNDED2",
  "id": 12

}

7.7. Example HTTP response

The response contains an workflow-controller output listing progress and current steps. Refer to this Chapter to learn about the Workflow Controller.

Response 201

{
  "id": 18948,
  "name": "motif-apply-ptb-chain",
  "status": "SUCCESS",
  "progress": 100,
  "currentStep": "updateWorkflowStatus",
  "startTimestamp": "2020-06-09T13:51:25.111854+02:00",
  "endTimestamp": "2020-06-09T13:51:25.771559+02:00",
  "executionTime": 1
}
8. Fetch Thumbnail, PDF Preview or Preflight PDF of an Article

Fetch a Thumbnail, PDF Preview or Preflight PDF Report of an Article. Available Download Formats are Direct Download or Base64 encypted.

GET /api/v1/articles/{id}/files/{fileTypeKey}/{downloadFormat}

8.1. Parameters

Type Name Description Schema
Path id required The id of the Article integer (int32)
Path downloadFormat required Download Format of the files enum (direct, base64)
Path fileTypeKey required File Type  enum (thumbnail, pdf, preflightPdfReport)

8.2. Responses

HTTP Code Description Schema
200 OK Download of the File
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content

8.3. Consumes 

application/json

8.4. Produces 

*/*

8.5. Tags

Article Controller Api

8.6. Example HTTP request

Request path

GET /api/v1/articles/{id}/files/{fileTypeKey}/{downloadFormat}
9. Add an Article to an existing Production Job

Add an existing Article to an existing Production Job. An empty Production Job (Production Job without Print Items) can be created in advance, then several Articles can be joined to this job from an external system. The Article will use the Production Jobs Color Policy and Substrate Shape (optional).

POST /api/v1/productionJobs/{id}/motifs/addArticle

9.1. Parameters

Type Name Description Schema
Path id required The ID of the Production Job integer (int 32)
Body articleReference required The ID of the Article to be added to the Production Job ProductionJobItemApi
Body numberCopies required Number of copies of the Article ProductionJobItemApi

9.2. Responses

HTTP Code Description Schema
200 OK MotifApi
201 Created No Content
401 Unauthorized No Content
403 Forbidden No Content
404 Not Found No Content

9.3. Consumes 

application/json

9.4. Produces 

*/*

9.5. Tags

Production Job Motif Controller Api

9.6. Example HTTP request

Request path

/api/v1/productionJobs/{id}/motifs/addArticle

Request body

{
  "articleReference": {
    "id": 4429
  },
  "numberCopies": 21
}

9.7. Example HTTP response

Response 201

{
  "id": 4429,
  "externalId": "EXTNR123",
  "status": "CREATED",
  "name": "Article 123",
  "comment": "Comment für Article",
  "widthMm": 225,
  "heightMm": 60,
  "pages": 1,
  "numberCopies": 21,
  "colorPolicyReference": {}
}
10. Update an Articles Status

Articles Statuses can be updated with a PATCH Request. The possible statuses are: CREATED, CHECKED_IN, CHECK_REQUIRED, FINAL_ARTWORK, WAITING_FOR_APPROVAL, APPROVED and LOCKED.

PATCH /api/v1/articles/{id}

10.1. Parameters

Type Name Description Schema
Body articleApi required  Defining Article attributes (Status only) articleApi

10.2. Responses

HTTP Code Description Schema
200 OK articleApi
204 Not Content No Content
400 Bad Request Error Code
403 Forbidden No Content
404 Not Found No Content

10.3. Consumes 

application/json

10.4. Produces 

*/*

10.5. Tags

Article Controller Api

10.6. Example HTTP request

Request path

/api/v1/articles/{id}

Request body

{
  "status": "FINAL_ARTWORK"
}

10.7. Example HTTP response

Response 200

{
  "id": 10874,
  "name": "Article 123",
  "externalId": "EXTNR123",
  "status": "FINAL_ARTWORK",
  "customfield": "This is a custom field for articles",
  "comment": "Comment für Article",
  "widthMm": 225,
  "heightMm": 60,
  "pages": 1,
  "customerReference": {
    "id": 55
  },
  "substrateReference": {
    "id": 2
  },
  "colorPolicyReference": {
    "id": 3
  },
  "articleCollectionReferenceList": [
    {
      "id": 1
    }
  ],
  "articleProcessingStepList": [
    {
      "id": 1
    }
  ]
}
Previous Article Introduction
Next Article Login

Connect Workflow with External Systems

Rest API Documentation – Workflow 21

Other Resources
Print Article