Randvoorwaarden

Om de API's te kunnen gebruiken, gelden enkele randvoorwaarden. Een (technisch) consultant kan helpen met deze randvoorwaarden.

Een Workplace beheeromgeving Management omgeving met de volgende subvoorwaarden:

1. Inkomende webservices worden ingeschakeld via de volgende toegangsregels (tabblad Authenticatie op algemene instellingen) (dit wordt gedaan via de klantenservice):

2. 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:

3. 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:

API OAuth 2.0 autorisatieschema

Algemeen

Om toegang te krijgen tot de bronnen die worden aangeboden door 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 tokenaanvraagbericht versleutelen

Het tokenaanvraagbericht moet nu worden versleuteld met de vooraf gedeelde AES-sleutel, die kan worden gegenereerd in Werkplekbeheer Workplace Management met behulp van AES-CBC-modus, wat resulteert in een cijfertekst en een IV (initialisatievectorinitialiseringsvector). 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/token

Het verzoek moet ten minste de volgende headers bevatten (waarbij de termen tussen haakjes weer moeten worden vervangen door de werkelijke waarden):

'Authorization': 'Axx_encryption_key [trust relation access id]',
'axx-client-reference': '[client reference]'

De request body moet formulier URL-gecodeerde gegevens bevatten zoals beschreven in de onderstaande tabel:

Wanneer de server de autorisatieaanvraag toekent, 200 OK antwoorden moeten worden ontvangen met die het bearer token draagtoken bevatten dat kan worden gebruikt voor toegang tot de resource endpoints 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:

1. Gegevens ophalen uit WerkplekbeheerWorkplace 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

2. 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 het juiste welk rapport dat 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 het juiste welk rapport dat 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 het juiste welk rapport dat 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 https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)

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 tenant 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 het juiste welk rapport dat 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 corrigerende werkopdrachten op (werkopdrachten die zijn correctieve werkorders (werkorders aangemaakt op een verzoek) op in de huurder met de relevante informatie per werkopdrachtwerkorder.

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 https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)

De volgende filtervelden kunnen ook worden gebruikt (niet weergegeven in de bovenstaande body):

• Activa (geef de ID-waarde van een activum op om de corrigerende correctieve werkorders te krijgen die aan dit activum zijn gekoppeld)

• Gebied (specificeer geef de ID-waarde van een gebied op om de corrigerende correctieve werkorders te krijgen die aan dit gebied zijn gekoppeld)

• Eigenschap (specificeer de ID-waarde van een eigenschap om de corrigerende correctieve werkorders gekoppeld aan deze eigenschap te krijgen)

• Verzoek (specifiek de ID-waarde van een verzoek , om de corrigerende 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 https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)

De volgende filtervelden kunnen ook worden gebruikt (niet weergegeven in de bovenstaande body):

(Omdat preventieve werkorders aan meerdere objecten kunnen worden gekoppeld aan meerdere objecten (bijv. onderhoud voor 10 liften), werkt het filteren een beetje anders voor correctieve werkorders. Een preventieve werkorder kan meer dan één keer 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 op te halenkrijgen)

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 de een id-waarde van een 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):

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):

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.