How to submit an Order Guide through REST API?

[goswami_sudipta]

Hello,

There are OoB REST APIs are available for service catalog, and I wanted to use those to submit an Order Guide. 

My Order Guide consists of two catalog items and can be chosen based on a drop down value in describe needs.The Order Guide is a custom created one which has two OoB items - Standard Laptop (04b7e94b4f7b4200086eeed18110c7fd) and Apple iPad 3 (060f3afa3731300054b6a3549dbe5d3e). Now, when I tried using below REST API Name - Checkout Order guide (https://xxx.service-now.com/sys_ws_operation.do?sys_id=b7fe7ff5c3101200d68d3b0ac3d3aecc).

I am using below values in parameter value and in request body

Path parameters - sys_id : sys_id of the Order Guide

Request Body - 

{"items":[{
  "sys_id":"04b7e94b4f7b4200086eeed18110c7fd",
  "variables":{
    "acrobat":"true",
    "Additional_software_requirements":"MS Office 2007"
  },
  "sysparm_quantity":"3"
}]}

Now when I send this, I am getting below error in response

Status Code: 400 Bad Request

Response body is as below. 

{
  "error": {
    "detail": "",
    "message": "All required items not sent"
  },
  "status": "failure"
}

Could anyone please let me know what I am doing wrong here? Thank you.

[Kiran Patil3]

Hi @goswam.sudipta

We have exactly same requirement but very poop documentation around Order Guide REST API. 

Did you get any solution or approach for above requirement, if yes, could you please share it.

[wakespirit]

we skip this part for the moment

[Kiran Patil3]

Hi

I was able to figure it out using running order guide automatically using server side scripting. Documentation does not explain it in details but very briefly.

Here is test I run on personal instance:

json needs to be updated as per requirement (variables & variables sets)

Basically, order guide need to have all variables which are on all catalog item in order guide.

var json = {"opened_by":"6816f79cc0a8016401c5a33be04be441",
			"requested_for":"6816f79cc0a8016401c5a33be04be441",
			"department":"221f3db5c6112284009f4becd3039cc9",
			"hiring_manager":"6816f79cc0a8016401c5a33be04be441",  //Added same variables as catalog item in order guide and set cascade checked.
			"new_email":"kiran.patil@teradata.com"};              //Added same variables as catalog item in order guide and set cascade checked.
 
var gr = new GlideRecord("sc_cat_item_guide");
if (gr.get("name","New Hire")) {
  var sog = new SNC.ScriptableOrderGuide(gr.getValue("sys_id"));
  var result = sog.process(new JSON().encode(json));
  if(!result)
    gs.log("Processing the scriptable order guide failed with message: " + sog.getMessage());
  else { 
    var request = sog.getRequest();
    gs.log("Request created - " + request.sys_id); } }

[jimv]

You don't have to create a scripted REST API to submit order guides. Which method is most appropriate depends on your requirements. To use the Service Catalog REST API, you need to make three requests, in order:

1. submit_guide
2. checkout_guide
3. checkout

submit_guide creates a cart and inactive cart items according to the order guide rule base applied to the variable values passed.

checkout_guide allows you to set variable values for catalog items corresponding to the cart items in the cart - where these variables have not been cascaded from the order guide. You have to explicitly reference all the catalog items associated with the cart items in the cart in the request (if there is a complex rule base this is what makes the baseline API challenging to use properly e.g. you will get errors if any mandatory variable values aren't provided or if a catalog item reference is missing for an associated cart item). After a successful request the cart items are marked active and are ready to be checked out.

checkout checks the cart out - essentially completing the order guide submission.

The summary above applies to one-step cart checkout.

In real world usage the biggest issue is likely to be associating the order guide beneficiary properly. The opened_by and requested_for columns on the resulting sc_request record will correspond to the request's authenticated user. So, for example, if you were submitting an order guide on behalf of a new hire, you'd have to authenticate the REST requests as the new hire user i.e. supplying the password. If you need independent control over the opened_by and requested_for values or you just want to use a single web services account for all submissions (but still set requested_for for each real beneficiary), then you'll need to go down the scripted REST API approach identified above.

A drawback of using SNC.ScriptableOrderGuide in a scripted REST API is that you can only easily set variable values for cart items by cascading all of them from the order guide. This means your guides and items need to be designed specifically with this approach in mind (e.g. avoid duplicate variable names in different catalog items in the guide unless the values are always the same).