DX Engine Sandbox Walkthrough
This guide outlines the sequence of steps to get yourself familiarized with your DX Engine sandbox. The sandbox is set up with some existing Connections, Components, Templates, Channels, Contexts and Experience Rules.
Please be sure to have the following handy:
- Customer Code
- API Token (provided during sandbox creation)
When you first enter your Sandbox, you will see this screen:
Secrets
You will find 'Secrets' under the 'Settings' Menu in the top nav. Secrets allow you to define API tokens which can be used by Connections without the need to display them in clear text. In your sandbox environment, we have created three secrets for you, one for Contentful and two for Commercetools.
To learn more about how to create and manage Secrets, please visit the Secrets page.
Connections
Your sandbox has been configured with two existing Connections to backend data sources, one for Contentful and one for Commercetools. You will find these Connections under the 'Settings' Menu.
If you right click and hit 'Update', a modal will pop up that will show how each Connection is using a Secret.
To learn more about how to create and manage Connections, please visit the Connections page.
Components
DX Engine Components are not the same as frontend Component. Components within the DX Engine are atomic units that do work. View the Components page to understand what a Component is in the context of orchestration.
In your sandbox, the following four DX Engine Components have already been created for you. These Component fetch content and product data from backend systems based on Experience Rules set up by the business team.
- Commercetools Static Record List
- Commercetools Dynamic Record List
- Contentful Static Record List
- Contentful Dynamic Record List
If you browse to the 'Components' dashboard, you will see the following:
Select the Contentful Static Record List, named 'Conscia - Contentful Articles (S)
Right-Click and select 'Update' to look at the Component Configuration
This Component will connect to Contentful and fetch content items from 'Article' Content Type as configured:
Similarly, you can explore the configurations of the other three Component.
All DX Engine Component including the ones set up in your sandbox offer a variety of configurations made available through this UI as well as the DX Engine APIs.
If you are interested in understanding all of the configurations available within a Component, you should visit the Components page.
Templates
A Template is a grouping of Components that are executed within a scope of a single Experience API request. For example, to deliver a Home Page, you may call the DX Engine requesting a Home Page Template that includes the Hero Banner, Product Carousel, Blog, Promotion, etc.
For business users, the left Nav on the Experience Rules page will list the hierarchy of Channels, Templates and Components.
In other words, Templates serve two objectives: 1) It organizes Components for business users to manage experiences in an intuitive fashion 2) It allows developers to group Components so that the DX Engine can return them to the client application as part of a single Experience API response instead of having to list out all the Components separately.
Browse to the Templates dashboard. Here are the list of Templates that have been set up for your sandbox.
To learn more about how to create and manage templates, please visit the Templates page.
Channels
Channels allow you to group one or more Templates together. The business users will see the Channel->Template->Component Hierarchy in the Experience Rules dashboard.
Navigate to the Channels dashboard in your sandbox.
You will see the following Channels present in your sandbox:
View the Channels page for more information.
Context Fields
We have set up some Context fields for you. These are the triggers that your Experience Rules can react to.
To learn about how to create and manage Context fields that you want to make available to the Rules Engine, visit the Context Fields page.
Experience Rules
DX Engine Components that require conditional logic will use 'Experience Rules'. These rules can be configured to pull content or data from different backend systems based on the real-time context provided to the Experience API request. For example, an Experience API request that is asking for content to be returned on the Home Page of a website may provide the customer's location, device or segment as real-time Context. These rules can evaluate this context and return the relevant experience.
Note that rules are not limited to pulling specific content from the backend. They can even be used to determine steps within the API orchestration flow. For example, if you want to call one CRM for B2C customers and another CRM for B2B customers, this can be achieved with Experience Rules as well.
Navigate to the 'Experience Rules' dashboard. Here, you will see a left nav tha displays a hierarchy of Channels, Templates and Components. The Rules are tied to each Component. This means that you can define business logic at the most granular level and create an infinite number of experiences by simply assembling a set of components.
In your sandbox, you will see the four components that we discussed earlier.
View the Business User Guide page for more information on creating Experience Rules.
Calling the Experience API
With Connections, Components, Templates, Channels, Contexts and Experience Rules in place, we can call the DX Engine using the Experience API.
- Navigate to the DX Engine API page.
- In the left panel, select the 'API Servers' link and then choose the API server. You will select the staging server since the sandbox application is deployed on the staging environment.
- In the left panel, select the 'Authentication' page and input the API token you were provided
- In the left panel under 'Experience Engine', select one of the following options:
- Query the Experience Engine by Template - returns all Components linked to the Template.
- Query the Experience Engine by List of Components - returns only the listed Components.
Let's start by requesting just one Component called: conscia-commercetools-products-static
- In the Request > Request Headers, input your customer code in the X-Customer-Code box
- In the Request > Request Body, enter the following:
{
"componentCodes": [
"conscia-commercetools-products-static"
],
"context": {
}
}
Note that we have not entered any Context here, so the DX Engine will respond with the default response.
- Click "Try" to run the orchestration and receive the response payload back
Here is the response you should see:
{
"duration": 261,
"components": {
"conscia-commercetools-products-static": {
"@extras": {
"rule": {
"code": "default",
"metadata": [],
"attributes": {
"display-pricing": "off"
}
}
},
"status": "VALID",
"response": [
{
"id": "bf709590-0eec-45c9-99d6-0dd5e9346da5",
"version": 14,
"productType": {
"typeId": "product-type",
"id": "4bad9afa-8d9b-45e9-9697-f0485b0063fa"
},
"name": {
"en": "Sterling Silver Necklace",
"en-US": "Sterling Silver Necklace"
},
"categories": [
{
"typeId": "category",
"id": "e7b1b567-9624-427d-b5e1-e11dbc5c8a29"
}
],
"categoryOrderHints": {},
"slug": {
"en": "sterling-silver-necklace-545359",
"en-US": "sterling-silver-necklace-545359"
},
"variants": [
{
"attributes": [
{
"name": "brand_name",
"value": "Sterling Diamonelle"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/5/54/545/0x0/545359.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "318002d3-04d3-44f0-a2c1-fc815a19d391",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 32999,
"fractionDigits": 2
},
"key": "12167836"
}
],
"key": "12167836",
"id": 2
},
{
"attributes": [
{
"name": "brand_name",
"value": "Sterling Diamonelle"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/5/54/545/0x0/545359_YGVER.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "595a726c-00a3-4243-9c93-ac297e49ecc1",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 32999,
"fractionDigits": 2
},
"key": "12167823"
}
],
"key": "12167823",
"id": 3
},
{
"attributes": [
{
"name": "brand_name",
"value": "Sterling Diamonelle"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/5/54/545/0x0/545359_RHOP.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "f7860ba7-4064-4a83-9fa3-e354c4a735a0",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 32999,
"fractionDigits": 2
},
"key": "12167822"
}
],
"key": "12167822",
"id": 4
}
],
"masterVariant": {
"attributes": [
{
"name": "brand_name",
"value": "Sterling Diamonelle"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/5/54/545/0x0/545359_RHOP.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "d08fe6c8-a7fe-4a89-9af4-14b0bb3f76f1",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 32999,
"fractionDigits": 2
},
"key": "12167821"
}
],
"key": "12167821",
"id": 1
},
"searchKeywords": {},
"hasStagedChanges": false,
"published": true,
"key": "545359",
"createdAt": "2022-10-11T15:51:49.793Z",
"lastModifiedAt": "2022-10-19T17:09:36.544Z"
},
{
"id": "e6071395-08a4-43d9-9b9f-c8e82f753614",
"version": 14,
"productType": {
"typeId": "product-type",
"id": "4bad9afa-8d9b-45e9-9697-f0485b0063fa"
},
"name": {
"en": "Apple AirPods Bundle",
"en-US": "Apple AirPods Bundle"
},
"categories": [
{
"typeId": "category",
"id": "0367ea8b-ac65-4870-870d-403345475c85"
}
],
"categoryOrderHints": {},
"slug": {
"en": "apple-air-pods-bundle-661646",
"en-US": "apple-air-pods-bundle-661646"
},
"variants": [
{
"attributes": [
{
"name": "brand_name",
"value": "Apple"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/6/66/661/0x0/661646_BLU.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "04c4e130-7f90-444e-91d8-bfa06eb40fec",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 27999,
"fractionDigits": 2
},
"key": "12371716"
}
],
"key": "12371716",
"id": 2
},
{
"attributes": [
{
"name": "brand_name",
"value": "Apple"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/6/66/661/0x0/661646_RED.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "ff6b76ef-9742-46dd-8d57-82fabc18dcf1",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 27999,
"fractionDigits": 2
},
"key": "12371717"
}
],
"key": "12371717",
"id": 3
},
{
"attributes": [
{
"name": "brand_name",
"value": "Apple"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/6/66/661/0x0/661646_BLK.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "5844f96c-1477-4b55-b0ce-88e49327e73a",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 27999,
"fractionDigits": 2
},
"key": "12371715"
}
],
"key": "12371715",
"id": 4
}
],
"masterVariant": {
"attributes": [
{
"name": "brand_name",
"value": "Apple"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/6/66/661/0x0/661646_PNK.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "f781e093-d3e8-4de5-9933-035a979db636",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 27999,
"fractionDigits": 2
},
"key": "12371733"
}
],
"key": "12371733",
"id": 1
},
"searchKeywords": {},
"hasStagedChanges": false,
"published": true,
"key": "661646",
"createdAt": "2022-10-11T16:03:47.179Z",
"lastModifiedAt": "2022-10-11T21:33:20.027Z"
},
{
"id": "d0890d11-f419-4f41-950a-d6713a2af27b",
"version": 5,
"productType": {
"typeId": "product-type",
"id": "4bad9afa-8d9b-45e9-9697-f0485b0063fa"
},
"name": {
"en": "Kitchenaid 3-Piece Ceramic Cutlery Set",
"en-US": "Kitchenaid 3-Piece Ceramic Cutlery Set"
},
"categories": [
{
"typeId": "category",
"id": "dfc05d36-5868-465f-b8db-6b6934b102d1"
}
],
"categoryOrderHints": {},
"slug": {
"en": "kitchenaid-3-piece-ceramic-cutlery-set-555408",
"en-US": "kitchenaid-3-piece-ceramic-cutlery-set-555408"
},
"variants": [],
"masterVariant": {
"attributes": [
{
"name": "brand_name",
"value": "KitchenAid"
}
],
"assets": [],
"images": [
{
"url": "https://item.tscimg.ca/TSC/5/55/555/0x0/555408.jpg?impolicy=M",
"dimensions": {
"w": 200,
"h": 200
}
}
],
"prices": [
{
"id": "bc8ccfc9-b1fc-4d58-a26b-9efd4a464091",
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 3999,
"fractionDigits": 2
},
"key": "12451318"
}
],
"key": "12451318",
"id": 1
},
"searchKeywords": {},
"hasStagedChanges": false,
"published": true,
"key": "555408",
"createdAt": "2022-10-11T15:50:35.314Z",
"lastModifiedAt": "2022-10-19T17:08:55.482Z"
}
]
}
}
}
Now, you can go ahead and request for the various Components that we have defined, either as a List of Components or by Template they are tied to.
Next Steps
Now that you have familiarized yourself with the Experience Studio, you can start to experiment with more sophisticated capabilities of the DX Engine. As a next step, we recommend that you follow the 10 Minute Quick Start Tutorial.
Here are the topics that you will want to learn about:
- Chaining API Calls
- Conditional logic in the Orchestration Flow
- Enriching the Real-time Context - Learn More
- Writing to external systems asynchronously
- Caching and Invalidating Cache - Learn More
- Transforming data and stitching data from multiple API responses Learn More
- Defining and managing Experience Attributes (Design Props) Learn More
- Defining Display Templates for Components that require Business User input. Learn More
- Access Control using Tags
- Setting up Preview for your Templates