User Tools

Site Tools


common_attachment_format

Common Attachments

Dubnium

Prerequisite(s): The functionality on this page applies to the Argon release or newer of the Perspectium for ServiceNow Update Set.

The following is the default implementation of the common attachment format. Since the approach of using embedded attachments in common documents limits us to 7MB per message (because of ServiceNow platform limitations with how big objects can be created programmatically), this format allows you to support sending large attachments when e-bonding ServiceNow instances for supported integrations such as Incident, Change, Problem and Request.

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 the table record the attachment is attached to. 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.

The Common Attachment update set will include script actions to run when attachments are added, a Table Map that generates the below XML payload when specified in a Dynamic Share, and an Import Set Table and Transform Maps to ingest this format.

Implementation


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

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 and 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.

NOTE: Common attachment deletes are not supported.

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.

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 is adding an attachment as he/she creates an incident), add the following script to the After 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
// 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).

We do need the above code to handle the case where the 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.

Note the “msp_incident_sent” tag listed above as this will be the same tag as created when installing a common document format.

Previously Uploaded Attachments

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

  1. Navigate to Perspectium > Replicator > Dynamic Share in your ServiceNow instance.
  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.

Outbound Table Maps


The following table map construct 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.

Name Type Source table Description
Attachment Doc to Common Attachment common_attachment Attachment Document [sys_attachment_doc] Main body of the common_attachment format

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):

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 goes along with our 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 our query for a record is searching for both of these values to see if we can 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.

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.

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.

Sample Output


<?xml version="1.0" encoding="UTF-8"?>
<common_attachment>
    <compressed>true</compressed>
    <content_type>image/png</content_type>
    <data>AQcD+PyJUE5HDQoaCgAAAA1JSERSAAAAIAAAACAIBgAAAHN6evQAAALOSURBVFiF7ZUxTxRBFMd/M3uc3OHBBY9wJhagH0BJTCR0FjTGmsrQ0GjCB+BLkFiYUNhYkNAQsaGxILExgRhro8VhQwKnwHHKHrsz8yyO1XUPuL07Ovgnl8vO7Mz7vf+bfQPXutZVl0oOTE5OqmKxmB0aGio451rmO5Xnefi+X6/X6ycbGxuSnM/EH0ZHR71yufx0cXHxdaFQGOk1eKTj4+P9hYWFF+Pj428rlYqJz/2Xodb61tbW1qdSqTR2WcEj7e7ufp+amnporf0RH487oJxzpYGBgRFrLQATExMvj46OqkCLdSmkSqXS7c3NzXmATCZTsNYOAz/j+/0HAGTDMERrjVIKrfVH4DNguwDIaK0fWWvnRQRjjErEawEAUNZarLUopVBKVYHvgEkuTKE+4J61FhHh1NWWQ91CZIzB8zyUUtC0qhv7o7UYY+IALWoBsNZijIkAetKp9X//UwFEwbXWiHSb/D+FYdgZQBAEiAha656DRwDOOcIwTAcQEXue13NwESEIgs4AIqucc5dSAmMMzrn0JYgcuIwSiMjfEnR0CC+rBEDnAFHjOP1ly+VybmxszHQCJCJUKpVMEAR9nZbAHR4eNgYHBwecc6ytrb3PZFoYU8sYQ7VaRUTY29urcUZLj+8uwO/l5eV3s7Ozz/r7+2/s7Ox0HTyu/f392tLS0hugTqKzJtvdTeABcB8oJOY14J2xJpLQzNAlxh3NG/AT8AVoXASggBwwBGRPn3WxWCzPzMw8n56efqKUOu/zkPX19bWVlZVXjUajFstUAB+oASfJRe0avlJKDa+urn71fX/Y9/1ze4NSinw+jzHm69zc3CNjTBziXLU7YUpERra3t8nlcu32olarcXBwkDfGlGhm3FZtHQDueJ73OJvN3qV5Di6SbTQa30TkA7BDCgfS3LlZYBjIp3hfgF/AAXB28+8CoJP3e788rpz+AKPReIgejN6uAAAAAElFTkSuQmCCvAMsEgcDAAA=</data>
    <file_name>television_alt.png</file_name>
    <length>1052</length>
    <position>1</position>
    <size_bytes>775</size_bytes>
    <size_compressed>798</size_compressed>
    <table_correlation_display/>
    <table_correlation_id/>
    <table_name>incident</table_name>
    <table_number>INC0075037</table_number>
    <table_sys_id>222e6c044f010300b6a444b18110c726</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

common_attachment_format.txt · Last modified: 2019/06/07 11:24 by timothy.pike