APIs do servidor Glide

ServiceNow Fornece APIs para o Glide Server.

GlideAggregate

. GlideAggregate a classe é uma extensão de GlideRecord E permite que consultas de agregação de banco de dados (COUNT, SOMA, 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 GlideAggregate API.

Exemplos de GlideAggregate

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

Nota:

Esta funcionalidade requer conhecimento de JavaScript.

Este é 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 abertos, basta adicionar uma consulta como feito com GlideRecord . Este é 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 MÍN , MÁX e MÉDIA valores.

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 para o próximo.

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 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 a SOMA agregada com ou sem o uso de GroupBy() método. Se você não usar GroupBy() O resultado da SOMA é 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 totais:

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

Ao SOMAR o conjunto de registros, o GetAggregate() o método retorna três somas diferentes: usd 36, usd 40 e usd 25.

O código a seguir ilustra a implementação da SOMA agregada sem usar o. GroupBy() método:

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 GroupBy() O agregado SOMA retorna a soma de todos os valores do campo especificado.

O exemplo a seguir ilustra a implementação da SOMA agregada usando GroupBy() método:

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 usado 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. Uma outra maneira de dizer isso é que um GlideRecord é uma lista ordenada.

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

Nota:

Uso de gs.sql()) a sintaxe de script foi descontinuada em Geneva. Padrão de uso GlideRecord sintaxe em seu lugar.

Usando GlideRecordSecure

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

Campos não graváveis

Esteja ciente disso, ao usar GlideRecordSecure Campos não graváveis são definidos como NULL ao tentar gravar no banco de dados. Por padrão, CanCreate() na coluna é substituído por CanWrite() na coluna . Se isso retornar falso, o valor da coluna será definido como NULO.

Verificando valores NULL

Se um elemento não puder ser lido porque uma ACL restringe o acesso, um valor NULL será criado na memória para esse registro. Com GlideRecord, você deve verificar explicitamente se há ACLs que possam restringir o acesso de leitura ao registro. Para fazer isso, uma instruçã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() mover 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 usando 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

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

. GlideSystem (referido pelo nome da variável ' gs " em regras de negócio) fornece uma série de 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 GlideSystem os métodos facilitam a inclusão fácil 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

. GlideDateTime a classe fornece métodos para executar operações no GlideDateTime objetos, como instanciação GlideDateTime objetos ou trabalhando com glide_date_time campos.

Além dos métodos de instanciação descritos abaixo, um objeto GlideDateTime pode ser instanciado de um glide_date_time campo usando GetGlideObject() método (por exemplo, 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. Usar esses métodos pode resultar em comportamento inesperado. Use métodos locais e UTC equivalentes sempre que possível.

Exemplos GlideDate e GlideDateTime

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

Nota:

Esta funcionalidade requer conhecimento de JavaScript.

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

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

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 Modifique um valor do campo GlideDateTime.

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

Valores de duração negativos não são compatíveis.

Usando o método GlideDateTime.subtract()

. Subtrair (início GlideDateTime, término GlideDateTime) método em GlideDateTime permite que você defina o valor da 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 a ser usado 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());

Os valores de tempo apresentados para GlideDateTime.subtrair espera-se que estejam no fuso horário do usuário e no formato do usuário.

Definir um valor padrão de um campo de duração

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

Definir o valor do campo Duração em um client script

Este script define um duration_field valor em um client script. Substituir duration_field com o nome do campo da sua instância.

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

Calcular e definir uma duração usando um client script

Este é um exemplo de como retornar um valor e preenchê-lo usando um client script.

Crie um Onchange client script que inclui o código a seguir. Você pode modificar este script se precisar que o cálculo aconteça em um OnLoad script 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 AjaxDurCálc que lida com a solicitação. 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 Duração

Se você manipular um valor de duração com adição/subtração de algum período 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 duração campo no registro atual.

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

Formatando o tempo de resolução

Para formatar o. Tempo de resolução ou Tempo de resolução de negócios campos 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 de dicionário do campo e adicione o atributo. Se houver um atributo existente, separe vários atributos com vírgulas.

Definir a unidade máxima de medida

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

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 para a 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