SOAP / WCF Integratie

SOAP (Simple Object Access Protocol) via WCF (Windows Communication Foundation) is een integratiemethode voor het uitwisselen van data met Ultimo via gestructureerde XML-berichten. Deze methode is beschikbaar voor Premium en Enterprise edities en biedt een formeel contract via WSDL.

Beschikbaarheid: Premium, Enterprise (niet beschikbaar in Professional)

Wanneer SOAP gebruikenbewerken

SOAP is geschikt wanneer: - Het externe systeem alleen SOAP/WCF ondersteunt - Er een formeel servicecontract (WSDL) vereist is - Legacy systemen gekoppeld moeten worden

Aanbeveling: Voor nieuwe integraties wordt de rest-api aanbevolen vanwege de eenvoud en flexibiliteit.

Setupbewerken

1. Maak een connector aan in de Ultimo Configuration Tool (UCT)
2. Definieer de beschikbare entiteiten en properties voor het SOAP body
3. Configureer authenticatie

Let op: Neem contact op met een Ultimo consultant voor begeleiding bij de connector configuratie.

Endpointbewerken

De standaard SOAP endpoint URL is:

https://{customer}.ultimo.net/WebServices/SoapConnector.svc

URL Componentenbewerken

Voorbeeldbewerken

https://mijnbedrijf.ultimo.net/WebServices/SoapConnector.svc

WSDLbewerken

De WSDL (Web Services Description Language) beschrijft alle beschikbare operaties en het verwachte berichtformaat:

https://{customer}.ultimo.net/WebServices/SoapConnector.svc?wsdl

De WSDL biedt: - Overzicht van alle beschikbare operaties - Berichtstructuur en datatypes - Endpoint binding informatie

Authenticatiebewerken

Authenticatie moet worden opgenomen in het SOAP body van elk request.

Voorbeeld SOAP Requestbewerken

Equipment ophalenbewerken

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ult="http://ultimo.net/webservices">
  <soap:Header>
    <ult:Authentication>
      <ult:Username>api_user</ult:Username>
      <ult:Password>secret123</ult:Password>
    </ult:Authentication>
  </soap:Header>
  <soap:Body>
    <ult:GetData>
      <ult:EntityType>Equipment</ult:EntityType>
      <ult:Filter>Id eq '00001'</ult:Filter>
    </ult:GetData>
  </soap:Body>
</soap:Envelope>

Data importeren via SOAPbewerken

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ult="http://ultimo.net/webservices">
  <soap:Header>
    <ult:Authentication>
      <ult:Username>api_user</ult:Username>
      <ult:Password>secret123</ult:Password>
    </ult:Authentication>
  </soap:Header>
  <soap:Body>
    <ult:ImportData>
      <ult:XmlData>
        <![CDATA[
        <Data>
          <Object Type="Equipment" Action="InsertOrUpdate">
            <Property Name="Id" Value="00001" />
            <Property Name="Description" Value="Koelinstallatie" />
            <Property Name="Context" Value="1" />
            <Property Name="Status" Value="2" />
          </Object>
        </Data>
        ]]>
      </ult:XmlData>
    </ult:ImportData>
  </soap:Body>
</soap:Envelope>

Voorbeeld: Externe webservice aanroepen vanuit Ultimobewerken

Ultimo import connectors kunnen ook externe SOAP webservices aanroepen. Hierbij configureert de import connector een POST request met een SOAP envelope:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:soap="https://webservice.leverancier.nl/api/soap.php">
  <soapenv:Header>
    <login>
      <username>${ImportConnector.WebServiceHttpUserName}</username>
      <password>${ImportConnector.WebServiceHttpPassword}</password>
    </login>
  </soapenv:Header>
  <soapenv:Body>
    <soap:getDataRequest>
      <soap:datetime>#formatdate(${ImportConnector.LastImportSuccess} "yyyy-MM-dd" true)</soap:datetime>
    </soap:getDataRequest>
  </soapenv:Body>
</soapenv:Envelope>

Let op: De variabelen ${ImportConnector.WebServiceHttpUserName} en ${ImportConnector.LastImportSuccess} worden automatisch door Ultimo gevuld. Zie import-connectors voor meer details.

Limietenbewerken

Foutafhandelingbewerken

SOAP responses bevatten standaard SOAP fault elementen bij fouten:

<soap:Fault>
  <faultcode>soap:Server</faultcode>
  <faultstring>Entiteit niet gevonden</faultstring>
  <detail>
    <error>Equipment met Id '99999' bestaat niet</error>
  </detail>
</soap:Fault>

Zie rest-api#Foutafhandeling voor een overzicht van HTTP statuscodes die ook voor SOAP gelden.

Gerelateerde artikelenbewerken

• rest-api -- REST API (aanbevolen voor nieuwe integraties)
• http-post -- HTTP POST alternatief
• import-connectors -- Import connectors configuratie
• api-keys -- API keys beheer