User Tools

Site Tools


common_change_format

Common Change Format

Version Author Comment
3.26.2 dloo initial version
3.26.3 dloo added support for embedded approvers (sysapproval_approver)

The following is the default implementation of the common change format. In a nutshell, the common change format mirrors what one would see in an ITIL view of the Change Request form in ServiceNow with related lists expressed in embedded XML form. The Common Change update set will include a Table Map that generates the below XML payload when specified in a Dynamic Share, it also includes the default Import Set Table and Transform Maps to ingest this format and produce all the artifacts that comprises of a Change Request and its related records.

Implementation

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

Dynamic Shares

For the correct outputs to be produced, you must create 2 Dynamic Shares - one to capture the comments and work_notes field values in a before context, and the other as async mode to capture the related records in a delayed step.

In the before Dynamic Share, use the following code snippet to prevent unwanted outbound messages to be queued when comments or work_notes are not updated.

if (current.comments.nil() && current.work_notes.nil()) {
	ignore = true;
}

Outbound Table Maps

The following table maps construct the outbound messages to be queued. Specify the main Change to Common Change Table Map in your Dynamic Share as the root map.

Name Type Source table Description
Change to Common Change common_change Change Request [change_request] Main body of the common_change format
psp_attachment embedded_attachment sys_attachment Map for building embedded attachments field in common_change
psp_affected_ci embedded_affected_ci CIs Affected [task_ci] Map for building embedded affected CI in common_change
psp_change_task embedded_change_task Change Task [change_task] Map for building embedded change_tasks in common_change
psp_problem embedded_problem Problem [problem] Map for building embedded problem records in common_change
psp_impacted_service embedded_impacted_service Impacted CIs [task_cmdb_ci_service] Map for building affected CI/service to common_change
psp_incident embedded_incident Incident [incident] Map for building incidents fixed and caused by embedded incidents for common_change
psp_approvers embedded_approvers Approval [sysapproval_approvers] Map for building embedded approvers

Inbound table Map

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

Import Set

The import set table is called u_psp_common_change and has a transform map called PSP Common Change to Change Request. This transform map has 7 transform scripts that are responsible for parsing the 7 embedded sections of common_change, namely

  • affected_cis
  • change_tasks
  • attachments
  • impacted_services
  • problems
  • incidents_fixed
  • incidents_caused
  • approvers

Select to deactivate each of these transform scripts if you choose not to parse these embedded objects into records. If you need to extend or add additional capabilities, instead of modifying the existing scripts, add new ones so that upgrades are possible.

These transform scripts use specific script includes to assist in parsing and ingesting the embedded objects into the correct artifacts. The script includes are

  • PerspectiumAttachment
  • PerspectiumAffectedCI
  • PerspectiumChangeTask
  • PerspectiumImpactedService
  • PerspectiumProblem
  • PerspectiumIncident
  • PerspectiumApprovers

Attachments

Attachments are automatically embedded inside the Common Document Format record that is shared and subscribed to by MSPs and Customer Endpoints. This is done using embedded table maps that are included with the Common Endpoint update set. Attachments are limited to 7MB in size per outgoing Common Document Format record.

To ensure that duplicate attachments are not sent out in an incident, a “tag” should be created so as to tag attachments. This way, when a record is updated and attachments are queried for that record to embed, it will ignore attachments that have been sent and are “tagged”.

To setup a tag:

  1. Create a tag in the “label” table (type “label.list” in the Filter Navigator box to quickly go to the label table):

  1. Use a unique name such as “msp_client_sent” or “msp_client_change_sent” to ensure this tag is not used by other MSP or SIAM integrations. If you create the tag as “msp_client_change_sent”, you can skip the next step and are done setting up a tag.
  2. Go to the Perspectium > Control and Configuration > Table Maps and open the “Change to Common Change” outbound table map
  3. Open the field map that begins with “${TM:psp_attachment”:
  4. In this field map, replace “msp_client_change_sent” with the name of the tag you created in step one:
  5. Go to the Import Set table (type in “u_psp_common_change.list” in the Filter Navigator box) and click on the “Transform maps” UI action
  6. Open the “PSP Common Change to Change” table transform map and then go to the “Transform Scripts” section:
  7. Open up the attachment transform script and change “msp_client_change_sent” to the tag created in step one. Note, keep the “” around the tag when you replace it here. For example, if your tag is named mycompany_sent, change “msp_client_change_sent” to “mycompanysent”:

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<common_change>
   <affected_cis>
      <affected_ci>
         <ci_class>cmdb_ci</ci_class>
         <ci_name>789188b1db1272005507f3561d9619b3</ci_name>
         <ci_id>72e91bb84f110300d8f453418110c785</ci_id>
      </affected_ci>
      <affected_ci>
         <ci_class>cmdb_ci_win_server</ci_class>
         <ci_name>usgson364</ci_name>
         <ci_id>661c5ff84f110300d8f453418110c719</ci_id>
      </affected_ci>
   </affected_cis>
   <approval>approved</approval>
   <approvers>
      <approver>
         <created>2017-09-28 06:07:46</created>
         <approver_name>Bernard Laboy</approver_name>
         <assignment_group_name/>
         <approver>ee826bf03710200044e0bfc8bcbe5de6</approver>
         <state>requested</state>
         <comments/>
         <approver_email>bernard.laboy@example.com</approver_email>
         <assignment_group/>
      </approver>
   </approvers>
   <assigned_to />
   <assignment_group>f375ab304f510300d8f453418110c751</assignment_group>
   <attachments>
      <attachment>
         <data>iVBORw0KGgoAAAANSUhEUgAAAK8AAABBCAMAAACQAgS1AAAA1VBMVEX///8AAAAAmTP3+/gAlSP39/f4+fsmRGFSUlJISEiMjIwAiwAAlCvV1dWCgoLo8+vXzdSurq7V7N3N49EAigp3u4Q9nUzc7N8xMTGOjo4AhAAwm0NNTU2np6cqKipoaGh5eXlBQUEgICB/vosODg7v7++fn58ZGRnMzMzY2Ng7OzvAwMAAeQBdXV2GwJNsr3St1bdgsG9UpmAvnkYAkwo7nEm+3cVqt3uq0bEhlzecy6aJvJGyzrULjSKQy6Bar2czjzbG28tKolcAHEWSnamXxJwhmzvL0grXAAAEZUlEQVRoge2Za3+qOBCHQWJXFGUrUS6lipeK4lFbu1K10otn2+//kTYTwkVtOdjqr/si/1fMEPTpOJnMUEHg4uLi4uLi+p/p4kwSBOkk2uf996+z6PdIwhh9X/+oe7xl8Tz6W6oohe8LcV7Oy3k579d4HbPMZJoloxZb4Gi3yAK5bLLbNn2gFa8xJ1m8SqR9W9lbcxzvTerOoL239LIriuXYGod/YOp2Bi+qRMKIouHEwZYhnLqfl7cjJ2q5aUuW7Q5Z0I1Njz6Q2LLxOS9+UOuhNrNKQHDvfT20tddZSIjwzK/rdb9XwUfwyqVERtcu7Wpii63EItEW+53E9jJ4e8kX6k1cQAs9cfgrAoxWWnwf5efNzAdBGIm13Sfl1AMZ+YAbsIA1L9pKQVcatUPHkqQt8sGhg0O7Qrl5nXItUtk2aokVqi12EqME281J1mfsN8qr9mY9itnDIe/tbPYGOOoWoRkhlabNKbGlBs7Nezod8tZfLKtZDxOA8k5/VaxHiOgzxmsIbGBZEOb1Ubx96h4zqxatuaZuKGIOe7LYFvvDTz/mkBcS03qk8cSU9wkXgoUa8t6GnNaS/j3KMfG9BDnMKF0TA375NnWDy74MdT0R+4PkOhcvbsDvPq9EvGgLPHMSX1VXe7hAuY/kPY0+5kVz+P47zPIhsHqEX20iZTHfzt+VsEocmw/FYvEi2uzOTTGRQEtWW2DmyB5Hlze1nLxNymux+L7T/fYGFZnMEkrBouE/cr+NqtXqyGRGe1hNNIaSK05gQXUwrlZr5OawDNawnZN3m+INpT9EJ1yhMoeyrC3y17PTKTevdhcwPtwE3ItZ+oA7VXzHXo2GeTToDr8aX9X3wZLWAV2Jt/TQm2LlKN58+XtTatHcFRz3y/k7tVCwEWh9ALIXGvPHHdwfzweoD9Kc1QdLwVfAsySMaPVKrooxLussT1V/B544COtu9+j6q25Z/bUKigUXGlYUWnmFR5bL0FzSvu1k59tEhLONnHHGxx+Tcb7pi/h8UyxaETDCW/iUNYsuutro+pL2bWfOh37L/Yy3vrLCvF0GUf+AacEl4AjTBuiXhWnL/v4qaBpt1L7Xn9Xi/swxaG9GMsWN1kPWuJ7daX3CS/qzBu3PZnv9mbTF4bm3bPRAjeBZ85/ebrU7/M3+t5j0vxPa+5KnjchDkrvvGYbhtT7mjfrfTbDX/25WCn5MvdjTX57127V2pz38kTd7vijJ8Xxhu3S2IAW5H68n05HtOa4hH/Km5gsYJ3bnC/Kzh7uNSV2QNuL+QcqRD1nzm0yJ2HXHBboOZKydzG/9jtFvecYhbzK/zWHbp+Y3nzrQU7SgXtf9+8q9JqmbHPstMx8uzNR8TArYRLgWd/NB7HpEh/mbno+p92A+RokDPAgjVMlRz7LeP5Tbbvz+waxBEB3IVNc0U+8fuh3jg/rw5/cPSlrM/rnz7evivJyX83Le3LwHg8HJeM/z/7fimXSu/29ycXFxcXFx/YD+A/kcro9vgcpQAAAAAElFTkSuQmCC</data>
         <size_bytes>1407</size_bytes>
         <file_name>db2.png</file_name>
         <sys_id>3775ab304f510300d8f453418110c761</sys_id>
         <content_type>image/png</content_type>
      </attachment>
   </attachments>
   <backout_plan>test</backout_plan>
   <category>Virtual Server</category>
   <change_tasks>
      <change_task>
         <assignment_group />
         <short_description>Implementation Task</short_description>
         <correlation_id>CTASK000021737</correlation_id>
         <number>CTASK0010008</number>
         <work_notes />
         <comments />
         <correlation_display />
         <change_task_type>planning</change_task_type>
         <assigned_to />
         <state>-5</state>
         <description>Please initiate the Implementation process.</description>
         <cmdb_ci />
      </change_task>
      <change_task>
         <assignment_group />
         <short_description>Test Change</short_description>
         <correlation_id>CTASK000021736</correlation_id>
         <number>CTASK0010009</number>
         <work_notes />
         <comments />
         <correlation_display />
         <change_task_type>planning</change_task_type>
         <assigned_to />
         <state>-5</state>
         <description>Please test change before implementing.</description>
         <cmdb_ci />
      </change_task>
   </change_tasks>
   <close_code />
   <close_notes />
   <cmdb_ci>72e91bb84f110300d8f453418110c785</cmdb_ci>
   <comments />
   <correlation_display />
   <correlation_id>CHG000003871</correlation_id>
   <description>test all</description>
   <end_date>2017-09-24 13:09:38</end_date>
   <impact>2</impact>
   <impacted_services>
      <impacted_service>
         <operational_status />
         <type>cmdb_ci_computer</type>
         <location_name>322 West 52nd Street, New York,NY</location_name>
         <id>46b673c6a9fe1981016c72cc01ac53c2</id>
         <manually_added>1</manually_added>
         <name>382735F5AD9E492</name>
      </impacted_service>
      <impacted_service>
         <operational_status />
         <type>cmdb_ci_computer</type>
         <location_name>322 West 52nd Street, New York,NY</location_name>
         <id>46c12959a9fe1981009955ab1fa64226</id>
         <manually_added>1</manually_added>
         <name>*CAROL3-GATEWAY</name>
      </impacted_service>
   </impacted_services>
   <implementation_plan />
   <incidents_caused>
      <incident>
         <number>INC0010001</number>
         <opened_at>2017-09-17 06:19:39</opened_at>
         <category>inquiry</category>
         <caller_id_name>Adela Cervantsz</caller_id_name>
         <assigned_to_name />
         <short_description>test</short_description>
         <priority>5</priority>
         <id>5e972f704f510300d8f453418110c749</id>
         <state>1</state>
         <assignment_group_name />
      </incident>
   </incidents_caused>
   <incidents_fixed>
      <incident>
         <number>INC0000004</number>
         <opened_at>2017-05-17 22:49:22</opened_at>
         <category>inquiry</category>
         <caller_id_name>Fred Luddy</caller_id_name>
         <assigned_to_name>Bud Richman</assigned_to_name>
         <short_description>Forgot email password</short_description>
         <priority>1</priority>
         <id>9d3c1197c611228701cd1d94bc32d76d</id>
         <state>7</state>
         <assignment_group_name>Service Desk</assignment_group_name>
      </incident>
      <incident>
         <number>INC0000005</number>
         <opened_at>2017-05-06 23:06:52</opened_at>
         <category>hardware</category>
         <caller_id_name>Alejandro Mascall</caller_id_name>
         <assigned_to_name>Bud Richman</assigned_to_name>
         <short_description>CPU load high for over 10 minutes</short_description>
         <priority>1</priority>
         <id>e8e875b0c0a80164009dc852b4d677d5</id>
         <state>7</state>
         <assignment_group_name>Hardware</assignment_group_name>
      </incident>
   </incidents_fixed>
   <justification />
   <number>CHG0030012</number>
   <priority>3</priority>
   <problems>
      <problem>
         <short_description>Windows XP SP2 causing errors in Enterprise</short_description>
         <assignment_group_name />
         <id>46eaa7c9a9fe198100bbe282da0d4b7d</id>
         <assigned_to_name>ITIL User</assigned_to_name>
         <state>3</state>
         <number>PRB0000001</number>
      </problem>
   </problems>
   <provider>servicenow</provider>
   <psp_action />
   <requested_by>6a32259c4fd14300d8f453418110c71d</requested_by>
   <requested_by_date />
   <risk>3</risk>
   <short_description>test perspectium 4</short_description>
   <start_date>2017-09-23 13:09:35</start_date>
   <state>-3</state>
   <test_plan>test</test_plan>
   <type>standard</type>
   <work_notes />
</common_change>

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 Change Sample - Inbound.xml.gz

Common Change Sample - Outbound.xml.gz

common_change_format.txt · Last modified: 2018/01/01 21:47 by paul