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.

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 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 o. 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

O exemplo a seguir é 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, há 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 o agregado DE SOMA com ou sem o uso de GroupBy() método. Se você não usar o. 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

Quando você SOMA 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 do agregado DE SOMA 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 deste 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 do agregado DE SOMA usando o. 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 deste 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. 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 iguais aos 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 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.

Por padrão, GlideRecordSecure Não impõe ACLs de consulta. Embora ele aplique ACLs de leitura e gravação padrão automaticamente, as ACLs de consulta exigem aceitação explícita dos desenvolvedores. Para obter mais informações, consulte Imposição de ACLs de consulta.

Campos não graváveis

Ao usar GlideRecordSecure , Os campos não graváveis são definidos como NULO ao tentar gravar no banco de dados. Por padrão, o. CanCreate() o método na coluna é substituído por CanWrite() na coluna. . CanWrite() O método retorna falso, o valor da coluna é definido como NULO.

Obtendo o tipo de objeto

Você pode verificar se um tipo de objeto é ScopedGlideRecordSecure chamando o. ToString() método.

Verificando o tipo real GlideRecord retornado

O objeto atual pode ser passado como ScopedGlideRecordSecure . Na maioria dos casos, você pode ligar ToString() para retornar o tipo de objeto atual.

A linha a seguir retorna [Objeto ScopedGlideRecordSecure] para um ScopedGlideRecordSecure objeto:

gs.info(current.toString());

Se o tipo de objeto retornado for diferente do esperado

Chamando uma função com escopo que retorna um GlideRecord o objeto como seu tipo retorna resultados diferentes, dependendo do escopo do qual é chamado.

• Chamar a função com escopo no escopo da aplicação retorna o tipo de objeto esperado de GlideRecord ou GlideRecordSecure .
• Chamar a função com escopo no escopo global retorna o tipo de objeto é GlideRecord ScopedGlideRecord ou ScopedGlideRecordSecure .

Verificando valores nulos

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 GlideRecord , Você deve verificar explicitamente se há ACLs que possam restringir o acesso de leitura ao registro. Para fazer isso, um se uma declaração como a seguinte é necessária para verificar se o registro pode ser lido:

if (!now_GRScanRead())
   continue;

Com GlideRecordSecure , não é necessário verificar explicitamente o acesso de leitura usando CanRead() . Em vez disso, você pode usar próximo() por si só para 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 now_GRS = new GlideRecordSecure('mytable');
now_GRS.query(); 
while (now_GRS.next()) {
    now_GRS.val = "val-" + now_GRS.id; 
    if (now_GRS.update())
        count ++; 
}

Imposição de ACLs de consulta

Por padrão, GlideRecordSecure Não impõe ACLs de consulta. A imposição da ACL de consulta requer aceitação explícita.

A imposição de ACLs de consulta é uma abordagem de segurança que garante que os usuários só possam consultar campos e registros autorizados a acessar. Esta estratégia fornece defesa profunda aplicando controles de acesso no nível de consulta, não apenas no nível de recuperação de dados. A imposição explícita de ACL de consulta representa um padrão de design mais seguro para aplicações que manipulam a entrada do usuário.

Para especificar explicitamente o comportamento de imposição de ACL de consulta, use GlideRecordSecure.addEncodedQuery() . Atualize o básico AddEncodedQuery(consulta) Uso sem especificação explícita de ACL. Use uma das seguintes opções de segurança.

Opção 1: Métodos de conveniência (recomendados)

Use o. AddUserEncodedQuery() método para os seguintes casos de uso:

• Consultas criadas a partir da entrada do usuário nas quais as ACLs de consulta se aplicam
• Crie filtros dinâmicos com base nas seleções do usuário
• Manipule dados não confiáveis

Use o. AddSystemEncodedQuery() método para os seguintes casos de uso:

• Condições de consulta codificadas
• Lógica de back-end ou somente do sistema sem entrada do usuário
• Condições de consulta predefinidas e seguras

Misture os dois métodos conforme necessário. Diferentes partes da sua consulta podem usar diferentes níveis de imposição com base na origem.

// Queries built from user input
nowGRS_ACL.addUserEncodedQuery(userInput);

// Hard-coded system queries
nowGRS.addSystemEncodedQuery("active=true");

Opção 2: Parâmetro booliano

O exemplo a seguir mostra como usar o. AddEncodedQuery() Método para imposição de ACL.

// Explicitly enforce query ACLs
var now_GRS_true = new GlideRecordSecure(<table_name>); 
nowGRS_true.addEncodedQuery(query, true);

// Explicitly skip query ACL enforcement (use cautiously) 
var nowGRS_false = new GlideRecordSecure(<table_name>); 
nowGRS_false.addEncodedQuery(query, false);

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 now_GRS = new GlideRecordSecure('task_ci');
now_GRS.addSystemQuery();
now_GRS.query(); 
var count = now_GRS.getRowCount(); 
if (count > 0 ) { 
    var allocation = parseInt(10000/count) / 100;
    while (now_GRS.next()) {
      now_GRS.u_allocation = allocation;
      now_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ócios) 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 GlideSystem os métodos facilitam a inclusão fácil de datas em intervalos de consulta e são mais usados em filtros e relatórios.

Para obter informações adicionais, consulte GlideSystem .

GlideDateTime

. GlideDateTime a classe fornece métodos para executar operações em GlideDateTime objetos, como instanciação GlideDateTime 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. O uso desses métodos pode resultar em comportamento inesperado. Sempre que possível, use métodos locais e UTC equivalentes.

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 E. GlideDateTime API.

Você pode criar um GlideDateTime objeto de um GlideDate objeto passando em 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()

. GlideDateTime start, GlideDateTime end método em GlideDateTime permite definir 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 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());

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

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

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

Definindo o valor do campo Duração em um script de cliente

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

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

Calculando e definindo uma duração usando um script de cliente

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

Crie um Onchange script de cliente que inclui o seguinte código. 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 Cálc. AjaxDur 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 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. O exemplo a seguir 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 o. 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 do dicionário para o campo e adicione o atributo. Se houver um atributo existente, separe vários atributos com vírgulas.

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