Digging Deeper into the DX Engine

Now that you have familiarized yourself with the sandbox environment, you are ready to do a deeper dive into the DX Engine. So far, you have worked with Orchestration Component Types that are pre-built such Contentful and Commercetools and you have configured them. In this tutorial, we are going to use Conscia's Universal API Connector to fetch and orchestrate data and content. This will show you how the DX Engine allows you to connect to any backend system and perform a read or write.

Specifically, we'll be reading movie and actor data along with users' genre preferences from a RESTful webservice.

By the end of this quickstart, you will understand:

How to use the Universal API Connector Component
How the DX Engine performs orchestration without writing and building code
How to use Context to pass in real-time information
How to group Orchestration Components into an Orchestration Template

The movie data source

Endpoints

The following table outlines how to interact with the webservice.

Endpoint	Description
`GET https://sample-data.conscia.ai/api/collections/collection-movie?_limit=10`	Fetch a list of 10 movies.
`GET https://sample-data.conscia.ai/api/collections/collection-actor?_limit=5`	Fetch a list of 5 actors.
`GET https://sample-data.conscia.ai/api/collections/collection-movie?_limit=10&_id=tt8254452`	Fetch a specific movie by its ID.
`GET https://sample-data.conscia.ai/api/collections/collection-movie?_limit=10&_id[]=tt8254452&_id[]=tt8255690`	Fetch multiple movies using IDs.
`GET https://sample-data.conscia.ai/api/collections/collection-movie?_limit=10&_query=primaryTitle:love`	Search for movies with a specific keyword in the title.
`GET https://sample-data.conscia.ai/api/collections/collection-movie?_limit=10&_query=genres:horror`	Search for movies with a specific genre.
`GET https://sample-data.conscia.ai/api/collections/collection-user?_limit=5`	Fetch a list of 5 users.
`GET https://sample-data.conscia.ai/api/collections/collection-user?_id=tony@iron.com`	Fetch a specific user.
`GET https://sample-data.conscia.ai/api/collections/collection-user?_query=favouriteGenre:horror`	Fetch users who prefer horror.

Record Structures

Movie

{
  "id": "tt8254452",
  "titleType": "movie",
  "primaryTitle": "The Marvin Case",
  "originalTitle": "The Marvin Case",
  "startYear": 2018,
  "runtimeMinutes": 70,
  "isAdult": false,
  "genres": [
    "comedy"
  ],
  "directors": [
    "nm3778312"
  ],
  "writers": [
    "nm3778312"
  ],
  "actors": [
    "nm1175179",
    "nm6339953",
    "nm4268373",
    "nm3799576",
    "nm6201108",
    "nm4969745",
    "nm1260396",
    "nm1458739"
  ]
}

Actor

{
  "id": "nm0990876",
  "primaryName": "Daniel Chaia",
  "birthYear": null,
  "deathYear": null,
  "primaryProfession": [
    "assistant_director",
    "writer",
    "actor"
  ]
}

Users

{
  "id": "tony@marvel.com",
  "favouriteGenre": "comedy"
}

Setting up a connection to the Sample Data Webservice

First we will create a Connection to the webservice we're going to call.

Navigate to the Connections page (Settings --> Connections).
Click the Add Connection button.
Enter the following and click Submit.

Field	Value
Connection Code	sample-data-connection
Connection Name	Conscia Sample Data Connection
Connector	Universal API Connector
Base URL	Get value from: Literal `https://sample-data.conscia.ai/api`

Fetching movies

We will setup a Component to fetch movies with a hardcoded limit of 5.

Navigate to the Experience Components page (Manage Experiences --> Components).
Click the Add Component button.
Enter the following and click Submit.

Field	Value
Component Code	movies
Component Name	Movies
No Rules	Checked
Component Type	Conscia - Universal API Connector

The DX Engine will create and prepare the Component for further configuration. You will see the Movies Component appear in the Component listing.

Click the Edit icon.
Enter the following and click Submit.

Field	Form Tab	Value	Description
Connection	Main	Conscia Sample Data Connection
Webservice Path	Main	Get value from: Literal /collections/collection-movie
Method	Main	GET
Headers	Main	Header: `content-type` Value: Get value from: Literal `application/json`	Under Headers, click `Add another item` in order to add a header. Under Get value from..., select `Specified value` in order to enter a value manually. Selecting `Context Field` or `Expression` would allow this value to be calculated and/or specified at query-time instead of setup time.
Query Parameters	Main	Parameter: `_limit` Value: Get value from: Literal `5`	Under Query Parameters, click `Add another item` in order to add a query parameter.

Now that the Component has been fully configured, let's query the DX Engine to see the results so far.

You can make a direct API call like this:

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["movies"],
  "context": {}
}

Or you can navigate to the Developer Tools page (Developer Tools --> Debug | Execution) and use the Experience Studio UI to run your query.

Select the "Movies" Component.
Click "Execute Component(s)".

"Movies Debugger"

The results will look like this:

{
  "duration": 585,
  "components": {
    "movies": {
      "status": "VALID",
      "response": [
        {
          "id": "tt8246150",
          "titleType": "movie",
          "primaryTitle": "Knife Blood Pt.2",
          "originalTitle": "Knife Blood Pt.2",
          "startYear": 2018,
          "runtimeMinutes": -1,
          "isAdult": false,
          "genres": [
            "horror"
          ],
          "directors": [
            "nm6984708"
          ],
          "writers": [],
          "actors": [
            "nm6787892",
            "nm4342385",
            "nm4088112",
            "nm6545691",
            "nm4044554"
          ]
        },
        {
          "id": "tt8250078",
          "titleType": "movie",
          "primaryTitle": "Sink",
          "originalTitle": "Sink",
          "startYear": 2018,
          "runtimeMinutes": 7,
          "isAdult": false,
          "genres": [
            "drama"
          ],
          "directors": [
            "nm9757557"
          ],
          "writers": [
            "nm8337244"
          ],
          "actors": [
            "nm0692305",
            "nm5073992",
            "nm0936087",
            "nm9757554",
            "nm9757555"
          ]
        },
        {
          "id": "tt8251336",
          "titleType": "movie",
          "primaryTitle": "No One Will Ever Know",
          "originalTitle": "Nadie sabrá nunca",
          "startYear": 2018,
          "runtimeMinutes": 102,
          "isAdult": false,
          "genres": [
            "drama"
          ],
          "directors": [
            "nm2571065"
          ],
          "writers": [
            "nm2571065"
          ],
          "actors": [
            "nm2578315",
            "nm2784856",
            "nm1173803",
            "nm0709204"
          ]
        },
        {
          "id": "tt8252898",
          "titleType": "movie",
          "primaryTitle": "The Man in the Mask",
          "originalTitle": "The Man in the Mask",
          "startYear": 2018,
          "runtimeMinutes": -1,
          "isAdult": false,
          "genres": [
            "documentary"
          ],
          "directors": [
            "nm3691317",
            "nm5692167"
          ],
          "writers": [
            "nm3691317",
            "nm5692167"
          ],
          "actors": []
        },
        {
          "id": "tt8254452",
          "titleType": "movie",
          "primaryTitle": "The Marvin Case",
          "originalTitle": "The Marvin Case",
          "startYear": 2018,
          "runtimeMinutes": 70,
          "isAdult": false,
          "genres": [
            "comedy"
          ],
          "directors": [
            "nm3778312"
          ],
          "writers": [
            "nm3778312"
          ],
          "actors": [
            "nm1175179",
            "nm6339953",
            "nm4268373",
            "nm3799576",
            "nm6201108",
            "nm4969745",
            "nm1260396",
            "nm1458739"
          ]
        }
      ]
    }
  }
}

The top-level property components will be an object with one child property for each configured Component. Each Component's property will contain: status, response and error (if an error was encountered). The response property should contain 5 movie records.

Fetch movies with a hardcoded genre

Now we will filter the movies further by genre.

Click on the Edit icon on the Movies component.
Enter the following and click Submit.

Field	Form Tab	Value	Description
Query Parameters	Main	Parameter: `_query` Value: Get value from: Literal `genres:horror`	Under Query Parameters, click `Add another item` in order to add a query parameter.

Query the DX Engine to see the results via the API:

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["movies"],
  "context": {}
}

Or use the Developers Tools page to run your query:

Select the "Movies" Component.
Click "Execute Component(s)".

The returned movies should now be all horror movies.

Fetch movies with a genre specified at query-time

Instead of hard-coding the genre, we will allow the genre to be sent at query-time using the Context in the body of every DX Engine request.

Click on the Edit icon on the Movies Component.
Enter the following and click Submit.

Field	Form Tab	Value	Description
Query Parameters	Main	Parameter: `_query` Value: Get value from: JS Expression `'genres:' + contextField('genre')`	Since this is a `JS Expression`, the engine will evaluate the specified expression at query-time. The `contextField` function in the expression informs the engine to grab the value from the Context field called `genre` and append it the string `genres:`.

Query the DX Engine via the API with a Context that specifies genre = comedy to see the results:

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["movies"],
  "context": {
    "genre": "comedy"
  }
}

Or use the Developers Tools page to run your query:

Select the "Movies" Component.
In the Context field enter: {"genre": "comedy"}.
Click "Execute Component(s)".

You should see 5 comedy move records returns. Try this with different genres such as: drama, short, western...

Fetch a user

Setup a Context Field to hold a user id.

Navigate to the Context Fields page (Settings --> Context Fields).
Click the Add Context Field button.
Enter the following and click Submit.

Field	Value
Context Field Name	userId
Display Name Name	User ID
Data Type	String

We will setup a Component to fetch a user based on a user id.

Navigate to the Components page (Manage Experiences --> Components).
Click the Add Experience Component button.
Enter the following and click Submit.

Field	Value
Component Code	user
Component Name	User
No Rules	Checked
Component Type	Conscia - Universal API Connector

The DX Engine will create and prepare the Component for further configuration. You will see the 'User' Component appear in the Component listings.

Click the Edit icon.
Enter the following and click Submit.

Field	Form Tab	Value	Description
Connection	Main	Conscia Sample Data Connection
Webservice Path	Main	/collections/collection-user
Method	Main	GET
Headers	Main	Header: `content-type` Value: Get value from: Literal `application/json`	Under Headers, click `Add another item` in order to add a header. Under Get value from..., select `Specified value` in order to enter a value manually. Selecting `Context Field` or `Expression` would allow this value to be calculated and/or specified at query-time instead of setup time.
Query Parameters	Main	Parameter: `_id` Value (Context Field): `User ID`	Under Query Parameters, click `Add another item` in order to add a query parameter.

Let's query the DX Engine to fetch a user with the ID pepper@iron.com.

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["user"],
  "context": {
    "userId": "pepper@iron.com"
  }
}

Or use the Developers Tools page to run your query:

Select the "User" Component.
In the Context field enter: {"userId": "pepper@iron.com"}.
Click "Execute Component(s)".

The result should look like this:

{
  "duration": 531,
  "components": {
    "user": {
      "status": "VALID",
      "response": [
        {
          "id": "pepper@iron.com",
          "favouriteGenre": "horror"
        }
      ]
    }
  }
}

Querying for multiple components

Let's say we would like to get the results of both the movies and user Component using one query. There are two methods to query multiple Components with one request.

Submitting a Component Query with a list of components

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["user", "movies"],
  "context": {
    "userId": "pepper@iron.com",
    "genre": "drama"
  }
}

Or use the Developers Tools page to run your query:

Select the "Movies" Component and the "User" Component.
In the Context field enter: {"userId": "pepper@iron.com", "genre": "drama"}.
Click "Execute Component(s)".

The reponse will look this:

{
  "duration": 198,
  "components": {
    "user": {
      "status": "VALID",
      "response": [
        {
          "id": "pepper@iron.com",
          "favouriteGenre": "horror"
        }
      ]
    },
    "movies": {
      "status": "VALID",
      "response": [
        {
          "id": "tt8250078",
          "titleType": "movie",
          "primaryTitle": "Sink",
          "originalTitle": "Sink",
          "startYear": 2018,
          "runtimeMinutes": 7,
          "isAdult": false,
          "genres": [
            "drama"
          ],
          "directors": [
            "nm9757557"
          ],
          "writers": [
            "nm8337244"
          ],
          "actors": [
            "nm0692305",
            "nm5073992",
            "nm0936087",
            "nm9757554",
            "nm9757555"
          ]
        },
        {
          "id": "tt8251336",
          "titleType": "movie",
          "primaryTitle": "No One Will Ever Know",
          "originalTitle": "Nadie sabrá nunca",
          "startYear": 2018,
          "runtimeMinutes": 102,
          "isAdult": false,
          "genres": [
            "drama"
          ],
          "directors": [
            "nm2571065"
          ],
          "writers": [
            "nm2571065"
          ],
          "actors": [
            "nm2578315",
            "nm2784856",
            "nm1173803",
            "nm0709204"
          ]
        },
        {
          "id": "tt8254556",
          "titleType": "movie",
          "primaryTitle": "Girl",
          "originalTitle": "Girl",
          "startYear": 2018,
          "runtimeMinutes": 109,
          "isAdult": false,
          "genres": [
            "drama"
          ],
          "directors": [
            "nm4080113"
          ],
          "writers": [
            "nm4080113",
            "nm3899543"
          ],
          "actors": [
            "nm9760132",
            "nm3581007",
            "nm9854120",
            "nm7904438"
          ]
        },
        {
          "id": "tt8257434",
          "titleType": "movie",
          "primaryTitle": "Kaaneen: A Secret Search",
          "originalTitle": "Kaaneen: A Secret Search",
          "startYear": 2018,
          "runtimeMinutes": 135,
          "isAdult": false,
          "genres": [
            "drama"
          ],
          "directors": [
            "nm9761042",
            "nm8646148"
          ],
          "writers": [],
          "actors": []
        },
        {
          "id": "tt8235296",
          "titleType": "movie",
          "primaryTitle": "The Trump Prophecy",
          "originalTitle": "The Trump Prophecy",
          "startYear": 2018,
          "runtimeMinutes": 120,
          "isAdult": false,
          "genres": [
            "drama"
          ],
          "directors": [
            "nm0776398"
          ],
          "writers": [
            "nm9444786",
            "nm1205833",
            "nm2052673",
            "nm9444787"
          ],
          "actors": [
            "nm8985653",
            "nm1690749",
            "nm1982532",
            "nm1546204"
          ]
        }
      ]
    }
  }
}

Submitting a Template query

An Orchestration Template is nothing more than a set of Components that you wish to group together in a response. A Component may belong to zero, one or more Templates. Let's create a Template that will contain the movies and user components.

Navigate to the Templates page (Manage Experiences --> Templates).
Click the Add Template button.
Enter the following and click Submit.

Field	Value
Experience Template Code	welcome
Name	Welcome Payload
Experience Components	Movies, User

Now we will query the template we've just created.

POST {{engineUrl}}/experience/template/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "templateCode": ["welcome"],
  "context": {
    "userId": "pepper@iron.com",
    "genre": "drama"
  }
}

Or use the Developers Tools page to run your query:

Select the "Welcome Payload" Template.
In the Context field enter: {"userId": "pepper@iron.com", "genre": "drama"}.
Click "Execute Template".

Template Debugger

The above query will respond with the same payload as the component query.

Using a user's favourite genre to filter the movie list

Instead of manually specifying the genre in the context, we will:

Only specify a user, and
Use the user's favourite genre to filter the movies

There are two different approaches to achieve this:

Context Field Enrichment: Configuring the User Component to update the Context with genre.
Component response expression: Configuring the Movies Component to pull genre directly from the user component's response

Context Field Enrichment

Context Enrichment is the process of using an expression to evaluate a Component's response and writing that evaluated expression to the Context. In this case, we will take the response of user Component and use the favouriteGenre property to populate the genre Context field.

Since the movie Component refers to the genre Context field and the user Component will populate that same Context field, the DX Engine sets up a dependency between the user and movies Components. Specifically, it will process the user Component before the movie Component to ensure that the genre Context field is set.

Let's update the user Component so that it will set the genre Context field to the fetched user's favourite genre.

Navigate to the Components page (Manage Experiences --> Components).
Click the Edit icon on the user Component.
On the Update Context tab, go to the Context Field Enrichments field. In Context Field select genre and in Expression enter response[0].favouriteGenre.
Click Submit.

note

By enriching the genre Context field, you could now configure other Components to refer to genre as part of their query. Those Components could also further enrich the Context and so on. This allows for extreme flexibility by allowing for unlimited dependencies between components.

Let's query the movies Component along with a userId since we know that the user Component will be processed by the engine first and it requires the userId Context field.

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["movies"],
  "context": {
    "userId": "pepper@iron.com"
  }
}

Or use the Developers Tools page to run your query:

Select the "Movies" component.
In the Context field enter: {"userId": "pepper@iron.com"}.
Click "Execute Component(s)".

The response will look like this:

{
  "duration": 266,
  "components": {
    "movies": {
      "status": "VALID",
      "response": [
        {
          "id": "tt8246150",
          "titleType": "movie",
          "primaryTitle": "Knife Blood Pt.2",
          "originalTitle": "Knife Blood Pt.2",
          "startYear": 2018,
          "runtimeMinutes": -1,
          "isAdult": false,
          "genres": [
            "horror"
          ],
          "directors": [
            "nm6984708"
          ],
          "writers": [],
          "actors": [
            "nm6787892",
            "nm4342385",
            "nm4088112",
            "nm6545691",
            "nm4044554"
          ]
        },
        {
          "id": "tt8281642",
          "titleType": "movie",
          "primaryTitle": "Sirf 5 Din",
          "originalTitle": "Sirf 5 Din",
          "startYear": 2018,
          "runtimeMinutes": 145,
          "isAdult": false,
          "genres": [
            "horror"
          ],
          "directors": [
            "nm1150018"
          ],
          "writers": [
            "nm1150018"
          ],
          "actors": [
            "nm0044796",
            "nm2735302",
            "nm2977124",
            "nm6389513",
            "nm4542765",
            "nm3056569"
          ]
        },
        {
          "id": "tt8289960",
          "titleType": "movie",
          "primaryTitle": "My Dead Selfie",
          "originalTitle": "My Dead Selfie",
          "startYear": 2018,
          "runtimeMinutes": 97,
          "isAdult": false,
          "genres": [
            "horror"
          ],
          "directors": [
            "nm0788309"
          ],
          "writers": [
            "nm0788309"
          ],
          "actors": [
            "nm3916819",
            "nm2201671",
            "nm6167779",
            "nm5615091"
          ]
        },
        {
          "id": "tt8083382",
          "titleType": "movie",
          "primaryTitle": "Tales from Beyond",
          "originalTitle": "Tales from Beyond",
          "startYear": 2018,
          "runtimeMinutes": -1,
          "isAdult": false,
          "genres": [
            "horror"
          ],
          "directors": [
            "nm2552518"
          ],
          "writers": [
            "nm2552518"
          ],
          "actors": [
            "nm1641229",
            "nm6232442",
            "nm7951387",
            "nm6014899"
          ]
        },
        {
          "id": "tt8063826",
          "titleType": "movie",
          "primaryTitle": "The Watcher",
          "originalTitle": "The Watcher",
          "startYear": 2018,
          "runtimeMinutes": 97,
          "isAdult": false,
          "genres": [
            "horror"
          ],
          "directors": [
            "nm8448178"
          ],
          "writers": [
            "nm8448178"
          ],
          "actors": [
            "nm5032640",
            "nm2467058",
            "nm7961808",
            "nm9695331"
          ]
        }
      ]
    }
  }
}

We can see that since pepper@iron.com has a favourite genre of horror, the response will only contain horror movies. Try querying with shuri@panther.com as the userId. Apparently she likes comedy, so we should see a list of comedy movies.

Component response expression

Instead of enriching the context, we can update the movies Component as follows:

Click the Edit icon on the movies Component.
Enter the following and click Submit.

Field	Form Tab	Value
Query Parameters	Main	Parameter: `_query` Value (JS Expression): `'genres:' + componentResponse('user')[0].favouriteGenre`

We have used the componentResponse function in the above expression to refer directly to the output the user component.

Submitting the following query will return the same response as the query used above (using Context field enrichment).

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["movies"],
  "context": {
    "userId": "pepper@iron.com"
  }
}

Or use the Developers Tools page to run your query:

Select the "Movies" Component.
In the Context field enter: {"userId": "pepper@iron.com"}.
Click "Execute Component(s)".

Working with errors

Click the Edit icon on the movies Component.
Enter the following and click Submit.

Field	Form Tab	Value
Query Parameters	Main	Parameter: `_query` Value (JS Expression): `'genres:' + componentResponse('user')[1].favouriteGenre`

The above expression is referencing the second element in an array (from the user Component's response) with only one element.

Querying the movies Component will result in this:

{
  "duration": 302,
  "components": {
    "movies": {
      "error": "Cannot read properties of undefined (reading 'favouriteGenre')",
      "status": "FAILED"
    }
  }
}

Let's correct the above expression

Click the Edit icon on the movies Component.
Enter the following and click Submit.

Field	Form Tab	Value
Query Parameters	Main	Parameter: `_query` Value (JS Expression): `'genres:' + componentResponse('user')[0].favouriteGenre`

Now we'll query with an unknown userId (unknown@unknown.com) and we will also ask to return the user Component response:

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["movies", "user"],
  "context": {
    "userId": "unknown@unknown.com"
  }
}

Or use the Developers Tools page to run your query:

Select the "Movies" Component and the "User" Component.
In the Context field enter: {"userId": "unknown@unknown.com"}.
Click "Execute Component(s)".

The response is:

{
  "duration": 345,
  "components": {
    "user": {
      "status": "VALID",
      "response": []
    },
    "movies": {
      "error": "Cannot read properties of undefined (reading 'favouriteGenre')",
      "status": "FAILED"
    }
  }
}

We get this error since componentResponse('user')[0].favouriteGenre refers to an empty array. You can choose to handle this response in your client logic. Or perhaps you would like to explicitly mark the user Component as INVALID since its response is, clearly, not what you expected (you expect an array of one element).

Click the Edit icon on the user Component.
Enter the following and click Submit.

Field	Form Tab	Value
Validity Expression	Validation	`response.length == 1`

Rerunning the query above will now yield:

{
  "duration": 190,
  "components": {
    "user": {
      "status": "INVALID",
      "response": []
    },
    "movies": {
      "error": "Cannot read properties of undefined (reading 'favouriteGenre')",
      "status": "FAILED"
    }
  }
}

The DX Engine has now explicitly informed us that the user Component is in an invalid state. Any Component that is dependent upon the user Component can choose to skip its execution if it has a dependency that is INVALID (or SKIPPED or FAILED).

Let's configure the movies Component to skip its execution if it has a dependency (in this case, the user component) that is invalid.

Click the Edit icon on the movies Component.
Enter the following and click Submit.

Field	Form Tab	Value
Skip on Invalid Dependency	Conditions	true

The response will now look like:

{
  "duration": 344,
  "components": {
    "user": {
      "status": "INVALID",
      "response": []
    },
    "movies": {
      "status": "SKIPPED"
    }
  }
}

Querying with a valid userId:

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["movies", "user"],
  "context": {
    "userId": "pepper@iron.com"
  }
}

will result in a valid Component response for user and movies .

Fetch a list of actors using a specified list of actor IDs

Setup a Context Field to hold actorIds.

Navigate to the Context Fields page (Settings --> Context Fields).
Click the Add Context Field button.
Enter the following and click Submit.

Field	Value
Context Field Name	actorIds
Display Name Name	Actor IDs
Data Type	String

We will setup a Component to fetch actors using a Context field of actorIds.

Navigate to the Components page (Manage Experiences --> Components).
Click the Add Component button.
Enter the following and click Submit.

Field	Value
Component Code	actors
Component Name	Actors
No Rules	Checked
Component Type	Conscia - Universal API Connector

The DX Engine will create and prepare the Component for further configuration. You will see the Actors Component appear in the Component listing.

Click the Edit icon.
Enter the following and click Submit.

Field	Form Tab	Value	Description
Connection	Main	Conscia Sample Data Connection
Webservice Path	Main	/collections/collection-actor
Method	Main	GET
Headers	Main	Header: `content-type` Value (Literal): `application/json`	Under Headers, click `Add another item` in order to add a header. Under Get value from..., select `Specified value` in order to enter a value manually. Selecting `Context Field` or `Expression` would allow this value to be calculated and/or specified at query-time instead of setup time.
Query Parameters	Main	Parameter: `_id` Value (Context Field): `Actor IDs`	Under Query Parameters, click `Add another item` in order to add a query parameter.
Query Parameter Options	Main	ArrayForma: `bracket`	This allows the `_id` to be restructured in bracket format. With Array Format set to `bracket`, if actorIds = `['a', 'b', 'c']`, the webservice query string will be formatted as `_id[]=a&_id[]=b&_id[]=c`.

Let's query the actors component via the API:

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": ["actors"],
  "context": {
    "actorIds": ["nm0000206", "nm0000098"]
  }
}

Or use the Developers Tools page to run your query:

Select the "Actors" Component.
In the Context field enter: {"actorIds": ["nm0000206", "nm0000098"]}.
Click "Execute Components(s)".

The results will look like this:

{
  "duration": 378,
  "components": {
    "actors": {
      "status": "VALID",
      "response": [
        {
          "id": "nm0000206",
          "primaryName": "Keanu Reeves",
          "birthYear": 1964,
          "deathYear": null,
          "primaryProfession": [
            "actor",
            "producer",
            "soundtrack"
          ]
        },
        {
          "id": "nm0000098",
          "primaryName": "Jennifer Aniston",
          "birthYear": 1969,
          "deathYear": null,
          "primaryProfession": [
            "actress",
            "producer",
            "soundtrack"
          ]
        }
      ]
    }
  }
}

Configure `movies` to use `actors` as a Sub Component

Click the Edit icon on the movies Component.
Enter the following and click Submit.

Field	Value
Sub Components	Property Name = `movieActors`, Component Codes = `actors`, Context Field = `actorIds`, Expression = `response.actors`

For each movie record in the movies Component response's array, the actors Component will be processed with an updated context. In this case, each actor Component will be processed with a Context that will have a Context field of actorIds with a value that is taken from the movie record's actors property.

We must explicitly instruct the DX Engine to process Sub Components like so:

POST {{engineUrl}}/experience/components/_query
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "componentCodes": [
    "movies"
  ],
  "context": {
    "userId": "pepper@iron.com"
  },
  "processSubComponents": true
}

Or use the Developers Tools page to run your query:

Select the "Movies" Component.
In the Context field enter: {"userId": "pepper@iron.com"}.
Click "Execute Components(s)".

The response will look like:

{
  "duration": 561,
  "components": {
    "movie": {
      "status": "VALID",
      "response": [
        {
          "id": "tt8246150",
          "titleType": "movie",
          "primaryTitle": "Knife Blood Pt.2",
          "originalTitle": "Knife Blood Pt.2",
          "startYear": 2018,
          "runtimeMinutes": -1,
          "isAdult": false,
          "genres": [
            "horror"
          ],
          "directors": [
            "nm6984708"
          ],
          "writers": [],
          "actors": [
            "nm6787892",
            "nm4342385",
            "nm4088112",
            "nm6545691",
            "nm4044554"
          ],
          "movieActors": {
            "actors": {
              "status": "VALID",
              "response": [
                {
                  "id": "nm4088112",
                  "primaryName": "Erin McShane",
                  "birthYear": null,
                  "deathYear": null,
                  "primaryProfession": [
                    "actress",
                    "sound_department",
                    "editor"
                  ]
                },
                {
                  "id": "nm6787892",
                  "primaryName": "Alison Chang",
                  "birthYear": 1995,
                  "deathYear": null,
                  "primaryProfession": [
                    "actress",
                    "miscellaneous"
                  ]
                },
                {
                  "id": "nm4342385",
                  "primaryName": "Tre Hall",
                  "birthYear": null,
                  "deathYear": null,
                  "primaryProfession": [
                    "actor",
                    "writer",
                    "miscellaneous"
                  ]
                },
                {
                  "id": "nm6545691",
                  "primaryName": "Andrew Nunes Jr.",
                  "birthYear": 1993,
                  "deathYear": null,
                  "primaryProfession": [
                    "actor",
                    "director",
                    "writer"
                  ]
                },
                {
                  "id": "nm4044554",
                  "primaryName": "Bennett Saltzman",
                  "birthYear": null,
                  "deathYear": null,
                  "primaryProfession": [
                    "actor",
                    "miscellaneous"
                  ]
                }
              ]
            }
          }
        },
        {
          "id": "tt8281642",
          "titleType": "movie",
          "primaryTitle": "Sirf 5 Din",
          "originalTitle": "Sirf 5 Din",
          "startYear": 2018,
          "runtimeMinutes": 145,
          "isAdult": false,
          "genres": [
            "horror"
          ],
          "directors": [
            "nm1150018"
          ],
          "writers": [
            "nm1150018"
          ],
          "actors": [
            "nm0044796",
            "nm2735302",
            "nm2977124",
            "nm6389513",
            "nm4542765",
            "nm3056569"
          ],
          "movieActors": {
            "actors": {
              "status": "VALID",
              "response": [
                {
                  "id": "nm3056569",
                  "primaryName": "Rocky Verma",
                  "birthYear": 1969,
                  "deathYear": null,
                  "primaryProfession": [
                    "actor",
                    "stunts",
                    "casting_director"
                  ]
                },
                {
                  "id": "nm4542765",
                  "primaryName": "Raju Thakkar",
                  "birthYear": null,
                  "deathYear": null,
                  "primaryProfession": [
                    "actor"
                  ]
                },
                {
                  "id": "nm2977124",
                  "primaryName": "Mahie Gill",
                  "birthYear": null,
                  "deathYear": null,
                  "primaryProfession": [
                    "actress",
                    "producer"
                  ]
                },
                {
                  "id": "nm0044796",
                  "primaryName": "Raj Babbar",
                  "birthYear": 1952,
                  "deathYear": null,
                  "primaryProfession": [
                    "actor",
                    "music_department"
                  ]
                },
                {
                  "id": "nm2735302",
                  "primaryName": "Anuj Gill",
                  "birthYear": null,
                  "deathYear": null,
                  "primaryProfession": [
                    "actor",
                    "casting_director"
                  ]
                },
                {
                  "id": "nm6389513",
                  "primaryName": "Suchhi Kumar",
                  "birthYear": null,
                  "deathYear": null,
                  "primaryProfession": [
                    "actor",
                    "producer",
                    "director"
                  ]
                }
              ]
            }
          }
        },
        { ... },
        { ... },
        { ... }
      ]
    }
  }
}

note

This demonstrates nested orchestration (GraphQL-like dependencies)

Here are some advanced exercises for you to try with the DX Engine:

Remap the above JSON response from one Component to a cleaner response that is more consumable by your frontend.

The movie data source​

Endpoints​

Record Structures​

Movie​

Actor​

Users​

Setting up a connection to the Sample Data Webservice​

Fetching movies​

Fetch movies with a hardcoded genre​

Fetch movies with a genre specified at query-time​

Fetch a user​

Querying for multiple components​

Submitting a Component Query with a list of components​

Submitting a Template query​

Using a user's favourite genre to filter the movie list​

Context Field Enrichment​

Component response expression​

Working with errors​

Fetch a list of actors using a specified list of actor IDs​

Configure movies to use actors as a Sub Component​

The movie data source

Endpoints

Record Structures

Movie

Actor

Users

Setting up a connection to the Sample Data Webservice

Fetching movies

Fetch movies with a hardcoded genre

Fetch movies with a genre specified at query-time

Fetch a user

Querying for multiple components

Submitting a Component Query with a list of components

Submitting a Template query

Using a user's favourite genre to filter the movie list

Context Field Enrichment

Component response expression

Working with errors

Fetch a list of actors using a specified list of actor IDs

Configure `movies` to use `actors` as a Sub Component