The AtomSphere platform provides a web service API (REST or SOAP) to perform process and other component deployments and promotions programmatically that you can incorporate into your automated change management procedure. Use of the deploy APIs requires orchestration logic to be performed by a client application such as an internal scripted application or even another AtomSphere integration process.
The platform API is available free-of-charge to all AtomSphere customers and partners. You can call the platform API from an external client application but there is also an AtomSphere API connector which can be used to easily interact with the API from within a process. Note the platform API is separate from and available without the API Management offering.
This article assumes the use of Environments and Extensions which are not available in all editions. However there are Atom-only versions of the attachments APIs that may be used instead.
Usage Notes and Limitations
- The AtomSphere API connector can be used to interact with the API from with an AtomSphere process.
- Using the API provides an opportunity to devise business logic to enforce environment-promotion sequencing if desired. For example, you could use decision to enforce that a deployment targeting the "production" environment may only come from a deployment that currently resides in the "stage" environment, not "test" or "dev".
- The digest value serves as the consistent value for comparing versions of a given deployment across environments. Note the version and Deployment id will vary across environments. You will use this to identify and validate the same deployment version.
- The digest is only returned by the Deployment GET action. It is not returned by the QUERY action.
- When updating environment extension values via the API, the entire set of values must be provided in the request; partial updates are not supported. This means the request must contain values for all extended fields, not only ones that are to be changed. If an extended field is omitted in the update, the value will be removed. The only exception is encrypted password fields.
- The client application may wish to query and maintain a local copy of the list of process and environment names and internal IDs for convenience.
- As of the January 2017 release, new deployments for additional component types such as API, Certificate, and Process Route can be created via the API.
- As of the January 2017 release, use of the new generic ComponentEnvironmentAttachment and ComponentAtomAttachment APIs are preferred over the legacy ProcessEnvironmentAttachment and ProcessAtomAttachment APIs.
- As of the June 2017 release, use of the new generic deployComponent API to copy/promote any type of component from one environment to another is preferred over the legacy deployProcess API.
The steps below assume the target Environment has been created, the Atom or Cloud runtime has been installed, and that runtime has been attached to the given Environment.
1. Deploy New Version to First Environment
- Developer manually attaches (if first time deploying to the target environment) and deploys initial deployment version to the first environment using the AtomSphere user interface. Although the APIs exist to attach and create the new deployment version programmatically, it is recommended to create the initial deployment manually after successful unit testing. This allows the developer more control over all the components involved with the given change.
- Alternatively, client application verifies attachment and calls CREATE Deployment with componentId=<process or other component ID to deploy>, environmentId=<target environment ID>, and deployNotes.
- Developer or client application sets extensions.
- For scheduled processes, developer or client application configures schedules.
2. Verify Attachment
- Client application calls QUERY ComponentEnvironmentAttachment with componentId=<process or other component ID> and environmentId=<target environment ID>.
- If a result is returned, no further action. Otherwise client application calls CREATE ComponentEnvironmentAttachment with componentId=<process or other component ID to attach> and environmentId=<target environment ID>.
3. Set Extensions
- After deploying to a new environment, the client application calls QUERY EnvironmentExtensions with environmentId=<target environment ID>, overlays the desired new values, and calls UPDATE EnvironmentExtensions.
- Alternatively the user can manually configure any new environment extension values required for the new process through the user interface.
4. Configure Schedules
- Client application calls QUERY EnvironmentAtomAttachment with environmentId=<target environment ID>.
- For each atomId returned, client application calls QUERY ProcessSchedules with atomId=<target atom ID> and processId=<process ID to schedule> to retrieve the ProcessSchedules object for each desired process.
- Client application calls UPDATE ProcessSchedules with id=<process schedule ID>, atomId=<target atom ID>, and processId=<process ID to schedule> for each desired process.
5. Promote to Next Environment
As of the June 2017 release, the deployComponent API should be used to promote any type of component from one environment to another.
- Client application calls QUERY Deployment with componentId=<process or component ID> AND environmentId=<source environment ID> AND current=“true” to retrieve the current deployment ID from the source environment.
- Client application then calls GET Deployment deploymentId=<source deployment ID> to retrieve the digest.
- Client application verifies attachment to target environment (see above).
- Client application calls DeployComponent with deploymentId=<source deployment ID>, digest=<source deployment digest>, and environment=<target environment ID>.
- Client application or user sets extensions as above.