The Common Incident document is an XML schema that contains default fields for mapping incident form values from one system to another. The common incident format mirrors what one would see in an ITIL view of an Incident form with related lists expressed in embedded XML form.
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.
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;
}
Embedded Records
Embedded records are fields in the Common Incident document that cannot be mapped by singular values. Instead, they are entirely different records included inside the Common Incident document to be created on the subscribing system.
NOTE: Deactivate each of the transform scripts in PSP Common Incident to Incident 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.
The following are examples of the embedded records in Common Incident:
Configuration Item's Affected Embedded Record
The CI affected field in the Common Incident is an embedded record that, when populated, will create a new ci affected on the system receiving the Common Incident.
| Table Map Source Field | Definition |
|---|---|
| ci_class | Class name of the configuration item |
| ci_name | Name of the configuration item |
| ci_id | Unique record identifier of the configuration item |
Assignment Group Embedded Record
The assignment group field in the Common Incident is an embedded record that, when populated, will create a new assignment group on the system receiving the Common Incident.
| Table Map Source Field | Definition |
|---|---|
| Email that represents the assignment group | |
| manager | Manager of the assignment group |
| manager_email | Manager's email address of the assignment group |
| name | Name of the assignment group |
Assigned To Embedded Record
The assigned to field in the Common Incident is an embedded record that, when populated, will create a new assigned to user on the system receiving the Common Incident.
| Table Map Source Field | Definition |
|---|---|
| Email address of user | |
| first_name | First name of user |
| last_name | Last name of user |
| user_name | User name of user |
Attachment Embedded Record
The attachment field in the Common Incident is an embedded record that, when populated, will create a new attachment on the system receiving the Common Incident.
| Table Map Source Field | Definition |
|---|---|
| data | Attachment data in an encoded string format |
| size_bytes | Measurement of how much the attachment data contains |
| file_name | Name of the attached file |
| sys_id | Unique record identifier of the attachment |
| content_type | Attachments content type (i.e jpeg, png, txt, etc.) |
Caller Embedded Record
The caller field in the Common Incident is an embedded record that, when populated, will create a new caller on the system receiving the Common Incident.
| Table Map Source Field | Definition |
|---|---|
| first_name | First name of caller |
| mobile_phone | Phone number of caller |
| active | Represents if the caller record is active or not |
| last_name | Last name of caller |
| Email address of caller | |
| location | Location of caller |
| employee_number | Employee number of caller |
| user_name | User name of caller |
| name | Full name of caller |
Opened By Embedded Record
The opened by field in the Common Incident is an embedded record that, when populated, will create a new opened by user on the system receiving the Common Incident.
| Table Map Source Field | Definition |
|---|---|
| Email address of user | |
| first_name | First name of user |
| last_name | Last name of user |
| user_name | User name of user |
Resolved By Embedded Record
The resolved by field in the Common Incident is an embedded record that, when populated, will create a new opened by user on the system receiving the Common Incident.
| Table Map Source Field | Definition |
|---|---|
| Email address of user | |
| first_name | First name of user |
| last_name | Last name of user |
| user_name | User name of user |
Table Maps
The Perspectium Common Change Helium update set will contain the following:
Outbound Table Maps
| Name | Type | Source Table | Description |
|---|---|---|---|
| Incident to Common Incident | common_incident | Incident [incident] | Main body of the common_incident format |
| psp_attachment | embedded_attachment | sys_attachment | Map for building embedded attachments field |
| psp_affected_ci | embedded_affected_ci | CIs Affected [task_ci] | Map for building embedded affected CIs |
Inbound Table Map
Name | Type | Target Table | Description |
|---|---|---|---|
| Common Incident to PSP Common Incident | common_incident | PSP Common Incident (u_psp_common_incident) | Main body of the common_incident format |
Import Set
Name | Description |
|---|---|
| PSP Common Incident to Incident (u_psp_common_incident) | Transforms the common_incident format to incident. |
Sample Output
A sample Common Incident looks like this:
<common_incident>
<action />
<active />
<activity_due />
<additional_assignee_list />
<affected_cis>
<affected_ci>
<ci_class />
<ci_name />
<ci_id />
</affected_ci>
</affected_cis>
<approval />
<approval_history />
<approval_set />
<assigned_tos>
<assigned_to>
<email />
<first_name />
<last_name />
<user_name />
</assigned_to>
</assigned_tos>
<assignment_group_name />
<assignment_groups>
<assignment_group>
<email />
<manager />
<manager_email/>
<name />
</assignment_group>
</assignment_groups>
<attachments>
<attachment>
<data />
<size_bytes />
<file_name />
<sys_id />
<content_type />
</attachment>
</attachments>
<business_duration />
<business_service_name />
<business_stc />
<calendar_duration />
<calendar_stc />
<callers>
<caller>
<first_name />
<mobile_phone />
<active />
<last_name />
<email />
<location />
<employee_number />
<user_name />
<name />
</caller>
</callers>
<caller_id />
<caller_full_name />
<caller_first_name />
<caller_last_name />
<caller_email />
<category />
<caused_by />
<child_incidents />
<close_code />
<close_notes />
<closed_at />
<closed_by />
<closed_bys>
<closed_by>
<email />
<first_name />
<user_name />
<last_name />
</closed_by>
</closed_bys>
<cmdb_ci_id />
<cmdb_ci_name />
<comments />
<comments_and_work_notes />
<company_id />
<company_name />
<contact_type />
<correlation_display />
<correlation_id />
<delivery_plan_display />
<delivery_task_display />
<description />
<due_date />
<escalation />
<expected_start />
<follow_up />
<group_list />
<impact />
<incident_state />
<knowledge />
<location_id />
<location_name />
<locations>
<city />
<company />
<contact/>
<country />
<fax_phone/>
<full_name />
<lat_long_error/>
<latitude />
<longitude />
<name />
<parent/>
<phone/>
<phone_territory display_value="Colombia">04b7e002eb1201007128a5fc5206fe0e</phone_territory>
<state/>
<stock_room>false</stock_room>
<street/>
<time_zone/>
<zip/>
</locations>
<made_sla />
<notify />
<number />
<opened_at />
<opened_by />
<opened_bys>
<email />
<user_name />
<first_name />
<last_name />
</opened_bys>
<order />
<parent_id />
<parent_incident_number />
<priority />
<problem_id />
<problem_number />
<provider />
<reassignment_count />
<reopen_count />
<resolved_at />
<resolved_by />
<resolved_bys>
<email />
<user_name />
<first_name />
<last_name />
<resolved_bys/>
<rfc_id />
<rfc_display />
<severity />
<short_description />
<sla_due />
<state />
<subcategory />
<time_worked />
<urgency />
<variables />
<watch_list />
<work_end />
<work_notes />
<work_start />
</common_incident>
The following Perspectium Inbound/Outbound Message unloads can be un-zipped and uploaded into your instance of ServiceNow to be viewed and/or used for testing.
Common Incident Sample - Inbound.xml.zip
Common Incident Sample - Outbound.xml.zip