The Common Change document is an XML schema that contains default fields for mapping change request form values from one system to another. The common change format mirrors what one would see in an ITIL view of the Change Request form with related lists expressed in embedded XML form.
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.
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. Please note this is only necessary if it applies to your use case.
if (current.comments.nil() && current.work_notes.nil()) { ignore = true; } |
Embedded records are fields in the Common Change document that cannot be mapped by singular values. Instead, they are entirely different records embedded inside the Common Change document to be created on the subscribing system.
NOTE: Deactivate each of the transform scripts in PSP Common Change to Change 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 Change:
The CI affected field in the Common Change is an embedded record that, when populated, will create a new CI affected on the system receiving the Common Change.
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 |
The approver field in the Common Change is an embedded record that, when populated, will create a new approver on the system receiving the Common Change.
Table Map Source Field | Definition |
---|---|
created | Date the record was created on |
approver_name | Name of the approver |
assignment_group_name | Name of the assignment group |
approver | Unique record identifier of the approver record |
comments | Comments of the approver |
approver_email | Email of the approver |
assignment_group | Unique record identifier of the assignment group record |
The attachment field in the Common Change is an embedded record that, when populated, will create a new attachment on the system receiving the Common Change.
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.) |
The change task field in the Common Change is an embedded record that, when populated, will create a new change task on the system receiving the Common Change.
Table Map Source Field | Definition |
---|---|
assignment_group | Unique record identifier of the assignment group record |
short_description | Short description of the change task |
correlation_id | Unique record identifier of the correlating change task |
number | Record number of change task |
work_notes | Work notes for the change task |
comments | Comments for the change task |
correlation_display | Unique record display of the correlating change task |
change_task_type | Change task category |
assigned_to | User the change task is assigned to |
state | State of the change task |
description | Description of the change task |
cmbd_ci | Unique record identifier of the parent record |
The impacted service field in the Common Change is an embedded record that, when populated, will create a new impacted service on the system receiving the Common Change.
Table Map Source Field | Definition |
---|---|
operational_status | Status of the impacted service |
type | Class type of the impacted service |
location_name | Location of the impacted service |
id | Unique record identifier of the impacted service |
manually_added | Represents if the impacted service is added manually |
name | Name of the impacted service |
The incidents_caused and incidents_fixed fields in the Common Change is an embedded record that, when populated, will create a new incident on the system receiving the Common Change.
Table Map Source Field | Definition |
---|---|
assigned_to_name | Display name of the assigned user |
assignment_group_name | Display name of the assigned group |
caller_id_name | Display name of the caller |
category | Category the incident record falls under |
number | Number of the incident record |
opened_at | Date the incident record was opened |
priority | Priority level of the incident record |
short_description | Short description of the incident record |
state | State of the incident record |
id | Unique record identifier of the incident |
The problems field in the Common Change is an embedded record that, when populated, will create a new problem on the system receiving the Common Change.
Table Map Source Field | Definition |
---|---|
short_description | Short description of the problem record |
assignment_group_name | Display name of the assigned group |
id | Unique record identifier of the problem |
assigned_to_name | Display name of the assigned user |
state | State of the problem record |
number | Number of the problem record |
The Perspectium Common Change Helium update set will contain the following:
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 |
Name | Type | Target Table | Description |
---|---|---|---|
Common Change to PSP Common Change | common_change | PSP Common Change (u_psp_common_change) | Main body of the common_change format |
Name | Description |
---|---|
PSP Common Change to Change Request (u_psp_common_chane) | Transforms the common_change format to change. |
A sample Common Change looks like this:
<common_change> <affected_cis> <affected_ci> <ci_class /> <ci_name /> <ci_id /> </affected_ci> </affected_cis> <approval /> <approvers> <approver> <created /> <approver_name /> <assignment_group_name/> <approver /> <state /> <comments/> <approver_email /> <assignment_group/> </approver> </approvers> <assigned_to /> <assignment_group /> <attachments> <attachment> <data /> <size_bytes /> <file_name /> <sys_id /> <content_type /> </attachment> </attachments> <backout_plan /> <category /> <change_tasks> <change_task> <assignment_group /> <short_description /> <correlation_id /> <number /> <work_notes /> <comments /> <correlation_display /> <change_task_type /> <assigned_to /> <state /> <description /> <cmdb_ci /> </change_task> </change_tasks> <close_code /> <close_notes /> <cmdb_ci /> <comments /> <correlation_display /> <correlation_id /> <description /> <end_date /> <impact /> <impacted_services> <impacted_service> <operational_status /> <type /> <location_name /> <id /> <manually_added /> <name /> </impacted_service> </impacted_services> <implementation_plan /> <incidents_caused> <incident> <number /> <opened_at /> <category /> <caller_id_name /> <assigned_to_name /> <short_description /> <priority /> <id /> <state /> <assignment_group_name /> </incident> </incidents_caused> <incidents_fixed> <incident> <number /> <opened_at /> <category /> <caller_id_name /> <assigned_to_name /> <short_description /> <priority /> <id /> <state /> <assignment_group_name /> </incident> </incidents_fixed> <justification /> <number /> <priority /> <problems> <problem> <short_description /> <assignment_group_name /> <id /> <assigned_to_name /> <state /> <number /> </problem> </problems> <provider /> <psp_action /> <requested_by /> <requested_by_date /> <risk /> <short_description /> <start_date /> <state /> <test_plan /> <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