Understanding the GlideRecord_Mutation API in ServiceNow (Update)

Updating record explained

Prerequesite

Before you read this blog post, please check out Using GraphQL in ServiceNow in order to understand using introspection and GraphQL Explorer in servicenow.

The GraphQL Mutation (Update) Explained

In this post, we'll explore the GlideRecord_Mutation API in ServiceNow by dissecting a GraphQL mutation, its variables, and the resulting data. We'll also provide an example of how to perform this mutation via a REST API call from a Service Portal widget.

GraphQL mutations are operations that allow you to create, update, or delete data on the server. In ServiceNow, the GlideRecord_Mutation API provides a way to perform these operations on records in the database. Being an out-of-the-box (OOTB) feature, it allows developers to update records without writing any server-side code. This significantly simplifies the development process, enabling faster and more efficient application development within the platform.

Keep in mind that all ServiceNow GraphQL OOTB API adhere to ACL. Therefore, if you don't get the expected result, my suggestion would be to verify your ACLs.

Updating Mutation Syntax

mutation ($sys_id: String!, $short_description: String) {
  GlideRecord_Mutation {
    update_sn_hr_core_case(sys_id: $sys_id, short_description: $short_description) {
      _row_data {
        canWrite
        uniqueValue
        displayValue
        __typename
      }
      short_description {
        value
      }
    }
  }
}

Breakdown:

• mutation: Declares a mutation operation.
• ($sys_id: String!, $short_description: String): Defines variables for the mutation. The exclamation mark (!) after String indicates that sys_id is a required field.
• GlideRecord_Mutation: The root mutation type provided by ServiceNow.
• update_sn_hr_core_case: A specific mutation function to update a record in the sn_hr_core_case table.
• Parameters:
  • sys_id: The unique identifier of the record to update.
  • short_description: The field you want to update.
• Fields Requested:
  • _row_data: Metadata about the record.
    • canWrite: Indicates if the user has write permissions.
    • uniqueValue: The sys_id of the record.
    • displayValue: A human-readable identifier of the record.
    • __typename: The GraphQL type name.
  • short_description: The updated field.
    • value: The new value of short_description.

The Variables

The variables are the dynamic inputs to the mutation:

{
  "sys_id": "45ae83320b30220097432da0d5673a76",
  "short_description": "New Value Here..."
}

Explanation:

• sys_id: Specifies the record in the sn_hr_core_case table that you want to update.
• short_description: The new value to set for the short_description field.

The Result

After executing the mutation, you receive the following response:

{
  "data": {
    "GlideRecord_Mutation": {
      "update_sn_hr_core_case": {
        "_row_data": {
          "canWrite": true,
          "uniqueValue": "45ae83320b30220097432da0d5673a76",
          "displayValue": "HRC0000282",
          "__typename": "GlideRecord_RowDataType"
        },
        "short_description": {
          "value": "New Value Here..."
        }
      }
    }
  }
}

Breakdown:

• data.GlideRecord_Mutation.update_sn_hr_core_case: The path to the mutation result.
• _row_data:
  • canWrite: true, confirming you have permission to write to this record.
  • uniqueValue: The sys_id of the updated record.
  • displayValue: The display value of the record, such as a case number.
  • __typename: The GraphQL type, helpful for client-side queries.
• short_description.value: Confirms the short_description field was updated to "New Value Here...".

Visualize in GraphQL Explorer

Performing the Mutation from a Service Portal Widget

To execute this mutation from a ServiceNow Service Portal widget, you can use AngularJS's $http service to make a REST API call.

Example Code

function($scope, $http) {
  // Define the GraphQL mutation as a string
  var mutationQuery = `
    mutation ($sys_id: String!, $short_description: String) {
      GlideRecord_Mutation {
        update_sn_hr_core_case(sys_id: $sys_id, short_description: $short_description) {
          _row_data {
            canWrite
            uniqueValue
            displayValue
            __typename
          }
          short_description {
            value
          }
        }
      }
    }
  `;

  // Define the variables
  var variables = {
    sys_id: '45ae83320b30220097432da0d5673a76',
    short_description: 'New Value Here...'
  };

  // Configure the request
  var request = {
    method: 'POST',
    url: '/api/now/graphql',
    headers: {
      'Content-Type': 'application/json'
    },
    data: {
      query: mutationQuery,
      variables: variables
    }
  };

  // Execute the HTTP request
  $http(request).then(function(response) {
    // Success callback
    var result = response.data;
    console.log('Mutation successful:', result);

    // Update the scope or perform additional actions
    $scope.updatedRecord = result.data.GlideRecord_Mutation.update_sn_hr_core_case;
  }, function(error) {
    // Error callback
    console.error('Mutation failed:', error);
  });
}

Explanation:

• mutationQuery: The GraphQL mutation defined as a multi-line string.
• variables: The dynamic values passed into the mutation.
• $http(request): Sends a POST request to the GraphQL endpoint.
  • method: Specifies the HTTP method (POST).
  • url: The endpoint for GraphQL API in ServiceNow (/api/now/graphql).
  • headers: Sets the Content-Type to application/json.
  • data: Contains the query and variables for the mutation.
• Success Callback:
  • response.data: Contains the result from the server.
  • $scope.updatedRecord: Stores the updated record in the widget's scope for use in the UI.
• Error Callback:
  • Logs any errors to the console for debugging.

Conclusion

The GlideRecord_Mutation API in ServiceNow provides a powerful way to interact with records using GraphQL. By understanding the structure of mutations, variables, and responses, you can efficiently update records and integrate these operations into Service Portal widgets or other custom interfaces.