5.2.1.3.4. Beispiel: Datenübertragung

Aufgabenstellung:
Es sollen per Knopfdruck Teile einer gerade geöffneten Firma aus einer Business App CRM-Instanz in eine andere Instanz unter Nutzung deren Standard-REST-API übertragen werden. Diese Teile umfassen Name, Suchnamen und Anschriften der aktuellen Firma. Der Name soll bei der Übertragung den Vermerk “[aus Instanz 1]” angehängt bekommen. Die Oid der neu erstellten Firma soll über das Feld ExternalGuid mit der aktuellen Firma verknüpft werden.

Vorgehen:
1. Authentifizierung
Wir verwenden eine Modifikation des ausgelieferten JWT-Login-Webservices zur Authentifizierung an der anderen Business App CRM-Instanz. Hinweis: Ein Authentifizierungs-Webservice kann nicht für mehrere Instanzen verwendet werden, das heißt, sollte der JWT-Webservice schon auf eine andere Instanz verweisen, muss eine Kopie mit einer neuen eindeutigen ID angelegt werden. Aber für das Beispiel gehen wir einmal davon aus, dass der Webservice noch nicht verwendet wird.

<WebServiceModification id="BA.Login.JWT">
  <Url>https://otherserver.gedys-intraware.de/otherbacrm/api/auth/login</Url>
  <OutboundMappings>
   <Mapping>
     <From type="text">my_username</From>
     <To>Username</To>
   </Mapping>
   <Mapping>
     <From type="text">my_secret_password</From>
     <To>Password</To>
   </Mapping>
  </OutboundMappings>
</WebServiceModification>

2. Anschriften
Die Anschriften sind quasi ein Mehrfachwert, d. h. hierfür wird ein Mehrfachwert-Mapping benötigt. Sinnvollerweise verwenden wir dieses zusammen mit einer Mapping-Vorlage.

<MappingTemplate id="Custom.Example.AddressMapping" sourceType="OrmSubAddressCompany" targetType="OrmSubAddressCompany">
  <Mapping>
    <From type="enum">AddressType</From>
    <To>AddressType</To>
  </Mapping>
  <Mapping>
    <From>[Address]</From>
    <To>Address</To>
  </Mapping>
  <Mapping>
    <From>[PostalCode]</From>
    <To>PostalCode</To>
  </Mapping>
  <Mapping>
    <From>[City]</From>
    <To>City</To>
  </Mapping>
  <Mapping>
    <From type="enum">StateSelection</From>
    <To>StateSelection</To>
  </Mapping>
  <Mapping>
    <From type="enum">Country</From>
    <To>Country</To>
  </Mapping>
</MappingTemplate>

3. Webservice
Am Ende benötigen wir die eigentliche Webservice-Definition mit Verwendung der Authentifizierung, der Mapping-Vorlage und den restlichen ein- und ausgehenden Mappings.
Die Definition verwendet zur Authentifizierung den obigen JWT-Webservice, definiert HTTP-Methode und URL zur Zielinstanz, ein URL-Mapping, um der Standard REST-API mitteilen zu können, welcher Datentap erstellt werden soll und die notwendigen ein- und ausgehenden Mappings.

Achtung: Das Feld ExternalGuid ist vom Datentyp her tatsächlich eine richtige Guid, vom Zielsystem bekommen wir aber einen String, d.h. dieser Wert muss umgewandelt werden!

<WebService id="Custom.Example.TransferCompany" displayName="Firma nach Instanz 2 übertragen" outboundModelType="OrmCRMCompany" inboundModelType="OrmCRMCompany">
  <Method>POST</Method>

  <Url>https://otherserver.gedys-intraware.de/otherbacrm/rest/v1/record/{ormtype}</Url>

  <UrlMappings>
    <Mapping>
      <From>[OrmType]</From>
      <To>ormtype</To>
    </Mapping>
  </UrlMappings>

  <Authentication>
    <JWT serviceRef="BA.Login.JWT" />
  </Authentication>

  <OutboundMappings>
    <Mapping>
      <From>[Name]</From>
      <To>Name</To>
      <Transform>[This] + ' [aus Instanz 1]'</Transform>
    </Mapping>
    <Mapping>
      <From>[SearchNames]</From>
      <To>SearchNames</To>
    </Mapping>
    <MultiValueMapping>
      <From>Addresses</From>
      <To>Addresses</To>
      <RowMappings targetRowType="OrmSubAddressCompany">
        <TemplateMapping ref="Custom.Example.AddressMapping"/>
      </RowMappings>
    </MultiValueMapping>
  </OutboundMappings>

  <InboundMappings>
    <Mapping>
      <From>$.Oid</From>
      <To>ExternalGuid</To>
      <Transform>BAToGuid([This])</Transform>
    </Mapping>
  </InboundMappings>      
</WebService>