Qualificadores de referência

Versão de lançamento: Australia

Atualizado 12 de mar. de 2026

7 min. de leitura

Use qualificadores de referência para filtrar os dados retornados para um campo de referência.

R campo de referência armazena um link (referência) para um campo em outra tabela, disponibilizando os registros/campos na tabela referenciada para o formulário que contém o campo de referência.

Por exemplo, o. Atribuído a. O campo na tabela Incidente é uma referência à tabela Usuário [sys_user]. Por padrão, todos os valores do campo que está sendo referenciado aparecem em pesquisa de referência e pode ser acessado diretamente por meio do campo de referência (digite adiante). Expandindo o exemplo anterior, se um qualificador de referência não estiver definido, todos os usuários na tabela Usuário aparecerão na pesquisa de referência. Incluindo os usuários inativos. Às vezes, essa pode ser a funcionalidade desejada. No entanto, em outros casos, somente um subconjunto dos valores disponíveis pode ser desejado. Nesse caso, crie um qualificador de referência para filtrar os dados disponíveis para que somente os valores desejados sejam retornados e disponibilizados para o formulário. Como somente os usuários ativos ou usuários que têm uma função específica. Os qualificadores de referência são robustos e podem consistir em condições simples E/OU, JavaScript em linha ou complexas inclusão de script .

Você pode modificar o qualificador de referência de uma tabela e qualquer tabela baseada nessa tabela (primária ou estendida), definindo um qualificador de referência por meio de Entrada do dicionário formulário. Você também pode modificar o qualificador de referência somente em uma tabela estendida e seus secundários (não na tabela primária), por meio de um substituição de dicionário . Você só pode definir um qualificador de referência único por campo, por formulário/tabela. Os qualificadores de referência não são aplicáveis aos construtores de condições. Para obter informações sobre como usar filtragem em construtores de condições, consulte Crie uma opção de filtro dinâmico .

Nota:

A criação de qualificadores de referência requer conhecimento da ServiceNow subjacente modelo de dados (tabelas e campos) e conhecimento do Serviços da web e. Scripts .
Para restringir quais dados os usuários específicos podem acessar, use ACLs e não qualificadores de referência.

Você pode definir um qualificador de referência usando um dos métodos a seguir.

Qualificador de referência simples

Os qualificadores de referência simples usam instruções AND/OR (condições) para criar filtros simples. Use qualificadores de referência simples ao filtrar condições como se uma empresa está ativa, um usuário tem uma função específica e/ou um chamador está em um fuso horário específico. Os qualificadores de referência simples podem ter no máximo 13 condições de qualificador de referência. Para obter informações adicionais sobre como usar construtores de condições, consulte Condition builder.

Qualificadores de referência dinâmica

Os qualificadores de referência dinâmica permitem que você use um Crie uma opção de filtro dinâmico para executar uma consulta em um campo de referência para filtrar o conjunto de dados retornado. As opções de filtro dinâmico são filtros armazenados que podem conter Cadeias de caracteres de consulta codificadas , Javascript ou script inclui e pode ser usado em vários qualificadores de referência dinâmica. As mudanças feitas em uma opção de filtro dinâmico se aplicam automaticamente a todos os qualificadores de referência que usam a mesma opção de filtro dinâmico. Use este tipo de qualificador de referência quando quiser usar o mesmo filtro em vários formulários ou para fornecer funcionalidade de filtro para implementadores "sem conhecimento de código".

A instância base fornece várias opções de filtro dinâmico OOB. Se não existir uma opção de filtro dinâmico que atenda às suas necessidades, você poderá criar uma nova opção de filtro dinâmico que seja específica para seus requisitos. Um exemplo de uma opção de filtro dinâmico OOB é o qualificador de referência no ID do modelo Campo em um formulário de item de configuração, como o formulário de computador. O qualificador de referência chama o. Qualificador do modelo de IC opção de filtro dinâmico, que, por sua vez, chama o. ModelAndCategoryFilters inclusão de script. Este script inclui filtros do conjunto de dados com base na classe do IC. As únicas opções para o ID do modelo são opções que pertencem à mesma classe que o IC atual. Por exemplo, somente ICs que pertencem à classe de computador estão disponíveis no ID do modelo Campo no formulário de computador.

Para localizar as opções de filtro dinâmico disponíveis, navegue até Definição do sistema → Opções de filtro dinâmico . No canto direito da lista Opções de filtro dinâmico, clique no ícone de filtro e crie a condição de filtro A opção de referência está disponível para verdadeiro . São exibidas todas as opções de filtro dinâmico que podem ser usadas em qualificadores de referência dinâmica.

Qualificador de referência avançado

Os qualificadores de referência avançados permitem definir uma cadeia de caracteres de consulta codificada em linha ou filtro JavaScript (código real ou o nome de uma inclusão de script existente ou regra de negócios) diretamente no Qual. De referência campo do qualificador de referência. Semelhante aos outros tipos de qualificador de referência, quando o formulário é carregado, o filtro é executado e somente os registros que correspondem ao filtro aparecem no campo de referência. Use este tipo de qualificador de referência para implementações que exigem apenas um filtro simples e exclusivo, que não pode ser manipulado por um qualificador de referência simples e não é usado em vários campos de referência.

Nota:

Como uma prática recomendada, faça chamadas JavaScript para funções em um script incluírem em vez de uma regra de negócios global.

Um exemplo de uma cadeia de caracteres de consulta codificada é verdadeiro , que retorna todas as empresas designadas como fornecedores. Inserir esta cadeia de caracteres é o mesmo que usar o construtor de condições, conforme mostrado no exemplo do qualificador de referência simples. Para obter informações adicionais sobre sintaxe de cadeia de caracteres de consulta codificada válida e exemplos, consulte Cadeias de caracteres de consulta codificadas .

Um exemplo de uma chamada JavaScript é MyScriptInclude().my_refqual() . Este código chama a função meu_refqual() na inclusão de script MyScriptInclude() . A função deve retornar uma cadeia de caracteres de consulta que possa filtrar as opções disponíveis em um campo de referência.

Nota:

Você também pode usar filtros JavaScript codificados, como "você pode usar o javascript: "u_active" ou "u_hr_service" ou "current.hr_service" nos qualificadores de referência.

Em outro exemplo, se você estiver tentando filtrar com base na empresa atual, você não precisa usar um script de pesquisa, mas pode simplesmente adicionar esta linha ao qualificador dinâmico:

return "company=" + current.company;

Você também pode simplificar isso e usar um qualificador de referência avançado em vez de um dinâmico:

javascript:"company=" + current.company

Para obter um exemplo adicional, configurar o campo de referência para mostrar somente usuários de um grupo específico, consulte Como selecionar somente usuários de um grupo específico em um campo de referência [KB0831564] artigo no Now Support Base de conhecimento

Qualificadores de referência e listas relacionadas

Quando um campo aparece em vários Listas relacionadas em uma exibição de formulário única, pode ser necessário validar qual lista relacionada está sendo referenciada para criar corretamente o qualificador de referência para o campo. Nesta situação, configure o controle de lista para a lista relacionada e insira um marcador exclusivo no Marcador de edição de lista campo. Este valor de marcador está disponível para filtrar scripts como uma variável chamada ListEditRefQualTag . O código de inclusão de script a seguir é um exemplo de uma função que usa esse tipo de marcador.

// Advanced reference qualifier on the CI Relationship Child field that takes into account
// the related list that we are editing the child field on, if the field is being edited
// from a tagged related list. 
 
 cmdb_rel_ci_child_refQual:function(){ 
 
  if(listEditRefQualTag =="application") return "sys_class_name = cmdb_ci_appl";
 
  if(listEditRefQualTag =="database") return "sys_class_name = cmdb_ci_database"
 
  }

Usando a sintaxe atual do JavaScript nos qualificadores de referência

atual É um objeto JavaScript que contém os campos e valores de campo do registro ativo (atual). Para formulários, este é o registro exibido (carregado) no formulário. Nos qualificadores de referência avançados e dinâmicos, você pode usar o JavaScript atual objeto para definir filtros, como current.company .

Este JavaScript, em um qualificador de referência, retorna somente os registros da tabela referenciada que são iguais ao valor do campo Empresa do registro atual. Então, se o valor que aparece em Empresa O campo é acme, o JavaScript retorna todos os registros de campo de referência cujo valor de empresa é igual a acme (empresa "acme"). Se você abrir um registro cujo valor da empresa é "ViewRite", o JavaScript será resolvido para empresa "ViewRite".

Todos os campos no formulário carregado no momento (tabelas) estão disponíveis para uso com atual objeto. Uso ponto-walking para acessar valores em uma tabela, incluindo a tabela referenciada. Por exemplo, no formulário Incidente, o. Atribuído a. O campo faz referência à tabela Usuário. Para acessar o endereço de e-mail do usuário, use a seguinte sintaxe: e-mail .