Importar dados de arquivos CSV

Preparar arquivo CSV

O plugin JIRA Importers presume que seu arquivo CSV seja baseado em um arquivo CSV padrão do Microsoft Excel. Os campos são separados por vírgulas e qualquer conteúdo que deve ser tratado literalmente, como as vírgulas e as novas linhas/"quebras de linha" são inseridas entre aspas.

 Para o Microsoft Excel e OpenOffice, não é necessário citar valores em células, pois esses aplicativos funcionam automaticamente.

Requisito de arquivo CSV

Além de serem "bem formatados", os arquivos CSV possuem os seguintes requisitos.

Cada arquivo CSV deve possuir uma linha de título com uma coluna Resumo

O assistente de importação de arquivo CSV (abaixo) usa a linha de cabeçalho de um arquivo CSV para determinar como mapear dados da 2ª linha em diante do arquivo CSV para campos do JIRA.

A linha de cabeçalho deve evitar conter qualquer pontuação (exceto as vírgulas que separam cada coluna) ou o importador pode não funcionar corretamente.

A linha de cabeçalho deve conter uma coluna de dados de "Resumo".

Vírgulas (como separadores de coluna/campo) não podem ser omitidas

Por exemplo, isto é válido:

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", admin, admin, 1, ,

... Mas, isto não é:

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", admin, admin, 1

Encapsular a estrutura de dados do JIRA no seu arquivo CSV

Capturar dados que abrangem várias linhas

Use aspas duplas (") no seu arquivo CSV para capturar dados que abrangem várias linhas. Por exemplo, após a importação, o JIRA tratará o seguinte como um arquivo CSV válido com um único registro:

Summary, Description, Status
"Login fails", "This is on
a new line", Open

Tratar literalmente caracteres especiais

Use aspas duplas (") em um trecho de texto para tratar literalmente todos os caracteres especiais dessa seção. Depois que esses dados são importados para o JIRA, estes caracteres especiais serão armazenados como parte dos dados de campo do JIRA. Exemplos de caracteres especiais incluem caracteres de quebra de linha (conforme mostrado no exemplo acima), vírgulas, entre outros.

Para tratar literalmente aspas duplas, você pode colocá-las entre novas aspas duplas. Portanto, o valor CSV:

• "Clicking the ""Add"" button results in a page not found error"
  após a importação, será armazenado no JIRA como:
• Clicking the "Add" button results in a page not found error

Agregar vários valores em campos individuais do JIRA

É possível importar vários valores para um campo do JIRA que aceita vários valores (por exemplo, Corrigir (em) versão, Afeta a versão, Componente, Rótulos). Para fazer isso, seu arquivo CSV deve especificar o mesmo nome de coluna para cada valor que você deseja agregar ao campo do JIRA mapeado. O número de nomes de colunas especificados deve corresponder ao número máximo de valores a serem agregados no campo mapeado. Por exemplo:

IssueType, Summary, FixVersion, FixVersion, FixVersion, Component, Component
bug, "First issue", v1, , , Component1,
bug, "Second issue", v2, , , Component1, Component2
bug, "Third issue", v1, v2, v3, Component1,

No exemplo acima, após a importação, o campo Componente da segunda pendência e o campo Corrigido na versão da terceira pendência gerarão vários valores nos campos apropriados do JIRA.

 Esteja ciente de que apenas um número limitado de campos do JIRA suporta vários valores. O importador de arquivo CSV não permitirá que você importe dados agregados em campos do JIRA que suportam apenas um valor.

Importar anexos

Você pode anexar arquivos a pendências criadas do seu arquivo CSV. Para fazer isso, especifique o URL do seu anexo em uma coluna "Anexos" no seu arquivo CSV.

Assignee, Summary, Description, Attachment, Comment
Admin, "Issue demonstrating the CSV attachment import", "Please check the attached image below.", "https://jira-server:8080/secure/attachment/image-name.png", "01/01/2012 10:10;Admin; This comment works"
Admin, "CSV attachment import with timestamp,author and filename", "Please check the attached image below.", "01/01/2012 13:10;Admin;image.png;file://image-name.png", "01/01/2012 10:10;Admin; This comment works"

 Os URLs de anexos são compatíveis com protocolos HTTP e HTTPS e podem ser qualquer local que o seu servidor JIRA possa ter acesso. Você também pode usar o protocolo FILE para acessar arquivos no subdiretório import/attachments do seu diretório inicial do JIRA.

Criar subtarefas

É possível criar subtarefas de pendências por meio da importação de arquivos CSV, encapsulando essa estrutura em seu arquivo CSV. Para fazer isso:

• Seu arquivo CSV requer duas colunas adicionais cujos títulos devem ser nomeados de modo semelhante a ID da pendência e ID principal.
• Certifique-se de que cada pendência regular (não subtarefa) tenha um número único (sequencial) na coluna ID da pendência. Não inclua nenhum valor nos campos ID principal para pendências regulares.
• Para criar uma subtarefa de uma pendência regular no seu arquivo CSV, faça referência ao número exclusivo da ID da pendência da pendência regular na coluna ID principal. Não inclua nenhum valor nos campos ID da pendência para subtarefas.

Por exemplo:

IssueType, Summary, FixVersion, FixVersion, FixVersion, Component, Component, Issue ID, Parent ID, Reporter
Bug, "First issue", v1, , , Component1, , 1, , jbloggs
Bug, "Second issue", v2, , , Component1, Component2, 2, , fferdinando
Bug, "Third issue", v1, v2, v3, Component1, , 3, , fferdinando
Sub-task, "Fourth issue", v1, v2, , Component2, , , 2, jbloggs

No exemplo acima, a quarta pendência será uma subtarefa da segunda pendência após a importação, presumindo que você corresponda os campos "ID da pendência" e "ID principal" no seu arquivo CSV com os campos ID da pendência e ID principal do JIRA, respectivamente, no assistente de importação de arquivo CSV.

Importar pendências para vários projetos do JIRA

Você pode importar pendências do seu arquivo CSV para diferentes projetos do JIRA por meio de uma importação de arquivos CSV. Para fazer isso:

• Seu arquivo CSV requer duas colunas adicionais cujos cabeçalhos devem ser nomeados de modo semelhante a Nome do projeto e Chave do projeto.
• Certifique-se de que cada pendência representada no seu arquivo CSV contenha o nome e a chave apropriados nestas colunas dos projetos do JIRA para os quais serão importadas.
   Os dados de nome e chave do projeto são os dados mínimos do projeto do JIRA necessários para importar pendências de um arquivo CSV para projetos específicos do JIRA.

IssueType, Summary, Project Name, Project Key
bug, "First issue", Sample, SAMP
bug, "Second issue", Sample, SAMP
task, "Third issue", Example, EXAM

No exemplo acima, a primeira e a segunda pendência serão importadas para o projeto "Amostra" (com a chave de projeto "AMOS") e a terceira pendência será importada para o projeto "Exemplo" (com a chave de projeto ''EXEM"), presumindo que você fez a correspondência dos campos "Nome do projeto" e "Chave do projeto" no seu arquivo CSV com os campos Nome do projeto e Chave do projeto do JIRA, respectivamente, no assistente de importação de arquivo CSV.

Como lidar com pendências não resolvidas

Para o mapeamento de campos para Resolução, Prioridade e Tipo de pendência, você receberá uma lista de seleção com valores disponíveis no JIRA. Além disso, você pode criar rapidamente valores que não existem no JIRA clicando nos sinais + verdes.

Para mapeamentos de campos de status, você receberá a lista de seleção com os valores disponíveis do JIRA, mas nenhum sinal de mais para criar novos valores de status.

Para esses quatro campos, existem duas opções especiais na lista de seleção além dos valores disponíveis do JIRA:

• "Importar em branco" — deixa o valor do JIRA em branco para esse campo. Observe que, se você estiver importando pendências não resolvidas, será preciso criar um mapeamento de campo para o campo Resolução e definir o valor "Não resolvida" para "Importar em branco".
• "Sem mapeamento" — tenta importar o valor no arquivo CSV como ele é. Observe que usar a opção "Sem mapeamento" para um valor de campo resultará em falha na importação se o valor não for válido para esse campo do JIRA. Nos mapeamentos de campos para Status e Tipo de pendência, valores padrão são usados quando a opção "Importar em branco" é selecionada.

Importar entradas de registro de trabalho

Seu arquivo CSV pode conter entradas de registro de trabalho. Por exemplo:

Summary,Worklog
Only time spent (one hour),3600
With a date and an author,2012-02-10 12:30:10;wseliga;120
With an additional comment,Testing took me 3 days;2012-02-10 12:30:10;wseliga;259200

Para rastrear o tempo gasto, é necessário usar segundos.

Importar para campos personalizados de seleções múltiplas

Seu arquivo CSV pode conter várias entradas para o campo personalizado de seleção múltipla. Por exemplo:

Summary,Multi Select,Multi Select,Multi Select
Sample issue,Value 1,Value 2,Value 3

Isso preencherá o campo personalizado de seleção múltipla com vários valores.

Importar campos personalizados de opção em cascata

É possível importar valores para um campo personalizado de opção em cascata usando a seguinte sintaxe:

Summary, My Cascading Custom Field
Example Summary, Parent Value -> Child Value

O separador "->" permite importar a hierarquia:

NOTA: Atualmente, o JIRA não é compatível com a importação de campos de seleção em cascata de vários níveis por CSV ( JRA-34202 - Getting issue details... STATUS ).

Atualizar pendências existentes

A partir da versão 4.3 do plugin JIRA Importers, é possível atualizar pendências existentes. Seu arquivo CSV precisa conter uma coluna que, durante o assistente de importação, seja mapeada para uma chave de pendência. Se houver uma pendência para uma determinada chave, ela será atualizada. Por exemplo:

issue key,summary,votes,labels,labels
TT-1,Original summary,1,label1,label2
TT-1,,7,label-1,label-2
TT-1,Changed summary,,,
TT-2,Original summary 2,1,label-1,label-2
TT-2,,<<!clear!>>,<<!clear!>>,

A primeira linha criará uma pendência, a segunda linha definirá votos para 7 e adicionará dois rótulos. A linha a seguir alterará o resumo. A pendência TT-2 será criada com dois rótulos, a segunda linha removerá esses rótulos com um marcador especial <>.

A  importação de um arquivo CSV para atualizar pendências existentes redefinirá as colunas para seus valores padrão se elas não forem especificadas no arquivo CSV.

Executar o assistente de importação de arquivos CSV

Antes de começar, faça um backup dos seus dados do JIRA.

1. Faça login no JIRA como um usuário com permissão global de administradores do JIRA.
2. Selecione Administração > Sistema > Importação e exportação > Importação de sistema externo.
3. Selecione CSV para abrir a página Importação de arquivo CSV.
4. Na página Importação de arquivo CSV, selecione Arquivo CSV de origem. Se desejar alterar a codificação e o formato delimitador CSV do arquivo, clique no título Avançado para exibir essa opção (conforme mostrado na captura de tela acima).
     Nota:
   
   • O arquivo será importado usando a codificação de arquivo especificada por você aqui (que é UTF-8 por padrão).
   • Se o seu arquivo CSV usar um caractere separador diferente de vírgula, especifique esse caractere no campo Delimitador CSV.
5. Deixe a caixa de seleção Usar arquivo de configuração existente desmarcada se você não possuir um arquivo de configuração ou se deseja criar um novo arquivo de configuração. Os arquivos de configuração especificam um mapeamento entre nomes de colunas na linha de cabeçalho do arquivo CSV e campos na instalação do JIRA.
     Nota:
   • Se selecionar esta opção, você será instruído a especificar um arquivo de configuração existente.
   • Se não selecionar essa opção, ao final do assistente de importação de arquivos CSV, o JIRA criará um arquivo de configuração que você pode usar para importações CSV futuras (nessa etapa do assistente de importação de arquivos CSV).
6. Clique no botão Avançar com o fim de prosseguir para a etapa Configurar mapeamentos do projeto do assistente de importação de arquivos CSV.

7. Na página Configurar mapeamentos do projeto você pode importar todas as suas pendências para um projeto do JIRA (novo ou existente) ou vários projetos do JIRA (desde que seu arquivo CSV inclua os dados mínimos necessários do projeto do JIRA — ou seja, o nome e a chave do projeto do JIRA). Preencha os seguintes campos/opções:

   Importar para projeto do JIRA	Escolha uma das seguintes opções: Selecione um projeto e realize uma das ações a seguir: Primeiro, digite o nome (ou chave) de um projeto que já existe no JIRA ou use o menu suspenso para selecioná-lo. Selecione Criar novo no menu suspenso, na caixa de diálogo Adicionar um novo projeto que será exibida, insira o seguinte: Um novo nome de projeto Uma nova chave de projeto. Ela será usada como o prefixo de todas as IDs de pendências do seu projeto do JIRA. O líder do projeto. Definido no CSV. Certifique-se de que cada pendência no seu arquivo CSV inclua dados do nome do projeto e da chave do projeto do JIRA. Esta opção é útil se você quiser importar pendências do seu arquivo CSV para vários projetos do JIRA. Consulte Importing issues into multiple JIRA projects para obter detalhes.
   Sufixo de e-mail para novos usuários	Insira o domínio do endereço de e-mail para qualquer novo usuário especificado no arquivo CSV que será adicionado ao JIRA durante a importação.
   Formato de data no arquivo de importação	Especifique o formato de data usado em seu arquivo CSV. Use a sintaxe que esteja em conformidade com o Java SimpleDateFormat.

8. Clique no botão Avançar com o fim de prosseguir para a etapa Configurar mapeamentos de campo do assistente de importação de arquivos CSV.

9. Na página Configurar mapeamentos de campo, especifique cada Campo CSV (determinado pela linha de cabeçalho do arquivo CSV) que deseja importar para o projeto escolhido do JIRA, marcando as caixas de seleção abaixo da coluna Importar, à esquerda.
     Nota:

   • Pelo menos um desses campos deve conter dados do campo Resumo do JIRA.

   • Se o seu arquivo CSV contiver mais de um nome de campo igual especificado em sua linha de cabeçalho, o assistente de importação de arquivo CSV os agregará em um único campo, que será marcado por um símbolo nesta etapa do assistente.

10. Na coluna campo do JIRA, selecione os campos do JIRA que deseja corresponder aos campos definidos no seu arquivo CSV (ou seja, cada Campo do CSV que você selecionou na etapa anterior). Para obter mais informações sobre como corresponder campos CSV com campos do JIRA, consulte Dicas para importar dados de arquivo CSV para campos do JIRA abaixo.
      Nota:

    • O campo Resumo deve ser especificado para um dos seus campos do JIRA e o botão Avançar permanecerá indisponível enquanto isso não for feito.

    • No caso de campos CSV que foram agregados pelo assistente de importação de arquivos CSV, você poderá selecionar apenas campos do JIRA que sejam compatíveis com vários valores.

    • Se estiver importando subtarefas, lembre-se de corresponder os campos ID da pendência e ID principal com os campos do JIRA no seu arquivo CSV.
    • Se estiver importando pendências para vários projetos, certifique-se de que você selecionou Definido no CSV durante a etapa Configurar mapeamentos do projeto acima e lembre-se de corresponder os campos Nome do projeto e Chave do projeto do JIRA com os do arquivo CSV.
11. Para modificar os valores dos dados de qualquer campo no arquivo CSV antes de importá-los para o JIRA, marque as caixas de seleção Mapear valor do campo ao lado dos campos apropriados.
12. Clique no botão Avançar para prosseguir para a etapa Configurar mapeamentos de valor do assistente de importação de arquivos CSV.
13. Na página Configurar mapeamentos de valor, especifique os valores de campo do JIRA para cada valor de campo de arquivo CSV (que foi detectado pelo assistente de importação de arquivos CSV).
    Nota:
    
    • Todos os campos cujas caixas de seleção Mapear valor do campo foram marcadas na etapa anterior do assistente de importação de arquivos CSV serão apresentados nesta página.

    • Deixe o campo desmarcado ou limpe qualquer conteúdo dentro dele se desejar importar o valor "como está".

    • Você pode criar novos valores Prioridade, Resolução e Tipo de pendência no JIRA (com base nos dados em seu arquivo CSV) clicando no link  Adicionar novo... (por exemplo, Adicionar nova "subtarefa" de tipo de pendência mostrado na captura de tela acima) ao lado do campo apropriado.

    • Se você estiver importando um campo CSV com base em nome de usuário (por exemplo, Relator ou Responsável) e você não marca a caixa de seleção Mapear valor do campo para esse campo na etapa anterior do assistente de importação de arquivos CSV, o importador mapeará automaticamente nomes de usuários importados do arquivo CSV para nomes de usuários (letras minúsculas) do JIRA.
      Independentemente de você ter ou não marcado a caixa de seleção Mapear valor do campo, o JIRA criará automaticamente nomes de usuário com base nos dados do arquivo CSV, caso ainda não tenham sido definidos no JIRA. 

14. Clique no botão Iniciar importação quando estiver pronto para começar a importar seus dados CSV para o JIRA. O importador exibirá atualizações conforme a importação avança, então exibirá uma mensagem de sucesso quando a importação estiver concluída.
    Nota:
    • se você tiver encontrado problemas com a importação (ou estiver curioso), clique no link baixar um registro detalhado para revelar informações detalhadas sobre o processo de importação de arquivo CSV.
    • Se precisar importar outro arquivo CSV com configurações iguais (ou similares) às usadas neste procedimento, clique no link salvar a configuração para baixar um arquivo de configuração CSV, que poderá ser usado na primeira etapa do assistente de importação de arquivo CSV.

Parabéns, você importou com sucesso seus dados CSV para o JIRA! Se tiver alguma dúvida ou encontrar algum problema, entre em contato com o suporte da Atlassian.

Dicas para importar dados CSV para campos do JIRA

A seguir estão algumas dicas úteis ao importar dados do arquivo CSV para campos específicos do JIRA: