Qualificadores de referência

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

Um 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 campo Atribuído a na tabela Incidente é uma referência à tabela Usuário [sys_user]. Por padrão, todos os valores do campo que está sendo referenciado aparecem na pesquisa de referência e podem ser acessados diretamente por meio do campo de referência (digitação antecipada). 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 que estão inativos. Às vezes, essa pode ser a funcionalidade desejada. Em outros casos, no entanto, 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. Por exemplo, 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 E/OU simples, JavaScript em linha ou inclusão de scriptcomplexo.

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

Nota:

• Criar qualificadores de referência requer conhecimento do modelo de dados subjacente da ServiceNow (tabelas e campos) e conhecimento dos serviços Web e scripts.
• Para restringir quais dados 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 seguintes métodos.

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 em condições como se uma empresa está ativa, um usuário tem uma função específica e/ou um solicitante 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ção, consulte Condition builder.

Figura 1. Exemplo de qualificador de referência simples

Qualificadores de referência dinâmica

Os qualificadores de referência dinâmicos permitem que você use uma opção Criar um 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 inclusões de script e podem ser usadas em vários qualificadores de referência dinâmicos. 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 a 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 campo ID do modelo em um formulário de item de configuração, como o formulário Computador. O qualificador de referência chama a opção de filtro dinâmico Qualificador de modelo de IC, que por sua vez chama a inclusão de script ModelAndCategoryFilters. Esta inclusão de script filtra o 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 do IC atual. Por exemplo, somente ICs que pertencem à classe Computador estão disponíveis no campo ID do modelo no formulário 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 Disponível para qualificador de referência verdadeiro. Todas as opções de filtro dinâmico que podem ser usadas em qualificadores de referência dinâmicos são exibidas.

Figura 2. Exemplo de qualificador de referência dinâmico

Qualificador de referência avançado

Os qualificadores de referência avançados permitem que você defina uma cadeia de caracteres de consulta codificada em linha ou um filtro JavaScript (código real ou o nome de uma inclusão de script ou regra de negócios existente) diretamente no campo Qualificador de referência do qualificador de referência. Semelhante a 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 tratado por um qualificador de referência simples e não é usado em vários campos de referência.

Nota:

Como prática recomendada, faça chamadas JavaScript para funções em uma inclusão de script em vez de uma regra de negócios global.

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

Figura 3. Exemplos de qualificador de referência avançado

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

Nota:

Você também pode usar filtros JavaScript codificados, como javascript:'u_active=true^' + "u_hr_service="+current.hr_service em qualificadores de referência.

Em outro exemplo, se você estiver tentando filtrar com base na empresa atual, não precisará usar um script de pesquisa, mas poderá simplesmente adicionar esta linha ao seu 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

Listas relacionadas e qualificadores de referência

Quando um campo aparece em várias Listas relacionadas em uma única exibição de formulário, 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 campo Marcador de edição de lista. 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"
 
  }

Uso da sintaxe atual Javascript em qualificadores de referência

current é 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 objeto JavaScript atual para definir filtros como javascript:"company=" + 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 da empresa do registro atual. Portanto, se o valor exibido no campo Empresa for Acme, o JavaScript retornará todos os registros de campo de referência cujo valor da empresa seja igual a Acme (company="Acme"). Se você abrir um registro cujo valor da empresa seja "ViewRite", o JavaScript será resolvido para company="ViewRite."

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

• Configurar qualificadores de referência
  Os administradores do sistema podem configurar qualificadores de referência que permitem a filtragem do campo de referência associado.
• O operador INSTANCEOF em qualificadores de referência
  Você pode usar o operador INSTANCEOF em um qualificador de referência para encurtar ou simplificar um qualificador de classe complexo.

Tópicos relacionados

• Criar uma opção de filtro dinâmico
• Criar filtros com script
• Classificações do CMDB