UPDATE: As of the Helsinki ServiceNow release, this is tracked for you automatically in a new ‘Order Guide’ field on the ‘Requested Item’ table! This solution should be discontinued in Helsinki releases and beyond.

O

rder guides are a service catalog concept that allow you to set up an initial form to ask the user certain questions in order to determine a collection of catalog items they need to order. The classic use case for an order guide is the ‘New Employee Hire’ item that ServiceNow provides in the out-of-box demo data. While order guides are really a front-end routing concept, it can sometimes be useful to report on requests that were generated for a particular order guide. This functionality doesn’t exist out-of-box in ServiceNow, but it is very easy to add. Here’s a good tip that I recently learned from Sean Grison and Valor Poland about how to populate the order guide used to generate a particular request.

While this solution gets you as close as possible to populating the correct order guide used to generate a request, you may still notice some false positives due to system behavior we can’t control. Any time people click on an order guide item in the catalog (even if they don’t end up completing the order guide), the order guide is populated on the cart and will be populated on the next request. Another issue is that people can work through an order guide and then delete certain contents of the request on the confirmation screen, and then go back to the catalog and add more items unrelated to the order guide. Unfortunately, there’s not any way to guarantee that the order guide will be populated correctly 100% of the time because of these factors.

The script below mitigates some of these issues by checking to make sure that at least one of the items from the order guide rule base is included in the order if we are populating the Order guide field on the request. It also does a second check to verify that any order guide rule base entry with NO condition (meaning it always ends up being added to the order guide) MUST be included in the order.

Even with these additional checks in place, the system behavior might still result in requests where somebody clicked on an order guide, then ordered one of the items in the guide as a standalone item instead. The best way to guard against this is to make sure you have at least one item with no conditions in the rule base, ensuring that it will always have to be part of the order if we’re going to populate an order guide.

Only three steps are necessary to record the order guide used to generate a request…

  1. Create a new reference field called ‘Order guide’ on the ‘Request (sc_request)’ table. The field needs to reference the ‘Order guide (sc_cat_item_guide)’ table. You may also choose to secure write access to this field using an ACL since it really shouldn’t need to be changed by any user.
  2. Create a new business rule on the ‘Request (sc_request)’ table with the following settings…
    ‘Populate Order Guide’ Business Rule
    Name: Populate Order Guide
    When: Before
    Insert: True
    Script:

    var c = new GlideRecord('sc_cart');
    c.get('user', gs.getUserID());
    if(c.current_guide){
       var isOrderGuide = true;
       var foundItemCount = 0;
       //Query the order guide rule base
       var og = new GlideRecord('sc_cat_item_guide_items');
       og.addQuery('guide', c.current_guide);
       og.query();
       while(og.next()){
          var mustHave = false;
          var foundItem = false;
          //If the condition is empty then item must be ordered
          if(og.condition.nil()){
             mustHave = true;
          }
          //Check to see if the rule matches at least one item in the cart
          var itm = new GlideRecord('sc_cart_item');
          itm.addQuery('cart', c.sys_id);
          itm.addQuery('cat_item', og.item.sys_id.toString());
          itm.query();
          if(itm.hasNext()){
             foundItem = true;
             foundItemCount++;
          }
          if(mustHave && !foundItem){
             //Do not update order guide
             isOrderGuide = false;
             break;
          }
       }
       if(isOrderGuide && foundItemCount > 0){
          //If actual order guide items are included populate the order guide field
          current.u_order_guide = c.current_guide;
       }
    }
  3. Set up a ‘Write’ ACL on your new ‘Order guide’ field to restrict access to the field. This field should only be modified by the system as part of the ordering process so you should set up an ACL to limit those permissions. The simplest way to do this is to set up a write ACL for ‘sc_request.u_order_guide’ with the ‘nobody’ role and un-check the ‘Admin override’ checkbox.

Now when users order an item using a record producer, the record producer will be referenced in the ‘Order guide’ field you created on the request table!

Knowing the order guide used to generate a request allows you to do all sorts of cool things including…

  • Reporting against the request table to see how often each order guide is used
  • Controlling the execution order of requested items within an order guide
  • Using the ‘Order guide’ field value as a key to separate workflow logic for an item that can be ordered as a standalone item or as part of an order guide

Request Order Guide