Groweon GET-rajapinnan avulla voit hakea Groweoon tallennettuja kontakteja HubSpotiin ilman manuaalista tiedonsiirtoa. Integraatio hakee kontaktit Groweosta API-tokenilla ja luo tai päivittää niitä vastaavat kontaktit HubSpotissa.

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 HubSpotiin, vaan integraatio hakee tiedot Groweosta.

Tässä ohjeessa käydään läpi kaksi tapaa toteuttaa integraatio:

HubSpot Workflows + Custom code
ulkoinen integraatio HubSpot API kautta

HubSpotin sisäinen toteutus sopii tilanteeseen, jossa käytössä on Custom code -toiminnon sisältävä HubSpot-tilaus ja käsiteltävä datamäärä on kohtuullinen. Suuremmille kontaktimäärille tai monipuolisempaan integraatioon ulkoinen integraatio on yleensä joustavampi ratkaisu.

Huomaathan, että Groweo ei toteuta integraatioita, vaan tarjoaa GET APIn sekä API-avaimen asiakkailleen. Tämä on esimerkki, joka havainnollistaa rajapinnan käyttöä ja toteutusmahdollisuuksia.

Ennen kuin aloitat

Tarvitset:

Groweo API-tokenin
pääsyn HubSpotin integraatio- ja property-asetuksiin
Groweon ja HubSpotin välisen kenttämappauksen
HubSpot API käyttöön tarvittavan tunnisteen
Custom code -toimintoa käytettäessä sitä tukevan HubSpot-tilauksen.

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 HubSpot-integraation rakentamista esimerkiksi Postmanilla. Näin näet samalla oman Groweo-ympäristösi palauttaman JSON-datan ja voit määrittää sen perusteella, mitkä tiedot haluat siirtää HubSpotiin.

2. Luo HubSpotiin Groweo ID -kenttä

Kontaktit kannattaa tunnistaa Groweon omalla pysyvällä yksilöllisellä tunnisteella, jos sellainen sisältyy Groweon API-vastaukseen.

Luo HubSpotiin Contact property esimerkiksi nimellä:

Groweo ID

Internal name voi olla esimerkiksi:

groweo_id

Määritä propertyn arvot yksilöllisiksi, jotta samaa Groweo IDä ei voida tallentaa usealle kontaktille.

Tämän jälkeen integraatio voi käyttää Groweo IDä kontaktien tunnistamiseen: jos sama tunniste löytyy jo HubSpotista, olemassa oleva kontakti voidaan päivittää. Muussa tapauksessa voidaan luoda uusi kontakti.

HubSpotin Contacts API tukee tietueiden luomista tai päivittämistä oman yksilöllisen propertyn perusteella.

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

Vaihtoehto 1: integraatio HubSpot Workflows -toiminnolla

HubSpotin Custom code -workflow-toiminnon avulla voit suorittaa JavaScript- tai Python-koodia HubSpotissa. Koodi voi tehdä HTTP-kutsun Groweon API ja käsitellä palautetun datan.

Tämä mahdollistaa integraation toteuttamisen HubSpotin sisällä ilman erillistä integraatiopalvelua.

3. Tallenna Groweo API-token salaisuutena

Älä kirjoita Groweo API-tokenia suoraan integraation lähdekoodiin.

Kun luot workflow’hun Custom code -toiminnon, tallenna Groweo API-token toiminnon Secrets-asetuksiin esimerkiksi nimellä:

GROWEO_API_TOKEN

Koodi voi tämän jälkeen lukea tokenin ympäristömuuttujasta.

4. Hae kontaktit Groweosta

Custom code -toiminto voi tehdä GET-kutsun Groweon kontaktirajapintaan.

Yksinkertaistettu JavaScript-esimerkki:

exports.main = async (event, callback) => {

  const groweoToken = process.env.GROWEO_API_TOKEN;

  const response = await fetch(
    'https://engine.groweo.com/engine/api/client-api/contacts' +
    '?page=1&limit=50&populateModuleData=true',
    {
      method: 'GET',
      headers: {
        'x-client-api-token': groweoToken
      }
    }
  );

  if (!response.ok) {
    throw new Error(
      `Groweo API returned ${response.status}`
    );
  }

  const data = await response.json();

  console.log(data);

  callback({
    outputFields: {
      success: true
    }
  });
};

Tee ensimmäinen testi vain datan hakemiseksi. Tarkista Groweon palauttama JSON-rakenne ennen kuin rakennat varsinaisen kenttämappauksen.

5. Määritä kenttämappaus

Seuraavaksi määritetään, mitkä Groweon tiedot tallennetaan mihinkin HubSpot-propertyyn.

Mappaus voi sisältää esimerkiksi seuraavia:

Groweon tieto	HubSpot
kontaktin yksilöllinen tunniste	Groweo ID
etunimi	First name
sukunimi	Last name
sähköposti	Email
puhelinnumero	Phone number
yrityksen nimi	Company name

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

Groweon APIn todellinen JSON-rakenne ja käytettävissä olevat kentät tulee vielä tarkistaa oman API-kutsun vastauksesta ennen integraation toteuttamista.

Jos populateModuleData=true palauttaa integraatiossa tarvittavaa moduulikohtaista dataa, sille voidaan luoda tarvittavat omat Contact properties -kentät HubSpotiin.

6. Luo tai päivitä kontaktit HubSpotissa

HubSpotin CRM API tarjoaa batch upsert -toiminnon, jolla useita kontakteja voidaan luoda tai päivittää yhdellä API-kutsulla.

Toimintaperiaate on:

Groweo ID löytyy HubSpotista
        ↓
päivitä kontakti

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

Jos HubSpotiin luotu groweo_id on määritetty yksilölliseksi propertyksi, sitä voidaan käyttää upsert-operaation tunnisteena.

Periaatteellinen request-rakenne on:

{
  "inputs": [
    {
      "id": "GROWEO_CONTACT_ID",
      "idProperty": "groweo_id",
      "properties": {
        "firstname": "Matti",
        "lastname": "Meikäläinen",
        "email": "matti@example.com",
        "phone": "+358401234567"
      }
    }
  ]
}

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

7. Huomioi Groweon sivutus

Groweon API käyttää sivutusta. Esimerkiksi:

?page=1&limit=50

Integraatiota ei siis pidä rakentaa hakemaan ainoastaan ensimmäistä sivua. Jos kontakteja on enemmän kuin yhdelle sivulle mahtuu, myös seuraavat sivut pitää käsitellä.

Esimerkiksi:

Groweo
  ↓
GET page=1
  ↓
kontaktien käsittely
  ↓
GET page=2
  ↓
kontaktien käsittely
  ↓
GET page=3
  ↓
...

Haku lopetetaan, kun kaikki sivut on käsitelty.

Tarkka tapa viimeisen sivun tunnistamiseen kannattaa toteuttaa Groweon API todellisen vastauksen perusteella.

8. Ajasta synkronointi

HubSpotissa workflow voidaan käynnistää aikataulun perusteella. Toistuva synkronointi voi tapahtua esimerkiksi päivittäin.

Periaate on:

Ajastettu HubSpot Workflow
        ↓
Custom code
        ↓
Groweo GET API
        ↓
kontaktien käsittely
        ↓
HubSpot CRM

Huomaa, että HubSpotin aikataulupohjaiset workflow’t toimivat CRM-tietueiden kautta: aikataulun täyttyessä workflow’hun otetaan määritetyt ehdot täyttävät tietueet. Siksi Groweo-synkronointia varten tarvitaan myös tarkoituksenmukainen tapa käynnistää Custom code -toiminto vain kerran kullakin synkronointikerralla.

Päivittäin, viikoittain tai kuukausittain toistuva aikataulu edellyttää HubSpot Data Hub Professional- tai Enterprise -tilausta.

Milloin HubSpotin sisäinen toteutus ei ole paras vaihtoehto?

Custom code -toiminto soveltuu parhaiten rajattuun integraatiologiikkaan.

Jos Groweossa on paljon kontakteja tai yksi synkronointi edellyttää suuren sivumäärän hakemista ja useita HubSpot API -kutsuja, integraation toteuttaminen ulkoisessa ympäristössä on yleensä hallittavampaa.

Ulkoinen integraatio mahdollistaa esimerkiksi:

pidempien synkronointiajojen käsittelyn
oman lokituksen
kattavamman virheenkäsittelyn
synkronoinnin tilan tallentamisen
API-kutsujen jonottamisen ja uudelleenyritykset.

Vaihtoehto 2: ulkoinen integraatio

Ulkoinen integraatio voidaan toteuttaa esimerkiksi omana Node.js- tai Python-palveluna tai pilvipalvelun ajastettavana funktiona.

Sen toimintamalli on:

Ajastettu integraatio
        ↓
Groweo GET API
        ↓
kontaktien käsittely
        ↓
HubSpot CRM API
        ↓
batch upsert

Tässä mallissa HubSpotin ei tarvitse itse käynnistää Groweo-hakua.

9. Luo HubSpot Service Key

Uuteen järjestelmästä järjestelmään -integraatioon kannattaa käyttää HubSpotin Service Key -tunnistautumista.

HubSpotissa Service Key löytyy:

Settings
→ Integrations
→ Service Keys

Luo integraatiolle esimerkiksi:

Groweo Integration

Anna avaimelle vain integraation tarvitsemat oikeudet, kuten tarvittavat CRM-kontaktien luku- ja kirjoitusoikeudet.

Service Key toimii integraation HubSpot API -tunnisteena. Säilytä avain integraatioympäristössä salaisuutena tai ympäristömuuttujana, älä lähdekoodissa.

Jos käytössäsi on jo aiemmin luotu HubSpot Private App, sen tunniste voi edelleen toimia. Uusia integraatioita ei kuitenkaan kannata enää rakentaa legacy Private App -mallin varaan.

10. Hae ja käsittele kaikki Groweo-kontaktit

Ulkoinen integraatio:

hakee Groweosta ensimmäisen kontaktisivun
muuntaa Groweon tiedot HubSpotin property-muotoon
lähettää kontaktit HubSpotiin batch upsert -kutsulla
hakee seuraavan Groweo-sivun
jatkaa, kunnes kaikki kontaktit on käsitelty.

Esimerkiksi:

Groweo page 1
      ↓
kenttämappaus
      ↓
HubSpot batch upsert
      ↓
Groweo page 2
      ↓
kenttämappaus
      ↓
HubSpot batch upsert
      ↓
...

Vältä duplikaatit pysyvän tunnisteen avulla

Integraation kannalta keskeinen päätös on kontaktin yksilöivä tunniste.

Jos Groweon API tarjoaa pysyvän yksilöllisen kontaktitunnisteen, suositeltu rakenne on:

Groweo contact ID
        ↓
HubSpot property: groweo_id
        ↓
HubSpot batch upsert

Sähköpostiosoitetta ei kannata automaattisesti olettaa integraation pysyväksi tunnisteeksi, koska sähköpostiosoite voi muuttua.

Integraation rakenne lyhyesti

                 GROWEO®
                    │
                    │ GET
                    ▼
              Contacts API
                    │
          x-client-api-token
                    │
                    ▼
             Integraatiokoodi
                    │
              kenttämappaus
                    │
                    ▼
             HubSpot CRM API
                    │
               batch upsert
                    │
                    ▼
               HUBSPOT CRM

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

Mitä tarvitset integraatiota varten?

Ulkoinen integraatio tarvitsee:

Groweo API-tokenin
HubSpot Service Keyn
Groweo ID -propertyn tai muun sovitun yksilöintitavan HubSpotiin
Groweo- ja HubSpot-kenttien mappauksen
integraatiokoodin, joka käsittelee Groweon sivutuksen
ajastuksen, jos synkronointi halutaan suorittaa automaattisesti.

Jos integraatio toteutetaan kokonaan HubSpot Workflows -toiminnolla, tarvitaan lisäksi kyseiset workflow- ja Custom code -ominaisuudet sisältävä HubSpot-tilaus.

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 ennen kenttämappauksen rakentamista.

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

Näin yhdistät Groweo® GET-APIn HubSpotiin