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://<YOUR_RAYNET_URL>.raynetone.com/v1/resultDatabase (esimerkiksi: https://matrix42-demo-datahub.raynetone.com/v1/resultDatabase) Tätä voidaan käyttää etuliitteenä lopulliselle kutsuttavalle URL-osoitteelle.
• REST Connector type - valitse Generic
• Authentication method - Auth Header
• Authentication Header Name - ApiKey
• Authentication Header Value - oman apikey-arvosi
• Pagination Type - Page Increment
• Pagination Page Attribute - page
• Pagination Page Start - 1
• Pagination Page Size Attribute - page_size
• Pagination Page Size - 500 (jos haluat käyttää suurempaa sivukokoa, varmista Raynetin dokumentaatiosta, että kyseinen sivukoko on tuettu)

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ää Raynetin juuri-https-varmenne luotetuksi Connector managementissa (EPE). Tämän voi tehdä vain Matrix42 seuraavan ohjeen mukaisesti Add certificate. Raynet käyttää yleensä ”ISRG Root X1” -juurivarmennetta, jonka voi ladata käyttämällä "base 64 encoded single certificate pem"-muotoa täältä: https://letsencrypt.org/certificates/

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

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

Tässä luvussa lisäämme ajastetun tehtävän, joka lukee dataa Raynetista.

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ä dataa haluat hakea.
Tässä esimerkissä haemme käyttäjiä käyttämällä: resultTable/paged?tableName=DataTransformation-result_devices, joka hakee käytännössä kaiken datan Raynetin DataTransformation-result_devices-taulusta.

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

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

Value Marker - records

Error Marker - jätä tämä 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. Tässä tapauksessa import_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ä Device, koska haemme laitteita)
• Target folder - valitse kansio kansioluettelosta. Luettelo on rajattu vastaamaan valittua mallia. (tässä esimerkissä Asset/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.
• Katso tuetut kartoitussyntaksit: https://docs.efecte.com/configure-connectors/jsonpath-mappings-for-generic-rest-api-connector 

• Attribute mappings
  1. External attribute - mikä Raynetin 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 import_id. Se täytyy kartoittaa mallin yksilöivään attribuuttiin, tässä esimerkissä Name.
• ensimmäinen kartoitus käyttää alikyselyä kartoittaakseen käyttäjien ryhmäjäsenyydet multiValueField-attribuuttiin. Muut kartoitukset ovat pääkyselyn käyttäjäattribuuttien kartoituksia.

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.

Raynetin rajapinnassa on suodatusominaisuuksia, joita voidaan käyttää Native Connectors -liittimistä.
Raynetin rajapintadokumentaatio suodatustoiminnosta Raynet 2025.3 -julkaisutiedot 

Käyttääksesi suodatinta tehtävän query-attribuutissa, sinun täytyy URL-koodata suodatinarvo manuaalisesti tai jonkin verkkosivuston avulla (esimerkiksi https://www.urlencoder.org) koodausta varten.

Suodatinesimerkki ilman URL-koodausta (ei toimi): resultTable/paged?tableName=DataTransformation-result_devices&filter=["device_manufacturer","=","HP"]
Sama esimerkki URL-koodattuna (toimii): resultTable/paged?tableName=DataTransformation-result_devices&filter=%5B%22device_manufacturer%22%2C%22%3D%22%2C%22HP%22%5D

Jos Raynet-ympäristössäsi on molemmat näistä tauluista: DataTransformation-result_devices ja Catalog_v2_SoftwareOnDeviceMatching voit hakea laitteet Query-kentällä ja asennetut ohjelmistot Sub Query -kentällä.

Query: resultTable/paged?tableName=DataTransformation-result_devices 

Subquery: resultTable/paged?tableName=Catalog_v2_SoftwareOnDeviceMatching&filter=["ComputerId","=","{import_id}"]

Esimerkki laiteattribuuttien kartoituksesta käyttäen query-kenttää:

Laitteiden asennettujen ohjelmistojen kartoitus käyttäen subquery-kenttää:

resultTable/paged?tableName=Catalog_v2_SoftwareOnDeviceMatching&filter=["ComputerId","=","{import_id}"].SoftwareId

Rajoitukset versiossa 2025.3

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

• Jos failure template on käytössä, tarkista virhetiedot oikealta tietokortilta
• 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

Lokien ongelmat
Extract-vaiheessa on tämä virhe lokeissa:
org.apache.http.ConnectionClosedException: Premature end of chunk coded message body: closing chunk expected at org.apache.http.impl.io.ChunkedInputStream.getChunkSize(ChunkedInputStream.java:263) at

Todennäköinen syy:
Väärä APIKEY asetettu liittimeen

Näin korjaat:
Aseta oikea APIKEY-arvo liittimen asetuksiin