Listar campos e atributos de item de trabalho

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Os campos de item de trabalho são usados para acompanhar informações no Azure DevOps. Esses campos são definidos no nível da organização e são compartilhados entre todos os projetos da organização. Para revisar os campos definidos para sua organização, você pode usar uma das duas ferramentas a seguir, disponíveis para modelos de processo XML herdado e hospedado:

• Página da Web Campos de Processo >
• Work Item Field Explorer

Para obter uma descrição de cada campo definido com um processo do sistema, confira Índice de campo de item de trabalho.

Pré-requisitos

Permissões: para exibir os campos definidos para uma organização ou coleção, seja membro do grupo de aplicativos Usuários Válidos da Coleção de Projetos ou tenha a permissão Exibir informações no nível da instância definida como Permitir para a organização ou coleção.

Listar ou revisar campos

Para listar ou revisar campos, use uma das seguintes ferramentas com base em seu modelo de processo: Herdado, XML hospedado ou XML local. Para obter um índice de campos definidos dentro dos processos padrão, confira Índice de campo de item de trabalho.

Ferramenta	Herança	XML hospedado	XML local
Portal da Web: listar campos herdados e personalizados	✔️	✔️1
Gerenciador de campo de item de trabalho	✔️	✔️	✔️
ferramenta de linha de comando witadmin listfields	✔️	✔️	✔️

Observação

1. Há suporte apenas para processos padrão (Agile, CMMI, Scrum).

Campo de nomes e tipos de dados

Cada tipo de item de trabalho especifica os campos incluídos em itens de trabalho desse tipo. Cada campo tem vários atributos, muitos dos quais são definidos pelo sistema e imutáveis.

Os campos são definidos pelos três atributos a seguir:

• Tipo de dados: indica o tipo de dados que podem ser inseridos no campo, como Booleano, Duplo, Inteiro, HTML ou String. Para obter descrições detalhadas de cada tipo de dados, consulte Consultar campos, operadores e macros.
• Nome amigável: o nome amigável atribuído ao campo, usado ao selecionar um campo em uma cláusula de consulta. Esse nome pode ser diferente do nome exibido no formulário de item de trabalho.
• Nome de referência: o identificador usado ao criar consultas WIQL, modelos de item de trabalho improvisados, executar comandos da API REST ou definir definições de tipo de item de trabalho XML. O nome de referência é permanente e não pode ser alterado depois de definido.

Para obter uma descrição detalhada de cada atributo de campo e instruções sobre como listá-los, consulte Atributos de campo e Listar atributos de campo mais adiante neste artigo. Para obter uma visão geral dos WITs (tipos de item de trabalho) e itens de trabalho, consulte Acompanhar o trabalho com histórias de usuário, problemas, bugs, recursos e épicos.

O que é um campo? Como os nomes de campo são usados?

Cada tipo de item de trabalho inclui 31 campos do sistema e vários campos específicos do tipo. Os itens de trabalho são usados para planejar e acompanhar seu projeto.

Cada campo captura informações específicas sobre o trabalho a ser executado. Os valores atribuídos a esses campos são armazenados no armazenamento de dados de acompanhamento de trabalho, permitindo que você crie consultas que determinam o status e as tendências.

Para obter descrições e uso de cada campo definido para os principais processos do sistema — Agile, Basic, Scrum e CMMI — consulte o índice de campo Item de trabalho.

Nomes de campo

Um nome de campo de item de trabalho identifica com exclusividade cada campo de item de trabalho. Certifique-se de que seus nomes de campo sigam as seguintes diretrizes:

• Exclusividade: os nomes de campo devem ser exclusivos na conta ou na coleção de projetos.
• Comprimento: os nomes de campo devem conter 128 caracteres Unicode ou menos.
• Espaçamento: os nomes de campo não podem ter espaços à esquerda ou à direita ou conter dois ou mais espaços consecutivos.
• Composição: Os nomes dos campos devem incluir pelo menos um caractere alfabético.
• Caracteres proibidos: Os nomes dos campos não podem incluir os seguintes caracteres: .,;':~/*|?" &%$!+=()[]{}<>'.

Como os campos personalizados são definidos no nível da organização ou da coleção, você não pode adicionar um campo personalizado com o mesmo nome a vários processos.

Para saber mais, confira Convenções e restrições de nomenclatura.

Sistema e campos predefinidos

Um nome de campo de item de trabalho identifica exclusivamente cada campo no Azure DevOps. Certifique-se de que seus nomes de campo estejam em conformidade com as seguintes diretrizes:

• Exclusividade: os nomes de campo devem ser exclusivos em uma conta ou coleção de projetos.
• Comprimento: os nomes de campo devem ter 128 caracteres Unicode ou menos.
• Espaçamento: os nomes de campo não podem ter espaços à esquerda ou à direita ou conter vários espaços consecutivos.
• Composição: Os nomes dos campos devem incluir pelo menos um caractere alfabético.
• Caracteres proibidos: Os nomes dos campos não podem incluir os seguintes caracteres: .,;':~/*|?" &%$!+=()[]{}<>'.

Como os campos personalizados são definidos no nível da organização ou da coleção, você não pode adicionar um campo personalizado com o mesmo nome a vários processos.

Para saber mais, confira Convenções e restrições de nomenclatura.

Campos personalizados

Como os campos personalizados são definidos no nível da organização ou da coleção de projetos, você não pode adicionar um campo personalizado com o mesmo nome a vários processos.

Ao adicionar campos personalizados, observe os seguintes limites:

• Máximo de campos por tipo de item de trabalho (WIT): 64
• Máximo de campos por processo: 512

O tipo de dados do campo determina o tipo e o tamanho dos dados que podem ser armazenados no campo. Cada campo pode ter apenas um tipo definido em uma coleção de projetos, incentivando o uso de campos comuns em diferentes projetos e tipos de item de trabalho.

Quando você adiciona um campo personalizado a um processo herdado, Azure DevOps atribui um nome de referência prefixado com Custom seguido pelo nome do campo sem espaços. Por exemplo, adicionar um campo chamado DevOps Triage resulta no nome de referência Custom.DevOpsTriage. Espaços não são permitidos em nomes de referência.

Para saber mais, confira Convenções e restrições de nomenclatura.

Como posso determinar o tipo de dados de campo?

Você pode exibir o tipo de dados de campos definidos para sua organização abrindo a página >Campos do Processo.

Revisar lista de campos

Para revisar a lista de campos definidos para uma organização ou coleção, execute as seguintes etapas:

1. Selecione o logotipo do Azure DevOps para abrir Projetos. Escolha Configurações da organização.

   

2. Selecione Processar.

   

3. Selecione Campos.

   Os campos listados correspondem a todos os campos definidos para a organização ou coleção, que inclui todos os campos personalizados e os campos definidos para processos do sistema.

   

   Observação

   Se você não vir Campos, sua coleção usará o processo XML local. Não há suporte para a página Campos nesse processo.

   Para obter descrições, uso e nomes de referência de cada campo, consulte o índice de campo Item de trabalho. Além disso, você pode recuperar nomes de referência de campo usando o Campo de Tipos de Item de Trabalho – API REST de Lista.

Work Item Field Explorer

É possível pesquisar as atribuições dos atributos de campo usando a ferramenta Gerenciador de Campo de Item de Trabalho.

Para acessar o Explorador de Campos de Item de Trabalho, instale a Ferramenta Editor de Processo. Com base na versão instalada do Visual Studio, obtenha a Ferramenta Editor de Processos de uma das seguintes extensões.

• Visual Studio 2019 e 2022: a partir de agora, não há nenhuma extensão específica do Editor de Modelo de Processo disponível. Mas você ainda pode personalizar modelos de processo usando outras ferramentas, como qualquer editor de texto ou editor XML. Você também pode usar o portal da Web do Azure DevOps para determinadas personalizações, especialmente para processos herdados.
• Visual Studio 2017: Editor de Modelo de Processo TFS. Você também pode usar essa versão do Editor de Processos para modificar os formulários de item de trabalho de estilo antigo. Não é possível usá-lo para editar formulários associados aos novos formulários da Web.
• Visual Studio 2015: TFS Power Tools.

Atributos do campo

Há muitos atributos inalteráveis e ocultos para cada campo de item de trabalho. A tabela a seguir descreve cada atributo. Os atributos têm nomes diferentes, dependendo se você os recupera por meio da API REST Campos – Obter ou os exibe por meio da ferramenta Explorador de Campo de Item de Trabalho (WIFE).

Os atributos atribuídos a um campo dependem da plataforma e da versão que você está usando. Por exemplo, alguns atributos não são compatíveis com o processo de herança. Para pesquisar o nome de referência de um campo, consulte o Índice de campo de item de trabalho.

Atributo

Tipo de atributo

Descrição

---

REST:
WIFE: AllowedValues

collection

Obtém a coleção de valores válidos para um campo que contém valores de lista de seleção. Você pode alterar isso especificando uma lista de seleção ou uma lista global (local).
Pode alterar?=Sim

REST: canSortBy
WIFE: CanSortBy

booleano

Indica se você pode classificar os resultados da consulta com esse campo.
Pode alterar?=Não

REST: description
WIFE: HelpText

string

Especifica uma descrição para o campo, que também define o texto de ajuda que aparece quando você passa o mouse sobre o campo dentro do formulário de item de trabalho.
Pode alterar?=Sim

REST:
WIFE: ID

Integer

Especifica a ID interna do campo.
Pode alterar?=Não

REST:
WIFE: IsCloneable

booleano

Indica se o valor definido para o campo é copiado quando um usuário opta por copiar o item de trabalho. Por exemplo, os campos Título, Marcas e Descrição são copiados, mas os campos ID e Histórico não são copiados.
Pode alterar?=Não

REST:
WIFE: IsComputed

booleano

Indica se o valor definido por esse campo é calculado pelo sistema (True) ou não (False). Exemplos de campos computados são os que são definidos pelo sistema, como a ID, Data Revisada, Data Alterada e Contagem de Link Externo.
Pode alterar?=Não

REST:
WIFE: IsCoreField

booleano

Indica se esse campo é especificado para todos os tipos de item de trabalho.
Pode alterar?=Não

REST:
WIFE: IsEditable

booleano

Indica se os usuários podem modificar esse campo (True) ou não (False). Exemplos de campos não editáveis são aqueles definidos pelo sistema, como os campos ID, Revisão, Criado por e Alterado por
Pode alterar?=Não

REST: isIdentity
WIFE: IsIdentity

booleano

Indica se esse campo é um campo Identidade. Os campos de identidade são campos de cadeia de caracteres usados para armazenar identidades de usuário.
Pode alterar?=Não

REST:
WIFE: IsIndexed¹

booleano

Indica se esse campo é indexado para dar suporte à pesquisa.
Pode alterar?=Não

REST:
WIFE: IsLongText

booleano

Indica que o campo pode conter mais de 255 caracteres, como campos atribuídos a um tipo de dados de PlainText, HTML ou Histórico.
Pode alterar?=Não

REST: isPicklist² WIFE:

Booliano

Indica se o campo está associado a uma lista de seleção. O valor é definido como True quando um campo personalizado está definido para o tipo Azure DevOps e Lista de seleção (Cadeia de caracteres) ou Lista de seleção (Inteiro) é selecionado. O valor é definido como False para campos herdados que definem listas de seleção.
Pode alterar?=Não

REST: isPicklistSuggested² WIFE:

Booliano

Indica se o campo permite que os usuários insiram seus valores para uma lista de seleção. O valor é definido como True quando um campo personalizado é definido para o tipo Azure DevOps, Lista de seleção (Cadeia de caracteres) ou Lista de seleção (Inteiro) é selecionado e a caixa de seleção Permitir que os usuários definam seus valores está marcada.
Pode alterar?=Sim

REST: isQueryable
WIFE: IsQueryable

booleano

Indica se o campo aparece dentro do conjunto de campos que você pode adicionar para filtrar uma consulta de item de trabalho (True) ou não (False). A maioria dos campos é consultável.
Pode alterar?=Não

REST:
WIFE: IsReportable ³

booleano

Indica se o atributo reportável está definido ou definido como algo diferente de Nenhum. Esse atributo pode ser alterado para ambientes locais.
Pode alterar?=Sim

REST:
WIFE: IsUsedInGlobalWorkflow

booleano

Indica se o campo está definido dentro de um fluxo de trabalho global.
Pode alterar?=Não

REST:
WIFE: IsUserNameField

booleano

Indica se o campo é usado para exibir um campo Identidade.
Pode alterar?=Não

REST: name
WIFE: Name

string

Nome amigável atribuído ao campo. O nome amigável não pode ser alterado para o Azure DevOps, mas pode ser alterado para local usando o comando witadmin changefield.
Pode alterar?=Somente no local

REST: picklistId
WIFE: HelpText

GUID

Se o campo for uma lista de seleção, o identificador da lista de seleção associada, caso contrário, será nulo. Um valor GUID exclusivo é atribuído quando um campo personalizado está definido para o tipo Azure DevOps e Lista de seleção (Cadeia de caracteres) ou Lista de seleção (Inteiro) é selecionado.
Pode alterar?=Não

REST:
WIFE: ProhibitedValues

collection

Obtém a coleção de valores proibidos para um campo que especifica esses valores. Você só pode definir valores proibidos para implantações locais.
Pode alterar?=Somente no local

REST: readOnly
WIFE:

Booliano

Indica se o campo está definido como somente leitura. No Azure DevOps Services, somente campos personalizados podem ser alterados para serem somente leitura. Os campos do sistema não podem ser modificados.
Pode alterar?=Sim

REST: referenceName
WIFE: ReferenceName

string

Especifica o nome de referência de um campo.
Pode alterar?=Não

REST:
WIFE: ReportingAttributes³

Especifica Detalhes, Dimensão ou Medida, dependendo se e como você deseja que o campo seja incluído nos relatórios. Os dados de campos que têm um valor diferente de Nenhum para esse atributo são exportados para o data warehouse e podem ser incluídos nos relatórios do SQL.
Pode alterar?=Somente no local

REST:
WIFE: ReportingName³

string

Especifica o rótulo de um campo quando os dados são exibidos em relatórios do SQL. Se você não especificar um valor, será usado o nome amigável do campo.
Pode alterar?=Somente no local

REST:
WIFE: ReportingReferenceName³

string

Especifica um nome de referência diferente para um campo que é usado quando os dados são exportados para o data warehouse relacional. Se você não especificar um valor, será usado o nome de referência dos campos.
Pode alterar?=Somente no local

REST: supportedOperations
WIFE:

set

O conjunto de operadores de consulta que são válidos para uso ao referenciar esse campo. Para obter uma referência rápida de operações com suporte baseadas no tipo de dados, confira Referência rápida de consulta, Operadores e macros com suporte para cada tipo de dados.
Pode alterar?=Não

REST:
WIFE: SupportsTextQuery

booleano

Indica se o campo dá suporte a consultas de texto, como Contém Palavras, Não Contém Palavras.
Pode alterar?=Não

REST:
WIFE: SystemType

string

Especifica o tipo de dados do campo, fazendo referência ao nome do sistema, como System.DateTime ou System.String.
Pode alterar?=Não

REST: type
WIFE: FieldType

string

Especifica o tipo de dados do campo, como Booleano, DateTime, Inteiro, Cadeia de caracteres e assim por diante. Para obter uma lista e descrições completas, confira Campos de consulta, operadores e macros.
Pode alterar?=Não

REST: usage
WIFE: Usage

string

Especifica se o campo destina-se a ser usado com objetos de itens de trabalho (WorkItem) ou de vínculo de item de trabalho (WorkItemLink). O uso para a maioria dos campos é WorkItem. Para obter uma lista completa de valores de uso, confira Obter Campos, FieldUsage.
Pode alterar?=Não

Observação

1. Para implantações no local, você pode ativar a indexação para um campo para melhorar o tempo de resposta de consultas ao filtrar no campo. Para saber mais, confira Campos indexados mais adiante neste artigo.
2. Os atributos isPicklist e isPicklistSuggested são atribuídos apenas a campos personalizados definidos para um processo herdado. O modelo de processo herdado tem suporte para o Azure DevOps Server 2019 e versões posteriores. Para obter mais informações, consulte Modelo de processo herdado.
3. Todos os atributos de relatório são válidos apenas para implantações locais cujos projetos foram configurados para dar suporte ao SQL Server Reporting e ao SQL Server Analysis Services.

Listar atributos do campo

Você pode listar os atributos atribuídos a um campo usando a API Fields – Get REST. Substitua OrganizationName pelo nome real da sua organização.

https://dev.azure.com/OrganizationName/_apis/wit/fields/FieldReferenceName

Por exemplo, para listar os atributos do Caminho de Iteração, use o nome System.IterationPath de referência da fabrikam organização:

https://dev.azure.com/fabrikam/_apis/wit/fields/System.IterationPath

**Returned data:**

> [!div class="tabbedCodeSnippets"]
> ```JSON
> {
> "name": "Iteration Path",
> "referenceName": "System.IterationPath",
> "description": "The iteration within which this bug will be fixed",
> "type": "treePath",
> "usage": "workItem",
> "readOnly": false,
> "canSortBy": true,
> "isQueryable": true,
> "supportedOperations": [
> {
> "referenceName": "SupportedOperations.Under",
> "name": "Under"
> },
> {
> "referenceName": "SupportedOperations.NotUnder",
> "name": "Not Under"
> },
> {
> "referenceName": "SupportedOperations.Equals",
> "name": "="
> },
> {
> "referenceName": "SupportedOperations.NotEquals",
> "name": "<>"
> },
> {
> "referenceName": "SupportedOperations.In",
> "name": "In"
> },
> {
> "name": "Not In"
> }
> ],
> "isIdentity": false,
> "isPicklist": false,
> "isPicklistSuggested": false,
> "url": "https://dev.azure.com/mseng/_apis/wit/fields/System.IterationPath"
> }
> ```

Adicionar e modificar campos

Para adicionar campos a um processo, adicione-os a um ou mais tipos de item de trabalho. Para obter mais informações, consulte Personalizar um processo de herança.

Artigos relacionados

• Consulte a referência rápida Consulta para entender rapidamente a sintaxe e o uso da consulta.
• Explore o índice de campo de item de trabalho para exibir todos os campos de item de trabalho disponíveis.
• Adicione e gerencie campos para um processo herdado para personalizar campos de acordo com seus requisitos de processo herdado.
• Acesse a referência de metadados do Azure Boards Analytics para entender os metadados de análise e os recursos de relatório.