Manage Import Customization Files for Deployment

This page provides general guidance and best practices for creating, managing, and maintaining import customization files.

What is an import customization file?

An import customization file allows you to change or configure the values of certain objects or settings during manual import, direct deployment, or external deployment.

This file lets you set values that vary between environments or that are not exported for security reasons, such as passwords. You can customize the import of the following:

• Admin Console settings
• Environment-specific constants
• Integrations
• Connected systems
• AWS model provider credentials

You can also use the import customization file to:

• Import unchanged objects in a target environment.
• Override object protection in a target environment.
• Start a full sync on a record type in a target environment.
• Complete a deployment without waiting for specific record types to sync.
• Resolve SQL reference name conflicts automatically during import.

Import customization file security

When configuring properties in an import customization file, you'll need knowledge of and access to applicable sensitive data such as data source passwords or third-party credential values.

To manage import customization files for Admin Console settings, you'll need a System Administrator account in all environments.

To manage import customization files for design objects, you'll need a basic user assigned the Designer user role and the appropriate permissions for the application:

• With Viewer permissions for the application, you can add an import customization file to a manual import, a package that you've created, or a deployment that you're initiating.
• With Administrator permissions for the application, you can add an import customization file to any package associated with the application or during any direct deployment.

Configure the import customization file

To configure an import customization file:

1. Download the template file from Appian.
2. Gather the values you'll need to configure the file.
3. Edit the file locally.
4. Upload the file to Appian.

Download a template file

Appian generates a template import customization file with the extension .properties. The template file contains both the properties you can configure and instructions for configuring those properties.

You can download a template file when you:

• Export Admin Console settings.
• Export an application or package. This download is only possible if the application or package contains objects for which you can customize import, or if the prepared package contains an import customization file.
• Prepare a package for deployment.
• Deploy an application or package using direct deployment.

Template file contents

The template file contains properties appropriate to the settings or object in the related application or packages:

• For Admin Console settings, the properties correspond to the settings you chose during export.
• For an application or prepared packages, the properties correspond to any objects in the application or packages that require customization.
• For deployments containing multiple packages, the template contains configurations for all objects included in the deployment.

For constants and non-sensitive Admin Console settings, the template file includes the current environment's values for the corresponding properties. For all other objects or settings, the property in the template is blank. You'll need to add sensitive and environment-specific data manually.

Some import customization properties require the universally unique identifier (UUID) of the object you want to customize. After you configure a constant, integration, or connected system in an application, the template customization file you download includes the UUID for that object in the appropriate properties.

Gather the values you'll need

• Gather the sensitive data you'll need for the target environment, such as data source passwords or third-party credential values.
• Some customizations require the UUID of the object you want to customize, but the UUID is not included in the template import customization file. For these customizations, look up the object UUID in the Properties for the object.
• When deploying multiple packages simultaneously, you must combine the necessary customization content for all relevant objects into a single consolidated file.

Edit the file locally

When editing, keep the following in mind:

• The system ignores commented-out lines, which start with a #. By default, all properties in a template file are commented out.
• The system ignores lines that reference a setting or object that cannot be customized or is not in the import package.
• 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.
• The system will set the value to whatever is specified between the = character and the next line break, including any whitespace.

To edit an import customization file:

1. Open the file in a text editor.
2. For each property you want to customize:
   • Remove the # from the beginning of the line.
   • Edit or add a value after the = character.
   • Add lines to consolidate multiple import customization files.
3. Save your changes.

Upload the file

You can upload an import customization file when you:

• Prepare a package or perform a direct deployment in Appian Designer.
• Perform an import in either the Admin Console or Appian Designer.
• Perform an import using ImportExportService. For more information, see the Appian Public API.

Update an import customization file

As you build and enhance your application, you're likely to add, update, or remove objects that impact the import customization file.

If you've added the import customization file to a package, you can make those updates in the package, as follows:

1. Download the current file from the package.
2. Make the updates locally.
3. Remove the current file from the package.
4. Upload the updated file to the package.

Learn more about taking these actions on import customization files in packages.

If you're storing the import customization file locally, rather than in a package, you'll need to make the updates in your local copy, then upload the updated file during development or during deployment.

Reuse an import customization file

The first time you deploy to a target environment, your import customization file should contain properties for relevant Admin Console settings and design objects.

For subsequent deployments, you can take either of the following approaches:

• Leave the properties from the first deployment in the file, but exclude related settings or objects from the next import or deployment. Appian only applies properties in an import customization file to the target environment if the imported or deployed package contains the related setting or object.
• Comment out the lines in the file, so you can guarantee that the values will not be overwritten if the related settings or objects are included in the import or deployment.

For example, you can use constants to hold values that are unique to each environment but are not static. These environment-specific constants include:

• Constants containing values 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.

For these constants, we recommend commenting out the lines in the import customization file to prevent overwriting the value in the target environment.

Manage multiple template files

As you prepare your application for deployment, you may need to download multiple import customization files to obtain setting-specific or object-specific properties. For example, the first time you deploy to a new environment, you might need to deploy relevant Admin Console settings and design objects that need customization. In this case, you'd have to download two template files: one in the Admin Console and one in the package view.

You can only use a single import customization file per interaction with the target environment—one file per deployment or import. As a result, you must consolidate customizations from separate template files into a single file for deployment or import. See the consolidated file example.

Similarly, when deploying multiple packages from a single application, each package may have its own import customization file with package-specific properties. You should consolidate these into a single file to ensure consistent configuration across the merged deployment.

When creating a consolidated file, we recommend grouping similar lines together, so they are easily discoverable. For example, keep all constants in their own section.

Manage import customization files across multiple environments

We recommend that you maintain a single import customization file for each environment in your deployment pipeline. This way, you can manage all the environment-specific values for Admin Console settings and design objects for a single environment in one place.

You can continue to use the same environment-specific file for every import on that environment, since non-applicable properties will be ignored.

Whenever development introduces new values that will require customization, you should add the appropriate properties with applicable values to each environment-specific file.

Import unchanged objects

Deploying applications using a System Administrator service account is a best practice, 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 deploy an application with a personal account, you can add a setting to the import customization file to force the re-deployment of the unchanged objects.

To re-deploy the exact same application using a different user account, add the following lines to your import customization file and include it with your 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 Compare Deployment Packages and Resolve Deployment Issues.

Override object protection

Applications can incorporate capabilities that let business users create and edit certain objects in a target environment; for example, reports and dashboards in Process HQ. When importing or deploying objects of this type, Appian checks if the object has been edited in the target environment:

• Edited: Assigns the object a Protected status and keeps the target environment version of the object, instead of the source environment version.
• Not edited: Assigns the object a Changed status and overwrites the object with the version from the source environment.

This default behavior may not align with how your organization must handle the deployment of reports and dashboards. For example, industry regulations may require the tracking of object creation and modification, and documenting and auditing multiple environments could be prohibitive. As necessary, you can override the object protection, so that the object from the source environment overwrites the object in the target environment.

To override the default behavior for individual reports and dashboards, add the following lines to your import customization file and include it with your deployment:

1
2
report.<UUID>.forceOverrideProtection=true
dashboard.<UUID>.forceOverrideProtection=true

For more information about the Protected status, see Compare Deployment Packages and Resolve Deployment Issues.

Start a full sync

The forceSync property triggers a full sync on a synced record type during deployment. A synced record type syncs automatically when you deploy the record type itself, but not when you deploy a package that affects its data without including the record type. For example, a package might include database scripts that change the record type's data source, which requires a forced sync.

Add the following property for each record type you want to sync:

recordType.<UUID of a Record Type>.forceSync=true

For example:

1
2
recordType.63e19e09-eb15-43e3-9864-a1ca4d9ece06.forceSync=true
recordType.548ac877-5baf-4677-b180-500c9ec96f38.forceSync=true

Complete a deployment without waiting for record type syncs

A deployment that includes a synced record type normally waits for the full sync to finish before it completes. If the record type has an extra large data source, waiting for the sync can cause the deployment to time out and fail.

The postDeploymentSync property lets the deployment complete while a record type sync is still running. Appian still starts the sync during the deployment, but does not wait for it to finish.

Add the following property for each record type that should sync independently from the deployment:

recordType.<UUID of a Record Type>.postDeploymentSync=true

For example:

1
2
recordType.63e19e09-eb15-43e3-9864-a1ca4d9ece06.postDeploymentSync=true
recordType.548ac877-5baf-4677-b180-500c9ec96f38.postDeploymentSync=true

Deployment and sync status

When you use the postDeploymentSync property, the deployment status changes as the sync progresses:

A deployment status of Completed does not confirm that data synced successfully. To check the sync results, go to the Record Sync Status tab of the Monitor view.

Resolve SQL reference name conflicts automatically

A synced record type's SQL reference name is included in its deployment package. If that SQL reference name already belongs to a different record type in the target environment, the deployment has a status of Completed with Errors and the record type is not imported.

The importSetting.updateSqlReferenceNames property lets Appian automatically rename conflicting SQL reference names during import by appending a number to make them unique. This renaming allows the record type to import successfully.

The importSetting.updateSqlReferenceNames property applies to all record types during deployment and is useful when:

• Source environment constraints: You cannot change the SQL reference name in the source environment.
• Large deployments: The package contains many record types with conflicting SQL reference names across environments.

Add the following to your import customization file:

1
2
## Import Setting: Update SQL Reference Names
importSetting.updateSqlReferenceNames=true

Event consumers

When deploying event consumers across environments, you can customize environment-specific settings using an import customization file.

Event consumer properties

The following properties can be configured in the import customization file:

Auto-activation on deployment

Event consumers automatically activate after deployment based on their state when added to the package:

• Automatic activation: The consumer activates automatically if its state was Active or Activation in progress when added to the package.
• Manual activation required: The consumer remains inactive if its state was Inactive, Error, or Deactivation in progress when added to the package. You must manually activate it in the target environment.

Import customization file examples

We've included a few examples of import customization properties here for your reference.

General instructions

The top portion of each template file consists of general instructions.

## ----------------------------------------------------------------------
## Instructions
##
## All of the properties in this file are commented out; they have a pound
## symbol at the start of each line that renders them inert.
##
## Instructions and headings are marked with two preceding pound
## symbols (##).
##
## On import, all commented-out properties are ignored, and the
## corresponding values in the destination environment remain
## unchanged.
##
## To set or change a property on import using this file,
## uncomment the property by removing the pound symbol from the start
## of its line. Then enter a value for the property after the equals
## sign (=) at the end of that import customization file.
##
## If you uncomment a property, but provide no value, the value of
## that property will be set to null in the destination environment.
## Properties that correspond to Admin Console settings and require a value
## will be set to their default value instead of being set to null. Default
## values of settings may be different between versions of Appian.
##
## To force sync of a record type please add an entry to the file in the following format
## recordType.\<UUID\>.forceSync=true
##
## To sync a record type asynchronously after deployment,
## add this property:
## recordType.\<UUID\>.postDeploymentSync=true
##
## To force import unchanged objects add the following line in the file
## importSetting.FORCE_UPDATE=true
##
## To automatically rename conflicting SQL reference names on import
## importSetting.updateSqlReferenceNames=true
##
## Note: Never remove the double pound symbols (##) in front of instructions
## and headings.
## ----------------------------------------------------------------------

Admin Console settings

The following example shows properties corresponding to a small set of Admin Console settings.

## 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=

Environment-specific constant

The following example shows a property that corresponds to an environment-specific constant.

In this example, the line representing the constant has been uncommented and configured.

## 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

Integration

The following example shows properties related to an integration.

## Integration: HRO_getCaseInfo
#content.ad5ce05d-a7d6-482e-842e-54bcfd5126f8.username=
#content.ad5ce05d-a7d6-482e-842e-54bcfd5126f8.password=

Connected system

The following example shows properties related to a connected system.

## Connected System: HR0 Google Drive
#connectedSystem._a-0000e7b6-ab5d-8000-9e38-011c48011c48_32396740.baseUrl=https://www.google.com
#connectedSystem._a-0000e7b6-ab5d-8000-9e38-011c48011c48_32396740.username=
#connectedSystem._a-0000e7b6-ab5d-8000-9e38-011c48011c48_32396740.password=

Consolidated file

This example contains properties for Admin App settings and a constant.

## 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

Credentials in a robotic task

This example shows how to deploy credentials referenced by a robotic task.

## Robotic Task Section bf43689c-f890-4545-bf20-b50d8ebb7b98 (AB_LoginOutlook)
## Credential Application: Outlook
##
## 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.
#roboticTaskDesignObject.bf43689c-f890-4545-bf20-b50d8ebb7b98.credential.649d869889afc1250bf30406.username=outlook.user1
#roboticTaskDesignObject.bf43689c-f890-4545-bf20-b50d8ebb7b98.credential.649d869889afc1250bf30406.password=

AWS model provider credentials

This example shows how to deploy AWS credentials when using a custom AWS account as the AI model provider.

When you configure your own AWS account to power Appian's generative AI features, the credentials are not exported for security reasons. You must provide these credentials in the import customization file when deploying to the target environment.

## Administration Console Setting: AWS Model Provider
## AWS Access Key ID
aiModelProvider.AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
## AWS Secret Access Key
aiModelProvider.AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
## AWS Region
aiModelProvider.AWS_REGION=us-east-1

See AI Services for more information about deploying AI model provider configurations.

Post-deployment sync

This example shows how to configure a record type so the deployment completes without waiting for its sync to finish.

## To complete a deployment without waiting for a sync,
## add this property:
recordType.63e19e09-eb15-43e3-9864-a1ca4d9ece06.postDeploymentSync=true

Feedback