Interact with table data in a ServiceNow instance
Summarize
Summary of Interact with table data in a ServiceNow instance
The Mobile SDK enables ServiceNow customers to interact with data stored in their ServiceNow instance tables. This interaction is facilitated through two main APIs:NowTableService()for direct REST Table API calls andNowGraphQLService()for executing GraphQL queries via the REST GraphQL API. These APIs support authorized CRUD operations on records within ServiceNow tables, allowing flexible and secure data access and manipulation.
Show less
Using NowGraphQLService to Interact with Tables
The NowGraphQLService class allows customers to construct and execute GraphQL queries on specified tables. It supports all CRUD operations within a single query and can return data from multiple tables in one call. Query execution can be handled via completion handlers, async/await, or (deprecated) Combine publishers.
Typical usage includes initializing the service with the instance URL and then executing queries asynchronously to fetch or manipulate data, for example retrieving the most recently published knowledge base articles. Proper user authorization is required for query execution.
Using NowTableService to Interact with Tables
The NowTableService class offers comprehensive methods for CRUD operations on ServiceNow table records accessible to the logged-in user. It supports dot-walking on reference fields to access related table data and respects all Access Control Lists (ACLs) to enforce data security and authorization.
Results from CRUD methods can be obtained via async/await, completion handlers with result enumerations, or deprecated Combine publishers. The service supports two variations of methods: those returning raw data and those returning strongly typed Codable models, enabling customers to choose based on their data handling preferences.
For example, createRecord() inserts records with options to specify write and read configurations, and update() methods update records while optionally returning Codable models for type safety.
Initialization involves creating a NowTableService instance with the ServiceNow instance URL, handling success or failure asynchronously.
Practical Benefits for ServiceNow Customers
- Enable secure and authorized interaction with ServiceNow table data directly from mobile applications using REST or GraphQL APIs.
- Perform complex queries and CRUD operations efficiently, including multi-table data retrieval via GraphQL.
- Leverage async/await for modern asynchronous programming or use completion handlers for callback-based workflows.
- Choose between raw data or strongly typed Codable models to fit application data handling needs.
- Respect ServiceNow security via ACL enforcement automatically applied in data access.
Next Steps
ServiceNow customers should incorporate the NowData framework, initialize the appropriate service (NowGraphQLService or NowTableService) with their instance URL, and utilize the provided APIs for their application-specific data interactions. For detailed method references and code examples, customers can consult the NowTableService iOS API documentation.
The Mobile SDK enables you to interact with data in tables that reside on your ServiceNow instance. You can interact with this data through the ServiceNow REST Table API using the NowTableService() API that directly calls the REST interface, or through the NowGraphQLService() API that executes a specified GraphQL query against the REST GraphQL API.
If you want to return data from multiple tables within a single call, you will need to use the NowGraphQLService() API. If you need to interact with other ServiceNow REST APIs, see Interact with the public REST API on a ServiceNow instance.
Using NowGraphQLService to interact with ServiceNow tables
The NowGraphQLService class provides methods that enable you to construct and execute GraphQL queries on a specified table within your ServiceNow instance if the logged in user has the proper authorization. You can define all CRUD operations within your GraphQL query.
func execute(_ query: GraphQLQuery, completion: @escaping (Result<Data, NowDataError>) → Void)func execute(_ query: GraphQLQuery) async throws -> Datafunc publisher(for query: GraphQlQuery) → AnyPublisher<Data, NowDataError>
// Import the NowData framework
import NowData
// Initialize a NowGraphQLService
// The makeGraphQLService completion handler returns a result that wraps
// the NowGraphQLService upon success or error.
private func initializeGraphQLService(instanceUrl: URL) {
makeGraphQLService(instanceUrl: instanceUrl) { [weak self] result in
switch result {
case .success(let service):
self?.graphQLService = service
case .failure(let error):
debugPrint("Creating GraphQL service failed with error: \(error.localizedDescription)")
self?.graphQLService = nil
}
}
}private func fetchArticles() async throws -> [Article] {
guard let graphQLService = graphQLService else {
throw ArticleListError.invalidGraphQLService
}
do {
let data = try await graphQLService.execute(GraphQLQuery(query: recentlyPublishedQuery))
let articles = try dataToArticleList(data)
} catch let error as NowDataError {
throw ArticleListError.fetchError(error)
} catch {
throw error
}
}
private let recentlyPublishedQuery =
"""
{
GlideRecord_Query {
kb_knowledge(queryConditions: "active=true^ORDERBYpublishedDESC" pagination: { limit: 10, offset: 0 }) {
_results {
sys_id {
value
},
number {
displayValue
},
short_description {
displayValue
},
author {
displayValue
}
published {
displayValue
}
}
}
}
}
"""Using NowTableService to interact with ServiceNow tables
The NowTableService class provides methods to perform CRUD operations on the records in tables that reside on your ServiceNow instance. Through this interface you can directly access any of the records within any ServiceNow table for which the logged in user is authorized. NowTableService supports dot-walking for reference fields. For example, if a table contains a reference to the User table, the
dot-walked value user.name returns the name of the user.
When returning the requested data, all applicable Access Control Lists (ACLs) are applied to the data, which may result in fewer results than expected, or authorization errors if the authenticated user does not have access rights to the specified table.
Most NowTableService methods provide three implementations for returning results data. One that uses async/await, one that calls a completion handler with a Result enumeration, and one that returns a Combine publisher, which is currently deprecated.
For example, all createRecord() methods insert a constructed record into a specified table, however, the
method calls a completion handler with a Result enumeration (the .success case contains the results as its associated
value).
The
NowTableService - createRecord(with fields: [FieldName: FieldValue], in tableName: String, writeOptions: FieldWriteOptions? = nil, configuration: FieldReadConfiguration? = nil) async throwsmethod performs an async/await function. While the
method returns a Combine publisher, but is currently deprecated.
In addition, NowTableService provides two different implementations of CRUD methods, one that returns raw data, and one that returns Codable models. For example, both the update() and updateRecord() methods update a specified record in a specified table, but the update() methods return a Codable model and the updateRecord() methods return raw data. In some cases, Codable methods might be preferable, as a strongly typed Codable structure provides more flexibility than a collection of raw data fields.
// Import the NowData framework
import NowData
// Initialize a NowTableService
// The makeTableService completion handler returns a result that wraps
// the NowTableService upon success or error.
makeTableService(instanceUrl: instanceUrl) { [weak self] result in
guard let self = self else { return }
switch result {
case .success(let tableService):
debugPrint("Successfully created a table service \(tableService)")
self.tableService = tableService
case .failure(let error):
debugPrint("Creating table service failed with error: \(error.localizedDescription)")
}
}For additional code examples using the available NowTableService methods, refer to the NowTableService class - iOS
API documentation.