Exemplos do campo de pesquisa externa em um formulário personalizado

Última atualização: 23 de outubro de 2024

Criado para:

  • Administrador

Um campo de pesquisa externo em um formulário personalizado chama uma API externa e retorna valores como opções em um campo suspenso. Os usuários que trabalham com o objeto ao qual o formulário personalizado está anexado podem selecionar uma ou mais dessas opções na lista suspensa.

Este artigo fornece exemplos de como usar o campo de pesquisa externa para chamar a mesma instância do Workfront ou uma API pública. Você também pode usar a Pesquisa externa para se comunicar com um sistema externo, como Jira, Salesforce ou ServiceNow.

Para obter mais informações sobre como adicionar um campo de pesquisa externa a um formulário personalizado e definições adicionais dos componentes de pesquisa externa, consulte Criar um formulário personalizado.

Configurar um campo de pesquisa externo para a mesma instância do Workfront

Você pode usar a Pesquisa externa para trazer dados da sua instância do Workfront para o formulário personalizado.

Usar valores de campo nativos do Workfront na pesquisa externa

Este exemplo mostra como chamar a API do Workfront e trazer dados do campo "Consulta de status" existente para o campo de pesquisa externa.

  1. Abra o formulário personalizado.

  2. No lado esquerdo da tela, encontre Pesquisa externa e arraste-a para uma seção da tela.

  3. Insira o Rótulo e o Nome do campo.

  4. Selecione o Formato para o campo.

  5. Insira a chamada de API no campo URL da API base.

    • Para fazer referência à mesma instância do Workfront em que o formulário personalizado está, use $$HOST para o URL.
    • Para filtrar os resultados com base na consulta de um campo diferente, adicione $$QUERY.

    Exemplo
    $$HOST/attask/api/v15.0/project/search?status={DE:StatusQuery}&$$QUERY

  6. Revise as Dependências dos campos aos quais este campo de pesquisa faz referência na API.

    Um campo de dependência pode ser qualquer campo personalizado ou nativo existente na página de detalhes do objeto.

    Neste exemplo, o {DE:StatusQuery} será substituído pelo valor do campo personalizado StatusQuery.

  7. Selecione o Método HTTP.

    Isto provavelmente será Obter.

  8. Insira o Caminho JSON para obter os resultados da sua chamada à API.

    Exemplo
    $.data[*].name

    NOTE
    As informações do Cabeçalho não são necessárias para uma chamada para a mesma instância do Workfront.

  9. Clique em Aplicar.

    Configuração da chamada de API para o Workfront no formato personalizado

    Quando o formulário personalizado é adicionado a um objeto do Workfront (neste exemplo, um projeto), ele é semelhante a este.

    Formulário personalizado com campo de pesquisa externo

    Opções de pesquisa externa com base no status

Usar valores de campo personalizado na pesquisa externa

Este exemplo mostra como chamar a API do Workfront e trazer dados de um campo personalizado para o campo de pesquisa externo. O exemplo de campo personalizado é chamado de "Cores personalizadas".

  1. Abra o formulário personalizado.

  2. No lado esquerdo da tela, encontre Pesquisa externa e arraste-a para uma seção da tela.

  3. Insira o Rótulo e o Nome do campo.

  4. Selecione o Formato para o campo.

  5. Insira a chamada da URL da API no campo URL da API de base.

    Exemplo
    $$HOST/attask/api/v18.0/PORT/search?ID={portfolioID}&fields=parameterValues

  6. Revise as Dependências dos campos aos quais este campo de pesquisa faz referência na API.

    Um campo de dependência pode ser qualquer campo personalizado ou nativo existente na página de detalhes do objeto.

  7. Selecione o Método HTTP.

    Isto provavelmente será Obter.

  8. Insira o Caminho JSON para obter os resultados da sua chamada à API.

    Exemplo
    $.data[*].parameterValues.["DE:Combo Colors"]

    • "parameterValues" refere-se a qualquer campo personalizado no Workfront para o objeto em que você está.
    • Neste exemplo, "DE:Combo Colors" é o campo personalizado específico que contém os valores que você deseja recuperar.
    NOTE
    As informações do Cabeçalho não são necessárias para uma chamada para a mesma instância do Workfront.

  9. Clique em Aplicar.

    Quando o formulário personalizado é adicionado a um objeto do Workfront, todos os valores do campo "Cores de combinação" são exibidos na lista suspensa do campo Pesquisa externa.

Configurar um campo de pesquisa externo para a API do Workfront Planning

Um endpoint está disponível na API do Workfront Planning para pesquisar registros por ID de tipo de registro por meio do método Get. Você pode usar esse endpoint para fazer referência a registros do Planning em campos de pesquisa Externos.

  • URL da API de Base: $$HOST/maestro/api/v1/records/search?recordTypeId={recordTypeID}

  • Método HTTP: Get

  • Caminho JSON: $.records[*].data.{fieldID}

    {fieldID} é o campo a ser exibido nos resultados da pesquisa de pesquisa externa no formulário personalizado para usuários finais.

Para obter mais informações, consulte API do Workfront Planning.

Configurar um campo de pesquisa externo para uma API pública

Você pode usar a pesquisa externa para chamar uma API externa e pública e recuperar dados.

Este exemplo mostra como chamar uma API de países (como https://api.first.org/data/v1/countries) para que você não precise codificar todos os nomes de países nas opções suspensas.

  1. Abra o formulário personalizado.

  2. No lado esquerdo da tela, encontre Pesquisa externa e arraste-a para uma seção da tela.

  3. Insira o Rótulo e o Nome do campo.

  4. Selecione o Formato para o campo.

  5. Insira a chamada da URL da API no campo URL da API de base.

    • Você pode adicionar $$QUERY para implementar a filtragem de consultas para seus usuários finais.

    Exemplos
    Lista todos os países: https://api.first.org/data/v1/countries

    Permite que o usuário pesquise por qualquer país no campo suspenso: https://api.first.org/data/v1/countries?q=$$QUERY

    Permite que o usuário procure por um país em uma região: https://api.first.org/data/v1/countries?region={DE:Region}&q=$$QUERY

    • As regiões disponíveis são definidas em um campo personalizado separado no Workfront.
    • Quando o usuário seleciona uma região no formulário, o campo Pesquisa externa mostra apenas os países dessa região (qual país está em qual região está definida na API). O usuário também pode pesquisar por um país na região selecionada.

  6. Revise as Dependências dos campos aos quais este campo de pesquisa faz referência na API.

    Um campo de dependência pode ser qualquer campo personalizado ou nativo existente na página de detalhes do objeto.

    Neste exemplo, o {DE:Region} será substituído pelo valor do campo personalizado Região.

  7. Selecione o Método HTTP.

    Isto provavelmente será Obter.

  8. Insira o Caminho JSON para obter os resultados da sua chamada à API.

    Essa opção permite extrair dados do JSON retornado pelo URL da API. Ela serve como uma maneira de selecionar quais valores dentro do JSON aparecerão nas opções suspensas.

    Exemplo
    $.data[*].country

  9. (Opcional) Clique em Adicionar cabeçalho e digite ou cole o par de valores chave necessário para autenticação com a API.

    NOTE
    Os campos de Cabeçalho não são um local seguro para armazenar credenciais, e você deve ter cuidado com o que digitar e salvar.

  10. (Opcional) Selecione Seleção múltipla para permitir que o usuário selecione mais de um valor na lista suspensa.

  11. Clique em Aplicar.

    Configuração da chamada de API para API pública no formato personalizado

    Quando o formulário personalizado é adicionado a um objeto do Workfront (neste exemplo, um projeto), ele é semelhante a este.

    Formulário personalizado com campo de pesquisa externo

    Opções de pesquisa externa para um país com base na região