API du serveur Glide

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 15 minutes de lecture

    • ServiceNow fournit des API pour le serveur Glide.

    Agrégat GlideAggregate

    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 effectuer des calculs pour des champs calculés.

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

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

    Exemples GlideAggregate

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

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

    Voici un exemple qui permet d’obtenir simplement le 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 décompte des incidents qui ont été ouverts, il vous suffit d’ajouter une requête comme 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 :

    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);}

    La sortie 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

    L’exemple suivant 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);}

    La sortie 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);
 
}

    La sortie 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

    L’exemple suivant permet d’obtenir un 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)');
}

    La sortie 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 de chaque valeur différente du champ pour lequel vous demandez la SOMME. Par exemple, si vous faites la somme du champ total_cost dans la table Actif immobilisé et que la table Actif immobilisé contient 12 enregistrements au total :
    • Trois disques avec un total_cost de 12 $
    • Quatre disques avec un total_cost de 10 $
    • Cinq disques avec un 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 :

    *** 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 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 :

    *** 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. En d’autres termes, un GlideRecord est une liste ordonnée.

    Un GlideRecord contient à la fois des enregistrements (lignes) et des champs (colonnes). Les noms de champs sont identiques à ceux des colonnes de la base de données sous-jacente. Pour plus d’informations, consultez GlideRecord : dans le champ d’application.

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

    Utilisation de GlideRecordSecure

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

    Par défaut, GlideRecordSecure n’applique pas les ACL de requête. Bien qu’il applique automatiquement les ACL standard en lecture-écriture, les ACL de requête nécessitent une adhésion explicite des développeurs. Pour plus d'informations, consultez Application des ACL de requête.

    Champs sans écriture

    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, la méthode canCreate() sur la colonne est remplacée par canWrite() sur la colonne. Si la méthode canWrite() renvoie la valeur false, la valeur de colonne est définie sur NULL.

    Obtention du type d’objet

    Vous pouvez vérifier si un type d’objet est ScopedGlideRecordSecure en appelant la méthode toString( ).

    Vérification du type réel GlideRecord renvoyé

    L’objet actuel peut être transmis en tant que ScopedGlideRecordSecure. Dans la plupart des cas, vous pouvez appeler current.toString() pour renvoyer le type d’objet actuel.

    La ligne suivante renvoie [object ScopedGlideRecordSecure] pour un objet ScopedGlideRecordSecure :

    gs.info(current.toString());

    Si le type d’objet renvoyé est différent de celui attendu
    L’appel d’une fonction incluse dans le périmètre qui renvoie un objet GlideRecord comme type renvoie des résultats différents selon le champ d’application à partir duquel il est appelé.
    • L’appel de la fonction incluse dans le périmètre de l’application retourne le type d’objet attendu GlideRecord ou GlideRecordSecure.
    • L’appel de la fonction incluse dans le champ d’application global renvoie que le type d’objet est ScopedGlideRecord ou ScopedGlideRecordSecure.

    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 (!now_GRScanRead())
   continue;
    Avec GlideRecordSecure, il n’est pas nécessaire 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 now_GRS = new GlideRecordSecure('mytable');
now_GRS.query(); 
while (now_GRS.next()) {
    now_GRS.val = "val-" + now_GRS.id; 
    if (now_GRS.update())
        count ++; 
}

    Application des ACL de requête

    Par défaut, GlideRecordSecure n’applique pas les ACL de requête. L’application de l’ACL de requête nécessite une adhésion explicite.

    L’application des ACL de requête est une approche de sécurité qui garantit que les utilisateurs ne peuvent interroger que les champs et les enregistrements auxquels ils sont autorisés à accéder. Cette stratégie fournit une défense en profondeur en appliquant des contrôles d’accès au niveau de la requête, et pas seulement au niveau de la récupération de données. L’application de l’ACL de requête explicite représente un modèle de conception plus sécurisé pour les applications gérant l’entrée de l’utilisateur.

    Pour spécifier explicitement le comportement d’application de l’ACL de requête, utilisez GlideRecordSecure.addEncodedQuery(). Mettre à jour l’utilisation de base de addEncodedQuery(query) sans spécification explicite d’ACL. Utilisez l’une des options sécurisées suivantes.

    Option 1 : Méthodes de commodité (recommandées)
    Utilisez la méthode addUserEncodedQuery() pour les cas d’utilisation suivants :
    • Requêtes créées à partir de l’entrée de l’utilisateur dans lesquelles les ACL de requête s’appliquent
    • Créer des filtres dynamiques en fonction des sélections des utilisateurs
    • Gérer les données non approuvées
    Utilisez la méthode addSystemEncodedQuery() pour les cas d’utilisation suivants :
    • Conditions de requête codées en dur
    • Logique back-end ou système uniquement sans entrée de l’utilisateur
    • Conditions de requête sûres et prédéfinies

    Mélanger les deux méthodes au besoin. Différentes parties de votre requête peuvent utiliser différents niveaux d’application en fonction de leur source.

    // Queries built from user input
nowGRS_ACL.addUserEncodedQuery(userInput);

// Hard-coded system queries
nowGRS.addSystemEncodedQuery("active=true");
    Option 2 : Paramètre booléen

    L’exemple suivant montre comment utiliser la méthode addEncodedQuery() pour l’application des ACL.

    // Explicitly enforce query ACLs
var now_GRS_true = new GlideRecordSecure(<table_name>); 
nowGRS_true.addEncodedQuery(query, true);

// Explicitly skip query ACL enforcement (use cautiously) 
var nowGRS_false = new GlideRecordSecure(<table_name>); 
nowGRS_false.addEncodedQuery(query, false);

    Exemples

    Ce sont 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 now_GRS = new GlideRecordSecure('task_ci');
now_GRS.addSystemQuery();
now_GRS.query(); 
var count = now_GRS.getRowCount(); 
if (count > 0 ) { 
    var allocation = parseInt(10000/count) / 100;
    while (now_GRS.next()) {
      now_GRS.u_allocation = allocation;
      now_GRS.update();
    }
}

    Système GlideSystem

    L’API GlideSystem fournit des méthodes de récupération d’informations.

    Le système 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 actuellement connecté, 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 facile des dates dans les plages de requête 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 pour effectuer des opérations sur les objets GlideDateTime , telles que l’instanciation d’objets GlideDateTime ou l’utilisation de champs glide_date_time .

    Outre les 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. Utilisez l’heure locale et les méthodes UTC équivalentes dans la mesure du possible.

    Exemples de GlideDate et de 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, consultez 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 dans 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 Modifier une valeur de champ GlideDateTime.

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

    Exemples de 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 subtract(GlideDateTime start, GlideDateTime end) 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 sur le temps écoulé entre un événement et la date/l’heure actuelle :
    <duration_field> = GlideDateTime.subtract(new GlideDateTime(<start_time>.getValue()),gs.nowDateTime());

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

    Définition d’une valeur par défaut d’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 retour d’une valeur et de remplissage de celle-ci à l’aide d’un script client.

    Créez un script client onChange qui inclut le code suivant. Vous pouvez modifier ce script si vous avez besoin 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 d’inclusion de script système 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 addition/soustraction d’une certaine durée, utilisez les fonctions qui vous permettent d’obtenir et de définir la valeur numérique de la durée. Une unité de mesure pour une valeur numérique de durée est la milliseconde. L’exemple suivant 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 Délai de résolution business en tant que durées, ce qui les affiche 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 de dictionnaire pour le champ et ajoutez l’attribut. S’il existe un attribut, séparez-en plusieurs par des virgules.

    Réglage de l’unité de mesure maximale

    L’attribut max_unit dictionnaire 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 correspond à 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 aux formats de date et d’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 motifs 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 après-midi
    H Heure dans la journée de 0 à 23 Numéro 0
    k Heure dans la journée de 1 à 24 Numéro 24
    K Heure en heures du matin ou de l’après-midi de 0 à 11 heures Numéro 0
    h Heure en matinée ou en après-midi de 13h à 12h 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 (en anglais seulement)
    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