Workplace Management: Generieke webservices
Lango: Language and translation manager
Algemeen
Webservices kunnen gegevens ophalen, aanmaken en bijwerken in een Workplace Management omgeving.
De Workplace Management API maakt gebruik van een REST-gebaseerd framework. Autorisatie is gebaseerd op Bearer tokens en een vooraf gedeelde sleutel.
Webservices zijn out of the box beschikbaar en gedocumenteerd in de volgende onderdelen voor enkele van de meest gebruikte objecten. Deze objecten zijn:
Masterdata:
Organisaties
Contactpersonen
Gebouwen
Gebieden
Activa
Soorten problemen
Processen:
Verzoeken
Correctieve werkorders
Preventieve werkorders
Momenteel gebruiken deze API's generieke eindpunten. In de toekomst kunnen domeinspecifieke eindpunten worden aangemaakt, zoals het geval is voor het reserveringsdomein.
Randvoorwaarden
Om de API's te kunnen gebruiken, gelden enkele randvoorwaarden. Een (technisch) consultant kan helpen met deze randvoorwaarden.
Een Workplace Management omgeving met de volgende subvoorwaarden:
Inkomende webservices worden ingeschakeld via de volgende toegangsregels (tabblad Authenticatie op algemene instellingen) (dit wordt gedaan via de klantenservice):
Een extern app-object (dat ook kan worden gemaakt via het tabblad Authenticatie op de algemene instellingen als beheerder van niveau 3) met een vertrouwensrelatie (sleuteltype = AES gedeelde sleutel) is beschikbaar met de geautoriseerde systeemgebruiker van de vertrouwensrelatie ook gekoppeld aan de externe app in het tabblad Systeemgebruiker:
Zorg ervoor dat je het domein toevoegt in het veld 'Toegestane herkomsten voor REST webservices' (Clientinstellingen, verificatie) als je externe domeinen asynchroon toegang wilt geven tot de generieke webservices (Cross-origin resource sharing (CORS)-Cross-origin resource sharing (CORS)).
Vereiste parameters
De volgende parameters zijn nodig om de API-oproepen met succes in te stellen:
Parameter | Beschrijving | Voorbeeld |
|---|
Parameter | Beschrijving | Voorbeeld |
|---|---|---|
server | de basis URL van de huurder, ofwel het huurder-specifieke domein of een algemene server | |
authenticatiemodus | Vaste waarde: "GENERIC. " Relevant voor de op OAuth 2.0 gebaseerde tokenauthenticatie. Dit is ALLEEN nodig voor de geautomatiseerde scripting voor tokenaanvragen in Postman. | GENERISCH |
clientRef | De referentie van het milieu | demotenant |
gebruikersnaam | De gebruikersnaam van de systeemgebruiker namens wie je wilt verifiëren. Relevant voor de tokenauthenticatie. (Deze gebruiker moet gekoppeld zijn aan de externe app via het tabblad systemuser) | demo_api |
app-id | De referentie van de externe app. Relevant voor de tokenauthenticatie aan toonder | DTW-EA-001 |
x-toegangs-id-waarde | De toegangs-id van de vertrouwensrelatie. Relevant voor de tokenauthenticatie aan toonder | demo_api_id |
geheime sleutel | De sleutel van de vertrouwensrelatie. Relevant voor de tokenauthenticatie aan toonder | DB2E51543E463290B946602B8047CC9E16048E2C99728DB2E51543E463290B946602B8047CC9E16048E2C99728 |
API OAuth 2.0 autorisatieschema
Algemeen
Om toegang te krijgen tot de bronnen van de Workplace Management REST API, moeten clients eerst een token aanvragen. De procedure hiervoor wordt hieronder beschreven:
Type subsidie
Dragertokens kunnen worden verkregen met behulp van het OAuth-subsidietype "Resource Owner Password Credentials". Hoewel dit toekennings-type suggereert dat een wachtwoord wordt gebruikt, is dit niet het geval in dit autorisatieschema. In plaats van een wachtwoord moet een token aanvraagbericht worden versleuteld met behulp van een vooraf gedeelde AES-sleutel, die het eindpunt zal valideren, en een token zal worden geretourneerd als de authenticatie slaagt. Brongegevens die worden teruggestuurd door de bron eindpunten zijn afhankelijk van de toegangsrechten van gebruikers tot de relevante bronnen.
Bericht voor tokenverzoek
Het tokenaanvraagbericht is een JSON-bericht dat de volgende gegevens moet bevatten, waarbij de termen tussen haakjes moeten worden vervangen door hun letterlijke waarden:
{
"grant_type": "password,""
"username": "[username of the resource owner]",
"password": "",
"scope": "session v1 v2 v3",
"app_id": "[external app id]"
}Het is mogelijk om de letterlijke alias "axx::access::admin" als gebruikersnaam te gebruiken (zonder de extra aanhalingstekens). Als je dit doet, wordt in plaats van de echte gebruikersnaam van de gebruiker die de bronnen aanvraagt, toegang aangevraagd namens de standaard geautoriseerde systeemgebruiker die is gekoppeld aan de (op AES-voorgedeelde sleutel gebaseerde) vertrouwensrelatie die wordt gebruikt door de externe applicatie.
Het tokenaanvraagbericht versleutelen
Het tokenaanvraagbericht moet nu worden versleuteld met de vooraf gedeelde AES-sleutel, die kan worden gegenereerd in Workplace Management met behulp van AES-CBC-modus, wat resulteert in een cijfertekst en een IV (initialiseringsvector). Maak nu een string met het volgende formaat:
[length of the base64 encoded ciphertext]:[base64 encoded ciphertext][base64 encoded IV]Deze resulterende string moet worden verzonden in het eigenlijke tokenverzoek als "encrypted-params"; zie de volgende paragraaf.
Maak een echt HTTP-verzoek aan voor het tokeneindpunt
Om nu het HTTP-verzoek voor het tokeneindpunt te vormen, moet een POST verzoek moet worden gegenereerd naar het volgende eindpunt (waarbij de server moet worden vervangen door het serverdomein):
https://[server]/axxerion/aaa/registration/oauth2/tokenHet verzoek moet ten minste de volgende headers bevatten (waarbij de termen tussen haakjes weer moeten worden vervangen door de werkelijke waarden):
De request body moet formulier URL-gecodeerde gegevens bevatten zoals beschreven in de onderstaande tabel:
toets | waarde |
|---|
toets | waarde |
|---|---|
| [encrypted-params] |
Wanneer de server de autorisatieaanvraag toekent, 200 OK antwoorden moeten worden ontvangen die het draagtoken bevatten dat kan worden gebruikt voor toegang tot de bron eindpunten zolang het token geldig is.
Een voorbeeld van het script kan worden gevonden via de voorbeeld Postman Verzamelingen in het tabblad Pre-request script, dat onderaan dit document kan worden gedownload.
Overzicht van API's
Elk eindpunt bestaat uit een basis URL: https://{server}/webservices/{{clientRef}}/rest
Zowel 'server' als 'clientRef' moeten worden ingevuld op basis van de omgevingsparameters.
Op basis van het type eindpunt wordt het tweede deel van de URL van het eindpunt bepaald:
Momenteel zijn er twee soorten eindpunten beschikbaar:
Gegevens ophalen uit Workplace Management. Hiervoor wordt de generieke functie 'completereportresult' gebruikt. Dit is hetzelfde eindpunt voor elke oproep; de specifieke gegevensaanvraag (Rapport) wordt toegevoegd aan de body van de oproep via een referentiewaarde (Verplicht en vaste waarde per oproep).
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Voorbeeld eindpunt: https://demotenant.axxerion.com/webservices/demotenant/rest/functions/completereportresult
Een object (bedrijfsmiddel of verzoek) maken. Hiervoor wordt de generieke functie 'createupdate' gebruikt. Het eigenlijke object en de categorie van het object (bijv. Create Asset in categorie "Furniture") dat moet worden aangemaakt, wordt ook toegevoegd aan het eindpunt na het createupdate-gedeelte.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions//createupdate{ObjectName}/{ObjectCategoryId}
Voorbeeld eindpunt: https://demotenant.axxerion.com/webservices/demotenant/rest/functions/Asset/710000000172835
De objectnaam kan "Asset" of "Request" zijn, de ObjectCategoryId is alleen relevant voor Assets (vaste waarde voor Requests). De opties voor assets kunnen worden opgehaald via een van de onderstaande API's.
De volgende API's zijn momenteel out of the box beschikbaar:
Verkrijg een lijst van organisaties
Deze POST-oproep zal alle organisaties (Eigen organisaties en leveranciers) in de tenant ophalen met de relevante informatie per organisatie.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Rapport_Organisaties_01", "filtervelden":["Email"], "filterValues":["example@email.com"]}
De referentie is verplicht; deze bepaalt het juiste rapport dat moet worden uitgevoerd: API_Rapport_Organisaties_01
De filtervelden zijn optioneel.
Beschikbare filtervelden:
Het is mogelijk om de organisaties te filteren op basis van een e-mailadres: E-mail
Voorbeeldresultaat:
Een lijst van personen krijgen
Deze POST-oproep zal alle personen in de huurder ophalen met de relevante informatie per persoon.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Report_Contacts_01", "filtervelden":["Email"], "filterValues":["noreply@spacewell.com"]}
De referentie is verplicht; deze bepaalt het juiste rapport dat moet worden uitgevoerd: API_Rapport_Contacten_01
De filtervelden zijn optioneel.
Beschikbare filtervelden:
Het is mogelijk om de personen te filteren op basis van een e-mailadres: E-mail
Voorbeeldresultaat:
Verkrijg een lijst met gebouwen
Deze POST-oproep zal alle gebouwen in de huurder ophalen met de relevante informatie per gebouw.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Report_Properties_01".}
De referentie is verplicht; deze bepaalt het juiste rapport dat moet worden uitgevoerd: API_Report_Properties_01
Deze oproep ondersteunt geen extra filtervelden
Voorbeeldresultaat:
Een lijst met gebieden
Deze POST-oproep zal alle gebieden in de huurder ophalen met de relevante informatie per gebied.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Report_Areas_01", "filtervelden":["Eigenschap"], "filterValues":[[1210000000000849]]}
De referentie is verplicht; deze bepaalt welk rapport correct moet worden uitgevoerd: API_Rapport_Areas_01
De filtervelden zijn optioneel.
Beschikbare filtervelden:
Het is mogelijk om de gebieden te filteren op basis van een specifiek gebouw: Eigendom
De filterwaarde moet de Id van het gebouw zijn, zoals opgehaald via de gebouw-API-oproep.
Voorbeeldresultaat:
Een lijst met activa ophalen
Deze POST-oproep zal alle middelen in de huurder ophalen met de relevante informatie per middel.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Report_Asset_01", "filtervelden":["Eigendom","Gebied"], "filterValues":[[1000066632],[1000212917]]}
De referentie is verplicht; deze bepaalt welk rapport correct moet worden uitgevoerd: API_Report_Asset_01
De filtervelden zijn optioneel.
Beschikbare filtervelden:
Het is mogelijk om de activa te filteren op basis van een specifiek gebouw: Gebouw
Het is mogelijk om de activa te filteren op basis van een specifiek gebied: Gebied
De filterwaarde moet de id van het gebouw en/of gebied zijn, zoals opgehaald via API-oproepen voor gebouwen en gebieden.
Voorbeeldresultaat:
Een lijst met activacategorieën opvragen
Deze POST-oproep zal alle activacategorieën in de huurder ophalen. De Id van een activacategorie kan worden gebruikt om een nieuwe asset aan te maken in de gewenste categorie (Zie Een bedrijfsmiddel maken). Bijv. auto, fiets, koffiezetapparaat.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Report_Asset_Categories_01"}
De referentie is verplicht; deze bepaalt het juiste rapport dat moet worden uitgevoerd: API_Report_Asset_Categories_01
Deze oproep ondersteunt geen extra filtervelden
Voorbeeldresultaat:
Een lijst met verzoeken ophalen.
Deze POST-oproep zal alle verzoeken in de tenant ophalen met de relevante informatie per verzoek.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Report_Requests_01", "filtervelden":["AangemaaktSinds","AangemaaktTot"], "filterValues":["2023-01-01T00:00:00Z","2023-08-01T00:00:00Z"]}
De referentie is verplicht; deze bepaalt welk rapport correct moet worden uitgevoerd: API_Report_Requests_01
De filtervelden zijn optioneel.
Beschikbare filtervelden:
Het is mogelijk om de verzoeken te filteren op basis van de aanmaaktijden: AangemaaktSinds en AangemaaktTot
Datum-/tijdfilters moeten worden ingevoerd in ISO 8610 Gecombineerde weergave van datum en tijd (Zie ISO 8601)
De volgende filtervelden kunnen ook worden gebruikt (niet weergegeven in de bovenstaande body):
Bedrijfsmiddel (geef de ID-waarde van een bedrijfsmiddel op om de verzoeken op te halen die aan dit bedrijfsmiddel zijn gekoppeld)
Gebied (geef de ID-waarde van een gebied op om de verzoeken te krijgen die aan dit gebied zijn gekoppeld)
Eigenschap (geef de ID-waarde van een eigenschap op om de verzoeken te krijgen die aan deze eigenschap zijn gekoppeld)
Voorbeeldresultaat:
Een lijst met probleemtypen opvragen
Deze POST-oproep haalt alle probleemtypes op (een probleemtype wordt gebruikt om het type verzoek te bepalen en welke servicegroep wordt toegewezen om het verzoek af te handelen) in de tenant met de relevante informatie per probleemtype.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "referentie":"API_Report_ProblemTypes_01"}
De referentie is verplicht; deze bepaalt het juiste rapport dat moet worden uitgevoerd: API_Report_ProblemTypes_01
Deze oproep ondersteunt geen extra filtervelden
Voorbeeldresultaat:
Een lijst met leden per servicegroep opvragen
Deze POST-oproep zal alle contactpersonen in een servicegroep ophalen (Een servicegroep wordt gebruikt in een probleemtype en zal worden gebruikt om te bepalen welke groep zal worden toegewezen om het verzoek te behandelen) in de huurder met de relevante informatie per servicegroep.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "referentie":"API_Report_ServiceGroupMembers_01"}
De referentie is verplicht; deze bepaalt welk rapport correct moet worden uitgevoerd: API_Report_ServiceGroupMembers_01
Deze oproep ondersteunt geen extra filtervelden
Voorbeeldresultaat:
Een lijst met correctieve werkorders opvragen
Deze POST-oproep haalt alle correctieve werkorders (werkorders aangemaakt op verzoek) op in de huurder met de relevante informatie per werkorder.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Report_Corrective_WorkOrders_01", "filtervelden":["AangemaaktSinds","AangemaaktTot"], "filterValues":["2023-01-01T00:00:00Z","2023-09-01T00:00:00Z"]}
De referentie is verplicht; deze bepaalt het juiste rapport dat moet worden uitgevoerd: API_Report_Corrective_WorkOrders_01
De filtervelden zijn optioneel.
Beschikbare filtervelden:
Het is mogelijk om de werkorders te filteren op basis van de aanmaaktijden: AangemaaktSinds en AangemaaktTot
Datum-/tijdfilters moeten worden ingevoerd in ISO 8610 Gecombineerde weergave van datum en tijd (Zie ISO 8601)
De volgende filtervelden kunnen ook worden gebruikt (niet weergegeven in de bovenstaande body):
Activa (geef de ID-waarde van een activum op om de correctieve werkorders te krijgen die aan dit activum zijn gekoppeld)
Gebied (geef de ID-waarde van een gebied op om de correctieve werkorders te krijgen die aan dit gebied zijn gekoppeld)
Eigenschap (specificeer de ID-waarde van een eigenschap om de correctieve werkorders gekoppeld aan deze eigenschap te krijgen)
Verzoek (specifiek de ID-waarde van een verzoek om de correctieve werkorders voor dit verzoek op te halen)
Voorbeeldresultaat:
Een lijst met preventieve werkorders opvragen
Deze POST-oproep zal alle preventieve werkorders (werkorders aangemaakt via een onderhoudsschema) in de huurder ophalen met de relevante informatie per werkorder.
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/completereportresult
Lichaam:
{ "Referentie":"API_Rapport_Preventive_WorkOrders_01", "filtervelden":["AangemaaktSinds","AangemaaktTot"], "filterValues":["2023-01-01T00:00:00Z","2024-01-01T00:00:00Z"]}
De referentie is verplicht; deze bepaalt het juiste rapport dat moet worden uitgevoerd: API_Report_Corrective_WorkOrders_01
De filtervelden zijn optioneel.
Beschikbare filtervelden:
Het is mogelijk om de werkorders te filteren op basis van de aanmaaktijden: AangemaaktSinds en AangemaaktTot
Datum-/tijdfilters moeten worden ingevoerd in ISO 8610 Gecombineerde weergave van datum en tijd (Zie ISO 8601)
De volgende filtervelden kunnen ook worden gebruikt (niet weergegeven in de bovenstaande body):
(Omdat preventieve werkorders aan meerdere objecten kunnen worden gekoppeld (bijv. onderhoud voor 10 liften), werkt het filteren een beetje anders voor correctieve werkorders. Een preventieve werkorder kan meer dan eens worden geretourneerd, afhankelijk van het aantal objecten waaraan het is gekoppeld. Om te filteren op een specifiek object kan de ID van het object worden toegevoegd. Dit kan een asset, gebied of gebouw zijn (let op, als de werkorder is gekoppeld aan een specifiek asset, zal het geen resultaten opleveren als er wordt gefilterd op het gebouw op dat asset, er moet specifiek op dat asset worden gefilterd (Of geen filter)).
Object (specificeer de ID-waarde van een Asset, Gebied of Gebouw om de preventieve werkorders gekoppeld aan dit object te krijgen)
Voorbeeldresultaat:
Activa maken
Deze postoproep wordt gebruikt om een nieuw object te maken
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/createupdate/Asset/{assetCategory}}
De '{{assetCategory}' in de URL van het eindpunt moet worden ingesteld op een id-waarde van de activacategorie (opgehaald via de een lijst met activacategorieën krijgen oproep)
Body met voorbeeldwaarden:
{ "naam": "Voorbeeld laptop 2", "externalReference": "987654321", "serialNumber": "123456789", "handelsnaam": "DTwin turbo", "modelnaam": "model X1", "Hoeveelheid": "1", "manufacturerContactId": "1210000000005286", "supplierContactId": "", "Aankoopdatum": "2023-01-01T00:00:00Z", "propertyId": "1210000000000849", "areaId": "1210000000048836", "parentAssetId": "1210000000008548"}
De volgende velden kunnen worden ingesteld via de body (allemaal optioneel):
Parameter | Beschrijving |
|---|
Parameter | Beschrijving |
|---|---|
Naam | Vrije tekst (max. 255 tekens) |
Externe verwijzing | Vrije tekst (max. 255 tekens) |
serienummer | Vrije tekst (max. 255 tekens) |
modelnaam | Vrije tekst (max. 255 tekens) |
hoeveelheid | Integer |
fabrikantContactId | Id-waarde van een organisatie of persoon (opgehaald via de een lijst van organisaties of een lijst met personen API krijgen oproepen) |
leverancierContactId | Id-waarde van een organisatie of persoon (opgehaald via de een lijst van organisaties of een lijst met personen API krijgen oproepen) |
aankoopdatum | Datum-/tijdfilters moeten worden ingevoerd in ISO 8610 Gecombineerde weergave van datum en tijd (Zie ISO 8601) |
propertyId | Id-waarde van een gebouw (Opgehaald via de een lijst van gebouwen krijgen API-oproep) |
gebiedId | Id-waarde van een gebied ( Opgehaald via de een lijst van een gebieden API-oproep) |
parentAssetId | Id-waarde van een actief ( Opgehaald via de een lijst van een activa API-oproep) |
Het antwoord is de Id-waarde van de nieuw aangemaakte asset:
Een verzoek maken
Deze postoproep wordt gebruikt om een nieuw verzoek te maken
Eindpunt: https://{server}/webservices/{{clientRef}}/rest/functions/createupdate/Request/1000000786
Body met voorbeeldwaarden:
{ "fromContactId": "1210000000004567", "naam": "Testverzoek", "description": "Test verzoek", "problemTypeId": "1210000000005757", "propertyId": "12100000000057634", "areaId": "1210000000005764", "assetId": "1210000000005734"}
De volgende velden kunnen worden ingesteld via de body (allemaal optioneel):
Parameter | Beschrijving |
|---|
Parameter | Beschrijving |
|---|---|
vanContactId | Id-waarde van een organisatie of persoon (Opgehaald via de een lijst van organisaties of een lijst met personen API krijgen |
naam | Vrije tekst (max. 255 tekens) |
beschrijving | Vrije tekst (max. 255 tekens) |
problemTypeId | Id-waarde van een probleemtype (Opgehaald via de een lijst van probleemtypen API-oproep) |
propertyId | Id-waarde van een gebouw (Opgehaald via de een lijst van gebouwen API-oproep) |
gebiedId | Id-waarde van een gebied ( Opgehaald via de een lijst van gebieden API-oproep) |
assetId | Id-waarde van een actief (Opgehaald via de een lijst van activa API-oproep) |
Het antwoord zal de Id-waarde van het nieuw aangemaakte verzoek zijn
Een bestaand object bijwerken
Via een PUT-oproep is het mogelijk om een van de bovenstaande objecten bij te werken.
Hiervoor is het volgende eindpunt nodig:https://{server}/webservices/{{clientRef}}/rest/functions/update/{ObjectType}/{ID}
De {ObjecType} moet de naam van het objecttype zijn. Bijv. 'Activa' of 'Aanvraag'.
De {ID} moet de ID-waarde zijn van het object dat je wilt bijwerken
De body van de aanroep moet de relevante velden bevatten om bij te werken. Zie de voorbeelden hierboven in de aanroepen om te creëren.
Postbode project
De volgende links bevatten een voorbeeld Postbode project en een (dummy) omgeving gebaseerd op de API-aanroepen die hierboven zijn beschreven. De omgeving moet worden ingevuld op basis van de daadwerkelijk te gebruiken omgevingsparameters.
