Developer Documentation

Data is exchanged in Mobilengine integration as XML messages called data packages. The schema for each type of data package exchanged in a Mobilengine integration solution must be set up in an integration message schema file, which must be coordinated out of band between the systems involved in the data exchange before data transfer can begin.

If multiple data packages are sent across the network simultaneously, the order that they arrive at the receiving system might not match the order in which the initiating system has sent them. The initiating system must make sure that, if the order of the data packages matters, only one package is transferred at any one time.

The receiving system must respond to an EnqueueDacs request within the HTTP response timeout. If completely processing the message takes longer than the timeout, the receiving system should store the incoming data package and process it asynchronously.

The EnqueueDacsResponse is an acknowledgement response only, and cannot be made to carry data. If the result of processing a data package needs to be reported back to the initiating system, the report must be implemented as a separate data package transferred in the opposite direction, with the two systems swapping roles.

The initiating system will resend each data package until it receives an accepted response for it, even if the receiving system has in fact received the data package and responded in time, but the response did not get through due to a network error. Because of this, the receiving system may have one or more duplicates of a data package.

To counter this, the initiating system must set the dacsid attribute on the dacs root element of each data package to a value that uniquely identifies the data package. The initiating system must use the same unique package identifier when resending a data package.

The sample below is a data package containing a message that conforms to the generalElement.dacsem schema. Note the dacsid attribute on the dacs root element.

<dacs dacsid="7c92c738-9352-423a-8941-04b38d05f5a4"
  dtu="2015-10-28T13:56:00.3027067Z"
  meta="rockyJupiter:generalElement">
  <Key>8cabea05026d45b697ee335c055a570a</Key>
  <Content>
    <splat xmlns="http://schemas.rockyjupiter.com/generalElement">
      <squish swoosh="66"/>
    </splat>
  </Content>
</dacs>

The WDX protocol requires an encrypted HTTPS connection to ensure the confidentiality of the data transferred over a Mobilengine integration solution, and authenticates the initiating system by requiring an endpoint-specific pre-shared API key to be included with each data package.

The API key must be inserted in the Key element before the Content wrapper element that contains the data package itself.

The sample below is a data package containing a message that conforms to the generalElement.dacsem schema. The Key element contains the API key for the sampleInbound inbound endpoint which this package was received through.

<dacs dacsid="7c92c738-9352-423a-8941-04b38d05f5a4"
  dtu="2015-10-28T13:56:00.3027067Z"
  meta="rockyJupiter:generalElement">
  <Key>8cabea05026d45b697ee335c055a570a</Key>
  <Content>
    <splat xmlns="http://schemas.rockyjupiter.com/generalElement">
      <squish swoosh="66"/>
    </splat>
  </Content>
</dacs>

When the Mobilengine Cloud is acting as the initiating system in an integration solution, workflow scripts are used to process, create, populate, and send integration messages over outbound endpoints.

The dacstype.New() method is used to create new instances of integration data packages based on integration message schema. Various methods on the dacsout object are used to populate the data packages, and the dacsout.Send() method is used to start the transfer of a completed data package to the integrated web service.

The Mobilengine Cloud accepts and transfers data packages over inbound and outbound integration endpoints respectively, which need to be set up on the Backoffice site on the Dev console>Integration screen using the Add outbound endpoint, or Add inbound endpoint links, and then configured using an intconf.xml configuration file.

Figure 430. The Dev console>Integration screen showing the links to create new endpoints

An endpoint can also be disabled on the Wdx Status screen by clicking toggle in the Accept messages column of its description.

Figure 431. The Wdx Status screen on the Backoffice site showing the enable/disable toggle

When you set up an inbound integration endpoint, you have the option to have the Cloud send a report of completed data package processing over an outbound endpoint of your choice.

If an outbound endpoint on the Mobilengine Cloud does not receive a response within the 1-minute HTTP response timeout after sending an EnqueueDacs request, it will attempt to resend the data package after a preset delay. The default delay is half a minute, which you can modify on the Backoffice of the Dev console>Integration>Add outbound endpoint screen in the Retry frequency box.

Figure 432. Setting up how often and how long an outbound endpoint will retry delivering an EnqueueDacs

Outbound endpoints also have a time limit for how long an EnqueueDacs request will be retried before the endpoint moves on to the next integration message in the queue. The default is one day, which you can modify on the Backoffice of the Dev console>Integration>Add outbound endpoint screen in the Retry duration box.

When the Mobilengine Cloud is receiving integration data packages through an inbound endpoint, the meta attribute of the received integration message is compared to the list of accepted message schema definitons in the WSDL service contract. If the type of the received message does not match one of the allowed message schema for the integration solution, the data package is rejected, and the EnqueueDacsFail SOAP fault is sent back to the initiating system.

The outbound endpoints of the Mobilengine Cloud prevent a mismatch between the order of dispatch and the order of delivery for data packages by sending packages one by one. The Cloud will only start transmitting a data package after it has received an EnqueueDacsResponse or EnqueueDacsFail SOAP response for the previously sent data package.

If the Mobilengine Cloud is receiving data packages through an inbound endpoint, a standard acknowledgement response can be set up to be transferred to the initiating system asynchronously whenever the processing of a previously transferred data package has been completed. This standard response is called a DacsDone, and you can configure an inbound endpoint to send one for each processed data package on the Backoffice site, on the Dev console>Integration>Add inbound endpoint>Create inbound endpoint screen in the Asynchronous ACK dropdown menu.

Figure 433. Use the dropdown menu when creating or modifying an inbound endpoint to select the outbound endpoint to handle the DacsDone response

A report that the processing of a data package has been completed, transferred from the receiving system to the initializing system as a regular data package with restricted content. See the section about Mobilengine-specific asynchronous data processing, above.

<DacsDone
  dacsidReplyTo="dacsid"
  kres="processing-result"
  message="error-message"/>

To detect duplicate packages, inbound endpoints on the Mobilengine Cloud store the dacsid of every data package that they have accepted, and compare any newly arriving data package's identifier to the stored list. Arriving data packages with identifiers matching a previous identifier are ignored.

When you set up an integration endpoint on the Backoffice site, an API key is automatically generated for the endpoint. In case of outbound endpoints, developers have the option to enter a key manually when creating or editing the endpoint.

Figure 434. The user-editable Key box on the Create outbound endpoint screen

If the key in a data package is missing or does not match the key for any of the configured endpoints, the Mobilengine Cloud responds with an EnqueueDacsFail SOAP response that carries the unauthorized error message.