Glide-Server-APIs

ServiceNow stellt APIs für den Glide Server bereit.

GlideAggregate

Die Klasse GlideAggregate ist eine Erweiterung von GlideRecord und ermöglicht die Durchführung von Abfragen von Datenbankzusammenfassungen (ANZAHL, SUMME, MIN, MAX, DURCHSCHNITT). Dies kann bei der Erstellung von angepassten Berichten oder Durchführung von Berechnungen für berechnete Felder hilfreich sein.

Hinweis:

Diese Funktionalität erfordert Kenntnisse in JavaScript.

Weitere Informationen finden Sie unter GlideAggregate -API.

GlideAggregate-Beispiele

GlideAggregate ist eine Erweiterung von GlideRecord und seine Verwendung wird wahrscheinlich am besten anhand einer Reihe von Beispielen gezeigt.

Hinweis:

Diese Funktionalität erfordert Kenntnisse in JavaScript.

Hier ein Beispiel, bei dem einfach die Anzahl der Datensätze in einer Tabelle gezählt wird:

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

Dem vorhergehenden Beispiel ist keine Abfrage zugeordnet. Wenn Sie die Anzahl der offenen Incidents abrufen möchten, fügen Sie einfach eine Abfrage wie unter GlideRecord hinzu. Hier ein Beispiel, um die Anzahl der aktiven Incidents zu ermitteln.

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

Um alle offenen Incidents nach Kategorien zu zählen, lautet der Code:

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

Die Ausgabe lautet:

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

Das folgende Beispiel zeigt anhand mehrerer Zusammenfassungen, wie oft Datensätze mithilfe der Werte MIN, MAX und DURCHSCHNITT geändert wurden.

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

Die Ausgabe lautet:

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

Das folgende ist ein komplexeres Beispiel, das zeigt, wie Aktivitäten von Monat zu Monat verglichen werden.

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

Die Ausgabe lautet:

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

Das folgende Beispiel zeigt ein eindeutiges Zählen eines Feldes in einer Gruppenabfrage.

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

Die Ausgabe lautet:

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

Sie können die SUMME-Zusammenfassung mit oder ohne Verwendung der Methode groupBy() implementieren. Wenn Sie die Methode groupBy() nicht verwenden, ist das SUMME-Ergebnis der kumulative Wert für jeden anderen Wert des Feldes, für das Sie SUM anfordern. Wenn Sie beispielsweise SUMME auf das Feld total_cost in der Tabelle „Festes Asset“ anwenden und die Tabelle „Festes Asset“ enthält insgesamt 12 Datensätze:

• Drei Datensätze mit total_cost von $12
• Vier Datensätze mit total_cost von $10
• Fünf Datensätze mit total_cost von $5

Wenn Sie SUMME auf den Datensatz anwenden, wirft die Methode getAggregate () drei unterschiedliche Summen aus: $36, $40 und $25.

Der folgende Code veranschaulicht die Implementierung der SUMME-Zusammenfassung ohne Verwendung der Methode 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');
}

Die Ausgabe für dieses Beispiel lautet:

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

Mit denselben Datenpunkten wie im vorherigen Beispiel wirft bei Anwendung der Methode groupBy() die SUMME-Zusammenfassung die Summe aller Werte für das angegebene Feld aus.

Das folgende Beispiel veranschaulicht die Implementierung der SUMME-Zusammenfassung mithilfe der Methode 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);
}

Die Ausgabe für dieses Beispiel lautet:

*** Script: SUM of total_cost: 101

GlideRecord

GlideRecord ist eine spezielle Java-Klasse (GlideRecord.java), die in JavaScript genauso verwendet werden kann, als wäre es eine native JavaScript-Klasse.

GlideRecord:

• Wird für Datenbankvorgänge verwendet, anstatt SQL-Abfragen zu schreiben.
• Ist ein Objekt, das null oder mehr Datensätze aus einer Tabelle enthält. Anders ausgedrückt kann man sagen, dass ein GlideRecord eine geordnete Liste ist.

Ein GlideRecord enthält sowohl Datensätze (Zeilen) als auch Felder (Spalten). Die Feldnamen entsprechen den zugrunde liegenden Datenbankspaltennamen. Weitere Informationen finden Sie unter GlideRecord – Bereichsbezogen.

Hinweis:

Die Verwendung der Skripting-Syntax gs.sql()) wurde in Genevaeingestellt. Verwenden Sie stattdessen die Standard -GlideRecord- Syntax.

GlideRecordSecure verwenden

GlideRecordSecure ist eine von GlideRecord geerbte Klasse, die die gleichen Funktionen wie GlideRecord erfüllt und auch ACLs durchsetzt.

Nicht beschreibbare Felder

Beachten Sie, dass bei der Verwendung von GlideRecordSecure nicht beschreibbare Felder auf NULL gesetzt werden, wenn versucht wird, in die Datenbank zu schreiben. Standardmäßig wird canCreate() in der Spalte durch canWrite() in der Spalte ersetzt. Wenn dies den Wert „false“ zurückgibt, wird der Spaltenwert auf NULL gesetzt.

Überprüfung auf NULL-Werte

Wenn ein Element nicht gelesen werden kann, weil eine ACL den Zugriff einschränkt, wird im Speicher für diesen Datensatz ein NULL-Wert erstellt. Mit GlideRecord müssen Sie explizit nach ACLs suchen, die den Lesezugriff auf den Datensatz einschränken könnten. Dazu ist eine if-Anweisung wie die folgende erforderlich, um zu prüfen, ob der Datensatz gelesen werden kann:

if ( !grs.canRead() ) continue;

Mit GlideRecordSecure brauchen Sie den Lesezugriff mit canRead() nicht explizit zu prüfen. Stattdessen können Sie next() alleine verwenden, um zum nächsten Datensatz zu gelangen. Das folgende Beispiel bietet einen Vergleich zwischen GlideRecord und 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 ++; 
}

Beispiele

Dies sind zwei einfache Beispiele mit 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

Das API GlideSystem bietet Methoden für den Abruf von Informationen.

Das GlideSystem (bezeichnet durch den Variablennamen „gs“ 'in Business Rules) bietet eine Reihe praktischer Methoden, um Informationen über das System, den aktuell angemeldeten Benutzer usw. abzurufen. Zum Beispiel ermöglicht die Methode addInfoMessage() die Kommunikation mit dem Benutzer.

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

Viele der GlideSystem-Methoden erleichtern den einfachen Einschluss von Datumsangaben in Abfragebereiche und werden am häufigsten in Filtern und Berichten verwendet.

Weitere Informationen finden Sie unter GlideSystem.

GlideDateTime

Die GlideDateTime- Klasse bietet Methoden zum Ausführen von Vorgängen für GlideDateTime- Objekte, z. B. das Instanziieren von GlideDateTime- Objekten oder das Arbeiten mit glide_date_time- Feldern.

Zusätzlich zu den nachfolgend beschriebenen Instanziierungsmethoden kann ein GlideDateTime-Objekt aus einem Feld glide_date_time mit der Methode getGlideObject() (z. B. var gdt = gr.my_datetime_field.getGlideObject (); instanziiert werden).

Einige Methoden verwenden die Zeitzone der Java Virtual Machine, wenn ein Datums- und Zeitwert abgerufen oder geändert wird. Die Verwendung dieser Methoden kann zu unerwartetem Verhalten führen. Verwenden Sie möglichst gleichwertige Ortszeit- und UTC-Methoden.

Beispiele für GlideDate und GlideDateTime

Die APIs GlideDate und GlideDateTime werden verwendet, um Datums- und Uhrzeitwerte zu ändern.

Hinweis:

Diese Funktionalität erfordert Kenntnisse in JavaScript.

Weitere Informationen finden Sie unter GlideDate -API und GlideDateTime -API.

Sie können ein GlideDateTime- Objekt aus einem GlideDate -Objekt erstellen, indem Sie das GlideDate- Objekt als Parameter an den GlideDateTime- Konstruktor übergeben. Standardmäßig wird das GlideDateTime- Objekt im internen Format jjjj-MM-tt HH:mm:ss und der Systemzeitzone UTC ausgedrückt.

var gDate = new GlideDate();
gDate.setValue('2015-01-01');
gs.info(gDate);
 
var gDT = new GlideDateTime(gDate);
gs.info(gDT);

Ausgabe:

2015-01-01
2015-01-01 00:00:00

Siehe auch GlideDateTime-Feldwert ändern.

Legen Sie einen Wert für das Feld „Dauer“ im Skript fest

Nachfolgend finden Sie Beispiele für JavaScript-Code, mit dem der Wert von Feldern des Typs „Dauer“ festgelegt werden kann.

Hinweis:

Negative Werte für die Dauer werden nicht unterstützt.

Methode „GlideDateTime.subtract()“ verwenden

Mit der Methode subtract(GlideDateTime start, GlideDateTime end) in GlideDateTime können Sie den Wert für die Dauer anhand eines bestimmten Startdatums/einer bestimmten Startuhrzeit und eines Enddatums/einer Enduhrzeit festlegen. Hier ein Beispiel für die Festlegung der Dauer basierend auf der Uhrzeit, zu der eine Aufgabe geöffnet wurde:

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

Soll der Wert als Zahl zurückgegeben und zur Berechnung von Datum oder Dauer verwendet werden, müssen Sie die Ausgabe in Millisekunden konvertieren:

var time = GlideDateTime.subtract(start,end).getNumericValue();

Soll die Dauer auf die verstrichene Zeit zwischen einem Event und dem aktuellen Datum/Uhrzeit-Wert festgelegt werden:

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

Es wird erwartet, dass die an GlideDateTime.subtract übergebenen Zeitwerte der Zeitzone des Benutzers und dem Format des Benutzers entsprechen.

Standardwert für Felder des Typs „Dauer“ festlegen

Das Festlegen eines Standardwerts für Felder des Typs „Dauer“ funktioniert ähnlich wie die im vorherigen Thema beschriebene Methode.

Wert für Felder des Typs „Dauer“ in Client-Skripts festlegen

Dieses Skript legt einen Wert für duration_field in einem Client-Skript fest. Ersetzen Sie duration_field durch den Feldnamen in Ihrer Instanz.

g_form.setValue('<duration_field>','11 01:02:03');

Dauer per Client-Skript berechnen und festlegen

Das Beispiel unten illustriert, wie Sie mithilfe eines Client-Skripts Werte zurückgeben und festlegen können.

Erstellen Sie zunächst ein Client-Skript des Typs onChange mit dem nachfolgend aufgeführten Code. Sie können dieses Skript ändern, wenn die Berechnung in einem Skript des Typs onLoad oder auf andere Weise durchgeführt werden muss.

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

Erstellen Sie eine System-Skripteinbindungsdatei mit dem Namen AjaxDurCalc, die die Anfrage verarbeitet. Sie kann auch für andere Funktionen wiederverwendet werden.

var AjaxDurCalc = Class.create();
AjaxDurCalc.prototype = Object.extendsObject(AbstractAjaxProcessor,{
 durCalc:function(){return GlideDuration.subtract(this.getParameter('sysparm_strt'),this.getParameter('sysparm_end'));}});

Wert von Feldern des Typs „Dauer“ ändern

Wenn Sie einen Wert des Typs „Dauer“ durch Addition oder Subtraktion eines Zeitwerts ändern möchten, müssen Sie Funktionen verwenden, die das Abrufen und Festlegen des numerischen Werts des Felds des Typs „Dauer“ erlauben. Eine Maßeinheit für einen numerischen Wert des Typs „Dauer“ ist Millisekunden. Das folgende Beispiel addiert 11 Sekunden zum Feld duration im aktuellen Datensatz.

var timems = current.duration.dateNumericValue();
timems = timems + 11*1000; 
current.duration.setDateNumericValue(timems);

Lösungszeitdauer formatieren

Wenn Sie das Feld Lösungszeitdauer oder das Feld Arbeitsausfall bis Störungslösung als Wert des Typs „Dauer“ formatieren möchten, sodass statt einer großen Ganzzahl eine Dauer angezeigt wird, müssen Sie dem jeweiligen Feld das folgende Attribut hinzufügen:

format=glide_duration

Ändern Sie den Dictionary-Eintrag des Felds, und fügen Sie das Attribut hinzu. Ist bereits ein Attribut vorhanden, trennen Sie alle zusätzlichen Attribute jeweils mit Komma.

Maximale Maßeinheit festlegen

Das Wörterbuchattribut max_unit definiert die maximale Maßeinheit, die für eine Dauer verwendet werden darf. Ist beispielsweise max_unit=minutes gesetzt, wird eine Dauer von 3 Stunden 5 Minuten 15 Sekunden als 185 Minuten 15 Sekunden angezeigt. Zum Festlegen der maximalen Maßeinheit für die Dauer müssen Sie dem Feld duration folgendes Wörterbuchattribut hinzufügen:

max_unit=<unit>

Richtlinien für das Datums- und Uhrzeitformat

Sie können ein Datumsformat mit einer Sequenz bestimmter Datums- und Uhrzeitmusterzeichenfolgen angeben. Eine Musterzeichenfolge besteht aus einem oder mehreren Groß- und Kleinbuchstaben von A bis Z. Text in Anführungszeichen wird ignoriert und stattdessen in die Datumsausgabe kopiert.

Zeichenfolge	Beschreibung	Ausgabeformat	Beispiel
G	Era-Bezeichner	Text	AD
y	Jahr	Jahr	2019; 19
Y	Woche im Jahr	Jahr	2019; 19
M	Monat im Jahr (innerhalb des Datums)	Monat	Juli; Juli; 07
L	Monat im Jahr (eigenständiger Wert)	Monat	Juli; Juli; 07
w	Woche im Jahr	Nummer	52
W	Woche im Monat	Nummer	1
D	Tag im Jahr	Nummer	365
d	Tag im Monat	Nummer	2
F	Wochentag im Monat	Nummer	3
E	Tagname in der Woche	Text	Mittwoch; Mi
u	Anzahl der Tage der Woche	Nummer	3
a	am oder nachmittags	Text	Uhr
H	Stunde am Tag von 0 bis 23	Nummer	0
k	Stunde am Tag von 1 bis 24	Nummer	24
K	Stunde in am oder pm von 0 bis 11 Uhr	Nummer	0
S	Stunde in am oder pm von 13 bis 12	Nummer	12
m	Minute in Stunde	Nummer	59
s	Sekunde in Minute	Nummer	1
S	Millisekunde	Nummer	500
z	Zeitzone im Standardformat	Zeitzone im Standardformat	Pazifik-Standardzeit PST
Z	Zeitzone im RFC 822-Format	Zeitzone im RFC 822-Format	-0800
X	Zeitzone im ISO 8601-Format	Zeitzone im ISO 8601-Format	-08; -0800; -08:00