Jira

Sobre a integração do ONLYOFFICE com o Jira

O ONLYOFFICE oferece conectores oficiais para integrar o ONLYOFFICE Docs ao Jira e colaborar em documentos de escritório anexados às suas issues do Jira. Há dois conectores disponíveis, dependendo da sua implantação do Jira:

• Jira Data Center / Server — disponível no Atlassian Marketplace e no GitHub. Distribuído sob a licença Apache.
• Jira Cloud — disponível no Atlassian Marketplace e no GitHub. Distribuído sob a licença Apache.

observação

Para saber mais sobre como o conector do Jira funciona, visite a nossa documentação da API.

Principais recursos

• Criação de novos documentos, planilhas, apresentações e formulários.

• Visualização e edição de documentos de texto, planilhas, apresentações e formulários com a opção Edit in ONLYOFFICE (Editar no ONLYOFFICE).

  observação

  Para saber mais sobre formulários, leia os artigos correspondentes sobre criação e preenchimento de formulários.

• Coedição de documentos em tempo real: dois modos de coedição (Rápido e Estrito), controle de alterações, comentários e um chat integrado.

• Suporte a JWT para proteger o seu tráfego, de modo que ninguém além dos usuários com os direitos adequados tenha acesso aos seus documentos.

• Suporte a assistente de IA (somente Jira Cloud) — conecte o seu provedor de IA preferido por meio do plugin de IA. Compatível com OpenAI, Mistral, Anthropic, Google Gemini, DeepSeek e outros. Consulte o guia de IA para mais detalhes.

Formatos compatíveis

Para visualização:

• WORD: DOC, DOCM, DOCX, DOT, DOTM, DOTX, EPUB, FB2, FODT, HTM, HTML, HWP, HWPX, MD, MHT, MHTML, ODT, OTT, PAGES, RTF, STW, SXW, TXT, WPS, WPT, XML
• CELL: CSV, ET, ETT, FODS, NUMBERS, ODS, OTS, SXC, XLS, XLSM, XLSX, XLT, XLTM, XLTX
• SLIDE: DPS, DPT, FODP, KEY, ODG, ODP, OTP, POT, POTM, POTX, PPS, PPSM, PPSX, PPT, PPTM, PPTX, SXI
• PDF: DJVU, DOCXF, OFORM, OXPS, PDF, XPS
• DIAGRAM: VSDM, VSDX, VSSM, VSSX, VSTM, VSTX

Para edição:

• WORD: DOCM, DOCX, DOTM, DOTX
• CELL: XLSB, XLSM, XLSX, XLTM, XLTX
• SLIDE: POTM, POTX, PPSM, PPSX, PPTM, PPTX
• PDF: PDF

Os formatos a seguir também estão disponíveis para edição no Jira Data Center / Server. Observe que a edição desses formatos pode resultar em perda de informações:

• WORD: EPUB, FB2, HTML, ODT, OTT, RTF, TXT
• CELL: CSV, ODS, OTS
• SLIDE: ODP, OTP

Novidades da versão 4.1.1

Jira Data Center

Alterado

• Corrigido um problema com as requisições HTTP do plugin quando o Jira é implantado com um caminho de contexto.

O registro completo de alterações está disponível aqui.

Jira Cloud

Adicionado

• Versão inicial do conector do ONLYOFFICE para o Jira Cloud.

O registro completo de alterações está disponível aqui.

Conectando o ONLYOFFICE Docs ao Jira Data Center / Server

Requisitos

• ONLYOFFICE Document Server v6.4.0 (versão servidor ou nuvem) ou posterior.

  Você precisa de uma instância do ONLYOFFICE Docs que possa ser resolvida e acessada tanto pelo Jira quanto por quaisquer clientes finais. Ela deve conseguir enviar requisições POST diretamente ao Jira.

  observação

  Consulte a página de documentação oficial para saber mais sobre a instalação do ONLYOFFICE Docs.

• Jira Software. Há dois conectores para diferentes versões do Jira Data Center:

  • Conector ONLYOFFICE v3.1.1 para o Jira Software (Server ou Data Center) v. 9.0.0 — 9.17.5
  • Conector ONLYOFFICE v4.1.1 para o Jira Software (Server ou Data Center) v. 10.0.0 — 10.7.2
  observação

  Consulte a documentação da Atlassian oficial para saber mais sobre a instalação do Jira Software.

• Conector ONLYOFFICE para o Jira.

  Consulte esta lista para baixar a versão necessária do conector.

Instalando o conector do ONLYOFFICE para o Jira

Você pode baixar o conector no Atlassian Marketplace oficial ou compilá-lo a partir do código-fonte disponível no GitHub.

Adicionando o conector pelo Atlassian Marketplace

• Faça login na sua instância do Jira Software como administrador.

• Clique no ícone Administration (Administração) no canto superior direito e escolha a opção Manage apps (Gerenciar aplicativos) no menu.

  

• A seção Find new apps (Encontrar novos aplicativos) será aberta. Clique no campo Search the Marketplace (Pesquisar no Marketplace) e encontre o aplicativo de integração Jira ONLYOFFICE (Jira ONLYOFFICE integration app).

• Clique no botão Install (Instalar) para baixar e instalar o aplicativo.

Adicionando o conector compilado a partir do código-fonte

Primeiro, você precisa instalar os pré-requisitos a seguir para poder compilar o conector do ONLYOFFICE para o Jira:

• 1.8.X do Oracle Java SE Development Kit 8
• Atlassian Plugin SDK

Para compilar o conector do ONLYOFFICE para o Jira, siga estas etapas:

• Clone o repositório onlyoffice-jira.

  git clone https://github.com/ONLYOFFICE/onlyoffice-jira.git

• Vá para o diretório onlyoffice-jira.

  cd onlyoffice-jira

• Execute o seguinte comando:

  atlas-package

Aguarde enquanto o conector é compilado. Depois disso, o conector poderá ser encontrado na pasta target.

Você pode enviar o conector compilado na página Jira Software Administration > Manage Apps.

• Faça login na sua instância do Jira Software como administrador.

• Clique no ícone Administration (Administração) no canto superior direito e escolha a opção Manage apps (Gerenciar aplicativos) no menu.

• Selecione a seção Manage apps no lado esquerdo da página.

• Clique no link Upload app (Enviar aplicativo).

• Clique no botão Choose File (Escolher arquivo), localize o arquivo compilado target/onlyoffice-jira-app.jar e clique em Upload (Enviar). Aguarde enquanto o aplicativo é instalado.

  

Configurando o conector do ONLYOFFICE para o Jira

Clique no botão Configure (Configurar) abaixo do aplicativo de integração Jira ONLYOFFICE instalado na página Manage apps ou encontre o aplicativo na seção OTHER da página Manage apps.

Document Server

1. No campo Document Editing Service address (Endereço do serviço de edição de documentos), especifique o endereço IP ou o nome do host do servidor onde o ONLYOFFICE Docs está instalado.

   observação

   O endereço do ONLYOFFICE Docs deve estar acessível a partir do Jira, assim como o endereço do Jira deve estar acessível a partir do ONLYOFFICE Docs.

2. Disable certificate verification (insecure) (Desativar a verificação de certificado (inseguro)) — marque esta caixa para desativar a verificação de certificado e permitir que o Jira estabeleça uma conexão com o ONLYOFFICE Docs se você estiver usando um certificado autoassinado. Esta é uma solução insegura; recomendamos fortemente substituir o certificado por um emitido por uma CA.

3. Especifique uma Secret key (Chave secreta) (deixe em branco para desativar) — o segredo para validar o JSON Web Token na requisição ao ONLYOFFICE Docs.

   observação

   A partir do ONLYOFFICE Docs v7.2, o JWT é ativado por padrão e a chave secreta é gerada automaticamente. Você também precisa ativá-lo no lado do Jira: encontre a sua chave secreta no arquivo de configuração do ONLYOFFICE Docs e, em seguida, especifique a mesma chave secreta nas configurações do conector. Para mais detalhes, consulte a seção Ativando o JWT deste artigo.

4. Authorization header (Cabeçalho de autorização) (deixe em branco para usar o cabeçalho padrão) — o cabeçalho JWT de autorização usado no ONLYOFFICE é Authorization. Caso esse cabeçalho entre em conflito com a sua configuração, você pode alterá-lo para um personalizado.

5. Connect to demo ONLYOFFICE Document Server (Conectar ao ONLYOFFICE Document Server de demonstração) — inicia um servidor de teste.

   Importante

   Este é um servidor de teste público que ficará disponível por um período de 30 dias. Não compartilhe seus dados confidenciais nele.

Advanced server settings (Configurações avançadas do servidor)

A seção Advanced server settings pode ser usada se a configuração da sua rede não permitir requisições entre o Jira Software e o ONLYOFFICE Docs usando endereços públicos. Especifique os endereços para requisições internas nos campos correspondentes:

1. Server address for internal requests from the Document Editing Service (Endereço do servidor para requisições internas do serviço de edição de documentos) — endereço do servidor Jira Software para requisições internas do ONLYOFFICE Docs.
2. Document Editing Service address for internal requests from the server (Endereço do serviço de edição de documentos para requisições internas do servidor) — endereço do ONLYOFFICE Docs para requisições internas do servidor Jira Software.

Common settings (Configurações comuns)

1. Editable formats (Formatos editáveis) — marque a caixa ao lado dos formatos compatíveis com o seu ambiente Jira.

   Pode ocorrer perda de dados ao salvar nos formatos especificados devido a restrições de formato.

2. Editor interface (Interface do editor) — personalize a interface dos editores:

   • Display Chat menu button — oculta/exibe o ícone Chat integrado online no painel esquerdo.
   • Display the header more compact — oculta/exibe o texto dos ícones na barra de ferramentas superior.
   • Display Feedback & Support menu button — oculta/exibe o botão Feedback & Support no painel esquerdo.
   • Display Help menu button — oculta/exibe o botão Help (Ajuda) no painel esquerdo.
   • Display monochrome toolbar header — alterna a barra de ferramentas superior para uma paleta de cores monocromática.

Security (Segurança)

1. Enable plugins — ativa/desativa o suporte a plugins nos editores.
2. Run document macros — ativa/desativa a execução de macros dentro dos editores.
3. Enable document protection for — escolha se deseja permitir que todos os usuários ativem a proteção por senha nos documentos ou somente o proprietário do documento.

Clique em Save (Salvar) para salvar as configurações.

Como funciona

A integração do ONLYOFFICE segue a API documentada aqui.

1. Um usuário navega até os anexos do Jira e seleciona a ação Edit in ONLYOFFICE.
2. O Jira faz uma requisição ao OnlyOfficeEditorServlet (URL no formato: /plugins/servlet/onlyoffice/doceditor?attachmentId=$attachment.id).
3. O Jira envia o documento ao serviço de armazenamento de documentos do ONLYOFFICE e recebe um link temporário.
4. O Jira prepara um objeto JSON com as seguintes propriedades:
   • url: o link temporário que o ONLYOFFICE Docs usa para baixar o documento;
   • callbackUrl: a URL que o ONLYOFFICE Docs usa para informar o status da edição do documento;
   • docserviceApiUrl: a URL à qual o cliente precisa responder ao ONLYOFFICE Docs (fornecida pela propriedade files.docservice.url.api);
   • key: o UUID que indica ao ONLYOFFICE Docs se deve baixar o documento novamente ou não;
   • title: o título (nome) do documento.
5. O Jira pega esse objeto e constrói uma página a partir de um modelo freemarker, preenchendo todos esses valores para que o navegador do cliente possa carregar o editor.
6. O navegador do cliente faz uma requisição à biblioteca JavaScript do ONLYOFFICE Docs e envia a ele a configuração do DocEditor com as propriedades acima.
7. Em seguida, o ONLYOFFICE Docs baixa o documento do armazenamento de documentos e o usuário começa a editar.
8. Quando todos os usuários e navegadores clientes terminam a edição, eles fecham a janela de edição.
9. Após 10 segundos de inatividade, o ONLYOFFICE Docs envia um POST ao callbackUrl informando ao Jira que os clientes terminaram de editar o documento e o fecharam.
10. O documento com todas as alterações é salvo como um novo anexo, com um sufixo adicionado ao nome do arquivo.

Ativando o JWT

Para proteger os documentos contra acesso não autorizado, os editores do ONLYOFFICE usam o JSON Web Token (JWT). O token é adicionado à configuração quando o editor de documentos é inicializado e durante a troca de comandos entre os serviços internos do ONLYOFFICE Docs. A chave secreta é usada para assinar o JSON Web Token e validar o token na requisição ao ONLYOFFICE Docs.

A partir do ONLYOFFICE Docs v7.2, o JWT é ativado por padrão e a chave secreta é gerada automaticamente. Você precisa encontrar a sua chave secreta no arquivo de configuração do ONLYOFFICE Docs e, em seguida, especificar a mesma chave secreta nas configurações do conector.

Etapa 1: encontre a sua chave secreta no arquivo de configuração do ONLYOFFICE Docs

1. Abra o arquivo local.json com qualquer editor de texto disponível:

   • Para Linux — /etc/onlyoffice/documentserver/local.json

   • Para Windows — %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json

   • Para Docker — entre no contêiner do ONLYOFFICE Docs usando o comando docker exec -it <containerID> bash e abra /etc/onlyoffice/documentserver/local.json.

     Como alternativa, você pode usar o comando a seguir para encontrar a chave secreta padrão sem abrir o local.json:

     sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

   O arquivo local.json deve ter esta aparência:

   {
     "services": {
       "CoAuthoring": {
         "token": {
           "enable": {
             "request": {
               "inbox": true,
               "outbox": true
             },
             "browser": true
           }
         },
         "secret": {
           "inbox": {
             "string": "yoursecret"
           },
           "outbox": {
             "string": "yoursecret"
           },
           "session": {
             "string": "yoursecret"
           }
         }
       }
     }
   }

2. O valor true é especificado em três seções, o que significa que a validação de token está ativada:

   • services.CoAuthoring.token.enable.browser
   • services.CoAuthoring.token.enable.request.inbox
   • services.CoAuthoring.token.enable.request.outbox

3. A chave secreta gerada automaticamente é especificada em três seções. Você pode substituir o valor padrão pela sua própria chave secreta — ela deve ser a mesma nas três:

   • services.CoAuthoring.secret.inbox.string
   • services.CoAuthoring.secret.outbox.string
   • services.CoAuthoring.secret.session.string

4. Se você fizer alterações, salve-as e reinicie os serviços:

   supervisorctl restart all

Etapa 2: especifique a mesma chave secreta nas configurações do conector

Nas configurações do conector, especifique a mesma chave secreta no campo Secret key (Chave secreta) e salve as configurações.

Conectando ao ONLYOFFICE Docs de demonstração

A partir da versão 2.0.0 do conector do ONLYOFFICE, você pode experimentar os editores online do ONLYOFFICE no Jira sem instalar o ONLYOFFICE Docs.

Para ativar a conexão, marque a caixa Connect to demo ONLYOFFICE Docs server e clique no botão Save (Salvar).

Importante

Este é um servidor de teste público que ficará disponível por um período de 30 dias. Não compartilhe seus dados confidenciais nele.

Conectando o ONLYOFFICE Docs ao Jira Cloud

Requisitos

• Uma instância do ONLYOFFICE Docs, auto-hospedada ou na nuvem.
• Jira Cloud.
• Conector do ONLYOFFICE para o Jira Cloud do Atlassian Marketplace.

Instalando o conector do ONLYOFFICE para o Jira Cloud

• Acesse marketplace.atlassian.com.
• Encontre o ONLYOFFICE Connector for Jira e clique no botão Get it now (Obter agora).
• Na janela pop-up, selecione o site onde deseja instalar o aplicativo e escolha a edição, se houver várias opções disponíveis.

Configurando o conector do ONLYOFFICE para o Jira Cloud

Os administradores podem configurar o aplicativo ONLYOFFICE em Apps → Manage apps → ONLYOFFICE Connector for Jira → Configure. Na página de configuração, defina:

• ONLYOFFICE Docs address (Endereço do ONLYOFFICE Docs) — a URL do ONLYOFFICE Docs instalado.
• ONLYOFFICE Docs secret key (Chave secreta do ONLYOFFICE Docs) — ativa o JWT para proteger os seus documentos contra acesso não autorizado. Consulte o guia de configuração do JWT para mais detalhes.
• Authorization header (Cabeçalho de autorização).

Você também pode se conectar ao servidor de teste público do ONLYOFFICE Docs por um mês marcando a caixa correspondente.

Importante

Este é um servidor de teste público que ficará disponível por um período de 30 dias. Não compartilhe seus dados confidenciais nele.

Começando a usar o ONLYOFFICE Docs no Jira Data Center / Server

Criando, visualizando e editando arquivos

Você pode abrir os editores do ONLYOFFICE em qualquer bloco Attachments (Anexos) de uma issue. Esta opção está disponível para issues de qualquer módulo em que uma issue possa ser aberta, por exemplo, lista de issues, backlog etc.

observação

Os anexos devem ser ativados pelo administrador.

Um novo anexo pode ser adicionado na página da issue usando a opção More → Attach files (Mais → Anexar arquivos). Para saber mais, consulte a documentação oficial.

Para abrir um documento de texto, planilha, apresentação ou formulário existente, passe o ponteiro do mouse sobre o arquivo desejado e clique no ícone Edit in ONLYOFFICE. Se o formato do arquivo não for compatível com edição, a opção View in ONLYOFFICE (Visualizar no ONLYOFFICE) estará disponível. Para arquivos .oform, a opção Fill in form in ONLYOFFICE (Preencher formulário no ONLYOFFICE) estará disponível. O documento resultante será salvo no formato PDF.

O arquivo será aberto em uma nova guia do navegador no editor do ONLYOFFICE correspondente.

Para criar um novo arquivo usando os editores do ONLYOFFICE:

• No bloco Attachments de uma issue, clique na opção Create file with ONLYOFFICE (Criar arquivo com ONLYOFFICE).

• Escolha o tipo de arquivo desejado: documento, planilha, apresentação ou modelo de formulário.

• Digite o nome do arquivo e clique em Create (Criar).

  

• O arquivo será aberto em uma nova guia do navegador no editor do ONLYOFFICE correspondente.

Quando a sessão de edição terminar, um documento com todas as alterações será salvo como um novo anexo. Você o reconhecerá pelo mesmo nome com um sufixo. Se você estiver editando um anexo de forma colaborativa, as alterações só serão salvas depois que o último usuário sair do editor.

Permissões de acesso

As permissões de acesso aos arquivos dependem dos direitos de acesso do usuário à issue correspondente.

Edição de arquivos. Para poder editar arquivos, o usuário deve ter permissão para criar anexos (Create attachments).

Visualização de arquivos. A visualização prévia de arquivos nos visualizadores do ONLYOFFICE está disponível para todos os usuários que podem ver uma issue, mas não têm permissão para editar a issue nem permissão para criar anexos. Se o formato do arquivo não for compatível com edição, o arquivo será aberto para visualização.

Convertendo documentos

Para converter um documento para o formato Office Open XML:

• Passe o ponteiro do mouse sobre o arquivo desejado e clique no ícone ONLYOFFICE conversion service (Serviço de conversão do ONLYOFFICE).

  

• Opcionalmente, você pode alterar o nome do arquivo.

• Clique no botão Convert (Converter).

• O arquivo convertido será armazenado no bloco Attachments.

  

Salvando alterações

As alterações feitas em um arquivo são salvas em um novo arquivo com o mesmo nome do arquivo original, com um sufixo adicionado ao final do nome, por exemplo, Sample-1.docx.

As alterações feitas em um arquivo durante a coedição são salvas apenas na primeira versão do arquivo. Se o documento estiver sendo editado por vários usuários simultaneamente, as alterações serão exibidas apenas no primeiro arquivo. Até que o último usuário feche o editor, uma nova versão do arquivo não é adicionada à issue.

Baixando arquivos

Para baixar um documento em outro formato:

• Passe o ponteiro do mouse sobre o arquivo desejado e clique no ícone ONLYOFFICE conversion service (Serviço de conversão do ONLYOFFICE).

  

• Opcionalmente, você pode alterar o nome do arquivo.

• Selecione o formato desejado na lista Target type (Tipo de destino).

• Clique no botão Download (Baixar).

• O arquivo baixado será armazenado no seu computador.

observação

Para saber mais sobre os problemas mais comuns e as formas de resolvê-los, visite o nosso guia de solução de problemas.

Começando a usar o ONLYOFFICE Docs no Jira Cloud

A página da issue do Jira inclui uma seção ONLYOFFICE Docs. Se você não a vir, clique no ícone de engrenagem abaixo do título da issue e selecione ONLYOFFICE Docs para ativá-la.

Criando arquivos

Para criar um novo arquivo, clique no botão Create with ONLYOFFICE (Criar com ONLYOFFICE). Na janela pop-up, insira um nome de arquivo e escolha um formato. Atualmente, você pode criar arquivos nos formatos DOCX, XLSX, PPTX e formulário PDF.

Ao clicar em Create (Criar), o arquivo será gerado e aberto instantaneamente em uma janela pop-up com permissões de edição. O arquivo recém-criado também será adicionado à seção Attachments.

Editando e visualizando arquivos

Para abrir um arquivo existente para edição, clique no ícone de lápis ao lado dele. Para abri-lo somente para visualização, clique no ícone de olho. O editor será iniciado de acordo com a escolha.

Importante

Devido às limitações do conector, o editor não pode permanecer aberto por longos períodos. Ele deve ser reiniciado a cada quatro horas para garantir o funcionamento adequado.

Permissões de acesso

• Download e visualização: disponíveis para todos os usuários com acesso à issue do Jira.
• Edição: os usuários podem editar os arquivos que criaram. Para editar arquivos criados por outras pessoas, os usuários devem ter a permissão Delete All Attachments.

Para conceder permissões de edição a uma função específica do Jira:

• Abra o menu de contexto do projeto desejado e selecione Project settings (Configurações do projeto).
• Acesse a seção Permissions (Permissões), clique no botão Action (Ação) e atualize a lista de funções para Delete All Attachments.