Skip to main content

Orchestration Components

Here are the main features of a DX Component:

  • may or may not use a Connection
  • can retrieve data directly from the backend system via the Connection or from other Orchestration Components
  • can be passed a real-time Context, which may be received from the client application or set by one of the other Orchestration Components
  • may or may not process business rules to drive aspects of the business logic based on the Context passed to it
  • can cache it's response to avoid unnecessarily calling backend APIs or process information that has already been processed
  • can manipulate and transform data received from various inputs
  • can be chained with other Orchestration Components

Note: Orchestration Components are NOT the same as UI Components. They may provide the data that can be consumed by the UI Component, but do not provide any HTML/CSS or any other framework specific code/markup.

Creating a Component

  1. Navigate to Manage Experiences > Experience Component.
  2. In the dashboard, select the “+” button to create a new Component.
  3. In the form modal, enter the following segment information:
    • Component Code: This is a unique name for the component
    • Component Name: A friendly name for the component
    • Component Description: A description of what the component does
    • Logo: The URL to a logo to be associated with the component
    • No Rules: Check this box if component will have no experience rules associated with italt_text
  4. In the Components Type field, type and select system this component should connect to and it's behaviour (i.e. static or dynamic component)
  5. Hit Submit

Component Configurations

All Orchestration Components have some sort of configuration that controls the Component's behaviour. For example, a Component may have configuration that will, for example:

  • select the content type in which to fetch specific content records
  • determine the search index to query
  • choose a promotion to offer
  • specify a value to transform
  • select a collection to write to
  • provide a list of products to remove from inventory
  • determine whether the component should do anything at all

To Configure a Component:

  1. Select the component from the list.
  2. Right click on the component and select "Update".

Many configurations can use values that are determined by it query-time via Expressions.

There are three different methods of specifying configuration values:

MethodDescription
Specific valueA hardcoded configuration value is specified within the Component at setup-time.
Context FieldThe configuration value is determined at query-time by using the value from the specified Context Field.
ExpressionThe configuration value is determined at query-time by evaluating an expression (which has access to all Context Fields and Component results)

There are a common set of configurations that all DX Engine Components have. Depending on the type of Component, there are configurations that are specific to a Component.

Common Configurations

NameAPI PropertyUses ExpressionsDescription
Context Field EnrichmentscontextFieldEnrichmentYesUses the Component's response to calculate values to be put into the Context for other Orchestration Components to reference. See details here.
Sub ComponentssubComponentsYesProvides a way to enrich each record in a Component's response with the results of other Component executions using custom Contexts. See details here.
CachedcacheConfig.cachedNoIf set to true, the responses of this Component will be cached. The default value is false.
Cache Time-to-livecacheConfig.cacheTtlNoThe number of seconds that cached responses will be cached.
Cache Tag ConfigurationcacheConfig.cacheTagsNoA list of tags that will be associated with the cached response. See details here
Trigger ExpressiontriggerYesThe default value is true.
Validity ExpressionvalidityYesThe default value is true.
Skip on Failed DependencyskipOnFailedDependencyNoThe component's execution is skipped if any of the components on which it depends, is in a FAILED state.
Skip on Skipped DependencyskipOnSkippedDependencyNoThe component's execution is skipped if any of the components on which it depends, is in a SKIPPED state.
Skip on Invalid DependencyskipOnInvalidDependencyNoThe component's execution is skipped if any of the components on which it depends, is in an INVALID state.
Note

The API Property is the corresponding property to update via the Management API.

Component-Specific Configuration

Component-specific configurations are dependent up on the specified Component Type of a Component. The available configurations for each Component are documented on that Component's documentation page. Note that some Component-specific configurations allow for the entry of an expression.

Expressions

Expressions allow for query-time evaluation of values using JavaScript syntax. Example: response.customerSegment and componentResponse('myComponent').

Depending on where and expression is used, it has access to different set of variables/functions.

All expressions have access to the following Javascript variables/functions:

Variable/FunctionDescription
_Lodash utility
encodeURINative Javascript function
encodeURIComponentNative Javascript function
JSONNative Javascript Object
ArrayNative Javascript Object
PromiseNative Javascript Object
ObjectNative Javascript Object
DateTimeDate and Time manipulation utility from the luxon library

The following sections list what variables/functions are available to expressions

Expression used for Component-specific query parameters

When a new Component Type is created such as Commercetools Dynamic Record List or Contentful Static Record List, specific parameters are made available to query these backends. For instance, a dynamic record list for Commercetools requires Category ID to be passed to Commercetools. You can also pass values such as Sort, Filter, etc.

Component Specific Query Parameters

Variable/FunctionDescriptionExample
contextField(contextField)Pass a value from the Context Field as a Query Parameter.contextField('categoryID')
componentResponse(componentCode)Pass a value from an upstream Component response as a Query Parameter_.castArray(componentResponse('fetchProductIDs').productIDs)
componentStatus(componentCode)Check to see if an upstream Component was processed successfullycomponentStatus('fetchProductIDs')

Expression used for Triggers

These expressions are evaluated to determine whether the current Component should be processed. The expression is expected to return a boolean value (true or false). However, if it returns a non-boolean value, the DX Engine will determine the Component's processing based on the 'truthiness' or 'falsiness' of that value. In JavaScript, certain values are inherently falsy (e.g., false, 0, "" (empty string), null, undefined, NaN), while all other values are considered truthy. This behavior allows for flexible expression evaluations in determining the processing logic of the Component.

Variable/FunctionDescriptionExample
contextField(contextField)Fetch the value of the Context Field by NamecontextField('location')==='US'
componentResponse(componentCode)Fetch the response of an upstream Component_.castArray(componentResponse('fetchProductIDs').productIDs).length > 0
componentStatus(componentCode)Check the status of an upstream ComponentcomponentStatus('callCustomerDatabase')==='VALID'

Expression used for Validity

These expressions check for the Validity of the response of the Component currently being processed. The expression is expected to return a boolean value (true or false). However, if it returns a non-boolean value, the DX Engine will determine the response validity on the 'truthiness' or 'falsiness' of the resulting value. In JavaScript, certain values are inherently falsy (e.g., false, 0, "" (empty string), null, undefined, NaN), while all other values are considered truthy.

Variable/Function
response
contextField(contextField)
componentResponse(componentCode)
componentStatus(componentCode)

Expression used for Context Field Enrichments

Context Fields are available to all Components that are to be processed within the scope of a single Experience API call. Each Component has the ability to update the Context of the query and all downstream Components will always read the most up to date value of the Context.

Variable/FunctionDescriptionExample
responseResponse of the current Component being processedresponse.customerSegment
contextField(contextField)Fetch the value of the Context Field by NamecontextField('categoryID')

Expression used for Sub Component

Variable/Function
response
Note

Component X becomes dependent upon Component Y when Component X uses any expression (anywhere within Component X's configurations) that contains:

  • uses contextField('someContextField') where someContextField is enriched by Component Y's Component Field Enrichments
  • uses componentResponse('componentB')
  • uses componentStatus('componentB')

Component Statuses

When a query is made to the DX Engine, all of the requested components are processed. The following flowchart describes the various states that a Component goes through.

Component Statuses

StateDescription
PROCESSINGA request to the DX Engine has occurred and this Component is part of fulfilling the reponse. Uses the Trigger expression to determine if it should run. If so, the Component is executed (enters the EXECUTING state). Otherwise, this Component will not be executed (enters SKIPPED state).
WAITING_FOR_COMPONENT_DEPENDENCIESWaits for any Orchestration Components on which it depends to be complete (either of the following states: VALID, FAILED, SKIPPED). Afterwards, the engine determines if the Component should be skipped. It will be skipped if any of the Skip on xxx Dependency (see this) checks are satisfied. Otherwise, the Component is executed (enters the EXECUTING state)
EXECUTINGThe Component logic is run. If any failure occurs during the execution, it enters FAILED state. Otherwise, the Component enters VALID state. If a Validity expression was specified, it is evaluated. If it evaluates to false, the state moves to INVALID.
SKIPPEDThe Component was not executed.
VALIDThe Component's response is valid.
INVALIDThe Component's response is not valid.

Orchestration

With Expressions and Component Statuses, the DX Engine allows for many complex real-time orchestration scenarios.

Context Field Enrichment

After a Component is executed and it is valid, it will process its Content Enrichments (if any). Take the following Context Field Enrichment configuration.

Context Field Enrichment

After this Component is run and get a response from whatever data source it is querying, it will evaluate each of the three expressions and puts the value into the request's context so that other Orchestration Components can use it. If a Context Field already exists, it will be overwritten.

If Component A references a Context Field that is enriched (via Context Field Enrichment) by Component B, then the DX Engine is aware that Component A dependent on Component B and will ensure that:

  • Component B is executed, even if it was not explicitly requested by the DX Engine Query.
  • Component B is executed BEFORE Component A is executed.

Sub Components

After a Component is executed and it is valid, it will process its Sub Components (if any). Take the following Sub Component configuration.

Sub Components

After this Component is run, it will:

  • Create a new Context that is a copy of the context available to the current Component with the addition of a new Context Field, actorIds. Note: This newly-created Context is only available to the specified Orchestration Components in the Sub Components configuration (actors).
  • Execute the the actors Component.
  • Add the response of the actors Component into the parent Component's response under the property, movieActors.

The Orchestration Components specified within another Component's Sub Component configuration may, themselves, have more Sub Components. There is no limit to this nesting. This "nested orchestration" is much like the possible nesting seen with GraphQL (but without the need to write resolver code!).


Display Templates

When records are displayed as part of an experience rule (or as part of a data grid in DX Graph), the look and feel of each record is controlled by the "display template". The display template is a snippet of HTML code that can contain elements of data combined with visual styling to make the record listing more visually friend to the business user.

alt_text

In the example above, the display template is defined to show elements of the record including the image, name and description.

Defining a Display Template

For 'Static' Components, you can configure a 'Display Template' to control the business user's editing experience. Here is how it's done:

  1. Navigate to the Components dashboard
  2. Select the experience component of interest
  3. Edit the component by selecting the update option from the right click menu.
  4. Under the "Options" portion of the component, find the "Display Template" section.
  5. Click on the code view("< >") button to bring up the HTML editor.
  6. Define the display template. Here, you can include HTML as well as attributes of the record using the {{myAttribute}} syntax.
  7. Once done, click the code view button again to visualize the record look and feel.
  8. Save the component

alt_text

In the example above, title, description and other attributes are defined as part of the display template. The actual name of the attribute will vary based on your collections schema mode. In most cases, the field code of the attribute can be used. If your target field is a nested field in the schema, simply define the path like in the example above.

Once the display template has been defined and saved, navigate back to the corresponding experience rule to see the updated look and feel of the records.

Sample Display Template

The following display template HTML generates the layout seen in the record list above with an image to the left and name and description to the right.

<div style="display:inline;text-align:left;">
<div style="display:inline;text-align:left;margin-right:20px;"><img src="{{Image_URL}}" height="75px" class="fr-fic fr-dii"></div>
<div style="vertical-align:top;display:inline-block;">
<div style="font-weight:600;font-size:1.5rem;margin-bottom:10px;">{{Name}}</div>
<div style="font-weight:400;font-size:1.2rem;margin-bottom:10px;">{{Header}}</div>
</div>
</div>

The DX Engine gives business users the ability to define what content should be seen by who, when and where. However, sometimes, you want to pass additional information to the calling application beyond the content or data fetched from external systems. Also, you want these options to be presented to the business user in an intuitive visual editor.

Using Component Attributes as Front-end Design Props

To empower digital teams to pass along additional information and directions to the frontend, the DX Engine offers Component Level Attributes. One of the use cases for Component Level Attributes is Design Props that the frontend could use to render itself. An example of this would be how you want the layout to be adjusted based on the context of the user. Or, it could be the styling that should be applied to the visual Component.

As an example, we have a Component that returns the hero banner. A business user may want to personalize the experience and show a full width banner in some cases but a split banner in other cases. This can be configured as an attribute. In this example, we'll call our attribute "layout" and setup the option for the user to select between "full width" and "split".

Setting Up Component Attributes

alt_text

  1. Navigate to the Components dashboard
  2. Select the experience Component of interest (in our case a hero banner Component)
  3. In the tab selector (top right), select the "Attribute Definition" tab
  4. Create a new attribute by clicking on the "Add another item" button
  5. For the attribute, give it a property, name and description. In our case, ours will be called "layout"
  6. Under the configuration, select "List"
  7. In the List of Values area, this is where you can define the options the user will be able to select from as well as the properties of each option. We'll define an option for boxed, fullwidth and split (side by side). For each, we'll give it a display name, image and description. These will be used in the next step.
  8. In the Template part of the configuration, we can define how the defined options will show up visually. Here we'll define an HTML snippet that shows an image and name for each option.
  9. Save the Component

Selecting an Attribute Option

Once the attribute definition(s) are setup, they automatically appear in the Experience Rule as part of the target experience section. Here you can see the options we setup.

alt_text

Using the Attributes

In the Component response, attributes are returned as part of the @extras section. This can be used by the front-end to drive additional behaviour related to the attribute.

alt_text

Types of Attributes

In order to provide user friendly editor experience for non-technical users, the DX Engine offers several types of Attributes:

NameDescription
TextPrompts the user to enter some text value. There is formatting for: JavaScript, JSON, Handlebars, Markdown, HTML
NumberPrompts the user to enter a numeric value.
CheckboxPrompts the user to check or uncheck a checkbox. This satisfies Yes/No; On/Off
Manual PicklistPrompts the user to pick a value from a dropdown. The available values are manually-provided during the configuration of a Component.
Component Response PicklistPrompts the user to pick a value from a dropdown. The available values are dynamically fetched from some other source using another Component. This allows you to fetch values, for example, another webservice or a delimited file from an S3 bucket.
Manual ListPrompts the user to re-order a list of values. The available values are manually-provided during the configuration of a Component
Component Response ListPrompts the user to re-order a list of values. The available values are dynamically fetched from some other source using another Component.

Common Component Attribute Configurations

Each Attribute has the following common configurations:

NamePropertyDescription
Attribute PropertyattributePropertyThe name of the property in the Component's JSON response that will store the value of the Attribute.
Attribute NameattributeNameThe display name of the Attribute when displayed to the business user.
Attribute DescriptionattributeDescriptionThe description of the Attribute when displayed to the business user.
Attribute RequiredattributeRequiredWhether the Attribute is required or optional.
Attribute TypevalueConfig.typeHow the value of the Attribute should be collected from the business user.

Component Attribute Configurations based on Attribute Type

Depending on the Attribute Type, the Attribute may have additional configurations.

NamePropertyDescription
Default Text ValuedefaultTextValueThe default value of the Attribute when the business user is setting up rules for a Component. This is only valid when Value Type is Text.
Default Number ValuedefaultNumberValueThe default value of the Attribute when the business user is setting up rules for a Component. This is only valid when Value Type is Number.
Default Checkbox ValuedefaultCheckboxValueThe default value of the Attribute when the business user is setting up rules for a Component. This is only valid when Value Type is Checkbox.
List of ValuesvalueConfig.listA hardcoded list of available values for the Attribute. The specified value is a JSON array of objects where each object must have a property called value. The value property is used to store the value of the Attribute. Each object may any other number of properties. These properties are used to display the available values to the business user in the UI using a Display Template. This is only valid when Value Type is Manual Pick List or Manual List.
Component CodevalueConfig.componentCodeThe code of the Component that will be used to retrieve the available values for the Attribute. This is only valid when Value Type is Component Response Pick List or Component Response List.
Display TemplatevalueConfig.displayTemplateA Handlebars HTML template used to display the available values to the business user in the UI. This is only valid when Value Type is Manual Pick List, Manual List, Component Response Pick List or Component Response List.

When hardcoding a list of available values for a Attribute (i.e. Value Type is Manual Pick List or Manual List), the specified value is a JSON array of objects where each object must have a property called value. The value property is used to store the value of the Attribute. Each object may any other number of properties. These properties are used to display the available values to the business user in the UI using a Display Template. The Display Template is specified as a Handlebars HTML template.

When retrieving a list of available values for a Attribute from another Component (i.e. Value Type is Component Response Pick List or Component Response List), the Component Code of the Component that will be used to retrieve the available values must be specified. The result of the Component must be in the format desribed in List of Values. The Display Template is specified as a Handlebars HTML template.

Example of List of Values

[
{
"value": "layout01",
"name": "Layout One",
"logoUrl": "https://images.com/layout-01.png"
},
{
"value": "layout02",
"name": "Layout Two",
"logoUrl": "https://images.com/layout-02.png"
},
{
"value": "layout03",
"name": "Layout Three",
"logoUrl": "https://images.com/layout-03.png"
},
{
"value": "layout04",
"name": "Layout Four",
"logoUrl": "https://images.com/layout-04.png"
}
]