Integrare gli allegati di Jira Software e Jira Service Desk

Jira Software e Jira Service Desk permettono grazie il campo attachments la condivisione degli allegati all’interno di una issue.

Il campo Attachments può essere integrato facilmente per l’esportazione verso qualsiasi applicativo, grazie all’integrazione API ed alla flessibilità di Deep Connector.
E’ possibile, ad esempio, esportare allegati come file di licenze software o email dei clienti all’interno di un’applicazione aziendale utilizzata dal reparto commerciale, per rendere più agevole la comunicazione tra tecnici e commerciali e per mantenere allineati i diversi repository dei software della propria organizzazione: Jira ed il proprio CRM oppure Jira ed il gestionale aziendale.
Questa attività, che di per sé può sembrare lunga e macchinosa, richiede poco tempo grazie a Deep Connector.
Vedremo come effettuare questa attività senza bisogno di memorizzare i file su un database diverso da quello di Jira, in modo da non replicare i dati, mantenendo Jira il sistema master dell’integrazione.

Recupero degli allegati con Deep Connector

Per integrare gli attachments di Jira è importante conoscere innanzitutto come integrare le Issue di Jira. Se non sai come fare, leggi prima di continuare questo articolo per l’integrazione delle issue di Jira.

• Crea un nuovo Job, con un IN Metadata di tipo Jira WS. In questo modo potrai collegarti agevolmente alle API di Jira.

• Ricordati di impostare la configurazione dal tab Configuration del IN Metadata:

Fatto questo, compila il campo Content in questo modo:

$issueKey = "My ISSUE Key";
$jiraWs = $this->getClient();
$jiraWs->login();
$jiraMap = $this->getJob()->getMap("jira_map");
$resource = $jiraWs->getResource("issue");
$issue = $resource->get($issueKey);
$jiraAttachments = $jiraMap->getJiraAttachments($issue);

Il codice appena visto imposta anzitutto una variabile $issueKey con la Key della Issue di Jira, della quale vogliamo recuperare gli allegati.
Successivamente:

• Recuperiamo il client di connessione alle Jira API
• Effettuiamo il login con le credenziali fornite nella configurazione del web service
• Recuperiamo una issue di Jira, con chiave specificata nella variabile $issueKey
• Recuperiamo le informazioni relative agli attachment della issue, grazie all’utilizzo di una mappa di Deep Connector

La variabile $jiraAttachments avrà la seguente struttura:

Array
(
    [0] => Array
        (
            [self] => https://jiraserver.local/rest/api/2/attachment/10420
            [id] => 10420
            [filename] => attachment.txt
            [author] => Array
                (
                    [self] => https://jiraserver.local/rest/api/2/user?username=autore
                    [name] => autore@jiraserver.local
                    [key] => autore@jiraserver.local
                    [emailAddress] => autore@jiraserver.local
                    [avatarUrls] => Array
                        (
                            [48x48] => https://jiraserver.local/secure/useravatar?avatarId=10349
                            [24x24] => https://jiraserver.local/secure/useravatar?size=small&avatarId=10349
                            [16x16] => https://jiraserver.local/secure/useravatar?size=xsmall&avatarId=10349
                            [32x32] => https://jiraserver.local/secure/useravatar?size=medium&avatarId=10349
                        )

                    [displayName] => Autore
                    [active] => 1
                    [timeZone] => Europe/Rome
                )

            [created] => 2018-03-08T12:42:35.000+0100
            [size] => 2156
            [mimeType] => application/json
            [content] => https://jiraserver.local/secure/attachment/10420/attachment.txt
        )

)

Ovvero un array contenente un insieme di elementi, con le proprietà degli attachments di Jira, come ad esempio l’id o l’autore.

Richiamare una determinata issue

Nell’esempio precedente si è visto come recuperare gli attachments di una issue già prestabilita, mediante l’impostazione di una variabile $issueKey.

Se si volesse recuperare la issue tramite le API di Deep Connector, sarebbe sufficiente eliminare la seguente istruzione nel codice:

$issueKey = "My ISSUE Key";

Ed utilizzare invece la seguente istruzione:

$issueKey = $this->getJob()->getApiRequest()->getUserParam('issue_key');

In questo modo, impostiamo il connettore per l’utilizzo di un parametro issue_key da passare nell’URL dell’integrazione.
L’URL deve essere di questo tipo:

http://server_deep_connector/api/rest/connector_jobs/nome_job/issue_key/KEY

Ovvero dobbiamo invocare il Job di Deep Connector, passando la coppia di valori issue_key e valore della chiave.

Configurare una mappa in Deep Connector

Per recuperare gli allegati della issue di Jira, abbiamo fatto uso di una mappa.

La mappa rappresenta un insieme di funzioni messe a disposizione di tutti i Job per eseguire determinate operazioni, generalmente invocate più volte all’interno della stessa installazione.

Nel caso in cui una funzione sia utilizzata più volte nella propria integrazione, consigliamo di creare sempre una mappa.

Per creare una mappa in Deep Connector accedere al menu “Connector” e cliccare sul sottomenu Map.

A questo creare una mappa con il pulsante “Add Map” in alto a destra.

Nel nostro esempio, la mappa che abbiamo creato contiene un metodo per il recupero degli allegati da una Jira Issue.

Nel campo Content della mappa è sufficiente scrivere questa istruzione per ottenere il recupero degli allegati:

$this->_addMethod("getJiraAttachments", function($jiraIssue) {
$jiraAttachments = [];
if (is_array($jiraIssue) && array_key_exists("attachment",$jiraIssue["fields"]) && is_array($jiraIssue['fields']['attachment'])) {
	$jiraAttachments = $jiraIssue["fields"]["attachment"];
}
return $jiraAttachments;
});

Per aggiungere un metodo alla mappa si utilizza la funzione _addMethod(), che accetta come parametri il nome del metodo, che sarà richiamabile da qualsiasi Job del connettore e una funziona contenente le operazioni da svolgere nel nostro metodo.

Elencare gli allegati di Jira

E’ facile, una volta ottenuto un array con gli allegati, elencarli in una pagina HTML di un nostro software web.

$html = '<ul>';
 foreach ($jiraAttachments as $attachment) {
 	$url = $this->getJob()->getApiBaseUrl()."api/deep-authorization/".$token->getToken()."/connector_jobs/nome_job/file_id/".$attachment['id'].'/';
 	$html .= '<li><a target="jiraframe" href="'.$url.'">'.$attachment['filename'].'</a></li>';
 }
 $html .= '<iframe name="jiraframe" style="display:none"></iframe>';
 $html .= '</ul>';

Il codice sopra riportato utilizza un ciclo for del PHP per recuperare le informazioni dall’array recuperato nei punti precedenti e mostra all’interno di una lista HTML l’elenco di allegati, con un link interno a Deep Connector per la visualizzazione.
Il risultato è il seguente: