ServiceNow Instance Migration - Migrating Attachments directly from Table Data

The recommended method of migrating ServiceNow attachments between instances is the Server-Server method, as defined in the execution settings. This is usually quick and easy to configure as long as the target server has visibility of the source server.

If this method does not work, you have two alternatives:

Use the Server-Client-Sever method

This is simple to configure, but has the following disadvantages:

• It will be slower than the server-server method
• The sys_id is not retained, nor is the created by and created on information. This might be an issue if the attachment is shown in activity logs. This can be worked around by updating the attachment record with the correct created by/on date after the attachments have been migrated (most templates do this).
• The target server can reject the attachment based on its extension/file type. For small attachments (<3.5MB) this may be a silent failure. Precision Bridge will not show the error, since these attachments are actually added asynchronously using the ecc_queue. The only way to see these errors is to look in the ecc_queue records.

• Large attachments can cause timeouts.

Directly map the sys_attachment and sys_attachment_doc files.

This is also slower than the server-server method and a little harder to configure, but has the following advantages:

• The sys_id and created on/by information can be retained
• The target server will not usually reject attachments migrated in this way
• This method, if configured correctly will usually succeed when others may fail
• Larger attachments can be migrated without a timeout resulting in an error.

However this method has the following risks:

• Attachments are not created as a single 'unit'. So if the migration fails midway, some attachments can be left only partly completed. This can be corrected by re-running the migration, ensuring existing attachments are updated.
• Care needs to be taken to avoid potential timeouts if the batch of records being retrieved/submitted is too large.
• PB will often need additional memory using this method, particularly for very large attachments. See here on how to configure available memory.

Configuring Attachment Migration using the Direct Table Data Method

NOTE: 

For this to work correctly, the following system property must be set: glide.soapprocessor.large_field_patch_max. This must be set to a value larger than the maximum size of the data values in sys_attachment_doc (usually around 933,000 bytes by default) The recommendation is to set the system property to a value of 1024000 to avoid the data value being migrated as an attachment to the sys_attachment_doc file.

Further instructions on configuration of this method are given below:

1. Do NOT enable attachment migration on the parent form. The parent records should be migrated first, but on the options tab for the form mapping, ensure the Attachment Migration Option is set to 'No Attachments'

2. Create a form mapping for the Attachments table (sys_attachment) and Attachment Document (sys_attachment_doc). You can use the Form Mapping Generation wizard for this. These mappings should run AFTER the parent table mapping. sys_attachment records should be migrated before sys_attachment_doc.

   

3. If your original project was a template, there may be existing mappings to update attachments (this is to set the created on/by details correctly for activity log purposes). You can remove these mappings (see above)
4. You are advised to change the identifiers of these mappings to reflect the parent (e.g. Incident Attachments & Incident Attachment Doc)

5. sys_attachment mapping: On the source filter tab, Create an inclusion filter to restrict to only migrate attachments for the migrated parents (see example below for Incident Attachments). Also add a filter to restrict attachments to those for the table.

   

6. sys_attachment mapping: On the options tab, change the Entry Exists on Target action to 'skip record' - if the project is re-run, you do not generally want to update existing attachment records, they are unlikely to have changed.

   

7. sys_attachment_doc mapping: On the source filter tab, Create an inclusion filter to restrict to only migrate  attachments for the migrated sys_attachment records (see below):

   

8. sys_attachment_doc mapping: On the options tab, go to the advanced sub-tab. Set the Migration Inclusion Chunk Size to 20, Set the Max Retrieval Size to 50 and set the Batch submit size to 10 (see below). These settings should prevent too much memory being used and should prevent timeouts - the attachment doc records can be quite large. If you do get timeouts when executing, you will need to reduce these values further.

   

9. You will need to add these 2 field mappings for every parent form mapping for which you want to migrate attachments for in your project. You can simplify this process by using the duplicate form mapping option (to make copies of the existing ones in the same project or import the form mappings if they are in another project. Remember to update the filtering on the sys_attachment mapping to get attachments for the correct parent.