Create an Incident

  • Navigate to Incident > Create New.
  • The Incident fields to configure are as follows:
# Field Description Value
1 Caller Person who reported or is affected by this incident. < Your Caller >
2 Category The type of issue. < Your Category >
3 Impact* Measure of the business criticality of the affected service. < Your Impact >
4 Urgency* The extent to which resolution of an incident can bear delay. < Your Urgency >
5 Short description A brief description of the incident. < Your Short description >
6 Description Detailed explanation on the incident. < Your Description >

*Impact/Urgency: These values are used to calculate the Priority.

Your Incident form should look like this:

New Incident Form

  • Note the values entered (including State & Priority), so that you can check them against the mapped fields on the corresponding record in the instance being integrated to.
  • ‘Save’ the Incident.

You should see a blue Info Message, confirming the CreateIncident Message is being sent to your Integration:

Sending CreateIncident

You should also see a note in the Activities stream:

Work Notes

When you scroll down to the ‘Integrations’ related list, notice:

Integrations Related List

  1. A Bond has been created.
  2. The State remains ‘pending’ until the list is refreshed.
  3. Refresh the list by clicking ‘Bonds.’

You should see the External reference populated & the State changed to ‘Open’:

Integrations Related List Refreshed

Note: We are using a sys_id for the External reference in our example because we are integrating with the table API. If possible, it is better to use something more meaningful, like the Number of the ticket integrated with, as this aids in debugging.

  1. Click on the link to the Bond in the Number column to open the Bond record.

View the Bond

Your Bond record should look like this:

Bond

  1. Bond details:
    • Integration: < Your Integration >
    • Table: ‘Incident [incident]’
    • Document: < Your Incident >
    • State: ‘Open’ (Message exchange is available)
    • Status: ‘OK’ (All transactions have completed)
    • Internal reference: < ServiceNow ticket reference > (Same as ‘Document’)
    • External reference: < External system’s ticket reference >
  2. History:
    • < History of transaction updates on the Bond > (Sending CreateIncident…)
  3. Transaction:
    • Message: ‘Createincident’
    • Direction: ‘Outbound’
    • Transaction state: ‘Complete’ (The data has been successfully transported)
    • Process state: ‘Accepted’ (The transaction was accepted as within the scope of the business logic that’s in place)

Note: Coming in Unifi v2 - you will be able to view the logs in the ‘Unifi Activity Logs’ related list.

Activity Logs

  1. Transaction sending: Logs from taking the Stage data, building the Request record & sending the Request to the integrated system.
  2. Transaction process next queued: Logs from checking whether there are any other transactions queued and processing those.

View the Transaction

  • Click through to the Transaction record from the related list on the Bond.

Your Transaction record should look like this:

Transaction

  1. Transaction details:
    • Table: ‘Incident [incident]’
    • Document: < Your Incident >
    • Integration: < Your Integration >
    • Bond: < Your Bond >
    • Message: ‘CreateIncident’
    • Direction: ‘Outbound’
    • Transaction state: ‘Complete’ (The data has been successfully transported)
    • Process state: ‘Accepted’ (The transaction was accepted as within the scope of the business logic that’s in place)
  2. Errors:
    • Error: (If there was a transactional error the Transaction state would show as ‘Error’ and the details would be captured here).
    • Process error: (If there was a process error the Process state would show as ‘Rejected’ and the details would be captured here)
  3. Stage:
    • Direction: ‘Outbound’
    • Message: ‘CreateIncident’
    • Internal reference: < ServiceNow ticket reference > (Same as ‘Document’)
    • External reference: < External system’s ticket reference >

View the Stage

  • Click through to the Stage record from the related list on the Transaction.
  • Check the values in the fields match what you expect.

Your Stage record should look like this:

Stage

Note: This form has been configured to display only the fields we are interested in for this integration.

  1. Stage details:
    • Direction: ‘Outbound’
    • External reference: < External system’s ticket reference >
    • Internal reference: < ServiceNow ticket reference >
    • Message: ‘CreateIncident’
    • Transaction: < Your Transaction >
    • Integration: < Your Integration >
  2. Mapped stage fields:
    • Caller ID: < Your caller.id >
    • Category: < Your Category >
    • Impact: < Your Impact >
    • Urgency: < Your Urgency >
    • Priority: < Your Priority >
    • Short description: < Your Short description >
    • Description: < Your Description >

View the HTTP Request

  • Click through to the HTTP Request record from the related list on the Transaction.

Note: this is where you will find details of the data that was transported between the systems being integrated. (These records are extremely useful for developing and debugging integrations because of the immediate availability and contextual relevance to the integration you are developing.)

Your HTTP Request record should look like this:

HTTP Request

  1. HTTP Request details:
    • Integration: < Your Integration >
    • Connection: < Your Connection >
    • Transaction: < Your Transaction >
    • Message: ‘CreateIncident’
    • Direction: ‘Outbound’
    • Request state: ‘OK’ (There are no errors with the HTTP Request.)
    • Attempt number: < Number of HTTP Request attempts > (Failed requests are retried up to the maximum attempts number as configured on the *Integration*.)
    • Endpoint URL: < The external system’s access URL >
  2. Payload details:
    • Request payload: < The payload of the request being sent >
    • Response payload: < The payload of the response being received >

Compare with the External System’s Incident

  • Navigate to the corresponding Incident in the external system.

  • Check the values in the fields match those you noted when you saved the Incident in the internal system.

Your external system’s Incident record should look like this (depending on the system you’re integrating with, your record may look different; the important matter is that the values match):

External System's Ticket

  1. Caller: < Your Caller >
  2. Category: < Your Category >
  3. State: < Your State >
  4. Impact: < Your Impact >
  5. Urgency: < Your Urgency >
  6. Priority: < Your Priority >
  7. Short description: < Your Short description >
  8. Description: < Your Description >
  9. Activities: < Note showing activity on the Incident > (Opened by < your.external.system.user > configured in the Connection)

We are now ready to move on and Update the Incident.