Application Deployment Guidelines

The Export and Import Process

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.

Cautions

  • Modifying the generated XML files and internal structure of the ZIP export package is not supported.
  • Application packages from an earlier version can be imported by later versions. Packages exported from later versions of Appian are not compatible for importing into prior versions.
  • Precedents of one application can impact another application. Importing a sub-process, group, folder, or other application component used by more than one application can have unintended side effects.
  • Process models that are configured to run as their designer will fail to run if the designer user becomes deactivated. Appian recommends that applications be imported using a service account of type System Administrator that will not be deactivated.

General Rules

  • During export, Appian processes the list of objects to be exported one-by-one and captures the state of the object when the export is initiated. If the contents of a container object change while you are creating the package, the exported contents will reflect the objects at the time the export was initiated for that object; subsequent changes will not be included.
  • It is possible to import the same package multiple times.
  • It is not possible to undo changes from an import.
  • Objects can be exported from and imported onto the same server for backup and restoration.

Updates

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.

Issues During Export or Import

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.

  • In each case an error occurs, Appian gathers information on any problems and displays it to you as a list after all objects in the package have been processed.
  • The export and import processes do not stop when errors are encountered on specific objects.

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:

  1. Resolve the cause of the problem and export or import the package again.
  2. Export or import only those objects that failed due to the issue identified. You might prefer this option when the export/import package is especially large, such that exporting or importing a subset of objects is much faster.
  3. (Import only) Manually create or update the objects that could not be imported in the new environment.

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

Reading the Import Log

Objects with import issues are placed in one of two sections at the top of the import log:

  • Problems: The most important section to review as it lists the items that could not be imported and the reason why. Make sure to address the cause of the problem and attempt 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 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:

  • Success: Lists the items what were successfully created or updated by import.
  • Not Changed: Lists the items that were skipped by import because they contained no updates. See Inspect Package for more information.

Object Creator and Creation/Last Modified Timestamp

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

References to Users

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.

System Configurations

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

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.

Branding

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.

Data Retention

The Allow News Entry Deletion setting shown on the Data Retention page in the admin console can be exported as one item.

Deployment

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.

File Upload

The Blocked File Extensions and Virus Scanning settings shown on the File Upload page in the admin console can be exported individually.

Internationalization

The Language and Date and Time settings shown on the Internationalization page in the admin console can be exported as one item.

Mobile

The mobile device settings shown on the Mobile page in the admin console can be exported as one item.

Permissions

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

Plug-ins

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.

User Start Pages

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.

Appian Authentication

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

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.

Email

The Allow Appian to Send Email setting shown on the Email page in the admin console can be exported as one item.

Embedded Interfaces

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.

HTTP Proxy

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.

Microsoft Office

All of the settings shown on the Microsoft Office page in the admin console can be exported as one item.

Third-Party Credentials

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.

Sensitive Values

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:

  • Set the values in the import customization file
  • Manually set the values after import

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.

Third Party Plug-ins

Configurations Without Deployment Support

The following admin console settings cannot be exported and imported:

  • Client Certificates
  • Trusted Server Certificates
  • Legacy Web Services

In addition, the Process Calendar found in the Appian Designer Objects view cannot be exported or imported.

Importing Applications and Admin Console Settings Together

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:

  • Data stores pointing to a data source by its JDNI name
  • Third-party credentials referencing design objects in the Test Connection field
  • Custom start pages secured to groups

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.

Import Customization

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:

  • Lines with a # are ignored.
  • Lines that reference a setting or object that cannot use import customization or is not in the import package will be ignored.
  • The value will be set to whatever is specified between the = character and the next line break, including any whitespace.
  • If you uncomment a line in the import customization file for a valid property but do not put anything on that line, the value will be set to null.

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.

Object-Specific Rules

Appian supports export/import for the following objects.

For the images displayed in the subsections below, the following key applies:

Applications

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.

Documents

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.

Groups

Group application objects can be exported then imported into another environment.

Notes on Exporting

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.

Notes on Importing

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.

Notes on Overwriting Existing Objects

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.

Common Reasons a Group Will Fail to Import

A group object may fail to import when:

  • It has the same name as an existing group, but a different UUID (only true when Appian is configured to enforce unique group names. See Configuring User Management Default Settings
  • The user lacks sufficient privileges to modify the object in the destination environment.
  • The user lacks sufficient privileges to create the object security type.
  • It references a parent that violates the parent/child relationship in the destination environment.
  • It references a group homepage that does not exist in the destination environment or in the import package.
  • It references a group type that does not exist in the destination environment or in the import package.
  • It references a parent group that does not exist in the destination environment or the import package.

Group Types

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.

Processes

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

  • If no published version exists, the draft version is exported.
  • References to other objects are determined based on the version of the process model that is exported.
  • Process models exported from the Process Modeler (using an earlier version of Appian) cannot be imported as an application.

On import, process models are published as a new version.

  • If you are reimporting an existing process model, draft versions you may be working on are overwritten when the imported process model is published.
  • When importing process models (for the first time) that are linked recursively, the process models are published twice - resulting in two new versions.
  • Subsequent imports (updates) publish the recursively linked process models one time per import, creating one new version.
  • The user performing an import is listed as the creator of notes and attachments associated with the process model, as well as the owner of the process model.
  • On import, if the process model references smart services that do not exist in the destination environment, the import of the process model fails.
    • The import behaves in the same way for missing referenced objects, such as a missing data type.
  • The Process Modeler cannot import process models from application packages.
  • Process models that are exposed as a web service must be re-exposed after import in the destination environment (if the process model is expected to be hosted in the destination environment).

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.

  • In such cases, you must edit the process model to specify the target of the send message event, before it can be published.
  • See also: Messaging Best Practices

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.

  • On import, the process model is created but not published.

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.

  • On import, the process model is created but may produce an error and fail to publish.
  • In such cases, you must manually add the rule and/or constant, before the process model can be published. Make sure to the name of the rule/constant is the same as what the expression references.

Custom Data Types

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.
  • The user who imports the application is listed as its Creator.
  • The date the application is imported is listed as its Date Created.
  • The visibility of a data type remains the same as on the source environment.

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:

  • Appian looks for the existence of the data type in the destination environment.
  • When the data type doesn't already exist, Appian calls out to the WSDL to retrieve the data type definitions.
  • Appian looks at the data type definitions in the import package.
  • If the WSDL is available and the data type structure does not match what's included in the import package, a data type definition warning appears in the import log.
    • Inspect the existing data type definition whenever a structural data type definition warning appears in the import log. It is important to determine whether the existing definition may or may not be compatible. If an incompatibility is found, the imported application should not be used until the process is updated to match the current WSDL.

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

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.

  • A data source with an identical JNDI name must exist in the destination environment, for successful import.
    • If Data Stores use a different JNDI name in the destination environment, the imported data store must be edited to update the data source used.
  • The latest version of a data store (at the time the application package is created) is the one that is included.
    • Draft (unpublished) data stores can be exported, if they are not yet published.
    • Once published, only the latest published version can be exported.
  • While a data store's automatic-schema-updates property is exported with the object, it will have no effect in environments where automatic update have been globally disabled.

Importing Data Stores

  • Custom data types (data types) used by data store entities must be included in your application package or must already exist in the destination environment for the import to be successful.
  • Ensure that automatic schema updates are configured correctly in the destination environment before import. Updates will only occur if automatic updates are enabled both in the Administration Console and on the imported data store.
  • If automatic schema updates are enabled both globally in the Administration Console and locally on the data store, Appian attempts to fix any discrepancies between your database schema and data store definition by adding tables or columns to the database to match entity definitions. At the same time, Appian never removes unused tables or columns from the database or alters existing columns. This means:
    • Columns and tables missing from the database, but present in the data type, are created.
    • Columns and tables missing from the data type, but present in the database, remain untouched.
    • Columns that are incorrectly configured to map to a data type field are not altered, so verification of the data store requires manual changes to the database. An example that requires manual changes is altering a database column of type text so that it maps to a data type field of type integer.
  • If automatic schema updates are disabled, Appian does not address any discrepancies between your database schema and data store definition. This means:
    • Tables missing from the database are not automatically created.
    • Columns missing from tables are not added.
  • If the data source or entity mappings aren't valid, the data store is created (or updated) as an unpublished new version or draft. This allows you to address any issues (such as updating the datasource) while retaining any references to other application components.
  • Any validation errors are listed in the import log. The cause of the error is also listed.

Expected Results when Importing Published Data Stores:

The following results occur when importing an application package that contains a published data store.

  • The import process attempts to publish a new version of the data store, when the package contains a published data store.
  • If auto-update is enabled, Appian will attempt to update the database to match the data store before attempting to publish the data store.
Data Store Version on Destination System Result when Publishing Succeeds Result if Publishing Fails
None A new published version is created.
  • A new draft version is created.
  • Imported objects that reference the data store retain their references.
  • Draft A new published version is created. The draft version is discarded.
  • The draft version in the destination environment is updated with the draft version in the application package.
  • Imported objects that reference the data store retain their references.
  • Published, without a subsequent draft version. A new published version is created.
  • A new draft version is created.
  • The published version is not affected.
  • Imported objects that reference the data store retain their references.
  • Published, with a new draft version. A new published version is created. The destination environment draft is discarded.
  • The draft in the destination environment is updated with the draft in package.
  • Imported objects that reference the data store retain their references.
  • 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

    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.

    • Report contexts that reference process models, groups, or users
    • Rules and constants in column definitions and drilldown paths
    • Drilldown paths to Appian objects such as another report or dashboard
    • Filters
    • Custom indicator icons
    • Custom chart properties

    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.

    Process Instance Context

    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

    Rules folders, rules, and constants can be exported and imported onto another server.

    Rules Folders

    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.

    Rules and Constants

    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.

    Environment Specific Constants

    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:

    • When importing an environment specific constant onto an environment where it does not exist, an import customization file is required for it to be imported successfully
    • When importing the environment specific constant onto a target environment where the constant already exists, if an import customization file is not provided then the constant will still import successfully but the current value will not be overwritten. All attributes besides its type and value (including whether or not it is environment specific) will be updated.
    • When importing the environment specific constant onto a target environment where the constant already exists and an import customization file is included, then the constant's value will be updated to what is specified in the import customization file.
    • Whether a constant should be treated as environment specific during import is based on the configuration of the constant in the import package, not on the target environment

    For general guidance and best practices for creating, managing, and maintaining import customization files, see Managing Import Customization Files.

    Connected Systems

    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.

    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.

    Environment Specific Integration Fields

    The following integration fields automatically support environment specific values:

    • Username
    • Password

    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:

    • Environment specific behavior applies only to literal values, not those defined using expressions.
    • Integration fields with encrypted values will not have an initial value in the import customization file. The values must be added manually.
    • When importing an environment specific field onto an environment where it does not exist, an import customization file is required for it to be imported successfully.
    • When importing the environment specific field onto a target environment where the field already exists, if an import customization file is not provided then the integration will still import successfully but the current field value will not be overwritten. All other fields will be updated.
    • When importing the environment specific field onto a target environment where the field already exists and an import customization file is included, then the field's value will be updated to what is specified in the import customization file.

    For general guidance and best practices for creating, managing, and maintaining import customization files, see Managing Import Customization Files.

    Feeds

    When exporting feeds, the feed properties and user rights are included.

    • User subscriptions to feeds are not changed if a feed is updated.
    • Individual feed postings and comments cannot be exported.
    • When a feed is updated on import, its postings and comments are not updated or changed.

    System Objects

    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.

    • Group Type Departments
    • Group Type Teams
    • Group Type Custom
    • Community Root
    • Default Community
    • System Knowledge Center
    • Email Template Folder
    • Leader Message Pictures Folder
    • Priority Icons Folder
    • System Reports Folder
    • System Reports
    • User Pictures Folder
    • Temporary Docs KC
    • Temporary Docs Folder
    • Green Report Indicator Icon
    • Red Report Indicator Icon
    • Yellow Report Indicator Icon

    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

    Notes for Application Administrators

    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.
    • Because an import is not one atomic operation, users may see some inconsistencies in their application behavior while the import is running. For example, during a lengthy import, a Constant might be updated, but the Process Model that references it has not been updated yet.
      • We recommend that production-environment application imports be performed during off-peak hours, especially when importing large applications.

    Security

    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.

    Assigning Administrator Rights to the User Who Imports an Application

    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.

    1. Create the group on the source machine, and export it (in an application package) to the target machine prior to importing the main application.
    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 machine to this group before performing an import.
    4. After the import, remove users from the <Application_Name>_Administrators group, as needed.

    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.

    Deploying Security Rolemaps with Exported Objects

    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:

    • 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 user rights from their parent. This configuration is preserved when the object is exported and imported. If the configuration of the object differs in the import package from the target server, the setting in the import package is used.

    Security Rolemaps Deployment Example

    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.

    • user1: Does not exist in the resulting rolemap because they do not exist on the target server.
    • group2: Changes to a Reader from an Author because that is the access level defined in the import package.
    • group1: Exists in the rolemap because it was in the import package.
    • group3 and group4: No longer appear in the rolemap because they were not in the rolemap of the Knowledge Center in the import package.
    FEEDBACK