Dynamics 365:n tekninen integraatio-opas
Dynamics- ja Entra-ylläpitäjille, tietoturva-arvioijille ja IT:lle — molemmat todennustavat, tarvittavat Dataverse-oikeudet, API-kulutus, virhetilanteet ja auditointi.
Tämä opas kuvaa, mitä Revial tekee Dynamics 365 -ympäristössäsi, jotta voit hyväksyä, määrittää ja myöhemmin auditoida integraation. Yhdistäminen vaihe vaiheelta: Yhdistetään Revial Microsoft Dynamics 365:een. Jokainen luettava ja kirjoitettava sarake: Mitä Revial synkronoi Microsoft Dynamics 365:n kanssa.
1. Mitä hyväksyt
Revial yhdistyy Dataverse Web API v9.2:een jommallakummalla tavalla:
| Ominaisuus | Microsoft-kirjautuminen (delegoitu) | Palvelutili (vain sovellus) |
|---|---|---|
| Identiteetti | Kirjautuva Dynamics-käyttäjä | Oman sovellusrekisteröintisi sovelluskäyttäjä |
| Protokolla | OAuth 2.0 -valtuutuskoodi (Azure AD v1, resource = instanssisi) | OAuth 2.0 client credentials (v2, scope {instance}/.default) |
| Sovellusrekisteröinti | Revialin | Sinun, yhden vuokraajan, client secretillä |
| Entra-suostumus | Riippuu vuokraajasi käyttäjäsuostumuskäytännöstä | Ei tarvita — sovellus ei tarvitse API-käyttöoikeuksia |
| Dynamicsin ylläpito-oikeudet | Ei tarvita | Ei tarvita |
Kummassakin tapauksessa identiteetin Dataverse-suojausroolit ovat ainoa raja sille, mitä Revial voi nähdä ja muuttaa. Conditional Access koskee interaktiivista kirjautumista.
2. Mitä ylläpitäjäsi tarvitsee tehdä
| Tilanne | Mitä tehdä |
|---|---|
| Käyttäjät näkevät "Need admin approval" | Anna Revialille ylläpitäjän suostumus Entrassa (delegoitu tapa) |
| Et halua käyttäjätiliä mukaan | Luo sovellusrekisteröinti, client secret ja sovelluskäyttäjä (vain sovellus -tapa) |
| Haluat vähimmät oikeudet | Luo mukautettu suojausrooli luvun 4 mukaisesti |
| Haluat Revialin kirjoittavan sarakkeisiin | Myönnä Write-oikeus ja mäppää sarakkeet Revialissa |
| Haluat tapaamisia tai mukautetun tapaamistietueen | Sovi määrityksestä Revialin kanssa (luku 6) |
Tuotavaa ratkaisua tai rekisteröitävää plug-inia ei ole.
3. Todennus ja tunnistemalli
Delegoitu tapa
| Ominaisuus | Arvo |
|---|---|
| Valtuutuspäätepiste | https://login.microsoftonline.com/{tenant}/oauth2/authorize, resource={instance} ja prompt=select_account |
| Tunnistepäätepiste | https://login.microsoftonline.com/{tenant}/oauth2/token |
| PKCE | Ei käytössä |
| Tarkistus yhdistämisen jälkeen | WhoAmI, sitten käyttäjän systemuserid, internalemailaddress ja fullname |
| Päivitys | Kun jäljellä on alle 35 minuuttia; enintään kolme yritystä viiveellä; kierrätetty päivitystunniste tallennetaan |
Vain sovellus -tapa
| Ominaisuus | Arvo |
|---|---|
| Tunnistepäätepiste | https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token, grant_type=client_credentials |
| Vuokraaja | Directory (tenant) ID GUID-muodossa — common ei kelpaa |
| Päivitystunniste | Ei ole — uusi pääsytunniste haetaan tarvittaessa |
| Tarkistus yhdistämisen jälkeen | Tunniste haetaan ja WhoAmI onnistuu ennen kuin mitään tallennetaan |
Instanssin URL. Osoitteen on oltava HTTPS ja muotoa yourorg.crmN.dynamics.com; polut, kyselymerkkijonot ja lopun kauttaviivat poistetaan. Datakutsut menevät vastaavaan osoitteeseen yourorg.api.crmN.dynamics.com/api/data/v9.2.
Säilytys. Pääsy- ja päivitystunnisteet sekä vain sovellus -tavan client secret salataan levossa (AES-256-GCM). Client ID ja tenant ID tallennetaan selväkielisinä.
Virheet. Delegoidussa tavassa 401 tai invalid_grant merkitsee yhteyden uudelleentodennusta vaativaksi ja ilmoittaa organisaation ylläpitäjälle ("CRM: Authentication expired"). Vain sovellus -tavassa virheellinen tai vanhentunut secret tuottaa ilmoituksen "CRM: App credential invalid" — se korjataan Entrassa, ei yhdistämällä uudelleen.
Kuka voi yhdistää Revialin puolella. Organisaation omistaja tai ylläpitäjä tilauksella, joka sisältää CRM-integraation; pyyntömäärää rajoitetaan; kertakäyttöinen state, voimassa viisi minuuttia. Yksi Dynamics-yhteys organisaatiota kohden; muita CRM-järjestelmiä voi yhdistää rinnalle.
4. Tarvittavat Dataverse-oikeudet
| Revialin tarvitsee… | Oikeus |
|---|---|
| Synkronoida asiakkaat, kontaktit, liidit, myyntimahdollisuudet | Read |
| Lukea myyntiprosessin vaiheet | Read (process stage ja opportunity sales process) |
| Hakea yhdistävä käyttäjä ja myyjät sähköpostin perusteella | Read (system user, organisaatiotaso) |
| Kirjoittaa tapaamisten muistiinpanot | Create (annotation); Append / Append To liitettäviin tauluihin |
| Luoda tapaamisia (jos käytössä) | Create (appointment); Assign (omistajaksi asetetaan myyjä) |
| Kirjoittaa mäpättyihin sarakkeisiin | Write kyseisten sarakkeiden tauluihin |
| Mukautetut tapaamistietueet (jos määritetty) | Create ja Write kyseiseen tauluun |
| Poistaa mitään, ylläpitää | Ei tarvita |
Puuttuvia oikeuksia ei ohiteta. Puuttuva lukuoikeus asiakkaisiin, kontakteihin, liideihin tai myyntimahdollisuuksiin pysäyttää synkronoinnin kyseiseen tauluun; seuraava ajo yrittää uudelleen. Virhe vaiheiden lukemisessa merkitsee synkronoinnin osittaiseksi ja jatkaa.
5. Mitä Revial lukee ja kirjoittaa
Lukee: asiakkaat (vain aktiiviset), kontaktit, liidit, myyntimahdollisuudet ja yhden myyntiprosessin vaiheet eksplisiittisillä $select-listoilla. Aktiviteetteja ja muistiinpanoja ei synkronoida. Synkronoinnin ulkopuolella: WhoAmI ja järjestelmäkäyttäjät, tapaamisen alkamisajan lähellä olevat tapaamiset (vain tapaamistoiminnoissa), sarakkeiden nykyiset arvot ennen kirjoitusta ja sarakkeiden metadata mäppäysnäkymää varten.
Kirjoittaa:
| Toiminto | Tiedot |
|---|---|
| Tapaamisen yhteenveto | Luo annotation (subject, notetext) tunnistettuun myyntimahdollisuuteen, asiakkaaseen tai kontaktiin |
| Tapaaminen (valinnainen) | Luo appointment, omistajana myyjä ja osallistujineen; ei koskaan merkitä valmiiksi |
| Olemassa oleva tapaaminen / mukautettu tietue (valinnainen) | Päivittää määritetyt sarakkeet korvaten niiden sisällön; voi luoda linkitetyn tietueen |
| Mäpätyt sarakkeet | Päivittää tunnistetun kontaktin, asiakkaan tai myyntimahdollisuuden |
Revial ei koskaan poista mitään, ei luo asiakkaita, kontakteja tai myyntimahdollisuuksia eikä sulje myyntimahdollisuuksia.
6. Kenttien mäppäykset ja määritykset
Kirjoitusmäppäykset ovat organisaation ylläpitäjien itse määritettävissä kohdassa Organisaatio → CRM-asetukset → Ominaisuuksien yhdistäminen: PATCH-erä, sitten sarakekohtainen uudelleenyritys; olemassa olevat arvot säilyvät, ellei mäppäys ylikirjoita.
Lukumäppäykset (synkronointiin lisättävät sarakkeet) sekä tapaamis- tai mukautetun tapaamistietueen määritykset tekee Revial organisaatiollesi. Mukautetussa tapaamistietueessa Revial tunnistaa tapaamisen oletuksena ±30 minuutin sisältä tapaamisen alkamisesta. Virheellinen määritys käsitellään kuin sitä ei olisi.
7. Synkronoinnin tahti ja API-kulutus
- Tahti: noin tunnin välein, alkaen heti yhdistämisen jälkeen (paitsi Revialin henkilökunnan määrittämät palvelutilit, jotka odottavat seuraavaa tunnin välein tapahtuvaa ajoa).
- Muutosten seuranta: Revial käyttää Dataversen muutosten seurantaa (
Prefer: odata.track-changes) ensimmäisestä synkronoinnista alkaen, tallentaa delta-linkin tauluittain ja saa poistot poistettuina riveinä. Muutosten seurannan on oltava käytössä synkronoitavissa tauluissa; muuten synkronointi pysähtyy kyseiseen tauluun. - Järjestys: asiakkaat → kontaktit → liidit → vaiheet → myyntimahdollisuudet.
- Määrä: Dataversen oletussivukoko, 5 sivua ajoa kohden automaattisella jatkolla ja enintään 50 000 tietuetta hakua kohden.
- Aikakatkaisut: 50 sekuntia pyyntöä kohden.
- Service protection -rajat: Revial ei hidasta HTTP 429 -vastauksella; epäonnistunut pyyntö kaataa ajon, jonka työjono yrittää uudelleen.
8. Tapaamisten yhdistäminen CRM-tietueisiin
Ensimmäinen osuma voittaa: tapaamisen suorat tunnukset; avoin myyntimahdollisuus, johon tapaaminen on jo linkitetty; osallistujien sähköpostit → kontaktit → niiden myyntimahdollisuudet (pisteytettyinä); asiakas verkkosivun tai sähköpostin verkkotunnuksen perusteella; asiakas nimen perusteella. Pisteytys suosii avoimia myyntimahdollisuuksia, osallistujaa ensisijaisena kontaktina, otsikon samankaltaisuutta, pidemmälle edenneitä vaiheita ja tuoreutta. Suljetut myyntimahdollisuudet jätetään pois; ilmaisten sähköpostipalveluiden verkkotunnukset ohitetaan asiakastunnistuksessa.
9. Tietoturva, rajat ja virhetilanteet
- Vähimmät oikeudet: ei Dynamicsin ylläpito-oikeuksia; mukautettua roolia tuetaan.
- Salaisuudet: tunnisteet ja client secret salattu levossa; ei koskaan lähetetä selaimeen.
- Kyselyjen turvallisuus: OData-suodattimien merkkijonot escapetaan.
- Virheiden käsittely: tallennetuissa virheissä säilytetään vain HTTP-tila ja Dataversen virhekoodi, ei tietueiden sisältöä.
- Datan säilytys: synkronoidut rivit ja raa'at API-vastaukset tallennetaan Revialiin ja poistetaan, kun katkaiset yhteyden.
10. Auditointi ja yhteyden katkaiseminen
Näin näet, mitä Revial on tehnyt: Entran kirjautumislokit yhdistävälle käyttäjälle tai palveluperiaatteelle; Dataversen auditointi (jos käytössä) kohdistaa muutokset yhdistävälle identiteetille; Revialin luomien muistiinpanojen ja tapaamisten luojana näkyy kyseinen identiteetti.
Yhteyden katkaiseminen:
- Revialissa — Katkaise yhteys kortissa. Revial poistaa synkronoidun kopionsa, kenttien mäppäykset ja tallennetut tunnisteet tai secretin. Se ei peruuta mitään Microsoftin puolella.
- Delegoitu — poista Revialin yrityssovellus Entrasta tai poista se käytöstä, tai peruuta käyttäjän istunnot.
- Vain sovellus — poista client secret, poista sovelluskäyttäjä käytöstä tai poista sen suojausrooli.
Revialin jo kirjoittamat tietueet jäävät Dynamicsiin.
11. Vianmääritys
| Oire | Todennäköinen syy | Korjaus |
|---|---|---|
| "Need admin approval" | Vuokraaja estää käyttäjien suostumuksen | Anna ylläpitäjän suostumus Entrassa |
| "Failed to validate Dynamics 365 access" | Ei Dataverse-roolia tai lisenssiä | Liitä käyttäjälle suojausrooli |
| "Could not authenticate with these credentials…" | Väärä client ID, secret tai tenant, tai sovelluskäyttäjä puuttuu | Tarkista sovellusrekisteröinti ja sovelluskäyttäjä |
| Synkronointi pysähtyy yhteen tauluun | Read-oikeus puuttuu tai muutosten seuranta ei ole käytössä | Myönnä Read / ota muutosten seuranta käyttöön |
| "CRM: App credential invalid" | Client secret vanheni | Luo uusi secret; katkaise yhteys ja yhdistä uudelleen |
| Asetukset katosivat uudelleen yhdistämisen jälkeen | Uudelleen yhdistäminen nollaa yhteyden asetukset | Pyydä Revialia palauttamaan tapaamis- tai lukumääritykset |
| Poistettu asiakas näkyy yhä | Asiakas poistettiin käytöstä, ei poistettu | Odotettua — käytöstä poistetut asiakkaat säilyttävät viimeiset arvonsa |
Mitä Revial synkronoi Microsoft Dynamics 365:n kanssa
Dynamics-ylläpitäjällesi ja sille, joka arvioi integraation tietojen käyttöoikeudet — jokainen Dataverse-sarake, jonka Revial lukee, kaikki mitä se kirjoittaa takaisin ja tunnetut puutteet.
Yhdistetään Revial Odooseen
Odoo-API-avaimen luominen, Odoo-instanssin yhdistäminen Revialiin ja mitä tehdä, kun yhteys epäonnistuu.