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 run your query in the DX Engine UI.
- Select the "Movies" Component.
- Click "Execute Component(s)".
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...