This page provides general guidance and best practices for creating, managing, and maintaining import customization files.
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:
You can also use the import customization file to:
Tip: If you're deploying robotic processes using Appian RPA, you may use a second file to manage these values. Learn more about what's included in the Appian RPA import customization file.
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:
To configure an import customization 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:
The template file contains properties appropriate to the settings or object in the related application or package:
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 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.
When editing, keep the following in mind:
#
. By default, all properties in a template file are commented out.=
character and the next line break, including any whitespace.To edit an import customization file:
#
from the beginning of the line.=
character.You can upload an import customization file when you:
ImportExportService
. For more information, see the Appian Public API.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:
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.
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:
For example, you can use constants to hold values that are unique to each environment but are not static. These environment-specific constants include:
For these constants, we recommend commenting out the lines in the import customization file to prevent overwriting the value in the target environment.
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.
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.
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.
It is a best practice to deploy 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 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 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 Compare Deployment Packages and Resolve Deployment Issues.
If data sync is enabled for a record type, a sync will automatically occur whenever that object is deployed to a new environment.
However, you'll need to trigger a sync if you deploy a package that doesn't include the record type, but impacts the synced data. For example, your deployment might include database scripts affecting the data source for the record type.
Note: If you prefer not to force a sync, you can wait for the next scheduled sync of the record type or manually trigger a sync in the record type object directly in the target environment.
To trigger a sync when you deploy a package to a target environment, add the following property to the import customization file:
recordType.<UUID of a Record Type>.forceSync=true
You can reference this property multiple times to trigger a sync on different record types.
For example:
1
2
recordType.63e19e09-eb15-43e3-9864-a1ca4d9ece06.forceSync=true
recordType.548ac877-5baf-4677-b180-500c9ec96f38.forceSync=true
We've included a few examples of import customization properties here for your reference.
Note: Don't copy and paste these examples in whole or in part when you're configuring your import customization file. Instead, download the template import customization file for the up-to-date properties and values specific to your environment.
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 force import unchanged objects add the following line in the file ## importSetting.FORCE_UPDATE=true ## ## Note: Never remove the double pound symbols (##) in front of instructions ## and headings. ## ----------------------------------------------------------------------
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=
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
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=
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=
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
Managing Import Customization Files