Skip to main content

Global Step Properties

When operating on large numbers of workflow experiences within a bundle it can be convenient to change certain values across all steps at once.

Global configuration can be built to specify properties that may be modified across all steps in a bundle. These properties may be applied to steps within a workflow and once applied, the step will inherit the value of the property when changes are made globally at the bundle level.

Check if global properties are available.​

To see if properties are available we have a convenience function available for you. Global properties resolve in an asynchronous matter so we need to await the result.

const hasGlobalProperties = await bundle.hasGlobalProperties();

Getting global properties​

Once you're ready to display or manipulate the global properties you may do so via the following interface. Again, you must await the result. This function will resolve to a list of GlobalPropertyHandle objects.

const globalProperties = await bundle.getGlobalProperties();

There is a number of generic fields and functions available on the GlobalPropertyHandle object. Their usage is shown below.

const property = globalProperties[0];

const name = property.getName(); // Returns the name of the property

const description = property.getDescription(); // Returns the description of the property

const type = property.getType(); // Returns the type of the property

If you need to implement more concrete behaviors such as setting data relating to the property you need to cast it to the appropriate type as the behavior will differ depending on the type of property.

const type = property.getType(); // Returns the type of the property
switch (type) {
    case AspectType.FileUpload:
        const fileUploadProperty = property as FileUploadGlobalPropertyHandle;
        // Do something with the file upload property
        break;
    case AspectType.Option:
        const optionProperty = property as OptionGlobalPropertyHandle;
        // Do something with the text property
        break;
}

Handling conditional properties​

Some properties may be conditional. When a property is updated, the selections made by the user may cause other properties to become available. To handle this, you may listen for the conditional-global-properties-changed event on the bundle. The event object, a BundleEvent, will contain a data property that contains the new list of global properties.

note

Calling getGlobalProperties will always return a filtered list of properties based on the current selections. This event is only necessary if you need to update the list of properties in your UI.

bundle.addEventListener("conditional-global-properties-changed", (e: BundleEvent) => {
    const data = e.data as ConditionalGlobalPropertiesChangedEventData;
    const properties = data.globalProperties;
    // Do something with the new list of properties
});

File Upload Properties​

The file upload property allows you to set an image across multiple frame steps. Assets are provided in the same format as what the frame step requires. To upload and retrieve image assets, see User Assets. You may await the image selection to know when all workflow experiences have been updated with the given asset.

const fileProperty = property as FileUploadGlobalPropertyHandle;

await fileProperty.selectImage(asset);

Background Remover​

The file upload property provides the ability to remove the background from a supplied raster image. Note that this feature is restricted to Partners who have the Background Remover addon.

// Check that an image has been supplied.
const hasBaseImage = (await fileProperty.getOriginalImage()) !== undefined;
// Ensure the Partner has access to the feature.
const canRemoveBackground = (await fileProperty.canUseBackgroundRemover()) && hasBaseImage;

// Note that this value clears whenever the original image changes.
const hasBgRemovedAsset = (await fileProperty.getBackgroundRemovedImage()) !== undefined;

// Whether the user has opted to prefer the original over the BG-removed asset.
// This will default to false, but is irrelevant until the BG-removed is available.
const useOriginalImage = fileProperty.getUseOriginalImage();

const updateUseOriginalImage = async (value: boolean) => {
    // This will apply the image if necessary, and will throw if the requested image type is missing.
    await fileProperty.setUseOriginalImage(value);
};

const removeBackground = async () => {
    if (!hasBaseImage) {
        return;
    }
    if (hasBgRemovedAsset) {
        // Already has image with bg removed, so just swap to it locally.
        updateUseOriginalImage(false);
        return;
    }
    // Removes the background from the original/base image and applies it to the state.
    await fileProperty.removeBackgroundFromImage();
};

// ... UI controls ...

Option Properties​

The option property allows you to select a variant across multiple steps. You may await the variant selection to know when all workflow experiences have been updated with the given variant. The interface for this property is similar to the interface on Step Handles.

const optionProperty = property as OptionGlobalPropertyHandle;

const currentVariant = optionProperty.getCurrentVariant(); // Returns the current variant

const availableVariants = optionProperty.getAvailableVariants(); // Returns the list of available variants

const variants = optionProperty.getAllVariants(); // Returns the list of variants

await optionProperty.selectVariant(variant); // Selects the given variant

Color Option Properties​

The color option property allows you to select a variant across multiple steps. They differ from the option property by adding two additional functions. getCustomerColor & setCustomColor. This option is specially designed for color selection and can exist alongside a normal option property on the same step.

You may access the same functions on the option variant above as this is an extension of that class.

const optionProperty = property as ColorOptionGlobalPropertyHandle;

await optionProperty.selectVariant(variant); // Selects the given variant

const color = getCustomColor(); // Returns the custom color

Text Properties​

The text property allows setting text content across multiple text steps.

const textProperty = property as TextGlobalPropertyHandle;

await textProperty.selectText("Go Wildcats!");