Since the approach of using embedded attachments in common documents limits us to 7MB per message in ServiceNow, this format allows you to support sending large attachments when e-bonding ServiceNow instances for supported integrations. Common Attachment solves this by sharing out the sys_attachment_doc records in their 4k chunks, while also adding the attachment metadata such as the file name, content type, and associated table record. The common_attachment records are read into the PSP Common Attachment import set table and saved into the sys_attachment_doc table, while also creating the sys_attachment record and linking it properly to the table record.

Implementation

The implementation of any common attachment format is symmetrical, meaning that the output, when consumed, should produce the same or similar records at the target. The implementation should also exhibit idempotent behavior, meaning when a document is consumed and processed repeatedly, the same result either appears or is ignored, because the results already exist.

↑ Go to top of page

Script Actions

In order to capture the event of an attachment being added to a record, script actions are run that will share out the attachment when the event occurs. The Perspectium Common Attachment script actions come packaged as part of the Common Attachment update set. The only change needed is to update the script actions to use the same tag as created when installing a common document format.

The two script actions captured are the “attachment.uploaded” and “attachment.renamed” events.

Since common attachments are subscribed to an import set table, both events will share out attachments that can be added to a record on the subscribing side. The attachment.uploaded event will send messages as “.bulk”, while the attachment.renamed event sends messages as “.rename”, in case you want to add special processing on the subscribing instance.

↑ Go to top of page

Dynamic Share

For the correct outputs to be produced, you must create a dynamic share on the Attachment Document [sys_attachment_doc] table with the same queue as the table that is being e-bonded (i.e. incident, problem, etc.). If you have multiple integrations such as incident, change, etc. that all use the same queue, then only one dynamic share on sys_attachment_doc is needed.

The script will evaluate the conditions of the dynamic share on the table where the attachment is attached (such as incident) to determine if the attachment is shared out. To ensure the attachment is captured when a record is first created (i.e. the user adds an attachment as they create an incident), add the following script to the Before share script of the dynamic share for the table (such as incident) where the attachments are attached to:

// only do on insert as script action will run other times
if (psp_action == 'insert') {	
	// schedule a job to run in the background to share out attachments
	var pspRepl = new PerspectiumReplicator();
	
	// share record, setting tag to mark attachments
	pspRepl.shareAttachmentsDelayed(current.sys_id, dynamicshare_gr, "bulk", true, 'msp_incident_sent');
	
}

When creating a new record (such as a new incident), script actions on the attachment.uploaded event will run if a new record is submitted immediately after adding the attachment. So in that case you may have duplicate records shared out as both the above code and the script action will run sharing out the attachment (this will be properly handled on the subscribing ServiceNow instance to not cause a duplicate attachment record).

The above code is needed in the case where a record isn't submitted until later. For example, if the user adds an attachment first and then spends a few minutes filling out the incident form before creating the incident, then the above script will capture the attachment and share it out, since the script action will not run.

Previously Uploaded Attachments

To ensure attachments that you previously uploaded are Dynamic Shared out:

1. In your ServiceNow instance, navigate to Perspectium > Replicator > Dynamic Share

2. Click the record you want to Dynamic Share attachments from.

3. In the upper right-hand corner of the page, click Advanced. Scroll down on the same page to see Advanced options.

4. Click Share Pending Attachments.

↑ Go to top of page

Table Maps

The Perspectium Common Attachment Helium update set will contain the following:

Outbound Table Map

The following table map constructs the outbound messages to be queued. Specify the Attachment Doc to Common Attachment Table Map in your sys_attachment_doc dynamic share as the table map.

The table map includes field maps for useful information about the record that the attachment was added to. These fields will be mapped into fields that are prefixed “table_”. For example, the <table_number> field map that will contain the record's number in the table that this attachment is added to. By default, the <table_number> field map uses the table's number field if the number field exists and the record's sys_id if the number field does not exist.

For example, if you are adding an attaching to the incident table, this will share out the incident record's number field in the common_attachment record's <table_number> field.

Sys ID Coalescing

If you are coalescing on sys_id for your table integration (i.e. coalescing on sys_id for incidents), the table_sys_id field map is also included to share the sys_id of the record as found in the table (such as incident) that this attachment is added to. This table_sys_id field map matches the table_sys_id as found in the sys_attachment table.

Common Document Table Map

In the outbound table map where attachments are added to (for example, the Incident to Common Incident if adding attachments to the incident table), remove the ${TM field map previously created here. With sharing of attachments using common attachment, we no longer want to embed the attachments in the common document so as to avoid sending duplicates.

Inbound Table Map

In order to process messages of topic: siam and type: common_attachment, you must create an inbound table map to target the import set table as follows (this map should have been included in the update set already):

↑ Go to top of page

Import Set

The import set table is called u_psp_common_attachment and has a transform map called PSP Common Attachment to Attachment Doc.

The transform map includes an onBefore transform script to check if the table record this attachment should be added to actually exists. This script will query to find a record in the table specified in the common_attachment record's <table_name> field, searching for a record that has the correlation_id matching the value in the <table_sys_id> field or a sys_id matching the value in the <table_correlation_id> field.

This corresponds with best practices for e-bonding two instances. That is, instance A's sys_id will be the correlation_id in instance B and instance B's sys_id will be the correlation_id in instance A. So, a query for a record searches for both of these values to try and find the record that the attachment should be added to.

If no record is found, then the import set row is ignored and the record is not saved into the sys_attachment_doc table.

 NOTE: Attachment records will only be added if the record it should be attached to actually exists i.e. if you try to add an attachment to an incident record that does not exist, the attachment records going into the import set table will be ignored.

The transform map's field map that targets the sys_attachment field will also use the <table_name>, <table_correlation_id> and <table_sys_id> fields doing the same query in the specified table in order to properly find the right table to link this attachment to. If the sys_attachment record that holds the metadata for the sys_attachment_doc records does not exist, this field map will also create the sys_attachment record so as to ensure the records are linked properly by sys_id.

 NOTE: If you want to query for a table record using different fields then correlation_id and sys_id, change the fields as specified both in the onBefore transform script and the field map with the sys_attachment target field.

↑ Go to top of page

Sample Output

A sample Common Attachment looks like this:

<common_attachment>
    <compressed/>
    <content_type/>
    <data/>
    <file_name/>
    <length/>
    <position/>
    <size_bytes/>
    <size_compressed/>
    <table_correlation_display/>
    <table_correlation_id/>
    <table_name/>
    <table_number/>
    <table_sys_id/>
</common_attachment>

The following Perspectium Inbound/Outbound Message unloads can be un-gzipped and uploaded into your instance of ServiceNow to view and used for testing.

Common Attachment Sample - Inbound.xml.zip

Common Attachment Sample - Outbound.xml.zip

↑ Go to top of page