ServiceNow’s JSON Web Service interface 3 / 3

Data modification functionality

In the first instalment of this blog series I briefly covered the JSON notation, compared it to SOAP and wrote about the overview of the ServiceNow platform’s JSON Web Service Interface.

In the second post I wrote about the JSON Web Service URL composition, action parameters and the Data retrieval functionality

In this blog post I will be covering the data modification functionality of the JSON Web Service interface.

URL

All of the examples in this blog post make a HTTPS POST call to same URL ( https://<instance>/incident.do?JSON ), but as you might remember from the previous blog post some of the action parameters can be concatenated into the URL and can then be dropped from the HTTPS POST call’s JSON payload.

insert and insertMultiple actions

The insert and insertMultiple actions are quite similar. You define the sysparm_action and provide the information to create new records.

The insert call

{"sysparm_action":"insert", "sysparm_view":"ess", "short_description":"testing 123"}

and response

The insertMultiple call. Pay attention to where the sysparm_action and sysparm_view are defined. If you define the sysparm_action within the record objects, the JSON Web Service will respond with an error message stating that the sysparm_action is not defined.

{
    "sysparm_action":"insertMultiple",
    "sysparm_view":"ess",
    "records":[
        {"short_description":"testing1"},
        {"short_description":"testing2"}
    ]
}

And response

update action

The update action can be used to update one or more records at one go. It all depends on the sysparm_query used to select the records to be updated. In the (poor) example below, we update the comments field in all records where the active field is true. If you would like to update just one record, use the sys_id or any other unique field in the query.

{
 "sysparm_action":"update",
 "sysparm_view":"ess",
 "sysparm_query":"active=true",
 "comments":"testing1,2,3"
}

The response message contains the now so familiar array of records.

 

deleteRecord action

The deleteRecord action is used to delete a single record from the system. As in the “get” action, deleteRecord requires the use of sysparm_sys_id to identify the record to be deleted.

{
 "sysparm_action":"deleteRecord",
 "sysparm_sys_id":"000d035ad0988100aa2866b3d3ae7e30",
}

The response message to the call will contain the information of the deleted record. Or an empty array if no records were deleted.

 

deleteMultiple action

The deleteMultiple actions is used to delete all records matching the query defined in the sysparm_query parameter. The response contains the count of deleted records.

{
 "sysparm_action":"deleteMultiple",
 "sysparm_query":"short_descriptionINtesting1,testing2"
}

The response returns the number of the deleted records.

{"records":[{"count":6}]}

The deleteMultiple is obviously quite powerful feature, and it is easy to delete too much. In fact, yours truly managed to delete 592 records from our demo environment using the following JSON payload. Kudos (and a free beer in Helsinki for first 10) to you if you spot the difference between the one that deleted 6 records and the one which deleted 592 records, shown below =)

{
 "sysparm_action":"deleteMultiple",
 "sysparm_query":"short_decriptionINtesting1,testing2",
}

This is what failure looks like.

{"records":[{"count":592}]}

Send email via LinkedIn or directly to my email accounts for the free beer. Free beer not available to Symfoni Finland employees ;)

Conclusions / Wrap up

During this blog series I have hopefully shown you how to leverage the ServiceNow platform’s JSON Web Service interface in your integrations, and inadvertently shown how you can totally screw up by making the slightest mistake with deleteMultiple action.