Tässä luvussa kuvataan liittimen määritysohjeet, joiden avulla liitin voi muodostaa yhteyden REST-rajapintaan.

Provisioningin määritystä varten tarvitset pääsyn Platform configuration -konsoliin.

1. Avaa Administration area (hammasratas-kuvake).
2. Avaa Connectors-näkymä.
3. Valitse "New connector"

4. Valitse Data Source type -arvoksi Generic REST API

5. Anna liittimelle nimi ja lisää yhteysasetukset:

• Connector name – anna liittimelle helposti tunnistettava nimi (nimen voi vaihtaa myöhemmin)
• Host url – REST-rajapinnan perus-url. Tätä voidaan käyttää lopullisen kutsuttavan url-osoitteen etuliitteenä.
• REST Connector type – Generic tai Google. Käytä Google-järjestelmille arvoa Google ja kaikille muille REST-rajapinnoille arvoa General.

Valitse oikea todennusmenetelmä sen järjestelmän mukaan, johon olet yhdistämässä

• Basic Auth – perustodennus, jossa käyttäjätunnus/salasana lähetetään base64-koodattuna todennusotsikkona
• Bearer Token – käyttää kiinteää bearer-token-todennusotsikkoa
• Disabled – julkisille rajapinnoille ilman todennusta (2025.3-julkaisusta alkaen)
• Auth Header – kiinteälle salaiselle otsikolle (2025.3-julkaisusta alkaen)
• Dynamic Token – OAuth 2.0 Client Credentials -vuolle ja vastaaville (2025.3-julkaisusta alkaen)
  • Esimerkki Dynamic Token -määrityksestä: https://docs.efecte.com/configure-connectors/ms-ado-connector
  • Kun käytät Dynamic Token -todennusta, sinun on asetettava myös Login Content type otsikoksi. Jos esimerkiksi Login Content type on application/json, sinun on lisättävä liittimeen otsikko:
    Content-Type application/json

Aseta oikea sivutus sen kolmannen osapuolen järjestelmän mukaan, johon yhdistät tällä liittimellä.

Generic REST API -liittimen sivutus tukee viittä erilaista sivutustyyppiä. Näitä käytetään ajastetuissa tehtävissä:

• Disabled – rajapinta ei tue sivutusta ja palauttaa kaiken datan yhdessä vastauksessa.
• Start & Offset – rajapinta käyttää start- ja offset-parametreja. Liitin kasvattaa jokaisella pyynnöllä automaattisesti start-arvoa offset-määrällä, kunnes kaikki data on haettu.
• Page Increment – rajapinta käyttää sivunumerointia. Liitin kasvattaa jokaisella pyynnöllä sivunumeroa yhdellä, kunnes tuloksia ei enää palaudu.
• Link Token – vastaus sisältää seuraavan sivun URL-osoitteen. Liitin seuraa tätä URL-osoitetta automaattisesti, kunnes seuraavaa linkkiä ei enää tarjota.
• Link Attribute Token – vastaus sisältää seuraavan sivun tokenin. Liitin lähettää tämän tokenin automaattisesti kyselyparametrina seuraavassa pyynnössä. Tätä käyttää esimerkiksi Google.

Täytä WebAPI-käyttäjän tiedot

• WebAPI user – valitse oikea WebAPI-käyttäjä, jota käytetään kirjoitettaessa tietoja ulkoisesta järjestelmästä Matrix42 Core-, Pro- ja IGA-ratkaisuihin
• WebAPI password – WebAPI-käyttäjän salasana

7. Tallenna liittimen tiedot

8. Lisää ulkoisen REST-rajapintajärjestelmän root https -varmenne, jotta Connector management (EPE) luottaa siihen.

Tämän voi tehdä vain Matrix42:

Connector certificates explained.

9. Matrix42 Core-, Pro- ja IGA-ratkaisu pystyy nyt muodostamaan yhteyden ulkoiseen REST-rajapintaan

• Seuraava vaihe on määrittää ajastettu tehtävä tietojen lukemista varten tai tapahtumatehtävä tietojen kirjoittamista ja toimintoja varten REST-rajapintaan.

2025.3-versio toi tuen tietojen lukemiseen ajastetuilla tehtävillä.

Generic REST API -liitintä käytetään tietojen lukemiseen kolmannen osapuolen ratkaisuista, jotka tarjoavat REST-rajapinnan, luomalla ajastukseen perustuva provisiointitehtävä.

Miten luodaan uusi tehtävä ajastettua provisiointia varten

Ajastukseen perustuvan provisiointitehtävän määritystä varten tarvitset pääsyn Platform configuration -konsoliin.

Huomio! Jos liitintä ei ole vielä luotu, sinun on ensin luotava “new connector”, minkä jälkeen voit luoda uusia tehtäviä.

1. Avaa Platform configuration -näkymä (hammasratas-kuvake).
2. Avaa Connectors-näkymä.
3. Valitse liitin, jolle ajastukseen perustuva tehtävä määritetään
4. Valitse “new task” oikean liittimen alta

5. Määritä tehtävän ajastus (ajetaanko ajastettu tehtävä säännöllisesti ja miten). Valitse ajastusväli, joka riippuu siitä, kuinka paljon dataa luetaan Matrix42 Core-, Pro- ja IGA-ratkaisuun.

Suositeltu ajastusväli riippuu siitä, kuinka paljon dataa luetaan asiakkaan hakemistosta Matrix42 Core-, Pro- ja IGA-ratkaisuun, ja onko kyseessä osittainen vai täysi lataus.

Esimerkki tietojen lukemisen ajastuksesta.

5. Täytä tehtävän tiedot

• Anna ajastetulle tehtävälle yksilöllinen nimi
• Task usage -kenttä ilmaisee, käytetäänkö tehtävää tietojen lukemiseen, kirjoittamiseen vai todennukseen. Huomaa, että jos tapahtumatyyppiä muutetaan jälkikäteen, se voi rikkoa työnkulkuja tai integraatioita.
• Mappings type riippuu siitä, minkä tyyppistä tietoa hakemistosta luetaan; Generic REST API -liittimelle tuetaan vain arvoa Generic
  • Generic (one template) – käytetään, kun hakemistosta luetaan yleistä tietoa

6. Täytä tehtävän parametrit

• Query – kutsuttava varsinainen API-url-päätepiste
• Sub Queries – valinnainen. Voidaan käyttää, jos Query-kenttään liittyvää tietoa on tarpeen hakea toisesta API-päätepisteestä.
  Sub queries -kentät tukevat vain pääkyselyn tulosjoukon yksinkertaisia ensimmäisen tason muuttujia. Alikyselyt eivät tue jsonpath-syntaksia.
  Esimerkki tuetusta alikyselystä (tämä olettaa, että json-vastauksen ensimmäisellä tasolla on userid-attribuutti): /groups/{userid}
  Esimerkki EI-tuetusta alikyselystä, joka yrittää käyttää jsonpath-syntaksia: /groups/{users[0].userid}
• Query headers – mukautetut otsikot, jotka lisätään lopulliseen kyselyyn tiedon haun aikana.
  Connector management (EPE) lisää nämä otsikot automaattisesti, joten niitä ei tarvitse lisätä erikseen:
  “Content-Type”, “…”
"Authorization", “…”
• Value Marker – voi olla tyhjä. Arvo riippuu Query-rajapinnan palauttaman JSON-datan rakenteesta. Jos esimerkiksi koko data on resultset-nimisen json-objektin sisällä, aseta tämän arvon merkiksi resultset.
• Error Marker – voi olla tyhjä. Arvo riippuu Query-rajapinnan palauttaman JSON-virheviestin rakenteesta. Jos esimerkiksi koko virheviesti on errors-nimisen json-objektin sisällä, aseta tämän arvon merkiksi errors.
• Safety Threshold for API calls – turvaraja, joka estää loputtomat silmukat. Aseta tämä arvo kaksinkertaiseksi verrattuna siihen, montako kutsua tämä tehtävä tarvitsee kaiken datan hakemiseen. Jos esimerkiksi kaiken datan hakemiseen tarvitaan 50 sivutettua kutsua, aseta tämän arvoksi 100.
• Unique attribute – aseta JSON-tulosjoukon yksilöivän attribuutin nimi (kirjainkoko merkitsee). Yleensä ID, id tai guid tms. Jokaisella rivillä on oltava tässä attribuutissa yksilöllinen arvo. Tämä attribuutti on lisättävä myös mappaustaulukkoon tehtävän määrityksen lopussa. Note! Ajastettu tehtävä ei voi hakea dataa, joka ei sisällä tätä yksilöivää attribuuttia jokaiselle objektille.
  

7. Täytä virhetilanteen tiedot

Valinnaiset asetukset virheiden käsittelyyn: jos ajastettu tehtävä epäonnistuu, se voi luoda ESM:ään datacardin, joka näyttää virheen. Jos virheasetukset on määritetty, pääkäyttäjän ei tarvitse tarkistaa ajastettujen tehtävien tilaa manuaalisesti.

• Failure template – valitse datacard-malli (Template), joka luodaan, jos provisioinnin aikana tapahtuu virheitä (yhteys tietolähteisiin, aikakatkaisut jne.)
• Failure folder – valitse kansio, johon virhe-datacard tallennetaan.
• Failure attribute – valitse attribuutti, johon virhetiedot tallennetaan Failure Template -mallissa. Valitse tekstityyppinen attribuutti.

8. Lisää Generic-mappaukset

Mappaus-osiossa määrität, mikä JSON-viestin attribuutti luetaan mihinkin Matrix42 Core-, Pro- ja IGA-datacardin attribuuttiin.

• Target template – valitse malli, jolla attribuuttimappaukset määritetään
• Target folder – valitse kansio kansioluettelosta. Luettelo suodattuu vastaamaan valitun mallin (Template) yhteensopivuutta.
• Data Source Type mapping – valinnainen. Jos tämä asetetaan, liittimen tyyppi kirjoitetaan kyseiseen attribuuttiin.
• Task Id mapping – tehtävän ID-numero kirjoitetaan tähän attribuuttiin. Tämän attribuutin on oltava ei-yksilöivä.
• Set value to datacard fo object deleted from source system – tämä toiminto otetaan käyttöön valitsemalla valintaruutu. Kun jokin objekti, joka on aiemmin luettu kolmannen osapuolen järjestelmästä ratkaisuun, poistetaan kolmannen osapuolen järjestelmästä (eli tämän tehtävän kysely ei enää palauta sitä). Ajastettu tehtävä huomaa, että objekti on poistettu, ja merkitsee kyseisen datacardin valitun attribuutin haluamallasi arvolla. Tätä voidaan käyttää esimerkiksi Status-attribuutin asettamiseen arvoon Deleted (kuten alla olevassa esimerkkikuvakaappauksessa).

• Attribuuttimappaukset
  1. External attribute – mikä kolmannen osapuolen järjestelmän API:n attribuutti luetaan JSON-rungosta
  2. Local attribute – mihin Matrix42 Core-, Pro- ja IGA-attribuuttiin mappaus kohdistuu
• Attribuuttimappauksiin on mahdollista lisätä ylimääräisiä attribuutteja valitsemalla New attribute
• JSONPath-lausekkeet, joita mappaustaulukon external attribute -kentässä tuetaan ja ei tueta:
  https://docs.efecte.com/configure-connectors/jsonpath-mappings-for-generic-rest-api-connector

9. Tallenna provisiointitehtävä Save-painikkeesta.

Jos joitakin pakollisia attribuutteja puuttuu, tallennuspainike näkyy harmaana ja se näyttää, mitä asetuksista puuttuu.

10. Olet nyt määrittänyt ajastukseen perustuvan liitintehtävän Generic REST API -lukua varten

• Voit nyt odottaa, että tehtävä käynnistyy ajastuksen mukaisesti, tai
• Run task manually – napsauttamalla “Run Task” -painiketta tehtävän muokkausikkunan yläreunassa, tehtävä käynnistetään heti. Käytetään yleensä testiajoissa tai kun ajastusasetuksia ei haluta muuttaa, mutta tehtävä halutaan ajaa nyt.

Esimerkki manuaalisen tehtäväajon käynnistysviestistä:

Jos tehtävä suoritetaan manuaalisesti (run task) tai se ajetaan ajastuksen mukaan, tehtävän tilan voi tarkistaa Scheduled tasks -listan manage-sarakkeesta napsauttamalla “View history” button.

Tapahtumatehtävää käytetään tietojen kirjoittamiseen (tai muiden tapahtumapohjaisten REST-rajapintakutsujen tekemiseen Workflow-työnkulusta) asiakkaan ratkaisuun, joka tarjoaa geneerisen REST-rajapinnan. Nämä Connector Management -ominaisuudet ovat käytettävissä kaikissa Matrix42 Core-, Pro- ja IGA-ratkaisuissa.

Esimerkkejä tapahtumapohjaisen tehtävän käyttötarkoituksista:

• Lisää tili
• Päivitä henkilö
• Aktivoi tili
• Luo tapaus
• Deaktivoi laite

Kaikki Connector Managementiin ja tapahtumapohjaiseen provisiointitehtävään liittyvät määritykset tehdään Matrix42 Core-, Pro- tai IGA-ratkaisun Connectors-näkymässä.

1. Avaa Matrix42 Core-, Pro- tai IGA-ratkaisun configuration view (hammasratas-kuvake).

2. Avaa connectors view

3. Valitse liitin, joka käyttää tapahtumatehtävää

4. Valitse “new task” oikean liittimen alta

5. Täytä tehtävän asetukset

• Task name – anna tehtävälle nimi, se näkyy connectors view -näkymässä.
  • On hyvä käytäntö nimetä tehtävä niin, että nimi kuvaa sen tarkoitusta, esimerkiksi [Template name]:[Activity] IGA Service request: Add account
• Task usage -kenttä ilmaisee, käytetäänkö tehtävää tietojen lukemiseen vai kirjoittamiseen. Sitä voi muuttaa jälkikäteen, mutta se ei ole suositeltavaa, jos tapahtumatehtävä on käytössä. Se rikkoo työnkulkuja.
• Mappings type riippuu siitä, minkä tyyppistä tietoa hakemistosta luetaan; identiteettimappausten valinnat näytetään tämän asetuksen perusteella.
  • Generic (one template) – käytetään, kun hakemistosta luetaan yleistä tietoa. Tämä voi olla minkä tahansa tyyppistä dataa.

Varoitus task usage- tai mappings type -asetuksen muuttamisesta, kun tapahtumatehtävä on käytössä:

6. Täytä tehtävän parametrit

• Query – API-päätepiste, jota tämä tehtävä kutsuu. Tämän voi jättää tyhjäksi ja antaa sen sijaan Workflow orchestration -solmussa. Voit antaa koko päätepisteen osoitteen, esimerkiksi: https://apiurl.com/endpointtocall, tai vain url:n loppuosan. Jos annat vain url:n loppuosan, esimerkiksi endpointtocall, lopullinen url muodostetaan yhdistämällä kaikki seuraavat: liittimen host url + tehtävän query + orkestrointisolmun url.
• Query headers – mukautetut otsikot, jotka lisätään lopulliseen REST-rajapintakyselyyn. Katso kohde-/lähdejärjestelmän API-dokumentaatiosta, mitä otsikoita se vaatii.
• Date Attribute formatter – käytetään päivämäärien muotoiluun, kun date-tyyppinen attribuutti provisioidaan kohdejärjestelmään. Voit valita muodon listalta tai lisätä oman mukautetun muodon. Oikeanpuoleinen kenttä näyttää esimerkin muotoillusta päivämäärästä.
• DateTime Attribute formatter – käytetään päivämäärä- ja kellonaikatietojen muotoiluun, kun datetime-tyyppinen attribuutti provisioidaan kohdejärjestelmään. Voit valita muodon listalta tai lisätä oman mukautetun muodon. Oikeanpuoleinen kenttä näyttää esimerkin muotoillusta datetime-arvosta.

7. Määritä generic-mappaukset

• Target template - Select a template to define attribute mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.
• Attribute mappings (Huomio! Useimmissa tapauksissa näitä ei tarvitse asettaa. Tapahtumatehtävässä käytettävä data määritetään Workflow Orchestration -solmussa).
  1. Efecte template attribute – mihin Efecte-hakemiston attribuuttiin mappaus kohdistuu.
  2. Directory attribute – mikä hakemiston attribuutti mapataan Efecteen
• Add new attribute – Ylimääräisiä attribuutteja voi lisätä valitsemalla New attribute -painikkeen.

8. Tallenna tehtävä

Tallenna provisiointitehtävä “save”-painikkeella

Jos pakollisia tietoja puuttuu, tehtävää ei voi tallentaa, ja tallennuspainike näyttää, mitkä tiedot puuttuvat.

9. Määritä Workflow käyttämään tätä tapahtumatehtävää Orchestration-solmun kautta

Seuraava vaihe on määrittää työnkulku käyttämään tätä tapahtumatehtävää.

Platformin työnkulkumoottorista on mahdollista suorittaa provisiointitoimintoja asiakkaan hakemistopalveluihin. Tämä tarkoittaa, että mitä tahansa saatavilla olevaa orkestrointisolmun toimintoa voidaan ajaa missä tahansa työnkulun vaiheessa.

Workflow-viittaukset näkyvät liittimen yleiskatsaussivulla (voit päivittää workflow-viittaukset “Show Workflow references” -painikkeella):

Generic REST call

Lisää Orchestration-solmu työnkulkuusi ja määritä seuraavat asiat.

Name – aseta kuvaava nimi

Description – aseta kuvaava kuvaus

Orchestrate – valitse Provisioning Engine

Data Source – valitse Generic REST API

Activity – valitse Generic REST call

Target – valitse tapahtumatehtäväsi (samaa tehtävää voi käyttää useissa orkestrointisolmuissa)

Action – valitse toiminto sen mukaan, mitä REST-rajapintaa kutsut (tarkista oikea toiminto API-dokumentaatiosta). Tuetut toiminnot ovat: POST, PUT, PATCH, DELETE ja GET

REST URL – API-päätepiste, jota kutsut. Tämä voi olla koko url tai url:n loppuosa. Jos käytät loppuosaa, kutsuttava lopullinen url muodostetaan yhdistämällä kaikki seuraavat: liittimen host url + tehtävän query + orkestrointisolmun url. Voit käyttää template-attribuuttimuuttujia samaan tapaan kuin email-solmussa, dollari-syntaksilla, esimerkiksi: $attribute_code$ ja $reference:attribute_code$.

Huomio! Jos url:ssasi on välilyöntejä tai $-merkkejä, muista url-koodata ne. Eli $ on %24 ja välilyönti on %20

Rest Body – API-kutsun json-runko. Voi olla tyhjä, jos kutsumasi API ei tarvitse runkoa. Katso rungon tiedot API-dokumentaatiosta. Voit käyttää template-attribuuttimuuttujia samaan tapaan kuin email-solmussa, dollari-syntaksilla, esimerkiksi: $attribute_code$ ja $reference:attribute_code$.

Esimerkiksi tässä rungossa on kaksi muuttujaa: $firstname$ ja $lastname$
{"name": {
"givenName": "$firstname$",
"familyName": “$lastname$”}}

Jos sinun on luotava monimutkainen json-runko API-kutsua varten, voit ensin muodostaa koko json-rakenteen johonkin datacardin attribuuttiin. Sen jälkeen rungossa tarvitsee olla vain kyseisen attribuutin koodi, esimerkiksi näin: $generated_json_body_attributecode$

import json

if onPremisesExtensionAttributes:
  _data = this.get("onPremisesExtensionAttributes")
  _obj = json.loads(_data)
  _value = _obj["extensionAttribute14"]
  this.set("extensionAttribute14code",_value)

Rest Response Attribute – API-kutsun tulosjoukon json kirjoitetaan tähän attribuuttiin. Kaikki API:t eivät palauta vastaus-jsonia. Katso tarkemmat tiedot API-dokumentaatiosta. Huomio! Tämä ei sisällä varsinaista http-koodia, esim. 200, 401, 500 jne., vaan ainoastaan tulosjoukon viestin, jos API sellaisen palautti.

import json

if onPremisesExtensionAttributes:
  _data = this.get("onPremisesExtensionAttributes")
  _obj = json.loads(_data)
  _value = _obj["extensionAttribute14"]
  this.set("extensionAttribute14code",_value)

Provisioning exception – jos REST-rajapintakutsussa on ongelma, virhe kirjoitetaan tähän attribuuttiin.

Poikkeusten käsittely:

• Provisioning exception on valinnainen ominaisuus tässä työnkulkusolmussa. Pääkäyttäjät voivat ottaa tämän ominaisuuden käyttöön, jolloin poikkeukset kirjoitetaan sinne, jos provisiointitoimien aikana ilmenee poikkeuksia.
• Solmun tulos on tilassa “Completed”, jos REST-rajapinnan http-vastauskoodi on 200 tai suurempi ja alle 400.
• Tiedot onnistuneista/epäonnistuneista REST-rajapintakutsuista löytyvät lokeista.

Microsoft Azure DevOps: https://docs.efecte.com/configure-connectors/ms-ado-connector

Google: https://docs.efecte.com/configure-connectors/google-connector

Raynet: https://docs.efecte.com/configure-connectors/raynet-connector

Matrix42 Enterprise and Matrix42 Software Asset Management (SAM): https://docs.efecte.com/configure-connectors/m42enterprise-sam-connector

Tässä luvussa kuvataan vianmääritysvaihtoehdot,

• Jos failure template on käytössä, tarkista virhetiedot oikealta datacardilta
• Tarkista ajastetun tehtävän historia connector managementista
• Tarkista Matrix42 Native Connectors -lokit, jotka löytyvät Connectors-välilehden Logs-osiosta
• Tarkista FAQ-dokumentit

Tapahtumapohjaisten tehtävien rajoitukset

• Liittyy attribuuttimappauksiin
  • Sähköposteja ei tueta
  • Liitteitä ei tueta

Ajastettujen tehtävien rajoitukset

• Vain GET-http-metodia tuetaan (POST, PATCH, DELETE jne. eivät ole tuettuja)
• Dynaamisia url-parametreja ei tueta
• Liittyy attribuuttimappauksiin
  • Date-tyyppiset attribuutit (nämä on mapattava string-tyyppiseen attribuuttiin)
  • DateTime-tyyppiset attribuutit (nämä on mapattava string-tyyppiseen attribuuttiin)
  • Sähköposteja ei tueta
  • Liitteitä ei tueta