Provisioinnin määrittämistä varten tarvitset pääsyn Platform configuration console -konsoliin.

1. Avaa Administration-alue (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. https://admin.googleapis.com/admin/directory/v1/ Tätä voidaan käyttää etuliitteenä lopulliselle kutsuttavalle URL-osoitteelle.
• REST Connector type - valitse Google
• Scopes - aseta laajuudet (scopes) sen mukaan, mitä Google-rajapintoja liittimestä kutsutaan. Käyttäjien, ryhmien ja käyttöoikeuksien laajuudet ovat https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.group.member
• Credentials JSON file content - kun olet määrittänyt Google-puolen, saat sieltä json-tiedoston. Kopioi ja liitä koko tiedoston sisältö tähän attribuuttiin.
• Delegated user - käyttäjä, jonka puolesta liitin muodostaa yhteyden Googleen. Tässä suositellaan käyttämään teknistä käyttäjää, esimerkiksi igagoogle@yourdomain.com
• Pagination Type - valitse Link Attribute Token
• Pagination Link token - nextPageToken
• URL Attribute name - pageToken

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

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

8. Tallenna liittimen tiedot

9. Lisää Googlen juuri-https-varmenne luotetuksi Connector managementissa (EPE). Tämän voi tehdä vain Matrix42: Add certificate. Googlen juurivarmenteet löytyvät osoitteesta https://pki.goog/repository/ 

10. Matrix42 Core-, Pro- ja IGA-ratkaisu pystyy nyt muodostamaan yhteyden Googleen

• Seuraava vaihe on määrittää ajastettu tehtävä datan lukemista varten tai tapahtumapohjainen tehtävä datan kirjoittamista ja toimintoja varten Googleen.

Tässä luvussa lisäämme esimerkkinä ajastetun tehtävän, joka lukee käyttäjät ja käyttäjien ryhmäjäsenyydet Googlesta.

Huomio! Jos haluat lukea myös Google-ryhmät tietokortteina ESM:ään, sinun täytyy luoda niitä varten toinen Generic Scheduled Task.

1. Lisää Scheduled task oikean liittimen alle napsauttamalla ”New Task”

2. Aseta tehtävän attribuutit

Scheduling - aseta ajastus tarvittaessa

Task name - aseta kuvaava nimi

Task usage - Scheduled

Mapping type - Generic Template

Query - kysely riippuu siitä, mitä Google-rajapinnan endpointia haluat kutsua datan hakemiseksi. Katso Googlen dokumentaatiosta oikea rajapinnan URL ja parametrit. Muista asettaa oikea domain-attribuutti oman Google-toimialueesi mukaan.
Tässä esimerkissä haemme käyttäjiä käyttämällä: users?domain=yourdomain.com

Sub Queries - voit lisätä alikyselyjä, jos haluat lukea lisää dataa varsinaisen kyselyn palauttamaan tulosjoukkoon liittyen. Tässä esimerkissä käytämme alikyselyä käyttäjien ryhmäjäsenyyksien hakemiseen: groups?userKey={id}

Query headers - Googlea varten meidän täytyy lisätä seuraavat otsikot:
Accept / application/json
Content-Type / application/json

Value Marker - tässä tapauksessa users (oikea arvo riippuu siitä, mitä rajapintaa kutsut)

Error Marker - aseta tämä arvoon error

Safety threshold for API calls - suositellaan asetettavaksi kaksi kertaa niin suureksi kuin kuinka monta sivua tämä rajapinta palauttaa. Jos jätät sen tyhjäksi, turvarajaa ei ole, jolloin liitin voi jäädä loputtomaan silmukkaan, jos määrityksessä on virhe.

Unique Attribute - yksilöivä attribuutti rajapinnan tulosjoukossa. Tässä tapauksessa id

3. Täytä virhetiedot (failure information)

Valinnaiset asetukset virheiden käsittelyyn: jos ajastettu tehtävä epäonnistuu, se voi luoda ESM:ään tietokortin, 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 tietokortin malli, joka luodaan, jos provisioinnin aikana tapahtuu virheitä (yhteys tietolähteisiin, aikakatkaisut jne.)
• Failure folder - valitse kansio, johon virhetietokortti tallennetaan.
• Failure attribute - valitse attribuutti Failure Template -mallista, johon virhetiedot tallennetaan. Valitse tekstityyppinen attribuutti.

4. Täytä Generic mappings -tiedot

Mappings-osiossa määritetään, mikä attribuutti JSON-viestistä luetaan mihinkin attribuuttiin Matrix42 Core-, Pro- ja IGA-tietokortilla.

• Target template - valitse malli, jolle attribuuttien kartoitukset määritetään (tässä esimerkissä IGA Account, koska haemme käyttäjiä/tilejä)
• Target folder - valitse kansio kansioluettelosta. Luettelo on rajattu vastaamaan valittua mallia. (tässä esimerkissä Accounts)
• Data Source Type mapping - valinnainen. Jos se on asetettu, se kirjoittaa liittimen tyypin kyseiseen attribuuttiin.
• Task Id mapping - tehtävän tunnusnumero kirjoitetaan tähän attribuuttiin. Oikea valittava attribuutti riippuu siitä, miten mallisi on määritetty.
• Set value to datacard for object deleted from source system - tämä toiminto otetaan käyttöön valitsemalla valintaruutu. Kun jokin kolmannen osapuolen järjestelmästä aiemmin luettu objekti poistetaan kyseisestä järjestelmästä, tämä ajastettu tehtävä huomaa poiston ja merkitsee tietokortin valitun attribuutin haluamallasi arvolla. Tätä voidaan käyttää esimerkiksi asettamaan Status-attribuutti arvoon Deleted. Attribuutin nimi ja arvo tulee määrittää sen mukaan, miten mallisi on määritetty.

• Attribute mappings
  1. External attribute - mikä Googlen rajapinnan attribuutti luetaan JSON-rungosta
  2. Local attribute - mihin attribuuttiin Matrix42 Pro- ja IGA-järjestelmässä kartoitus kohdistuu
• Lisää attribuutteja attribuuttikartoituksiin valitsemalla New attribute
• Sinun täytyy lisätä kartoitus myös Unique Attribute -kenttään, tässä esimerkissä se on id. Se täytyy kartoittaa mallin yksilöivään attribuuttiin, tässä esimerkissä Directory identifier.
• Ensimmäinen kartoitus alla olevassa esimerkkitaulukossa käyttää alikyselyä kartoittaakseen käyttäjien ryhmäjäsenyydet multiValueField-attribuuttiin. Muut kartoitukset ovat pääkyselyn käyttäjäattribuuttien kartoituksia. Jotta tämä toimii, tarvitset Subquery: groups?userKey={id}
  Alikyselyssä {id} on dynaaminen muuttuja, joka tässä tapauksessa viittaa pääkyselyn tulosjoukon id-attribuuttiin. Kartoitus tälle alikyselylle, jolla haetaan niiden ryhmien tunnukset, joihin käyttäjä kuuluu:
  groups?userKey={id}.groups[*].id, jossa varsinainen JSONPath on tämä osa lopussa: groups[*].id
• Katso tuetut kartoitussyntaksit: https://docs.efecte.com/configure-connectors/jsonpath-mappings-for-generic-rest-api-connector 

5. Tallenna provisiointitehtävä Save-painikkeesta.

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

6. Olet nyt määrittänyt ajastukseen perustuvan liitintehtävän

• Voit nyt joko odottaa, että tehtävä käynnistyy ajastuksen mukaisesti, tai
• ajaa tehtävän manuaalisesti (Run task) - napsauttamalla ”Run Task” -painiketta tehtävän muokkausikkunan yläreunassa, tehtävä ajastetaan käynnistymään välittömästi. Käytetään yleensä testiajoissa tai kun ajastusasetuksia ei haluta muuttaa, mutta tehtävä halutaan ajaa heti.

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

Jos tehtävä suoritetaan manuaalisesti (run task) tai ajastuksen mukaisesti, tehtävän tila voidaan tarkistaa Scheduled tasks -listan manage-sarakkeesta napsauttamalla ”View history” -painiketta.

Tässä on perusesimerkki Event task- ja Orchestration node -toiminnoista, joita käytetään uuden käyttäjän luomiseen Googleen. Tuotantokäytössä sinun täytyy suunnitella, mitkä kaikki attribuutit uudelle käyttäjälle tulee asettaa.

1. Lisää Event-based task oikean liittimen alle napsauttamalla ”New Task”

2. Aseta tehtävän attribuutit

Task name - kuvaava ja yksilöivä nimi
Task usage - Event
Mappings type - Generic Template
Query - kutsuttavan rajapinnan URL. Tässä esimerkissä jätämme sen tyhjäksi, koska asetamme URL:n Workflow orchestration node -solmussa. Lopullinen kutsuttava rajapinnan URL muodostetaan yhdistämällä liittimen URL, tämä query-URL ja orkestrointisolmun REST URL.

Query headers - Googlea varten meidän täytyy lisätä seuraavat otsikot:
Accept / application/json
Content-Type / application/json

Date Attribute formatter - aseta oikea muoto, jos provisioit date-tyyppisiä attribuutteja

DateTime Attribute formatter - aseta oikea muoto, jos provisioit datetime-tyyppisiä attribuutteja

Aseta Generic Mappings

Target template - malli, jonka työnkulusta (Workflow) tätä tehtävää kutsutaan
Target folder - kansio datallesi

Älä aseta attribuutteja kartoitustaulukkoon (external attribute - local attribute). Attribuuttien kartoitus tehdään työnkulun orkestrointisolmussa.

3. Tallenna tehtävä

4. Luo Orchestration node työnkulkuusi tämän tapahtumapohjaisen tehtävän kutsumiseksi

Orchestrate - Provisioning Engine
Data Source - Generic REST API
Activity - Generic REST call
Target - Create google user (oman tapahtumapohjaisen tehtäväsi nimi)
Action - tässä esimerkissä POST, koska luomme käyttäjän Googleen
REST URL - tässä esimerkissä users, koska luomme käyttäjiä Googleen
REST Body - voit luoda rajapintakutsun rungon suoraan tässä. Monimutkaisemmissa tapauksissa se voidaan luoda erikseen (script node -solmussa) johonkin attribuuttiin ja käyttää sitten kyseistä attribuuttia tässä. Tässä tapauksessa käyttäjän luontirunko luodaan suoraan tässä, käyttäen firstname- ja lastname-attribuuttikoodimuuttujia.
Tässä käytetty runko on hyvin yksinkertaistettu esimerkki. Tuotantokäytössä sinun täytyy suunnitella, mitkä kaikki attribuutit haluat asettaa uusille käyttäjille.
{
"name": {
"givenName": "$firstname$",
"familyName": "$lastname$"
},
"password": "$randompassword$",
"primaryEmail": "$firstname$.$lastname$@mydomaincom"
}

REST Response attribute - rajapintakutsun vastaus tallennetaan tähän attribuuttiin. Tässä esimerkissä se sisältää luodun käyttäjän tiedot JSON-muodossa.

import json

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

Provisioning exception - jos rajapintakutsussa on ongelma, poikkeus tallennetaan tähän attribuuttiin

Viimeistele työnkulun muut solmut ja kulku

Tallenna työnkulku ja julkaise se

5. Testaa työnkulku ja tapahtumapohjainen tehtävä

Rajoitukset versiossa 2025.3

Useamman kuin yhden tason alikyselyjä ajastetuille tehtäville ei tueta suorituskykysyistä.