- 1. Algemeen
- 2. Typen
Info
Dit artikel biedt achtergrondinformatie over het concept ‘API-connector’ en moet worden gelezen in de context van het instellen van een integratie met een van de andere Spacewell-producten (bijv. Workplace Experience of Workplace Analytics).
1. Algemeen
Een API-connector in Asset is een object dat wordt gebruikt om de verbinding met een extern systeem te configureren en te bewaken. De connector zorgt ervoor dat het externe systeem toegang heeft tot de Asset-omgeving om relevante gegevens op te halen en, indien van toepassing, invoer te leveren. Daarnaast maakt de API-connector het voor de Asset-omgeving mogelijk om met het externe systeem te communiceren.
Het menu Integraties op het startboard van de beheerder biedt een centrale locatie voor het beheren van bestaande integraties. Deze landingspagina biedt toegang tot de meest relevante configuratie- en beheeropties met betrekking tot integraties.
De landingspagina biedt via een knop die naar de knowledgebase verwijst toegang tot aanvullende informatie over integraties. De pagina bevat ook de optie ‘Module activeren’, waarmee aanvullende integraties kunnen worden geactiveerd naast de integraties die al zijn ingeschakeld.
In de sectie ‘Actieve integraties’ wordt voor elke geactiveerde integratie een knop weergegeven, die snel toegang biedt tot de configuratie- en beheeropties.
Ten slotte biedt de landingspagina ook toegang tot andere integratiegerelateerde instellingen en overzichten, zoals Aangepaste webservices, Toegangsregels en het zoeken in het gebeurtenissenlogboek.
Door een van de knoppen voor geactiveerde integraties te selecteren, wordt de integratiespecifieke landingspagina geopend. Deze pagina biedt toegang tot de configuratie- en beheeropties voor de geselecteerde integratie.
Vanuit het overzicht van API-connectors kunt u de bijbehorende API-connector openen door de betreffende knop te selecteren. Als een integratie meerdere API-connectors bevat, worden alle beschikbare connectors weergegeven, zodat u de juiste connector kunt selecteren.
Alle geconfigureerde API-connectors voor een tenant zijn ook te vinden via:
Clientinstellingen → Verificatie → Page include ‘API-connectors’.
API-connectors worden ook gebruikt bij het instellen van integraties tussen Spacewell-producten (bijv. Workplace Experience en Workplace Analytics). Het grootste deel van de configuratie wordt geautomatiseerd tijdens de relevante stappen voor het activeren van modules. Voor bepaalde stappen kunnen echter handmatige acties nodig zijn. Inzicht in de details van de API-connector kan nuttig zijn voor foutopsporing.
In de volgende secties worden de algemene instellingen en opties voor alle API-connectors uitgebreid toegelicht. Ook worden specifieke details besproken voor de API-connectors die worden gebruikt met native Spacewell-producten.
1.1 Vertrouwensrelatie
Elke API-connector bevat een vertrouwensrelatie, die wordt gebruikt om de verificatie te configureren die nodig is voor toegang tot de Asset-omgeving via de API-connector. Het verificatietype wordt automatisch bepaald op basis van het type API-connector en wordt ingesteld binnen de vertrouwensrelatie.
Verificatietypen kunnen variëren en omvatten mogelijk:
- Gebruikersnaam/wachtwoord
- Tweerichtings-SSL-certificaat
- Geheime sleutel
Afhankelijk van het gekozen verificatietype moeten gegevens, zoals een gebruikersnaam/wachtwoord of een toegangs-ID/sleutel, met het externe systeem worden gedeeld om toegang tot de API-connector mogelijk te maken. Meer informatie hierover vindt u via de relevante moduleactivering.
Info
Via de verschillende van toepassing zijnde moduleactiveringen wordt automatisch een speciale gebruiker ‘Spacewell Integration’ aangemaakt en/of gekoppeld aan de vertrouwensrelaties als de standaard geautoriseerde systeemgebruiker.
Opmerking
Belangrijk: Zorg ervoor dat de aan de vertrouwensrelatie gekoppelde geautoriseerde systeemgebruiker een actieve gebruiker is met beheerderstoegang. Deze gebruiker wordt automatisch gebruikt om beheeracties uit te voeren via de API-connector. Als de gebruiker inactief is of niet over de vereiste machtigingen beschikt (bijvoorbeeld om specifieke stamgegevens op te halen), werkt de integratie niet correct.
Opmerking
De toegangs-ID van de vertrouwensrelatie voor de Workplace Experience API-connector is een unieke, gegenereerde referentie en kan niet (meer) worden bewerkt. Hierdoor blijft elke vertrouwensrelatie uniek, ook als een klant meerdere API-connectors gebruikt op meerdere servers (bijv. productie en test).
1.2 Bedieningsmodus
De bedieningsmodus van een API-connector geeft aan vanaf welke server de app toegankelijk is. De beschikbare bedieningsmodi zijn:
- Productie
- Back-up
- Test
- Ontwikkeling
Deze modi komen overeen met de servers van de Asset-omgeving (bijv. axpr, axbk, axts, enzovoort, afhankelijk van clusters en servers).
Als de bedieningsmodus bijvoorbeeld is ingesteld op Productie, is de API-connector voor het externe systeem niet toegankelijk via de back-up- of testservers. De geselecteerde bedieningsmodus zorgt ervoor dat de toegankelijkheid van de app overeenkomt met de bedoelde serveromgeving.
Opmerking
Belangrijk: Als de bedieningsmodus leeg wordt gelaten, is de API-connector toegankelijk op alle servers zodra deze is gesynchroniseerd (dagelijks voor de back-upserver en elke 6–8 weken voor de testserver). Dit moet echter koste wat kost worden voorkomen, omdat dit problemen kan veroorzaken. Testen op een back-up- of testserver kan bijvoorbeeld onbedoeld gegevens naar de productieserver van het externe systeem sturen als de bedieningsmodus niet is opgegeven.
1.3 Ingebruikname
De ingebruikname van een API-connector bepaalt de status ervan (actief of inactief) en de richting waarin deze toegankelijk is. De beschikbare opties voor ingebruikname zijn:
- Actief: de API-connector is volledig functioneel en toegankelijk.
- Gedeactiveerd: de API-connector is inactief en ontoegankelijk, ook als de geheime sleutel nog door het externe systeem wordt gebruikt.
- Inkomend toegestaan: de API-connector staat alleen inkomende verbindingen toe.
- Uitgaand toegestaan: de API-connector staat alleen uitgaande verbindingen toe.
Standaard moet de ingebruikname van de API-connector worden ingesteld op Actief. Als de app niet langer wordt gebruikt, moet deze worden ingesteld op Gedeactiveerd om ervoor te zorgen dat deze niet langer toegankelijk is.
In gevallen waarin de API-connector in een unidirectionele modus moet werken (bijv. alleen inkomend of uitgaand), kan de juiste optie worden geselecteerd. Dergelijke configuraties zijn echter niet-standaard en worden beschouwd als aanpassingen.
Verdere configuratieopties voor de API-connector zijn afhankelijk van het type. Details over verschillende apptypen worden in het volgende hoofdstuk besproken.
2. Typen
Bij het maken van een API-connector bepaalt de categorie het type van de app. Het type bepaalt welke specifieke opties en instellingen relevant zijn voor het externe systeem waarmee de app communiceert. Standaard zijn de volgende categorieën/typen beschikbaar:
- Workplace Experience
- Analytics
- Agenda-integratie
- GoCanvas
- SCIM
Daarnaast is het mogelijk om een API-connector in de standaardcategorie te maken door in het overzicht van API-connectors op de knop ‘Nieuw’ te klikken. Deze optie is nuttig voor het instellen van een API-connector voor verificatiedoeleinden als onderdeel van een aangepaste integratie.
Naast de eerder genoemde algemene configuraties van API-connectors heeft elk van de drie standaardtypen aanvullende, typespecifieke configuraties en opties. Deze worden in de volgende hoofdstukken uitgebreid toegelicht.
2.1 Workplace Experience
Het type API-connector Workplace Experience is ontworpen om de Asset-omgeving beschikbaar te stellen aan Workplace Experience-touchpoints, zoals de Workplace-app, Go, roomdisplays, kiosken en vloerschermen.
Met deze integratie kan Workplace Experience relevante gegevens ophalen, waaronder gebruikersinformatie, reserveringsgegevens en reserveerbare objecten. Reserveringen of bezoekers die via Workplace Experience-touchpoints worden aangemaakt, worden via de API-connector met Asset gesynchroniseerd. Ook zijn reserveringen die in Asset zijn gemaakt zichtbaar op Workplace Experience-touchpoints, waardoor een naadloze gegevensuitwisseling wordt gegarandeerd.
Standaard wordt de Workplace Experience-API-connector door Customer Support ingesteld tijdens de eerste configuratie van een nieuwe Asset-omgeving voor de klant.
2.1.1 Objecten koppelen
De Workplace Experience API-connector bestaat uit verschillende page includes die worden gebruikt om relevante stamgegevensobjecten aan Workplace Experience-touchpoints te koppelen. De volgende objecten kunnen via de bijbehorende page includes worden gekoppeld:
- Gebouwen
- Gebieden
- Assets (apparatuur)
- Cateringitems (diensten)
- Kostenplaatsen
- Systeemgebruikers
Alleen objecten die aan de API-connector zijn gekoppeld, zijn beschikbaar en zichtbaar in Workplace Experience-touchpoints. Niet-gekoppelde objecten zijn niet toegankelijk in de Workplace Experience-touchpoints.
Objecten kunnen rechtstreeks vanaf de bijbehorende page include aan de API-connector worden gekoppeld. Het is ook mogelijk om het object vanuit het object zelf aan een API-connector te koppelen. Meer informatie vindt u hier: Object aan applicatie koppelen.
U kunt configureren of nieuwe objecten (bijv. gebouwen, gebieden, reserveerbare assets, reserveerbare catalogusitems of kostenplaatsen) automatisch of handmatig aan de Workplace Experience API-connector worden toegevoegd. Deze instelling kan worden aangepast via de Workplace Experience-moduleactivering of via Module-instellingen → tabblad Workplace Experience.
Als een klant bijvoorbeeld wil dat alle Asset-gebouwen en -gebieden automatisch beschikbaar worden gesteld in Workplace Experience, kan de betreffende instelling worden ingeschakeld om handmatig koppelen te voorkomen.
Info
Nadat objecten in Asset aan de API-connector zijn toegevoegd, kan het maximaal 4 uur duren voordat de objecten beschikbaar zijn in Workplace Experience.
2.1.2 Cacheconfiguratie
Raadpleeg voor gedetailleerde informatie over de cacheconfiguratie: Cacheconfiguratie
2.1.3 Beschikbaarheidscontroles optimaliseren
In Asset zijn er verschillende configuratieopties die van invloed zijn op de reserveringsmodule. Dit omvat:
-
Toegang tot reserveerbare objecten:
Aangepaste toegangsinstellingen kunnen reserveringen beperken tot specifieke gebruikers of systeemgroepen. Alleen gebruikers uit de toegewezen groep kunnen bepaalde objecten reserveren. -
Geblokkeerde datums:
Reserveerbare objecten kunnen voor specifieke perioden worden geblokkeerd, waardoor ze niet beschikbaar zijn voor reservering. Zie voor meer informatie Reserveerbare objecten. -
Regimes:
Regimes bepalen de beschikbaarheid van reserveerbare objecten (bijv. alleen beschikbaar van 08:00 tot 17:00 uur). Zie voor meer informatie Regimes beheren.
Wanneer een gebruiker bijvoorbeeld een plattegrond opent in de Workplace-app, toont de applicatie alle beschikbare en niet-beschikbare reserveerbare objecten. Objecten kunnen om de volgende redenen niet beschikbaar zijn:
- De gebruiker heeft geen toegang tot het reserveerbare object.
- Het object heeft geblokkeerde datums binnen de geselecteerde periode.
- Het object wordt beperkt door een regime met beperkte beschikbaarheid.
Voor elk reserveerbaar object op de plattegrond moet de applicatie deze controles uitvoeren om de beschikbaarheid te bepalen. Als de plattegrond een groot aantal reserveerbare objecten bevat, kunnen deze controles de prestaties aanzienlijk beïnvloeden.
Om het ophalen van gegevens te versnellen en de gebruikerservaring te verbeteren, kunnen klanten die geen geblokkeerde datums, specifieke toegangsbeperkingen of regimes met beperkte beschikbaarheid gebruiken, deze controles uitschakelen via de instellingen van de API-connector:
- Toegangscontrole overslaan bij het zoeken naar reserveerbare objecten
- Controle op geblokkeerde datums overslaan bij het zoeken naar reserveerbare objecten
- Regimecontrole overslaan bij het zoeken naar reserveerbare objecten
Het uitschakelen van onnodige controles verkort de verwerkingstijd en zorgt ervoor dat Workplace Experience relevante gegevens sneller kan weergeven.
Info
Deze controles worden standaard overgeslagen. Schakel ze alleen uit als de klant specifiek een bepaalde controle vereist. Wees voorzichtig met het inschakelen van deze controles voor tenants met grote plattegronden of een groot aantal reserveerbare objecten, omdat ze de prestaties aanzienlijk kunnen beïnvloeden bij het zoeken naar reserveerbare objecten of het laden van plattegronden via Workplace Experience-touchpoints.
Belangrijk: Het overslaan van deze controles geldt alleen voor Workplace Experience-touchpoints en heeft geen invloed op het gebruik van Asset voor het maken of beheren van reserveringen.
Info
De toegangscontrole wordt uitgevoerd op het reserveerbare object. Door toegang op het reserveerbare object in te stellen, kan worden voorkomen dat een gebruiker het object reserveert, maar het object blijft bijvoorbeeld beschikbaar voor selectie bij het maken van een aanvraag. Als toegang op het object zelf (gebied, asset of catalogusitem) wordt ingesteld, ziet de gebruiker het object in geen enkele module.
2.1.3.1 Selectieve toegangscontrole voor reserveerbare objecten
Als de toegang tot bepaalde reserveerbare bronnen (bijv. specifieke vergaderruimten) via aangepaste toegangsinstellingen is beperkt en de algemene instelling ‘Toegangscontrole overslaan bij het zoeken naar reserveerbare objecten’ niet is ingeschakeld, is het nog steeds mogelijk om selectief alleen voor die specifieke bronnen de toegang te controleren. Hierdoor kan het systeem toegangscontroles voor andere bronnen overslaan waar toegangsbeperkingen niet relevant zijn, waardoor de prestaties bij het ophalen van gegevens en de gebruikerservaring in Workplace Experience-touchpoints verbeteren.
Deze configuratie zorgt ervoor dat het systeem alleen de toegang tot specifieke reserveerbare bronnen controleert (bijv. vergaderruimten die zijn beperkt tot SMT-leden) wanneer gebruikers via Workplace Experience naar beschikbare bronnen zoeken.
Standaard zijn toegangscontroles uitgeschakeld voor alle reserveerbare objecten (bijv. gebieden, assets, catalogusitems) die aan de Workplace Experience API-connector zijn toegevoegd. Zo schakelt u toegangscontrole in voor specifieke objecten:
- Open het getagde object.
- Schakel de instelling voor toegangscontrole voor dat object in.
Deze selectieve aanpak optimaliseert de prestaties en behoudt tegelijkertijd toegangscontrole waar dat nodig is.
Belangrijk: Als toegangscontroles voor specifieke reserveerbare bronnen moeten worden ingeschakeld, zorg er dan voor dat de algemene instelling ‘Toegangscontrole overslaan bij het zoeken naar reserveerbare objecten’ uitgeschakeld is. Anders worden alle toegangscontroles overgeslagen, ook voor die specifieke bronnen.
Info
Standaard is ‘Toegangscontrole uitschakelen’ ingeschakeld voor alle reserveerbare objecten die aan de Workplace Experience API-connector zijn getagd. Schakel deze instelling alleen uit als de klant specifieke toegangscontroles vereist. Wees voorzichtig met het inschakelen van toegangscontroles voor veel reserveerbare bronnen, vooral voor tenants met grote plattegronden of veel reserveerbare objecten, omdat deze controles de prestaties aanzienlijk kunnen beïnvloeden bij het zoeken naar reserveerbare objecten of het laden van plattegronden via Workplace Experience-touchpoints.
Belangrijk: Het overslaan van toegangscontroles voor specifieke reserveerbare bronnen geldt alleen voor Workplace Experience-touchpoints en heeft geen invloed op het gebruik van Asset voor het maken of beheren van reserveringen.
2.1.4 Check-inopties
In de API-connector kan per categorie en gebouw worden opgegeven of de gebruiker bij het bijna beginnen van de reservering moet inchecken. Meer informatie over de check-ininstellingen vindt u in de aanvullende instellingen voor moduleactivering.
2.1.5 Workflowinteractie
In de API-connector bepaalt de workflowinteractie welke categorieën worden gebruikt voor afzonderlijke en terugkerende reserveringen die vanuit het externe systeem worden gemaakt. Standaard worden automatisch de juiste categorieën gebruikt. De workflowinteractie op de API-connector moet alleen worden gebruikt als er wordt afgeweken van de standaardcategorieën.
2.1.6 Ticketing
Het is mogelijk om via de Workplace-app een ticket te maken. Meer informatie over ticketing vanuit de Workplace-app vindt u via Workplace Experience-integratie: eenvoudige moduleactivering voor ticketing en informatie.
Opmerking
Zorg er bij het koppelen van de relevante servicetypen aan de WPE API-connector altijd voor dat u ook eventuele bovenliggende servicetypen koppelt; anders worden de servicetypen niet weergegeven of kunnen ze niet worden geselecteerd in Workplace Experience.
2.2 Analytics
Door de Analytics-integratie via de moduleactivering te activeren, wordt de API-connector automatisch gemaakt en correct geconfigureerd. Voor Analytics zijn er geen aanvullende configuratieopties in de API-connector naast de hierboven beschreven algemene instellingen.
2.3 Agenda-integratie
Met het type Agenda-integratie voor de API-connector kan de Asset-omgeving integreren met Exchange of Google Workspace. Hierdoor kunnen ruimte- en reserveringsgegevens worden gesynchroniseerd tussen Asset en de agenda-applicatie, zodat vergaderingen die in een van beide systemen worden gemaakt automatisch in het andere systeem worden weergegeven.
Standaard wordt de API-connector voor agenda-integratie gemaakt en gedeeltelijk geconfigureerd tijdens het proces voor moduleactivering. Mogelijk zijn aanvullende handmatige configuratiestappen nodig, zoals hieronder beschreven, om de configuratie te voltooien.
2.3.1 Koppelingen
De koppelingen die nodig zijn om de integratie tussen Asset en Exchange/Google Workspace tot stand te brengen, worden gemaakt en gedeeltelijk vooraf geconfigureerd tijdens de moduleactivering voor Agenda-integratie. De client_id en client_secret moeten echter nog handmatig worden ingevoerd.
Raadpleeg de Asset-configuratiehandleiding voor meer informatie over het verkrijgen van de client_id en client_secret.
2.3.2 Reserveerbare ruimten koppelen
De API-connector voor agenda-integratie bevat een page include die wordt gebruikt om alle relevante reserveerbare ruimten te koppelen die binnen de scope van de agenda-integratie vallen. Reserveerbare ruimten die niet aan de API-connector zijn gekoppeld, vallen buiten de scope van de agenda-integratie. Reserveringen/vergaderingen die vanuit Workplace zijn gemaakt, worden dan ook niet gesynchroniseerd met de externe agenda-applicatie en omgekeerd.
Reserveerbare gebieden kunnen rechtstreeks vanaf de bijbehorende page include aan de API-connector worden gekoppeld. Het is ook mogelijk om het reserveerbare gebied vanuit het gebied zelf aan een API-connector te koppelen. Meer informatie vindt u hier: Object aan applicatie koppelen.
2.3.3 Observaties
Nadat de reserveerbare objecten aan de API-connector zijn gekoppeld, moeten de bijbehorende reserveerbare bronnen worden gekoppeld aan hun tegenhangers in Exchange of Google Workspace. Instructies voor het koppelen van bronnen vindt u in de configuratiehandleiding.
Nadat een koppeling tussen een reserveerbare bron in Asset en een bron in Exchange/Google Workspace succesvol is gemaakt, wordt automatisch een observatie gegenereerd binnen de API-connector. Deze observatie bundelt alle meldingen met betrekking tot de specifieke bron, waardoor een gestroomlijnde communicatie en synchronisatie wordt gegarandeerd.
2.3.4 Workflowinteractie
In de API-connector bepaalt de workflowinteractie welke categorieën worden gebruikt voor afzonderlijke en terugkerende reserveringen die vanuit het externe systeem worden gemaakt. Standaard worden automatisch de juiste categorieën gebruikt. De workflowinteractie op de API-connector moet alleen worden gebruikt als er wordt afgeweken van de standaardcategorieën.
2.3.5 Gebeurtenissenlogboek
Het gebeurtenissenlogboek op de API-connector voor agenda-integratie biedt een overzicht van alle gebeurtenissen die vanuit de agenda-integratie zijn verzonden en ontvangen. Dit overzicht kan worden gebruikt voor foutopsporing.
2.4 Integratie met de Asset-app
Met het type API-connector Asset-app kan de Asset-omgeving integreren met de Asset-app. Hierdoor kunnen werkorders voor correctief en/of preventief onderhoud naar de Asset-app worden verzonden, zodat aannemers deze rechtstreeks vanuit de app kunnen oppakken.
De moduleactivering van de Asset-app maakt de API-connector en configureert deze gedeeltelijk. Aanvullende handmatige configuratiestappen, zoals hieronder beschreven, zijn nodig om de configuratie te voltooien.
2.3.1 Koppelingen
De koppelingen die nodig zijn om de integratie tussen Asset en de Asset-app tot stand te brengen, worden gemaakt en gedeeltelijk vooraf geconfigureerd tijdens de moduleactivering voor integratie met de Asset-app. De tenant_id, default_form, client_id en client_secret moeten echter nog handmatig worden ingevoerd.
Raadpleeg de Asset-configuratiehandleiding voor meer informatie over het verkrijgen van de client_id en client_secret.
2.3.2 Systeemgebruikers koppelen
De API-connector van de Asset-app bevat een page include die wordt gebruikt om alle relevante systeemgebruikers te koppelen die de Asset-app gaan gebruiken om de werkorders af te handelen. Systeemgebruikers die niet aan de API-connector zijn gekoppeld, kunnen de werkorders vanuit Asset afhandelen.
Systeemgebruikers kunnen rechtstreeks vanaf de bijbehorende page include aan de API-connector worden gekoppeld. Het is ook mogelijk om de systeemgebruiker vanuit de systeemgebruiker zelf aan een API-connector te koppelen. Meer informatie vindt u hier: Object aan applicatie koppelen.
2.5 SCIM
Met het type SCIM-integratie voor de API-connector kan Azure integreren met Asset voor het inrichten van gebruikers. Hierdoor worden groepen en gebruikers automatisch in Asset ingericht, zonder dat de gebruikers handmatig in Asset hoeven te worden beheerd.
De moduleactivering voor SCIM-integratie maakt de API-connector. Er is geen aanvullende configuratie van de API-connector nodig in Asset.