API du serveur Glide

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 14 minutes de lecture

    • ServiceNow fournit des API pour le serveur Glide.

    GlideAggregate (en anglais seulement)

    La classe GlideAggregate est une extension de GlideRecord et permet d’effectuer des requêtes d’agrégation de base de données (COUNT, SUM, MIN, MAX, AVG). Cela peut être utile pour créer des rapports personnalisés ou pour les calculs de champs calculés.

    Remarque :
    Cette fonctionnalité nécessite une connaissance de JavaScript.

    Pour plus d’informations, reportez-vous à l’API GlideAggregate .

    Exemples GlideAggregate

    GlideAggregate est une extension de GlideRecord et son utilisation est probablement mieux illustrée à travers une série d’exemples.

    Remarque :
    Cette fonctionnalité nécessite une connaissance de JavaScript.

    Voici un exemple qui permet d’obtenir simplement un décompte du nombre d’enregistrements dans une table :

    var count = new GlideAggregate('incident');
count.addAggregate('COUNT');
count.query();
var incidents = 0;
if(count.next()) 
   incidents = count.getAggregate('COUNT');

    Aucune requête n’est associée à l’exemple précédent. Si vous souhaitez obtenir un nombre d’incidents qui étaient ouverts, ajoutez simplement une requête comme cela se fait avec GlideRecord. Voici un exemple pour obtenir un décompte du nombre d’incidents actifs.

    var count = new GlideAggregate('incident');
count.addQuery('active','true');
count.addAggregate('COUNT');
count.query();
var incidents = 0;
if(count.next()) 
   incidents = count.getAggregate('COUNT');

    Pour obtenir un décompte de tous les incidents ouverts par catégorie, le code est le suivant :

    var count = new GlideAggregate('incident');
count.addQuery('active','true');
count.addAggregate('COUNT','category');
count.query();
while(count.next()){
  var category = count.category;
  var categoryCount = count.getAggregate('COUNT','category');
  gs.log("The are currently "+ categoryCount +" incidents with a category of "+ category);}

    Le résultat est :

     *** Script: The are currently 1.0 incidents with a category of Data  
       *** Script: The are currently 11.0 incidents with a category of Enhancement
       *** Script: The are currently 1.0 incidents with a category of Implementation
       *** Script: The are currently 197.0 incidents with a category of inquiry
       *** Script: The are currently 13.0 incidents with a category of Issue
       *** Script: The are currently 1.0 incidents with a category of 
       *** Script: The are currently 47.0 incidents with a category of request

    Voici un exemple qui utilise plusieurs agrégations pour voir combien de fois les enregistrements ont été modifiés à l’aide des valeurs MIN, MAX et AVG .

    var count = new GlideAggregate('incident');
count.addAggregate('MIN','sys_mod_count');
count.addAggregate('MAX','sys_mod_count');
count.addAggregate('AVG','sys_mod_count');
count.groupBy('category');
count.query();
while(count.next()){
  var min = count.getAggregate('MIN','sys_mod_count');
  var max = count.getAggregate('MAX','sys_mod_count');
  var avg = count.getAggregate('AVG','sys_mod_count');
  var category = count.category.getDisplayValue();
  gs.log(category +" Update counts: MIN = "+ min +" MAX = "+ max +" AVG = "+ avg);}

    Le résultat est :

           *** Script: Data Import Update counts: MIN = 4.0 MAX = 21.0 AVG = 9.3333
       *** Script: Enhancement Update counts: MIN = 1.0 MAX = 44.0 AVG = 9.6711
       *** Script: Implementation Update counts: MIN = 4.0 MAX = 8.0 AVG = 6.0
       *** Script: inquiry Update counts: MIN = 0.0 MAX = 60.0 AVG = 5.9715
       *** Script: Inquiry / Help Update counts: MIN = 1.0 MAX = 3.0 AVG = 2.0
       *** Script: Issue Update counts: MIN = 0.0 MAX = 63.0 AVG = 14.9459
       *** Script: Monitor Update counts: MIN = 0.0 MAX = 63.0 AVG = 3.6561
       *** Script: request Update counts: MIN = 0.0 MAX = 53.0 AVG = 5.0987

    Voici un exemple plus complexe qui montre comment comparer l’activité d’un mois à l’autre.

    var agg = new GlideAggregate('incident');
agg.addAggregate('count','category'); 
agg.orderByAggregate('count','category'); 
agg.orderBy('category'); 
agg.addQuery('opened_at','>=','javascript:gs.monthsAgoStart(2)'); 
agg.addQuery('opened_at','<=','javascript:gs.monthsAgoEnd(2)'); 
agg.query();
while(agg.next()){
  var category = agg.category;
  var count = agg.getAggregate('count','category');
  var query = agg.getQuery();
  var agg2 = new GlideAggregate('incident');   
  agg2.addAggregate('count','category');
  agg2.orderByAggregate('count','category');
  agg2.orderBy('category');
  agg2.addQuery('opened_at','>=','javascript:gs.monthsAgoStart(3)');
  agg2.addQuery('opened_at','<=','javascript:gs.monthsAgoEnd(3)');
  agg2.addEncodedQuery(query);
  agg2.query();
  var last ="";
  while(agg2.next()){
     last = agg2.getAggregate('count','category');}
  gs.log(category +": Last month:"+ count +" Previous Month:"+ last);
 
}

    Le résultat est :

     *** Script: Monitor: Last month:6866.0 Previous Month:4468.0
 *** Script: inquiry: Last month:142.0 Previous Month:177.0
 *** Script: request: Last month:105.0 Previous Month:26.0
 *** Script: Issue: Last month:8.0 Previous Month:7.0
 *** Script: Enhancement: Last month:5.0 Previous Month:5.0
 *** Script: Implementation: Last month:1.0 Previous Month:0

    Voici un exemple pour obtenir le nombre distinct d’un champ sur une requête de groupe.

    var agg = new GlideAggregate('incident');
agg.addAggregate('count');
agg.addAggregate('count(distinct','category');
agg.addQuery('opened_at', '>=', 'javascript:gs.monthsAgoStart(2)');
agg.addQuery('opened_at', '<=', 'javascript:gs.monthsAgoEnd(2)');
//
agg.groupBy('priority');
agg.query();
while (agg.next()) {
// Expected count of incidents and count of categories within each priority value (group)
  gs.info('Incidents in priority ' + agg.priority + ' = ' + agg.getAggregate('count') + 
            ' (' + agg.getAggregate('count(distinct','category') + ' categories)');
}

    Le résultat est :

    *** Script: Incidents in priority 1 = 13 (3 categories)
*** Script: Incidents in priority 2 = 10 (5 categories)
*** Script: Incidents in priority 3 = 5 (3 categories)
*** Script: Incidents in priority 4 = 22 (6 categories)
    Vous pouvez implémenter l’agrégat SUM avec ou sans l’utilisation de la méthode groupBy(). Si vous n’utilisez pas la méthode groupBy(), le résultat de la SOMME est la valeur cumulative pour chaque valeur différente du champ pour lequel vous demandez la SOMME. Par exemple, si vous ADDITIONNEZ le champ total_cost de la table Actif immobilisé et que la table Actif immobilisé contient 12 enregistrements au total :
    • Trois disques d’une total_cost de 12 $
    • Quatre disques d’une total_cost de 10 $
    • Cinq disques d’une total_cost de 5 $
    Lorsque vous ADDITIONNEZ l’ensemble d’enregistrements, la méthode getAggregate() renvoie trois sommes différentes : $36, $40 et $25.

    Le code suivant illustre l’implémentation de l’agrégat SUM sans utiliser la méthode groupBy() :

    var totalCostSum = new GlideAggregate('fixed_asset');
totalCostSum.addAggregate('SUM', 'total_cost');
totalCostSum.query();
 
while (totalCostSum.next()) {
  var allTotalCost = 0;
  allTotalCost = totalCostSum.getAggregate('SUM', 'total_cost');
  aTotalCost = totalCostSum.getValue('total_cost');
  gs.print('Unique field value: ' + aTotalCost + ', SUM = ' + allTotalCost + ', ' + allTotalCost/aTotalCost + ' records');
}

    La sortie de cet exemple est la suivante :

    *** Script: Unique field value: 12, SUM = 36, 3 records
*** Script: Unique field value: 10, SUM = 40, 4 records
*** Script: Unique field value: 5, SUM = 25, 5 records

    En utilisant les mêmes points de données que dans l’exemple précédent, si vous utilisez la méthode groupBy(), l’agrégat SUM renvoie la somme de toutes les valeurs du champ spécifié.

    L’exemple suivant illustre l’implémentation de l’agrégat SUM à l’aide de la méthode groupBy() :

    var totalCostSum = new GlideAggregate('fixed_asset');
totalCostSum.addAggregate('SUM', 'total_cost');
totalCostSum.groupBy('total_cost');
totalCostSum.query();
if(totalCostSum.next()){  // in case there is no result
   var allTotalCost = 0;
   allTotalCost = totalCostSum.getAggregate('SUM', 'total_cost');
   gs.print('SUM of total_cost: = ' + allTotalCost);
}

    La sortie de cet exemple est la suivante :

    *** Script: SUM of total_cost: 101

    GlideRecord

    GlideRecord est une classe Java spéciale (GlideRecord.java) qui peut être utilisée en JavaScript exactement comme s’il s’agissait d’une classe JavaScript native.

    GlideRecord :
    • est utilisé pour les opérations de base de données au lieu d’écrire des requêtes SQL.
    • est un objet qui contient zéro ou plusieurs enregistrements d’une table. Une autre façon de le dire est qu’un GlideRecord est une liste ordonnée.

    Un GlideRecord contient à la fois des enregistrements (lignes) et des champs (colonnes). Les noms de champs sont les mêmes que les noms de colonnes de base de données sous-jacentes. Pour plus d’informations, référez-vous à GlideRecord - Scoped.

    Remarque :
    L’utilisation de la syntaxe de script gs.sql()) a été abandonnée en Geneva. Utilisez la syntaxe GlideRecord standard à la place.

    Utilisation de GlideRecordSecure

    GlideRecordSecure est une classe héritée de GlideRecord qui remplit les mêmes fonctions que GlideRecord et applique également les ACL.

    Champs non accessibles en écriture

    N’oubliez pas que, lors de l’utilisation de GlideRecordSecure, les champs non accessibles en écriture sont définis sur NULL lors de la tentative d’écriture dans la base de données. Par défaut, canCreate() sur la colonne est remplacé par canWrite() sur la colonne. Si cela renvoie false, la valeur de colonne est définie sur NULL.

    Recherche de valeurs NULL

    Si un élément ne peut pas être lu parce qu’une ACL restreint l’accès, une valeur NULL est créée en mémoire pour cet enregistrement. Avec GlideRecord, vous devez rechercher explicitement toutes les ACL susceptibles de restreindre l’accès en lecture à l’enregistrement. Pour ce faire, une instruction if telle que la suivante est nécessaire pour vérifier si l’enregistrement peut être lu :
    if ( !grs.canRead() ) continue;
    Avec GlideRecordSecure, vous n’avez pas besoin de vérifier explicitement l’accès en lecture à l’aide de canRead(). Au lieu de cela, vous pouvez utiliser next() seul pour passer à l’enregistrement suivant. L’exemple suivant fournit une comparaison entre GlideRecord et GlideRecordSecure. 
    var count  = 0;
var now_GR  = new GlideRecord('mytable');
now_GR. query(); 
while (now_GR. next()) { 
    if (!now_GR. canRead()) continue; 
    if (!now_GR. canWrite()) continue; 
    if (!now_GR. val. canRead() || !now_GR. val. canWrite())
        now_GR. val = null;
    else
        now_GR. val = "val-" + now_GR. id; 
    if (now_GR. update())
        count ++; 
}
    var count  = 0; 
var grs  = new GlideRecordSecure('mytable');
grs. query(); 
while (grs. next()) {
    grs. val = "val-" + grs. id; 
    if (grs. update())
        count ++; 
}

    Exemples

    Il s’agit de deux exemples simples utilisant GlideRecordSecure.

    var att  = new GlideRecordSecure ('sys_attachment');
att. get('$[sys_attachment.sys_id]'); 
var sm  = GlideSecurityManager.get(); 
var checkMe  = 'record/sys_attachment/delete'; 
var canDelete  = sm.hasRightsTo(checkMe,att);
gs. log('canDelete: ' + canDelete);
canDelete;
    var grs = new GlideRecordSecure('task_ci');
grs.addQuery();
grs.query(); 
var count  = grs. getRowCount(); 
if (count  > 0 ) { 
    var allocation  = parseInt(10000/count) / 100;
    while (grs.next()) {
      grs.u_allocation = allocation;
      grs.update();
    }
}

    GlideSystem

    L’API GlideSystem fournit des méthodes pour récupérer des informations.

    Le GlideSystem (désigné par le nom de variable « gs » dans les règles métier) fournit un certain nombre de méthodes pratiques pour obtenir des informations sur le système, l’utilisateur connecté actuel, etc. Par exemple, la méthode addInfoMessage() permet de communiquer avec l’utilisateur.

     gs.addInfoMessage('Email address added for notification');

    De nombreuses méthodes GlideSystem facilitent l’inclusion de dates dans des plages de requêtes et sont le plus souvent utilisées dans les filtres et les rapports.

    Pour plus d’informations, consultez GlideSystem.

    GlideDateTime

    La classe GlideDateTime fournit des méthodes permettant d’effectuer des opérations sur les objets GlideDateTime , telles que l’instanciation d’objets GlideDateTime ou l’utilisation de glide_date_time champs.

    En plus des méthodes d’instanciation décrites ci-dessous, un objet GlideDateTime peut être instancié à partir d’un champ glide_date_time à l’aide de la méthode getGlideObject() (par exemple, var gdt = gr.my_datetime_field.getGlideObject() ;).

    Certaines méthodes utilisent le fuseau horaire de l’ordinateur virtuel Java lors de la récupération ou de la modification d’une valeur de date et d’heure. L’utilisation de ces méthodes peut entraîner un comportement inattendu. Dans la mesure du possible, utilisez des méthodes équivalentes à l’heure locale et à l’heure UTC.

    Exemples GlideDate et GlideDateTime

    Les API GlideDate et GlideDateTime sont utilisées pour manipuler les valeurs de date et d’heure.

    Remarque :
    Cette fonctionnalité nécessite une connaissance de JavaScript.

    Pour plus d’informations, reportez-vous à l’API GlideDate et à l’API GlideDateTime .

    Vous pouvez créer un objet GlideDateTime à partir d’un objet GlideDate en transmettant l’objet GlideDate comme paramètre au constructeur GlideDateTime . Par défaut, l’objet GlideDateTime est exprimé au format interne, aaaa-MM-jj HH :mm :ss et le fuseau horaire du système UTC.
    var gDate = new GlideDate();
gDate.setValue('2015-01-01');
gs.info(gDate);
 
var gDT = new GlideDateTime(gDate);
gs.info(gDT);
    Sortie : 
    2015-01-01
2015-01-01 00:00:00
    Voir aussi :

    Définir une valeur de champ de durée dans le script

    Exemples de code JavaScript pouvant être utilisés pour définir la valeur d’un champ de durée.

    Remarque :
    Les valeurs de durée négatives ne sont pas prises en charge.

    Utilisation de la méthode GlideDateTime.subtract()

    La méthode de soustraction (début GlideDateTime, fin GlideDateTime) dans GlideDateTime vous permet de définir la valeur de durée à l’aide d’une date/heure de début et d’une date/heure de fin données. Voici un exemple de définition de la durée d’ouverture d’une tâche :
    var duration = GlideDateTime.subtract(start, end);
    Si vous souhaitez utiliser la valeur renvoyée sous forme de nombre à utiliser dans l’arithmétique de date ou de durée, convertissez le retour en millisecondes :
    var time = GlideDateTime.subtract(start,end).getNumericValue();
    Si vous souhaitez définir une durée entre un événement et la date/heure actuelle :
    <duration_field> = GlideDateTime.subtract(new GlideDateTime(<start_time>.getValue()),gs.nowDateTime());

    Les valeurs de temps présentées à GlideDateTime.subtract sont censées être dans le fuseau horaire de l’utilisateur et au format de l’utilisateur.

    Définition d’une valeur par défaut pour un champ de durée

    La définition de la valeur par défaut d’un champ de durée est similaire à la méthode utilisée dans la rubrique précédente.

    Définition de la valeur du champ de durée dans un script client

    Ce script définit une valeur duration_field dans un script client. Remplacez duration_field par le nom de champ de votre instance.
    g_form.setValue('<duration_field>','11 01:02:03');

    Calcul et définition d’une durée à l’aide d’un script client

    Voici un exemple de la façon de renvoyer une valeur et de la renseigner à l’aide d’un script client.

    Créez un script client onChange incluant le code suivant. Vous pouvez modifier ce script si vous souhaitez que le calcul se fasse dans un script onLoad ou d’une autre manière.
    function onChange(control, oldValue, newValue, isLoading){
var strt = g_form.getValue('<start_field>');
var end = g_form.getValue('<end_field>');
var ajax = new GlideAjax('AjaxDurCalc');
  ajax.addParam('sysparm_name','durCalc');
  ajax.addParam('sysparm_strt',strt);
  ajax.addParam('sysparm_end',end);
  ajax.getXMLWait();
  var answer = ajax.getAnswer();
  g_form.setValue('<duration_field>', answer);}
    Créez un fichier de script système Include appelé AjaxDurCalc qui gère la demande. Il peut également être réutilisé pour d’autres fonctions.
    var AjaxDurCalc = Class.create();
AjaxDurCalc.prototype = Object.extendsObject(AbstractAjaxProcessor,{
 durCalc:function(){return GlideDuration.subtract(this.getParameter('sysparm_strt'),this.getParameter('sysparm_end'));}});

    Modification de la valeur du champ de durée

    Si vous manipulez une valeur de durée avec une addition/soustraction d’un certain laps de temps, utilisez les fonctions qui vous permettent d’obtenir et de définir la valeur numérique de la durée. L’unité de mesure d’une valeur numérique de durée est exprimée en millisecondes. Voici un exemple qui ajoute 11 secondes au champ de durée dans l’enregistrement actuel.
    var timems = current.duration.dateNumericValue();
timems = timems + 11*1000; 
current.duration.setDateNumericValue(timems);

    Formatage de l’heure de résolution

    Pour formater les champs Temps de résolution ou Temps de résolution de l’activité en tant que durées, qui les affichent sous forme de durée au lieu d’un grand nombre entier, ajoutez l’attribut suivant à ces champs :
    format=glide_duration

    Modifiez l’entrée du dictionnaire pour le champ et ajoutez l’attribut. S’il existe un attribut, séparez les attributs multiples par des virgules.

    Réglage de l’unité de mesure maximale

    L’attribut max_unit dictionary définit l’unité de temps maximale utilisée dans une durée. Par exemple, si max_unit=minutes, une durée de 3 heures 5 minutes 15 secondes apparaît comme suit : 185 minutes 15 secondes. Pour définir l’unité maximale de mesure de durée, ajoutez l’attribut de dictionnaire suivant au champ de durée :
    max_unit=<unit>

    Directives relatives au format de la date et de l’heure

    Vous pouvez spécifier un format de date avec une séquence de chaînes de modèles de date et d’heure spécifiques. Une chaîne de modèle se compose d’une ou plusieurs lettres majuscules et minuscules de A à Z. Tout texte entre guillemets est ignoré et copié dans la sortie de date.

    Chaîne Description Format de sortie Exemple
    G Désignateur d’ère Texte AD
    o Année Année 2019; 19
    Y Semaine de l’année Année 2019; 19
    M Mois de l’année (dans la date) Mois Juillet; Juil; 07
    L Mois de l’année (valeur autonome) Mois Juillet; Juil; 07
    w Semaine de l’année Numéro 52
    W Semaine du mois Numéro 1
    D Jour de l’année Numéro 365
    j Jour du mois Numéro 2
    F Jour de la semaine du mois Numéro 3
    E Nom du jour de la semaine Texte Mercredi; Mer
    U Nombre de jours de la semaine Numéro 3
    a matin ou après-midi Texte H.
    H Heure du jour de 0 à 23 Numéro 0
    k Heure du jour de 13h à 24h Numéro 24
    K Heure du matin ou de l’après-midi de 0 à 11 heures Numéro 0
    h Heure du matin ou de l’après-midi de 13 h à 12 h Numéro 12
    m Minute dans heure Numéro 59
    s Seconde dans minute Numéro 1
    S Milliseconde Numéro 500
    z Fuseau horaire au format par défaut Fuseau horaire au format par défaut Heure normale du Pacifique ; PST
    Z Fuseau horaire au format RFC 822 Fuseau horaire au format RFC 822 -0800
    X Fuseau horaire au format ISO 8601 Fuseau horaire au format ISO 8601 -08; -0800; -08:00

    Conflits courants de format date-heure

    Fournir une chaîne de format de date-heure incorrecte peut entraîner un comportement inattendu pour les méthodes des API GlideDate, GlideDateTime et GlideTime . Utilisez la table suivante pour vous aider à résoudre les problèmes de format.

    Format incorrect Explication Format correct
    AAAA-MM-JJ HH :MM :ss
    • Problème : Utiliser un « Y » majuscule pour représenter l’année. Le symbole « Y » est rarement utilisé et représente l’année de la semaine.
    • Solution : utilisez le symbole « y » minuscule pour l’année civile.
    		 aaaa-MM-jj hh:mm:ss
    HH :mm :ss a

    hh :mm :ss
    • Problème : conflit d’utilisation entre les symboles « HH » et « hh ».
      Remarque :
      Le symbole « a », un marqueur AM/PM, n’est pas compatible avec les symboles H ou k (24 heures).
    • Solution : utilisez la configuration appropriée pour représenter le format d’heure.
      • HH indique le format d’heure sur 24 heures avec un nombre de départs égal à zéro. C’est-à-dire l’heure dans une journée (0-23).
      • KK indique le nombre de début de 1 au format d’heure de 24 heures. C’est-à-dire l’heure dans un jour (1-24).
      • HH désigne le format d’heure 12 heures en AM/PM avec une heure de début de un (1-12).
      • KK indique le format d’heure 12 heures en am/pm avec une heure de début de zéro (0-11).
    		 hh :mm :ss : a

    HH:mm:ss
    HH :mm :ss z
    • Problème : les valeurs d’affichage du fuseau horaire « z » unique ne sont pas uniques. Par exemple, IST : Heure normale d’Inde/Israël.
    • Solution : utilisez « zzzz » pour le nom complet du fuseau horaire.
    		 HH :mm :ss zzzz
    MM-jj-aaaa HH :MM
    • Problème : Utilisation de « MM » pour le mois et la minute.
    • Solution : utilisez « MM » pour le mois et « mm » pour la minute.
    		 MM-jj-a HH :mm
    aaaa-j-MM
    • Problème : utilisation de « DDD » pour le jour du mois. Le symbole 'D' est utilisé pour le numéro du jour de l’année.
    • Solution : utilisez « jj » pour le jour du mois.
    		 aaaa-MM-jj

    Pour plus d’informations, reportez-vous à la section Modèles de date et d’heure pour SimpleDateFormat.