APIs do Glide Server

ServiceNow fornece APIs para o Glide Server.

GlideAggregate

A classe GlideAggregate é uma extensão de GlideRecord e permite que consultas de agregação de banco de dados (COUNT, SUM, MIN, MAX, AVG) sejam feitas. Isso pode ser útil na criação de relatórios personalizados ou em cálculos para campos calculados.

Nota:

Esta funcionalidade requer conhecimento de JavaScript.

Para obter informações adicionais, consulte API GlideAggregate.

Exemplos de GlideAggregate

GlideAggregate é uma extensão de GlideRecord e seu uso provavelmente é melhor mostrado por meio de uma série de exemplos.

Nota:

Esta funcionalidade requer conhecimento de JavaScript.

Aqui está um exemplo que simplesmente obtém uma contagem do número de registros em uma tabela:

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

Não há consulta associada ao exemplo anterior. Se você quiser obter uma contagem dos incidentes que estavam em aberto, basta adicionar uma consulta como é feito com GlideRecord. Aqui está um exemplo para obter uma contagem do número de incidentes ativos.

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

Para obter uma contagem de todos os incidentes em aberto por categoria, o código é:

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

A saída é:

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

A seguir está um exemplo que usa várias agregações para ver quantas vezes os registros foram modificados usando os valores MIN, MAXe 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);}

A saída é:

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

A seguir está um exemplo mais complexo que mostra como comparar a atividade de um mês com o outro.

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

A saída é:

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

A seguir está um exemplo para obter uma contagem distinta de um campo em uma consulta de grupo.

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

A saída é:

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

Você pode implementar o agregado SUM com ou sem o uso do método groupBy(). Se você não usar o método groupBy(), o resultado da SOMA será o valor cumulativo para cada valor diferente do campo para o qual você solicita a SOMA. Por exemplo, se você SOMAR o campo total_cost na tabela Ativo fixo e a tabela Ativo fixo contiver 12 registros no total:

• Três registros com um total_cost de US$ 12
• Quatro registros com total_cost de US$ 10
• Cinco registros com um total_cost de US$ 5

Quando você SOMA o conjunto de registros, o método getAggregate() retorna três somas diferentes: $ 36, $ 40 e $ 25.

O código a seguir ilustra a implementação do agregado SUM sem usar o método 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');
}

A saída para este exemplo é:

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

Usando os mesmos pontos de dados do exemplo anterior, se você usar o método groupBy(), o agregado SUM retornará a soma de todos os valores do campo especificado.

O exemplo a seguir ilustra a implementação do agregado SUM usando o método 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);
}

A saída para este exemplo é:

*** Script: SUM of total_cost: 101

GlideRecord

GlideRecord é uma classe Java especial (GlideRecord.java) que pode ser usada em JavaScript exatamente como se fosse uma classe JavaScript nativa.

GlideRecord:

• é usado para operações de banco de dados em vez de gravar consultas SQL.
• é um objeto que contém zero ou mais registros de uma tabela. Outra maneira de dizer isso é que um GlideRecord é uma lista ordenada.

Um GlideRecord contém registros (linhas) e campos (colunas). Os nomes de campo são os mesmos que os nomes de coluna do banco de dados subjacente. Para obter informações adicionais, consulte GlideRecord - Com escopo.

Nota:

O uso da sintaxe de script gs.sql()) foi descontinuado em Geneva. Use a sintaxe GlideRecord padrão em seu lugar.

Como usar o GlideRecordSecure

GlideRecordSecure é uma classe herdada de GlideRecord que executa as mesmas funções que GlideRecorde também impõe ACLs.

Campos não graváveis

Esteja ciente de que, ao usar GlideRecordSecure, os campos não graváveis são definidos como NULO ao tentar gravar no banco de dados. Por padrão, canCreate() na coluna é substituído por canWrite() na coluna. Se retornar falso, o valor da coluna será definido como NULO.

Verificando se há valores NULL

Se um elemento não puder ser lido porque uma ACL restringe o acesso, um valor NULO será criado na memória para esse registro. Com o GlideRecord, você deve verificar explicitamente se há ACLs que possam restringir o acesso de leitura ao registro. Para fazer isso, uma declaração "if" como a seguinte é necessária para verificar se o registro pode ser lido:

if ( !grs.canRead() ) continue;

Com GlideRecordSecure, você não precisa verificar explicitamente o acesso de leitura usando canRead(). Em vez disso, você pode usar next() sozinho para passar para o próximo registro. O exemplo a seguir fornece uma comparação entre GlideRecord e 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 ++; 
}

Exemplos

Estes são dois exemplos simples que usam 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

A API GlideSystem fornece métodos para recuperar informações.

O GlideSystem (referido pelo nome de variável 'gs' nas regras de negócio) fornece vários métodos convenientes para obter informações sobre o sistema, o usuário conectado no momento etc. Por exemplo, o método addInfoMessage() permite a comunicação com o usuário.

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

Muitos dos métodos GlideSystem facilitam a inclusão de datas em intervalos de consulta e são usados com mais frequência em filtros e relatórios.

Para obter informações adicionais, consulte GlideSystem.

GlideDateTime

A classe GlideDateTime fornece métodos para executar operações em objetos GlideDateTime, como instanciar objetos GlideDateTime ou trabalhar com campos glide_date_time.

Além dos métodos de instanciação descritos abaixo, um objeto GlideDateTime pode ser instanciado a partir de um campo glide_date_time usando o método getGlideObject() (por exemplo, var gdt = gr.my_datetime_field.getGlideObject();).

Alguns métodos usam o fuso horário da Java Virtual Machine ao recuperar ou modificar um valor de data e hora. O uso desses métodos pode resultar em comportamento inesperado. Use hora local equivalente e métodos UTC sempre que possível.

Exemplos de GlideDate e GlideDateTime

As APIs GlideDate e GlideDateTime são usadas para manipular valores de data e hora.

Nota:

Esta funcionalidade requer conhecimento de JavaScript.

Para obter informações adicionais, consulte API GlideDate e API GlideDateTime.

Você pode criar um objeto GlideDateTime a partir de um objeto GlideDate passando o objeto GlideDate como um parâmetro para o construtor GlideDateTime. Por padrão, o objeto GlideDateTime é expresso no formato interno, aaaa-MM-dd HH:mm:ss e o fuso horário do sistema UTC.

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

Saída:

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

Consulte também Modificação de um valor de campo GlideDateTime.

Definir um valor de campo de duração no script

Exemplos de JavaScript que podem ser usados para definir o valor de um campo de duração.

Nota:

Não há suporte para valores de duração negativos.

Usando o método GlideDateTime.subtract()

O método subtract(GlideDateTime start, GlideDateTime end) em GlideDateTime permite que você defina o valor de duração usando uma determinada data/hora de início e data/hora de término. Um exemplo de como definir a duração do tempo em que uma tarefa foi aberta é:

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

Se você quiser trabalhar com o valor retornado como um número para usar na aritmética de data ou duração, converta o retorno em milissegundos:

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

Se você quiser definir uma duração para a quantidade de tempo entre algum evento e a data/hora atual:

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

Espera-se que os valores de hora apresentados para GlideDateTime.subtract estejam no fuso horário e no formato do usuário.

Como definir um valor padrão de um campo de duração

Definir o valor padrão para um campo de duração é semelhante ao método usado no tópico anterior.

Como definir o valor do campo de duração em um client script

Este script define um valor de duração_field em um client script. Substitua duração_field pelo nome do campo da sua instância.

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

Como calcular e definir uma duração usando um client script

Aqui está um exemplo de como retornar um valor e preenchê-lo usando um client script.

Crie um client script onChange que inclua o código a seguir. Você pode modificar este script se precisar que o cálculo aconteça em um script onLoad ou de outra forma.

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

Crie um arquivo de inclusão de script do sistema chamado AjaxDurCalc que lida com a solicitação. Ele também pode ser reutilizado para outras funções.

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

Alterando o valor do campo de duração

Se você manipular um valor de duração com adição/subtração de uma certa quantidade de tempo, use as funções que permitem obter e definir o valor numérico da duração. Uma unidade de medida para um valor numérico de duração é milissegundos. A seguir está um exemplo que adiciona 11 segundos ao campo de duração no registro atual.

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

Como formatar o tempo de resolução

Para formatar os campos Tempo de resolução ou Tempo de resolução de negócios como durações, que os exibe como uma duração em vez de um número inteiro grande, adicione o seguinte atributo a esses campos:

format=glide_duration

Modifique a entrada do dicionário para o campo e adicione o atributo. Se houver um atributo existente, separe vários atributos com vírgulas.

Definir a unidade de medida máxima

O atributo de dicionário max_unit define a unidade máxima de tempo usada em uma duração. Por exemplo, se max_unit=minutes, uma duração de 3 horas 5 minutos e 15 segundos aparecerá como 185 minutos e 15 segundos. Para definir a unidade máxima de medição de duração, adicione o seguinte atributo de dicionário ao campo de duração :

max_unit=<unit>

Diretrizes de formato de data e hora

Você pode especificar um formato de data com uma sequência de cadeias de caracteres de padrão de data e hora específicas. Uma cadeia de caracteres padrão consiste em uma ou mais letras maiúsculas e minúsculas de A a Z. Qualquer texto entre aspas é ignorado e, em vez disso, é copiado na saída de data.

Cadeia de caracteres	Descrição	Formatos de Saída	Exemplo
G	Designador de era	Texto	AD
y	Ano	Ano	2019; 19
Y	Semana do ano	Ano	2019; 19
M	Mês do ano (na data)	Mês	Julho; jul; 07
L	Mês do ano (valor autônomo)	Mês	Julho; jul; 07
w	Semana do ano	Número	52
Sem	Semana do mês	Número	1
D	Dia do ano	Número	365
D	Dia do mês	Número	2
F	Dia da semana do mês	Número	3
E	Nome do dia na semana	Texto	Quarta-feira; qua
u	Dia da semana	Número	3
a	a.m. ou p.m.	Texto	p.m.
H	Hora do dia de 0 a 23	Número	0
k	Hora do dia de 1 a 24	Número	24
mil	Hora em am ou pm de 0 a 11	Número	0
h	Hora em am ou pm de 1 a 12	Número	12
M	Minuto da hora	Número	59
s	Segundo do minuto	Número	1
S	Milissegundo	Número	500
z	Fuso horário no formato padrão	Fuso horário no formato padrão	Horário padrão do Pacífico; PST
Z	Fuso horário no formato RFC 822	Fuso horário no formato RFC 822	-0800
X	Fuso horário no formato ISO 8601	Fuso horário no formato ISO 8601	-08; -0800; -08:00