Appian allows you to move applications to different servers by exporting objects into XML files, bundling them into a ZIP-format package, and then importing them. The tool exports the associated object properties, security rolemaps, and information about related objects as part of the package. The links between related objects are preserved across the move except where specifically noted. In most cases, the related objects themselves are not automatically exported. Instead, they must be explicitly added as objects within the application, or be already present on the target environment.
The Application View allows you to scan your application for missing precedents and automatically add them to the package. The export limitations described in this page explain those relationships that cannot be preserved during export and import of the application.
Each such limitation also applies to dependency scans. If we do not preserve an object relationship during export, it cannot be detected by the dependency scan.
See also: Missing Precedents
The export and import process follows rules for each object exported, and certain general rules.
If an imported object already exists in the destination environment (identified by a universally unique ID or "UUID") a new version is created – so long as versioning is supported for the object. (Versioning is supported by Appian for objects such as rules, process models and documents.) When this is true, a new version is created even if only the rolemap of the object has changed. There is no distinction between an object's rolemap and its properties during import.
When versioning is not supported for an object, the imported object overwrites the object in the destination environment and its properties.
Best Practice: Test each application package using the Inspect Package feature prior to deploying the application to identify issues with a deployment before you apply changes that cannot be undone or may cause problems on the server.
Export or import issues might be encountered for various reasons. For example, an error may occur when you do not have ownership of the exported or imported object, or if you attempt to import a group with the same name as another group.
A problem during the import of an object might 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 (the tool does not attempt to import these groups in this case).
When an import/export problem occurs, the message displayed indicates the cause of the problem (in most cases) and identifies the object or objects that were not successfully exported or imported. In such cases, you can do one of the following:
If a group fails to be created during an 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.
See below: Deploying Security Rolemaps with Exported Objects
Objects with import issues are placed in one of two sections at the top of the import log:
The following example illustrates the log entries that may be generated when an object reference is not included in an import package, and is not present in the destination 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 destination environment has a user with the same username, prior to importing the application.
Additional sections in the import log include:
When an object is created during an import, the user performing the import is listed as its creator. The current date and time is the object's creation timestamp. When an object is updated during an import, the user performing the import is listed in the object's last modified by field. The current date and time is the object's last modified timestamp.
If the imported object supports versioning, the user performing the import is listed as the new version's creator. The current date and time is listed as the new version's creation timestamp. The creator and creation timestamp of previous versions are not affected.
The creator and last modified by user are not given administrator rights for that object. The list of user rights are based on the security rolemap defined for the importing object.
See below: Deploying Security Rolemaps with Exported Objects
Users cannot be exported and imported. When importing objects that reference users such as in task assignment or constant values, the users must already be present in the destination environment (identified by username) for the import to succeed. If they are not present, the import of the object fails.
Object rolemaps and group membership, however, are excluded from this rule. That is, import succeeds even if users that are not in the target environment are referenced in imported objects' rolemaps or are members of imported groups.
Applications typically rely on some system configurations in the Administration Console. They need to be configured for the applications to be fully functional.
Administration console settings that are related to applications can be imported and exported from the Appian Administration Console. The applicable settings are listed in the Categories section below, followed by the Import Customization section that describes how to customize your import per environment.
Learn more about importing an application and its related administration console settings together in the Importing Applications and Admin Console Settings Together section.
The categories of admin console settings that can be imported and exported are listed below.
All of the settings shown on the Branding page in the admin console can be exported as one item. If an image is uploaded as the logo or favicon, the file will be included in the export package.
The Allow News Entry Deletion setting shown on the Data Retention page in the admin console can be exported as one item.
The Enable Periodic Cleanup of Export Packages setting can be exported as one item.
The Allow Test Values to Be Imported with Design Objects and Allow Database Schema Changes Through Data Stores settings shown on the Deployment page in the admin console can be exported individually.
The Blocked File Extensions and Virus Scanning settings shown on the File Upload page in the admin console can be exported individually.
The Language and Date and Time settings shown on the Internationalization page in the admin console can be exported as one item.
The mobile device settings shown on the Mobile page in the admin console can be exported as one item.
The Editable User Profile Fields, Default User Profile Visibility, and Quick Apps Data Source settings shown on the Permissions page in the admin console can be exported individually. To export and import Quick App Creator permissions, export the Quick App Creators group.
Note: Member groups are included when exporting a group, but individual user members are not. See also: Groups
The list of Encryption Service public API permissions for all plug-ins shown on the Plug-ins page in the admin console can be exported as one item. For example, if you have plug-in X that has permission to use the Encryption Service and plug-in Y that doesn't, both permissions would be set during import if the setting was included in your import package. On import into the target environment, only the plug-ins that are listed in the package are updated. You may have more plug-ins in the target environment, and their Encryption Service configurations are not updated.
Appian recommends that if you are sharing an admin console package with environments where you have no knowledge of the deployed plug-ins, you should not include this setting as it might overwrite a plug-in's permissions.
Note: Plug-ins themselves cannot be imported or exported.
All of the settings shown on the Sign-in Page Links page in the admin console can be exported as one item.
The default start page setting and the list of user start pages on the User Start Pages page can each be exported and imported independently. Groups that are associated with a start page must already exist on the target system or be included in the import for the list of user start pages to be imported successfully. These groups are not exported along with the list of start pages when it is exported.
If one of your start pages points to a specific record or action, this URL will not be the same across environments so be sure to confirm the URL is correct for these pages after import.
All of the settings shown on the Appian Authentication page in the admin console can be exported as one item. To support different authentication requirements across environments, all of the Appian Authentication settings can be set during import using an import customization file. If the customization file fails any validations on import, none of the Appian Authentication settings will be updated.
Data sources can be imported and exported from the administration console. A data source's name, type, and connection string are included when it is exported. The username and password for a data source are not exported for security reasons. It is possible to provide a data source's type, username, password, and connection string during import using an import customization file.
During import, Appian tests the connection of the data source, if a connection cannot be established successfully, the data source will fail to import. This connection test also happens during inspection.
When importing a data source onto a target environment for the first time, an import customization must be provided with at minimum the username and password specified. The connection string and database type are included with the exported data source but since they may vary between systems, they can be specified in the import customization file as well.
When updating an existing data source via import (identified by its UUID), the data source's username and password are not overwritten. This means the username and password for a data source do not need to be provided in the import customization file if the data source has already been configured on the target environment; the connection test will still be executed during inspect and import but it will use the currently defined username and password. To set a different username or password via import, provide their values using an import customization file.
If you change the name of your data source, you either need to include the objects that use the data source in the import as well, or manually update them to use the new data source name after import.
Note: If you have data sources defined in the administration console prior to Appian 16.2, you will need to follow the steps in the 16.2 Update Guide to be able to update those data sources via import.
You can import a data store that points to a data source together with the data source. Learn more in the Importing Applications and Admin Console Settings Together section below.
The Allow Appian to Send Email setting shown on the Email page in the admin console can be exported as one item.
The Origins and Themes shown on the Embedded Interfaces page in the admin console can be exported individually. The list of allowed Origins is exported and imported as a single item, while each Theme is exported and imported invidually.
If a Theme uses an expression to define either the Page Background Color or Accent Color, the expression will be exported and imported as written. Any referenced application object (e.g. constant) in an expression will need to be included in the import process or already exist in the target environment.
All of the settings shown on the HTTP Proxy page in the admin console can be exported as one item. If you are using proxy authentication, the username and password are not exported for security reasons. It is possible to provide a username and password during import using an import customization file. The other HTTP Proxy settings can also be changed on import using an import customization file.
All of the settings shown on the Microsoft Office page in the admin console can be exported as one item.
Third-Party Credentials can be imported and exported from the administration console. All information about third-party credentials are exported except for the credential field values themselves. These values are not exported for security reasons because they are typically sensitive in nature, however, they can be set during import using an import customization file.
When importing a set of third-party credentials onto a target environment for the first time, the credential field values can be configured in one of two ways:
When updating a set of third-party credentials via import (identified by its UUID), the credential field values are not overwritten. To update them, set their values in the import customization file. It is possible to update some field values and not others during an import.
Additionally, updating the set of third-party credentials via import will not reset any per-user credentials that a user has stored. These will only be removed if that specific credential field has been deleted from the third-party credentials.
Note: If you have third-party credentials on your system prior to Appian 16.2, you will need to follow the steps in the 16.2 Update Guide to be able to update those third-party credentials via import.
Third-party credentials may reference Appian design objects in its Test Connection field and these objects are not exported along with the third-party credentials. These objects must already exist on the target environment or be imported together with the third-party credentials for the third-party credentials to be imported successfully.
Third-party credentials may reference plug-ins. The referenced plug-ins may be deployed before or after the third-party credentials, and the reference to the plug-in name will be preserved. Appian recommends that plug-ins are deployed before importing your applications and admin console settings.
The following admin console settings cannot be exported and imported:
In addition, the Process Calendar found in the Appian Designer Objects view cannot be exported or imported.
Administration console settings and application objects can be tightly coupled. Because of this, Appian allows you to import an application package and an administration console package together from the Import Settings dialog in the Appian Administration Console.
These packages will be included in a single import, so any dependencies between them are identified and properly resolved. Dependencies include:
You can choose to import a patch instead of an application by selecting the Patch option on the Import Settings dialog. When uploading a patch package, you will be required to select the application to which the patch objects should be added. Administration console settings are never added to an application.
A deployment can be parameterized with an import customization file. Use the import customization file for values that vary between environments or that are not exported for security reasons, such as passwords.
When exporting objects or admin console settings that can be parameterized, an import customization .properties file is generated. This file lists all the values that can be configured for the applicable objects or settings (they are commented out by default). You will need to fill this out and provide it in the Import Settings dialog in the admin console along with the application or admin console package.
An example customization file contains the following:
## Administration Console Setting: Third-Party Credentials ## Name: Jira thirdPartyCredentials.6f59ef17-672d-444c-9c1c-31410474aad0.username=jira.system thirdPartyCredentials.6f59ef17-672d-444c-9c1c-31410474aad0.password=1password! ## Administration Console Setting: Data Source ## Name: jdbc/LegacyDB ## Valid types: DB2, MySQL, Oracle, SQL Server dataSource.935f04f8-e8ac-449f-8410-d9ac13cac74e.USERNAME=db.user dataSource.935f04f8-e8ac-449f-8410-d9ac13cac74e.PASSWORD=1234abcd #dataSource.935f04f8-e8ac-449f-8410-d9ac13cac74e.TYPE= #dataSource.935f04f8-e8ac-449f-8410-d9ac13cac74e.CONNECTION_STRING= ## Constant: CO_WEB_SERVICE_URL ## Type: Text ## ## Text values will be displayed in Appian exactly as they are ## specified here. No spaces are trimmed. Values do not need to be ## encased in quotation marks. content._a-0000de3d-42e6-8000-1c9f-01ef9001ef90_5573.VALUE=https://testsite.com/BLZService?wsdl
The following rules apply to how an import customization file is read and values are set:
# are ignored.= character and the next line break, including any whitespace.An import customization file can also be provided when performing an import using the ImportExportService. For more information, please refer to the Appian Public API.
Refer to the Managing Import Customization Files page to learn more about how to maintain these files for your deployment processes.
Appian supports export/import for the following objects.
For the images displayed in the subsections below, the following key applies:
In Appian, you can export an application for import onto another server. The application properties, navigation items, user rights, and all associated objects are included in the export. For example, a process model and a page are associated with an application named expenses. When exporting the expenses application, the process model and the page are also exported. Importing an application overrides its application properties, its set of associated objects, and the existing navigation items.
Both published and unpublished applications can be exported. On import, the state of an application is the same as it was when exported.
In Appian, a document (or file) resides in a folder, which resides in a Knowledge Center, which resides in a Community, which might reside within another Community. A document export includes the document, the document properties, and a reference to its parent object (such as the folder where the document resides). A Document, Folder, Knowledge Center, or Community might also be associated with a forum.
The image above illustrates the relationships between Document Management objects. Items displayed in red indicate required objects. Dashed lines indicate object references. Objects and references fully contained within an object's border indicate items that are automatically included within an object when it is exported.
The objects in the hierarchy must each be selected for inclusion in your application. An export of a document does not include the actual parent object of the document, only the awareness of the parent object. Imports fail if the necessary parent object is not present.
If a document already exists on the server that you are importing onto, a new version of the document is created. For documents and document containers, any existing object properties are overwritten by an import.
When exporting a content container (such as a Community, Knowledge Center, or Folder) only the selected container is exported. The contents are not exported.
If you do not have the necessary user rights to add or update the object being imported, then the import fails. For example, if an import package contains a folder that resides under a given Knowledge Center, the user importing the folder must have the right to create a folder in that Knowledge Center.
The ZIP file of Knowledge Center or Folder downloaded from the Document Management interface using the Download toolbar action is not importable from the Applications view. Instead, perform a bulk upload from the Documents tab.
See also: Document Management
If you've created Document Management objects using Appian's Java API, be aware that the system flag is no longer used. It is ignored when importing documents and document containers.
Group application objects can be exported then imported into another environment.
All properties of group objects are exported except for users listed as members in the group object. On export, group objects do not retain references to individual users listed in the members tab of the group, but do retain references to member groups in this tab. The administrators tab will export references to both users and groups.
Importing new or modified group objects requires that the user have sufficient privileges in the destination environment to create or modify groups.
When importing a group object, references to users or groups that do not exist in the destination environment are discarded.
To preserve the integrity of group properties and relationships, it’s best to export all related group and group type objects together.
When importing a group object into an environment where a group with the same UUID already exists, all properties of the inbound object overwrite the properties in the destination object except for group membership (users and member groups listed in the members tab); the inbound object and the destination object member lists are merged.
This means references to users and member groups in the destination object cannot be deleted as a result of importing an object without those references.
A group object may fail to import when:
Group types allow you to specify attributes (required or optional) for each group of that type. Required attributes must be input when each new group (of the type) is created. It is possible for these attributes to vary from environment to environment for the same group type. If the list of attributes of an imported group does not match the list of attributes of the group type in the destination environment - and the import package does not include a corresponding group type - the imported group's list of attributes is updated to match the group type in the destination environment. All groups of a group type must have the same set of attributes.
Exporting a group type packages its properties (the list of attributes and attribute values associated with all groups in the group type) into a zip file for import on another environment.
When an import package includes a group and its group type - but the list of attributes of the group do not match the destination environment - the import package attributes are applied to the destination environment. The group type is imported first, followed by the group.
If you exclude the group type from the export package, and an imported group's attributes do not match those of the existing group, the result of the import preserves the values of the attributes in the destination environment.
On import, if the same group type exists on the target server (identified by UUID), all group type properties and its list of attributes are overwritten by the imported group type, except the values of the attributes. Attribute values are not overwritten on import. You cannot update the default values of group type attributes.
If a group type with an existing name (but different UUID) is imported, the import of the group type fails. Group type names must be unique within one installation (instance) of Appian.
The names of system group types cannot be updated.
If two or more attributes of a group type have the same name, only the first attribute is added to the group type. Group type attributes must have unique names.
Process models and process model folders can be exported for import onto another server. Process instances are not exported.
Process Model Folders
A process model folder export includes the folder's properties and user rights. The contents of a process model folder (any sub-folders or process models) must be selected individually for export as well, and are not exported automatically with the folder.
The My Models folder only exists on the server when it is used for the first time. This occurs when a subfolder is created within it, when a process model is placed in it (or if the folder is renamed for any reason). Only after the folder has been used is it exportable. For the sake of import and export, the My Models folder is treated as any other process model folder, and is created at the root level (in the left navigation of the Processes view) when imported.
API DEVELOPERS ONLY: The ProcessModelFolder type and isSpecial attributes are not exported. On import, the type attribute is set to TYPE_COMMUNITY, if the folder has no parent. Process model folders that have a parent folder inherit the type of the parent folder.
Process Models
A process model resides in a process model folder. A process model export includes its properties (name, description, etc), definition (process flow), user rights, a reference to the process model folder where it resides, and a reference to any custom dashboards. A process model can include references to many other object types. A referenced object must be present in the destination environment - or you must include it in the application package - to successfully import the process model.
When exporting a process model, the latest published version is exported (if published).
On import, process models are published as a new version.
Importing an application package that contains a process model makes it available to the Process Modeler, in a similar manner to the legacy process model import.
If a process model contains a Send Message event that specifies another process model for its destination configuration, and if the model generally targets a process model, rather than a specific Receive Message event in the process model, the process model (with the Send Message event) can be imported - but not published.
If a process model contains a smart service that stores passwords, such as the Query Database and Call Web Service smart services, the passwords are not exported.
If a process model contains an Escalation Task that uses rules and/or constants in an expression for the task recipient, the rules and/or constants are not exported.
When an import package contains a custom data type (data type) with the same name and namespace as a data type that already exists in the destination environment, all objects excluding running processes will be updated to use the imported definition of the data type. Additionally, any dependent objects in the import package will reference the new version on import. Data types in the import package that are detected as Not Changed on inspection will not be updated unless they depend on a data type that is updated.
When importing a package containing data types, the data types complete import first and then the rest of the design objects in the package import. If one data type fails to import, the other data types in the package and their dependent objects will also fail to import, in order to preserve the integrity of the data structure.
Note: Since data type references in the package are updated on import, ensure that all objects are referencing the latest versions of all data types on export. If outdated references are exported, unexpected behavior changes or errors can occur at runtime because references were updated on import. There could be a brief window of time when the data types in the package have imported but the updated design objects that depend on those data types have not yet imported, therefore it is recommended that you always make compatible changes to the data type.
Data type metadata is not imported. Imported data types take the following properties:
XSD Import is listed as its Source.There are special considerations when dealing with data types that are created from WSDLs configured in Call Web Service smart services or webservicequery() functions. If the data types are not included in the application, they will be created on the target environment at the time of import by calling the WSDL using the following process:
This can increase import time and could lead to data type structure mismatches if the WSDL has changed.
Best Practice: Always include data types created from WSDLs in the application created in the development environment before exporting it.
See also: Call Web Service Smart Service and webservicequery()
Data stores can be added to your application packages for export and import.
Exporting Data Stores
When exporting a data store, the data source JNDI name is also exported.
Importing Data Stores
Expected Results when Importing Published Data Stores:
The following results occur when importing an application package that contains a published data store.
| Data Store Version on Destination System | Result when Publishing Succeeds | Result if Publishing Fails |
|---|---|---|
| None | A new published version is created. | |
| Draft | A new published version is created. The draft version is discarded. | |
| Published, without a subsequent draft version. | A new published version is created. | |
| Published, with a new draft version. | A new published version is created. The destination environment draft is discarded. |
Expected Results when Importing Draft Data Stores:
The following results occur when importing an application package that contains a draft (unpublished) data store.
| Data Store Version on Destination System | Result on Import |
|---|---|
| None | A new draft version is created. |
| Draft | The draft in the destination environment is overwritten by the draft in the application package. |
| Published, without a subsequent draft version. | A new draft is created; the published version is not affected. |
| Published, with draft | The draft version in place is overwritten using the draft in the application package. |
Reports are managed as documents for export and import. References are retained by reports after export and import, except for certain contexts. Supported references are listed when using the Missing Precedents tool in the Appian Designer.
See also: Missing Precedents
The following references are retained on import when included in an application package.
Reports exported prior to Appian 6.0.2 do not include these references. Export the report again using an upgraded version of Appian to enable the references.
When a report definition specifies a process instance context, the context will not be preserved after the report is exported. (Individual process instances cannot be exported or imported.) The report context must be reconfigured after import. This does not impact reports without a context, or those that take a run-time context (from a dashboard when shown in a Report Channel, or by prompting the user to select a context).
Rules folders, rules, and constants can be exported and imported onto another server.
The Rules folder export includes its properties, user rights and a reference to any parent folder. The contents of a rules folder (sub-folders, rules, and constants) are not exported automatically. The rule folder must be included in your application in order to import a rule or constant.
A rule or constant export includes its properties, definitions, user rights, and a reference to its parent folder. A rule definition can reference other rules and constants. A constant can reference most other object types. When exporting a rule or constant, the latest version is exported. On import, a new version of the rule or constant is created.
Duplicate names for rules and constants are not allowed. On import, if the name of the importing rule or constant matches an existing rule or constant (with a different UUID) or any interface, integration, or function, the import fails.
Constants have the option of being configured so that their value is not overwritten when the object is imported. When exporting environment specific constants, their values are not included in the object's exported XML file. Instead, the value of an environment specific constant can be preconfigured via an import customization file that will be set during the import.
The rules that govern how environment specific constants behave when imported are as follows:
For general guidance and best practices for creating, managing, and maintaining import customization files, see Managing Import Customization Files.
A connected system export includes its properties, user rights, and a reference to its system logo.
Duplicate names for connected systems are not allowed. On import, if the name of the importing connected system matches an existing connected system (with a different UUID) the import fails.
Connected systems support the same environment specific values as integrations.
An integration export includes its properties, definition, user rights, and a reference to its parent folder. An integration definition can reference rules and constants. When exporting an integration, the latest version is exported. On import, a new version of the integration is created.
Duplicate names for integrations are not allowed. On import, if the name of the importing integration matches an existing integration (with a different UUID) or any interface, rule, constant, or function, the import fails.
The following integration fields automatically support environment specific values:
When exporting environment specific integration fields, their values are not included in the object's exported XML file. Instead, the value of an environment specific field can be preconfigured via an import customization file that will be set during the import.
The rules that govern how environment specific integration fields behave when imported are as follows:
For general guidance and best practices for creating, managing, and maintaining import customization files, see Managing Import Customization Files.
When exporting feeds, the feed properties and user rights are included.
System objects are created automatically by Appian, and can be included in your application packages for export. Examples of system objects include system reports, the System Knowledge Center, and other objects such as the default process dashboard page.
System objects can be exported and imported. Each system object is given a predefined UUID (also called a system UUID) with the format SYSTEM_<OBJECT-TYPE>_<OBJECT-NAME> that is the same on each installation of Appian. This means that on import, the corresponding system object on the target server is updated.
The following system objects are not listed as application precedents when scanning an application using the Missing Precedents tool.
If you modify one of these system objects, and you want to include it in your application, you can select it in the same manner as other objects of that same category.
See also: Application View
If you are moving complete applications from a staging environment to a production environment, take standard precautions to ensure continuity.
You have to have at least viewer rights for any object to export it.
The user who imports an object is listed as its creator, but is not given administrator rights for that object.
You must have the right to create an imported object in order for an import to succeed. 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 administrate).
If you are importing (updating) an object that already exists in the destination environment from a prior import, you must have administrative rights for the object, or the import fails. To update an object, you must have the right to update the object's properties, as well as the object's rolemap.
The user who imports an application does not automatically have the necessary user rights to administer an application object. You must ensure that the importer of the application can administer it and create the objects that it contains.
Best Practice: For each application, we recommend using a group called <Application_Name>_Administrators to hold the necessary object creation rights for successful import of your application.
Your application administrators group must be uniquely identified as the same group on both the source and destination environments. The group must be deployed in an application package in order for Appian to recognize it as the same group on both environments.
Almost all Appian objects are associated with a set of users and groups who hold certain rights to view, execute, or change the object. When objects are deployed to another Appian installation, the associated user rights are also moved. 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. A deployed object's rolemap (and resulting user rights) can vary based on the objects that are present in the import package and on the target server.
Rolemap deployment rules:
Export Package
An exported Knowledge Center has the following rolemap:
| Role | User or Group |
|---|---|
| Administrators | group1, user1 |
| Authors | <none> |
| Readers | group2 |
Target Server
The same Knowledge Center and group2 exist on the target server, but group1 and user1 do not. The Knowledge Center on the target server has the following rolemap:
| Role | User or Group |
|---|---|
| Administrators | group3 |
| Authors | group2, group4 |
| Readers | <none> |
Target Server after Deployment
After the package is imported onto the target server, the following rolemap for the Knowledge Center is created as a result:
| Role | User or Group |
|---|---|
| Administrators | group1 |
| Authors | <none> |
| Readers | group2 |
Deployment Results
After this example import has occurred, the following results appear in the rolemap.
