Interagir com dados da tabela em uma instância ServiceNow

O Mobile SDK permite que você interaja com dados em tabelas que residem em sua instância ServiceNow. Você pode interagir com esses dados por meio da ServiceNow REST Table API usando a NowTableService() API que chama diretamente a interface REST ou por meio da NowGraphQLService() API que executa uma consulta GraphQL especificada em relação à REST GraphQL API.

Se você quiser retornar dados de várias tabelas em uma única chamada, precisará usar a API NowGraphQLService(). Se você precisar interagir com outras ServiceNow REST APIs, consulte Interagir com a REST API pública em uma instância ServiceNow.

Usando NowGraphQLService para interagir com ServiceNow tabelas

A classe NowGraphQLService fornece métodos que permitem construir e executar consultas GraphQL em uma tabela especificada dentro de sua instância ServiceNow se o usuário conectado tiver a autorização apropriada. Você pode definir todas as operações CRUD em sua consulta GraphQL.

O NowGraphQLService oferece suporte à busca de resultados para uma consulta retornando um manipulador de conclusão:

func execute(_ query: GraphQLQuery, completion: @escaping (Result<Data, NowDataError>) → Void)

Por meio de assíncrono/aguardar:

func execute(_ query: GraphQLQuery) async throws -> Data

Ou um fornecedor Combine (que está obsoleto no momento):

func publisher(for query: GraphQlQuery) → AnyPublisher<Data, NowDataError>

O exemplo a seguir mostra como importar a estrutura NowData e inicializar um objeto NowGraphQLService que você pode usar para interagir com tabelas em sua instância ServiceNow.

// 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
    }
  }
}

Este exemplo mostra como criar uma função assíncrona que busca e publica os artigos da base de conhecimento publicados mais recentemente.

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
        }
      }
    }
  }
}
"""

Usando NowTableService para interagir com ServiceNow tabelas

A classe NowTableService fornece métodos para executar operações CRUD nos registros em tabelas que residem em sua instância ServiceNow. Por meio dessa interface, é possível acessar diretamente qualquer um dos registros em qualquer tabela ServiceNow para a qual o usuário conectado esteja autorizado. O NowTableService oferece suporte à referência com pontos para campos de referência. Por exemplo, se uma tabela contiver uma referência à tabela Usuário, o valor de referência com pontos user.name retornará o nome do usuário.

Ao retornar os dados solicitados, todas as ACLs (Access Control Lists, listas de controle de acesso) aplicáveis são aplicadas aos dados, o que pode resultar em menos resultados do que o esperado ou em erros de autorização se o usuário autenticado não tiver direitos de acesso à tabela especificada.

A maioria dos métodos NowTableService fornece três implementações para retornar dados de resultados. Um que usa async/await, um que chama um manipulador de conclusão com uma enumeração Result e um que retorna um fornecedor Combine, que está obsoleto no momento.

Por exemplo, todos os métodos createRecord() inserem um registro construído em uma tabela especificada, no entanto, o

NowTableService - createRecord(com campos: [FieldName: FieldValue], em tableName: String, writeOptions: FieldWriteOptions, configuração: FieldReadConfiguration, conclusão: @escaping (Resultado<Data, NowDataError> )

O método chama um manipulador de conclusão com uma enumeração Result (o caso .success contém os resultados como seu valor associado).

O

NowTableService - createRecord (com campos: [FieldName: FieldValue], em tableName: cadeia de caracteres, writeOptions: FieldWriteOptions? = nil, configuração: FieldReadConfiguration? = nil) lançamentos assíncronos

O método executa uma função assíncrona/em espera. Enquanto o

NowTableService - createRecord(com campos: [FieldName: FieldValue], em tableName: String, writeOptions: FieldWriteOptions? = nil, configuração: FieldReadConfiguration? = nil)

O método retorna um fornecedor Combine, mas está obsoleto no momento.

Além disso, o NowTableService fornece duas implementações diferentes de métodos CRUD, uma que retorna dados brutos e uma que retorna modelos codáveis. Por exemplo, os métodos update () e updateRecord() atualizam um registro especificado em uma tabela especificada, mas os métodos update() retornam um modelo Codable e os métodos updateRecord() retornam dados brutos. Em alguns casos, os métodos Codáveis podem ser preferenciais, já que uma estrutura Codável fortemente digitada oferece mais flexibilidade do que uma coleção de campos de dados brutos.

O exemplo a seguir mostra como importar a estrutura NowData e inicializar um objeto NowTableService que você pode usar para interagir com ServiceNow tabelas de instância.

// 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)")
  }
}

Para obter exemplos de código adicionais usando os métodos NowTableService disponíveis, consulte a Classe NowTableService - iOS documentação da API.