Managing Environments

All DX Engine elements (Secrets, Connections, Components) are scoped to an environment. This means that a Secret, Connection, or Component 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. Typically, Secrets (which are used by Connections) are created for each Environment while Connections and Components are created in a development environment and then exported to other environments.

Environment Management API

Create an Environment

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

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

Update an Environment

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

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

List Available Environments

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

Remove an Environment

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}}

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": [
      {...},
      {...}
    ]
  }
}

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 (SCMS), and use that JSON to create the production Environment.

note

After importing an Environment, overwrite Secrets and otherwise update any Connections or other configuration as appropriate for the new 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.

note

An Environment includes everything that you define through the the DX Studio UI DX Engine APIs including Channels, Connections, Context Fields, Orchestration Components, Orchestration Templates, Experience Rules, Secrets, and Webhooks.

Environment Management API​

Create an Environment​

Update an Environment​

List Available Environments​

Remove an Environment​

Exporting Configurations of an Environment​

Restoring an Environment​