HTTP POST Integratie

HTTP POST is een integratiemethode waarmee externe systemen data naar Ultimo kunnen sturen via een XML-gebaseerd HTTP POST request. Dit is een alternatief voor de REST API, specifiek voor Premium en Enterprise edities.

Beschikbaarheid: Premium, Enterprise (niet beschikbaar in Professional)

Hoe het werktbewerken

Bij HTTP POST communicatie stuur je een XML-bericht met key-value pairs naar de Ultimo HTTP handler. Het bericht bevat alle objecten en hun properties in een vast XML-formaat. De ontvangende applicatie moet de XML response van Ultimo Business Integration zelf parsen.

Setupbewerken

1. Maak een connector aan in de Ultimo Configuration Tool (UCT)
2. Definieer welke entiteiten en properties beschikbaar zijn voor het POST body
3. Configureer authenticatie (gebruikersnaam en wachtwoord)

Let op: De exacte configuratie vereist begeleiding van een Ultimo consultant. De connector in UCT bepaalt welke data er verstuurd en ontvangen kan worden.

Endpointbewerken

De standaard endpoint URL is:

https://{customer}.ultimo.net/WebServices/Connector.ashx

URL Componentenbewerken

Voorbeeldbewerken

Als je Ultimo omgeving draait op https://mijnbedrijf.ultimo.net/:

https://mijnbedrijf.ultimo.net/WebServices/Connector.ashx

Let op: Het pad /WebServices/Connector.ashx kan afwijken als Ultimo op een andere locatie is geinstalleerd.

Authenticatiebewerken

Gebruikersnaam en wachtwoord worden als parameters aan de connection string toegevoegd.

Aanbeveling: Gebruik altijd een HTTPS-verbinding bij HTTP POST om credentials te beschermen.

XML Formaatbewerken

Basisstructuur voor data importbewerken

Het standaard Ultimo XML importformaat ziet er als volgt uit:

<?xml version="1.0" encoding="utf-8"?>
<Data>
  <Object Type="Equipment" Action="InsertOrUpdate">
    <Property Name="Id" Value="00001" />
    <Property Name="Description" Value="Koelinstallatie gebouw A" />
    <Property Name="Context" Value="1" />
    <Property Name="Status" Value="EquipmentStatus.Active" />
    <Property Name="Department.Id" Value="01" />
    <Property Name="CostCenter.Id" Value="01" />
    <Property Name="InstallDate" Value="2022-04-07" />
  </Object>
</Data>

Ondersteunde actiesbewerken

Statuswijzigingenbewerken

Gebruik het ChangeStatusTo attribuut om de status te wijzigen:

<Object Type="Equipment" Action="InsertOrUpdate" ChangeStatusTo="EquipmentStatus.Active">
  <Property Name="Id" Value="00001" />
  <Property Name="Description" Value="Koelinstallatie" />
</Object>

Meerdere objectenbewerken

<?xml version="1.0" encoding="utf-8"?>
<Data>
  <Object Type="Equipment" Action="InsertOrUpdate">
    <Property Name="Id" Value="00001" />
    <Property Name="Description" Value="Asset A" />
    <Property Name="Context" Value="1" />
    <Property Name="Status" Value="2" />
  </Object>
  <Object Type="Equipment" Action="InsertOrUpdate">
    <Property Name="Id" Value="00002" />
    <Property Name="Description" Value="Asset B" />
    <Property Name="Context" Value="1" />
    <Property Name="Status" Value="2" />
  </Object>
</Data>

Geneste objecten (parent-child)bewerken

Voor het aanmaken van gerelateerde records kun je objecten nesten. Gebruik ${Parent.Id} om naar het parent-record te verwijzen:

<Data>
  <Object Type="Job" Action="InsertOrUpdate">
    <Property Name="Context" Value="1" />
    <Property Name="Status" Value="1" />
    <Property Name="Description" Value="Onderhoudsorder" />
    <Object Type="JobLine" Action="InsertOrUpdate">
      <Property Name="Job.Id">
        <xsl:attribute name="Value">${Parent.Id}</xsl:attribute>
        <xsl:attribute name="Evaluate">true</xsl:attribute>
      </Property>
      <Property Name="Description" Value="Werkregel 1" />
    </Object>
  </Object>
</Data>

Voorbeeld: IoT meting versturenbewerken

<?xml version="1.0" encoding="utf-8"?>
<Data>
  <Object Type="MeasuredValue" Action="InsertOrSkip">
    <Property Name="Equipment.Id" Value="00001" />
    <Property Name="MeasurementPoint.Id" Value="TEMP-01" />
    <Property Name="Date" Value="2025-03-15 14:30:00" />
    <Property Name="Value" Value="72.5" />
    <Property Name="Text" Value="Routine meting" />
  </Object>
</Data>

Limietenbewerken

Foutafhandelingbewerken

De HTTP response bevat statuscodes en eventueel foutdetails in de response body. Zie rest-api#Foutafhandeling voor een overzicht van HTTP statuscodes.

Belangrijk: Een 200 OK response betekent alleen dat het bericht is ontvangen, niet dat de data succesvol is verwerkt. Controleer altijd de response body op verwerkingsresultaten.

Gerelateerde artikelenbewerken

• rest-api -- REST API (aanbevolen voor nieuwe integraties)
• soap -- SOAP/WCF alternatief
• import-connectors -- Import via connectors met XSLT transformatie
• api-keys -- API keys beheer