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. Tätä voidaan käyttää etuliitteenä lopulliselle kutsuttavalle URL-osoitteelle.
• REST Connector type - valitse Generic
• Authentication method - valitse Basic Authentication
• Basic User Name - käyttäjätunnus M42 Enterpriseen / SAM:iin
• Basic Password - edellisen kentän käyttäjän salasana

6. Aseta oikea sivutus (pagination)

Voit luoda 2 erillistä liitintä, joilla on identtiset asetukset paitsi tämä sivutusasetus. Luo yksi liitin tehtäville, joissa rajapinta tukee sivutusta, ja toinen liitin tehtäville, joissa rajapinta ei tue sivutusta.

A) Aseta sivutus Matrix42 Enterprise/SAM-liittimelle (tehtäville, jotka kutsuvat rajapintoja, jotka eivät tue sivutusta)
Käytä arvoa disabled, koska ajastetun tehtävän esimerkissä käytetty dataquery-rajapinta ei tue sivutusta:

B) Aseta sivutus Matrix42 Enterprise/SAM-liittimelle tehtäville, jotka kutsuvat rajapintoja, jotka tukevat sivutusta.

• Pagination type - Page Increment
• Pagination Page Attribute - pagenumber
• Pagination Page Start - 1
• Pagination Page Size Attribute - pagesize
• Pagination Page Size - aseta tämä datasi mukaan. Tarkista enimmäisarvo Matrix42 Enterprise/SAM-dokumentaatiosta tai konsulteilta. Tämän tulee olla pienempi kuin pienin datamäärä, jonka kutsuttava rajapinta palauttaa. Jos asetat tämän liian suureksi, Matrix42 Enterprise tai SAM ei palauta lainkaan dataa.

7. 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ää ulkoisen Matrix42 Enterprise- tai SAM-järjestelmän juuri-https-varmenne luotetuksi Connector managementissa (EPE). Tämän voi tehdä vain Matrix42: Add certificate.

10. Matrix42 Core-, Pro- ja IGA-ratkaisu pystyy nyt muodostamaan yhteyden Matrix42 Enterpriseen ja Matrix42 SAM:iin

• Seuraava vaihe on määrittää ajastettu tehtävä datan lukemista varten tai tapahtumapohjainen tehtävä datan kirjoittamista ja toimintoja varten Matrix42 Enterpriseen ja SAM:iin.

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ä Matrix42 Enterprisen rajapinnan endpointia haluat kutsua datan hakemiseksi. Katso Matrix42 Enterprisen dokumentaatiosta oikea rajapinnan URL ja parametrit.
Tässä esimerkissä: /data/fragments/SPSActivityClassBase?columns=ID,Subject,Description,TicketNumber

Sub Queries - voit lisätä alikyselyjä, jos haluat lukea lisää dataa varsinaisen kyselyn palauttamaan tulosjoukkoon liittyen. Tässä esimerkissä emme käytä tätä toimintoa.

Query headers - voidaan jättää tyhjäksi

Value Marker - jätä tyhjäksi

Error Marker - jätä tyhjäksi

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. Yleensä ID Matrix42 Enterprisen rajapinnoissa, mutta varmista asia dokumentaatiosta.

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ä Ticket)
• Target folder - valitse kansio kansioluettelosta. Luettelo on rajattu vastaamaan valittua mallia. (tässä esimerkissä Tickets)
• 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 09 - Closed (kuten alla olevassa esimerkkikuvakaappauksessa). Attribuutin nimi ja arvo tulee määrittää sen mukaan, miten mallisi on määritetty.

• Attribute mappings
  1. External attribute - mikä Matrix42 Enterprise -järjestelmän rajapinnan attribuutti luetaan JSON-rungosta
  2. Local attribute - mihin attribuuttiin Matrix42 Core-, Pro- ja IGA-järjestelmässä kartoitus kohdistuu
• Attribuuttikartoituksiin on mahdollista lisätä lisää attribuutteja 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ä text1.
• 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ä luvussa kuvataan esimerkki siitä, miten dataa haetaan Matrix42 SAM -ratkaisusta Pro/IGA-ratkaisuun.
Ratkaisun määrityksistä, katso: https://docs.efecte.com/baseline-configuration-instructions/m42-sam-m42-pro-integration-implementation 

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ä Matrix42 SAM:n rajapinnan endpointia haluat kutsua datan hakemiseksi. Katso Matrix42 SAM:n dokumentaatiosta oikea rajapinnan URL ja parametrit.
Tässä esimerkissä: dataquery/aad704de-a242-c667-123b-08d45a5faa97

Huomio! Jos käytät Matrix42 Enterprise/SAM dataquery-rajapintaa (kuten tässä esimerkissä), se palauttaa oletuksena vain 10 000 objektia. Dataquery-rajapinta ei tue sivutusta. Jos sinun täytyy hakea yli 10 000 objektia, ota yhteyttä Matrix42:een ja pyydä ympäristösi rajan nostamista. Lisätietoja alla:

“Data Query Response Records Count
Asetus PDRDwpConfigurationClass.DataQueryMaxResponseRecords määrittää enimmäismäärän tietueita, jotka "Data Query" -verkkopalvelu palauttaa.
Oletusarvo: 10 000 tietuetta.”

Sub Queries - voit lisätä alikyselyjä, jos haluat lukea lisää dataa varsinaisen kyselyn palauttamaan tulosjoukkoon liittyen. Tässä esimerkissä emme käytä tätä toimintoa.

Query headers - voidaan jättää tyhjäksi

Value Marker - jätä tyhjäksi

Error Marker - jätä tyhjäksi

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. Yleensä Id Matrix42 SAM:n rajapinnoissa, mutta varmista asia dokumentaatiosta.

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ä Device)
• Target folder - valitse kansio kansioluettelosta. Luettelo on rajattu vastaamaan valittua mallia. (tässä esimerkissä Assets/Servers)
• 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. Tässä esimerkissä tätä toimintoa ei käytetä.

• Attribute mappings
  1. External attribute - mikä Matrix42 SAM -järjestelmän rajapinnan attribuutti luetaan JSON-rungosta
  2. Local attribute - mihin attribuuttiin Matrix42 Core-, Pro- ja IGA-järjestelmässä kartoitus kohdistuu
• Attribuuttikartoituksiin on mahdollista lisätä lisää attribuutteja 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ä Intune 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 activitytype 6 -tikettien luomiseen Matrix42 Enterpriseen. Tuotantokäytössä sinun täytyy suunnitella, minkä tyyppisiä tikettejä haluat luoda ja mitkä attribuutit niihin täytyy 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ä luomme tiketin, joten käytämme querynä: /ticket/ (lopullinen kutsuttava rajapinnan URL muodostetaan yhdistämällä liittimen URL, tämä query-URL ja orkestrointisolmun REST URL). Voit myös jättää queryn tyhjäksi ja asettaa rajapinnan URL:n Orchestration node REST URL -attribuuttiin.

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 ticket as service request (oman tapahtumapohjaisen tehtäväsi nimi)
Action - tässä esimerkissä POST, koska luomme tikettejä rajapinnalla, joka luo tiketin.
REST URL - tässä esimerkissä create?activitytype=6, koska luomme tikettejä activitytype 6:lla
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 tiketin luontirunko luodaan suoraan tässä, käyttäen subject- ja details-attribuuttikoodimuuttujia.
Tässä esimerkissä käytetyssä rungossa User on kovakoodattu (voit harkita jotain muuta logiikkaa tähän), subject- ja description-arvot luetaan tietokortin subject- ja details-attribuuteista.
{
"Subject": "$subject$",
"Description": "$details$",
"Priority": 0,
"Impact": 0,
"Urgency": 0,
"User":"0e8aac28-b2df-ef11-58b1-005056905558"
}

REST Response attribute - rajapintakutsun vastaus tallennetaan tähän attribuuttiin
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

• Useamman kuin yhden tason alikyselyjä ajastetuille tehtäville ei tueta suorituskykysyistä.
• Liitteiden lähettämistä tai hakemista ei tueta.
• Sähköpostien lähettämistä tai hakemista ei tueta.
• Date-tyyppisten attribuuttien hakeminen suoraan tietokortin Date-tyyppiseen attribuuttiin (ne täytyy kartoittaa string-tyyppiseen attribuuttiin ja käyttää esimerkiksi käsittelijää arvon kopioimiseksi Date-attribuuttiin)
• DateTime-tyyppisten attribuuttien hakeminen suoraan tietokortin DateTime-tyyppiseen attribuuttiin (ne täytyy kartoittaa string-tyyppiseen attribuuttiin ja käyttää esimerkiksi käsittelijää arvon kopioimiseksi DateTime-attribuuttiin)

M42 SAM - M42 Pro Integration implementation

M42 SAM & SaaS Management in M42 Professional