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 and Environment Variables 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 Engine UI, you can use the drop-down at the top right to select an Environment.

When calling DX Engine Webservice APIs other than those used to manage Environments, use the X-Environment-Code HTTP header to specify the Environment.

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.

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.

Customers have the option to enable the explicitEnvironmentHeader flag in their configuration. This requires all HTTP calls to the customer code to include the X-Environment-Code header to specify which Environment to access. The preview Environment will not be accessed by default and an error will result if the header is not included.

PUT {{dxEngineUrl}}/customer-config
Content-Type: application/json
Authorization: Bearer {{DX_ENGINE_SYSTEM_TOKEN}}
X-Customer-Code: {{customerCode}}
{
  "configuration": {
    "explicitEnvironmentHeader": true
  }
}

note

When you log in and select DX Engine, 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 Engine 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 the engine-config API endpoint.

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

The response will be in the following format:

{
  "connection": {
    {...},
    {...}
  },
  "secret": {
    {...},
    {...}
  },
  "component": {
    {...},
    {...}
  }
}

Only objects with configurations will appear in the response. If the Environment doesn't have any Secrets configured, for example, then there will not be an empty secret object in the response.

Restoring an Environment

Once wrapped in an engineConfig property, an exported JSON config can be used to restore an Environment via PUT to the engine-config endpoint.

By default, this will completely overwrite the existing Environment's Components, Secrets, Connections, and Environment Variables. This is useful for restoring an Environment to a previous state, or for a wholesale update using work done in another Environment.

Flag	Behaviour	Default
preserveSecrets	When true, all secrets on the target environment will be retained, and the Secrets in the input config will be ignored. When false, all Secrets on the target environment will be deleted and replaced with the Secrets in the provided environment config.	false
preserveEnvironmentVariables	When true, all Environment Variables on the target environment will be retained, and the Environment Variables in the input config will be ignored. When false, all Environment Variables on the target environment will be deleted and replaced with the Environment Variables in the provided environment config.	false

An example API call for promoting a configuration from a lower environment:

PUT {{engineUrl}}/engine-config?preserveSecrets=true&preserveEnvironmentVariables=true.
Content-Type: application/json
Authorization: Bearer {{dxEngineSystemToken}}
X-Customer-Code: {{customerCode}}
X-Environment-Code: {{environmentCode}}

{
  "engineConfig": {
    "connection": {
      {...},
      {...}
    },
    "secret": {
      {...},
      {...}
    },
    "component": {
      {...},
      {...}
    }
  }
}

note

The response of raw-engine-config will not be used unless wrapped:

"engineConfig": {
  // GET raw-engine-config response
}

An engine-config call providing an unwrapped raw-engine-config response will delete the existing environment (Components, Connections, et cetera) and return a success.

After importing an Environment, you may need to update Connections or other configuration as appropriate to incorporate Secrets or Environment Variables native to that 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 Engine

To create an Environment in the DX Engine 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 the DX Engine 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.