API du serveur Glide

ServiceNow fournit des API pour le serveur Glide.

Agrégat GlideAgrégat

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 calculer des champs calculés.

Remarque :

Cette fonctionnalité nécessite une connaissance de JavaScript.

Pour plus d’informations, consultez l’API GlideAggregate .

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

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 illustre plusieurs agrégations pour voir combien de fois des 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 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)');
}

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 additionnez le 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 le jeu 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 l’exemple précédent, si vous utilisez la méthode groupBy(), l’agrégat SUM renvoie la somme de toutes les valeurs pour le 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 ceux des colonnes de la base de données sous-jacente. Pour plus d’informations, consultez GlideRecord : 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 des ACL.

Champs non accessibles en écriture

Sachez 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 la valeur faux, 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 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

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 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 de récupération d’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 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 .

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 la machine virtuelle 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 l’heure locale et les méthodes UTC équivalentes.

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 API GlideDate et 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 la façon de définir la durée d’ouverture d’une tâche :

var duration = GlideDateTime.subtract(start, end);

Si vous souhaitez utiliser la valeur renvoyée en tant que 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 la durée entre un événement et la date/heure actuelle :

<duration_field> = GlideDateTime.subtract(new GlideDateTime(<start_time>.getValue()),gs.nowDateTime());

Les valeurs temporelles 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 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');

Calculer et définir 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 qui inclut le code suivant. Vous pouvez modifier ce script si vous avez besoin que le calcul s’effectue 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. La valeur millisecondes est une unité de mesure pour une valeur numérique de durée. L’exemple suivant illustre l’ajout de 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’entreprise en tant que durées, ce qui les affiche sous forme de durée au lieu d’un grand 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-le par des virgules.

Définition de l’unité de mesure maximale

L’attribut de dictionnaire max_unit 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 équivaut à 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 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ésignation d’ère	Texte	ANNONCE
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 dans la semaine	Texte	Mercredi; Marier
u	Numéro de jour de la semaine	Numéro	3
a	matin ou après-midi	Texte	p.m.
H	Heure dans la journée de 0 à 23	Numéro	0
k	Heure dans la journée de 1 à 24 heures	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
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