HostFact Help
HostFact Help > Eigen diensttypes
Voorbeeld integratie eigen diensttype: Microsoft 365 via PAX8
In dit help artikel leggen we uit op wat voor manier u een integratie kunt opzetten voor uw eigen diensttypes. Als voorbeeld hiervoor gaan we een integratie opzetten om Microsoft 365 abonnementen te kunnen aanvragen en opzetten via cloudmarktplaats PAX8.
Stappenplan
Voor het aanmaken van een eigen diensttype met een integratie kan je het volgende stappenplan volgen. Voordat je een integratie gaat opzetten wil je in principe al gekeken hebben naar de API documentatie van de dienst die je gaat integreren. Hierdoor weet je welke API calls er benodigd gaan zijn en wat voor velden hierin moeten worden meegegeven die je eventueel binnen de backoffice als product of dienstvelden moet gaat aanmaken. Voor het specifieke voorbeeld van Microsoft 365 via PAX8 staan deze stappen hieronder uitgelegd en is dit vooronderzoek dus niet noodzakelijk.
1. Aanmaken diensttype in de backoffice
Allereerst dient de module voor eigen diensttypes te worden geactiveerd en gaan we een diensttype aanmaken voor deze integratie. Deze stappen worden uitgelegd in help artikel Gebruik maken van een eigen diensttype.
Als naam geven we hierbij "Microsoft 365" op en bij de instellingen vinken we "Integratie met webhooks" en "Aantal" aan.
2. Productvelden toevoegen
Wanneer we een Microsoft 365 abonnement gaan aanvragen via de API van PAX8 hebben we hiervoor het product id nodig van binnen de PAX8 omgeving. Om dit product id bij de Microsoft 365 producten te kunnen opslaan gaan we een eigen veld aanmaken voor producten bij dit diensttype.
U gaat hiervoor in het menu naar "Instellingen" -> "HostFact voorkeuren" -> "eigen velden".
Als veldnaam gebruiken we "Extern ID" en als veldcode "EXTERNALID". Let op dat deze veldcode gelijk dient te zijn wanneer u het voorbeeld webhookbestand wilt gaan gebruiken!
Bij "Veld toepassen voor" kiest u voor "Producten" en "Gebruiken bij" dient op "Microsoft 365" te staan, zie onderstaand screenshot.
3. Dienstvelden toevoegen
Op het niveau van diensten kunnen ook velden worden toegevoegd aan een diensttype. Deze velden gaan voor iedere individuele dienst afzonderlijk worden ingevuld, in tegenstelling tot de productvelden die op productniveau worden beheerd.
Voor Microsoft 365 zijn er meerdere velden die moeten worden meegeven bij een aanmaken van een dienst via PAX8.
Deze velden zijn onderdeel van de zogenoemde "provisioning details" en kunnen via de PAX8 API worden opgevraagd bij een specifiek product: https://devx.pax8.com/reference/findprovisiondetailsbyproductid.
Voor de Microsoft 365 integratie gaan we hiervoor de volgende eigen velden toevoegen. U gaat voor ieder veld weer naar "Instellingen" -> "HostFact voorkeuren" -> "eigen velden". Bij "Veld toepassen voor" kiest u nu voor "Diensten" en "Gebruiken bij" dient weer op "Microsoft 365" te staan. De veldnamen kunt u naar eigen wens aanpassen, de veldcode dient wel zoals onderstaand te worden overgenomen.
De eigen velden in het overzicht dienen nu gelijk te zijn aan degene in het onderstaande screenshot.
4. Debiteur velden toevoegen
Het kan zijn dat uw debiteur ook dient te worden aangemaakt bij de externe partij waarmee u integreert. Bij PAX8 is dit ook het geval en dient er eerst een "Company" te worden aangemaakt voor de betreffende debiteur binnen de PAX8 omgeving voordat er een MS365 abonnement kan worden besteld.
De externe identifier van de "company" vanuit PAX8 willen we opslaan bij de debiteur. Hiervoor dienen we ook een eigen veld aan te maken op het niveau van een debiteur. U gaat hiervoor weer naar "Instellingen" -> "HostFact voorkeuren" -> "eigen velden". Als veldnaam vullen we "PAX8 Company ID" in met veldcode "PAX8COMPANY". Bij "veld toepassen voor" laat u het staan op "Algemeen" en vervolgens vinkt u "debiteur" aan onder "Gebruiken bij".
5. Producten toevoegen
We kunnen nu de Microsoft 365 producten gaan toevoegen die u wilt aanbieden.Ga hiervoor in het menu naar "Beheer" -> "Productbeheer" -> "Product toevoegen".
Als type product kiest u voor "Microsoft 365". Aan de rechter zijde van uw scherm komt nu het eigen veld te staan dat we eerder hebben aangemaakt met "Extern ID".
Hierin dienen we de identifier vanuit PAX8 in te vullen voor het MS365 product dat u wilt aanbieden. Deze identifiers zijn te vinden door in uw PAX8 omgeving in te loggen en via "Catalog" te zoeken naar de producten. Voor het PAX8 product "Microsoft 365 Business Standard [New Commerce Experience]" is het id bijvoorbeeld "9e8ff14a-a4ae-441a-af3d-9b23b3ab01be". Je kan deze identifier zien in onderstaand screenshot in het rood gearceerde blok.
Voeg ieder MS365 product dat u via de integratie met PAX8 wilt aanbieden als los product toe.
6. Webhook bestanden
Voor de daadwerkelijke integratie zijn er nog webhooks nodig die de acties uitvoeren zoals het aanmaken en opzeggen van de abonnementen via de API van PAX8.
De voorbeeldintegratie kunt u hier downloaden: https://www.hostfact.nl/downloads/cst_ms365_pax8.zip.
Plaats het bestand "hooks.cst1.php" in de map "Pro/includes". Zowel in de bestandsnaam als in de namespace op regel 3 dient het ID van de eigen diensttype te worden opgegeven. Dit ID is zichtbaar in de URL op de diensttype bewerken pagina binnen de backoffice.
Wanneer het de eerste diensttype is die u toevoegd zal dit ID 1 zijn en hoeft u dit dus niet aan te passen.
Op regel 4 en 5 dienen ook de API credentials voor PAX8 te worden ingevoerd. Deze kunt u aanmaken binnen de PAX8 omgeving onder "Users". Selecteer hier de gebruiker onder wie u de API gegevens wilt aanmaken aan ga vervolgens naar tabblad "Integrations".
In dit help artikel leggen we uit op wat voor manier u een integratie kunt opzetten voor uw eigen diensttypes. Als voorbeeld hiervoor gaan we een integratie opzetten om Microsoft 365 abonnementen te kunnen aanvragen en opzetten via cloudmarktplaats PAX8.
Stappenplan
Voor het aanmaken van een eigen diensttype met een integratie kan je het volgende stappenplan volgen. Voordat je een integratie gaat opzetten wil je in principe al gekeken hebben naar de API documentatie van de dienst die je gaat integreren. Hierdoor weet je welke API calls er benodigd gaan zijn en wat voor velden hierin moeten worden meegegeven die je eventueel binnen de backoffice als product of dienstvelden moet gaat aanmaken. Voor het specifieke voorbeeld van Microsoft 365 via PAX8 staan deze stappen hieronder uitgelegd en is dit vooronderzoek dus niet noodzakelijk.
- Aanmaken diensttype in de backoffice
- Productvelden toevoegen
- Dienstvelden toevoegen
- Optioneel: Debiteur velden toevoegen
- Producten toevoegen
- Webhook bestand
- Optioneel: Bestelformulier configureren
1. Aanmaken diensttype in de backoffice
Allereerst dient de module voor eigen diensttypes te worden geactiveerd en gaan we een diensttype aanmaken voor deze integratie. Deze stappen worden uitgelegd in help artikel Gebruik maken van een eigen diensttype.
Als naam geven we hierbij "Microsoft 365" op en bij de instellingen vinken we "Integratie met webhooks" en "Aantal" aan.
2. Productvelden toevoegen
Wanneer we een Microsoft 365 abonnement gaan aanvragen via de API van PAX8 hebben we hiervoor het product id nodig van binnen de PAX8 omgeving. Om dit product id bij de Microsoft 365 producten te kunnen opslaan gaan we een eigen veld aanmaken voor producten bij dit diensttype.
U gaat hiervoor in het menu naar "Instellingen" -> "HostFact voorkeuren" -> "eigen velden".
Als veldnaam gebruiken we "Extern ID" en als veldcode "EXTERNALID". Let op dat deze veldcode gelijk dient te zijn wanneer u het voorbeeld webhookbestand wilt gaan gebruiken!
Bij "Veld toepassen voor" kiest u voor "Producten" en "Gebruiken bij" dient op "Microsoft 365" te staan, zie onderstaand screenshot.
3. Dienstvelden toevoegen
Op het niveau van diensten kunnen ook velden worden toegevoegd aan een diensttype. Deze velden gaan voor iedere individuele dienst afzonderlijk worden ingevuld, in tegenstelling tot de productvelden die op productniveau worden beheerd.
Voor Microsoft 365 zijn er meerdere velden die moeten worden meegeven bij een aanmaken van een dienst via PAX8.
Deze velden zijn onderdeel van de zogenoemde "provisioning details" en kunnen via de PAX8 API worden opgevraagd bij een specifiek product: https://devx.pax8.com/reference/findprovisiondetailsbyproductid.
Voor de Microsoft 365 integratie gaan we hiervoor de volgende eigen velden toevoegen. U gaat voor ieder veld weer naar "Instellingen" -> "HostFact voorkeuren" -> "eigen velden". Bij "Veld toepassen voor" kiest u nu voor "Diensten" en "Gebruiken bij" dient weer op "Microsoft 365" te staan. De veldnamen kunt u naar eigen wens aanpassen, de veldcode dient wel zoals onderstaand te worden overgenomen.
- Veldnaam "Klant heeft bestaand Microsoft account" met veldcode "msCustExists". Als type kan er worden gekozen voor radiobuttons of een selectieveld. Hierbij voegt u de optie met waarde "No, the customer does not have a Microsoft account" en omschrijving "Geen bestaand Microsoft account". De tweede optie heeft waarde "Yes, the customer has and can log into their Microsoft account" en omschrijving "Wel bestaand Microsoft account".
- Veldnaam "Onmicrosoft domein prefix" met veldcode "msDomain".
- Veldnaam "Microsoft Customer Tenant ID" met veldcode "msTenantId".
- Veldnaam "Datum akkoord" met veldcode "mca2020EffectiveDate". Het type van dit veld is "datum".
- Naast bovengenoemde velden zijn er ook nog de contact voornaam/achternaam/e-mailadres en MCA voornaam/achternaam/e-mailadres. Indien gewenst kunnen deze ook op dienstniveau worden toegevoegd, het alternatief is om deze gegevens altijd vanuit de debiteur te gebruiken.
De eigen velden in het overzicht dienen nu gelijk te zijn aan degene in het onderstaande screenshot.
4. Debiteur velden toevoegen
Het kan zijn dat uw debiteur ook dient te worden aangemaakt bij de externe partij waarmee u integreert. Bij PAX8 is dit ook het geval en dient er eerst een "Company" te worden aangemaakt voor de betreffende debiteur binnen de PAX8 omgeving voordat er een MS365 abonnement kan worden besteld.
De externe identifier van de "company" vanuit PAX8 willen we opslaan bij de debiteur. Hiervoor dienen we ook een eigen veld aan te maken op het niveau van een debiteur. U gaat hiervoor weer naar "Instellingen" -> "HostFact voorkeuren" -> "eigen velden". Als veldnaam vullen we "PAX8 Company ID" in met veldcode "PAX8COMPANY". Bij "veld toepassen voor" laat u het staan op "Algemeen" en vervolgens vinkt u "debiteur" aan onder "Gebruiken bij".
5. Producten toevoegen
We kunnen nu de Microsoft 365 producten gaan toevoegen die u wilt aanbieden.Ga hiervoor in het menu naar "Beheer" -> "Productbeheer" -> "Product toevoegen".
Als type product kiest u voor "Microsoft 365". Aan de rechter zijde van uw scherm komt nu het eigen veld te staan dat we eerder hebben aangemaakt met "Extern ID".
Hierin dienen we de identifier vanuit PAX8 in te vullen voor het MS365 product dat u wilt aanbieden. Deze identifiers zijn te vinden door in uw PAX8 omgeving in te loggen en via "Catalog" te zoeken naar de producten. Voor het PAX8 product "Microsoft 365 Business Standard [New Commerce Experience]" is het id bijvoorbeeld "9e8ff14a-a4ae-441a-af3d-9b23b3ab01be". Je kan deze identifier zien in onderstaand screenshot in het rood gearceerde blok.
Voeg ieder MS365 product dat u via de integratie met PAX8 wilt aanbieden als los product toe.
6. Webhook bestanden
Voor de daadwerkelijke integratie zijn er nog webhooks nodig die de acties uitvoeren zoals het aanmaken en opzeggen van de abonnementen via de API van PAX8.
De voorbeeldintegratie kunt u hier downloaden: https://www.hostfact.nl/downloads/cst_ms365_pax8.zip.
Plaats het bestand "hooks.cst1.php" in de map "Pro/includes". Zowel in de bestandsnaam als in de namespace op regel 3 dient het ID van de eigen diensttype te worden opgegeven. Dit ID is zichtbaar in de URL op de diensttype bewerken pagina binnen de backoffice.
Wanneer het de eerste diensttype is die u toevoegd zal dit ID 1 zijn en hoeft u dit dus niet aan te passen.
Op regel 4 en 5 dienen ook de API credentials voor PAX8 te worden ingevoerd. Deze kunt u aanmaken binnen de PAX8 omgeving onder "Users". Selecteer hier de gebruiker onder wie u de API gegevens wilt aanmaken aan ga vervolgens naar tabblad "Integrations".