LeadAPIProcessUtilOOB - Scoped

  • Release version: Yokohama
  • Updated January 30, 2025
  • 5 minutes to read

    • The LeadAPIProcessUtilOOB script include provides methods that are called by the lead REST API to retrieve lead records and their associated lead line item records.

    If you want to customize how lead records are retrieved when the lead API methods are called, override the methods in this script include in the LeadAPIProcessUtil script include. The names of the methods that you are overriding in the LeadAPIProcessUtil script include must be the same as those in the LeadAPIProcessUtilOOB script include file.

    This API is provided within the sn_lead_mgmt_core namespace. To access the API, the Lead Management Data Model (sn_lead_mgmt_core) plugin must be activated on the instance, and the calling user must have the sn_lead_mgmt_core.lead_integrator role.

    For additional information on Lead Management, see Using Lead Management.

    LeadAPIProcessUtilOOB - processCreateLead (Object requestBody)

    Processes the request body and creates a lead and all its associated line items, based on the passed parameters.

    Records are inserted in the following tables:
    • Lead [sn_lead_mgmt_core_lead]
    • Lead Line Item [sn_lead_mgmt_core_lead_line_item]
    Table 1. Parameters
    Name Type Description
    requestBody Object Request body of the lead and its related lead line items to create.

    For details on the contents of this object, see lead - POST /sn_lead_mgmt_core/lead.
    Table 2. Returns
    Type Description
    JSON object Details of the saved lead and lead line item records.

    Data type: Object

    {
  "body": {Object},
  "status": "String"
}
    <JSONobject>.body Response body.

    Successful response: All fields within the requested lead record and all fields in the associated lead line item records. For a description of the fields returned, refer to lead - POST /sn_lead_mgmt_core/lead.

    Error response: List of errors detected when trying to process the request. These error messages are defined in the LeadAPIConstants script include.

    Data type: Object
    <JSONobject>.status Response status code.

    These status codes are defined in the LeadAPIConstants script include.

    Data type: String

    The following code example shows where to add your custom code for the processCreateLead() method in the LeadAPIProcessUtil script include.

    var LeadAPIProcessUtil = Class.create(); 

LeadAPIProcessUtil.prototype = Object.extendsObject(LeadAPIProcessUtilOOB, { 

// Define overriding functions here 

processCreateLead: function(requestBody) { 
// Add your custom code 
}, 

type: 'LeadAPIProcessUtil' 

});

    LeadAPIProcessUtilOOB - processGetAllLeads (Object queryParams, String requestUrl)

    Retrieves all lead records and associated line item records based on the passed-in filter criteria. This method returns all fields within the associated records.

    Record details are fetched from the following tables:
    • Lead [sn_lead_mgmt_core_lead]
    • Lead Line Item [sn_lead_mgmt_core_lead_line_item]
    Table 3. Parameters
    Name Type Description
    queryParams Object Object containing the query parameters to apply when retrieving the lead records. These are the query parameters passed in the lead - GET /sn_lead_mgmt_core/lead endpoint.
    For example: 
    {
  "sysparm_fields":["first_name,last_name,sys_id,lead_line_items"],
  "sysparm_query":["lead_type=new_business"],
  "sysparm_offset":["2"],"sysparm_limit":["25"]
}
    requestUrl String Request URL. Pass this URL when you are processing a paginated response so that the method has the links to all of the pages in the response.
    Table 4. Returns
    Type Description
    JSON object Details of the requested lead and lead line item records.

    Data type: Object

    {
  "body": [Array],
  "contentRange": "String",
  "links": "String", 
  "status": "String",
  "totalCount": "Number" 
}

    If an errors occur while processing the request, the JSON object only contains the body and status parameters.
    <JSONobject>.body Response body.

    Successful response: An array of objects with each object containing a lead record and all associated lead line item records. All fields within the requested lead record and all fields in the associated lead line item records are returned. For a description of the fields returned, refer to lead - GET /sn_lead_mgmt_core/lead.

    Error response: List of errors detected when trying to process the request. These error messages are defined in the LeadAPIConstants script include.

    Data type: Array of Objects
    <JSONobject>.contentRange Range of the content returned in a paginated call.

    For example: If offset=2 and limit=3, the value of this parameter is items 3-5.

    Data type: String
    <JSONobject>.links In the case of a paginated response, comma-separated links to each page contained in the response.
    For example:
    <https://servicenow-instance/api/sn_lead_mgmt_core/lead?sysparm_offset=0&sysparm_limit=20>;rel="self",
<https://servicenow-instance/api/sn_lead_mgmt_core/lead?sysparm_offset=20&sysparm_limit=20>;rel="last",
<https://servicenow-instance/api/sn_lead_mgmt_core/lead?sysparm_offset=20&sysparm_limit=20>;rel="next"

    Data type: String
    <JSONobject>.status Response status code.

    These status codes are defined in the LeadAPIConstants script include.

    Data type: String
    <JSONobject>.totalCount Total number of lead records returned by the method.

    Data type: Number (Integer)

    The following code example shows where to add your custom code for the processGetAllLeads() method in the LeadAPIProcessUtil script include.

    var LeadAPIProcessUtil = Class.create(); 

LeadAPIProcessUtil.prototype = Object.extendsObject(LeadAPIProcessUtilOOB, { 

// Define overriding functions here 

processGetAllLeads: function(queryParams, requestUrl) { 
// Add your custom code here 
}, 

type: 'LeadAPIProcessUtil' 
});

    LeadAPIProcessUtilOOB - processGetLeadById (String id)

    Retrieves the specified lead record and its associated line item records. This method returns all fields within the associated records.

    Record details are fetched from the following tables:
    • Lead [sn_lead_mgmt_core_lead]
    • Lead Line Item [sn_lead_mgmt_core_lead_line_item]
    Table 5. Parameters
    Name Type Description
    id String Sys_id of the lead record to retrieve.

    Table: Lead [sn_lead_mgmt_core_lead]
    Table 6. Returns
    Type Description
    JSON object Details of the requested lead and lead line item records.

    Data type: Object

    {
  "body": {Object},
  "status": "String"
}
    <JSONobject>.body Response body.

    Successful response: All fields within the requested lead record and all fields in the associated lead line item records. For a description of the fields returned, refer to lead - GET /sn_lead_mgmt_core/lead/{sys_id}.

    Error response: List of errors detected when trying to process the request. These error messages are defined in the LeadAPIConstants script include.

    Data type: Object
    <JSONobject>.status Response status code.

    These status codes are defined in the LeadAPIConstants script include.

    Data type: String

    The following code example shows where to add your custom code for the processGetLeadById() method in the LeadAPIProcessUtil script include.

    var LeadAPIProcessUtil = Class.create(); 

LeadAPIProcessUtil.prototype = Object.extendsObject(LeadAPIProcessUtilOOB, { 

// Define overriding functions here

processGetLeadById: function(id) { 
  // Add your custom code here
}, 

type: 'LeadAPIProcessUtil' 

});

    LeadAPIProcessUtilOOB - processUpdateLead (Object requestBody, String id)

    Processes the request body and updates the specified lead and all its associated line items, based on the passed parameters.

    Records are updated in the following tables:
    • Lead [sn_lead_mgmt_core_lead]
    • Lead Line Item [sn_lead_mgmt_core_lead_line_item]
    Table 7. Parameters
    Name Type Description
    requestBody Object Request body of the lead and its related lead line item fields to update.

    For details on the contents of this object, see lead - PATCH /sn_lead_mgmt_core/lead/{sys_id}.
    id String Sys_id of the lead record to update.

    Table: Lead [sn_lead_mgmt_core_lead]
    Table 8. Returns
    Type Description
    JSON object Details of the saved lead and lead line item records.

    Data type: Object

    {
  "body": {Object},
  "status": "String"
}
    <JSONobject>.body Response body.

    Successful response: All fields of the updated lead record and all fields in the associated lead line item records (updated or not). For a description of the fields returned, refer to lead - PATCH /sn_lead_mgmt_core/lead/{sys_id}.

    Error response: List of errors detected when trying to process the request. These error messages are defined in the LeadAPIConstants script include.

    Data type: Object
    <JSONobject>.status Response status code.

    These status codes are defined in the LeadAPIConstants script include.

    Data type: String

    The following code example shows where to add your custom code for the processUpdateLead() method in the LeadAPIProcessUtil script include.

    var LeadAPIProcessUtil = Class.create();

LeadAPIProcessUtil.prototype = Object.extendsObject(LeadAPIProcessUtilOOB, {

// Define overriding functions here 

processUpdateLead: function(requestBody, id) { 
// Add your custom code here
},

type: 'LeadAPIProcessUtil' 

});