Overview

This page provides general guidance and best practices for creating, managing, and maintaining the import customization files that your applications use. The guidance here is directed towards users who fill the role of deployment manager for their organization. This role requires:

• Access to the Appian Administration Console in all environments
• Knowledge of and access to applicable sensitive data such as data source passwords or third-party credential values
• Permission to manage the import customization files and their values in the organization's version control system

Import Customization

Values of certain objects can be changed during deployment 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 customized, 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: MySQL, MariaDB, Oracle, SQL Server, PostgreSQL, DB2
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.

See the next section on Managing Multiple Files to learn more about how to maintain these files for your deployment processes.

Managing Multiple Files

Since administration console settings and application objects (like environment specific constants, integrations, and connected systems) are exported separately, they will generate separate import customization files. Appian recommends that you have a single import customization file for each environment in your deployment pipeline. This way all the environment specific values for administration console settings and design objects for a single environment can be managed in one place. These master files should be named according to the environment they are intended for and should be version controlled in your version control system. The deployment manager will need to keep the values and files in sync when values are changed or new environment specific values are introduced.

Importing Values for the First Time

As mentioned above, all environment specific values for a single environment should be stored in their own master import customization file for that particular environment. Whenever introducing new values that will require import customization, you should add the generated lines for these into the single master file for each environment with the applicable values.

During import, only the values that reference a setting or environment specific design object field that are in the current import package will be used. This allows you to continue to use the same master import customization file for every import (admin console settings, application, or package) on that environment since the non-applicable values will be ignored.

The basic steps for importing values set by import customization are:

1. Export your relevant administration console settings from the Administration Console. Download the generated import customization file from the Export confirmation dialog.
2. Uncomment the lines in the file and fill out the values for the current environment.
3. Export your application from Appian Designer and download the generated import customization file for any environment specific objects in your application.
4. Uncomment the lines in the file and copy them over to the other import customization file that was generated during export of the admin console settings.
   • For constants the current values are already included in the file.
   • For integrations and connected systems the value of sensitive fields will need to be added to the file manually.
   • If you already have a master import customization file for each environment then you only need to add the new lines and values to the existing files.
5. Save this file and store it as the master import customization file for your current environment.
6. Make a copy of this file for every environment in your deployment pipeline and update each of those files to have the corresponding values for that environment. It's likely that some of these values will need to be provided to you by the application designers themselves.
7. Import your application and administration console settings packages and the environment's import customization file together from the Import Settings dialog in the Appian Administration Console

Dealing With Dynamic Values

Some constants today are used to hold values that are unique to each environment but are not static, these include:

• Constants whose values are updated using the Update Constant smart service
• Constants that are used as global counters whose values are used and then incremented to the next value using the Increment Constant smart service
• Constants that are used as feature toggles in an application's logic that may change over time

It makes sense for these constants to be environment specific constants because environment specific constants that are imported without a value provided in an import customization file will not override the constant's current value on the target system. However, for these constants, you will need to actively manage that you are not providing a value in the import customization file for them when they are in your import package but not intending to overwrite their values.

It is recommended that once imported onto an environment for the first time, the lines in your import customization file that correspond to these types of constants should be commented out and grouped together in their own section so they are easily discoverable. This way, subsequent imports with the environment's import customization file that include these constants will not override their values that may have changed on the system over time.

Learn more about about the import behavior of environment specific constants on the Application Deployment Guidelines page.

Importing Unchanged Objects

It is a best practice to import applications using a System Administrator service account, so process models that are configured to run as their designer will have the proper permissions and not be at risk of the designer user becoming deactivated. If you accidentally import an application with a personal account, you can add an import-specific setting to the import customization file to force an import of unchanged objects.

To re-import the exact same application using a different user account, add the following lines to your import customization file and include it with your application deployment:

1
2
3
## Import Setting: Force Update
## Forces the import of objects that were detected to be Not Changed on inspect/import
importSetting.FORCE_UPDATE=true

For more information about the Not Changed status, see Inspect Package and Application Deployment Guidelines