Rendering jobs

• 3 minutes to read

Customer's Canvas uses the RenderingService API to process projects that reflect customer orders and contain personalization results. This processing is based on the concept of RenderingJobs.

A rendering job is a set of step-by-step instructions, which defines how to process a personalized design. Each step is called a task. It describes an action that needs to be taken to reach the final result. For example, let's look at business cards:

1. We can take the personalized design of a card from the project.
2. Then, render it with certain parameters, to produce a proper print file.
3. Then, perform imposition by composing multiple copies of a print file in a single page.
4. Finally, we upload the result to the FTP of a printing company.

Configuring a rendering job

When you add tasks to a rendering job, you first need to configure them. To do so, define an array of RenderingJobs data as follows:

{
  "tasks": [
    {
      "description": "Extract design from project",
      "name": "extract",
      "namespace": "customers-canvas",
      "type": "extract-project-design",
      "parameters": {},
      "outputArtifacts": [
        "design"
      ]
    },
    ...
  ]
}

Every object in tasks contains:

• Identifying fields:
  • type - defines the function performed by the task, i.e., the set of expected parameters and the list of actions to be performed on them
  • namespace - defines the module in which to search for a task of the specified type
  • name - arbitrary task name unique within the list of RenderingJob tasks
  • description - text description of the task used for visualization
• Fields for working with artifacts:
  • inputArtifacts - list of input artifacts
  • outputArtifacts - list of output artifacts
  • finalArtifacts - list of artifacts to mark as final
• Fields specifying task parameters:
  • parameters - key-value dictionary with parameters required to complete the task.

When a file is created as a result of a task, it is saved as an artifact. Input files for a task are specified in the inputArtifacts array, and output files are listed in the outputArtifacts array.

{
  "description": "Render design",
  "name": "render-hires",
  "namespace": "customers-canvas",
  "type": "render-hires",
  "inputArtifacts": [
    "design"
  ],
  "outputArtifacts": [
    "print-file"
  ]
}

Output artifacts may be consumed in other tasks or marked as final so that you can download them once the job is finished.

{
  "description": "Finalize",
  "name": "finalize",
  "namespace": "customers-canvas",
  "type": "finalize",
  "finalArtifacts": [
    "print-file"
  ]
}

Attaching a rendering job configuration to product specifications

To attach a rendering job to a specification, you need to create the following entities:

1. A product reference based on a product specification.

   Using the endpoints ProductSpecifications_GetAll and ProductSpecifications_Get, you can get product specifications stored in your Customer's Canvas account.

   To bind a product to a specification, call the endpoint ProductReferences_Create.

2. A project based on a product reference and an order line item.

   To create a project, call the endpoint Projects_Create.

3. A rendering job based on tasks for a project.

   To create and run a job, call the endpoint RenderingJobs_Create.

Running the rendering jobs

Since rendering jobs automatically start executing after their creation, you do not need to run them. If for some reason you need to stop a job, use the RenderingJobs_Discard endpoint. You can then continue execution of the remaining tasks using the RenderingJobs_Recover endpoint. To restart a stopped job from the beginning, use RenderingJobs_Restart.

Browsing the rendering jobs

To browse them through the Rendering Service API, use the RenderingJobs_GetAll endpoint to retrieve the list of defined jobs for the specified owner or tenant. This endpoint supports filtering by job status and project ID.

For example, when browsing projects in your Customer's Canvas account in the Jobs section, the project list appears as follows:

To get properties of a single rendering job for the specified ID, user, and tenant, call RenderingJobs_Get. This endpoint returns the following properties of the rendering jobs:

• id - the job identifier.
• tenantId - the tenant identifier.
• ownerId - the owner identifier.
• project - the project description.
• tasks - the rendering task list.
• created - the rendering job creation time stamp.
• finished - the rendering job completion time stamp.
• status - the rendering job status.
• statusDescription - an error message, if any.