Groweon GET-rajapinnan avulla voit hakea Groweoon tallennettuja kontakteja Microsoft Dynamics 365 -järjestelmääsi ilman manuaalista tiedonsiirtoa.

Integraatio hakee kontaktit Groweosta API-tokenilla ja luo tai päivittää niitä vastaavat kontaktit Microsoft Dataversessa.

Groweon rajapinta on tarkoitettu kontaktien lukemiseen. Sen kautta ei voi lisätä, muokata tai poistaa Groweon kontakteja. Groweo ei myöskään työnnä kontaktidataa automaattisesti Dynamicsiin, vaan integraatio hakee tiedot Groweosta.

Tässä ohjeessa integraatio toteutetaan Microsoft Power Automatella.

Huomaathan, että Groweo ei suunnittele tai toteuta integraatioita. Tämä artikkeli on esimerkki, joka auttaa sinua tai kumppaniasi suunnittelemaan ja/tai toteuttamaan tietojen siirron Groweon tarjoaman rajapinnan avulla.

Ennen kuin aloitat

Tarvitset:

Groweo API-tokenin
Microsoft Dynamics 365 / Dataverse -ympäristön
oikeudet luoda Dataverse-kenttiä ja alternate key -avaimia
Power Automate -käyttöoikeudet toteutuksessa tarvittaviin premium-ominaisuuksiin
Groweon ja Dynamicsin välisen kenttämappauksen.

1. Hanki Groweo API-token

Saat API-tokenin omalta Groweo-asiakasvastaavaltasi tai Groweon asiakaspalvelusta.

Groweon kontaktirajapinnan osoite on:

GET https://engine.groweo.com/engine/api/client-api/contacts

Esimerkiksi ensimmäinen 50 kontaktin sivu voidaan hakea parametreilla:

?page=1&limit=50&populateModuleData=true

API-token välitetään HTTP-headerissa:

x-client-api-token: <API_TOKEN>

Kokonainen pyyntö näyttää esimerkiksi tältä:

GET https://engine.groweo.com/engine/api/client-api/contacts?page=1&limit=50&populateModuleData=true

Testaa API-kutsu ennen integraation rakentamista esimerkiksi Postmanilla. Näin näet samalla oman Groweo-ympäristösi palauttaman JSON-datan ja voit määrittää sen perusteella Dynamicsiin siirrettävät tiedot.

2. Luo Dynamicsiin Groweo ID -kenttä

Dynamics 365 -kontaktit tallennetaan Microsoft Dataversen Contact-tauluun.

Integraatiota varten kannattaa luoda Contact-tauluun oma kenttä Groweo-kontaktin pysyvälle yksilölliselle tunnisteelle, jos tällainen tunniste sisältyy Groweon API-vastaukseen.

Kentän nimi voi olla esimerkiksi:

Groweo ID

Sen schema name voi olla esimerkiksi:

new_groweoid

Groweo ID:n avulla sama Groweo-kontakti voidaan yhdistää samaan Dynamics-tietueeseen myös seuraavilla synkronointikerroilla.

Sähköpostiosoitetta ei kannata automaattisesti käyttää integraation pysyvänä tunnisteena, koska sähköpostiosoite voi muuttua.

Huomio: varmista ensin Groweon todellisesta API-vastauksesta, että käytettävissä on tähän tarkoitukseen sopiva pysyvä kontaktitunniste.

3. Tee Groweo IDä Dataversen alternate key

Avaa Power Apps ja valitse Dynamics-ympäristösi.

Siirry Contact-taulun avaimiin:

Tables
→ Contact
→ Keys
→ New key

Luo avain, joka käyttää Groweo ID -kenttää.

Esimerkiksi:

Display name: Groweo ID Key
Column: Groweo ID

Dataversen alternate key mahdollistaa tietueen tunnistamisen ulkoisen järjestelmän omalla tunnisteella Microsoftin GUID-tunnisteen sijaan.

Tämä sopii integraatioon, jossa Groweo-kontakti halutaan yhdistää aina samaan Dataverse-tietueeseen.

Toimintaperiaate on:

Groweo ID löytyy
        ↓
päivitä kontakti

Groweo ID:tä ei löydy
        ↓
luo uusi kontakti

Dataversen Web API tukee tähän upsert-operaatiota.

4. Luo Power Automate -flow

Avaa Power Automate ja luo uusi:

Scheduled cloud flow

Määritä sopiva ajastus sen mukaan, kuinka nopeasti Groweoon syntyneiden kontaktien pitää näkyä Dynamicsissa.

Flow’n perusrakenne voi olla:

Recurrence
    ↓
HTTP-kutsu Groweoon
    ↓
JSON-datan käsittely
    ↓
kontaktien käsittely
    ↓
Dataverse

5. Lisää HTTP-kutsu Groweoon

Lisää flow’hun HTTP-toiminto.

Määritä metodiksi:

GET

ja URI:

https://engine.groweo.com/engine/api/client-api/contacts?page=1&limit=50&populateModuleData=true

Pyynnössä tarvitaan header:

x-client-api-token

jonka arvoksi annetaan Groweo API-token.

Power Automatella voidaan tehdä HTTP-pyyntöjä ulkoisiin REST-rajapintoihin. Toteutuksessa käytettävät HTTP- ja Dataverse-toiminnot voivat edellyttää premium-käyttöoikeuksia, joten varmista oman Microsoft-ympäristösi lisensointi ennen integraation rakentamista.

6. Säilytä API-token turvallisesti

Älä kirjoita Groweo API-tokenia suoraan näkyviin flow’n lähdekoodiin tai muihin helposti luettaviin asetuksiin.

Power Platform tukee Azure Key Vaultiin tallennettujen salaisuuksien käyttämistä environment variable -viittausten kautta. Tällöin varsinainen token säilytetään Azure Key Vaultissa ja Power Platformiin tallennetaan viittaus salaisuuteen.

Tämä on tavallista tekstimuotoista environment variablea turvallisempi tapa käsitellä API-tokenia.

Voit lisäksi käyttää Power Automaten Secure Inputs– ja Secure Outputs -asetuksia estämään arkaluonteisten arvojen näkymistä flow’n run historyssa.

Noudata tokenin säilytyksessä oman organisaatiosi Power Platform- ja tietoturvakäytäntöjä.

7. Tarkista Groweon palauttama JSON

Aja flow ensimmäisen kerran pelkällä HTTP-kutsulla.

Power Automaten run historysta näet Groweon palauttaman JSON-vastauksen.

Sen jälkeen voit lisätä:

Parse JSON

-toiminnon ja muodostaa sen skeeman todellisen API-vastauksen perusteella.

Groweon API koko kontaktivastauksen rakennetta ei ole määritelty tässä ohjeessa. Siksi kenttämappaus pitää tehdä oman Groweo-ympäristösi todellisen API-vastauksen perusteella.

8. Määritä kenttämappaus

Seuraavaksi määritetään, mitkä Groweon tiedot tallennetaan Dynamicsiin.

Mappaus voi sisältää esimerkiksi seuraavat tiedot:

Groweon tieto	Dynamics 365 / Dataverse
kontaktin yksilöllinen tunniste	Groweo ID
etunimi	First Name
sukunimi	Last Name
sähköposti	Email
puhelinnumero	Business Phone tai Mobile Phone
tehtävänimike	Job Title
yrityksen nimi	Dynamicsin datamallin mukainen kenttä tai Account-yhteys

Taulukko kuvaa mahdollista kenttämappausta, ei Groweon API dokumentoitua response-skeemaa.

Jos populateModuleData=true palauttaa integraatiossa tarvittavaa moduulikohtaista dataa, sille voidaan luoda tarvittavat omat kentät Dataverseen.

Kentät kannattaa määrittää oman Dynamics-datamallin ja Groweosta todellisuudessa saatavan datan perusteella.

9. Luo tai päivitä kontaktit

Groweosta haetut kontaktit voidaan käsitellä Power Automatessa esimerkiksi kahdella tavalla.

Tapa A: etsi kontakti ja päivitä tai luo

Power Automaten Microsoft Dataverse -connectorilla voidaan ensin hakea Groweo IDä vastaava tietue.

Sen jälkeen logiikka on:

kontakti löytyy
→ Update a row

kontaktia ei löydy
→ Add a new row

Tämä tapa on suoraviivainen rakentaa Power Automaten käyttöliittymässä, mutta se voi tuottaa useita Dataverse-kutsuja jokaista käsiteltävää kontaktia kohti.

Tapa B: käytä Dataverse Web API upsertia

Dataverse Web API mahdollistaa tietueen luomisen tai päivittämisen yhdellä PATCH-pyynnöllä, kun tietue tunnistetaan Groweo ID perustuvalla alternate keyllä.

Pyyntö voi olla esimerkiksi:

PATCH
https://<organization>.crm.dynamics.com/api/data/v9.2/contacts(new_groweoid='GROWEO_ID')

Body sisältää päivitettävät tiedot, esimerkiksi:

{
  "firstname": "Matti",
  "lastname": "Meikäläinen",
  "emailaddress1": "matti@example.com",
  "telephone1": "+358401234567"
}

Jos alternate keytä vastaava kontakti löytyy, Dataverse päivittää sen. Jos tietuetta ei löydy, Dataverse luo uuden.

Alternate keyn arvoa ei tarvitse lisätä requestin bodyyn, koska se annetaan jo pyynnön URL-osoitteessa.

Esimerkin henkilötiedot ja kentät ovat havainnollistavia eivätkä kuvaa Groweon dokumentoitua API-vastausta.

10. Huomioi Groweon sivutus

Groweon API käyttää sivutusta. Esimerkiksi:

?page=1&limit=50

Jos kontakteja on enemmän kuin yhdelle sivulle mahtuu, integraation pitää hakea myös seuraavat sivut.

Toimintaperiaate voi olla esimerkiksi:

page = 1
    ↓
GET Groweo
    ↓
käsittele kontaktit
    ↓
page = page + 1
    ↓
GET Groweo
    ↓
käsittele kontaktit
    ↓
...

Power Automatessa toisto voidaan toteuttaa esimerkiksi Do until -rakenteella.

Tarkka lopetusehto pitää määrittää Groweon todellisen API-vastauksen perusteella. Älä siis oleta tiettyä pagination-kenttää ennen kuin olet tarkistanut API palauttaman JSON-datan.

11. Vältä tarpeettomia Dynamics-päivityksiä

Jos integraatio hakee kaikki Groweo-kontaktit esimerkiksi tunnin välein, samat Dynamics-tietueet voidaan päätyä päivittämään jokaisella ajolla.

Jos Groweon API-vastaus sisältää luotettavan tiedon kontaktin viimeisimmästä muokkausajasta, sitä voidaan hyödyntää muuttuneiden kontaktien tunnistamiseen.

Jos tällaista tietoa ei ole saatavilla, integraatio voidaan toteuttaa esimerkiksi vertaamalla olennaisia kenttiä ennen päivitystä tai hyväksymällä se, että samat tietueet käsitellään uudelleen.

Älä rakenna muutosten tunnistamista Modified At -kentän varaan ennen kuin olet varmistanut, että tarvittava tieto sisältyy Groweon API-vastaukseen.

12. Lisää virheenkäsittely

Tuotantointegraatioon kannattaa lisätä vähintään:

Groweo API -kutsun statuskoodin tarkistus
Dataverse-virheiden käsittely
epäonnistuneiden kontaktien lokitus.

Power Automatessa virheenkäsittely voidaan rakentaa esimerkiksi Scope-toiminnoilla:

Scope: Try
    ↓
Groweo GET
    ↓
Dataverse-käsittely

Scope: Error
    ↓
kirjaa virhe
    ↓
lähetä ilmoitus

Error-scope voidaan määrittää käynnistymään, jos varsinainen integraatioscope epäonnistuu.

13. Huomioi Dataversen ja Power Automaten rajat

Power Automaten Microsoft Dataverse -connectorin dokumentoitu connector-kohtainen throttling-raja on tällä hetkellä 1 000 API-kutsua per yhteys 60 sekunnissa.

Tämän lisäksi Dataversella, Power Automatella ja käytössä olevalla lisenssillä on muita palvelu- ja käyttörajoja.

Erityisesti rivi kerrallaan toimivassa toteutuksessa kutsujen määrä voi kasvaa nopeasti. Esimerkiksi erillinen haku ja päivitys jokaiselle kontaktille tuottavat useita kutsuja yhtä kontaktia kohti.

Suuremmissa integraatioissa kannattaa siksi arvioida Dataverse Web API upsert- ja batch-mahdollisuuksia sen sijaan, että jokainen kontakti käsitellään usealla erillisellä connector-kutsulla.

Vaihtoehto: erillinen integraatiopalvelu

Power Automate sopii hyvin moniin Dynamics-integraatioihin.

Jos kontaktimäärä on suuri tai integraatiolta vaaditaan esimerkiksi kattavaa lokitusta, retry-logiikkaa tai tehokasta batch-käsittelyä, integraation voi toteuttaa myös erillisellä palvelulla.

Tällainen voi olla esimerkiksi:

Azure Function
Azure Logic Apps
oma Node.js-palvelu
oma Python-palvelu

Rakenne on silloin:

Ajastettu integraatio
        ↓
Groweo GET API
        ↓
kontaktien käsittely
        ↓
Dataverse Web API
        ↓
Dynamics 365

Dataverse Web API tukee ulkoisten järjestelmien synkronointiin soveltuvia alternate key- ja upsert-toimintoja.

Integraation rakenne lyhyesti

                 GROWEO®
                    │
                    │ GET
                    ▼
              Contacts API
                    │
          x-client-api-token
                    │
                    ▼
             Power Automate
                    │
              JSON-käsittely
                    │
              kenttämappaus
                    │
                    ▼
          Microsoft Dataverse
                    │
             Groweo ID key
                    │
                 upsert
                    │
                    ▼
              DYNAMICS 365

Groweo toimii tässä integraatiossa kontaktidatan lähteenä. Integraatio hakee tiedot Groweosta ja tallentaa ne Microsoft Dataverseen.

Mitä tarvitset integraatiota varten?

Tarvitset:

Groweo API-tokenin
Dynamics 365 / Dataverse -ympäristön
Groweo ID -kentän tai muun sovitun yksilöintitavan Contact-tauluun
Groweo ID perustuvan alternate keyn, jos käytät sitä upsert-tunnisteena
Power Automate -flow’n tai erillisen integraatiopalvelun
Groweo- ja Dynamics-kenttien mappauksen
ajastuksen, jos synkronointi halutaan suorittaa automaattisesti.

Power Automate -ratkaisussa tarvitset lisäksi käyttöoikeuden toteutuksessa tarvittaviin premium-ominaisuuksiin. Tarkista oman Dynamics 365- ja Power Automate -ympäristösi lisensointi ennen tuotantoon vientiä.

Aloita testaamalla yksi API-kutsu

Ennen varsinaisen synkronoinnin rakentamista hae Groweosta yksi sivu kontakteja:

page=1
limit=50
populateModuleData=true

Tarkista palautuvan JSON-datan rakenne ja määritä sen perusteella Groweon ja Dynamicsin välinen kenttämappaus.

Näin integraatio perustuu oman Groweo-ympäristösi todellisiin kenttiin eikä oletuksiin kontaktidatan rakenteesta.

Näin yhdistät Groweo® GET-rajapinnan Microsoft Dynamics 365 -järjestelmääsi