Glide サーバー API

ServiceNow は Glide サーバー用の API を提供します。

GlideAggregate

GlideAggregate クラスは GlideRecord の拡張であり、データベース集計 (COUNT、SUM、MIN、MAX、AVG) クエリを実行できます。これは、カスタマイズされたレポートの作成や計算フィールドの計算に役立ちます。

注:

この機能を使用するには、JavaScript のナレッジが必要です。

詳細については、GlideAggregate API を参照してください。

GlideAggregate の例

GlideAggregate は GlideRecord の拡張であり、一連の例を参照することでその使用法を最もよく理解できます。

注:

この機能を使用するには、JavaScript のナレッジが必要です。

以下は、テーブル内のレコード数を取得する簡単な例です。

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

前の例に関連付けられたクエリはありません。オープンであったインシデントの数を取得する場合は、GlideRecord を使用するときと同じようにクエリを追加するだけです。アクティブなインシデントの数を取得する例を次に示します。

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

すべてのオープンインシデントの数をカテゴリ別に取得する場合、コードは次のようになります。

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

出力は次のとおりです。

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

次の例では、複数の集計を使用して、[最小値]、[最大値]、および [平均] の値を使用してレコードが変更された回数を確認します。

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

出力は次のとおりです。

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

次のさらに複雑な例は、ある月と翌月のアクティビティを比較する方法を示しています。

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

出力は次のとおりです。

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

次の例は、グループクエリでフィールドの個別のカウントを取得する方法です。

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

出力は次のとおりです。

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

SUM 集計は、groupBy() メソッドの使用の有無にかかわらず実施できます。groupBy() メソッドを使用しない場合、SUM の結果は、SUM を要求したフィールドのさまざまな値の累積値になります。たとえば、固定資産テーブルの total_cost フィールドを SUM で集計する場合、固定資産テーブルに合計で 12 のレコードが含まれていると、次のようになります。

• total_cost が $12 である 3 つのレコード
• total_cost が $10 である 4 つのレコード
• total_cost が $5 である 5 つのレコード

レコードセットを SUM で集計すると、getAggregate() メソッドは $36、$40、$25 の 3 つの異なる合計を返します。

次のコードは、groupBy() メソッドを使用せずに SUM 集計を実施する方法を示しています。

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

この例の出力は次のとおりです。

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

前の例と同じデータポイントを使用して、groupBy() メソッドを使用すると、SUM 集計は指定されたフィールドのすべての値の合計を返します。

次の例は、groupBy() メソッドを使用して SUM 集計を実施する方法を示しています。

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

この例の出力は次のとおりです。

*** Script: SUM of total_cost: 101

GlideRecord

GlideRecord は、JavaScript でネイティブ JavaScript クラスとまったく同じように使用できる特別な Java クラス (GlideRecord.java) です。

GlideRecord：

• SQL クエリを記述する代わりにデータベース操作に使用されます。
• 1 つのテーブルからの 0 個以上のレコードを含むオブジェクトです。別の言い方をすると、GlideRecord は順序付きリストです。

GlideRecord にはレコード (行) とフィールド (列) の両方が含まれます。フィールド名は、基礎となるデータベースの列名と同じです。詳細については、「GlideRecord - スコープ対象」を参照してください。

注:

gs.sql() スクリプト構文の使用は Geneva で廃止されました。代わりに標準 GlideRecord 構文を使用します。

GlideRecordSecure の使用

GlideRecordSecure は GlideRecord から継承されるクラスであり、GlideRecord と同じ関数を実行し、ACL も適用します。

書き込み不可能なフィールド

GlideRecordSecure を使用すると、書き込み不可能なフィールドがデータベースへの書き込み試行時に NULL に設定されることに注意してください。デフォルトでは、列上の canCreate() が列上の canWrite() で置き換えられます。false を返す場合、列の値は NULL に設定されます。

NULL 値の確認

ACL がアクセスを制限するために要素を読み取ることができない場合、このレコードのメモリに NULL 値を作成します。GlideRecord を使用する場合、レコードへの読み取りアクセスを制限する可能性のある ACL を明示的にチェックする必要があります。これを行うには、レコードを読み取ることができるかどうかを確認する、次のような if ステートメントが必要です。

if ( !grs.canRead() ) continue;

GlideRecordSecure を使用する場合、canRead() を使用して読み取りアクセスを明示的にチェックする必要はありません。代わりに、next() 自体を使用して次のレコードに移動できます。次の例は、GlideRecord と 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 ++; 
}

例

これらは GlideRecordSecure を使用する簡単な 2 つの例です。

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

GlideSystem API は、情報を取得するためのメソッドを提供します。

GlideSystem (ビジネスルールでは変数名「gs」で参照) は、システムや現在ログインしているユーザーなどの情報を取得するための多数の便利なメソッドを提供しています。たとえば、メソッド addInfoMessage() は、ユーザーとの通信を許可します。

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

GlideSystem メソッドの多くは、日付をクエリ範囲に簡単に含めることができ、フィルターとレポートで最もよく使用されます。

詳細については、「GlideSystem」を参照してください。

GlideDateTime

GlideDateTime クラスは、GlideDateTime オブジェクトのインスタンス化や glide_date_time フィールドの操作など、GlideDateTime オブジェクトに対する操作を実行するためのメソッドを提供します。

上で説明したインスタンス化メソッドに加えて、getGlideObject() メソッドを使用して glide_date_time フィールドから GlideDateTime オブジェクトをインスタンス化できます (例：var gdt = gr.my_datetime_field.getGlideObject();)。

一部のメソッドでは、日付と時刻の値を取得または変更するときに Java 仮想マシンのタイムゾーンを使用します。このようなメソッドを使用すると、予期しない動作が発生する可能性があります。可能な限り、同等の現地時間と UTC メソッドを使用してください。

GlideDate と GlideDateTime の例

GlideDate および GlideDateTime API を使用して、日時の値を操作します。

注:

この機能を使用するには、JavaScript のナレッジが必要です。

詳細については、「GlideDate API」および「GlideDateTime API」を参照してください。

GlideDate オブジェクトを GlideDateTime コンストラクターにパラメーターとして渡すことで、GlideDate オブジェクトから GlideDateTime オブジェクトを作成できます。デフォルトでは、GlideDateTime オブジェクトは、内部形式 yyyy-MM-dd HH:mm:ss とシステムタイムゾーン UTC で表されます。

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

出力:

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

「GlideDateTime フィールド値の変更」も参照してください。

スクリプトでの期間フィールド値の設定

期間フィールド値の設定に使用できる JavaScript の例。

注:

負の期間値はサポートされていません。

GlideDateTime.subtract() メソッドの使用

GlideDateTime の subtract(GlideDateTime start, GlideDateTime end) メソッドを使用すると、指定された開始日時と終了日時を使用して期間値を設定できます。タスクがオープンされた時間に期間を設定する方法の例：

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

数値で返される値を日付または期間の計算に使用する場合は、戻り値をミリ秒に変換します。

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

イベントと現在の日付/時刻の間の時間に期間を設定する場合：

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

GlideDateTime.subtract に示される時間値は、ユーザーのタイムゾーン、ユーザーの形式であることが予期されます。

期間フィールドのデフォルト値の設定

期間フィールドのデフォルト値の設定は、前のトピックで使用した方法と似ています。

クライアントスクリプトでの期間フィールド値の設定

このスクリプトは、クライアントスクリプトで duration_field 値を設定します。インスタンスのフィールド名で duration_field を置き換えます。

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

クライアントスクリプトを使用した期間の計算と設定

クライアントスクリプトを使用して値を返したり入力したりする方法の例を次に示します。

次のコードを含む onChange クライアントスクリプトを作成します。onLoad スクリプトまたはその他の方法で計算を実行する必要がある場合は、このスクリプトを変更できます。

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

要求を処理する AjaxDurCalc というシステムスクリプトインクルードファイルを作成します。これは他の関数でも再利用できます。

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

期間フィールド値の変更

時間を加算/減算して期間の値を操作する場合は、期間の数値を取得および設定できる関数を使用します。期間の数値の測定単位はミリ秒です。次の例は、現在のレコードの duration フィールドに 11 秒を追加します。

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

解決時間の書式設定

[解決時間] または [ビジネス解決時間] フィールドを期間として書式設定して、大きい整数ではなく期間として表示するには、これらのフィールドに次の属性を追加します。

format=glide_duration

フィールドの辞書エントリを変更し、 属性を追加します。既存の属性がある場合は、複数の属性をカンマで区切ります。

最大測定単位の設定

max_unit 辞書属性は、期間で使用される時間の最大単位を定義します。たとえば、max_unit=minutes の場合、期間が 3 時間 5 分 15 秒であれば、185 分 15 秒と表示されます。期間の最大測定単位を設定するには、次の辞書属性を duration フィールドに追加します。

max_unit=<unit>

日付形式のガイドライン

特定の日付と時刻パターンの文字列シーケンスを使用して、日付形式を指定できます。パターン文字列は、A から Z までの 1 つ以上の大文字と小文字で構成されます。引用符で囲まれたテキストは無視され、代わりに日付出力にコピーされます。

文字列	説明	出力形式	例
G	年代指定子	テキスト	AD
y	年	年	2019; 19
Y	年の週	年	2019; 19
M	年の月 (日付内)	月次	July; Jul; 07
L	年の月 (スタンドアロン値)	月次	July; Jul; 07
w	年の週	番号	52
W	月の週	番号	1
D	年の日	番号	365
d	月の日	番号	2
F	月の曜日	番号	3
E	曜日名	テキスト	水曜日; 水
u	週の日の番号	番号	3
a	午前または午後	テキスト	p.m.
H	0 〜 23 の日の時間	番号	0
k	1 〜 24 の日の時間	番号	24
K	午前または午後 0 時から 11 時までの時間	番号	0
h	午前または午後 1 時から 12 時までの時間	番号	12
m	分	番号	59
s	秒	番号	1
S	ミリ秒	番号	500
z	デフォルト形式のタイムゾーン	デフォルト形式のタイムゾーン	太平洋標準時; PST
Z	RFC 822 形式のタイムゾーン	RFC 822 形式のタイムゾーン	-0800
X	ISO 8601 形式のタイムゾーン	ISO 8601 形式のタイムゾーン	-08; -0800; -08:00