Jira

Sobre a integração entre ONLYOFFICE e Jira

O ONLYOFFICE oferece um conector oficial para integrar o ONLYOFFICE Docs com o Jira Software para colaborar em documentos de escritório anexados às suas questões do Jira. Você pode baixá-lo do Marketplace oficial da Atlassian ou do GitHub. O aplicativo é distribuído sob a licença Apache.

Para saber mais sobre como funciona, visite 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 usando a opção Editar no ONLYOFFICE .
Para saber mais sobre formulários, leia os artigos correspondentes para criar e preencher formulários.
Co-edição de documentos em tempo real: dois modos de co-edição (Rápido e Estrito), Controlar Alterações, comentários e chat integrado.
Suporte JWT para proteger seu tráfego de modo que ninguém possa ter acesso aos seus documentos com a exceção dos usuários com os devidos direitos.

Formatos suportados

Para criação, edição e visualização: DOCX, XLSX, PPTX, DOCXF.
Para trabalhar com formulários: DOCXF/PDF.
Para visualização apenas: DOC, DOCM, DOC, DOTX, DOTM, ODT, FODT, OTT, RTF, TXT, HTML, HTM, MHT, PDF, DJVU, FB2, EPUB, XPS, XLS, XLSM, XLTZ, XLTX, XLTM, ODS, FODS, OTS, CSV, PPS, PPSX, PPSM, PPT, PPTM, POT, POTX, POTM, ODP, FODP, OTP.

Novidades na versão 4.1.1

Alterado

Corrigido um problema com solicitações HTTP do plugin quando o Jira é implantado usando um caminho de contexto.

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

Conectando ONLYOFFICE Docs ao Jira

Requisitos

ONLYOFFICE Document Server v6.4.0 (servidor ou versão cloud) ou posterior
Você precisa de uma instância do ONLYOFFICE Docs que seja resolvível e conectável tanto do Jira quanto de qualquer cliente final. Deve ser capaz de fazer POST para o Jira diretamente.
Consulte a página de documentação oficial para saber mais sobre a instalação do ONLYOFFICE Docs.
Jira Software (Server ou Data Center) v. 9.0.0 - 9.9.*
Consulte a documentação oficial da Atlassian para saber mais sobre a instalação do Jira Software.
Conector ONLYOFFICE v2.1.0 ou posterior para Jira

Instalando o conector ONLYOFFICE para Jira

Você pode baixar o conector do Marketplace oficial da Atlassian ou compilá-lo dos códigos-fonte disponíveis no GitHub.

Adicionando o conector do marketplace da Atlassian

Faça login na sua instância Jira Software como administrador.
Clique no ícone Administração no canto superior direito e escolha a opção Gerenciar aplicativos do menu.
A seção Encontrar novos aplicativos será aberta. Clique no campo Pesquisar no Marketplace e encontre o aplicativo de integração Jira ONLYOFFICE.
Clique no botão Instalar para baixar e instalar o aplicativo.

Adicionando o conector compilado do código-fonte

Primeiramente, você precisa instalar os seguintes pré-requisitos para conseguir compilar o conector ONLYOFFICE para Jira:

Para compilar o conector ONLYOFFICE para Jira, siga estes passos:

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 está sendo compilado. Depois que terminar, o conector pode ser encontrado na pasta target

Você pode carregar o conector compilado na sua página Administração do Jira Software > Gerenciar Aplicativos .

Faça login na sua instância Jira Software como administrador.
Clique no ícone Administração no canto superior direito e escolha a opção Gerenciar aplicativos do menu.
Selecione a seção Gerenciar aplicativos no lado esquerdo da página.
Clique no link Carregar aplicativo.
Clique no botão Escolher Arquivo, procure o arquivo compilado target/onlyoffice-jira-app.jar e clique em Carregar. Aguarde enquanto o aplicativo está sendo instalado.

Configurando o conector ONLYOFFICE para Jira

Clique no botão Configurar abaixo do aplicativo de integração Jira ONLYOFFICE instalado na página Gerenciar aplicativos ou encontre o aplicativo na seção OUTROS da página Gerenciar aplicativos.

No campo Endereço do Serviço de Edição de Documentos, especifique o endereço IP ou nome do host do servidor com o ONLYOFFICE Docs instalado.

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

Desabilitar verificação de certificado (inseguro) - marque esta caixa para desabilitar a verificação de certificado e permitir que o Jira estabeleça conexão com o ONLYOFFICE Docs se você estiver usando um certificado autoassinado para seu ONLYOFFICE Docs (caso contrário, o Jira não validará um certificado autoassinado e não permitirá conexão de/para o ONLYOFFICE Docs). Esta é uma solução insegura, e recomendamos fortemente que você substitua o certificado por um emitido por alguma AC.

Especifique uma Chave secreta - o segredo para validar o token web JSON mediante solicitação ao ONLYOFFICE Docs.

A partir do ONLYOFFICE Docs v7.2, o JWT está habilitado por padrão e a chave secreta é gerada automaticamente. Você precisa habilitá-lo no lado do Jira também: encontre sua chave secreta no arquivo de configuração do ONLYOFFICE Docs, depois especifique a mesma chave secreta nas configurações do conector. Para mais detalhes, veja a seção Habilitando JWT para a integração ONLYOFFICE e Jira deste artigo.

A seção Configurações avançadas do servidor pode ser usada se sua configuração de rede não permitir solicitações entre o Jira Software instalado e o ONLYOFFICE Docs usando os endereços públicos. Neste caso, especifique endereços para solicitações internas nos campos correspondentes:

Endereço do servidor Jira Software para solicitações internas do ONLYOFFICE Docs.
Endereço do ONLYOFFICE Docs para solicitações internas do servidor Jira Software.

Clique em Salvar para salvar as configurações.

Como funciona

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

O usuário navega pelos anexos do Jira e seleciona a ação Editar no ONLYOFFICE.
O Jira faz uma solicitação para OnlyOfficeEditorServlet (URL da forma: /plugins/servlet/onlyoffice/doceditor?attachmentId=$attachment.id).
O Jira envia o documento para o serviço de armazenamento de documentos ONLYOFFICE e recebe um link temporário.
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 sobre o status da edição do documento;
- docserviceApiUrl: a URL que o cliente precisa para responder ao ONLYOFFICE Docs (fornecida pela propriedade files.docservice.url.api);
- key: o UUID para instruir o ONLYOFFICE Docs se deve baixar o documento novamente ou não;
- title: o título (nome) do documento.
O Jira pega esse objeto e constrói uma página a partir de um template freemarker, preenchendo todos esses valores para que o navegador cliente possa carregar o editor.
O navegador cliente faz uma solicitação para a biblioteca JavaScript do ONLYOFFICE Docs e envia para o ONLYOFFICE Docs a configuração DocEditor com as propriedades acima.
Então o ONLYOFFICE Docs baixa o documento do armazenamento de documentos e o usuário começa a editar.
Quando todos os usuários e navegadores clientes terminam de editar, eles fecham a janela de edição.
Após 10 segundos de inatividade, o ONLYOFFICE Docs envia um POST para callbackUrl informando ao Jira que os clientes terminaram de editar o documento e o fecharam.
O documento com todas as alterações é salvo como um novo anexo com o sufixo adicionado ao nome do arquivo.

Habilitando JWT para a integração ONLYOFFICE e Jira

Para proteger documentos de acesso não autorizado, os editores ONLYOFFICE usam o JSON Web Token (JWT). O token é adicionado na 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 token web JSON e validar o token mediante solicitação ao ONLYOFFICE Docs.

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

Passo 1: Encontre sua chave secreta no arquivo de configuração do ONLYOFFICE Docs

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 – acesse o container ONLYOFFICE Docs usando o comando docker exec -it <containerID> bash e abra /etc/onlyoffice/documentserver/local.json
  Alternativamente, você pode usar o seguinte comando 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 ficar assim:
```
{"services": {"CoAuthoring": {"token": {"enable": {"request": {"inbox": true,"outbox": true},"browser": true}},"secret": {"inbox": {"string": "yoursecret"},"outbox": {"string": "yoursecret"},"session": {"string": "yoursecret"}}}}}
```
O valor true é especificado em três seções. Isso significa que a validação de token está habilitada.
- services.CoAuthoring.token.enable.browser
- services.CoAuthoring.token.enable.request.inbox
- services.CoAuthoring.token.enable.request.outbox
A chave secreta gerada automaticamente é especificada em três seções. Você pode substituir o valor secreto padrão pela sua própria chave secreta. A chave secreta deve ser a mesma nas três seções.
- services.CoAuthoring.secret.inbox.string
- services.CoAuthoring.secret.outbox.string
- services.CoAuthoring.secret.session.string
Se você fizer alterações, salve-as e reinicie os serviços para que as mudanças de configuração tenham efeito.
```
supervisorctl restart all
```

Passo 2: Especifique a mesma chave secreta nas configurações do conector

Nas configurações do conector, especifique o mesmo segredo no campo Chave secreta e salve as configurações.

Conectando ao ONLYOFFICE Docs de demonstração

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

Para ativar a conexão, marque a caixa Conectar ao servidor de demonstração ONLYOFFICE Docs e clique no botão Salvar.

ImportanteEste é um servidor de teste público que estará disponível durante um período de 30 dias. Não compartilhe seus dados confidenciais lá.

Começar a usar ONLYOFFICE Docs no Jira

Criando, visualizando e editando arquivos

Você pode abrir os editores ONLYOFFICE de qualquer bloco de Anexos de uma questão. Esta opção está disponível para questões de qualquer módulo onde uma questão pode ser aberta, por exemplo, lista de questões, backlog, questões, etc.

Os anexos devem estar habilitados pelo administrador.

Um novo anexo pode ser adicionado na página da questão usando a opção Mais -> Anexar arquivos. Para saber mais, veja a documentação oficial.

Para abrir um documento de texto, planilha, apresentação ou formulário existente, mova o ponteiro do mouse sobre o arquivo necessário e clique no ícone ONLYOFFICE_conector Editar no ONLYOFFICE. Se o formato do arquivo não for suportado para edição, a opção Visualizar no ONLYOFFICE estará disponível. Para arquivos .oform, a opção Preencher formulário no ONLYOFFICE estará disponível. O documento resultante será salvo em formato PDF.

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

Para criar um novo arquivo usando os editores ONLYOFFICE:

No bloco Anexos de uma questão, clique na opção Criar arquivo com ONLYOFFICE.
Escolha o tipo de arquivo necessário: Documento, Planilha, Apresentação ou Modelo de formulário.
Digite o nome do arquivo e clique em Criar.
O arquivo será aberto em uma nova aba do navegador no editor ONLYOFFICE correspondente.

Após o término da sessão de edição, 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 colaborativamente, as alterações são salvas apenas após o último usuário sair do editor.

Permissões de acesso

As permissões de acesso para arquivos dependem dos direitos de acesso de um usuário à questão correspondente.

Editando arquivos. Para poder editar arquivos, um usuário deve ter permissões para criar anexos (Create attachments).

Visualizando arquivos. A pré-visualização de arquivos nos visualizadores ONLYOFFICE está disponível para todos os usuários que podem visualizar uma questão, mas não têm permissões para editar a questão ou permissões para criar anexos. Se o formato do arquivo não for suportado para edição, o arquivo será aberto para visualização.

Convertendo documentos

Para converter um documento para o formato Office Open XML:

Mova o ponteiro do mouse sobre o arquivo necessário e clique no ícone Serviço de conversão ONLYOFFICE .
Opcionalmente, você pode alterar o nome do arquivo.
Clique no botão Converter.
O arquivo convertido será armazenado no bloco Anexos.

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 do arquivo, por exemplo, Sample-1.docx.

As alterações feitas em um arquivo durante o processo de co-ediçã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 à questão.

Baixando arquivos

Para baixar um documento em um formato diferente:

Mova o ponteiro do mouse sobre o arquivo necessário e clique no ícone Serviço de conversão ONLYOFFICE .
Opcionalmente, você pode alterar o nome do arquivo.
Selecione o formato necessário da lista Tipo de destino.
Clique no botão Baixar.
O arquivo baixado será armazenado no seu computador.

Host ONLYOFFICE Docs on your own server or use it in the cloud

Get it now Use in the cloud