Skip to main content

Standard Java Plugin Worker Methods

1 Introduction​

The topics described in this documents relate to Service tasks only.

Worker Service enables processes to perform part of their rendering logic in an application running separately from priint:suite and priint:bpm. Processes can call one of the available Plugin Methods, which variable to expect and what outcome variables to add to the variable map as a result.

2 Assigning Task​

To assign some Task to a Worker Service:

Add a Service Task to a diagram and select it.

2.1 General Tab​

  • set its Implementation to External (Delegate Expression is not used)
  • set its Topic to priint-plugin-methods
  • Asynchronous Continuations - do not set
  • Documentation is a description for a Service Task

2.2 Definition Tab​

Choose a Plugin method type to Document, Folder or Publication and needed Plugin method.

2.3 Input/Output Tab​

Input/Output parameters differ depending on which method was chosen. If parameter is not provided in the process context, then add described variables here.

Note:

Parameter forceRefreshComponent set to true is automatically added.

3 Error Handling​

While running the method by a service task, errors can occur. There can be two types of errors. Business error (logical error) and technical error.

When business error happens the method sets two variables:

errorCode, errorMessage

to point out the problem and the process goes on - the business error can be handled using gateway element after a service task element in the process.

A technical error means that some exception occurred and can be handled using Error Boundary Events placed at the service task's boundary.

4 Standard Methods​

The standard methods need some variables to work as expected. If those variables are not set at the start of the process and they are not added by the service and user tasks leading to this point in the process, values can be set directly in the Input/Output -> Input Parameters section.

Parameters set in Input/Output Tab have higher priority and will override parameters incoming from previous steps.

4.1 Publication/Folder​

ZipInDesignPackages

Description

Adobe InDesign Server exports packages for each document in a form of a zip file. This plugin combines them to form a single zip archive of those packages. It is meant to be used for processes running for whole publications.

Input

This method expects the following to be set at a stage in the process where it gets called:

    • publicationId variable needs to be set in process context

      • outputFolder variable needs to be set telling the plugin where the outcome file should be placed

      • either a zipFilenamePrefix or objectLabel variable needs to be set and non-blank to tell the plugin how to name the outcome zip

      • zip files containing InDesign packages should reside next to the .indd documents, with zip files full names being the same as indds (they should only differ in file extensions, paths and filenames should be the same)

Outcome

The outcome of this method will be a newly set variable ZIP_FILE_PATH with a value equal to the path of a created combined archive. A single zip file will be placed in the output folder as a result.

ZipPdfs

Description

This method aims at creating a single zip archive of all pdf files exported in a rendering process. It works for merged pdfs, for single-document processes and for publication processes for which separate (non-merged) pdfs got created. It also takes pdf profiles used while rendering into account as they affect the names of pdfs this method should merge.

Input

This method expects the following to be set at a stage in the process where it gets called:

    • outputFolder variable needs to be set telling the plugin where the outcome file should be placed

      • either a zipFilenamePrefix or objectLabel variable needs to be set and non-blank to tell the plugin how to name the outcome zip

      • one of these variables needs to be set: MERGED_PDF_PATHS, documentid, publicationId, determining which pdfs will get processed.

      • if MERGED_PDF_PATHS is set, it should list existing files (supposedly pdfs merged on a per-pdf-profile basis). Pdfs compressed in a newly created archive are grouped in a directory described in a variable pdfFilenamePrefix - it needs to be set as well.

      • if MERGED_PDF_PATHS was not set, but variable documentid exists, this plugin assumes you only want to zip pdfs for a single document. An optional variable pdfProfiles listing pdf profiles used (or a lack of it) determines what the names of pdfs to zip are. Properly named pdf files are expected to exist next to the document file. Those pdfs will be zipped without any additional folders in an archive.

      • if both if MERGED_PDF_PATHS and documentid were not set, variable publicationId is expected. Again, an optional variable pdfProfiles listing pdf profiles used (or a lack of it) determines what names of pdfs to merge are. Properly named pdf files are expected to exist next to the document file. Those pdfs will be zipped without any additional folders in an archive.

Outcome

The outcome of this method will be a newly set variable ZIP_FILE_PATH with a value equal to the path of a created combined archive. A single zip file will be placed in the output folder as a result.

Calculate the start page of the document

Description

The method calculates the start page numbering of all documents in given publication tree and saves it in publication parameters. More information how it works is available here.

Input

    • publicationId variable needs to be set in process context

Outcome

Page numbers saved in publication parameters as configured.

MergePDFDocument

Description

This method merges (concatenates, appends) separate document pdfs. If separate pdf profiles were used for creating a few versions of each document's pdfs, the method will merge the files on a per-pdf-profile basis.

Input

    • outputFolder variable needs to be set telling the plugin where the outcome file or files should be placed

      • an optional variable pdfProfiles listing pdf profiles used (or a lack of it) determines what the names of pdfs to merge are.

      • documentIds variable needs to list identifiers of documents that got exported to pdfs

      • pdfFilenamePrefix variable is required telling the plugin how to name the outcome merged pdfs

      • pdfs named DOCUMENT_ID + _ + NORMALIZED_PDF_PROFILE_NAME + .pdf (or just DOCUMENT_ID + .pdf if no pdf profiles are provided) need to reside next to the document files

Outcome

The outcome of this method will be a newly set variable MERGED_PDF_PATHS with a list of paths to merged versions of pdf files. In the output folder, a merged pdf will be created for each pdf profile or a single merged pdf will appear if no pdf profiles were provided.

GetDocumentIDs

Description

This method enriches process context by adding a list of document identifiers for a publication.

Input

    • publicationId variable to be set at a stage in the process where it gets called

Outcome

Variable documentIds will be set to a list of document IDs.

Get Publication/Folder MetaData

Description

The method retrieves meta data of publication inclusive name, created on, updated on, updated by, created by id and the publication parameters. It has additional string parameter "prefix". It creates new or use existing process variables which names are built by the prefix and the identifiers of the parameters and set their values to the values of the document variables.

Outcome

Following process variables are created/updated: (preceded by prefix)

name, created, creator, updated, updater, type, kind and variables named like publication parameters.

Additionally if process is run on the folder, the following variables are added:

parent_name, parent_id, parent_type, parent_kind.

Set Publication MetaData

Description

The method allows to change the value of the publication parameter.

Outcome

The selected publication parameter is updated.

Set Publication/Folder Name

Description

The method allows to change the publication/folder name.

Outcome

The name of the publication is changed.

4.2 Document​

AdjustPageNumbersAndFetchDocumentMetaData

Description

This is an extension of a GetDocumentMetaData plugin that is also capable of adjusting starting page numbers of documents. This is useful if rendering changes the number of pages a document has and page number on subsequent documents need adjusting. Be sure to call this plugin sequentially for all rendered documents.

Input

    • documentIds variable needs to list identifiers of documents that a process renders

      • documentid variable is needed to determine, which document is currently being processed

      • startingPageParameterName variable must state a name of a document parameter that stores its starting page value

      • startingPageNumber variable is needed if currently processed document is not the first one

      • documentPageCounts variable is required if currently processed document is not the first one. It should contain a map with keys equal to document ids processed so far and their values set to the page counts of rendered documents.

Outcome

As a result, additional variables will be set:

    • documentpath - a full path to a document file

      • masterdocumentpath - a full path to a master document file

      • if it is the first document in the list that is being processed, startingPageNumber is set to a starting page number from that document. An extra side-effect is that documents except the first one will get their startingPageParameterName adjusted to a sum of first documents starting page number and a sum of page counts in documents rendered up to this point.

Set Document Stage

Description

Process updates document stage for given documentId.

Input

    • documentid variable for which document stage is updated
      • Fixed Value - if set true, then Document Stages is provided, otherwise pass the value from process variable
      • Document Stages - document stage from predefined values or value taken from process variable

Outcome

The document is updated with new Document stage or value from process variable. If document stage doesn't exist then process will throw a technical error.

Set Next Document Stage

Description

The method changes the document stage to the next one. If a document is in the last stage, the business error is raised.

Input

    • documentid variable for which document stage is updated

Outcome

The document stage is changed to the next one.

Get Document Paths

Description

This method sets additional file location information about a document in the running process context.

Input

    • documentid variable

Outcome

Sets additional file location information a document in the running process context.

Variables:

    • documentpath - a full path to a document file

      • masterdocumentpath - a full path to a master document file

Get Document MetaData

Description

The method retrieves meta data of a document inclusive name, created on, updated on, updated by, created by id, source document id, source document name, master document id, master document name and the document parameters. It has additional string parameter "prefix". It creates new or use existing process variables which names are built by the prefix and the identifiers of the parameters and set their values to the values of the document variables.

Input

    • documentid variable

Outcome

Following process variables are created/updated: (preceded by prefix)

name, created, creator, updated, updater, parent_name, parent_id, parent_type, parent_kind, stage, type, file_exists, locked and variables named like document parameters.

If a document is based on the source document additionally variables appear:

source_doc_id, source_doc_name.

If a document is based on the master document (template document) then the following variables appear:

template_doc_id, template_doc_name.

Set Document MetaData

Description

The method allows to change the value of the publication parameter.

Input

    • documentid variable

Outcome

The selected document parameter is updated.

MoveExportedInDesignPackage

Description

When an Adobe InDesign Server® package export gets called, it creates a zip file next to an .indd document. This method simply moves that package to the desired output folder, renaming the file on the way.

Input

    • outputFolder variable needs to be set telling the plugin where the destination folder is

      • objectLabel variable determines the name of the package to be set at the destination folder. zip file extension will be automatically added

      • an exported Adobe InDesign Server package needs to reside next to the document file with the same name as the document (only its extension should differ)

Outcome

The outcome of this plugin's work is simply a moved and possibly renamed package.

Remove notes

Description

The method allows to remove notes of selected type from the document.

Input

    • documentid variable

Outcome

The selected notes are removed from the document.