Submitting Service Catalog Items via Server-Side Script

Automating the submission of Service Catalog items is a fundamental requirement for advanced ServiceNow implementations, enabling processes like inbound email provisioning, workflow automation, and external integrations. This is achieved using server-side APIs that mimic the user checkout process.

The method you choose depends on your application’s scope: the Global scope uses the traditional Cart API, while a Scoped Application uses the modern CartJS API.

---

1. Using the CART API (Global Scope)

The Cart API is a widely-used, server-side object available for scripts running in the Global scope, such as Business Rules, Inbound Email Actions, or Global Script Includes.

Key Steps

1. Instantiate the Cart: Create a new Cart object, typically using a unique GlideGuid.
2. Add the Item: Use the addItem() method with the sys_id of the catalog item. This returns a cart item ID.
3. Set Variables: Use the setVariable() method to populate the item’s variables using the cart item ID, variable name, and value.
4. Place the Order: Use the placeOrder() method to submit the request.

Code Example

This script submits a catalog item and retrieves the resulting RITM number.

JavaScript

// 1. Instantiate the Cart with a unique ID
var cartID = GlideGuid.generate(null);
var cart = new Cart(cartID);

// Replace with your catalog item's sys_id
var catalogItemSysID = 'a22c1b1c476721004653609822a7fcf2';

// 2. Add the item and get its cart item ID
var cartItemID = cart.addItem(catalogItemSysID);

// 3. Set the variables for the item
cart.setVariable(cartItemID, 'ram_size', '16GB'); 
cart.setVariable(cartItemID, 'operating_system', 'windows_11');
cart.setVariable(cartItemID, 'location', 'San_Diego');

// 4. Place the order
var requestGR = cart.placeOrder(); // Returns a GlideRecord for the sc_request

// 5. Retrieve the RITM number from the Request
var ritmGR = new GlideRecord('sc_req_item');
ritmGR.addQuery('request', requestGR.sys_id);
ritmGR.query();

if (ritmGR.next()) {
    gs.print('Order Submitted! Request: ' + requestGR.number + ', RITM: ' + ritmGR.number);
}

💡 Important Note: The placeOrder() method returns the Request (sc_request). You must perform a separate GlideRecord query on the Request Item table (sc_req_item) using the Request’s sys_id to get the resulting RITM number.

---

2. Using the Cartjs API (Scoped Application)

The CartJS API is the modern, preferred method for submitting catalog items when working within a Scoped Application. It relies on JSON objects for input and output, making it highly structured.

Key Steps

1. Instantiate CartJS: Create a new sn_sc.CartJS object.
2. Define Item Details: Construct a JSON object containing the item’s sysparm_id, sysparm_quantity, and a nested variables object.
3. Add to Cart: Use the addToCart() method with the item details JSON.
4. Checkout: Use the checkoutCart() method to submit the order.

Code Example

This script uses the JSON-based approach to submit the catalog item.

JavaScript

// 1. Instantiate the CartJS object
var cart = new sn_sc.CartJS();

// 2. Define the Catalog Item and all its variables in a JSON object
var itemOrderDetails = {
    // Catalog item sys_id
    'sysparm_id': '875e031c47a321004653609822a7fc9c', 
    'sysparm_quantity': '1',
    // Key-value pairs for all variable names and their desired values
    'variables': { 
        'access_level': 'admin',
        'application_name': 'jira',
        'approver_email': 'john.doe@example.com'
    }
};

// 3. Add item to the cart
var cartStatus = cart.addToCart(itemOrderDetails);

// 4. Checkout and submit the order
var checkoutResult = cart.checkoutCart();

// Log the result, which contains the Request number
if (checkoutResult && checkoutResult.request_number) {
    gs.info('Order successfully submitted. Request Number: ' + checkoutResult.request_number);
} else {
    gs.error('Failed to submit order: ' + JSON.stringify(checkoutResult));
}

💡 Data Handling: The CartJS methods return JSON objects, which makes parsing the response simple and efficient for tracking the resulting Request and RITM IDs.

Important Note on User Context

The scripts above, by default, will NOT automatically populate the Requested For and Opened By fields with a specific target user.

For scenarios where you need to order items on behalf of another user, additional logic is required. You can achieve this by:

1. Setting the User: Manually update the sc_request and sc_req_item records after placeOrder() is called, setting the requested_for and opened_by fields to the desired user’s sys_id.
2. Using runAs: For Scoped applications, you may use methods to impersonate or run the script under a different user context, though this requires careful implementation and permissions.