Interagir avec les données de table dans une ServiceNow instance

Le Mobile SDK vous permet d’interagir avec les données dans les tables qui résident sur votre ServiceNow instance. Vous pouvez interagir avec ces données via l’API deServiceNow table REST à l’aide de l’API NowTableService() qui appelle directement l’interface REST, ou via l’API NowGraphQLService() qui exécute une requête GraphQL spécifiée sur l’API GraphQL REST.

Si vous souhaitez renvoyer des données à partir de plusieurs tables au sein d’un seul appel, vous devez utiliser l’API NowGraphQLService(). Si vous devez interagir avec d’autres ServiceNow API REST, reportez-vous à la section Interagir avec l’API REST publique sur une ServiceNow instance.

Utilisation de NowGraphQLService pour interagir avec ServiceNow les tables

La classe NowGraphQLService fournit des méthodes qui vous permettent de construire et d’exécuter des requêtes GraphQL sur une table spécifiée au sein de votre ServiceNow instance si l’utilisateur connecté dispose de l’autorisation appropriée. Vous pouvez définir toutes les opérations CRUD dans votre requête GraphQL.

NowGraphQLService prend en charge l’extraction des résultats d’une requête en renvoyant un gestionnaire de complétion :

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

Via async/await :

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

Ou, un éditeur Combine (qui est actuellement déconseillé) :

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

L’exemple suivant montre comment importer le cadre de travail NowData, puis initialiser un objet NowGraphQLService que vous pouvez ensuite utiliser pour interagir avec les tables de votre ServiceNow instance.

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

Cet exemple montre comment créer une fonction asynchrone qui récupère et publie les articles de la base de connaissances les plus récemment publiés.

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

Utilisation de NowTableService pour interagir avec ServiceNow les tables

La classe NowTableService fournit des méthodes pour effectuer des opérations CRUD sur les enregistrements dans les tables qui résident sur votre ServiceNow instance. Grâce à cette interface, vous pouvez accéder directement à n’importe quel enregistrement de n’importe quelle ServiceNow table pour laquelle l’utilisateur connecté est autorisé. NowTableService prend en charge la remontée pas à pas pour les champs de référence. Par exemple, si une table contient une référence à la table Utilisateur, la valeur de remontée pas à pas user.name renvoie le nom de l’utilisateur.

Lors du renvoi des données demandées, toutes les listes de contrôle d’accès (ACL) applicables sont appliquées aux données, ce qui peut entraîner moins de résultats que prévu ou des erreurs d’autorisation si l’utilisateur authentifié ne dispose pas des droits d’accès à la table spécifiée.

La plupart des méthodes NowTableService fournissent trois implémentations pour renvoyer les données de résultats. Une qui utilise async/await, une qui appelle un gestionnaire de complétion avec une Result énumération et une qui renvoie un éditeur Combine , qui est actuellement déconseillé.

Par exemple, toutes les méthodes createRecord() insèrent un enregistrement construit dans une table spécifiée, cependant, la méthode

NowTableService : createRecord(avec champs : [FieldName : FieldValue], dans tableName : String, writeOptions : FieldWriteOptions, configuration : FieldReadConfiguration, complétion : @escaping (Result<Data, NowDataError>)

appelle un gestionnaire de complétion avec une Result énumération (le cas .success contient les résultats comme valeur associée).

Le champ

NowTableService : createRecord(avec les champs : [FieldName : FieldValue], dans tableName : String, writeOptions : FieldWriteOptions ? = nil, configuration : FieldReadConfiguration ? = nil) Levées asynchrones

exécute une fonction asynchrone/en attente. Alors que l'

NowTableService : createRecord(avec les champs : [FieldName : FieldValue], dans tableName : String, writeOptions : FieldWriteOptions ? = nil, configuration : FieldReadConfiguration ? = nil)

renvoie un éditeur Combine, mais est actuellement déconseillée.

En outre, NowTableService fournit deux implémentations différentes des méthodes CRUD, l’une qui renvoie des données brutes et l’autre qui renvoie des modèles codables. Par exemple, les méthodes update() et updateRecord() mettent à jour un enregistrement spécifié dans une table spécifiée, mais les méthodes update() renvoient un modèle codable et les méthodes updateRecord() renvoient des données brutes. Dans certains cas, les méthodes codables peuvent être préférables, car une structure codable fortement typée offre plus de flexibilité qu’une collection de champs de données brutes.

L’exemple suivant montre comment importer le cadre de travail NowData , puis initialiser un objet NowTableService que vous pouvez ensuite utiliser pour interagir avec ServiceNow les tables d’instance.

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

Pour obtenir des exemples de code supplémentaires utilisant les méthodes NowTableService disponibles, consultez la documentation relative à l’API Classe NowTableService : iOS .