Environments

All DX Engine elements (Channels, Components, Connections, Context Fields, Secrets, Experience Rules, Templates, and Webhooks) are scoped to an Environment. This means that any particular element can only be used within the Environment it was created in. This allows you to create multiple Environments for different purposes (development, staging, production, etc.) and to use the same names for Secrets, Connections, and Components across Environments.

Secrets typically are created for each Environment while Connections, Components, etc., are created in a development Environment and then exported to other Environments.

In the DX Studio UI, you can use the drop-down at the top right to select an Environment.

For Webservice API calls, use the X-Environment-Code HTTP header.

Uses of Environments

The most common use of DX Engine Environments is to separate your development, integration test, user acceptance testing, production, and other Environments to correspond with your solution build and deployment processes. You can create different Environments for different developers, eventually using DX Engine APIs to merge their artifacts into a common Environment. You can create DX Engine elements in a development Environment and migrate those elements through zero or more test Environments to a production Environment.

You can use Environments for other purposes unrelated to migration from development to production. For example, you can create temporary Environments to experiment and evaluate DX Engine functionality as well as custom and third-party Webservice APIs.

note

Your Conscia licensing agreement may limit the number of Environments that you are allowed to create. Check your licensing agreement or confirm with Conscia before you create an Environment.

The Default Environment

Each DX Engine instance includes a default preview Environment. If you do not specify the X-Environment-Code HTTP header, DX Engine Webservice APIs access the preview Environment by default.

note

When you log in and select DX Studio, the UI consults the browser's local storage in an attempt to bring you back into the Environment that you last accessed.

note

You can change the Name of the preview environment.

note

If you delete the preview Environment, unless you have selected a different Environment, the DX Studio UI will default to accessing the first environment in the list of Environments.

Managing Environments and Elements

You can use DX Engine Webservice APIs to export and import the JSON representation of an entire Environment including all of the elements that it contains, or to export individual elements. If you store that JSON as files, then you can manage those files in a source code management system.

Considering dependencies between Context Fields, Components, Templates, Experience Rules, and other elements in a solution, to create Production environments, Conscia recommends using APIs to export and import a complete Environment from a preview, integation test, or user test Environment. Replicating entire Environments rather than selectively exporting and importing certain elements avoids inconsistencies in DX Engine's operation due to differences in dependencies. You can export an Environment as JSON for management in a source code management system, and use that JSON to create the production Environment.

While Conscia recommends replicating an entire Environments to create the production Environment, granular APIs allow precise adjustments where needed. During development, you can use DX Engine APIs to export individual elements as static JSON for tracking in a source code management system, and use that JSON to migrate individual elements through one or more pre-production Environments, the last of which is replicated to become the production Environment.

Exporting Configurations of an Environment

All DX Engine configurations within an Environment can be exported as a JSON file via an API call, which you can then version control. This file can then be used to restore an Environment via another API endpoint.

GET {{engineUrl}}/raw-engine-config
Content-Type: application/json
Authorization: Bearer {{dxEngineSystemToken}}
X-Customer-Code: {{customerCode}}
X-Environment-Code: {{environmentCode}}

Restoring an Environment

The exported JSON from above can be used to restore an Environment via the following API call. This will completely overwrite the existing Environment configurations. This is useful for restoring an Environment to a previous state or for a wholesale update with work done in another Environment.

Wrap the exported Environment configuration with an engineConfig property.

If you wish to preserve the current Secrets when importing an Environment and do not want them overwritten, use the preserveSecrets flag and set it to true: PUT /engine-config?preserveSecrets=true.

PUT {{engineUrl}}/engine-config
Content-Type: application/json
Authorization: Bearer {{dxEngineSystemToken}}
X-Customer-Code: {{customerCode}}
X-Environment-Code: {{environmentCode}}

{
  "engineConfig": {
    "connections": [
      {...},
      {...}
    ],
    "secrets": [
      {...},
      {...}
    ],
    "components": [
      {...},
      {...}
    ]
  }
}

note

After importing an Environment, overwrite Secrets and otherwise update any Connections or other configuration as appropriate for the new Environment.

Create an Environment via the API

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

{
  "environmentCode": "test",
  "name": "Testing",
  "description": "My Testing Environment description"
}

Update an Environment via the API

PUT {{engineUrl}}/experience/environments/{{environmentCode}}
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

{
  "name": "New Testing name",
  "description": "My Testing Environment description"
}

List Available Environments via the API

GET {{engineUrl}}/experience/environments
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

Remove an Environment via the API

When you remove an environment, all associated elements (including Orchestration Templates, Components, Connections, etc) will be removed with it. You do not need to remove them first.

DELETE {{engineUrl}}/experience/environments/{{environmentCode}}
X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}

Creating an Environment in DX Studio

To create an Environment in the DX Studio UI:

1. In the top navigation, click Settings, and then click Environments. The Manage Environments page appears.
2. Click Add Environment. The Create Environment wizard appears.
3. For Environment Code, enter a unique identifier for the Environment.
4. For Name, enter a friendly name for the Environment. This will appear in the drop-down list in DX Studio UI. Environment names should be short and often correspond directly to Environment codes, but can contain uppercase letters, spaces, and special characters.
5. Optionally, enter a Description for the Environment.
6. Click Submit.