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 it’s one or more applications, patches, environment specific data, Admin Console settings, or a mix. There are three methods for deploying a package in Appian:

• Compare and Deploy - Directly deploy applications and patches with guided steps.
• Export and Import - Manually import and export applications and patches between environments
• Automated Deployment Manager - Customize your own deployment process with this tool.

Before You Begin Deployment

We recommend that production deployments be performed during off-peak hours, especially when there are many changes.

If you are moving complete applications from a staging environment to a production environment, take standard precautions to ensure continuity:

• Before importing an application to your production site, create a backup the engine files (KDBs) if possible.
• To create a backup of your production objects, export all of the existing objects associated with your application. If the import should fail for any reason, this allows you to restore the previous state of the 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, these connected environments can be enabled to interact and directly deploy changes from one to another without manually downloading and uploading .zip files.

Use compare and deploy if you are pushing an application or patch between lower environments, such as development to test. Import customization files and database scripts can also be included.

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

• Compare and add objects to your package
• Inspect your package
• Deploy

Compare and Add Objects

After changes have been made, comparing objects between environments will help clarify which objects should be added to your package, making it easier to peer review and deploy.

1. Within an application, click Compare and Deploy.
2. Select a target environment to compare your objects against and deploy to.
3. Review your changes and add the necessary objects.
   • A. If the application properties, security, or actions have changed, the option is provided to either deploy the entire application or just a patch.
   • B. For an object with the status of Changed or Conflict Detected, click on the Status link to see the object comparison.
   • C. If you are deploying a patch, select the individual objects and add them to the patch. When deploying an entire application, all objects are automatically included.
4. Database changes can be deployed alongside object changes:
   • A. Click the Database Scripts tab.
   • B. Select the data source to run the scripts on. This is a list of data sources available on the source environment; the data source’s name on the target environment must match in order for the scripts to properly execute.
   • C. Upload the database scripts, which can be .sql or .ddl files.
     • Note: Scripts that contain custom delimiters, such as stored procedures, must be executed directly on your database. Compare and deploy currently does not support this functionality.
   • D. Specify the sequence of execution. Scripts can be moved up, down, or removed. Appian must be able to successfully run the scripts before it can attempt to deploy the objects. If an error occurs during script execution, the deployment will stop. To resolve script errors, refer to the deployment log for further details.
     • Note: Appian will attempt to rollback database changes if script execution is not successful. However, some database types and versions do not allow rollback of certain changes, such as data manipulations.
5. Once all objects and scripts are added to the package, click Next.

Inspect the Package

The package must be inspected against the target environment before deploying. Entire applications and patches can both be inspected, although this does not include uploaded database scripts.

Two types of results may need your attention:

• Missing precedents will appear if a necessary object is not included in the package and not already in the target environment.
• Warnings and errors that may prevent successful deployment of objects.

Once you resolve the issues, click Inspect Again to confirm that there are no missing precedents, warnings, or errors before clicking Next.

Review and Deploy

Confirm the high-level details, and add a name and description for the deployment. These allow you to track what’s included in a deployment, and will be reflected in the News posts on the source and target environments.

Click Deploy to immediately push the changes to the target environment. On the other hand, you can click Export to just download the package as a zip file; this will not affect the target environment. Only application administrators can deploy, while viewers and editors can export objects to which they have permissions. Refer to the security section for more details.

A confirmation dialog will appear once the changes are sent to the target:

On the source environment, a News event is posted on behalf of the user who sent the deployment. This post is visible only to this user and system administrators. Attached are the package zip file, database scripts, export log and a deployment log. Refer to Resolving Issues for more information on logging.

On the target environment, a system News event is posted. This post is visible only to system administrators, with similar information attached.

Automated Deployment Manager

Appian provides the Automated Deployment Manager which allows you to customize and even further automate your deployment process with Appian, by integrating with your team’s version control system and continuous integration tools.

For more information, 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. Appian recommends using this method of deployment if you are deploying an application or patch to a higher environment that requires further review, such as Test to Production.

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

Both export and import create an event in the News Feed. For import, the event has the import log attached. For export, the event will have both the export log and the exported package attached. By default, the user performing the export or import is the only viewer of the post, but they can add other users to it.

To deploy objects, import customization files, and database scripts directly to another environment, use compare and deploy.

Export

Once you've checked your application for missing precedents, you are ready to export your package. To export a package:

1. Depending on your package type, click one of the following buttons in your source environment:
   • To export an application, select it in Appian Designer, click EXPORT and select Application in the dropdown menu.
   • To export patches, in the application view click EXPORT PATCH.
2. Review or edit the file name and click EXPORT.
3. Click the Download package link to download the zip file. If your application contains objects with environment specific or sensitive values, click the Download import customization file link.

Applications that contain many objects may take a long time to export. You can navigate away or log out while the export is in progress, and the event will appear in the News Feed when the export is completed.

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 does not catch all possible errors, such as incorrect permissions or insufficiently unique names.

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:
   • Import Application for full application packages in Appian Designer.
   • Import Patch for patch packages in the application.
   • Import for admin setting packages and related application or patch packages in the Administration Console.
2. Upload your package zip file and related import customization file if applicable.
3. Click Inspect and review the inspection results.
4. Click IMPORT PACKAGE. Importing your package adds the objects directly in the environment.

Export and Import Multiple Patches Across Applications

To export multiple patches from the applications list view:

1. Select the Applications with Patches filter on the left-hand pane and check all the applications with patches.
2. Click the EXPORT dropdown menu and select Patches.
3. Edit the file name and click EXPORT.

The IMPORT option in the applications view handles both applications and patches for multiple applications. When you import a package that contains multiple patches, the corresponding objects are added to the appropriate applications, depending on where the patches 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 application or patch 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 compare and inspect these objects 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 admin console.

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 _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.

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. See the object comparison statuses for more information.