API de tabela - ServiceNow Fluent

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

    • A API de tabela inclui objetos para definir tabelas [sys_db_object] em uma aplicação com escopo.

    Crie uma tabela usando o objeto Tabela. Na propriedade de esquema, adicione objetos de coluna, como StringColumn ou IntegerColumn, para definir as colunas.

    Para obter informações gerais sobre administração de tabelas, consulte Table administration.

    Objeto de tabela

    Crie uma tabela [sys_db_object] em uma aplicação com escopo.

    Tabela 1. Propriedades
    Nome Tipo Descrição
    nome Cadeia de caracteres Obrigatório. Um nome para a tabela que começa com o escopo da aplicação e em letras minúsculas no seguinte formato:<scope> _<name> . O nome deve corresponder ao identificador de variável do objeto Tabela.
    Nota:
    Para adicionar colunas a uma tabela existente em um escopo da aplicação diferente, você pode fornecer o nome da tabela sem o escopo da aplicação seguido por como qualquer. Os nomes das colunas devem começar com o escopo da aplicação.

    Tamanho máximo: 80
    esquema Matriz Obrigatório. Uma lista de objetos de coluna. Para obter mais informações, consulte Objeto de coluna.
    estendidos Cadeia de caracteres O nome de qualquer outra tabela na qual a tabela se baseia.

    Estender uma tabela base incorpora todos os campos da tabela original e cria campos do sistema para a nova tabela. Se eles estiverem no mesmo escopo ou se puderem ser configurados a partir de outros escopos, você poderá estender as tabelas marcadas como extensíveis.
    rótulo Cadeia de caracteres ou matriz Um rótulo exclusivo para a tabela nas exibições de lista e formulário. Os rótulos de campo podem ser fornecidos como uma cadeia de caracteres ou uma matriz de objetos de rótulo. Para obter mais informações, consulte objeto de rótulo.

    Tamanho máximo: 80

    Padrão: o valor da propriedade de nome

    tela Cadeia de caracteres A coluna de exibição padrão. Use um nome de coluna da propriedade do esquema.
    extensível Booliano Sinalizador que indica se outras tabelas podem estender a tabela.
    Valores válidos:
    • verdadeiro: outras tabelas podem estender a tabela.
    • falso: outras tabelas não podem estender a tabela.

    Alterar esta propriedade de verdadeira para falsa impede a criação de tabelas secundárias adicionais, mas as tabelas secundárias existentes permanecem inalteradas.

    Padrão: falso
    live_feed Booliano Sinalizador que indica se os feeds de atividades estão disponíveis para registros na tabela.
    Valores válidos:
    • verdadeiro: feeds de atividades são fornecidos para registros na tabela. Esta opção adiciona a opção Mostrar Feed de atividades ( Mostrar ícone do Feed de atividades) no cabeçalho do formulário.
    • falso: feeds de atividades não são fornecidos para registros na tabela.

    Padrão: falso
    auto_number Objeto A configuração de numeração automática [sys_number] para uma tabela. Para obter mais informações, consulte objeto auto_number.
    acessível_de Cadeia de caracteres Os escopos da aplicação que podem acessar a tabela.
    Valores válidos:
    • público: a tabela pode ser acessada de todos os escopos da aplicação.
    • package_private: a tabela só pode ser acessada pelo escopo da aplicação em que está.

    Padrão: público
    caller_access Cadeia de caracteres O nível de acesso para solicitações entre escopos.
    Valores válidos:
    • restrito: as chamadas para o recurso devem ser aprovadas manualmente. As solicitações de acesso são rastreadas na tabela Acesso de solicitante restrito com um status de Solicitado.
    • acompanhamento: as chamadas para o recurso são aprovadas automaticamente. As chamadas são rastreadas na tabela Acesso de chamador restrito com um status de Permitido.
    • nenhum: chamadas entre escopos para o recurso são aprovadas ou negadas com base no valor da propriedadeaccess_from.

    Para obter mais informações, consulte Configurações de privilégio de acesso de chamador restrito.

    Padrão: nenhum
    ações Matriz Uma lista de opções de acesso.
    Valores válidos:
    • leitura: permite que objetos de script de outros escopos da aplicação leiam registros armazenados nesta tabela. Por exemplo, um script em outra aplicação pode consultar dados nesta tabela. O acesso de leitura é necessário para conceder outras operações de registro de API.
    • criar: permite que objetos de script de outros escopos da aplicação criem registros nesta tabela. Por exemplo, um script em outra aplicação pode inserir um novo registro nesta tabela.
    • atualização: permite que objetos de script de outros escopos da aplicação modifiquem registros armazenados nesta tabela. Por exemplo, um script em outra aplicação pode modificar um valor de campo nesta tabela.
    • excluir: permite que objetos de script de outros escopos da aplicação excluam registros desta tabela. Por exemplo, um script em outra aplicação pode remover um registro desta tabela.

    Padrão: ler
    allow_web_service_access Booliano Sinalizador que indica se os serviços web podem fazer chamadas para a tabela.
    Valores válidos:
    • verdadeiro: os serviços Web podem fazer chamadas para a tabela.
    • falso: os serviços Web não podem fazer chamadas para a tabela.

    Padrão: falso
    allow_new_fields Booliano Sinalizador que indica se a configuração de tempo de design de novos campos na tabela de outros escopos da aplicação deve ser permitida.
    Valores válidos:
    • verdadeiro: permite a configuração de tempo de design de novos campos na tabela de outros escopos da aplicação.
    • falso: não permite a configuração de tempo de design de novos campos na tabela de outros escopos da aplicação.

    Padrão: falso
    allow_ui_actions Booliano Sinalizador que indica se a configuração de tempo de design de ações de IU na tabela deve ser permitida a partir de outros escopos da aplicação.
    Valores válidos:
    • verdadeiro: permite a configuração do tempo de design de ações de IU na tabela de outros escopos da aplicação.
    • falso: não permite a configuração de tempo de design de ações de IU na tabela de outros escopos da aplicação.

    Padrão: falso
    allow_client_scripts Booliano Sinalizador que indica se a configuração de tempo de design de client scripts na tabela deve ser permitida a partir de outros escopos da aplicação.
    Valores válidos:
    • verdadeiro: permite a configuração de tempo de design de scripts de cliente na tabela de outros escopos da aplicação.
    • falso: não permite a configuração de tempo de design de client scripts na tabela de outros escopos da aplicação.

    Padrão: falso
    auditoria Booliano Sinalizador que indica se a criação, a atualização e a exclusão de todos os registros na tabela devem ser rastreadas.
    Valores válidos:
    • verdadeiro: rastreia a criação, a atualização e a exclusão de todos os registros na tabela
    • falso: não rastreia a criação, a atualização e a exclusão de todos os registros na tabela.

    Padrão: falso
    somente leitura Booliano Sinalizador que indica se os usuários podem editar campos na tabela.
    Valores válidos:
    • verdadeiro: os usuários não podem editar campos na tabela.
    • falso: os usuários podem editar campos na tabela.

    Padrão: falso
    índice_texto Booliano Sinalizador que indica se os mecanismos de pesquisa indexam o texto em uma tabela.
    Valores válidos:
    • verdadeiro: o texto da tabela está indexado.
    • falso: o texto da tabela não está indexado.

    Padrão: falso
    atributos Objeto Pares de chave e valor de quaisquer atributos de dicionário compatíveis [sys_schema_attribute]. Por exemplo:
    attributes: 
   {
      update_sync_custom: Boolean,
      native_recordlock: Boolean
   }
    Para obter mais informações, consulte Atributos de dicionário.
    índice Matriz Uma lista de referências de coluna para gerar índices no XML de metadados da tabela. O valor da propriedade do elemento deve corresponder à chave do objeto usada com o objeto Coluna.

    Um índice de banco de dados aumenta a velocidade de acesso aos dados da tabela com a despesa de usar armazenamento adicional.

    index: [
    {
        name: 'String',
        element: 'String',
        unique: Boolean
    },
    ...
]

    Para suporte autocompletável para colunas, atribua o objeto Tabela a uma variável exportada com o mesmo nome da propriedade de nome.

    import { Table, StringColumn } from "@servicenow/sdk/core";
import { myFunction } from "../server/myFunction.js"

export const x_snc_example_to_do = Table({
    name: 'x_snc_example_to_do',
    label: 'My To Do Table',
    extends: 'task',
    schema: {
        status: StringColumn({ label: 'Status' }),
        deadline: StringColumn({
            label: 'Deadline',
            active: true,
            mandatory: false,
            read_only: false,
            maxLength: 40,
            dropdown: 'none',
            attributes: { 
                update_sync: false,
            },
            default: 'today',
            dynamic_value_definitions: {
                type: 'calculated_value',
                calculated_value: '',
            },
            choices: {
                choice1: {
                    label: 'Choice1 Label',
                    sequence: 0,
                    inactive_on_update: false,
                    dependent_value: '5',
                    hint: 'hint',
                    inactive: false,
                    language: 'en',
                },
                choice2: { label: 'Choice2 Label', sequence: 1 },
            },
        }),
        dynamic1: StringColumn({
            dynamic_value_definitions: {
                type: 'calculated_value',
                calculated_value: myFunction,
            },
        }),
        dynamic2: StringColumn({
            dynamic_value_definitions: {
                type: 'dynamic_default',
                dynamic_default: `gs.info()`,
            },
        }),
        dynamic3: StringColumn({
            dynamic_value_definitions: {
                type: 'dependent_field',
                column_name: 'status',
            },
        }),
        dynamic4: StringColumn({
            dynamic_value_definitions: {
                type: 'choices_from_other_table',
                table: 'sc_cat_item',
                field: 'display',
            },
        }),
    },
    actions: ['create', 'read'],
    display: 'deadline',
    accessible_from: 'package_private',
    allow_client_scripts: true,
    allow_new_fields: true,
    allow_ui_actions: true,
    allow_web_service_access: true,
    extensible: true,
    live_feed: true,
    caller_access: 'none',
    auto_number: {
        number: 10,
        number_of_digits: 2,
        prefix: 'abc',
    },
    audit: true,
    read_only: true,
    text_index: true,
    attributes: {
        update_sync: true,
    },
    index: [
        {
            name: 'idx',
            element: 'status',
            unique: true,
        },
    ],
})

    Objeto de coluna

    Adicione uma coluna [sys_dictionary] a uma tabela.

    Adicione objetos de coluna na propriedade de esquema do objeto de tabela.

    Existem muitos tipos de colunas com base no tipo de campo. Objetos de coluna usam o formato<Type> Coluna em que é o tipo de campo. Para obter informações sobre os tipos de campo, consulte Field types reference.

    The following types of columns are supported: ListColumn, RadioColumn, StringColumn, ChoiceColumn, ScriptColumn, BooleanColumn, ConditionsColumn, DecimalColumn, IntegerColumn, VersionColumn, DomainIdColumn, FieldNameColumn, ReferenceColumn, TableNameColumn, UserRolesColumn, BasicImageColumn, DocumentIdColumn, DomainPathColumn, TranslatedTextColumn, SystemClassNameColumn, TranslatedFieldColumn, GenericColumn, DateColumn, DateTimeColumn, CalendarDateTime, BasicDateTimeColumn, DueDateColumn, CalendarDateTime, IntegerDateColumn, ScheduleDateTimeColumne OtherDateColumn.

    Tabela 2. Propriedades
    Nome Tipo Descrição
    rótulo Cadeia de caracteres ou matriz Um rótulo exclusivo para a coluna que aparece em cabeçalhos de lista e campos de formulário. Os rótulos de campo podem ser fornecidos como uma cadeia de caracteres ou uma matriz de objetos de rótulo. Para obter mais informações, consulte objeto de rótulo.

    Padrão: a chave usada para o objeto de coluna
    maxLength Número O tamanho máximo de valores na coluna.

    Um comprimento inferior a 254 aparece como um campo de texto de linha única. Qualquer coisa com 255 caracteres ou mais aparece como uma caixa de texto de várias linhas.

    Nota:
    Para evitar a perda de dados, diminua o tamanho de um campo de cadeia de caracteres somente quando estiver desenvolvendo uma nova aplicação e não quando um campo contiver dados.

    Padrão: 40
    ativo Booliano Sinalizador que indica se o campo deve ser exibido em listas e formulários.
    Valores válidos:
    • verdadeiro: exibe o campo.
    • falso: oculta o campo.

    Padrão: verdadeiro
    obrigatória Booliano Sinalizador que indica se o campo deve conter um valor para salvar um registro.
    Valores válidos:
    • verdadeiro: o campo deve conter um valor.
    • falso: o campo não é obrigatório.

    Padrão: falso
    somente leitura Booliano Sinalizador que indica se você pode editar o valor do campo.
    Valores válidos:
    • verdadeiro: você não pode alterar o valor e o sistema calcula e exibe os dados do campo.
    • falso: você pode alterar o valor do campo.

    Padrão: falso
    padrão Qualquer O valor padrão do campo ao criar um registro. O valor deve usar o tipo correto com base no tipo de coluna.
    escolhas Objeto Uma lista de opções [sys_choice] para uma coluna. Para obter mais informações, consulte objeto de escolhas.

    Esta propriedade se aplica somente a objetos ChoiceColumn e tipos de coluna que estendem as colunas de opção. Pode incluir uma matriz de valores primitivos ou uma série de objetos de opção.
    atributos Objeto Pares de chave e valor de quaisquer atributos de dicionário compatíveis [sys_schema_attribute]. Por exemplo:
    attributes: 
   {
      update_sync_custom: Boolean,
      native_recordlock: Boolean
   }
    Para obter mais informações, consulte Atributos de dicionário.
    função_definição Cadeia de caracteres A definição de uma função que o campo executa, como uma operação matemática, cálculo de comprimento de campo ou cálculo de dia da semana.

    Cada definição começa com glidefunction:, seguida pela operação a ser executada (como, concat), seguida pelos parâmetros da função. As constantes devem ser colocadas entre aspas simples.

    Por exemplo, a definição de função a seguir cria um campo que mostra a descrição resumida, seguida por um espaço e pelo nome do solicitante:
    function_definition: 'glidefunction:concat(short_description, ' ', caller_id.name)'

    Para obter mais informações sobre definições de função, consulte Function field.
    definições_de_valor_dinâmico Objeto Valores padrão que são gerados dinamicamente com base em filtros dinâmicos. Forneça uma combinação de um tipo e uma chave de comportamento relacionada para especificar padrões dinâmicos. Os seguintes tipos são compatíveis:
    • dynamic_default: forneça uma função da tabela Opções de filtro dinâmico [sys_filter_option_dynamic]. Para obter mais informações, consulte Create a dynamic filter option. Por exemplo:
      dynamic_value_definitions: {
   type: 'dynamic_default',
   dynamic_default: `gs.info()`,
},
    • dependente_field: forneça outro nome de coluna da mesma tabela. Por exemplo:
      dynamic_value_definitions: {
   type: 'dependent_field',
   column_name: 'status',
},
    • resolved_value: forneça uma função para calcular o valor. A função pode ser importada de um módulo JavaScript ou definida em linha. Por exemplo:
      dynamic_value_definitions: {
   type: 'calculated_value',
   calculated_value: function,
},
    • escolhas_de_outra_tabela: forneça opções de uma coluna em outra tabela. Por exemplo:
      dynamic_value_definitions: {
   type: 'choices_from_other_table',
   table: 'sc_cat_item',
   field: 'display',
},
    lista suspensa Cadeia de caracteres Uma opção de como uma lista de opções é exibida para exibições de lista e formulário da tabela. Esta propriedade se aplica somente a objetos ChoiceColumn e tipos de coluna que estendem as colunas de opção.
    Valores válidos:
    • nenhum: as escolhas não são impostas.
    • menu suspenso sem nenhum: um menu sem a opção -- Nenhum --. Se você selecionar esta opção, deverá configurar a propriedade padrão da coluna.
    • menu suspenso sem nenhum: um menu com a opção -- Nenhum --. O valor padrão é -- Nenhum --.
    • sugestão: as opções são exibidas em uma lista de valores sugeridos.

    Padrão: nenhum
    Os nomes de coluna são fornecidos como chaves de objeto emparelhadas com as definições de coluna.
    schema: {
   deadline: DateColumn({ label: 'Deadline' }),
   state: StringColumn({
      label: 'State',
      choices: {
         ready: { label: 'Ready' },
         completed: { label: 'Completed' },
         in_progress: { label: 'In Progress' },
      }   
   }),
   task: StringColumn({ label: 'Task', maxLength: 120 }),
}
    Se o nome da tabela não incluir o escopo da aplicação, os nomes das colunas deverão ser prefixados com o escopo da aplicação.
    schema: {
   x_scope_myColumn: StringColumn({...})
}

    objeto de escolhas

    Configure escolhas [sys_choice] para uma coluna em uma tabela.

    O objeto de escolhas é uma propriedade dentro do objeto Column. Use o objeto de escolhas com tipos de coluna compatíveis na propriedade de esquema de um objeto de tabela. Somente determinados tipos de coluna estendem o tipo de coluna de opção (ChoiceColumn) e podem incluir opções.

    Tabela 3. Propriedades
    Nome Tipo Descrição
    rótulo Cadeia de caracteres Obrigatório. O texto a ser exibido para a opção na lista.
    dependente_value Cadeia de caracteres Um valor que você mapeia para o Dependent_field na propriedade dynamic_value_definitions do objeto Column.
    dica Cadeia de caracteres Uma descrição resumida da opção que é exibida como dica de ferramenta ao passar o mouse sobre ela.
    idioma Cadeia de caracteres O código BCP 47 do idioma para a opção traduzida.

    Padrão: en
    sequência Números inteiros A ordem na lista de opções em que uma escolha ocorre.
    inativo Booliano Sinalizador que indica se a opção deve ser mostrada na lista.
    Valores válidos:
    • verdadeiro: a opção está oculta na lista.
    • falso: a opção aparece na lista.

    Padrão: falso

    O objeto de opções inclui uma série de objetos de opção, em que os nomes das opções são fornecidos como chaves de objeto emparelhadas com as definições de opções.

    choices: {
   choice1: {
      label: 'Choice1 Label',
      sequence: 0,
      inactive_on_update: false,
      dependent_value: '5',
      hint: 'hint',
      inactive: false,
      language: 'en',
   },
   choice2: { label: 'Choice2 Label', sequence: 1 },
}

    objeto de rótulo

    Configure um rótulo de campo [sys_documentation] para uma tabela ou coluna.

    O objeto de rótulo é uma propriedade dentro dos objetos Tabela e Coluna.

    Tabela 4. Propriedades
    Nome Tipo Descrição
    idioma Cadeia de caracteres O código BCP 47 do idioma do rótulo do campo. Um idioma pode ter apenas um rótulo, portanto, cada idioma deve ser exclusivo em uma matriz de objetos de rótulo.
    rótulo Cadeia de caracteres O texto do rótulo do campo no idioma especificado.
    dica Cadeia de caracteres Uma descrição resumida que é exibida como uma dica de ferramenta ao passar o mouse sobre o rótulo do campo.
    ajuda Cadeia de caracteres Informações adicionais sobre o campo. O texto de ajuda não é exibido no formulário ou nas exibições de lista da tabela.
    plural Cadeia de caracteres A forma plural do rótulo do campo.
    URL Cadeia de caracteres Um URL para uma página da Web que fornece informações sobre o campo. Quando uma URL é fornecida, o rótulo é exibido como um hiperlink.
    url_target Cadeia de caracteres Não usado (obsoleto). 
    label: [
   { 
      label: 'English description', 
      language: 'en', 
      hint: 'Provide a short description' 
   },
   {
      label: 'Description de español', 
      language: 'es' 
   },
]

    objeto auto_number

    Configure a numeração automática [sys_number] para uma tabela.

    O objeto auto_number é uma propriedade dentro do objeto Tabela.

    Tabela 5. Propriedades
    Nome Tipo Descrição
    prefixo Cadeia de caracteres Um prefixo para cada número de registro na tabela. Por exemplo, INC para Incidente.

    Padrão: pre
    número Números inteiros O número do registro base desta tabela. Os números de registro são incrementados automaticamente e o próximo número é mantido na tabela Contador [sys_number_counter].

    Se você definir o número de base com um valor maior do que o contador atual, o próximo número de registro usará o novo número de base. Caso contrário, o próximo número de registro usará o contador atual. O contador não é redefinido para um número base inferior a ele mesmo.

    Padrão: 1000
    número_de_dígitos Números inteiros O número mínimo de dígitos a serem usados após o prefixo.

    Zeros à esquerda são adicionados aos números automáticos, se necessário. Por exemplo, INC0001001 contém três zeros à esquerda. O número de dígitos pode exceder o tamanho mínimo. Por exemplo, se number_of_digits for 2 e mais de 99 registros forem criados na tabela, os números continuarão após 100 (como INC101).

    Aviso:
    Alterar este campo pode atualizar todos os valores numéricos dos registros existentes em uma tabela. Tenha cuidado ao alterar este campo em uma instância de produção.

    Padrão: 7

    		 
    auto_number: {
   prefix: 'TODO',
   number: 2000,
   digits: 9,
}