Overview

This page outlines the various methods to deploy a package from one environment to another, and which method is best for each type of environment.

When you deploy a package, changes are taken from the source environment and moved to the target environment. Some common deployment paths include:

Source Environment	Target Environment
Development	Test
Development 1	Development 2
Break Fix / Hotfix	Development
Test	Production

The optimal approach depends on the security considerations of your source and target environments, as well as the type of changes you have. Whether you are deploying one or more applications, packages, environment specific data, Admin Console settings, or a mix of these can impact how you decide to deploy. There are three methods for deploying a package in Appian:

• Compare and deploy (direct) - Directly deploy applications, packages, plug-ins, and database scripts with guided steps.
• Programmatic via APIs (external) - Customize your own deployment process with our native APIs.
• Export and import (manual) - Manually import and export applications and packages between environments.

Additional logic can be run after direct or external deployments by configuring a post-deployment process.

If you're an Appian RPA customer, remember you'll need to package and deploy robotic processes separately from applications. Learn how to deploy robotic processes and apps.

For production environments, we recommend preforming any deployment activities, including inspections, during off-peak hours. If necessary, a maintenance window can be scheduled in the Administration Console. Also, consider adding a post-deployment process to your application to automate tasks and make your development lifecycle more efficient.

If you are moving complete applications from a staging environment to a production environment, take standard precautions to ensure continuity by creating a backup of your production objects. If the import should fail for any reason, this allows you to restore the previous state of the application.

To create a backup of your production objects, export all of the existing objects associated with your application.

Compare and deploy across connected environments

Compare and deploy is the easiest and recommended method of deployment. If your DevOps infrastructure is set up, you can enable these connected environments to interact and directly deploy changes from one to another without manually downloading and uploading .zip files. For deployments to higher environments such as Production, you can require a review process by enabling it in the Administration Console

The compare and deploy feature guides you through a few straightforward steps:

• Select your target environment.
• Review your application objects, packages, database scripts, and plug-ins for deployment.
• Inspect your deployment.
• Deploy to your target environment.

Deployment contents

Within compare and deploy, you can deploy:

• All application objects.
• Packages.
• Database scripts.
• Plug-ins.

If you’re unsure about what you should deploy, check the table below to see which best matches your use case. You'll be prompted to choose one of these options when you reach the Prepare deployment step.

Deployment Contents	When to Use	More Information
Entire application	If the application does not exist in your target environment, you will deploy your entire application. You should also deploy an entire application if changes have been made to the application properties, such as application name, description, application actions, security, or post-deployment process.	You can include database scripts and plug-ins with your application deployment.
Package	If the application already exists in your target environment, you can create a package or select an existing package to deploy. To learn how to create a package, check out our Packaging Process.	You can include database scripts and plug-ins when you deploy your package.
ONLY database scripts or plug-ins	If your application already exists in your target environment and you only need to deploy plug-ins or make changes to the environment's database via scripts, you can deploy these changes without objects. Database scripts and plug-ins can only be deployed to a target environment using compare and deploy if you are an application administrator.	To deploy database scripts and plug-ins without other objects, the application must already exist in your target environment.

Select the target environment

Once you've determined what needs to be deployed, check that your deployment contents are prepared and ready to be sent to your target environment. If you're deploying a package, make sure that you've properly prepared it for deployment.

After everything has been prepared, it's time to start the compare and deploy process.

To start compare and deploy:

1. From within your application, click COMPARE AND DEPLOY.
2. Select the target environment to deploy to.
3. Click NEXT.

If you don't see any connected environments available, see DevOps infrastructure to learn more about setting up connected environments for deployments.

Prepare the deployment

The Prepare Deployment step helps you get all the objects, database scripts, and plug-ins together for deployment and check out any changes that have been made to objects.

In the Prepare Deployment step, you can:

• See all objects within your application or package.
• Manage the objects, database scripts, or plug-ins in the deployment.
• View the statuses for objects and plug-ins.
• Review changes to objects.

The Prepare Deployment step compares the objects in the application in your current environment to the target environment.

This comparison determines if the objects that you're deploying:

• Exist on the target environment.
• Exist on the target environment and have changed.
• Exist on the target environment but have conflicts with those in your source environment.

If the application and objects that you're deploying already exist in your target environment, you can check the status to see which objects have changed.

To check an object's status:

1. Click Changed to compare the changes between the two environments. Peer reviewers can also use this to quickly see the objects and changes they need to review.
2. Click Conflict Detected to view and resolve any issues between the object in the current environment and the target environment. For more information on resolving conflicts, see Addressing Object Conflicts.

From the Prepare Deployment step, there are three options for deployment:

• Deploy an entire application. If your application doesn't yet exist in the target environment, this is your only deployment option.
• Deploy a package.
• Deploy database scripts or plug-ins without application objects.

Skip to the relevant section for what you're deploying.

Prepare an application

To review an entire application for deployment:

1. If the application isn't in the target environment, all objects in the application are automatically included. Otherwise, in Package, select All Application Objects.
2. To add database scripts or plug-ins, go to the database scripts and plug-ins section.
3. If you don't need to add database scripts or plug-ins to your deployment, click NEXT to continue on to the Inspect Deployment step.

Prepare a package

To review a package for deployment:

1. Select an existing package from the Package dropdown list.
   • To learn how to create a package, check out our Packaging Process.
2. If any object has a Conflict Detected status, address the conflicts before deploying. Click Conflict Detected for more details.
   • See more information about object statuses.
3. To add database scripts or plug-ins, go to the database scripts and plug-ins section.
4. If you don't need to add database scripts or plug-ins to your deployment, click NEXT to continue on to the Inspect Deployment step.

Prepare database scripts or plug-ins

Database scripts and plug-ins can be deployed on their own or included within the deployment of an application or package.

Database scripts and plug-ins are not exported along with packages and application objects, so skip this step if you do not have permission to deploy directly to the target environment.

If you're deploying database scripts or plug-ins without any application objects:

1. Select Deploy only database scripts and plug-ins.
2. Add your database scripts and plug-ins using the steps below.

To deploy database scripts:

1. Click DATABASE SCRIPTS.
2. Select a Data Source.
3. Click UPLOAD to add your database scripts. If you’re deploying multiple scripts, set the execution order by using the up or down arrows.
4. Click NEXT and continue on to the Inspect Deployment step.

For information on using database scripts and record types with sync enabled, see force sync on import.

To deploy plug-ins:

1. Click PLUG-INS.
2. Select the plug-ins you want to deploy and click INCLUDE.
   • See more information about plug-in statuses.
3. Click NEXT and continue on to the Inspect Deployment step.

Inspect deployment

The Inspect Deployment step checks all of the objects in your package for security warnings, failing test cases, and missing precedents. This step eliminates most manual checks and helps you to identify and resolve issues with the objects in your package.

If you are only deploying database scripts or plug-ins, there is no inspection required at this step but you should review them manually before deployment. Note that if a database script or plug-in fails during deployment, Appian will attempt to rollback changes. For more information on resolving problems with your deployment, see the deployment log.

To inspect your package for deployment:

1. If there are no issues to resolve, click NEXT to continue to the review and deploy step.
2. If there are any warnings for security or test cases click Review and resolve the issues.
3. If there are any missing precedents, select the missing object and click ADD TO PACKAGE.
4. Once the issues are resolved, click Inspect Again.
5. Continue until all issues are resolved, then click NEXT.

Review and deploy

Your deployment is almost ready to go. Just review a few high-level details to confirm that this is the information that you want displayed in the deployments view and you’re ready to deploy.

To complete your deployment:

1. Edit the deployment name and description if necessary.
2. Optionally select Delete package after deployment. For more information, see Deleting Packages.
   • If you're deploying anything other than a package, this option isn't shown.
3. Click Deploy. Only application administrators can deploy and the target environment must have direct deployments enabled. See security for more information.
4. If you aren't an application administrator, click Export. Then download the package and the export log. This won’t affect your target environment.

A confirmation dialog will appear once the deployment has been sent to the target environment.

Once your deployment is in progress, the deployment details will be available on the deployments view of both the source and target environments. Deployment details are only visible to system administrators and application administrators.

If your deployment requires review, application administrators and users in the reviewer group will receive an email about the pending deployment. They can approve or reject deployments in the deployments details view.

Programmatic deployments via APIs

Appian has native deployment APIs that can be called from external tools, such as Jenkins. There are five endpoints that allow you to inspect and deploy packages, import customization files, and database scripts.

This allows you to programmatically trigger deployments and integrate your Appian release into an automated pipeline. You can set up your pipeline once and run it the exact same way for all future deployments, saving time and avoiding manual errors.

In order to programmatically deploy Administration Console settings or tightly integrate with a version control system to store and retrieve package files, use the Automated Deployment Manager. For more information on setting it up, see the DevOps Quick Start Guide.

Manual export and import

Packages can be manually exported from the source environment and then imported into the target. Import and export details are available in the deployments view of every environment. Appian recommends using manual export and import if you do not have environments added to your infrastructure. To deploy objects, plug-ins, import customization files, and database scripts directly to another environment, connect your environments and use compare and deploy.

Import customization files can be included in your packages for manual export and import, but other dependencies, such as changes to Administration Console settings, database scripts, and plug-ins must be handled separately.

Export

Once you've checked your application for missing precedents, you're ready to export your package.

To export an application:

1. In Appian Designer, select your application.
2. Click EXPORT.
3. Select Application in the dropdown list.
4. Review or edit the file name and click EXPORT.
5. Click the DOWNLOAD PACKAGE button to download the zip file. If your application contains objects with environment specific or sensitive values, click Download Import Customization File.
6. Once your application download is complete, click CLOSE.

To export a package:

1. In the application view, click PACKAGES.
2. Select a package.
3. Click EXPORT.
4. Review or edit the file name and click EXPORT.
5. Click the DOWNLOAD PACKAGE button to download the zip file. If your application contains objects with environment specific or sensitive values, click Download Import Customization File.
6. Once your download is complete, click CLOSE.

Inspect and import

Since you can't undo an import, you should always inspect a package before completing the import to check for warnings, conflicts, or missing precedents. Inspecting objects identifies general issues, such as missing dependencies, data stores that don't match the schema on the target environment, and package corruption or invalid XML.

Inspect may not report some errors. Insufficient permissions, duplicate object names, other users editing the object, and missing import customization files are some issues that can cause import failures but are not reported when inspecting objects.

Importing an application into another application will add objects to that specific application. You can remove them by selecting the imported objects and clicking REMOVE FROM APP in the toolbar.

To inspect and import a package:

1. Depending on your package type, click one of the following buttons in your target environment:
   • Application: In Appian Designer, click IMPORT.
   • Packages: In the application, click IMPORT PACKAGE.
   • Administration Console settings: In the Administration Console, click IMPORT.
2. Upload your exported zip file and related import customization file if applicable.
3. Click INSPECT and review the inspection results.
4. Click IMPORT PACKAGE. Importing adds the objects directly in the environment.

Export and import multiple packages across applications

To export multiple packages from the applications list view:

1. Select the Applications with Packages filter on the left-hand pane and check all the applications with packages.
2. Click the EXPORT dropdown list and select Packages.
3. Select a package from each application.
4. Edit the file name and click EXPORT.

The IMPORT option in the applications view handles both applications and packages for multiple applications. When your import contains multiple packages, the corresponding objects are added to the appropriate applications, depending on where the packages were created.

Inspecting data types from web services

It's a best practice to include data types created from web service definition languages (WSDLs) in your package before exporting it. If those data types are not included in your package AND they don't already exist on the target environment, they'll be listed as problems in the inspection results. Data types that are normally created by the Call Web Service Smart Service or webservicequery() function during import cannot be created by the package inspection process.

Security

Source environment

Developers with viewer access to an application and objects are able to create, compare, and inspect packages across environments, and manually export them. Application administrators and system administrators on the source environment are the only roles able to directly deploy to the target using compare and deploy.

Target environment

Before using compare and deploy, a system administrator account must be specified when setting up deployment configuration in the administration console. The Deploy As account must be in the service account role.

When manually importing a package, you must ensure that you can administer the application and the objects that it contains:

• For new objects, the user must be able to create an object on the environment. For example, only a System Administrator has the rights to create a Public group (non-system administrators can only create Public groups within groups that they administer).
• For existing objects, the user must already be an administrator of the object.

The Last Modified By field displays the user who most recently modified the object and the time at which it happened. If the object supports versioning, the Last Modified By information of previous versions are not affected.

Best Practice: Regardless of deployment method, we recommend using a group for each application called <Application_Name>_Administrators.

1. Create the group on the source environment, and export it (in an application package) to the target machine prior to importing the main application. The group must be deployed in an application package in order for Appian to recognize it as the same group on both environments.
2. Before exporting the application, add this group to all object rolemaps. Assign Administrator rights to this group.
3. Temporarily add the users (or user) who imports the application on the target environment to this group before performing an import.
4. After the import, remove users from the _Administrators group, as needed.

Deploying security rolemaps with exported objects

When objects are deployed to another Appian environment, the deployed objects contain a reference to the users and groups listed in their rolemaps. For example, an exported Knowledge Center contains the list of users and groups with rights to the Knowledge Center.

Rolemap deployment rules:

• A user or group is only included in the rolemap of a deployed object if at least one of the two conditions below is true.
  • The group is present in the import package or on the target server.
  • The user exists on the target server and is not deactivated. All other users are dropped.
• When importing an object that already exists on the target server (identified by UUID), the resulting rolemap of the object is what's defined in the import package.
• Some objects can be configured to inherit their rolemaps from their parent. This configuration is preserved when the object is exported and imported. If the configuration of the object in the import package differs from what’s on the target server, the setting in the import package is used.

Object behavior in target environments

If an object already exists on the target environment (an object exists there with the same UUID), then:

• A new version is created, if the object supports versioning. A new version is created even if the only modification was to its rolemap.
• The object in the package overwrites the object in the target, if the object does not support versioning.

Because objects in a deployment aren't updated simultaneously, users may see some inconsistencies in their application behavior as objects are updated. For example, during a lengthy deployment, a constant may be updated but the process model that references the constant has not been updated yet.

During deployments that include a record type with sync enabled, the record type must successfully sync in that environment before it will be available. This may mean that your record type will be unavailable to users, processes, or APIs until the import is complete. For more information on record types with sync enabled, see Data Sync in Appian Records.

Deploying database scripts to force a sync

When deploying database scripts that add rows to the source table of a record type with sync enabled, you can use the force sync command in the import customization file to see the new rows from your source directly after import. The record type does not need to be in the deployment package in order to force a sync. Instead of forcing a sync, you can also wait for the next scheduled sync of the record type or trigger a manual sync on the record type object directly.

To force the sync on import:

1. In your import customization file, uncomment the command recordType.<UUID>.forceSync = true.
2. Replace <UUID> with your record type’s UUID.

To find your record type's UUID:

1. From the application view, open your record type object.
2. In your record type object, click the gear menu.
3. Click Properties. Find the UUID near the bottom of the dialog.

For more information on record types with sync enabled, see Data Sync in Appian Records.

Resolving issues

Issues may be encountered for various reasons. For example, an error may occur when you are not an administrator of the object, or if you attempt to deploy a group with the same name as another group.

Best Practice: Inspect the package before deployment in order to identify issues ahead of time.

Deployment errors

Object errors

The deployment, including the export and import processes, does not stop when errors are encountered on specific objects.

However, a problem during the import of an object may cause the import of related objects to also fail. For example, a failure to create a group type during an import would cause the import of any groups of that type to also fail (Appian does not attempt to import these groups in this case).

If a group fails to be created during import, and the group exists in rolemaps for other objects - or is a member of another group - the other objects (or groups) will fail to import due to the missing precedent.

Database script errors

The deployment will completely stop when a database script cannot be executed. In this case, Appian will roll back all possible changes that have been executed so far - this will vary depending on your specific database server. Executing subsequent database scripts and deploying objects will not be attempted.

Reading deployment logs

In each case an error occurs, Appian gathers and displays information on any problems after all objects in the package have been processed. Generally, you can do one of the following:

1. Resolve the cause of the problem as identified by the log and try again.
2. Retry with only those objects that failed due to the issue identified. You might prefer this option when the package is especially large.
3. Manually create or update the failed objects in the target environment.

Deployment log

When using compare and deploy, a deployment log is generated. The log details the stages of your deployment - such as the sending and receiving of the deployment request, executing database scripts, and importing the objects - and whether they succeeded. Errors that occur during database script execution or object import are included here. For more information on object import errors, see below.

Import log

When manually importing, an import log is generated. Objects with import issues are placed in one of two sections at the top of the import log:

• Problems: Lists the items that could not be imported and the reason why. Make sure to address the cause of the problem before attempting to import the application again.
• Cascading Problems: Lists the items that could not be imported because they reference an item that failed to import previously. They do not need to be addressed individually.

The following example illustrates the log entries that may be generated when an object reference is not included in the package, and is not present in the target environment.

In this instance, an imported process model listed an individual user for the assignment of an activity. We recommend using groups for assignments instead. Otherwise, ensure that the target environment has a user with the same username, prior to importing the application.

Additional sections in the import log include:

• Success: Lists the items that were successfully created or updated by import.
• Not Changed: Lists the items that were skipped by import because they contained no updates.
• Version Synchronized: Lists the items were imported to synchronize the version histories. These items had different version histories but were otherwise identical.

See the object comparison statuses for more information.