Service Catalog API for Order Guide

[Alikutty A]

The Service Catalog API used for requesting an order guide has been there for a while but you wont find a clear documentation on how exactly you could request them. This blog explores its usage, alternatives and related drawbacks. There are 3 API’s required to submit a request for order guide. If the order guide has a Two step flag checked then it requires only 2 APIs. The following Service Catalog APIs needs to be called in a sequential order to submit the request.

1. SUBMIT GUIDE - /sn_sc/servicecatalog/items/{sys_id}/submit_guide

This submit guide is called first to filter out the required items based on the rule base of order guide. You will need to input the order guide variables which are required to filter the items. The cart item entries are added in the DEFAULT cart of user and it will contain all selected items based on rule base. The variables in cart items will remain empty and needs to be populated by the checkout_guide API. If the Two step is checked, then a new sc_cart entry for the user is created with order guide sys_id as its name and it does not get added to the DEFAULT cart.

{
  variables :{
    "standard_package" : "No",
    "hiring_manager" : "admin",
    "laptop_type" : "sales"
  }
}

2. CHECKOUT GUIDE - /sn_sc/servicecatalog/items/{sys_id}/checkout_guide

The second API should be requested soon after the first call and it should contain all the variables associated with the catalog items that got selected in the order guide. This will update values for all variables within the cart items. If Two step is checked on order guide then the request gets submitted and the response will contain the request number and its sys_id. You will not require to use the third API to submit the cart.

{
    "items": [{
                 "sys_id": "04b7e94b4f7b4200086eeed18110c7fd",
                 "variables": {
                                "acrobat": true,
                                "remote": "No",
                                "additional_software_requirements": "NA"
                              }
              }]
}

3. SUBMIT ORDER - /sn_sc/servicecatalog/cart/submit_order

If Two step is not checked on the order guide then, the third API is required to submit the cart. The API does not require any input and will return the request number in the response.

These APIs can be accessed under the scripted REST APIs and you could understand its working or customize it if there are additional requirements to handle. To access, replace your instancename in the link  - https://instancename.service-now.com/nav_to.do?uri=sys_ws_definition.do?sys_id=b4558e83c3a302006f333...

You could also disable the mandatory validations on variables by passing the value of sysparm_no_validation in the request body. This will skip all mandatory variable validations.

eg: "sysparm_no_validation": "true"

DRAWBACKS

1. Using cascade on an order guide does not pass the values to the catalog items and you will need to additionally pass the cascaded variable values in the request body of checkout_guide API for each items separately
2. The API does not support usage of MVRS variables and you will require additional API to update any associated variables in a multi row variable set
3. It does not support the use of Requested For variable. The API would take the value of your web service user id as the requested for. If you are requesting from an external system, you would probably need to impersonate as the requested for or use other approaches to populate its value correctly
4. For reference fields, you will need to pass the sys_id from external systems which is not a practical solution. You could also pass the display name but there can be cases where the name is duplicate and the API is not be able to locate the correct record
5. Since it involves usage of 3 API’s, you need to make sure that all are submitted sequentially to ensure the request is properly submitted. It can produce incorrect results if there is a delay or error in processing it.

ALTERNATE METHOD

The SNC.ScriptableOrderGuide API can be used to submit an order guide via scripting. The good part of this API is that it supports cascading of variables and you also get the ability to specify the requested_for as a different user but the bad part is that it does not allow you to update additional variables within your catalog items that are not cascaded. You could primarily use it for cases where all the variable values are cascaded in an order guide. You can find additional information on its usage from the official documentation (link provided under references)

REFERENCES

https://docs.servicenow.com/bundle/quebec-application-development/page/integrate/inbound-rest/concep...

https://docs.servicenow.com/bundle/quebec-application-development/page/script/server-scripting/conce...