API voorbeelden

In dit artikel worden de volgende voorbeelden uitgelegd.

• Vrije velden (FreeFields)
• Bijlagen en DocumentReferences
  
  

 

Vrije velden (FreeFields)

Bij verschillende entiteiten kunnen vrije velden worden meegegeven (zoals werkorders, requests, objecten, formulieren, inkooporders, enzovoort).
Deze velden worden opgenomen in de freeFields-property, als een array van FreeField-objecten.

Een vrij veld (FreeField) heeft altijd een definitie, een FreeFieldDefinition, die een unieke ID bevat.
Elke FreeFieldDefinition heeft een AttributeType, dat gekoppeld is aan een BaseAttributeType.

In de collectie van vrije velden bij bijvoorbeeld een werkorder, moet per vrij veld minimaal het volgende worden opgenomen:

• freeFieldDefinitionId

• value

De property value

De property value is een complex type, waarvan ten minste de volgende properties ingevuld moeten zijn:

• value – de daadwerkelijke waarde van het vrije veld

• baseAttributeType – het type van de waarde

Door gebruik te maken van de property value is het niet nodig om de andere properties (zoals stringValue, booleanValue, enzovoort) te gebruiken.
De property value abstraheert deze types.

Voorbeeld: werkorder met één vrij veld

Om een werkorder met één vrij veld in ControlOffice te registreren, gebruik je het endpoint:
POST /api/v1/workorder

Met bijvoorbeeld de volgende body:

{
  "id": "",
  "statusId": "4ab1f3a0-4a6c-4761-9856-fd3a91060768",
  "objectId": "6e823b36-8e83-4879-b49a-0a326436e496",
  "workorderTypeId": "bc4aad96-f7ff-4195-bbb7-2acef6d3a73f",
  "creationDt": "2025-10-07T14:37:32.8838648Z",
  "name": "test werkorder via api met freefield",
  "outsource": false,
  "requestorId": "5ccaba53-e165-4450-840b-4e405ba35498",
  "freeFields": [
    {
      "freeFieldDefinitionId": "41c85f0e-2655-42c0-a558-a56268483448",
      "value": {
        "baseAttributeType": 1,
        "value": "TEST12345"
      }
    }
  ]
}

---

 

Bijlagen en DocumentReferences

In ControlOffice kunnen bijlagen (bijvoorbeeld gekoppeld aan een werkorder) worden geregistreerd.
Dit werkt via een hiërarchie van drie entiteiten:

1. DocumentReference – een verwijzing van bijvoorbeeld een werkorder naar een document.

2. Document – beschrijft de metadata van het document (zoals titel, type, auteur, enz.).

3. File – bevat de daadwerkelijke inhoud van de bijlage (in Base64-gecodeerde vorm).

Een DocumentReference is dus eigenlijk een koppeling tussen een werkorder en een document dat ergens als file is opgeslagen.

Uploadproces

Het uploaden van een bijlage verloopt in twee stappen, niet in één POST:

1. Upload de file

De inhoud van de bijlage (het bestand zelf) wordt eerst geüpload via:

POST /api/v1/file

Vereiste body (JSON)

{
  "id": "<een guid>",
  "name": "<de naam van de file>",
  "content": "<base64 string met de content van de file>"
}

• id → Unieke identifier (GUID) van het bestand.

• name → Bestandsnaam, inclusief extensie (bijv. foto.png, rapport.pdf).

• content → Base64-gecodeerde inhoud van het bestand.

Uploadlocatie

De file wordt opgeslagen in de standaard upload folder, die in ControlOffice is ingesteld als:

UploadFolder

Maak een DocumentReference aan

Na het uploaden van het bestand wordt een DocumentReference aangemaakt, die verwijst naar het bijbehorende document (en dat document verwijst op zijn beurt weer naar de file die je net hebt geüpload).

Dit gebeurt typisch via een endpoint als:

POST /api/v1/documentreference

met een body die het document koppelt aan bijvoorbeeld een werkorder-ID en de file-ID die je net hebt geüpload.
(Dit specifieke endpoint is niet in je voorbeeld genoemd, maar volgt logisch uit de datastructuur.)

Voorbeeld: Upload van het ControlOffice-logo

Onderstaand voorbeeld uploadt het controlofficelogo.png-bestand naar de standaard “UploadFolder”:

{
  "id": "",
  "name": "controlofficelogo.png",
  "content": "iVBORw0KGgoAAAANSUhEUgAAB6YAAADLCAYAAADN2f1wAAAQ..."
}

• De Base64-string is uiteraard ingekort in de documentatie; in de praktijk is dit de volledige inhoud van het bestand.

Belangrijke aandachtspunten

• De file-upload en documentreferentie-aanmaak zijn aparte calls — je kunt ze niet combineren in één POST.

• De UploadFolder is configureerbaar binnen ControlOffice, maar standaard wordt deze gebruikt.

• De Base64-string moet geldig zijn — foutieve codering zal leiden tot een 400 (Bad Request).

• De GUID kun je client-side genereren of laten genereren door de backend, afhankelijk van de API-architectuur.