Groweo-kontaktien tuominen Salesforceen API-rajapinnalla

Groweon API-rajapinnan avulla voit hakea Groweo Contactsiin tallennettuja kontakteja Salesforceen ja tallentaa ne esimerkiksi Salesforce Contact- tai Lead-tietueiksi.

Integraatio toimii Salesforcesta Groweoon tehtävillä GET-pyynnöillä. Groweo ei lähetä kontakteja Salesforceen eikä rajapinnan kautta voi luoda, muokata tai poistaa Groweo-kontakteja.

Tässä ohjeessa käydään läpi yksi tapa toteuttaa integraatio Salesforcen Named Credential-, External Credential- ja Apex-toiminnoilla.

Huomio: Salesforce-ympäristöt ja niiden asetukset voivat poiketa toisistaan. Toteutus kannattaa siksi aina tehdä tai tarkistuttaa Salesforce-kehittäjällä tai -pääkäyttäjällä. Groweo ei toteuta integraatioita, vaan tarjoaa asiakkailleen GET APIn sekä avaimen.

Ennen kuin aloitat

Tarvitset:

Groweon API-tokenin
oikeudet Salesforcen Named Credentials- ja External Credentials -asetuksiin
mahdollisuuden luoda Salesforceen Permission Set
Apex-kehitysoikeudet, jos toteutat integraation Apexilla.

Groweon kontaktirajapinnan osoite on:

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

Rajapinta tukee sivutusta. Esimerkiksi:

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

API-token välitetään pyynnö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

1. Hanki Groweo API-token

Saat API-tokenin Groweon asiakasvastaavaltasi, tai asiakaspalvelustamme.

Token antaa lukuoikeuden Groweon kontaktirajapintaan. Rajapinnan kautta ei voi luoda, muokata tai poistaa Groweo-kontakteja.

Ennen Salesforce-integraation rakentamista kannattaa varmistaa, että token ja rajapintakutsu toimivat. Voit testata niitä esimerkiksi Postmanilla tai cURL-komennolla:

curl --location \
'https://engine.groweo.com/engine/api/client-api/contacts?page=1&limit=50&populateModuleData=true' \
--header 'x-client-api-token: OMA_TOKEN'

Korvaa OMA_TOKEN saamallasi API-tokenilla.

Jos rajapinta palauttaa onnistuneen JSON-vastauksen, voit siirtyä Salesforce-asetuksiin.

Älä tallenna API-tokenia Apex-koodiin tai muuhun lähdekoodiin.

2. Luo Salesforceen External Credential

Avaa Salesforcessa:

Setup → Named Credentials → External Credentials → New

Voit käyttää esimerkiksi seuraavia tietoja:

Label: Groweo API Credential
Name: Groweo_API_Credential
Authentication Protocol: Custom

Groweo käyttää tunnistautumiseen omaa x-client-api-token-headeriaan. Siksi External Credentialin autentikointitavaksi soveltuu Custom.

Tallenna External Credential.

Luo Principal ja tallenna API-token

Avaa luomasi External Credential ja lisää sille Principal.

Esimerkiksi:

Parameter Name: Groweo
Identity Type: Named Principal

Lisää Principalille Authentication Parameter:

Name: ApiToken
Value: <GROWEO API TOKEN>

Näin API-token säilytetään Salesforcen credential-rakenteessa eikä Apex-koodissa.

3. Lisää Groweon vaatima HTTP-header

Lisää External Credentialiin uusi Custom Header.

Headerin nimi:

x-client-api-token

Headerin arvo:

{!$Credential.Groweo_API_Credential.ApiToken}

Tässä:

Groweo_API_Credential on External Credentialin API-nimi
ApiToken on edellisessä vaiheessa luodun Authentication Parameterin nimi.

Jos käytät omassa Salesforce-ympäristössäsi eri nimiä, muuta viittaus vastaamaan niitä.

4. Luo Named Credential Groweon API

Avaa:

Setup → Named Credentials → Named Credentials → New

Luo esimerkiksi:

Label: Groweo API
Name: Groweo_API
URL: https://engine.groweo.com
External Credential: Groweo API Credential

Poista Generate Authorization Header käytöstä. Groweo ei käytä tässä integraatiossa tavallista Authorization-headeria, vaan API-token välitetään omassa x-client-api-token-headerissa.

Varmista myös, että credential-asetukset sallivat HTTP-headerissa käytetyn credential-viittauksen.

Tallenna Named Credential.

5. Anna integraatiota ajavalle käyttäjälle oikeudet

External Credentialin Principal pitää antaa sen Salesforce-käyttäjän käyttöön, jonka kontekstissa integraatio suoritetaan.

Voit tehdä tätä varten esimerkiksi Permission Setin:

Groweo API Access

Avaa Permission Setistä:

External Credential Principal Access

ja ota käyttöön Groweolle luomasi Principal.

Varmista lisäksi, että Permission Set on määritetty integraatiota ajavalle Salesforce-käyttäjälle.

Salesforce voi ympäristöstä ja käytetyistä oikeuksista riippuen edellyttää myös oikeuksia User External Credentials -objektiin.

6. Testaa ensimmäinen API-kutsu Apexilla

Kun Named Credentialin API-nimi on Groweo_API, voit käyttää sitä Apex-calloutissa näin:

callout:Groweo_API/engine/api/client-api/contacts

Esimerkiksi:

public with sharing class GroweoApiService {

    public static String getContacts(Integer pageNumber) {

        HttpRequest req = new HttpRequest();

        req.setEndpoint(
            'callout:Groweo_API' +
            '/engine/api/client-api/contacts' +
            '?page=' + pageNumber +
            '&limit=50' +
            '&populateModuleData=true'
        );

        req.setMethod('GET');
        req.setTimeout(120000);

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 200 &&
            res.getStatusCode() < 300) {

            return res.getBody();
        }

        throw new CalloutException(
            'Groweo API error: ' +
            res.getStatusCode() +
            ' ' +
            res.getBody()
        );
    }
}

API-tokenia ei tarvitse eikä pidä lisätä Apex-koodiin. Salesforce lisää External Credentialiin määritetyn x-client-api-token-headerin pyyntöön.

Named Credential puolestaan korvaa:

callout:Groweo_API

-arvon määritetyllä osoitteella:

https://engine.groweo.com

Endpointin polku ja query-parametrit voidaan lisätä Apexissa tämän perään.

7. Tarkista Groweon palauttama JSON ja määritä kenttäkartoitus

Ennen varsinaisen Salesforce-kenttäkartoituksen rakentamista tarkista Groweon API palauttaman datan rakenne omassa ympäristössäsi.

Voit esimerkiksi hakea ensimmäisen sivun ja tutkia vastauksen:

String jsonBody = GroweoApiService.getContacts(1);

Object response = JSON.deserializeUntyped(jsonBody);

System.debug(response);

API-vastauksen perusteella määritetään, mitkä Groweo-kentät tallennetaan Salesforceen ja mihin Salesforce-kenttiin ne sijoitetaan.

Esimerkiksi integraatiossa voidaan haluta käsitellä seuraavan tyyppisiä tietoja:

Groweo-kontaktin tunniste
Etunimi
Sukunimi
Sähköpostiosoite
Puhelinnumero
Muut kontaktin yhteydessä tallennetut tiedot

Kenttien todelliset nimet ja JSON-rakenne pitää tarkistaa API-vastauksesta ennen Apex-luokkien tai kenttäkartoituksen toteuttamista.

Älä rakenna integraatiota esimerkkimuotoisen JSON-rakenteen varaan.

8. Tallenna Groweo-kontaktin tunniste Salesforceen

Jos Groweon API-vastauksessa on kontaktin pysyvä yksilöllinen tunniste, sille kannattaa luoda Salesforceen oma kenttä.

Esimerkiksi Salesforce Contact -objektiin:

Groweo_ID__c

Suositeltu kenttätyyppi:

Type: Text
Unique: true
External ID: true

Tällöin sama Groweo-kontakti voidaan tunnistaa myös seuraavilla synkronointikerroilla.

Integraatio voi käyttää Salesforce upsert -toimintoa:

upsert contactsToSave Groweo_ID__c;

Näin olemassa oleva Salesforce-tietue voidaan päivittää sen sijaan, että jokaisella synkronointikerralla syntyisi uusi tietue.

Esimerkkirakenne:

List<Contact> contactsToSave = new List<Contact>();

for (GroweoContact g : groweoContacts) {

    Contact c = new Contact();

    c.Groweo_ID__c = g.id;
    c.FirstName = g.firstName;
    c.LastName = g.lastName;
    c.Email = g.email;
    c.Phone = g.phone;

    contactsToSave.add(c);
}

upsert contactsToSave Groweo_ID__c;

Tämä koodi on esimerkki integraation toimintaperiaatteesta. Käytettävät kentät pitää sovittaa Groweon todelliseen API-vastaukseen ja Salesforce-organisaatiosi tietomalliin.

Jos pysyvää Groweo-tunnistetta ei ole käytettävissä API-vastauksessa, integraation yksilöintilogiikka pitää määritellä erikseen. Sähköpostiosoitetta ei kannata automaattisesti olettaa pysyväksi integraatioavaimeksi, koska asiakkaan sähköpostiosoite voi muuttua.

9. Käsittele kaikki kontaktisivut

Groweon kontaktirajapinta käyttää sivutusta.

Esimerkiksi:

?page=1&limit=50

Tämä tarkoittaa, että integraation pitää hakea kontaktit sivu kerrallaan. Jos integraatio hakee aina vain page=1, Salesforceen siirtyy vain ensimmäisen sivun sisältämä kontaktijoukko.

Yksi tapa toteuttaa käsittely Salesforcessa on Queueable Apex:

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

Integraation pitää jatkaa sivujen hakemista, kunnes Groweon API palauttaman tiedon perusteella kaikki sivut on käsitelty.

Se, miten viimeinen sivu tunnistetaan, kannattaa toteuttaa API-vastauksen todellisen sivutusrakenteen perusteella.

10. Ajasta synkronointi tarvittaessa

Jos Groweon ja Salesforcen tiedot halutaan synkronoida automaattisesti, Salesforce voi käynnistää haun Scheduled Apexilla.

Esimerkiksi:

Scheduled Apex
      ↓
Queueable Apex
      ↓
Groweo GET API
      ↓
JSON-vastauksen käsittely
      ↓
kenttäkartoitus
      ↓
upsert Salesforceen

Synkronointi voidaan ajastaa yrityksen tarpeen mukaan esimerkiksi tunnin välein tai kerran vuorokaudessa.

Groweon API on tässä toteutuksessa lukurajapinta: Salesforce hakee tiedot Groweosta. Integraatio ei siis edellytä, että Groweo lähettää muutoksia Salesforceen.

Integraation rakenne lyhyesti

                 GROWEO
                    │
                    │ GET
                    ▼
https://engine.groweo.com
/engine/api/client-api/contacts
                    │
                    │ x-client-api-token
                    ▼
       Salesforce External Credential
                    │
                    ▼
         Salesforce Named Credential
                    │
                    ▼
             Queueable Apex
                    │
             JSON → Salesforce
                    │
                    ▼
          Contact tai Lead
                    │
              External ID
                    │
                 upsert

Salesforce-toteutukseen tarvitaan tyypillisesti:

External Credential, jossa Groweo API-token säilytetään
Custom Header x-client-api-token tunnistautumista varten
Named Credential Groweon API-osoitteelle
Permission Set, joka antaa integraatiota ajavalle käyttäjälle oikeuden credentialiin
Apex callout, joka hakee kontaktit Groweon GET-rajapinnasta
kenttäkartoitus Groweon API-vastauksen ja Salesforce-tietomallin välille
pysyvä tunniste / External ID, jolla sama kontakti voidaan päivittää ilman duplikaatteja
sivutuksen käsittely, jotta kaikki kontaktit haetaan
Scheduled Apex, jos tietojen haku halutaan automatisoida.

Mitä integraatio tekee ja mitä se ei tee?

Tällä toteutuksella Salesforce voi:

hakea Groweoon tallennettuja kontakteja
käsitellä Groweon palauttamaa kontaktidataa
luoda tai päivittää Salesforce-tietueita oman integraatiologiikan mukaisesti
suorittaa haun automaattisesti määritetyin väliajoin.

Groweon GET-rajapinnan kautta ei voi:

luoda uusia Groweo-kontakteja
muokata Groweossa olevia kontakteja
poistaa Groweo-kontakteja
lähettää Salesforce-tietoja Groweoon.

Integraation suunta on siis Groweosta Salesforceen, Salesforcen käynnistämänä.

Groweo-kontaktien tuominen Salesforceen GET API-rajapinnan avulla

Ennen kuin aloitat

1. Hanki Groweo API-token

2. Luo Salesforceen External Credential

Luo Principal ja tallenna API-token

3. Lisää Groweon vaatima HTTP-header

4. Luo Named Credential Groweon API

5. Anna integraatiota ajavalle käyttäjälle oikeudet

6. Testaa ensimmäinen API-kutsu Apexilla

7. Tarkista Groweon palauttama JSON ja määritä kenttäkartoitus

8. Tallenna Groweo-kontaktin tunniste Salesforceen

9. Käsittele kaikki kontaktisivut

10. Ajasta synkronointi tarvittaessa

Integraation rakenne lyhyesti

Mitä integraatio tekee ja mitä se ei tee?

Yhteystiedot

Ratkaisut

Tutustu Groweoon

Ura ja yritys