The DFaaS platform uses resources stored in the cloud. All resources are tracked and promoted by resource promotion.

As we’ll see, document flows are capable of referencing templates in other projects. Document flows often have a different development cycle and different maintainers than the templates they process. While it is possible to mix template and document flow resources in a single project, for these reasons, it is probably a good idea to create a different project dedicated to document flows.

We recommend at least two environments for a document flow project. A developement environment that can be synced to your Design & Compose Self-Hosted Edition for experimenting and developing, and a production environment that will handle actual requests. A test-environment for validation by QA or business users before promoting changes to production is commonly added to the setup as well.

At the moment, the DFaaS functionality is only meant to be used in projects managed by Unifiedpost. For this reason the DFaaS specific functionality is hidden from the Design & Compose Self-Hosted Edition designer.

In order to enable this functionality, add the following fragment to your local configuration:

You will probably want to test as much as possible locally, on your own computer, to avoid build and deploy times and iterate faster. Input will be simulated by putting input data in a folder. Similarly, deliverables will be written to an output folder.

The location of these input and output folders can be defined in the local configuration file as follows:

The json you need to place in the folder in order to trigger the flow has the following structure:

The DFaaS platform will automatically build and deploy all document flow packages it finds in DFaaS enabled environments. To enable an environment, use the Xribe Deploy API to enable an environment.

Invoking a document flow is done by POSTing a message with input type documentflow to the Xribe Output API. An example of a message is:

When a document flow is ready for the next step, the resources can be deployed to the next environment, which will automatically trigger the build of a new package. Once the build has finished, existing instances will be terminated and replaced by instances containing the newly promoted version.

The main part of the project descriptor is the list of document flows.

The document-flow-name is what will be used to route your message to the correct document flow when using the Xribe Output API.

Resources like templates and images can be referenced relatively if they are included in the project, but if you followed the advice to put templates in a different project, you will reference them using the idr:// protocol. Note that this means you will need to provide your document flow with credentials, a client-id/client-secret linked to a user authorized to access the resources. Instead of hardcoding the client-id and client-secret, add them as properties when enabling the environment and pass them as Environment Variables to the document flow. That way, you can use the same document flow in different environments with different users.

If your document flow uses custom steps, either from the market place or developed yourself, you can make them available to the DFaaS platform by placing a zipped update site in your project and referencing the steps in the project descriptor like so:

If the templates used in the document flows require custom fonts, these fonts need to be installed before they can be used. Provide the necessary fonts by including them in your project and referencing them as follows in the project descriptor:

If the templates used in the document flows require custom color profiles, these profiles need to be made available to the processing server before they can be used. Provide the necessary profiles by including them in your project and referencing them as follows in the project descriptor:

The log configuration, influencing how much is logged and by what components can be configured as follows:

For access to the logs, contact support or the Xribe team.

If specific configuration entries are needed, like AFP font configuration or certain performance settings, configuration entries can be passed to the server running the package as follows:

When a message is submitted through the Xribe Output API, an instance of the package is spun up to handle it. When additional messages are submitted and they start queueing up, additional instances of the package are started in order to process the increased load. The maximum number of instances that are started can be influenced by the package-instances max attribute. A reason for limiting the maximum number of instances might be to limit the load on external systems that the document flows are interacting with.

Starting an instance can take a few minutes. In order to avoid this cold start, the min attribute can be used to make sure there are always one or more instances available to handle requests.

When started, a package instance can limit the amount of messages an instance is picking up by specifying a messages-per-instance limit.

Not all document flows require the same amount of CPU, memory or disk. A document flow that generates a single pdf document for example needs little to no local disk space, whereas a document flow processing large batches likely needs local disk space to temporarily store and sort files.

Additionally, disk requirements can optionally be added as well. The size is expressed in GB with legal values between 20 and 200.

In order to introduce variability between environments, environment variables (properties) set when enabling the environment can be used in the project descriptor. This makes it possible for document flow to use different users, credentials, endpoints, …​ in different environments. To use environment variables, use the mustache syntax like so: {{variablename}}

One way to make environment variables available in the document flow is to pass them in a document flow property data source, or to use them to select a specific file to load more configuration options from:

Variables can be used anywhere in the package descriptor. This means they can also be used to change the scaling per environment for example.

The only way to trigger a document flow instance on the DFaaS platform is through the Message Monitor initial step. This step accepts the message used to call the Xribe Output API and outputs the value of the data property as a flow object of type Stream.

This step provisions a property data source with the following properties:

The Set Status step is used to update the status of the message that triggered this document flow instance. The status can be changed either to Generated, which indicates the successful processing of the message, or Error, which signals an error during processing. Details can be provided in a free-form message.

Should multiple Set Status steps be triggered, the Error status will trump the Generated status. Put in another way: once a message is marked as being Errored, it will never transition to a Generated state.

When the flow instance ends, a callback will be triggered if the original message specified this in its webhookParameters.

This step has the following properties:

When a flow instance aborts, the message will be retried by offering it to a new document flow instance. If the same message leads to aborts multiple times (10), it is sent to a Dead Letter Queue.

When a failure in a document flow is a legitimate possibility, error handling should be implemented in the flow; place appropriate steps in a container, set the skip on error property and add a Set Status step (with error status) to the error flow. That way the message will not be retried multiple times, the message and deliverable will transition to the error state and the callback (if present) will be notified of the error.

If a document flow wishes to communicate a result to the caller in the same way as the Xribe Output API - with pre-signed S3 links in output properties as part of the deliverable - this step must be used.

The file that should be made available as output is expected as an incoming flow object with data type Stream.

The step has the following properties:

This step generates a property data source with the following properties:

Invoking another document flow in the same package is possible using the Call Flow step.

The step requires the following properties:

Note that the amount of data that can be passed as properties is limited to a few hundred kB. Larger amounts of data are best passed as files in the data-storage-location with a reference passed as a property.

Files can be stored temporarily in the data-storage-location returned by the Initial Step. Files will be automatically deleted after 3 months.

The data-storage-location is a uri that can be used like a local path with folders like the Folder Delivery, Read Folder, Read Resource, Copy Resource or Delete Resource steps from the I/O category.

The lack of a tracking database or relational database in the DFaaS platform is mitigated by the Store, Read and Delete Data steps that provide access to a Non-relation Database. The data structure available is a map of maps and steps exist to add, read and delete entries from it.