helpers - Construtor de IU

A API de ajuda fornece funcionalidade geral que é comum em scripts de página, eliminando a necessidade de escrever scripts para funcionalidades simples, como abrir e fechar um modal.

Esta API está disponível somente para scripts de página. Ela não está disponível em nenhum outro script do Construtor de IU, incluindo:

• scripts de valor da propriedade do componente
• scripts de visibilidade do componente
• scripts de carga do evento
• Inclusões de client script de UX

helpers - helpers.modal.close(cadeia de caracteres modalId)

Fecha o modal especificado na página atual.

Tabela 1. Parâmetros

Nome	Tipo	Descrição
modalId	Cadeia de caracteres	ID do componente modal do modal a ser fechado. Os IDs de componente são gerados automaticamente quando um componente é arrastado e solto na fase Construtor de IU. Você pode localizar o ID na página de propriedades.

Tabela 2. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo mostra o fechamento de um modal com um ID de componente que termina com alert-modal.

function handler({api, event, imports, helpers}) {
  helpers.modal.close("[component-id$='alert_modal']")
}

helpers - helpers.modal.open(cadeia de caracteres modalId, opções de objeto)

Abre o modal especificado na página atual.

Você só pode exibir um modal de cada vez em uma página. Se um modal estiver aberto no momento e você chamar este método, o modal existente ficará oculto e o novo modal aparecerá.

Tabela 3. Parâmetros

Nome	Tipo	Descrição
modalId	Cadeia de caracteres	ID do componente do modal a ser aberto. Os IDs de componente são gerados automaticamente quando um componente é arrastado e solto na fase Construtor de IU. Você pode localizar o ID na página de propriedades.
opções	Objeto	Opcional. "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }
opções.conteúdo	Cadeia de caracteres	Conteúdo de texto para o modal.
opções.contentFullWidth	Booliano	Sinalizador que indica se o preenchimento horizontal deve ser removido ao redor do corpo do modal para ajustar o conteúdo mais amplo. Valores válidos: verdadeiro: remova o preenchimento. falso: não remova o preenchimento. Padrão: falso
opções.cabeçalhoRótulo	Cadeia de caracteres	Conteúdo de texto para o cabeçalho do modal.
opções.tamanho	Cadeia de caracteres	Tamanho do contêiner modal. A maioria dos tamanhos é expandida automaticamente para preencher a janela de visualização quando o tamanho da tela é pequeno. Valores válidos: sm md lg tela cheia Padrão: sm

Tabela 4. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo mostra a abertura de um modal com o ID de componente do Ca que termina com alert-modal.

function handler({api, event, imports, helpers}) {
  helpers.modal.open("[component-id$='alert_modal']")
}

helpers - helpers.navigate.setRouteParams (parâmetros de objeto)

Passa os parâmetros especificados para outros componentes na mesma página.

Use este método em qualquer componente de página que queira adicionar um parâmetro em um URL. Você pode adicionar um parâmetro a um URL quando outro componente precisar saber o valor atual desse parâmetro quando ele mudar, para que possa reagir a ele. Por exemplo, use este método para passar o selectedIndex de um componente da guia para que ele seja refletido no URL para dar foco a essa guia.

Tabela 5. Parâmetros

Nome	Tipo	Descrição
parâms	Objeto	Pares de chave-valor de parâmetros opcionais a serem passados para outros componentes. Deve ser um objeto simples e plano com apenas valores primitivos. As referências de matriz ou objeto são ignoradas e não adicionadas ao URL. Todas as chaves especificadas devem fazer parte dos parâmetros opcionais na configuração de rota ou também serão ignoradas. Para obter informações adicionais sobre parâmetros opcionais, consulte Criação de uma página no Construtor de IU.

Tabela 6. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo de código mostra como anexar os parâmetros de URL/selected-tab-index/2. Observe que o parâmetro no URL real é alterado de caso de camelo para caso de cobra, portanto selectedTabIndex se torna selected-tab-index.

function handler({api, event, helpers, imports}) {  
  helpers.navigate.setRouteParams({'params': {'selectedTabIndex':  2}});  
} 

helpers - helpers.navigate.to (cadeia de caracteres rota, campos de objeto, parâmetros de objeto, redirecionamento booliano, PassiveNavigation booliano, cadeia de caracteres targetRoute)

Navega de uma tela para outra com base na rota especificada e nas informações de campo. Mudanças de URL e os respectivos carregamentos de tela são observados.

Tabela 7. Parâmetros

Nome	Tipo	Descrição
rota	Cadeia de caracteres	Nome da rota. Deve ser uma entrada válida de Rotas da aplicação de UX (sys_ux_app_route.list). Este valor é refletido no URL e o URL é criado com base nos valores das colunas route, fieldse optionalParams : /<route> /<field1Value> /{<field2Value> /parâmetros/<optionalParamKey1> /<optionalParamValue1> /<optionalParamKey2> /<optionalParamValue2> Por exemplo: /record/incident/12345/params/selectedTabIndex/4
campos	Objeto	Opcional. Pares de chave-valor de parâmetros obrigatórios. Por exemplo: 'fields' : {'table': 'incident', 'sysId': '12345'}.
parâms	Objeto	Opcional. Pares de chave-valor de parâmetros opcionais. Por exemplo: 'params' : {'selectedTabIndex': 4}.
redirect	Booliano	Sinalizador que indica se a entrada de histórico mais recente deve ser removida do histórico do navegador. Por exemplo, se você navegar para os sites A, B e, em seguida, C. Se redirect estiver definido como verdadeiro ao navegar para C, a entrada de histórico de B será removida. O histórico do navegador mostra apenas A e C. Valores válidos: verdadeiro: remove a entrada de histórico mais recente e redireciona para a URL mais recente. falso: não remove nenhuma entrada de histórico. Padrão: falso
passiveNavigation	Booliano	Sinalizador que indica se a navegação em segundo plano deve ser executada. A navegação em segundo plano ocorre quando uma página é aberta, mas não está ativa ou mostrada. Por exemplo, abrir uma guia inativa para a página, mas não está visível, mas carregada em segundo plano. Valores válidos: verdadeiro: executa a navegação em segundo plano. falso: não executa a navegação em segundo plano. Padrão: falso
targetRoute	Cadeia de caracteres ou objeto	Subnavegação para detalhamento, link profundo ou subguia. Se definido como atual, a rota atual fará uma subnavegação no URL atual. Por exemplo, se /record/incident/123 for o URL atual e a seguinte chamada for feita: helper.navigate.to('record', {'table': 'problem', 'sysId': '567'}, {}, false, false, 'current'); O seguinte URL é gerado: /record/incident/123/sub/record/problem/567 Nota: targetRoute pode ser uma cadeia de caracteres como "atual" ou um objeto, como carga NAV_ITEM_SELECTED de navegação.

Tabela 8. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo mostra como navegar para uma página passando apenas o parâmetro route.

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test');
}

Este exemplo mostra como navegar até uma página passando os parâmetros route e fields.

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test', {'key': 'value'});
}

Este exemplo mostra como navegar até uma página passando os parâmetros route, fieldse params.

function handler({api, event, helpers, imports}) {
  helpers.navigate.to('test', {'key': 'value'}, {'first': 'FirstName', 'last': 'Last Name'});
}

helpers - helpers.screen.updateStatus(Object statusObj)

Permite que as páginas relatem suas atualizações de status, como título, ícone, estado sujo, mensagem e mudanças de erro.

As atualizações de status são relatadas para WorkspaceChrome ou AppShell, qualquer que seja a camada externa, e agindo como o host.

Tabela 9. Parâmetros

Nome	Tipo	Descrição
statusObj	Objeto	Carga a ser enviada para a página atual para relatar que o conteúdo foi atualizado. Valores válidos: dirtyModalId: (Cadeia de caracteres) ID do modal que foi alterado. hasError: (booliano) Sinalizador que indica que há erros na página. hasUpdate: (booliano) Sinalizador que indica que houve atualizações na página. icon: (Cadeia de caracteres) Nome do ícone atualizado ou novo. isDirty: (booliano) Sinalizador que indica se a página está modificada (os valores foram alterados). message: (Cadeia de caracteres) Mensagem atualizada/nova. screenKey: (Cadeia de caracteres) ID da tela na qual a mudança ocorreu. Cada tela tem um screenKey como uma propriedade no macroponent de tela dentro de sn-canvas-screen. status: (Cadeia de caracteres) Operação de status para esta ação. Este valor deve ser um dos seguintes: inserido, excluído, salvo ou encerrado. title: (Cadeia de caracteres) Título de exibição atualizado/novo. tooltipPreview: (JSON) Dica de ferramenta atualizada ou nova. Por exemplo, tooltipPreview : { primaryTitle,secondContent: {} }

Tabela 10. Retornos

Tipo	Descrição
Nenhum

screen.updateStatus({'dirtyModalId': 'customModalId', 'isDirty': true});

helpers - helpers.snHttp (cadeia de caracteres URL, opções de objeto)

Faz uma solicitação HTTP para a instância ServiceNow e retorna uma promessa com os resultados.

Nota:

Há um problema conhecido em que objetos chamados options são omitidos da resposta HTTP.

{
  options: {},
  otherFields: {}
}

becomes

{
  otherFields: {}
}

Tabela 11. Parâmetros

Nome	Tipo	Descrição
URL	Cadeia de caracteres	Endpoint HTTP relativo ao URL da instância. Por exemplo, /api/now/table/incident ou /api/now/table/incident/a83820b58f723300e7e16c7827bdeed.
opções	Objeto	Descreve o conteúdo da solicitação HTTP. "options": { "batch": Boolean, "body": {Object}, "headers": {Object}, "method": "String" }
opções.lote	Booliano	Opcional. Sinalizador que indica se esta solicitação HTTP deve ser agrupada com outras solicitações HTTP feitas para a instância. Valores válidos: verdadeiro: faz a solicitação como parte de uma solicitação em lote. falso: fazer solicitação dedicada. Padrão: verdadeiro
opções.corpo	Objeto	Opcional. Dados a serem enviados como o corpo da solicitação. Aplicável somente para métodos de solicitação PUT, POSTe PATCH. Os elementos no objeto dependem do tipo de método HTTP. Para obter detalhes, consulte os exemplos de código abaixo. Padrão: {}
opções.cabeçalhos	Objeto	Opcional. Cabeçalhos de solicitação HTTP adicionais. Por exemplo: headers: { "Content-Type": "application/json", "Accept": "application/xml" }
opções.método	Cadeia de caracteres	Opcional. Método HTTP. Valores válidos: DELETE GET PATCH POST PUT Padrão: GET

Tabela 12. Retornos

Tipo	Descrição
erro	Objeto que descreve qualquer erro retornado pela REST API. Tipo de dados: objeto "error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }
erro.dados	Resposta retornada da API HTTP. Tipo de dados: definido pela REST API
mensagem.erro	Mensagem que descreve o erro encontrado ao tentar processar a solicitação HTTP. Nota: Este parâmetro nem sempre é retornado. Tipo de dados: cadeia de caracteres
erro.opções	Descreve a solicitação HTTP original. Tipo de dados: objeto "options": { "headers": {Object}, "responseHeader": {Object} }
cabeçalhos.opções.erro	Objeto que contém uma lista de todos os cabeçalhos de solicitação enviados na solicitação. Tipo de dados: objeto
error.options.responseHeaders	Objeto que contém uma lista de todos os cabeçalhos de resposta enviados na solicitação. Tipo de dados: objeto
erro.status	Código de status de erro HTTP retornado, como 400, 405 ou 500. Tipo de dados: número
erro.statusText	Mensagem de status HTTP retornada, como Solicitação incorreta. Tipo de dados: cadeia de caracteres
resposta	Retornado quando a solicitação HTTP é bem-sucedida. A resposta à solicitação HTTP. Tipo de dados: qualquer

O exemplo a seguir mostra como chamar snHttp() que retorna uma promessa.

function handler({api, event, helpers, imports}) {
  helpers.snHttp('/api/now/table/u_movie', {method: 'GET'})
    .then(({response}) => {
      // do something with the table data
    })
    .catch(({error}) => {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
    });
  });
}

O exemplo a seguir mostra como chamar snHttp() usando async e await.

async function handler({helpers}) {
  try {
    const result = await helpers.snHttp('/api/now/table/u_movie', {method: 'GET'});
  } catch ({error}) {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
      });
  }
}

O exemplo a seguir mostra como configurar uma solicitação POST.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident", {
      method: "POST",
      body: {
        description: "Sample description",
        close_notes: "Sample close notes",
        order: "-1"
      }
    })
    .then(({ response }) => {
      // handle POST request response
    })
    .catch(({ error }) => {
      // handle POST request errors
    });
}

O exemplo a seguir mostra como configurar uma solicitação PUT.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident/a83820b58f723300e7e16c7827bdeed2", {
      method: "PUT",
      body: {
        activity_due: "1970-04-02 18:26:17"
      },
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/xml"
      }
    })
    .then(({ response }) => {
      // handle PUT request response
    })
    .catch(({ error }) => {
      // handle PUT request errors
    });
}

helpers - helpers.timing.clearInterval(Number timeoutId)

Cancela a execução da função que foi programada por meio de uma chamada setInterval() anterior.

Tabela 13. Parâmetros

Nome	Tipo	Descrição
timeoutId	Número	Identificador exclusivo da função programada a ser limpa. Este valor é retornado pela chamada setInterval() correspondente.

Tabela 14. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo mostra o uso de clearInterval() para cancelar uma operação de tempo que foi definida anteriormente usando o métodosetInterval(). Esta função pode ser invocada por um usuário que clica no botão Desabilitar atualização automática em uma página.

function handler({api, helpers}) {
  api.setState('intervalId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearInterval(currentValue);
    }
    return -1;
  });
}

helpers - helpers.timing.clearTimeout(Número timeoutId)

Cancela a execução da função que foi programada por meio de uma chamada setTimeout() anterior.

Tabela 15. Parâmetros

Nome	Tipo	Descrição
timeoutId	Número	Identificador exclusivo da função programada a ser limpa. Este valor é retornado pela chamada setTimeout() correspondente.

Tabela 16. Retornos

Tipo	Descrição
Nenhum(a)

Este exemplo de código mostra como encerrar um temporizador com o timeoutIdespecificado.

function handler({api, helpers}) {
  api.setState('timeoutId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearTimeout(currentValue);
    }
    return -1;
  });
}

helpers - helpers.timing.setInterval (função fn, atraso de número)

Executa repetidamente a função especificada, usando o valor de atraso especificado como o intervalo entre chamadas de função.

Ao contrário do método JavaScript nativo setInterval(), este método não é compatível com a passagem de uma cadeia de caracteres de código para avaliar como o primeiro argumento. Todos os argumentos adicionais são passados para a própria função.

Tabela 17. Parâmetros

Nome	Tipo	Descrição
fn	Função	Função a ser executada repetidamente.
atraso	Número	Duração do intervalo de tempo entre cada execução de função. Unidade: Milissegundos

Tabela 18. Retornos

Tipo	Descrição
Número	Identificador exclusivo da operação de execução da função. Use este valor no método helpers - helpers.timing.clearInterval(Number timeoutId) se precisar cancelar esta operação.

Este exemplo de código mostra como atualizar o carimbo de data/hora em uma página a cada segundo. Esta função pode ser invocada por um usuário que clica no botão Habilitar atualização automática em uma página.

function handler({api, helpers}) {
  // Every one second, refresh the value of current timestamp client state parameter
  const intervalId = helpers.timing.setInterval(() => {
    api.setState('currentTimestamp', new Date().toString())
  }, 1000);

  // The interval ID is kept in state to use when calling the helpers.timing.clearInterval() method at a later point
  api.setState('intervalId', intervalId);
}

helpers - helpers.timing.setTimeout (função fn, atraso de número)

Executa a função especificada, após o atraso especificado.

Ao contrário do método JavaScript nativo setTimeout(), este método não é compatível com a passagem de uma cadeia de caracteres de código para avaliar como o primeiro argumento. Todos os argumentos adicionais são passados para a própria função.

Tabela 19. Parâmetros

Nome	Tipo	Descrição
fn	Função	Função a ser executada.
atraso	Número	Período de espera antes de chamar a função especificada. Unidade: Milissegundos

Tabela 20. Retornos

Tipo	Descrição
Número	Identificador exclusivo da operação de execução da função. Use este valor no método helpers - helpers.timing.clearTimeout(Número timeoutId) se precisar cancelar esta operação.

Este exemplo de código mostra como definir um temporizador de 20 minutos. Você pode associar esta função a um botão Lembrar-me em 20 minutos.

function handler({api, helpers}) {
  const timeoutId = helpers.timing.setTimeout(() => {
    api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
      id: 'alert5',
      status: 'high',
      icon: 'info-circle-outline',
      content: 'Try to look away at something that is 20 feet away from you for a total of 20 minutes.',
      action: { type: 'dismiss' }
    });
  }, 20 * 60 * 1000);

  // The timeout ID is kept in state to use when calling the helpers.timing.clearTimeout() method at a later point
  api.setState('timeoutId', timeoutId);
}

helpers - helpers.translate (cadeia de caracteres de mensagem, cadeia de caracteres de tokens)

Recupera e traduz de forma assíncrona a mensagem especificada com base no idioma da sessão do usuário atual.

Você pode usar este método com api - setState(cadeia de caracteres "stateParam", qualquer valor) para vincular o valor traduzido a outros campos na página.

Nota:

Você pode chamar este método usando uma promessa ou assíncrono e aguardar. Os exemplos de código abaixo mostram ambas as implementações.

Tabela 21. Parâmetros

Nome	Tipo	Descrição
message	Cadeia de caracteres	Mensagem a ser traduzida.
tokens	Cadeia de caracteres	Opcional. Lista separada por vírgulas de parâmetros a serem usados para substituir variáveis de cadeia de caracteres. Por exemplo: helpers.translate('Text {0} {1}', 'to', 'translate');

Tabela 22. Retornos

Tipo	Descrição
Cadeia de caracteres	Cadeia de caracteres de texto traduzido.

O exemplo a seguir mostra como passar referências de campo de tabela para incorporar nas variáveis correspondentes em uma cadeia de caracteres, usando uma promessa.

function handler ({api, helpers}) {
  helpers.translate('Welcome {0} {1}!', user.firstName, user.lastName)
    .then((translatedText) => {
      api.setState('greeting', translatedText);
    });
}

O exemplo a seguir mostra como usar async e await em sua função em vez de uma promessa.

async function handler ({api, helpers}) {
  const translatedText = await helpers.translate('Welcome to {0}', 'ServiceNow');
    api.setState('greeting', translatedText);
}