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:
Method | Description |
---|---|
Specific value | A hardcoded configuration value is specified within the Component at setup-time. |
Context Field | The configuration value is determined at query-time by using the value from the specified Context Field. |
Expression | The 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
Name | Property | Uses Expressions | Description |
---|---|---|---|
Context Field Enrichments | contextFieldEnrichment | Yes | Uses the Component's response to calculate values to be put into the Context for other Components to reference. See details here. |
Sub Components | subComponents | Yes | Provides a way to enrich each record in a Component's response with the results of other Component executions using custom Contexts. See details here. |
Cached | cached | No | If set to true , the responses of this Component will be cached. The default value is false . |
Cache Time-to-live | cacheTtl | No | The number of seconds that cached responses will be cached. |
Trigger Expression | trigger | Yes | The default value is true . |
Validity Expression | validity | Yes | The default value is true . |
Skip on Failed Dependency | skipOnFailedDependency | No | The component's execution is skipped if any of the components on which it depends, is in a FAILED state. |
Skip on Skipped Dependency | skipOnSkippedDependency | No | The component's execution is skipped if any of the components on which it depends, is in a SKIPPED state. |
Skip on Invalid Dependency | skipOnInvalidDependency | No | The component's execution is skipped if any of the components on which it depends, is in an INVALID state. |
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/Function | Description |
---|---|
_ | Lodash utility |
encodeURI | Native Javascript function |
encodeURIComponent | Native Javascript function |
JSON | Native Javascript Object |
Array | Native Javascript Object |
Promise | Native Javascript Object |
Object | Native 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 |
Component X becomes dependent upon Component Y when Component X uses any expression (anywhere within Component X's configurations) that contains:
- uses
contextField('someContextField')
wheresomeContextField
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.
State | Description |
---|---|
PROCESSING | A 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_DEPENDENCIES | Waits 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) |
EXECUTING | The 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 . |
SKIPPED | The Component was not executed. |
VALID | The Component's response is valid. |
INVALID | The 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.
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.
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!).