Bundles

info

This feature is currently in the process of being rolled out. As such, certain interfaces may change.

Bundles are currently an enterprise only feature. If you are interested in learning more about bundles, please contact your account manager.

A bundle acts as an extra abstraction layer on top of workflow experiences. The intent is to give you a set of tools for operating on transactions at scale. Allowing you to set shared settings while also providing access to the underlying transactions.

Creating a new bundle

To create a bundle, you'll need to call getNewBundle on the client. This will return a bundle object, which you will use to interact with the bundle.

const bundle = await client.getNewBundle();

Reloading an existing bundle

You can retrieve the bundle ID from the bundle object. This can be used to reload the bundle at a later time.

const bundleId = bundle.getId(); // Save this somewhere.

And to reload the bundle:

const bundle = await client.getExistingBundle(bundleId);

Duplicating an existing bundle

In order to duplicate an existing bundle, the current context must have access to it. The customer must be Authenticated and a Stakeholder of the bundle.

const duplicatedBundle = await client.duplicateBundle(
  bundleId, // The id of the bundle to duplicate
  undefined, // Optional: [boolean] Whether you wish the new duplicate to be marked as a template. Default is false
  undefined, // Optional: [boolean] Whether you wish to also duplicate the transactions linked to the original bundle. Default is true.
  undefined, // Optional: [object] Additional options
)

Adding & Removing Workflow Experiences

info

Version 14.10.0 introduced the ability to add multiple workflow experiences at once. If you wish to add multiple workflow experiences, it is recommended to use the new functions instead of calling addWorkflowExperience multiple times.

First load a workflow experience as normal (see Getting Started for more information). Then call addWorkflowExperience on the bundle object, or removeWorkflowExperience to remove it.

The user must have write access to the workflow experience, and the bundle, in order to add it to a bundle. Only write access to the bundle is required to remove a workflow experience.

// Add the workflow experience to the bundle.
await bundle.addWorkflowExperience(workflowExperience);

// Remove the workflow experience from the bundle.
await bundle.removeWorkflowExperience(workflowExperience);
// Or, if you have the transaction
await bundle.removeWorkflowExperienceByTransaction(transaction);

Adding & Removing Multiple Workflow Experiences

If you want to add or remove multiple workflow experiences at once, you can use addWorkflowExperiences and removeWorkflowExperiences respectively. It is recommended to use these functions instead of calling addWorkflowExperience or removeWorkflowExperience multiple times, as fewer requests will be made to the server.

The ability to create multiple workflow experiences is available for this use-case, and is recommended over calling getWorkflowExperience multiple times. See Requesting Multiple Workflow Experiences for more information.

// Add multiple workflow experiences to the bundle.
await bundle.addWorkflowExperiences([workflowExperience1, workflowExperience2]);

// Remove multiple workflow experiences from the bundle.
await bundle.removeWorkflowExperiences([workflowExperience1, workflowExperience2]);
// Or, if you have the transactions
await bundle.removeWorkflowExperiencesByTransactions([transaction1, transaction2]);

Inserting Workflow Experiences

You can also insert a workflow experience at a specific index in the bundle. This can be done by calling insertWorkflowExperience on the bundle object, and passing the index you wish to insert at. If you intend to insert the workflow experience at the end of the bundle, it's recommended to use addWorkflowExperience instead as fewer requests will be made to the server.

// Insert the workflow experience at index 0.
await bundle.insertWorkflowExperience(workflowExperience, 0);

Updating Workflow Experiences

When you have a bundle loaded, workflow experiences can be updated as normal. Access permissions will be checked against the bundle, rather than the workflow experience. See Workflow Experience for more information.

Submitting an Order

When you're ready to submit an order the flow is similar to submitting a transaction, except you'll pass the bundle ID instead of the transaction ID in the OrderItemInput object.

3D Preview

To use a bundle with a preview service, you can either inject each Workflow Experience manually at your own discretion (see Injecting a Workflow Experience), or you can associate an entire bundle with a preview service.

When you get a new bundle, this will need to be done manually after creation by calling setPreviewService on the bundle object. Calling this function on a bundle that has workflow experiences will cause all workflow experiences to be re-injected into the preview service.

If you want to eject all workflow experiences from the preview service, you can call setPreviewService with no arguments, or pass null or undefined.

note

When a bundle has a preview service associated with it, the injection and ejection of workflow experiences will be handled automatically. You may still manually inject and eject workflow experiences if you wish, but this is not required.

await bundle.setPreviewService(previewService);

You can also specify a preview service when retrieving an existing bundle.

const bundle = await client.getExistingBundle(bundleId, previewService);

Listening for hover events

You can listen for mouse hover events on workflow experiences in the 3D preview by calling addEventListener on the bundle object, and passing a callback to the workflow-experience-hover-enter and workflow-experience-hover-exit events. The callback can be removed by calling removeEventListener with the same arguments.

This event will be a BundleEvent with the data property being a WorkflowExperienceHoverEventData object.

note

This event will only be fired when Material highlighting is enabled.

const callback = (event) => {
  // Do something when the user hovers over a workflow experience.
};
bundle.addEventListener("workflow-experience-hover-enter", callback);
bundle.removeEventListener("workflow-experience-hover-enter", callback);

Positioning Workflow Experiences

Using Bundles exposes the ability to position workflow experiences in the 3D preview. This can be done by calling updateWorkflowExperienceTransform to assign a name to a transform, then calling activateWorkflowExperienceTransform to make that transform active. These functions takes the Workflow Experience you wish to position, while a transform is an object containing position, rotation and scale properties, with each of these properties containing x, y and z values. Take note that the rotation value is in degrees.

These functions update the state on the server, so you should await the result before continuing.

const transform = {
  position: { x: 0, y: 0, z: 0 },
  rotation: { x: 0, y: 0, z: 0 },
  scale: { x: 1, y: 1, z: 1 },
};
await bundle.updateWorkflowExperienceTransform(workflowExperience, "default-position", transform);
await bundle.activateWorkflowExperienceTransform(workflowExperience, "default-position");

Any changes made to the WorkflowExperience's transform will be reflected in the 3D preview. This state will also automatically be applied whenever setPreviewService is called, and when a bundle is reloaded from the server.