Créer une activité JDBC

Créez une activité JDBC personnalisée pour automatiser les commandes SQL et les appels de procédures stockées aux bases de données relationnelles à partir du workflow.

Avant de commencer

Rôle requis : activity_admin, activity_creator

Pourquoi et quand exécuter cette tâche

Le modèle d’activité JDBC vous permet d’exécuter des instructions SQL ANSI ou des procédures stockées sur une base de données cible. La prise en charge des procédures stockées avec les paramètres IN, OUT et INOUT est disponible dans Xanadu. Pour en savoir plus sur la configuration de ces paramètres, reportez-vous à la section Paramètres de procédure stockée JDBC.

Remarque :

Si vous transférez des données en bloc dans une ServiceNow instance à partir d’une source de données externe, utilisez les concepts clés des ensembles de données à importer. Les activités JDBC vous permettent de transférer des données entre des sources de données externes et ServiceNow au sein d’un workflow. Il n’est pas destiné à remplacer les fonctionnalités d’importation en bloc des sources de données.

Procédure

1. Créez ou vérifiez vos informations d’identification JDBC.
   Vos informations d’identification JDBC doivent disposer d’une autorisation pour la base de données cible et d’une configuration appropriée pour la connexion JDBC correspondante. Les informations d’identification doivent être configurées avant de pouvoir créer une activité JDBC.
2. Créez ou vérifiez votre connexion JDBC.
   Votre connexion JDBC doit être configurée avec des informations d’identification JDBC valides avant de pouvoir créer une activité JDBC.
3. Créez une activité personnalisée.
   Cette action crée une activité personnalisée à l’aide d’un modèle.
4. Après avoir configuré les propriétés générales et créé des variables d’entrée, configurez la commande d’exécution JDBC.

   Option	Description
   Connexion JDBC	Configurez ou référencez la connexion JDBC appropriée pour la base de données. La connexion sélectionnée fournit à l’activité les informations suivantes : Informations sur la base de données cible (noms du serveur et de la base de données) URL de connexion Port de la base de données cible (s’il est différent du numéro de port standard) Nom d’instance de base de données
   Informations d'identification	Informations d’identification JDBC à utiliser pour votre connexion JDBC.
   Requête SQL	Entrez le SQL ANSI à exécuter sur la base de données cible JDBC. Remarque : Ce champ est masqué lorsque la case Procédure stockée est cochée. Vous pouvez mapper les variables d’entrée que vous avez créées pour configurer les instructions SQL. Par défaut, vous pouvez exécuter les instructions SQL suivantes. sélectionner insérer mettre à jour supprimer show créer décrire Pour des mesures de sécurité supplémentaires, une propriété de Serveur MID contrôle les opérations exécutées par cette sonde JDBCOrchestrationProbe, ce qui restreint les commandes SQL utilisées. Cette propriété protège contre les commandes potentiellement destructrices, telles que drop database. Le mid.property.jdbc_operations contient les contrôles de propriété de Serveur MID. Remarque : Vous ne pouvez pas exécuter plusieurs instructions de types différents. Par exemple, vous ne pouvez pas exécuter une instruction select et une instruction update ensemble, mais vous pouvez exécuter deux instructions insert. Toutefois, vous ne pouvez pas exécuter plusieurs instructions Selected dans cette activité.
   Nombre maximal de lignes	Nombre maximal d’enregistrements à extraire de la base de données. La valeur par défaut est 1 000.
   Taille maximale de la charge utile (Ko)	Vous pouvez définir une limite sur la taille maximale de la charge utile des données extraites de la base de données. La valeur par défaut est de 64 kilo-octets.
   Délai de connexion	Durée d’attente de l’activité avant d’établir la connexion. Ce champ est renseigné automatiquement à partir de la source de données, mais peut être modifié pour cette activité.
   Délai d'expiration de requête	Temps d’attente écoulé après l’exécution de la requête jusqu’à ce que les données soient renvoyées. Ce champ est renseigné automatiquement à partir de la source de données, mais peut être modifié pour cette activité.
   Options de Serveur MID requises	Serveur MID à utiliser pour interroger JDBC, par options. Par défaut, le système sélectionne un Serveur MID doté de l’aptitude JDBC.
   Utiliser la procédure stockée	Si cette option est cochée, vous pouvez exécuter une procédure stockée sur des bases de données MySQL, Oracle ou SQL Server en saisissant le nom et les paramètres de la procédure. Consultez Paramètres de procédure stockée JDBC.

   Remarque :

   Vous pouvez mapper automatiquement les valeurs des paramètres d’une charge utile de test aux variables de l’onglet Sorties . Reportez-vous à la section Variables de sortie de mappage automatique.

Que faire ensuite

• Tester les entrées d’activité JDBC
• Utiliser le mappage automatique pour générer des sorties et des règles d’analyse (recommandé pour JDBC)
• Si vous n’utilisez pas le mappage automatique, vous pouvez créer manuellement des variables de sortie et créer des règles d’analyse

Tâches associées

• Créer des activités personnalisées à l’aide de modèles de concepteur d’activité personnalisés

Créer une connexion JDBC pour une Orchestration activité

La table Connexion JDBC [jdbc_connection] fournit les informations que les activités d’orchestration JDBC personnalisées utilisent pour se connecter à diverses bases de données cibles.

Avant de commencer

Vous devez disposer d’un fichier JAR approprié, qu’il soit fourni avec l’instance ou d’un fichier JAR personnalisé.

Remarque :

L’instance ServiceNow fournit des fichiers mysql-connector-java-5.1.21.jar, sql-server-jdbc-4.0.jar et ojdbc6.jar dans le cadre de la version actuelle, qui prend en charge les bases de données MySQL, SQLServer et Oracle. D’autres bases de données, telles que Sybase ou DB2 Universal, doivent utiliser un fichier JAR personnalisé qui doit être téléchargé sur l’instance avant de définir la connexion JDBC.

Rôle requis : activity_admin, activity_creator

Pourquoi et quand exécuter cette tâche

Informations d’identification JDBC Les informations d’identification JDBC sont récupérées séparément par le modèle de concepteur d’activité et prennent en charge le stockage des informations d’identification externe, tel que CyberArk.

Procédure

1. Accédez à la Tout > Orchestration > Informations d'identification et connexions > Connexions JDBC et cliquez sur Nouveau.
2. Remplissez le formulaire à l'aide des champs de la table.
   La sélection de base de données dans le champ Format détermine les champs qui sont disponibles.

   Tableau 1. Champs de connexion JDBC

   Champ	Format de base de données	Description
   Nom	Tout	Nom unique de cette connexion JDBC. Par exemple, vous pouvez entrer JDBC MySQLProd.
   Délai d'expiration de requête	Tout	Durée maximale écoulée pendant laquelle la requête JDBC est autorisée à s’exécuter sans réponse.
   Délai de connexion	Tout	Temps d’attente maximal écoulé pour l’activité JDBC lors de la tentative de connexion à la base de données cible.
   Application	Tout	Champ d’application de cette table. Par défaut, la table Connexion JDBC [jdbc_connection] s’exécute dans le champ d’application global .
   Domaine	Tout	Domaine de cette table. Par défaut, la table Connexion JDBC [jdbc_connection] s’exécute dans le domaine global .
   Format	Tout	Type de base de données pour cette connexion. Les choix par défaut sont les suivants : MySQL Oracle SQL Server Aucun Vous pouvez ajouter Sybase ou DB2 Universal à la liste de choix en chargeant le fichier JAR du pilote JDBC approprié dans l’instance. Orchestration reconnaît automatiquement ces pilotes lorsqu’ils sont chargés dans le système et les ajoute à cette liste.
   Serveur	Oracle, MySQL, SQL Server	Nom d’hôte ou adresse IP du serveur de base de données.
   SID Oracle	Oracle	L’identificateur de site de base de données Oracle. La valeur par défaut est orcl.
   Port Oracle	Oracle	Port utilisé par la base de données Oracle. La valeur par défaut est 1521.
   Nom de base de données	MySQL, SQL Server	Nom de la base de données.
   Port de la base de données	MySQL, SQL Server	Port utilisé par la base de données sélectionnée.
   Nom d'instance	SQL Server	Nom d’instance pour le SQL Server sélectionné
   URL de connexion	Tout	URL que le Serveur MID utilise pour se connecter à la base de données spécifiée. L’URL est créée automatiquement lorsque vous enregistrez le formulaire et est en lecture seule pour les bases de données par défaut. Remarque : Si le format sélectionné n’est pas l’une des bases de données par défaut, vous devez créer l’URL de connexion manuellement afin que le serveur MID sache comment créer la connexion.
   Pilote JDBC	Aucun, DB2 universel, Sybase	Pilote JDBC à utiliser pour cette connexion lorsqu’il ne s’agit pas d’une base de données par défaut. Remarque : Si vous ajoutez une base de données Sybase ou DB2 Universal, vous devez saisir le nom du pilote dans ce champ et charger le fichier JAR du pilote dans l’instance.

   Figure 1. Exemple de connexion JDBC à Oracle

   

3. Cliquez sur Envoyer.

Information associée

• Informations d’identification JDBC

Mapper automatiquement les variables de sortie d’activité JDBC

Le ServiceNow concepteur d’activité vous permet de mapper automatiquement les valeurs des paramètres d’une charge utile de test JDBC aux variables de l’onglet Sorties .

Avant de commencer

Rôle requis : administrateur

Procédure

1. Dans le formulaire du modèle de fournisseur JDBC, sélectionnez l’onglet Entrées .
2. Cliquez sur Tester l’activité pour tester les paramètres d’entrée.
   Si vous avez ajouté des valeurs réelles pour les paramètres et les champs, le système les compare à la cible spécifiée et renvoie la charge utile qui en résulte. Si vous avez mappé des variables d’entrée à des champs et des paramètres, le système affiche une boîte de dialogue permettant d’affecter des valeurs de test à ces variables.
3. Fournissez des valeurs de test, si demandé, puis cliquez sur OK pour afficher la charge utile.
   L’ensemble de la charge utile s’affiche dans l’onglet Sortie brute du formulaire de réponse.

   

4. Sélectionnez l’une de ces options de mappage automatique.
   • Mapper automatiquement au local : mappe directement les valeurs à une variable locale pour une utilisation dans l’activité.
   • Correspondance automatique avec la sortie : mappe directement les valeurs à la variable de sortie pour les transmettre à d’autres activités du workflow. Le mappage automatique à une variable de sortie crée un tableau d’objets, chacun contenant les noms de colonnes du résultat de la requête.

Paramètres de procédure stockée JDBC

Vous pouvez utiliser Orchestration pour exécuter une procédure stockée sur des bases de données MySQL, Oracle DB et MS-SQL.

Plusieurs types de données sont pris en charge, avec les limitations suivantes :

• Un seul jeu de résultats est renvoyé.
• L’ordre des types de données d’entrée et de sortie dans les paramètres de la procédure stockée doit correspondre à la définition de l’activité.
• Binary, Blob, Varbinary et LongBinary doivent être codés en base64.
• La date, l’heure et l’horodatage ont un format spécifique :

  Format de date : aaaa-mm-jj

  AAAA-MM-JJ est le format pris en charge.

  Format d’heure : hh :mm :ss[.sss]

  hh :mm :ss[.sss] est le format pris en charge. La précision n’est qu’en millisecondes, les microsecondes ou les nanosecondes ne peuvent pas être gérées.

  Remarque :

  10:30:59 et 10:30:59.999000 sont corrects, mais 10:30:59 est incorrect.

  Format d’horodatage : aaaa-mm-jj hh :mm :ss[.ffffff]

  aaaa-mm-jj hh :mm :ss[.ffffff] est le format pris en charge. La précision est de l’ordre de la microseconde.

• Le jeu de résultats est le premier ensemble de résultats renvoyé par le serveur de base de données.
• MS-SQL ne prend pas en charge les paramètres INOUT. Si vous utilisez des paramètres INOUT, le modèle d’activité les mappe de manière transparente aux paramètres OUT.

Remarque :

Si vous ne souhaitez pas effectuer de validation des types de données dans les paramètres de procédure stockée, comme le comportement hérité, définissez glide.stored_proc.data_type.validation sur false. Consultez les propriétés du serveur MID pour plus d’informations.

Tableau 2. Paramètres de procédure stockée

Champ	Description
Mode	Type de paramètre de procédure stockée. Paramètres pris en charge : DANS DEHORS SORTIE
Sql Type	Un type de données SQL. Types de données pris en charge : TABLEAU LE BIGINT BINAIRE MORS BLOB CARBONISER CLOB DATE DÉCIMAL DISTINCT DOUBLE FLOTTANT INT ENTIER JAVA_OBJECT LONGVARBINARY LONGVARCHAR NULL NUMÉRIQUE AUTRE RÉEL REF REF_CURSOR PETIT STRUCT HEURE HORODATAGE TINYINT VARBINARY VARCHAR
Nom/valeur	Paires nom-valeur à transmettre à l’hôte. Vous pouvez créer ces paramètres manuellement ou glisser-déplacer des variables d’entrée dans les champs de paramètres et affecter une valeur.

Remarque :

Tous les fournisseurs de bases de données ne prennent pas en charge l’ensemble des types de données JDBC. Reportez-vous au manuel de référence de votre base de données pour comprendre les types de données pris en charge pour votre installation.

Tester les entrées du modèle d’activité JDBC

Vous pouvez tester les paramètres d’entrée d’une activité JDBC personnalisée pendant son développement sans avoir à exécuter l’activité dans un contexte de workflow.

Avant de commencer

Créez des variables d’entrée et mappez-les à des champs dans le formulaire Commande d’exécution ou fournissez des valeurs réelles pour ces champs. Rôle requis : web_service_admin, activity_admin activity_creator

Pourquoi et quand exécuter cette tâche

Ce test exécute uniquement les paramètres d’entrée sur un point de terminaison et non les scripts de prétraitement ou de post-traitement. Il n’est pas nécessaire de vérifier l’activité pour la tester.

Remarque :

Si vous fournissez suffisamment d’informations pour qu’Orchestration contacte le point de terminaison ou l’hôte et renvoie les données, vous pouvez tester les variables d’entrée. Vous pouvez tester à partir de n’importe quelle étape dans le concepteur d’activité. En règle générale, l’étape Commande d’exécution est le point auquel vos entrées sont prêtes pour le test.

Procédure

1. À partir de la commande d’exécution JDBC, cliquez sur Tester les entrées.
   La liste des variables sources d’entrée s’affiche. Si vous avez ajouté des valeurs par défaut pour ces variables, ces valeurs apparaissent dans la colonne Valeur de substitution . Les variables obligatoires sont marquées d’une étoile rouge.

   Remarque :

   Le test échoue si le serveur MID est introuvable ou s’il ne peut pas se connecter à la cible.

   Figure 2. Valeurs des tests d’entrée JDBC

   

2. Filtrez la liste de variables avec ces contrôles :
   • Toutes les entrées : affiche toutes les variables d’entrée. Ce contrôle est la vue par défaut.
   • Entrées obligatoires : affiche uniquement les variables obligatoires.
   • Entrées sans valeur par défaut : affiche les variables d’entrée auxquelles aucune valeur par défaut n’a été affectée.
3. Réinitialisez les valeurs si nécessaire.
   • Réinitialiser les valeurs par défaut : si des valeurs sont présentes, ce contrôle remplace toutes les valeurs de test définies dans ce formulaire par les valeurs par défaut.
   • Effacer les valeurs : efface toutes les valeurs de la liste de variables d’entrée, même si des valeurs par défaut existent.
4. Lorsque vos valeurs de test sont correctement configurées, cliquez sur OK.
   Le système exécute les valeurs de toutes les entrées configurées par rapport à la cible spécifiée et renvoie la charge utile qui en résulte. Les boutons du formulaire de réponse affichent différentes vues de la charge utile. L’ensemble de la charge utile s’affiche dans la fenêtre Sortie brute .

   Figure 3. Charge utile de la réponse à partir du test d’entrées

   

5. Pour mapper automatiquement les valeurs de paramètres appropriées de la charge utile aux variables de l’étape Sorties , sélectionnez une option de mappage automatique.
6. Cliquez sur le X dans le coin supérieur droit de la fenêtre pour la fermer.