Yhdistä Salesforce muihin järjestelmiin käyttäen REST API:a
27.8.2024
Vaikka Salesforce on laaja ja monipuolinen alusta, on monella toimijalla muitakin päivittäisessä työssä käytettäviä liiketoiminnan kannalta merkittäviä järjestelmiä. Tällaisten järjestelmien olemassaolo ei kumoa Salesforcen tarvetta, vaan päinvastoin – ne vahvistavat sen vaikutusta, jos ne laitetaan toimimaan yhdessä. Kolmannen osapuolen järjestelmien integroiminen Salesforceen käy näppärästi REST API:n avulla, joten tässä blogissa syvennymme sen käyttöönottoon.
Integraatiokäyttäjän luominen
Salesforce tarjoaa nykyisin 5 kappaletta ilmaisia integraatiolisenssejä, joita voidaan käyttää API only- käyttöoikeuksilla. Näiden avulla Salesforce saadaan kommunikoimaan muiden ulkoisien järjestelmien kanssa, joista voidaan hakea tietoa Salesforceen tai lähettää tietoja Salesforcesta. Käyttäjän luominen tapahtuu Saleforcessa seuraavasti: Setup -> Users -> Users -> New User.
Uuden käyttäjän luomisessa täytetään vaaditut perustiedot sekä oleellisena seuraavat kentät:
- User Licence: Salesforce Integration
- Profile: Minimum Access – API Only Integrations
- Sivun alalaidasta (ei näy kuvassa) “Generate new password and notify user immediately” täppäys päälle -> Mikäli ottaa täpän pois, täytyy salasana lähettää manuaalisesti käyttäjälle
Kun käyttäjä tallennetaan, lähtee Email- kentässä olevaan sähköpostiosoitteeseen salasanan asetuslinkki, josta käyttäjälle saa luotua salasanan.
Linkkiä klikatessa avautuu salasanan asettamisikkuna, jossa käyttäjälle voi asettaa haluamansa salasanan sekä turvakysymyksen + vastauksen.
Koska käyttäjälle asetettiin API only profiili, salasanan asettamisen jälkeen tulee ilmoitus, ettei käyttäjällä ole oikeutta Salesforcen käyttöliittymään.
Lisätietoa aiheeseen liittyen täältä.
Käyttöoikeuksien antaminen käyttäjälle
Tämän jälkeen käyttäjä on valmis, mutta sillä ei ole oikeuksia mihinkään Salesforcen dataan. Oikeudet Salesforcen dataan asetetaan käyttöoikeusjoukkojen (permission sets) avulla, joilla voidaan määrittää kaikki vaaditut ja tarpeelliset oikeudet sekä rajata oikeudet vain välttämättömiin. Tämä onnistuu Salesforcesta Setup -> Users -> Permission Sets -> New.
Uudelle permission setille tulee asettaa nimi, API nimi ja halutessaan lisenssityyppi, jota luotava permission set koskee. Tässä tapauksessa lisenssikenttään voidaan asettaa Salesforce Integration.
Tallennuksen jälkeen esiin tulee lista erilaisia kategorioita, joille käyttöoikeuksia voidaan asettaa. Useimmiten oleellisimpana asiana on käydä asettamassa tarvittaville objekteille ja niiden kentille luku- ja/tai muokkausoikeudet, jotta integraation avulla päästään näihin tietoihin käsiksi.
Tarvittavien oikeuksien lisäyksen jälkeen permission set täytyy asettaa vielä käyttäjälle, joka tapahtuu käyttäjän asetuksista
Edit Assignments -nappia painamalla aukeaa listaus kaikista kyseiselle käyttäjälle saatavilla olevista permission seteistä. Vasemmasta listasta etsitään juuri tehty permission set, klikataan sitä ja painetaan vierestä löytyvää Add-nappia, jolloin permission set siirtyy oikean puolen listalle (Enabled Permission Sets).
Tallennuksen jälkeen käyttäjällä on kyseisessä permission setissä annetut oikeudet.
Connected App luominen
Connected App mahdollistaa varsinaisen kommunikaation ja datan kulkemisen toisien järjestelmien ja Salesforcen välillä. Connected Appin kautta saadaan toisen järjestelmän palveluntarjoajalle annettua kaikki tarpeellinen tieto ja oikeudet, jotta Salesforcen niin sanottu “kutsuminen” on mahdollista. Connected Appin pääsee luomaan: Setup -> Apps -> App Manager -> New Connected App.
New Connected App -napin painaminen avaa seuraavanlaisen ikkunan:
Tärkeimmät asiat Connected Appia luodessa:
- Kuvaava nimi, jotta myöhemmin sen löytää helposti listauksesta, jos siihen tarvitsee tehdä muokkauksia
- Mikäli halutaan vaatia tunnistautuminen rajapintaan, Enable Oauth Settings täytyy merkata päälle
- Tämä avaa uusia kenttiä, joissa määritellään Callback URL:t sekä valitaan käyttöön vaadittavat/tarvittavat oikeudet
Alempana sivulla on paljon lisää asetuksia, jotka on hyvä katsoa läpi ennen tallennusta:
Tallentamisen jälkeen aukeaa ilmoitusteksti, jonka mukaan muutosten voimaantuleminen voi kestää jonkin aikaa. Tästä seuraavana aukeaa juuri luodun Connected Appin “etusivu”, josta voidaan jatkaa muihin muutoksiin.
Seuraavassa kuvassa on kaksi huomioitavaa asiaa:
- Numerolla yksi (1.) merkattu “Manage”-nappi avaa ikkunan, josta saadaan asetettua tarkempia käyttöoikeusasetuksia
- Numerolla kaksi (2.) merkatun “Manage Consumer Details” -napin kautta saadaan key/secret arvot.
Edellisen kuvan “Manage”-napin painallus avaa seuraavanlaisen näkymän:
Kuvaan punaisella neliöllä rajattu “Edit Policies”-nappi avaa yllä näkyvät kentät muokattavaan muotoon:
Tästä huomioitavina asioina ovat pakolliset kentät. Permitted Users -kentällä voidaan asettaa rajapinnan kutsuminen siten, että kuka vain käyttäjä pystyy kutsumaan järjestelmää rajapinnan avulla ilman suurempia rajoituksia. Toki tässäkin tilanteessa sellaiset käyttäjän käyttöoikeudet otetaan huomioon, joilla hän on suorittanut rajapintakutsun. Oikealla puolella olevilla kentillä määritetään Tokenia koskevia käytänteitä, kuten kuinka nopeasti haettava Token vanhenee.
Mikäli rajapinnan kutsumista halutaan rajoittaa vain tiettyyn tai tiettyihin profiileihin, asetetaan Permitted Users kenttään “Admin approved users are pre-authorized”. Kun asetukset ovat kunnossa, painetaan Save, jolloin palataan Manage -sivulle.
Mikäli Permitted Users on tallennettu “Admin approved users are pre-authorized” -tilassa, voidaan käyttäjät ja muut käyttöoikeudet määritellä uudelleenauenneen sivun alalaidasta. Näitä kaikkia osioita ei ilmesty esille, jos käyttöoikeudet jätettiin “Self-Authorize” -tilaan.
Remote site
Mikäli Salesforcesta on tarpeen kutsua toista järjestelmää, täytyy kutsuttava osoite asettaa luotettuihin osoitteisiin. Jos osoitetta ei lisätä luotettuihin osoitteisiin, kutsut eivät mene läpi Salesforcesta ja syntyy virheviesti. Osoitteen lisääminen onnistuu: Setup -> Security -> Remote Site Settings -> New Remote Site.
Sivulle annetaan nimi, jolla käytettävä URL ilmenee Salesforcessa (eli on siellä tunnistettavissa tällä nimellä) ja URL kenttään asetetaan osoite, jota tullaan kutsumaan.
Mikäli endpointeista on useita eri variaatioita, voi osoitteeseen asettaa vain alkuosan “.com” asti. Näin yhdellä remote sitella päästään käsiksi kaikkiin endpointteihin. Esimerkkiskenaario: käytetään kuvassa olevaa https://test.salesforce.com URL:a. Kuvitellaan, että kyseisestä endpointista pitäisi hakea liidejä, myyntimahdollisuuksia ja tilejä. Näiden Remote Site URLit olisivat tällöin seuraavanlaiset:
https://test.salesforce.com/Lead
https://test.salesforce.com/Opportunity
https://test.salesforce.com/Account
Tässä tilanteessa voimme sallia https://test.salesforce.com URL:n, jolloin kaikki yllä mainitut URL:t ovat sallittuja ja niihin päästään käsiksi, kutsumalla niitä esimerkiksi koodista.
Authentication Flow
Toisinaan integraatioiden halutaan toimivan automatisoidusti, ilman käyttäjän manuaalisia toimia jokaisen pyynnön välillä (eli server to server) tai järjestelmä muutoin vaatii erilaisen authentikoinnin. Tällöin tunnistautumiseen pystytään lisäämään lisätunnistautuminen, joita Salesforcessa on useita vaihtoehtoja. Yleisimmät vaihtoehdot ovat JWT (JSON Web Token) ja Username-Password yhdistelmä. Avataan nämä tarkemmin seuraavaksi.
JWT
JSON Web Tokenia käytettäessä tarvitaan hieman lisäkonfiguraatioita aiemmin tehtyihin kohtiin. JWT:n käyttöön nimittäin vaaditaan sertifikaatti, kuten “Self-signed” -sertifikaatti. Sertifikaatin lataamiseksi Connected App:iin täytyy käydä lisäämässä “Use digital signatures” -asetus päälle. Tämän jälkeen sertifikaatin pystyy lataamaan tiedostona järjestelmään. Etsi sertifikaatti ja lataa se, jonka jälkeen näkymä on kuvan mukainen:
Mikäli tarvitset apua sertifikaatin luomisessa, olethan yhteydessä support@ceili.fi.
Tarkempia ohjeita ja tietoja löydät Salesforcen Help artikkeleista:
OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration
OAuth 2.0 Web Server Flow for Web App Integration
Username-Password
Käyttäjätunnuksen ja salasanan avulla tehtävä tunnistautuminen on toinen, joskaan ei niin suojaava tapa kuin JWT. Tähän ei tarvitse tehdä edellisen kaltaista konfigurointia Connected Appiin. Prosessi kulkee seuraavalla tavalla:
- Kutsutaan Salesforcen token endpointtia käyttäjän tunnuksien sekä järjestelmän key/secret arvoilla
Esimerkkikutsu:
https://exampleOrg.my.site.com/services/oauth2/token?
grant_type=password&
client_id=3MVG9k02hQhyUgQCLih5AmZkEfXu7rTCLmy9bQt89ZHaQVVvf5uxZgR6BTm1YuP3Vb7xkMgrL3ci7aEex4Ti9&
client_secret=E56DBDA01EE63B00C38BAC10736152F004CC4C34703D99DD9F2F8D4291320E3E&
username=integration@test.fi&
password=mypassword
- Kutsu palauttaa JSON vastauksen, jonka avulla saadaan Bearer token (access_token)
Esimerkkivastaus:
{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448832702",
"instance_url":" https://exampleOrg.my.site.com/",
"signature":"0CmxinZir53Yex7nE0TD+zMpvIWYGb/bdJh6XfOH6EQ=",
"access_token":"00Dx0000000BV7z!AR8AQAxo9UfVkh8AlV0Gomt9Czx9LjHnSSpwBMmbRcgKFmxOtvxjTrKW19ye6PE3Ds1eQz3z8jr3W7_VbWmEu4Q8TVGSTHxs",
"token_type":"Bearer"}
- Bearer token otetaan talteen kutsun vastauksesta, jonka jälkeen kutsuja voidaan tehdä Salesforce järjestelmään erilaisilla kutsuilla, sisällyttäen bearer token kutsuun.
Esimerkkikoodi Salesforcen rajapinnan kutsumiseen username/password tunnistautumisella käyttäen Javaa
Esimerkin tarkoituksena on havainnollistaa, kuinka toisesta järjestelmästä voi kutsua Salesforcen rajapintaa hakeakseen tietoja Salesforcesta. Luokka kutsuu Salesforcen rajapintaa ja hakee halutut tiedot järjestelmästä. Alla olevalla esimerkki queryllä haetaan kaikki Salesforcessa olevat Accountit, mutta queryä muuttamalla saataisiin haettua mitä tahansa tarvittavia tietoja Salesforcesta. Queryä voidaan myös rajata WHERE-lauseella.
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
public class SalesforceAPI {
// Replace with your instance URL
private static final String INSTANCE_URL = "https://yourInstance.salesforce.com";
/*
* This method sends a GET request to the Salesforce REST API to query for
* Account records. Can be used to query any object in Salesforce by changing
* query.
*/
public static void main(String[] args) throws Exception {
String ACCESS_TOKEN = SalesforceAuth.getAccessToken();
URI uri = new URI(INSTANCE_URL + "/services/data/v58.0/query?q=SELECT+Id,Name+FROM+Account");
URL url = uri.toURL();
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + ACCESS_TOKEN);
try {
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println("Response: " + response.toString());
// TODO: Make your necessary things with the received data. Data is in JSON
// format.
} catch (Exception e) {
System.out.println("Error: " + e.getMessage());
}
}
}
HUOM! Aiemmissa kohdissa olevat käyttäjäoikeudet tulee olla kunnossa, jotta tietoja voidaan hakea. Mikäli haettavan kentän tai objektin oikeudet puuttuvat queryn toteuttavalta käyttäjältä, päätyy koodi aina virheeseen.
Seuraavassa koodissa haetaan access token, jota tarvitaan edellisen koodin queryn toteuttamiseksi. Tokenin hakua kutsutaan yllä olevassa koodissa seuraavalla tavalla:
String ACCESS_TOKEN = SalesforceAuth.getAccessToken();
Acces tokenia haettaessa tulee määrittää (1.) käyttäjä, jolla tietoja haetaan, (2.) kohdeympäristö sekä (3.) ympäristön key/secret arvot, joiden haku löytyy ylempää tästä dokumentista. Myös Connected Appin oikeudet tulee olla asetettuna joko tarpeeksi avoimiksi tai valitulle käyttäjälle saataville, jotta access tokenin haku onnistuu.
import org.json.simple.JSONValue;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
import java.util.Map;
public class SalesforceAuth {
// Replace with your instance URL and credentials
private static final String TOKEN_URL = "https://yourInstance.salesforce.com/services/oauth2/token";
private static final String CLIENT_ID = "YOUR_CLIENT_ID";
private static final String CLIENT_SECRET = "YOUR_CLIENT_SECRET";
private static final String USERNAME = "YOUR_SALESFORCE_USERNAME";
private static final String PASSWORD = "YOUR_SALESFORCE_PASSWORD";
private static final String GRANT_TYPE = "password";
/*
* This method sends a POST request to the Salesforce OAuth2 token endpoint
* to get an access token.
*
* @return The access token as a string.
*/
public static String getAccessToken() throws Exception {
URI uri = new URI(TOKEN_URL);
URL url = uri.toURL();
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
String requestBody = "grant_type=" + GRANT_TYPE +
"&client_id=" + CLIENT_ID +
"&client_secret=" + CLIENT_SECRET +
"&username=" + USERNAME +
"&password=" + PASSWORD;
conn.setDoOutput(true);
OutputStream os = conn.getOutputStream();
os.write(requestBody.getBytes());
os.flush();
os.close();
InputStream is = conn.getInputStream();
BufferedReader rd = new BufferedReader(new InputStreamReader(is));
StringBuilder response = new StringBuilder();
String line;
while ((line = rd.readLine()) != null) {
response.append(line);
response.append('\r');
}
rd.close();
conn.disconnect();
Object jsonResponse = JSONValue.parse(response.toString());
Map responseMap = (Map) jsonResponse;
return responseMap.get("access_token").toString();
}
}
Lue lisää username/password skenaarioista Salesforcen Help artikkelista: OAuth 2.0 Username-Password Flow for Special Scenarios
Tämä on pääpiirteisesti suuntaa antava ohjeistus erilaisiin Salesforce integraatioskenaarioihin ja tärkeimpiin aihealueisiin integraatioihin liittyen. Jos kaipaat apua REST API:n tai integraatiokäyttäjän asetusten kanssa omassa käyttötapauksessasi, Ceili auttaa mielellään.
Kirjoittaja:
Atte Komppa
Salesforce Developer
Lue lisää Salesforcen mahdollisuuksista
UN Women Suomi kehittää varainhankintaansa Salesforcessa Ceilin kanssa
YK:n tasa-arvojärjestö UN Women on maailman johtava naisten ja tyttöjen ihmisoikeuksia ajava järjestö, jonka tavoitteena on maailma, jossa on yhtäläiset oikeudet ja mahdollisuudet kaikille. Yli
Tekoälyblogisarja: Salesforce Agentforce avuksi arjen työhön
Tekoäly on puhututtanut jo jonkin aikaa ja nyt se alkaa olla osa yhä useamman arkipäivää. Mutta miten tekoälyä voi hyödyntää Salesforcessa? Olemme koostaneet Tekoälyblogisarjan, joka
Ceilin Winter ’25 Release -tiedote
Saatesanat Tässä on perinteinen Ceilin koostama yhteenveto Salesforcen Winter ’25 Releasen tulevista uusista ominaisuuksista ja muutoksista. Salesforce julkaisee kolme kertaa vuodessa päivityspaketin, joka pitää sisällään
Salesforce®, Sales Cloud® ja muut ovat salesforce.com, inc:n tavaramerkkejä, joita käytetään täällä luvan kanssa.
Haluatko tietää lisää Salesforcen mahdollisuuksista?
Ota yhteyttä, niin räätälöidään teille sopiva tarjous tarpeidenne pohjalta.
Jos tarjouspyynnössäsi on liitteitä, voit ottaa lomakkeen sijaan yhteyttä osoitteeseen info@ceili.fi