Johdanto
Provetin eläinlääkinnän toiminnanohjausjärjestelmä voidaan integroida kolmannen osapuolen sovelluksiin käyttämällä työkaluja, joita ovat REST API ja webhooks.
Webhooks ovat Provetissa käytettävissä, jotta voit lähettää ilmoituksia kolmannen osapuolen järjestelmille Provetin sisällä tehtävistä lisäyksistä tai muutoksista tiedoissa. Webhookit eivät siirrä varsinaisia muuttuneita tietoja, vaan ne välittävät tiedon siitä, mitä on muuttunut, ilmoittamalla muutoksesta yksinkertaisesti kolmannelle osapuolelle. Varsinaiset tiedot voidaan sen jälkeen noutaa kolmannen osapuolen järjestelmästä hyödyntämällä Provetin REST APIa.
REST API on viestintätapa, jolla voidaan käyttää, muokata tai lisätä Provet-ohjelmassa olevia tietoja ohjelmallisesti mistä tahansa kolmannen osapuolen sovelluksesta. Provetin REST API tarjoaa suurimman osan Provetin keskeisistä tiedoista luettavaksi tai muiden järjestelmien muokattavaksi.
Provetin webhookien ja REST API:n yhdistelmä luo ainutlaatuiset mahdollisuudet integroitujen ratkaisujen rakentamiseen. Mikä tahansa muiden järjestelmien toimittaja, joka tuntee nämä teknologiat, voi helposti integroida Provetin eläinlääkinnän toiminnanohjausjärjestelmässä oleviin tietoihin hyödyntämällä näitä teknologioita.
Ennen kuin voit aloittaa Provet API:en käytön, meidän täytyy ottaa sinulle käyttöön testausympäristön käyttöoikeus. Ota yhteyttä Partner Development Manageriin, jotta pääset alkuun.
Luomme sinulle testausympäristön, jota voit käyttää alkuvaiheen kehityksen aikana. Luomme myös sinulle integraation mallipohjan halutulla OAuth2 myönnystyypillä (grant type) siten, että saat pääsyn testausympäristöösi. Näin voit kehittää ja testata koodiasi API:n avulla.
Katso developer-sivumme API-dokumentaatiota, API-schemaa ja muita hyödyllisiä tietoja, jotka auttavat kehitystyössäsi.
Webhooks
Webhookit voidaan määrittää ja ottaa käyttöön kohdassa Settings > Integrations > Webhooks tai API-päätepisteen avulla. Jos integraatiosi käyttää webhookeja, suosittelemme webhookien luonnin automatisointia API:n avulla. Katso uusimmat tiedot List of Webhook Triggers -listasta ja tarkempi Webhooks guide -oppaasta developer-sivustoltamme.
REST API
Provet tarjoaa REST API:n, jolla mahdollistetaan pääsy Provetissa olevaan dataan. API käyttää OAuth 2.0 -tunnistusta. Tiedot palautetaan JSON-muodossa.
REST API:iin pääsyä varten tarvitset integraation mallipohjan.
Provet API tukee kahta myönnystyyppiä: Authorization Code ja Client Credentials.
Authorization Codea käytetään käyttäjäliittymien tunnistamiseen ja tilanteissa, joissa käyttäjät käyttävät API:a omana itsenään. PKCE tuetaan ja sitä suositellaan. Julkiset asiakkaat (Public clients) MUST käyttää PKCE:ä.
Client Credentialsia käytetään palvelinpuolen yhteyksiin, joissa palvelut kommunikoivat suoraan toisen palvelun kanssa ilman käyttäjän toimenpiteitä.
REST API:iin voi päästä käsiksi käyttämällä seuraavasti koottua URL-osoitetta: https://<provet_environment>/<provet_id>/api/0.1/
<provet_environment> URL eroaa hieman jokaisessa ympäristössä. Se voi olla esimerkiksi
provetcloud.com EU-ympäristöä varten
us.provetcloud.com US-ympäristöä varten
URL-osoitteessa <provet_id> on yksilöllinen ID Provet-instanssille, joka kuuluu yrityksellesi
Koko URL näytetään aina API-asetuksissa Provetissa kohdassa Settings > Integrations > Open API access.
Provetin REST API on selattavissa, mikä pitäisi tarjota kehittäjille hyvän mahdollisuuden arvioida tietojen siirtämisen vaihtoehtoja.
Integraatiosovelluksen lisääminen Provetiin
Kun mallipohja on luotu, integraatio näkyy Provetissa integraatioiden luettelossa: Settings > Integrations > Open API access > Add Application. Luettelo listaa käytettävissä olevat integraatiot ja sisältää lyhyen kuvauksen siitä, mitä kukin integraatio tekee. Jos integraatiolla on enemmän asennusohjeita, ne näkyvät myös luettelossa.
Integraatioiden näkyvyys voi olla rajoitettu: ne voidaan rajoittaa vain tiettyihin Provet-tenantteihin tai tietyille maille. Integraation tarjoava kolmannen osapuolen taho voi valita, miten laajasti integraation pitää näkyä tenantteina. Kun rajoituksia on, sovellus näkyy integraatioiden luettelossa vain niissä tokeneissa / niissä maissa, joissa sen käyttö on sallittu.
Vaihtoehdot uudessa asiakasrekisteröinnissä
Joka kerta, kun uusi asiakas rekisteröityy käyttämään integraatiota eli valitsee sen Provetissa integraatioiden luettelosta (Add Application), integraation tarjoajalle lähetetään yksilölliset asiakassalaisuudet (client credentials). Uutta asiakasta koskevan rekisteröinnin ilmoittamiseen on kaksi vaihtoehtoa, jotka voidaan valita integraation mallipohjaa luotaessa:
email
hookup URL
Kun integraatiota käytetään vain yhdellä Provet-instanssilla, email on hyvä valinta: silloin sähköpostin vastaanottava henkilö voi määrittää tunnistuksen tiedot integraatioon ja aloittaa sen käytön. Toisaalta, kun integraatiota käytetään laajasti, hookup URL ja uuden asiakkaan lisäämisen automatisointi ovat suositeltavia.
Hookup URL kuuntelee kaikkia automaattisia ilmoituksia uusista asiakkaista. Kun uusi asiakas lisää integraation Provetiin, orkestrointityökalu lähettää automaattisesti JSON-viestin kyseiseen annettuun URL-osoitteeseen. Tarvittavaa ei ole minkäänlaista ihmisen tekemää vuorovaikutusta, kun integraatio automaattisesti jäsentää uuden asiakkaan JSON-viestistä ja lisää heidän tunnistetietonsa asiakkaiden tauluun.
JSON schema uusille integraation rekisteröinneille lähetettävälle datalle:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "provet_id", "client_id", "client_secret", "algorithm", "authorization_grant_type", "client_type", "redirect_uris", "token_url", "authorize_url", "openid_autodiscovery_url" ], "properties": { "provet_id": { "type": "number", "description": "Provet ID of the tenant who added this integration." }, "client_id": { "type": "string" }, "client_secret": { "type": ["null", "string"] }, "algorithm": { "type": ["null", "string"], "description": "Signing algorithm used.", "examples": [null, "HS256", "RS256"] }, "authorization_grant_type": { "type": "string", "description": "Authorization flow used.", "examples": ["authorization_code", "client_credentials"] }, "client_type": { "type": "string", "description": "Client type.", "examples": ["confidential", "public"] }, "redirect_uris": { "type": "string", "description": "Space-separated list of callback URIs.", "examples": ["https://example.com/callback"] }, "token_url": { "type": "string", "description": "OAuth2.0 token endpoint URL." }, "authorize_url": { "type": "string", "description": "OAuth2.0 authorize endpoint URL." }, "openid_autodiscovery_url": { "type": ["null", "string"], "description": "OpenID autodiscovery URL. Null if integration does not use OpenID." }, "departments": { "type": "array", "items": { "type": "integer" }, "description": "Array of department IDs that have enabled this integration.", "examples": [[1, 2, 3]] }, "added_department": { "type": "integer", "description": "ID of the department that enabled this integration.", "examples": [3] }, "removed_department": { "type": "integer", "description": "ID of the department that disabled this integration.", "examples": [3] } }}
Oikeudet
Kun uusi integraation sovellus lisätään Provetiin, integraatiota varten luodaan automaattisesti virtuaalikäyttäjä ja oikeustasoryhmä. Virtuaalikäyttäjän nimi on Integration <Integration name>, ja se löytyy kohdasta Settings > Users käyttämällä Virtual-suodatinta. Oikeustasoryhmällä on sama nimi kuin integraatiolla.
Provet tukee oikeuksien hallinnan automaatiota, mikä vähentää käsityötä ja varmistaa johdonmukaisuuden. Tämä ominaisuus on nimeltään 'permission template', ja se lisätään integraation mallipohjaan. Ota yhteyttä Provet-tukeen, jotta saat permission template -mallipohjan integraation mallipohjaasi.
Kun permission template -mallipohjia muokataan, niihin liitetty oikeustasoryhmä Provetissa päivitetään automaattisesti vastaamaan uusinta mallipohjaa. Lisätyt oikeudet sisällytetään, ja poistettuja oikeuksia ei huomioida, jotta tiedot pysyvät synkronissa.
Jos permission template -mallipohjaa ei käytetä, oikeudet ovat oletuksena samat kuin oikeustasoryhmällä Users.
Jos integraatio vaatii erilaiset oikeudet (jotkin päätepisteet ovat estettyjä tai haluat rajoittaa oikeuksia), oikeudet täytyy muokata. Tarkista Provet API schemasta, mitä oikeuksia kukin päätepiste tarvitsee. Katso myös View and Manage User Permissions.
Toimipistekohtainen integraatio
Provet-ympäristöissä, joissa on useita klinikan toimipisteitä, integraatio voidaan ottaa käyttöön tai poistaa käytöstä erikseen jokaiselle toimipisteelle. Tämä asetus on pelkästään informatiivinen, eikä se luo mitään lisäasiakastietoa. Luettelo toimipisteistä, joissa integraatio on otettu käyttöön, sisältyy webhookin data payloadiin.
Joka kerta, kun integraatio otetaan käyttöön tai poistetaan käytöstä toimipisteelle, lähetetään uusi webhook, joka sisältää seuraavat tiedot:
Kaikki tällä hetkellä käytössä olevat departmentit
Department, joka lisättiin
Department, joka poistettiin
Tätä toimintoa ei yleensä tarvita. Jos tarvitset tiedon siitä, mitkä toimipisteet käyttävät tai eivät käytä integraatiotasi samalla Provet-tenantilla, ota yhteyttä Provet-tukeen ja kysy, voiko tämä ominaisuus olla käytössä integraatiossasi.
Provetissa toimipistekohtaisesti rajatut integraatiot näyttävät Enable- tai Disable-painikkeen rivin lopussa. Tämä mahdollistaa käyttäjien ottamaan integraation käyttöön tai poistamaan sen käytöstä toimipisteessä, jota he parhaillaan katsovat. Kun integraatio on lisätty, se täytyy ottaa erikseen käyttöön jokaiselle toimipisteelle. Toimipisteet, joissa integraatio on käytössä, näkyvät Disable-painikkeen vieressä. Jos integraatio ei tue toimipistekohtaista aktivointia, se aktivoidaan automaattisesti organisaatiotasolla.
Integraation julkaiseminen
Kun olet kehittänyt ja testannut integraatiosi ja haluat julkaista sen yleiseen käyttöön, ota yhteyttä Provet-tukeen, jotta Integration Template tulee näkyviin kaikille Provet-instansseille. Jos integraatiosi ei ole asiakaskohtainen ja se on tarkoitettu käytettäväksi monissa Provet-instansseissa monien käyttäjien toimesta, on joitakin vaatimuksia täytettävä ennen julkaisua. Nämä vaatimukset on tarkoitettu tekemään integraation käyttöönotosta helpompaa ja antamaan Provet-tuelle tarvittavat tiedot.
Tee lyhyt video integraatiostasi: miten sitä käytetään ja mitä se tekee.
Tee käyttöönotto-ohjeistus, joka sisältää kaikki manuaaliset vaiheet, joita Provet-käyttäjä tarvitsee integraation ottamiseen käyttöön. Vaiheisiin voi sisällyttää myös omassa järjestelmässäsi tarvittavat toimenpiteet.
Katso tämä esimerkkikäyttöönotto-ohje. Esimerkkaintegraatio käyttää yhtä webhookia, mutta sinun integraatiosi saattaa tarvita jotain muuta määritystä, kuten mukautetun kentän jne.
Toimita meille sekä video että käyttöönotto-ohje ja kerro, millä markkinoilla / missä maissa integraation pitäisi olla näkyvissä.
Jotta käyttöönotto voidaan automatisoida ja ihmisen aiheuttamat virheet minimoida, suosittelemme seuraavia ominaisuuksia yleiseen käyttöön tarkoitetuille integraatioille, joita käytetään monissa Provet-tanneissa:
Permission template
Hookup URL sähköposti-ilmoituksen sijaan
Webhookien ja mukautettujen painikkeiden luominen API-päätepisteiden avulla (jos soveltuu)
Jos näitä ominaisuuksia ei ole käytössä, ota yhteyttä Provet-tukeen, niin määritämme sinulle permission template -mallipohjan ja hookup URL:n. Jos sinulla on erityinen syy käyttää ilmoitussähköpostia, kerro siitä meille.
Kumppaneille, joilla on sijaintiperusteinen laskutus, toimipistekohtainen ominaisuus on pakollinen. Se täytyy määrittää, testata ja sisällyttää käyttöönotto-ohjeisiin, ennen kuin integraatio voidaan ottaa käyttöön.