Defining Attachment Options

When migrating records including attachments, you have the following options for managing those attachments:

Maximum Attachment Size (MB)

This option only applies to projects where attachment migration is supported

Users can define a limit to the size of attachments to migrate (default is 32MB). If this limit is too high, there is a risk of timeouts in the server calls to perform the migration. This limit does not apply to all target server types.

Service Now Instance Migration Options

This option only applies to Service Now -> Service Now migrations

Use Server->Server Attachment Migration Method. This gives the user the option of using the generally faster scripted method of migrating attachments between ServiceNow servers. If unchecked then the slower Server->Client->Server method is used. Usually, the slower method would only be used if there was an issue in connectivity between the source and target servers preventing the script from working or the user did not want to create the attachment migration web service on the target server.

To support this faster attachment migration method, a scripted web service called <app name>_migrate_attachments_<version no.> is created on the target instance, where <name> is the name of the Import Set Application above and version no. is the version of the script.

Note that this option can only be applied when the attachment target is the Target Server (see next section).

Define Attachment Target

This option only applies to Database target and ServiceNow target migrations

The Define Attachment Target tab provides additional options specific to the final storage location of attachments when migrating them.

Write To:

The following options are available to specify where Precision Bridge should migrate attachments to when archiving:

Target Server	For ServiceNow targets, the attachment is added as an attachment on the target record For database targets, the data for the file attachment is stored in base64 encoding within the sn_sys_attachment table on the target database.
File	The file attachments will be saved in a subfolder within the folder specified in the Path to Attachment Files Root Directory field. The subfolder will be automatically created if it does not already exist with the name of the migrated form from which the attached files were extracted. For database targets, an entry will still be created in the sn_sys_attachment table on the database, but without the data stored in the base64_data column. Instead, the path to the attachment file will be stored within the attachment_file_path column.  For ServiceNow targets, a record containing the path to the file is stored in the Linked Files table.
AWS S3	The file attachments will be saved into the selected Bucket on your AWS S3 account in a folder automatically created if it does not already exist with the name of the migrated form from which the attached files were extracted. For database targets, an entry will still be created in the sn_sys_attachment table on the database, but without the data stored in the base64_data column. Instead, the S3 URL of the attachment will be stored within the attachment_file_path column.  For ServiceNow targets, a record containing the S3 download URL is stored in the Linked Files table.

Storing attachments within Amazon Web Services S3

Before you can use Precision Bridge with AWS S3, you must setup your environment for connection to your S3 account by configuring the following environment variables on the machine running the Precision Bridge client software:

AWS_ACCESS_KEY_ID

AWS_SECRET_ACCESS_KEY

AWS_REGION

For example:

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-west-2

In some cases, you might also need to configure the AWS_DEFAULT_REGION variable as well:

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-west-2
AWS_DEFAULT_REGION=us-west-2

It is recommended that these variables are set as permanent system variables:

For Windows, set these via the Control Panel within the System Variables section.

URL Authentication (Basic)

This option applies to CSV or Database source migrations, where the csv file / attachment table contains the URL from which the attachment can be downloaded and the attachment options for one or more form mappings indicate that basic authentication is needed for this download operation.

If the download requires an authenticated connection, the username/password to be used to authenticate must be specified here. Note that OAUTH2 authentication is not currently supported.

URL Authentication (Token)

This option applies to CSV or Database source migrations, where the csv file / attachment table contains the URL from which the attachment can be downloaded and the attachment options for one or more form mappings indicate that token based authentication is needed for this download operation.

If the download requires a token authenticated connection, the token to be used to authenticate must be specified here. Optionally, you can also specify the name of the header to use for authentication in the API call. By default, the Authorization header will be used and the authentication string will be 'Bearer <token>', which is consistent with most APIs that support the use of tokens to authenticate.

URL Authentication (ManageEngine)

This option only applies to CSV Source Only migrations, where the source was an export from ManageEngine and Manage Engine Authentication is required for one or more Form Mappings.

This option allows the user to define authentication details that will be used to download attachments from ManageEngine via a URL.

See the article Manage Engine Authentication for Attachment Migration for more information.

Footprints Authentication

This option only applies to Database migrations (from a footprints database source).

There are 2 options, BMC Footprints, which should be used where the source is the database for BMC Footprints v12+ or BMC Footprints 11, which should be used where the source is the database for BMC Footprints v11. This authentication will not apply for any other use case.

The base URL should be the initial part of the login URL for BMC footprints.

For version 12+, this will be prefixed with /footprints/servicedesk/login.html to give the login page, e.g. http://sql2019:8080/footprints/servicedesk/login.html

For version 11, this will be prefixed with MRcgi/mrlogin.pl to give the login page  e.g. http://sql2019:8080/MRcgi/mrlogin.pl

You must also enter valid login credentials for a Footprints user that has a minimum of read access to all tickets for which attachments are to be migrated.

Attachment Filtering Options

This option currently only applies to Service Now -> Database migrations

Attachment Filtering gives you the option to specify certain properties that attachments must have in order to be migrated. There are 3 basic options:

1. No Filter. This is the default. All attachments will be included in migration unless they exceed the attachment migration size.

2. Inclusive Filter. Attachments will be migrated if they meet ALL of the filtering criteria defined.

3. Exclusive Filter. Attachments will be migrated if they meet NONE of the filtering criteria defined.

For inclusive and exclusive filters, you can filter on the user creating the attachment (By User ID) and the extension of the file name. For both, it is possible to define a comma delimited list of values. If you define a list, there should be no spaces before or after the separating commas. 

In the example above, an exclusive filter is defined for the user with id admin OR system and the file extension exe. This means that attachments will be migrated if:

1. They were created by a user other than the admin or system
2. They have a file extension other than exe.

The list of user ID's is not validated, so be careful to define these correctly. The filter conditions are case-sensitive.