Jira

Informazioni sull'integrazione di ONLYOFFICE e Jira

ONLYOFFICE offre connettori ufficiali per integrare ONLYOFFICE Docs con Jira e collaborare sui documenti d'ufficio allegati alle tue issue di Jira. Sono disponibili due connettori, a seconda della distribuzione di Jira:

• Jira Data Center / Server — disponibile su Atlassian Marketplace e su GitHub. Distribuito con licenza Apache.
• Jira Cloud — disponibile su Atlassian Marketplace e su GitHub. Distribuito con licenza Apache.

note

Per saperne di più su come funziona il connettore di Jira, visita la nostra documentazione API.

Funzionalità principali

• Creazione di nuovi documenti, fogli di calcolo, presentazioni e moduli.

• Visualizzazione e modifica di documenti di testo, fogli di calcolo, presentazioni e moduli con l'opzione Edit in ONLYOFFICE (Modifica in ONLYOFFICE).

  note

  Per saperne di più sui moduli, leggi gli articoli corrispondenti sulla creazione e sulla compilazione dei moduli.

• Co-editing dei documenti in tempo reale: due modalità di co-editing (Veloce e Rigorosa), revisione delle modifiche, commenti e una chat integrata.

• Supporto JWT per proteggere il traffico, in modo che solo gli utenti con i diritti appropriati abbiano accesso ai tuoi documenti.

• Supporto dell'assistente IA (solo Jira Cloud) — collega il provider di IA che preferisci tramite il plugin IA. Compatibile con OpenAI, Mistral, Anthropic, Google Gemini, DeepSeek e altri. Consulta la guida all'IA per i dettagli.

Formati supportati

Per la visualizzazione:

• 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

Per la modifica:

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

I formati seguenti sono disponibili per la modifica anche in Jira Data Center / Server. Tieni presente che la modifica di questi formati può comportare la perdita di informazioni:

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

Novità della versione 4.1.1

Jira Data Center

Modificato

• Risolto un problema con le richieste HTTP del plugin quando Jira è distribuito con un percorso di contesto.

Il registro completo delle modifiche è disponibile qui.

Jira Cloud

Aggiunto

• Versione iniziale del connettore ONLYOFFICE per Jira Cloud.

Il registro completo delle modifiche è disponibile qui.

Collegamento di ONLYOFFICE Docs a Jira Data Center / Server

Requisiti

• ONLYOFFICE Document Server v6.4.0 (versione server o cloud) o successiva.

  Hai bisogno di un'istanza di ONLYOFFICE Docs risolvibile e raggiungibile sia da Jira sia da qualsiasi client finale. Deve poter inviare richieste POST direttamente a Jira.

  note

  Consulta la pagina della documentazione ufficiale per saperne di più sull'installazione di ONLYOFFICE Docs.

• Jira Software. Esistono due connettori per le diverse versioni di Jira Data Center:

  • Connettore ONLYOFFICE v3.1.1 per Jira Software (Server o Data Center) v. 9.0.0 — 9.17.5
  • Connettore ONLYOFFICE v4.1.1 per Jira Software (Server o Data Center) v. 10.0.0 — 10.7.2
  note

  Consulta la documentazione di Atlassian ufficiale per saperne di più sull'installazione di Jira Software.

• Connettore ONLYOFFICE per Jira.

  Consulta questo elenco per scaricare la versione del connettore richiesta.

Installazione del connettore ONLYOFFICE per Jira

Puoi scaricare il connettore dall'Atlassian Marketplace ufficiale oppure compilarlo dai codici sorgente disponibili su GitHub.

Aggiunta del connettore dall'Atlassian Marketplace

• Accedi alla tua istanza di Jira Software come amministratore.

• Fai clic sull'icona Administration (Amministrazione) nell'angolo in alto a destra e scegli l'opzione Manage apps (Gestisci app) dal menu.

  

• Si aprirà la sezione Find new apps (Trova nuove app). Fai clic sul campo Search the Marketplace (Cerca nel Marketplace) e trova l'app di integrazione Jira ONLYOFFICE (Jira ONLYOFFICE integration app).

• Fai clic sul pulsante Install (Installa) per scaricare e installare l'applicazione.

Aggiunta del connettore compilato dal codice sorgente

Per prima cosa, devi installare i seguenti prerequisiti per poter compilare il connettore ONLYOFFICE per Jira:

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

Per compilare il connettore ONLYOFFICE per Jira, segui questi passaggi:

• Clona il repository onlyoffice-jira.

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

• Vai alla directory onlyoffice-jira.

  cd onlyoffice-jira

• Esegui il comando seguente:

  atlas-package

Attendi il completamento della compilazione del connettore. Al termine, il connettore si trova nella cartella target.

Puoi caricare il connettore compilato nella pagina Jira Software Administration > Manage Apps.

• Accedi alla tua istanza di Jira Software come amministratore.

• Fai clic sull'icona Administration (Amministrazione) nell'angolo in alto a destra e scegli l'opzione Manage apps (Gestisci app) dal menu.

• Seleziona la sezione Manage apps sul lato sinistro della pagina.

• Fai clic sul link Upload app (Carica app).

• Fai clic sul pulsante Choose File (Scegli file), individua il file compilato target/onlyoffice-jira-app.jar e fai clic su Upload (Carica). Attendi l'installazione dell'applicazione.

  

Configurazione del connettore ONLYOFFICE per Jira

Fai clic sul pulsante Configure (Configura) sotto l'app di integrazione Jira ONLYOFFICE installata nella pagina Manage apps oppure trova l'app nella sezione OTHER della pagina Manage apps.

Document Server

1. Nel campo Document Editing Service address (Indirizzo del servizio di modifica dei documenti), specifica l'indirizzo IP o il nome host del server su cui è installato ONLYOFFICE Docs.

   note

   L'indirizzo di ONLYOFFICE Docs deve essere accessibile da Jira, così come l'indirizzo di Jira deve essere accessibile da ONLYOFFICE Docs.

2. Disable certificate verification (insecure) (Disabilita la verifica del certificato (non sicuro)) — seleziona questa casella per disabilitare la verifica del certificato e consentire a Jira di stabilire una connessione con ONLYOFFICE Docs se utilizzi un certificato autofirmato. Questa soluzione non è sicura; ti consigliamo vivamente di sostituire il certificato con uno emesso da una CA.

3. Specifica una Secret key (Chiave segreta) (lascia vuoto per disabilitare) — il segreto per convalidare il JSON Web Token nella richiesta a ONLYOFFICE Docs.

   note

   A partire da ONLYOFFICE Docs v7.2, JWT è abilitato per impostazione predefinita e la chiave segreta viene generata automaticamente. Devi abilitarlo anche lato Jira: trova la tua chiave segreta nel file di configurazione di ONLYOFFICE Docs, quindi specifica la stessa chiave segreta nelle impostazioni del connettore. Per ulteriori dettagli, consulta la sezione Abilitazione di JWT di questo articolo.

4. Authorization header (Intestazione di autorizzazione) (lascia vuoto per usare l'intestazione predefinita) — l'intestazione JWT di autorizzazione usata in ONLYOFFICE è Authorization. Se questa intestazione è in conflitto con la tua configurazione, puoi sostituirla con una personalizzata.

5. Connect to demo ONLYOFFICE Document Server (Connetti al ONLYOFFICE Document Server demo) — avvia un server di prova.

   Importante

   Questo è un server di prova pubblico che sarà disponibile per un periodo di 30 giorni. Non condividere lì i tuoi dati sensibili.

Advanced server settings (Impostazioni avanzate del server)

La sezione Advanced server settings può essere utilizzata se la configurazione di rete non consente richieste tra Jira Software e ONLYOFFICE Docs tramite indirizzi pubblici. Specifica gli indirizzi per le richieste interne nei campi corrispondenti:

1. Server address for internal requests from the Document Editing Service (Indirizzo del server per le richieste interne dal servizio di modifica dei documenti) — indirizzo del server Jira Software per le richieste interne da ONLYOFFICE Docs.
2. Document Editing Service address for internal requests from the server (Indirizzo del servizio di modifica dei documenti per le richieste interne dal server) — indirizzo di ONLYOFFICE Docs per le richieste interne dal server Jira Software.

Common settings (Impostazioni comuni)

1. Editable formats (Formati modificabili) — seleziona la casella accanto ai formati supportati dal tuo ambiente Jira.

   Può verificarsi una perdita di dati durante il salvataggio nei formati specificati a causa delle limitazioni dei formati.

2. Editor interface (Interfaccia dell'editor) — personalizza l'interfaccia degli editor:

   • Display Chat menu button — nasconde/mostra l'icona Chat integrata online nel pannello a sinistra.
   • Display the header more compact — nasconde/mostra il testo delle icone nella barra degli strumenti superiore.
   • Display Feedback & Support menu button — nasconde/mostra il pulsante Feedback & Support nel pannello a sinistra.
   • Display Help menu button — nasconde/mostra il pulsante Help (Guida) nel pannello a sinistra.
   • Display monochrome toolbar header — passa la barra degli strumenti superiore a una tavolozza di colori monocromatica.

Security (Sicurezza)

1. Enable plugins — abilita/disabilita il supporto dei plugin per gli editor.
2. Run document macros — abilita/disabilita l'esecuzione delle macro negli editor.
3. Enable document protection for — scegli se consentire a tutti gli utenti di abilitare la protezione con password dei documenti oppure solo al proprietario del documento.

Fai clic su Save (Salva) per salvare le impostazioni.

Come funziona

L'integrazione di ONLYOFFICE segue l'API documentata qui.

1. Un utente passa agli allegati di Jira e seleziona l'azione Edit in ONLYOFFICE.
2. Jira invia una richiesta a OnlyOfficeEditorServlet (URL del tipo: /plugins/servlet/onlyoffice/doceditor?attachmentId=$attachment.id).
3. Jira invia il documento al servizio di archiviazione dei documenti di ONLYOFFICE e riceve un link temporaneo.
4. Jira prepara un oggetto JSON con le seguenti proprietà:
   • url: il link temporaneo che ONLYOFFICE Docs usa per scaricare il documento;
   • callbackUrl: l'URL che ONLYOFFICE Docs usa per informare sullo stato della modifica del documento;
   • docserviceApiUrl: l'URL a cui il client deve rispondere a ONLYOFFICE Docs (fornito dalla proprietà files.docservice.url.api);
   • key: l'UUID che indica a ONLYOFFICE Docs se scaricare di nuovo il documento o no;
   • title: il titolo (nome) del documento.
5. Jira prende questo oggetto e costruisce una pagina da un modello freemarker, inserendo tutti questi valori in modo che il browser del client possa caricare l'editor.
6. Il browser del client invia una richiesta alla libreria JavaScript di ONLYOFFICE Docs e le invia la configurazione di DocEditor con le proprietà sopra indicate.
7. Quindi ONLYOFFICE Docs scarica il documento dall'archivio dei documenti e l'utente inizia la modifica.
8. Quando tutti gli utenti e i browser client hanno terminato la modifica, chiudono la finestra di modifica.
9. Dopo 10 secondi di inattività, ONLYOFFICE Docs invia un POST a callbackUrl per informare Jira che i client hanno terminato la modifica del documento e lo hanno chiuso.
10. Il documento con tutte le modifiche viene salvato come nuovo allegato, con un suffisso aggiunto al nome del file.

Abilitazione di JWT

Per proteggere i documenti dall'accesso non autorizzato, gli editor ONLYOFFICE utilizzano il JSON Web Token (JWT). Il token viene aggiunto alla configurazione quando l'editor di documenti viene inizializzato e durante lo scambio di comandi tra i servizi interni di ONLYOFFICE Docs. La chiave segreta viene utilizzata per firmare il JSON Web Token e convalidare il token nella richiesta a ONLYOFFICE Docs.

A partire da ONLYOFFICE Docs v7.2, JWT è abilitato per impostazione predefinita e la chiave segreta viene generata automaticamente. Devi trovare la tua chiave segreta nel file di configurazione di ONLYOFFICE Docs, quindi specificare la stessa chiave segreta nelle impostazioni del connettore.

Passaggio 1: trova la tua chiave segreta nel file di configurazione di ONLYOFFICE Docs

1. Apri il file local.json con qualsiasi editor di testo disponibile:

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

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

   • Per Docker — entra nel container di ONLYOFFICE Docs con il comando docker exec -it <containerID> bash e apri /etc/onlyoffice/documentserver/local.json.

     In alternativa, puoi usare il seguente comando per trovare la chiave segreta predefinita senza aprire local.json:

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

   Il file local.json dovrebbe avere questo aspetto:

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

2. Il valore true è specificato in tre sezioni, il che significa che la convalida del token è abilitata:

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

3. La chiave segreta generata automaticamente è specificata in tre sezioni. Puoi sostituire il valore predefinito con la tua chiave segreta — deve essere la stessa in tutte e tre:

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

4. Se apporti modifiche, salvale e riavvia i servizi:

   supervisorctl restart all

Passaggio 2: specifica la stessa chiave segreta nelle impostazioni del connettore

Nelle impostazioni del connettore, specifica la stessa chiave segreta nel campo Secret key (Chiave segreta) e salva le impostazioni.

Collegamento a ONLYOFFICE Docs demo

A partire dalla versione 2.0.0 del connettore ONLYOFFICE, puoi provare gli editor online ONLYOFFICE all'interno di Jira senza installare ONLYOFFICE Docs.

Per attivare la connessione, seleziona la casella Connect to demo ONLYOFFICE Docs server e fai clic sul pulsante Save (Salva).

Importante

Questo è un server di prova pubblico che sarà disponibile per un periodo di 30 giorni. Non condividere lì i tuoi dati sensibili.

Collegamento di ONLYOFFICE Docs a Jira Cloud

Requisiti

• Un'istanza di ONLYOFFICE Docs, self-hosted o cloud.
• Jira Cloud.
• Connettore ONLYOFFICE per Jira Cloud dall'Atlassian Marketplace.

Installazione del connettore ONLYOFFICE per Jira Cloud

• Vai su marketplace.atlassian.com.
• Trova ONLYOFFICE Connector for Jira e fai clic sul pulsante Get it now (Ottienilo ora).
• Nella finestra a comparsa, seleziona il sito su cui vuoi installare l'app e scegli l'edizione se sono disponibili più opzioni.

Configurazione del connettore ONLYOFFICE per Jira Cloud

Gli amministratori possono configurare l'app ONLYOFFICE da Apps → Manage apps → ONLYOFFICE Connector for Jira → Configure. Nella pagina di configurazione, imposta:

• ONLYOFFICE Docs address (Indirizzo di ONLYOFFICE Docs) — l'URL di ONLYOFFICE Docs installato.
• ONLYOFFICE Docs secret key (Chiave segreta di ONLYOFFICE Docs) — abilita JWT per proteggere i tuoi documenti dall'accesso non autorizzato. Consulta la guida alla configurazione di JWT per i dettagli.
• Authorization header (Intestazione di autorizzazione).

Puoi anche collegarti per un mese al server di prova pubblico di ONLYOFFICE Docs selezionando la casella corrispondente.

Importante

Questo è un server di prova pubblico che sarà disponibile per un periodo di 30 giorni. Non condividere lì i tuoi dati sensibili.

Come iniziare a usare ONLYOFFICE Docs in Jira Data Center / Server

Creazione, visualizzazione e modifica dei file

Puoi aprire gli editor ONLYOFFICE da qualsiasi blocco Attachments (Allegati) di una issue. Questa opzione è disponibile per le issue di qualsiasi modulo in cui è possibile aprire una issue, ad es. elenco delle issue, backlog ecc.

note

Gli allegati devono essere abilitati dall'amministratore.

Un nuovo allegato può essere aggiunto nella pagina della issue con l'opzione More → Attach files (Altro → Allega file). Per saperne di più, consulta la documentazione ufficiale.

Per aprire un documento di testo, un foglio di calcolo, una presentazione o un modulo esistente, posiziona il puntatore del mouse sul file desiderato e fai clic sull'icona Edit in ONLYOFFICE. Se il formato del file non è supportato per la modifica, è disponibile l'opzione View in ONLYOFFICE (Visualizza in ONLYOFFICE). Per i file .oform è disponibile l'opzione Fill in form in ONLYOFFICE (Compila il modulo in ONLYOFFICE). Il documento risultante verrà salvato in formato PDF.

Il file verrà aperto in una nuova scheda del browser nell'editor ONLYOFFICE corrispondente.

Per creare un nuovo file con gli editor ONLYOFFICE:

• Nel blocco Attachments di una issue, fai clic sull'opzione Create file with ONLYOFFICE (Crea file con ONLYOFFICE).

• Scegli il tipo di file necessario: documento, foglio di calcolo, presentazione o modello di modulo.

• Digita il nome del file e fai clic su Create (Crea).

  

• Il file verrà aperto in una nuova scheda del browser nell'editor ONLYOFFICE corrispondente.

Al termine della sessione di modifica, un documento con tutte le modifiche verrà salvato come nuovo allegato. Lo riconoscerai dallo stesso nome con un suffisso. Se stai modificando un allegato in modo collaborativo, le modifiche vengono salvate solo dopo che l'ultimo utente esce dall'editor.

Autorizzazioni di accesso

Le autorizzazioni di accesso ai file dipendono dai diritti di accesso dell'utente alla issue corrispondente.

Modifica dei file. Per poter modificare i file, l'utente deve avere l'autorizzazione a creare allegati (Create attachments).

Visualizzazione dei file. L'anteprima dei file nei visualizzatori ONLYOFFICE è disponibile per tutti gli utenti che possono vedere una issue, ma che non hanno l'autorizzazione a modificare la issue né l'autorizzazione a creare allegati. Se il formato del file non è supportato per la modifica, il file verrà aperto in visualizzazione.

Conversione dei documenti

Per convertire un documento nel formato Office Open XML:

• Posiziona il puntatore del mouse sul file desiderato e fai clic sull'icona ONLYOFFICE conversion service (Servizio di conversione ONLYOFFICE).

  

• Facoltativamente, puoi modificare il nome del file.

• Fai clic sul pulsante Convert (Converti).

• Il file convertito verrà archiviato nel blocco Attachments.

  

Salvataggio delle modifiche

Le modifiche apportate a un file vengono salvate in un nuovo file con lo stesso nome del file originale, con un suffisso aggiunto alla fine del nome, ad es. Sample-1.docx.

Le modifiche apportate a un file durante il co-editing vengono salvate solo nella prima versione del file. Se il documento viene modificato contemporaneamente da più utenti, le modifiche saranno visualizzate solo nel primo file. Finché l'ultimo utente non chiude l'editor, non viene aggiunta alla issue una nuova versione del file.

Download dei file

Per scaricare un documento in un formato diverso:

• Posiziona il puntatore del mouse sul file desiderato e fai clic sull'icona ONLYOFFICE conversion service (Servizio di conversione ONLYOFFICE).

  

• Facoltativamente, puoi modificare il nome del file.

• Seleziona il formato necessario dall'elenco Target type (Tipo di destinazione).

• Fai clic sul pulsante Download (Scarica).

• Il file scaricato verrà salvato sul tuo computer.

note

Per saperne di più sui problemi più comuni e sui modi per risolverli, visita la nostra guida alla risoluzione dei problemi.

Come iniziare a usare ONLYOFFICE Docs in Jira Cloud

La pagina della issue di Jira include una sezione ONLYOFFICE Docs. Se non la vedi, fai clic sull'icona a forma di ingranaggio sotto il titolo della issue e seleziona ONLYOFFICE Docs per abilitarla.

Creazione di file

Per creare un nuovo file, fai clic sul pulsante Create with ONLYOFFICE (Crea con ONLYOFFICE). Nella finestra a comparsa, inserisci un nome di file e scegli un formato. Attualmente puoi creare file nei formati DOCX, XLSX, PPTX e modulo PDF.

Dopo aver fatto clic su Create (Crea), il file verrà generato e aperto immediatamente in una finestra a comparsa con i permessi di modifica. Il file appena creato verrà aggiunto anche alla sezione Attachments.

Modifica e visualizzazione dei file

Per aprire un file esistente in modifica, fai clic sull'icona a forma di matita accanto ad esso. Per aprirlo solo in visualizzazione, fai clic sull'icona a forma di occhio. L'editor verrà avviato di conseguenza.

Importante

A causa delle limitazioni del connettore, l'editor non può rimanere aperto per lunghi periodi. Deve essere riavviato ogni quattro ore per garantire un funzionamento regolare.

Autorizzazioni di accesso

• Download e visualizzazione: disponibili per tutti gli utenti con accesso alla issue di Jira.
• Modifica: gli utenti possono modificare i file che hanno creato. Per modificare i file creati da altri, gli utenti devono avere l'autorizzazione Delete All Attachments.

Per concedere i permessi di modifica a un ruolo Jira specifico:

• Apri il menu contestuale del progetto desiderato e seleziona Project settings (Impostazioni del progetto).
• Vai alla sezione Permissions (Autorizzazioni), fai clic sul pulsante Action (Azione) e aggiorna l'elenco dei ruoli per Delete All Attachments.