Créer une activité JDBC

Créez une activité JDBC personnalisée pour automatiser les commandes SQL et les appels de procédure stockée vers des 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 Yokohama. Pour savoir comment configurer 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 instance à partir d’une ServiceNow source de données externe, utilisez les concepts clés des jeux d’importation. 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 avoir l’autorisation pour la base de données cible et la 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 base de données cible (s’il est différent du numéro de port standard) Nom de l’instance de base de données
   Information 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 afficher créer décrire Par mesure de sécurité supplémentaire, une propriété de Serveur MID contrôle les opérations exécutées par cette sonde JDBCOrchestration, ce qui limite les commandes SQL utilisées. Cette propriété protège contre les commandes potentiellement destructrices, telles que la base de données de suppression. La mid.property.jdbc_operations contient les contrôles de propriété du 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 simultanément, mais vous pouvez exécuter deux instructions insert. Toutefois, vous ne pouvez pas exécuter plusieurs instructions de sélection 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 il peut être modifié pour cette activité.
   Délai 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 il peut être modifié pour cette activité.
   Capacités 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 la fonction JDBC.
   Utiliser la procédure stockée	Si cette option est activée, vous pouvez exécuter une procédure stockée sur les bases de données MySQL, Oracle ou SQL Server en entrant 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 . Voir variables de sortie de mappage automatique.

Que faire ensuite

• Tester les entrées d’activité JDBC
• Utilisez 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 JDBC Orchestration 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 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, SQL Server 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 du concepteur d’activité et prennent en charge le stockage des informations d’identification externes, telles 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 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 de requête	Tout	Temps écoulé maximal pendant lequel la requête JDBC est autorisée à s’exécuter sans réponse.
   Délai de connexion	Tout	Temps écoulé maximal de l’activité JDBC pendant la tentative de connexion à la base de données cible.
   Demande	Tout	Périmètre de cette table. Par défaut, la table Connexion JDBC [jdbc_connection] s’exécute dans le périmètre Global .
   Domaine	Tout	Domaine pour 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. Par défaut, les choix possibles sont les suivants : MySQL Oracle SQL Server Aucun Vous pouvez ajouter Sybase ou DB2 Universal à la liste de choix en téléchargeant le fichier JAR du pilote JDBC approprié sur 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	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 manuellement l’URL de connexion afin que le serveur MID sache comment établir la connexion.
   Pilote JDBC	Aucun, DB2 Universal, 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 entrer le nom du pilote dans ce champ et télécharger le fichier JAR du pilote sur 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 : admin

Procédure

1. Dans le formulaire du modèle de fournisseur JDBC, sélectionnez l’onglet Entrées .
2. Cliquez sur Activité de test 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 exécute ces valeurs par rapport à la cible spécifiée et renvoie la charge utile résultante. 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é, et cliquez sur OK pour afficher la charge utile.
   L’ensemble de la charge utile apparaît dans l’onglet Sortie brute du formulaire de réponse.

   

4. Sélectionnez l’une de ces options de mappage automatique.
   • Mappage automatique vers local : mappe directement les valeurs à une variable locale à utiliser dans l’activité.
   • Mappage automatique vers 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 les bases de données MySQL, Oracle et MS-SQL.

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

• Un seul ensemble de résultats est renvoyé.
• L’ordre des types de données d’entrée et de sortie dans les paramètres de 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

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

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

  hh :mm :ss[.sss] est le format pris en charge. La précision se situe en millisecondes uniquement, les microsecondes ou 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]

  Le format pris en charge est le format pris en charge AAAA-MM-JJ HH :MM :SS[.FFFFFF]. La précision est à la microseconde.

• ResultSet est le premier jeu de résultats renvoyé du 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é, vous définissez la valeur 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 ENTRER
Sql Type	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 SMALLINT STRUCT HEURE HORODATAGE MINUSCULE VARBINARY VARCHAR
Nom/valeur	Paires nom-valeur à transmettre à l’hôte. Vous pouvez créer ces paramètres manuellement ou glisser-déposer des variables d’entrée dans les champs de paramètre et attribuer une valeur.

Remarque :

Tous les fournisseurs de bases de données ne prennent pas en charge l’ensemble du domaine des types de données JDBC. Consultez votre manuel de référence de 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 aux champs du 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 sur les scripts de prétraitement ou de post-traitement Il n’est pas nécessaire de consulter 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 des données, vous pouvez tester les variables d’entrée. Vous pouvez effectuer des tests à partir de n’importe quelle étape du concepteur d’activité. En règle générale, l’étape de commande d’exécution est le point auquel vos entrées sont prêtes pour le test.

Procédure

1. Dans 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, celles-ci s’affichent 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 de test 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. Il s’agit de 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’est affectée.
3. Réinitialisez les valeurs selon vos besoins.
   • 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 des variables d’entrée, même si des valeurs par défaut existent.
4. Lorsque vos valeurs de test sont configurées correctement, 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 résultante. Les boutons du formulaire de réponse affichent différentes vues de la charge utile. L’ensemble de la charge utile apparaît 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.