Skip to main content

Anatomy of a DX Engine Component

A Component performs one of the following:

  • Reads from a data source
  • Writes to a data target (which may or may not act as a data source for other Components)
  • Modify data that was read from a data source
  • Modify data that was from the result of another Component

Component Configurations

All 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

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

NamePropertyUses ExpressionsDescription
Context Field EnrichmentscontextFieldEnrichmentYesUses the Component's response to calculate values to be put into the Context for other 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.
CachedcachedNoIf set to true, the responses of this Component will be cached. The default value is false.
Cache Time-to-livecacheTtlNoThe number of seconds that cached responses will be cached.
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 Property column list the compondng 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. Expressions are entered as strings that surrounded in backticks. 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

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

Expression used for Component-specific configurations

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

Expression used for Triggers

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

Expression used for Validity

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

Expression used for Context Field Enrichments

Variable/Function
response
contextField(contextField)

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 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 Content 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 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 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 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!).