Action parameters

  • Release version: Xanadu
  • Updated August 1, 2024
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Action parameters

    Action parameters in ServiceNow are distinct from data parameters and specify the action to perform when a JSON object parameter is included in an HTTP GET or POST request. These parameters can be included as fields within the JSON object and enable triggering specific API actions or filtering query/update results effectively.

    Show full answer Show less

    Key Features

    • sysparmaction: Defines the action the API performs. Actions include:
      • getKeys: Queries a table and returns a comma-separated list of sysid values matching the encoded query.
      • getRecords: Retrieves all records and fields matching an encoded query.
      • get: Retrieves a single record by specifying sysid.
      • insert: Creates one or more new records.
      • insertMultiple: Creates multiple new records.
      • update: Updates existing records filtered by an encoded query.
      • deleteRecord: Deletes a single record by sysid.
      • deleteMultiple: Deletes multiple records filtered by an encoded query.
    • sysparmquery: Specifies an encoded query string to filter get, getRecords, update, or deleteMultiple actions.
    • sysparmview: Customizes returned fields by specifying a form view for get and getRecords calls. If the view is invalid or not provided, all active dictionary fields are returned.
    • sysparmsysid: Targets a specific record by sysid for get or delete actions.
    • sysparmrecordcount: Limits the number of records retrieved, capped by system property glide.processor.json.rowlimit.
    • displayvalue: Controls whether reference fields return display values or sysids:
      • true: Return display values only.
      • false: Return sysids only (default).
      • all: Return both display values and sysids.
    • displayvariables: Set to true in get or getRecords calls to retrieve all variables attached to the record.

    Practical Use for ServiceNow Customers

    ServiceNow customers can leverage action parameters to precisely control API behavior for data retrieval and modification. This enables efficient querying, creation, updating, and deletion of records using REST calls tailored by encoded queries, views, and display preferences. By using parameters like sysparmaction and sysparmquery, customers can automate and streamline data operations while controlling the volume and format of returned data to optimize performance and integration scenarios.

    Action parameters are separate and different from data parameters because they specify the action to take when the JSON object parameter is part of an HTTP GET or POST request.

    The parameters can also be specified as a field in the supplied JSON object. They have the effect of triggering an action in the case of sysparm_action, or filtering the results of an update or query in the case of sysparm_query.

    sysparm_action

    The following are the valid values for sysparm_action and the corresponding action triggered by the API.
    Table 1. Data Retrieval
    Method Summary Description
    getKeys Query the targeted table using an encoded query string and return a comma delimited list of sys_id values.
    getRecords Query the targeted table using an encoded query string and return all matching records and their fields.
    get Query a single record from the targeted table by specifying the sys_id in the sysparm_sys_id URL parameter, and return the record and its fields.
    Table 2. Data Modification
    Method Summary Description
    insert Create one or more new records for the table targeted in the URL.
    insertMultiple Create multiple new records for the table targeted in the URL.
    update Update existing records in the targeted table in the URL, filtered by an encoded query string.
    deleteRecord Delete a record from the table targeted in the URL by specifying its sys_id in the sysparm_sys_id URL parameter.
    deleteMultiple Delete multiple records from the table targeted in the URL, filtered by an encoded query string.

    sysparm_query

    Specify an encoded query string to be used in get, getRecords, update or deleteMultiplesysparm_action value.

    sysparm_view

    Specify a form view to customize the return values for get and getRecords function calls. When using a view, the query returns only the fields defined in the view, including referenced values. If there is no view name, or if the view name is not valid, then the query returns all field names that are marked active in the dictionary.

    sysparm_sys_id

    Specify a target sys_id during a get or delete function call (sysparm_action value).

    sysparm_record_count

    Specify an integer value to limit the number of records retrieved for this request. Note that this value is capped by the glide.processor.json.row_limit system property.

    displayvalue

    Get the display value of a reference field, if any are in the record. For example, the Incident record can have an assigned_to field that is a reference to a user record. Instead of sending the sys_id of the user record, the user name is sent.

    The displayvalue parameter can have three values: true, false, or all.
    • true: All the references fields show the display value instead of sys_id.
    • false (default): All reference fields show sys_ids.
    • all: The display value and the sys_id are shown. For example, the assignedto field in the Incident record is sent back as assigned_to:1234556, dv_assigned_to:Fred Luddy.

    displayvariables

    Set this boolean value to true during a get or getRecords function call to retrieve all variables attached to this record.