Integraatio organisaation omasta aineistojen metatietovarannosta aloitetaan aina suunnittelu- ja käyttöönottoprojektilla yhdessä CSC:n Fairdata-tiimin kanssa (fairdata (at) csc.fi).
Projektin aikana integraatio toteutetaan Metaxin demoympäristöön, ja sovittuna ajanhetkenä otetaan demoympäristössä testattu toteutus käyttöön tuotantoympäristössä.
- Organisaation aineistojen kuvailutiedot tuodaan Metaxiin omaan aineistokatalogiinsa, jonka CSC luo organisaatiota varten.
- CSC luo organisaatiolle service-tunnuksen (käyttäjätunnus ja salasana) aineistojen kuvailutietojen tuomiseksi yo. aineistokatalogiin.
- Organisaatio luo tarvittavat API-kutsut (sanomat), joilla aineistojen kuvailutiedot tuodaan.
Projektin eteneminen, esimerkki
Aloituskokouksessa sovitaan yhdessä organisaation kanssa tarkemmat projektivaiheet ja aikataulu.
Alla on esitetty esimerkki, millaisin vaihein projekti yleensä etenee.
Esimerkkiprojekti tehtävittäin
Tehtävä | Kuvaus | Ympäristö | Vastuu |
---|---|---|---|
Organisaation oman aineistokatalogin luominen, demo | CSC luo organisaatiolle oman aineistokatalogin, jonne aineistojen kuvailutiedot tuodaan. Sovitaan yhdessä katalogin nimi ja muut perustiedot. | Demo | CSC |
Organisaation Service-tunnuksen luominen, demo | CSC luo organisaatiolle käyttäjätunnuksen ja salasanan, joilla on oikeus tuoda ja päivittää organisaation aineistokatalogiin aineistojen kuvailutietoja | Demo | CSC |
Sanomamallit, API-rajapintojen dokumentaatio, reunaehdot integraatiolle | CSC toimittaa sanomamallit ja API-rajapintojen dokumentaation, sekä sopii yhdessä organisaation kanssa integraation reunaehdoista (PID-käytännöt, ym.) | - | CSC |
Sanomamalleihin ja API-rajapintoihin tutustuminen ja sanomien suunnittelu | Organisaatio tutustuu Metaxin API-rajapintoihin ja sanomamalleihin, ja kerää avoimet kysymykset yhdessä läpikäytäväksi | - | Organisaatio |
Tarkempi sanomasisältöjen ja API-rajapintojen läpikäynti yhdessä ja mäppäystarpeiden tunnistaminen | Käydään yhdessä läpi organisaation tunnistamat API-rajapintojen käyttöön ja sanomien muodostamiseen liittyvät avoimet kysymykset. Tunnistetaan tässä vaiheessa myös mäppäystarpeet (käytettyjen koodistojen ja tunnisteiden muuntaminen organisaation käyttämistä arvojoukoista Metaxin tunnistamiin arvojoukkoihin). | - | Organisaatio (CSC vahvasti tukena) |
Mäppäykset | Tehdään mäppäystaulukot kuhunkin muunnosta vaativaan koodiarvojoukkoon liittyen. (Organisaation käyttämä arvo <-> Metaxin tunnistama arvo) Organisaatio toimittaa käyttämänsä arvot CSC:lle, ja CSC muodostaa ehdotuksen mäppäyksestä. Organisaatio hyväksyy lopullisen mäppäyksen. | - | CSC / Organisaatio |
Sanomien muodostus | Organisaatio toteuttaa sanomat mäppäysmuunnoksineen | - | Organisaatio |
Testaus | Organisaatio testaa sanomamuodostuksen ja API-rajapintojen käytön Metaxin demo-ympäristöön. CSC auttaa tarvittaessa tuotujen aineistojen kuvailutietojen katselmoinnissa. Huom! Aineistojen kuvailutietojen tuonnin lisäksi testataan myös tietojen päivitys ja poistaminen. | Demo | Organisaatio |
Testaushavaintoihin reagoiminen | Organisaatio kommunikoi CSC:lle, jos testauksessa havaitaan sellaisia haasteita tai muutostarpeita, joissa CSC:n tukea tarvitaan. Esim. sanomasisällöissä tai rajapintojen kutsuissa, | Demo | Organisaatio (CSC vahvasti tukena) |
Tuotantoonmenosta sopiminen | Testauksen loppuvaiheessa sovitaan yhdessä tuotantoonmenon ajankohta. | Tuotanto | Organisaatio |
Organisaation oman aineistokatalogin luominen, tuotanto | CSC luo organisaatiolle oman aineistokatalogin, jonne aineistojen kuvailutiedot tuodaan. | Tuotanto | CSC |
Organisaation Service-tunnuksen luominen, tuotanto | CSC luo organisaatiolle käyttäjätunnuksen ja salasanan, joilla on oikeus tuoda ja päivittää organisaation aineistokatalogiin aineistoja | Tuotanto | CSC |
Aineistojen kuvailutietojen tuonti tuotantoon, vaihe 1 | Organisaatio tuo ensimmäiset aineistojen kuvailutiedot tuotantoympäristöön (1 tai korkeintaan muutama). | Tuotanto | Organisaatio |
Aineistojen kuvailutietojen katselmointi tuotannossa | Varmistetaan, että 1-vaiheessa tuodut aineistojen kuvailutiedot ovat siirtyneet tuotantoon oikein ja hyvälaatuisina. Huom! Tässä vaiheessa varmistetaan myös, miltä aineistojen kuvailutiedot näyttävät Tiedejatutkimus.fi-portaalissa. | Tuotanto | Organisaatio (CSC vahvasti tukena) |
Aineistojen kuvailutietojen tuonti tuotantoon, vaihe 2 | Organisaatio käynnistää integraation täysimittaisesti (aineistojen kuvailutietojen tuonti, päivitys, poistaminen) | Tuotanto | Organisaatio |
Ohjeita sanoman muodostamiseen:
- Käyttäjätunnus ja salasana välitetään sanomassa Base64 encoodattuna autentikointi-stringinä
- Key = ‘Authorization’
- Value = ‘Basic ‘+ base64 enkoodattu login:password
- Monet Metaxin kentät toimivat ns. "referenssidata" -tyyppisesti, eli arvona on tunniste (identifier) taustalla toimiviin erilaisiin koodistoihin
- Tällaisia kenttiä ovat mm. lisenssi, pääsyoikeus, asiasanat, tieteenala, aineiston kieli, toimijoiden organisaatiotiedot, infrastruktuuri ja rahoittajaorganisaatio
- Tällaisia tietoja tuotaessa on tärkeää, että tunnisteina käytetään Metaxin tunnistamia arvoja
- Tarvittaessa CSC auttaa organisaatiota käytössä olevien tunnisteiden muuntamisessa Metaxin tunnisteisiin (ns. "arvojoukkojen mäppäys")
- Sivulla https://metax.demo.fairdata.fi/swagger/v2/#/dataset_api on lista API-operaatioista, joita voidaan käyttää. Samalta sivulta pääsee myös koekäyttämään operaatioita:
- Avaa haluamasi operaatio klikkaamalla
- Klikkaa "Try it out" -painiketta
- Täytä haluamasi parametrit, ja aseta "dryrun" -parametrin arvoksi true (tällöin operaatioita ei oikeasti suoriteta Metaxiin saakka)
- Klikkaa "Execute"
Joihinkin operaatioihin vaaditaan käyttäjätunnus, jota ei sellaisenaan voi sivulle antaa. Ilman käyttäjätunnustakin pääsee kuitenkin näkemään oikean syntaxin kutsulle.
- Muita hyödyllisiä operaatioita:
- Lista kaikista aineistoista tietyssä katalogissa: https://metax.demo.fairdata.fi/rest/v2/datasets?data_catalog=<tähän katalogisi tunniste>&limit=1000
- Esimerkki aineistosta (pakolliset kentät täytettynä): https://metax.demo.fairdata.fi/docs/v1/datasets.html#retrieve-minimal-valid-dataset-template
- Esimerkkisisältö kutsusta, jolla aineiston kuvailutiedot tuodaan Metaxiin: Example_post.py
- Esimerkit tietosisällöittäin löydät täältä: Tietosisältö
Muita linkkejä
Referenssidatat: https://koodistot.suomi.fi/registry;registryCode=fairdata
Yleinen Metaxin dokumentaatio: https://metax.demo.fairdata.fi/docs/Organisaatiotason ohjeistukset tuodaan tälle sivulle.