Jira

Yhteenveto

Jira-yhteys mahdollistaa Siesta AI -alustan turvallisen yhdistämisen Atlassian Jiraan virallisen API:n kautta. Integraatio tarjoaa hallitun pääsyn Jira-projekteihin ja issueihin ja mahdollistaa:

• issueiden luomisen,
• issueiden etsimisen ja lataamisen,
• olemassa olevien issueiden päivittämisen,
• issueiden käyttäjille määrittämisen.

Suunniteltu varten:

• häiriö- ja operaatioautomaatio,
• insinöörityönkulkujen orkestrointi,
• ulkoisten järjestelmien (CRM, valvonta, AI-agentit) synkronointi,
• auditoitavat tikettipohjaiset prosessit.

Vaatimukset

• Aktiivinen Jira Cloud -sivusto.
• Atlassian-tili, jolla on pääsy Jira-projekteihin, joiden kanssa liitin työskentelee.
• Generoitu API-token Atlassian-tilillä (id.atlassian.com → Security → API tokens).
• Ylläpitäjän oikeudet liitännän hallintaan Siesta AI:ssa.

Konfigurointiparametrit

Pakolliset parametrit

Parametri	Kuvaus
Nimi	Liittimen sisäinen tunnus
ApiKey	Atlassian-tilillä generoitu API-token
Email or username of Atlassian account	Sähköposti (tai käyttäjänimi) tililtä, jonka alla token on luotu
URL	Jira/Atlassian-instanssin URL (esim. https://firma.atlassian.net)

Jira-liittimen lisäämisprosessin vaiheet

1) Valmistele pääsytiedot

Ennen kuin aloitat liitännän luomisen Siesta AI:ssa, valmistele kaikki arvot, jotka aiot syöttää lomakkeeseen.

Avaa Atlassian-tililläsi Security ja API Tokens -osio.

Napsauta Create API token (ilman scopeja), syötä tokenin nimi ja voimassaoloaika, ja vahvista luominen.

Kun token on luotu, kopioi se kerran ja tallenna turvallisesti.

Valmistele myös:

• Sähköposti tai käyttäjänimi Atlassian-tililtä, jonka alla token on luotu
• URL Jira/Atlassian-instanssi (esim. https://firma.atlassian.net)

2) Avaa integraatioiden hallinta Siesta AI:ssa

Siesta AI:n hallinnassa siirry kohtaan Administration → Connected Apps.

3) Valitse Jira

Add Connection (Lisää integraatio) -dialogissa valitse Jira ja jatka.

4) Täytä Jira-lomake

Täytä:

• Nimi
• ApiKey (token Atlassianista)
• Sähköposti / käyttäjänimi Atlassian-tililtä, jonka alla token on luotu
• URL (esim. https://firma.atlassian.net)

Vahvista integraation luominen.

5) Aseta toimintojen oikeudet

Integraation luomisen jälkeen avaa Oikeusasetukset ja määritä sallitut toiminnot.

Suositus: kirjoitustoiminnot määritä Sallituksi vahvistuksella.

Tärkeä huomautus API-tokenista ja oikeuksista

API-token on sidottu tiettyyn Atlassian-tiliin. Liitin perii tämän tilin oikeudet Jirassa (mitä tili ei näe tai voi muuttaa, sitä ei voi muuttaa liittimellä).

Tästä syystä suositellaan:

• että jokaisella käyttäjällä on oma token, jos liitäntä toimii hänen identiteettinsä alla,
• tai käyttää omistettua palvelutiliä jaettuihin/tuotantoautomaatioihin,
• seurata tokenin voimassaoloaikaa ja suorittaa säännöllistä vaihtoa.

Varmennus ja turvallisuus

• Yhteys käyttää virallista Jira REST API:a.
• Yhteyden varmennus tapahtuu Atlassian-tilin ja API-tokenin (syötetty kenttään ApiKey) kautta.
• Oikeudet hallitaan suoraan Jira-instanssin tasolla.
• Assigneeiden kanssa työskenneltäessä Jira API:ssa käytetään AccountId:tä (ei sähköpostia).

Jos käyttäjällä ei ole oikeutta nähdä issueita, liitäntä ei myöskään näe niitä.

Peruskäsitteet

• IssueKey: tiketin ID (esim. PROJ-123).
• ProjectKey: Jira-projektin avain (esim. PROJ).
• AccountId: käyttäjän ainutlaatuinen tunniste Atlassian-ekosysteemissä.
• JQL: Jira Query Language.

1. Tikettien luominen

1.1 CreateTicketAsync

Kuvaus
Luo uusi Jira-issue annettuun projektiin.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
projectKey	String	Kyllä	Jira-projektin avain.
issueType	String	Kyllä	Issue-tyyppi (Task, Bug, Story, ...).
summary	String	Kyllä	Lyhyt issue-nimi.
description	String	Ei	Yksityiskohtainen kuvaus.
assigneeId	String	Ei	Atlassian Account ID käyttäjälle.

Käyttäytyminen

• IssueType:n on oltava olemassa projektissa.
• Ei tee fallbackia tai tyyppien kartoitusta.
• Huono yhdistelmä = epäonnistuminen.

2. Tikettien määrittäminen

2.1 AssignTicketAsync

Kuvaus
Määrittää olemassa olevan issue tietylle käyttäjälle.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen
issueKey	String	Kyllä
assigneeAccountId	String	Kyllä

Huomautus Jira ei huomioi sähköposteja. Account ID on ainoa luotettava tunniste.

3. Tikettien hakeminen

3.1 GetTicketAsync

Kuvaus
Palauttaa issue-yksityiskohdat issueKey:n mukaan.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen
issueKey	String	Kyllä

3.2 GetTicketsByProjectAsync

Kuvaus
Palauttaa issueita, jotka kuuluvat tiettyyn projektiin.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen
projectKey	String	Kyllä
maxResults	Int	Ei

3.3 GetTicketsByUserAsync

Kuvaus
Palauttaa issueita, jotka on määritetty tietylle käyttäjälle.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen
assigneeEmail	String	Kyllä
maxResults	Int	Ei

4. Tikettien päivittäminen

4.1 UpdateTicketAsync

Kuvaus
Päivittää olemassa olevan issue:n summaryn ja/tai descriptionin.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen
issueKey	String	Kyllä
summary	String	Ei
description	String	Ei

Käyttäytyminen

• Vain annetut kentät päivitetään.
• Ei tee validointia työnkulkujen tilasta.

5. Haku ja kysely

5.1 SearchTicketsAsync

Kuvaus
Hakee issueita JQL-kyselyn avulla.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen
jql	String	Kyllä
maxResults	Int	Ei

Esimerkki JQL

project = PROJ AND status = "To Do"

Virheellinen JQL palauttaa välittömän virheen.

6. Projektit ja käyttäjätoiminnot

6.1 GetAllProjectsAsync

Kuvaus
Palauttaa luettelon projekteista, jotka ovat nykyisen käyttäjän saatavilla.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen
maxResults	Int	Ei

6.2 GetUserAsync

Kuvaus
Palauttaa tietoja käyttäjästä Account ID:n mukaan.

Syöttöparametrit

Parametri	Tyyppi	Pakollinen
accountId	String	Kyllä

Suunnitteluperiaatteet

• Account ID > sähköposti (GDPR ja Atlassianin todellisuus).
• Ilmeiset syötteet ilman oletuksia.
• Fail-fast-käyttäytyminen virheellisissä pyyntöissä.
• Jira-työnkulkujen sääntöjen kunnioittaminen.

Yhteenveto

Jira-yhteys tarjoaa suoran, turvallisen ja auditoitavan pääsyn Jira-issueihin ja projekteihin. Se soveltuu automatisoituun tikettien hallintaan, häiriöagentteihin, insinöörityökalujen tuottavuuteen ja yritystyönkulkujen integraatioon.