Criar definição de scripts para uma tabela remota

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 7 min. de leitura

    • Defina scripts para uma tabela remota para recuperar dados de uma fonte de dados externa ou editar dados na fonte externa.

    Antes de Iniciar

    Função necessária: delegado_developer com permissões Permitir script ou administrador

    Por Que e Quando Desempenhar Esta Tarefa

    O Now Platform recupera e armazena em cache os dados da tabela remota executando o script de consulta em uma fonte de dados externa para que você possa exibi-la ou modificá-la. Indique também como e por quanto tempo esses dados externos serão armazenados em cache na memória.

    Procedimento

    1. Navegar até Tudo > Definição do Sistema > Tabelas Remotas > Definição.
    2. Selecione Novo.
    3. No formulário, preencha os campos.
      Controle Descrição
      Nome

      Nome do script que você está criando para associar à tabela remota selecionada.
      Tabela
      Nome da tabela remota que você deseja associar ao script que você está criando.
      • Para uma tabela remota em uma aplicação com escopo, o nome é prefixado com um identificador de namespace e a cadeia de caracteres st_ para indicar que é remoto e faz parte de uma aplicação.
      • Para uma tabela remota na aplicação global, o nome é prefixado com a cadeia de caracteres u_st_.
      Aplicação Aplicação associada a esta tabela remota. Se você estiver trabalhando em uma aplicação ou criando uma tabela remota a partir de um registro de aplicação, o campo será padronizado para essa aplicação. Caso contrário, o padrão do campo é Global. Todos os registros criados a partir do registro da tabela, como módulos e regras de segurança, são atribuídos a este aplicativo por padrão.
      Ativo Opção para ativar o script que você está associando à tabela remota. Você pode ter várias definições de script inativas para uma tabela remota, mas só pode ter uma definição de script ativa. Ao ativar uma definição de script, você a associa à tabela remota para que possa recuperar e armazenar em cache os dados externos.
      Avançado Opção para acessar configurações avançadas de cache e edição.
      As configurações de cache designam como o cache de memória deve operar no Now Platform para esta tabela remota.
      Nota:
      Somente usuários avançados devem definir parâmetros de cache para uma tabela remota.
    4. Opcional: Se você selecionou a opção Avançado, na seção Avançado, preencha os campos.
      Nota:
      Por padrão, os dados externos são armazenados em cache na memória pelo usuário.
      Campo Descrição
      TTL do cache Tempo de vida do cache, expresso em segundos, em que os dados externos são armazenados em cache na memória para esta definição de script de tabela remota. Por exemplo, insira 300 para armazenar em cache os dados na memória por 5 minutos.

      O valor padrão é 0, o que significa que os dados não são armazenados em cache e são recuperados sempre. O valor máximo é 60 minutos (3600 segundos).
      Nível de Isolamento de Cache Armazene em cache os resultados da consulta para cada usuário ou em todos os usuários.
      • Cache por usuário: os resultados da consulta em cache devem ser específicos para o usuário conectado. Este é o valor padrão.
      • Cache compartilhado do sistema: os resultados da consulta em cache devem ser os mesmos para todos os usuários.
      Capacidade aprimorada Opção para selecionar a capacidade aprimorada para oferecer suporte a mais de 1000 linhas em uma tabela remota.
      Nota:
      Se o tamanho dos dados recuperados da fonte externa for pequeno, use o limite padrão de 1000 linhas em uma tabela remota para minimizar os tempos de consulta. Você pode usar o recurso Capacidade Estendida se o tamanho dos dados recuperados for grande e puder ter menos desempenho.

      A opção Capacidade aprimorada não será compatível se Editável estiver selecionado.
      Editável Opção para oferecer suporte à edição da tabela remota e sua fonte de dados externa da instância. Use a API v_record para personalizar definições de script para inserir, atualizar e excluir dados na tabela.
    5. Personalize as seguintes definições de script usando as APIs v_table, v_querye v_record.

      Para obter mais informações sobre essas APIs, consulte v_table – Scoped, Global, v_query – Scoped, Globale v_record - Scoped, Global.

      Definição de script Descrição
      Consulta

      A definição do script de consulta recupera dados da fonte externa para incluir na tabela remota. Na seção Consulta, personalize o script usando as APIs v_table e v_query.

      Sempre que uma lista que contém dados externos de uma tabela remota é atualizada, os scripts de consulta associados são executados.

      (function executeQuery(v_table, v_query) {
     // Parameters:
     //      v_table - object to record response:
     //          v_table.addRow({ ... })                - adds a row to the result set.
     //              keys are the column names of the table definition.
     //              sys_id must be non-empty and uniquely identify each row.
     //                  the above rule will be strictly enforced for editable tables, and generate warnings for read-only tables.
     //                  sys_id will be supplied to the Update, and Delete scripts to specify the row's identity.
 
     //      v_query - the query definition:
     //          v_query.getEncodedQuery()              - encoded querystring
     //          v_query.getCondition(field)            - encoded querystring for the given field (includes field name, operator, and value)
     //          v_query.getParameter(field)            - parameter for the given field (only includes value for equality conditions)
     //          v_query.isGet()                        - whether the query is a single get by sys_id
     //          v_query.getSysId()                     - parameter for sys_id field
     //          v_query.isTextSearch()                 - whether the query contains a text query parameter
     //          v_query.getTextSearch()                - text search query parameter (internal field name 123TEXTQUERY321)
     //          v_query.getFirstRowWanted()            - the first row to include, don't use with caching
     //          v_query.getLastRowWanted()             - the last row to include, don't use with caching
     //          v_query.setLastErrorMessage(message)   - the message is visible from GlideRecord.getLastErrorMessage()
 
     // Sample code:
     //  try {
     //      retrieve-rows-from-external-system;     //      if (there-was-an-error) {
     //          var message = ...;     //          v_query.setLastErrorMessage(message);
     //          return;
     //      }
     //
     //      for (var row in rows) {
     //          v_table.addRow(row);
     //      }
     //  } catch (ex) {
     //      var message = ex.getMessage();
     //      v_query.setLastErrorMessage(message);
     //  }
 
  })(v_table, v_query);
      Inserir

      A definição de script de inserção adiciona um registro à origem externa. Esta definição de script estará disponível somente se você tiver selecionado a opção avançada Editável. Na seção Inserir, personalize o script usando a API v_record.

      Cada vez que um registro é adicionado a uma tabela remota, os scripts de inserção associados são executados.

      function executeInsert(v_record) {
     // Parameters:
     //      v_record is a map of field names and values containing the sys_id of the
     //              record and the fields that need to be inserted in the record on the
     //              remote system (source of data)
     
     //          v_record.<field_name>                   - fields in the remote table GlideRecord
     //          v_record.setLastErrorMessage(message)   - signal an error
 
     // Sample code:
     //  try {
     //      update-external-system;
     //      if (there-was-an-error) {
     //          var message = ...;
     //          v_record.setLastErrorMessage(message);
     //      }
     //  } catch (ex) {
     //      var message = ex.getMessage();
     //      v_record.setLastErrorMessage(message);
     //  }
  })(v_record);
      Atualizar

      A definição de script de atualização modifica um registro na origem externa. Esta definição de script estará disponível somente se você tiver selecionado a opção avançada Editável. Na seção Atualizar, personalize o script usando a API v_record.

      Cada vez que um registro é atualizado em uma tabela remota, os scripts de atualização associados são executados.

      Nota:
      Se vários usuários atualizarem o mesmo registro ao mesmo tempo, o valor no sistema remoto será da última chamada de atualização executada.
      (function executeUpdate(v_record, v_changed_fields) {
     // Parameters:
     //    v_record - a map of field names and values containing the sys_id of the record
     //          v_record.<field_name>                   - fields in the remote table GlideRecord
     //          v_record.setLastErrorMessage(message)   - signal an error
     //    v_changed_fields - a map of field names and values containing the sys_id of the record
     //          v_changed_fields.<field_name>           - changed fields in the remote table GlideRecord
 
     // Sample code:
     //  try {
     //      update-external-system;
     //      if (there-was-an-error) {
     //          var message = ...;
     //          v_record.setLastErrorMessage(message);
     //      }
     //  } catch (ex) {
     //      var message = ex.getMessage();
     //      v_record.setLastErrorMessage(message);
     //  }
  })(v_record, v_changed_fields);
      Excluir

      A definição de script de exclusão remove um registro da origem externa. Esta definição de script estará disponível somente se você tiver selecionado a opção avançada Editável. Na seção Excluir, personalize o script usando a API v_record.

      Cada vez que um registro é excluído de uma tabela remota, os scripts de exclusão associados são executados.

      (function executeDelete(v_record) {
     // Parameters:
     //      v_record - a map of field names and values containing (among others) the
     //              sys_id of the record that needs to be deleted on the remote system
     //          v_record.<field_name>                  - fields in the remote table GlideRecord
     //          v_record.setLastErrorMessage(message)   - signal an error
 
     // Sample code:
     //  try {
     //      update-external-system;
     //      if (there-was-an-error) {
     //          var message = ...;
     //          v_record.setLastErrorMessage(message);
     //      }
     //  } catch (ex) {
     //      var message = ex.getMessage();
     //      v_record.setLastErrorMessage(message);
     //  }
  })(v_record);
    6. Selecione Enviar.