JIRA Service Desk

Inleiding

Jira Service Management (JSM), ook gekend als Jira Service Desk (JSD), is een ticket management systeem voor het opvolgen van requests of incidenten. Deze connector legt de link met een self-hosted JSD-instantie (bijvoorbeeld van een Vlaamse overheidsdienst).

Use case

Via de JSD-connector kan je vanuit een dossier een ticket aanmaken in een Jira Service Management omgeving.

Setup

Onboarding

De aansluitingsgegevens (access-token, consumer-key, secret, private-key) worden niet zelf gegenereerd, maar manueel aangemaakt door de beheerder van de Jira Service Desk-omgeving bij de Vlaamse overheid, via een OAuth 1.0a-applicatielink (Application Link). Neem hiervoor contact op met de betrokken beheerder om deze waarden te bekomen.

Maven dependency in pom.xml

Voeg onderstaande maven dependency toe in je pom.xml. Dit zorgt ervoor dat de connector code binnengehaald en meegenomen wordt in de build van je applicatie.

<dependency>
   <groupId>com.skryv.connectors</groupId>
   <artifactId>jsd</artifactId>
   <version>${skryv.version}</version>
</dependency>

Applicatie eigenschappen

JSD-specifieke applicatie eigenschappen die je moet toevoegen.

Externe documentatie

Bekijk de Jira Server/Data Center REST API-referentiepagina’s voor meer technische info.

Services en functies

Overzicht

@RequiredArgsConstructor
public class MyOwnService {
    private final JsdCamundaConnector jsd;
}

createCustomer

Hiermee kan je een klant aanmaken in Jira Service Desk.

Workflow expression

${jsd.createCustomer(String email, String fullName)}

Java-code

String customerName = jsd.createCustomer(email, fullName);

Input

Output

Retourneert de aangemaakte klantnaam (String) als bevestiging. Dit is niet louter een bevestiging zonder inhoud: de teruggegeven waarde kan je verder gebruiken in het proces (bv. opslaan in het dossier).

Error

Deze connector zet fouten niet om naar een BpmnError. Elke fout (inclusief een klant die al bestaat) resulteert in een onafgevangen RuntimeException, en dus in een Camunda-incident dat manuele tussenkomst vereist. Je kan hier dus geen error boundary event op voorzien.

Voorbeeld van het foutbericht wanneer de klant al bestaat:

{
  "errorMessage": "This request is invalid. Check that the request contains all the required parameters and that the parameters are valid. (username : A user with that username already exists.)",
  "i18nErrorMessage": {
    "i18nKey": "sd.rest.error.bad.request.with.extra.info",
    "parameters": ["username : A user with that username already exists."]
  }
}

Dit bericht komt terecht in de Camunda-incidentmelding, niet in een gestructureerd, opvangbaar foutobject.

createTicket

Hiermee kan je een ticket aanmaken in Jira Service Desk. Deze functie bestaat in drie varianten, afhankelijk van welke gegevens je wil meegeven.

Workflow expression 1

Met expliciete serviceDeskId/requestTypeId, met collection-velden.

${jsd.createTicket(String serviceDeskId, String requestTypeId, TreeMap<String, String> requestFieldValues, TreeMap<String, String> requestComplexFieldValues, TreeMap<String, ArrayList<String>> requestCollectionValues, String raiseOnBehalfOf)}

Workflow expressie 2

Zonder expliciete serviceDeskId/requestTypeId. Deze worden uit de applicatie-eigenschappen gehaald.

${jsd.createTicket(TreeMap<String, String> requestFieldValues, TreeMap<String, String> requestComplexFieldValues, TreeMap<String, ArrayList<String>> requestCollectionValues, String raiseOnBehalfOf)}

Workflow expressie 3

Met expliciete serviceDeskId/requestTypeId, zonder collection-velden.

${jsd.createTicket(String serviceDeskId, String requestTypeId, TreeMap<String, String> requestFieldValues, TreeMap<String, String> requestComplexFieldValues, String raiseOnBehalfOf)}

Java-code

// Variant 1
String issueKey = jsd.createTicket(serviceDeskId, requestTypeId, requestFieldValues, requestComplexFieldValues, requestCollectionValues, raiseOnBehalfOf);

// Variant 2
String issueKey = jsd.createTicket(requestFieldValues, requestComplexFieldValues, requestCollectionValues, raiseOnBehalfOf);

// Variant 3
String issueKey = jsd.createTicket(serviceDeskId, requestTypeId, requestFieldValues, requestComplexFieldValues, raiseOnBehalfOf);

Input

Output

Retourneert de issue-key van het aangemaakte ticket (bv. "HELPDESK-123") als String. Ook hier geen ‘lege’ output, de issue-key kan je verder gebruiken in het proces (bv. opslaan in het dossier, gebruiken voor latere opvolging).

Error-handling

Zoals bij createCustomer: geen BpmnError-conversie. Elke fout (ontbrekend verplicht veld, ongeldig veld-id, verkeerd aanvraagtype, ...) resulteert in een onafgevangen RuntimeException en dus een Camunda-incident.