External Deployment using Deployment REST API

External deployments use Appian's deployment REST API suite, which allows you to orchestrate your Appian deployments using an external deployment pipeline tool. This provides a secure way to expose Appian deployment services and data, and unifies your deployments across all the systems you manage.

These deployment APIs allow you to:

• Trigger deployments programmatically.
• Integrate your Appian releases into an automated pipeline.
• Coordinate with your other software releases and business processes.
• Set up your pipeline once and run it the exact same way for all future deployments, saving time and avoiding manual errors.

You can also programmatically inspect and import Admin Console settings, however exports must be done manually through Administration Console UI.

External deployments allow you to completely automate your CI/CD pipeline—including Appian exports, inspections, and imports—using a pipeline you set up once and run the same way for all future deployments, saving time and avoiding manual errors. They also allow you to configure a post-deployment process to run after external deployments.

This page gives an overview of Appian's deployment REST API suite. You can enable these deployment APIs for use on your environment in the Admin Console infrastructure page.

To learn more about our other deployment types, see Direct Deployments and Manual Deployments.

Versions of the deployment REST API

There are three versions of the deployment REST API. Use the table below to determine which version of the API works best with your Appian installation. We recommend upgrading to the latest version of the API when available to get the latest functionality.

Appian Version	API Version
23.2 or earlier	V1
26.4 or earlier	V2
26.5+	V3

Each new version of the API for import and export have added additional flexibility in the contents of the deployment. Below is a summary of the different deployment types you can perform based on the API version:

API Version	Admin Console Settings	Single Application	Multiple Applications	Single Package	Multiple Packages	Scripts for Different Sources
V1	Yes*	Yes*	Yes*	Yes	No	No
V2	Yes*	Yes	Yes	Yes	No	No
V3	Yes*	Yes	Yes	Yes	Yes	Yes

* Only supports the import (deploy) API

For more information on each endpoint review their specific documentation page.

Versions 2 and 3

Appian's deployment REST API suite provides a secure way to expose Appian deployment services and data via external systems.

These deployment APIs allow you to:

• Trigger external deployments programmatically.
• Integrate your Appian releases into an automated pipeline.
• Coordinate with your other software releases and business processes.
• Set up your pipeline once and run it the exact same way for all future deployments, saving time and avoiding manual errors.

With Appian's native APIs, you can completely automate your CI/CD pipeline, including your Appian exports, inspections, and imports. They also allow you to configure a post-deployment process to run after external deployments. There are six endpoints available for deployments:

• Export apps and packages.
• Inspect apps and packages.
• Get inspection results.
• Import apps and packages.
• Get deployment results.
• Get deployment log.

In addition to these capabilities, you can also use the Application Package Details to retrieve package identifier information to trigger your deployments.

This page gives an overview of Appian's deployment REST API suite. You can enable these deployment APIs for use on your environment in the Admin Console infrastructure page.

Endpoints

All deployment API endpoints are called with a URL beginning with https://<domain>/suite/deployment-management/<v#>, where <domain> is replaced with your Appian site domain and <v#> specifies the version of the endpoint you are using.

Every API endpoint must be called using the HTTP request method (POST or GET) specified in the documentation. A POST request is used to send data to (in the case of import) or retrieve data from (in the case of export) Appian. A GET request is used to request data from Appian, such as retrieving the status of an existing deployment or retrieve the corresponding deployment log.

Authentication

All requests are authenticated with an API key or OAuth 2.0 token linked to a service account. This is the same mechanism that Appian uses to secure Web API objects. The service account, as well as the API key or OAuth client configuration, can be created in the Admin Console, and then used to secure external deployments.

Once configured, there are multiple ways to use the credentials to authenticate your request. For example, you can add it to the HTTP header with the key name appian-api-key:

curl https://<domain>/suite/deployment-management/v3/deployments -H "appian-api-key: <API key>"

For any GET requests, users can use the provided URL in their browser to retrieve results. As long as that user has the correct access to the application to see deployment details they will be able to see the results.

Mutual TLS

For added security, trusted server certificates can be uploaded to the Admin Console, enabling mutual TLS (mTLS) authentication between Appian and the system calling the API.

When mTLS is enabled, all requests are served on port 8443.

Configuring incoming and outgoing deployments

The same sets of endpoints are used for incoming and outgoing deployments. For POST requests where you need to differentiate between imports and exports, you can specify the Action-Type in the header alongside your API key or OAuth token.

curl https://<domain>/suite/deployment-management/v3/deployments -H "appian-api-key: <API key>" -H "Action-Type: <import/export>"

Workflow

Appian recommends inspecting all packages before deployment. Additionally, the export endpoint should be used with a change management system to ensure only work that is ready for deployment is being exported.

The high-level workflow and endpoints for each step are:

1. Retrieve the corresponding package UUIDs for your deployment using the Application Package Details. Make sure you've selected the right package(s)* to avoid deploying incomplete features.
   • *Multiple packages is only supported on versions v3+ of the API.
2. Trigger your export. After work is complete on an increment, specify the package(s) or application(s) ready for export. Use the header of the deployments endpoint to specify the Action-Type as export and extract the desired deployment package. When exporting, any database scripts, plug-ins, or import customization file specified in the package will be available as resources of the deployment once it completes.
3. Check the status of your deployment using the /deployments/<uuid> endpoint. Once it completes, you will be able to download the corresponding resources created from your deployment.
4. For more detailed results, retrieve the deployment log using the /deployments/<uuid>/log endpoint.
5. Once you have your deployment contents, you can begin the process of deploying to your target environment. Inspect your package, Admin Console settings (though you can programmatically deploy admin console settings, you still must export them manually), import customization file, or any combination of those using the /inspections endpoint. The endpoint response provides the UUID of the inspection, which you can use in the next step.
6. Retrieve the status and results of your inspection using the /inspections/<uuid> endpoint. The inspection may take longer depending on the size of your package. Appian recommends hitting this endpoint on a regular interval until the inspection is complete and results are available, which is indicated by the status response.
7. Deploy your Admin Console settings, package, customization file, plug-ins, and/or database scripts using the /deployments endpoint. This is the same endpoint used in step 1. You can set the Action-Type to import, otherwise the value is set to import by default. The endpoint’s response provides the UUID of the deployment, which you can use in the next step.
8. Retrieve the status and results of your deployment by using the /deployments/<uuid> endpoint. As in step 2, the deployment time will vary with the size of your package. Appian recommends hitting this endpoint on a regular interval until the deployment is completed and results are available, which is indicated by the status response.
9. Again, for more detailed results, retrieve the deployment log using the /deployments/<uuid>/log endpoint.

Version 1

There are five endpoints available for deployments in version 1:

• Inspect packages
• Get inspection results
• Execute a deployment
• Get deployment results
• Get deployment log

This page gives an overview of Appian's deployment REST API suite. You can enable these deployment APIs for use on your environment in the Admin Console infrastructure page.

Endpoints

All deployment API endpoints are called with a URL beginning with https://<domain>/suite/deployment-management/v1, where <domain> is replaced with your Appian site domain.

Every API endpoint must be called using the HTTP request method (POST or GET) specified in the documentation. A POST request is used to send data to Appian in order to create or update information, such as creating a new deployment. A GET request is used to request data from Appian, such as retrieving the status of an existing deployment.

Authentication

All endpoint requests are authenticated with an API key, which is linked to a service account. This is the same mechanism that Appian uses to secure Web API objects. The service account and API key can be created in the Admin Console, and then configured to secure external deployments.

Once configured, there are multiple ways to use the API key to authenticate your request. For example, you can add it to the HTTP header with the key name appian-api-key:

curl https://<domain>/suite/deployment-management/v1/deployments -H "appian-api-key: <API key>"

Workflow

Appian recommends that any package should first be inspected and then deployed.

The high-level workflow and endpoints for each step are:

1. Inspect your package, Admin Console settings, import customization file, or any combination of those using the /inspections endpoint. The endpoint response provides the UUID of the inspection, which you can use in the next step.
2. Retrieve the status and results of your inspection using the /inspections/<uuid> endpoint. The inspection may take longer depending on the size of your package. We recommend hitting this endpoint on a regular interval until the inspection is complete and results are available, which is indicated by the status response.
3. Deploy your Admin Console settings, package, customization file, plug-ins, and/or database scripts using the /deployments endpoint. The endpoint’s response provides the UUID of the deployment, which you can use in the next step.
4. Retrieve the status and results of your deployment, by using the /deployments/<uuid> endpoint. Similar to step 2, the deployment time will vary with the size of your package. We recommend hitting this endpoint on a regular interval until the deployment is completed and results are available, which is indicated by the status response.
5. If necessary, retrieve the deployment log for more detailed results by using the /deployments/<uuid>/log endpoint.

Feedback