What are Workflow Elements

Last updated on August 1, 2024
•
6 minutes to read

Workflow Elements represent a format of workflow files that allows you to configure such components as the Handy Editor, Simple Editor, and CC Options.

Structure

All elements have a similar structure. To define a workflow element, you describe their Input, Output, Resources, and Settings:

Input describes the resources that are processed and recycled by the element: designs, mockups, and PIM products including variants.
Output is the processed resources, which usually serve as input data to the next element of the process: changed design and, if there is an option selector, then the variant is also changed.
Resources describe the rules and folder paths for processing assets.
Settings are a set of feature flags and configurations that change the behavior of design elements.

For example, a workflow file with the Handy Editor may look as follows:

{
    "configVersion": 2,
    "component": "handy-editor",
    "tagName": "au-handy-editor",
    "settings": {
        "designViewer": {
            "grid": {
                "gridEnabled": true
            }
        }
    },
    "resources": {
        "assetLibrary": {
            "clipartsFolder": "Clipart",
            "imagesFolder": "Images"
        }
    }
}

For more details about creating workflow files and their format, refer to the Help Center.

How does it work?

First, you create a workflow in your application based on your personalization process. When the user starts personalization, you can search this workflow for the workflow element that will be displayed in a personalization step, for example, Handy Editor. On the page where you implement the integration:

Insert links to the script and styles of the workflow element.
Define the configuration parameters.
Add the code loading the element into the page.
Handle the results.

After completing the personalization step, you take the output data. If another workflow element is needed on the next step, you can search for it in the same workflow file and initialize it in the same way. The data obtained in a workflow element can be conveyed to the next element.

Integrating workflow elements

To get a workflow, you request its configuration specified for a product by using the endpoint Products_GetPersonalizationWorkflow as described in Opening products for editing. When it is received from the backend, you can save it in a workflowFile object.

If you know in advance that a specific component is guaranteed to be in a workflow file, you can create the style and script tags statically or from the backend. This will speed up the loading of the editor by loosing a certain flexibility, since the scripts will be loaded immediately, without waiting for the workflow file from your Customer's Canvas tenant. Let's look at how you can integrate workflow elements dynamically.

1. Insert links to the script and styles

First, form the base address to the element as follows:

https://staticjs-aurigma.azureedge.net/libs/{environment}/workflow-elements/{component}

For example, for the Handy Editor on a US tenant, this will be:

https://staticjs-aurigma.azureedge.net/libs/us/workflow-elements/handy-editor

Important

Specify the correct version of the environment. If you specify US for an EU tenant, and different versions of the Personalization Platform will be deployed to these environments, the editor may fail to open designs due to different versions of Design Atoms.

Then, add the index.js script and the default styles styles.css to the base address.

const baseUrl = "https://staticjs-aurigma.azureedge.net/libs/us/workflow-elements/" + workflowFile.component;

// Dynamically add styles.css
const stylesUrl = `${baseUrl}/styles.css`;
const stylesElement = document.createElement("link");
stylesElement.href = stylesUrl;
stylesElement.rel = "stylesheet";
document.head.appendChild(stylesElement);

// Dynamically add the script
const scriptUrl = `${baseUrl}/index.js`;
const scriptElement = document.createElement("script");
scriptElement.src = scriptUrl;
document.head.appendChild(scriptElement);

2. Define the configuration parameters

Additionally to the parameters defined in a workflow file, you need also to provide your integration and input parameters.

Defining the integration parameters, you pass the identifiers of your tenant, storefront, and user and URLs that link to Customer's Canvas BackOffice and API Gateway.

{
    "integration": {
        "tenantId": 12345,
        "storefrontId": 123456,
        "cchubApiGatewayUrl": "https://api.customerscanvashub.com/",
        "user": {
            "id": "john.wood",
            "token": "fcmVhZCIsIlN0b3JlZnJvbnRVc2Vyc19mdWxsIiwiU3R..."
        }
    }
}

The input is provided depending on the Customer's Canvas integration type. For example, for the Handy Editor:

If you need to open a PIM product by ID and its specific product variant by ID, then fill in the productId and productVariantId.
If you integrate a workflow element into a standard e-commerce solution (Shopify, WooCommerce, etc.), then pass the productReference to it.
If you upload only a design, then pass the designTemplateId.

You can get these parameters in your Customer's Canvas tenant.

The basic case is using the PIM module and passing a product variant. Generate them on the backend and provide as the following object.

{
    "input": {
        "productId": 402,
        "productVariantId": 358246
    }
}

3. Load the element

After getting the tag name from your workflow file, you can add a container tor the element to the page.

const tagName = workflowFile.tagName; // For example, "au-handy-editor"
const container = document.getElementById('editor-parent-div'); // "<div>" that will contain the workflow element
container.appendChild(document.createElement(tagName));

You can save an instance of the created element to initialize it later. You can also get it through document.getElementsByTagName. Note that you can call methods of the Web component only when the script has loaded.

scriptElement.onload = () => {
    const workflowElement = document.getElementsByTagName(tagName).item(0);
};

To load and initialize an element, pass configuration parameters to the init method.

workflowElement?.init({
    configVersion: workflowFile.configVersion,
    component: workflowFile.component,
    input: {
        productId: 402,
        productVariantId: 358246
    },
    integration: {
        tenantId: 12345,
        storefrontId: 123456,
        ...
    }
    settings: workflowFile.settings,
    resources: workflowFile.resources
});

4. Handle the results

Workflow Elements communicate by releasing events. To handle an event, you must subscribe to it.

For example, the Handy Editor triggers the addToCart event when the customer finishes their customization and adds the product to a shopping cart. This event passes the data corresponding to a line item — a single product added to the cart. This is how you can handle this event:

handyEditor.addEventListener("addtocart", event => {
    const cartItem = event.detail;
    console.log(cartItem);
});

Multiple workflow elements

A workflow file may contain several elements. For example, you may want to describe an integration where CC Options is embedded into the product page, the Handy Editor is on the editor's page, and there is a Cart element on the shopping cart page.

Then you may have a workflow file with the following structure.

[
  { component: 'handy-editor', settings: { ... }, ... },
  { component: 'cc-options', settings: { ... }, ... },
  { component: 'cart', settings: { ... }, ... }
]

For multiple workflow elements, you need additional code that parses the workflow file and then adds scripts, defines configuration parameters, and loads these elements according to your personalization process.

When implementing integration, you can request a workflow file on each page. As an alternative, you can request the file only for the first page and then pass it between pages through localStorage or another mechanism.

On the product page, look for an element corresponding to the cc-options component. On the editor's page, look for the handy-editor. On the cart page, look for the cart, etc. Initialize them in the same way as described above for a single component.