Import Connectors

Import connectors zijn de standaard methode in Ultimo om externe data geautomatiseerd te importeren. Ze ondersteunen zowel bestandsgebaseerde imports als webservice-imports, met XSLT transformaties om externe dataformaten om te zetten naar het Ultimo XML importformaat. Elke connector heeft ingebouwde logging en optionele rollback bij fouten.

Beschikbaarheid: Premium, Enterprise

Wat is een Import Connector?bewerken

Een import connector is een configuratie in Ultimo die bepaalt: - Waar de data vandaan komt (bestand of webservice) - Hoe de data wordt getransformeerd (XSLT) - Wat er met de data gebeurt (insert, update, delete) - Welke entiteiten worden bijgewerkt (Equipment, Job, Aoc, etc.)

Import connectors worden geconfigureerd in de Ultimo Configuration Tool (UCT) onder het menu Business Integration.

Connector eigenschappenbewerken

Databronnenbewerken

Bestandsgebaseerde importbewerken

De connector leest bestanden van een geconfigureerde locatie. Ondersteunde formaten: - XML - CSV - JSON

Let op bij Azure: Ultimo omgevingen op Azure hebben geen directe toegang tot FTP-servers of netwerkshares. Overweeg webservice-gebaseerde imports als alternatief.

Webservice importbewerken

De connector roept een externe webservice aan en verwerkt de response. Configuratie-opties:

Voorbeeld: GET webservice

WebServiceUrl: https://aoc-codering.nl/aoc/export/xml/#licensecodeofcustomer#
WebServiceMethod: GET

Voorbeeld: POST naar SOAP webservice

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

Beschikbare variabelen in webservice configuratiebewerken

Authenticatie voor externe webservicesbewerken

XSLT Transformatiebewerken

De kern van een import connector is de XSLT transformatie. Deze zet de externe data om naar het Ultimo XML importformaat.

Ultimo XML importformaatbewerken

Het doelformaat waar de XSLT naartoe moet transformeren:

<Data>
  <Object Type="Equipment" Action="InsertOrUpdate" ChangeStatusTo="EquipmentStatus.Active">
    <Property Name="Id" Value="00001" />
    <Property Name="Description" Value="Koelinstallatie" />
    <Property Name="ExternalId" Value="EXT-001" />
    <Property Name="Department.Id" Value="01" />
  </Object>
</Data>

Object attributenbewerken

Voorbeeld XSLT: AOC import vanuit GMGbewerken

Deze XSLT transformeert een extern XML formaat van de GMG (Gemeentelijke Model Gemeenten) naar het Ultimo importformaat:

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" encoding="UTF-8" indent="yes" />

  <xsl:template match="/Aocs">
    <Data>
      <xsl:apply-templates />
    </Data>
  </xsl:template>

  <xsl:template match="Aoc">
    <Object Type="Aoc" Action="InsertOrUpdate" ChangeStatusTo="AocStatus.Active">
      <Property Name="Id">
        <xsl:attribute name="Value">
          <xsl:choose>
            <xsl:when test="string-length(Id) &lt;= 8">
              <xsl:value-of select="concat(Id, '.00')"/>
            </xsl:when>
            <xsl:otherwise>
              <xsl:value-of select="Id"/>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:attribute>
      </Property>
      <Property Name="ExternalId" Value="{Id}" />
      <Property Name="Description" Value="{Descr}" />
      <Property Name="MainGroup" Value="{MainGroupAocId}" />
    </Object>
  </xsl:template>
</xsl:stylesheet>

Voorbeeld XSLT: Criticality import vanuit Optimizer+bewerken

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="/CriticalityUpdate">
    <Data>
      <xsl:for-each select="Changes/CriticalityChange">
        <Object Type="{OriginType}" Action="UpdateOrSkip">
          <Property Name="Id" Value="{OriginId}" />
          <xsl:choose>
            <xsl:when test="IsCritical = '0'">
              <Property Name="ImportedCriticality" Value="2" />
            </xsl:when>
            <xsl:otherwise>
              <Property Name="ImportedCriticality" Value="1" />
            </xsl:otherwise>
          </xsl:choose>
          <Property Name="ExternalStatus" Value="CriticalityUpdate" />
        </Object>
      </xsl:for-each>
    </Data>
  </xsl:template>
</xsl:stylesheet>

Voorbeeld XSLT: Geneste objecten (CAD import)bewerken

Bij geneste objecten (parent-child relaties) gebruik je ${Parent.Id} met Evaluate="true":

<Data>
  <Object Type="CadImportRun" Action="InsertOrUpdate">
    <Property Name="Context" Value="CadImportRunContext.CadImportRunSpace" />
    <Property Name="Status" Value="CadImportRunStatus.Created" />
    <xsl:for-each select="Rooms/Room">
      <Object Type="CadImportLine" Action="InsertOrUpdate">
        <Property Name="CadImportRun.Id">
          <xsl:attribute name="Value">${Parent.Id}</xsl:attribute>
          <xsl:attribute name="Evaluate">true</xsl:attribute>
        </Property>
        <Property Name="BimGuid" Value="{BimGuid}" />
        <Property Name="ImportedSpaceCode" Value="{RoomId}" />
      </Object>
    </xsl:for-each>
  </Object>
</Data>

Response XSLTbewerken

Sommige connectors hebben ook een Response XSLT geconfigureerd. Deze transformeert het Ultimo verwerkingsresultaat terug naar het formaat dat de externe partij verwacht:

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="/Data">
    <CriticalityUpdate>
      <xsl:for-each select="Object">
        <CriticalityChange>
          <IdentityTag><xsl:value-of select="Property[@Name='Id']/@Value"/></IdentityTag>
          <Result><xsl:value-of select="@Action"/></Result>
          <OriginType><xsl:value-of select="@Type"/></OriginType>
          <OriginId><xsl:value-of select="Property[@Name='Id']/@Value"/></OriginId>
        </CriticalityChange>
      </xsl:for-each>
    </CriticalityUpdate>
  </xsl:template>
</xsl:stylesheet>

Loggingbewerken

Import connectors bieden ingebouwde logging:

De Event Log in Ultimo toont per import: - Tijdstip van uitvoering - Aantal verwerkte records - Eventuele foutmeldingen per record - De connector die is gebruikt

Rollbackbewerken

Met RollbackOnError="true" worden alle wijzigingen van een import teruggedraaid als er een fout optreedt. Dit garandeert data-integriteit: ofwel alle records worden succesvol verwerkt, ofwel geen enkel record wordt gewijzigd.

Advies: Gebruik RollbackOnError="true" voor kritieke imports waar data-consistentie essentieel is (bijv. financiele data). Gebruik "false" voor bulk imports waar partiele verwerking acceptabel is.

Praktische tips voor consultantsbewerken

1. Naamgeving: Gebruik duidelijke connector ID's die de bron en het doel beschrijven (bijv. AOC_GMG_IMPORT, EQUIPMENT_SAP_SYNC)
2. DataProvider: Stel altijd een unieke DataProvider in per externe bron voor traceerbaarheid
3. Testen: Test XSLT transformaties eerst lokaal met een XML editor voordat je ze in Ultimo configureert
4. Foutafhandeling: Activeer LogErrorToEventLog altijd, ook in productie
5. Incrementele imports: Gebruik ${ImportConnector.LastImportSuccess} om alleen gewijzigde data op te halen
6. Azure migratie: Bij migratie naar Azure moeten bestandsgebaseerde imports worden omgezet naar webservice-imports

Gerelateerde artikelenbewerken

• export-connectors -- Export connectors configuratie
• rest-api -- REST API als alternatief
• http-post -- HTTP POST integratie
• soap -- SOAP/WCF integratie
• Integraties overzicht