Overview

The document describes the approach in integrating other business systems ( other than the supported by default ) with Dynamics Mobile.

Dynamics Mobile provides public REST API allowing integration of other business systems. The integration allows the mobile applications to work with different business software systems by receiving and sending data to them.

High level architecture

The integration process is built around the idea that Dynamics Mobile platform stands between the mobile applications and the business system (ERP) and facilitates the communication between them.

The users are using the Dynamics Mobile application on their mobile devices ( Android, iOS, Windows 10). The mobile app is "connected" to specific application area. The ERP is communication with the Dynamics Mobile Platform via calls to REST APIs over internet using https. Every ERP is "connected" to specific application are and hence communicating with the mobile users in this application area only.

The integration is built over the following concepts:

1. Synchronization Packet Description of the business data in terms of entities(tables) and members(fields), exchanged between the mobile application and the ERP in predefined XML or JSON format.

2. Push Used to describe the process of sending synchronization packet from the ERP to specific the mobile user via the integration REST API.

3. Pull Used to describe the process of sending synchronization packet from the mobile application to the ERP via the integration REST API.​

4. Integration API REST API accessible via internet over https ,which can be used by the ERP to communicate with the mobile users.

5. Mobile User Named user registered on the platform, who is using Dynamics Mobile application within specific application area

6. Mobile Application Mobile application developed with the Dynamics Mobile SDK.

ERP Push process

The mobile application is able to store business data locally, which is then used in offline mode - e.g. all data related queries are executed against the mobile application's data storage. This requires that the mobile application is able to obtain the business data in advance and store it . The process of sending data from the ERP to the mobile application is called PUSH.

The diagram shows the steps involved in the ERP Push process. Only the steps with blue color ( having <<ERP>> role) must be implemented by the ERP. The rest of the steps are part of the Dynamics Mobile synchronization process.

The ERP Push process is entirely orchestrated by the ERP - e.g. the ERP shall decide when and how often to execute the ERP Push process. The frequence depends mostly from the actual business process but the frequency of the PUSH processing must meet the application area default limits. The ERP Push process goes through the following steps. Please not that only the first 3 steps must be implemented by the ERP.

1. Prepare Sync packet for one mobile user The ERP push process starts with the preparation of the data to be sent to the mobile application. The process is supposed to "extract" the data from the ERP which will be sent. The data must be stored locally ( file system or memory) in one of the supported Synchronization Packet formats. Note that the actual synchronization packet content must be aligned with the data model expected by the specific mobile application. For example , of the mobile user works with the Dynamics Mobile Field Sales app, the packet must always contain the DeviceSetup entity. IMPORTANT: the packet is expected to be a complete data snapshot - e.g. containing all the data required from the mobile app to work. The ERP Push sync packet completely replaces the data stored on the device. This avoids the need to work with incremental updates and implement complex multi-table record change schemes.

2. call Push REST api Once the sync packet for the specific mobile user is prepared, the ERP must call the ERP Push api over internet to obtain temporary upload link. The link can be then used in the next step to upload the actual sync packet content.

3. Upload sync packet The ERP must use the temporary upload link obtain in step #2, to upload the packet content. The upload process must begin within 15 minutes from the temporary link obtaining. This timeout might change in the future. The maximum upload size of single sync packet is up to 100Mb.

4. Validate and Process ( the ERP must not implement this step ) Dynamics Mobile Platform will transform the packet to mobile native format and will store it in the cloud

5. Notify Mobile User ( the ERP must not implement this step) Dynamics Mobile Platform will send notification to the mobile user. The mobile user will see a message on the mobile device, which alerts that there is a new data waiting for download.

6. Mobile User Initiates synchronization (the ERP must not implement this step) The mobile user initiates the synchronization process by tapping over the Sync button (or uses the pull-to-sync from the top of the mobile screen ) in the mobile app

7. Data snapshot downloaded (the ERP must not implement this step)

   The mobile application downloads the snapshot in native mobile format from the cloud as well as other settings and artefacts. The downloaded snapshot replaces the currently stored data on the mobile device

​

 //EXAMPLE PSUEDO CODE used to upload master data for 
 //specific application area for specific mobile user   
 void generateMobileUserMasterData(string appArea, string restApiKey, string userName) {
   DataTable customers  = extractDataForTable('Customers',mobileUser);
   DataTable   = extractDataForTable('Products',mobileUser);
   DataTable  = extractDataForTable('Inventory',mobileUser);
   //... do this for all tables which has to be sent to the mobile user
   
​
   const PushAPIUrl = 'https://api.portal.dynamicsmobile.com/erp/push/'+appArea+'/'+mobileUser;
   //prepare XML sync packet from the prepared data
   const syncPacketInXml  = prepareDynamicsMobileSyncPacketFrom(customers, products, inventory);
   //retreive temporary upload path from the REST api
   const tempUploadUrl = await callRestApiWithGet(PushAPIUrl,restApiKey);
   //use the reveived temporary url to upload the packet content
   await callRestApiWithPut(tempUploadUrl, syncPacketInXml);
 }
 
 DataTable extractDataForTable(string tableName, string mobileUser) {
    DataSet result;
    using(SqlConnection connection = new SqlConnection()){
          SqlDataAdapter da = new SqlDataAdapter();
          SqlCommand cmd = conn.CreateCommand();   
          //thinks about reducing the exteacted data by filtering the dataset over
          //username or/and period of activity 
          cmd.CommandText = "SELECT * FROM "+tableName+" ORDER BY NAME"           
          da.SelectCommand = cmd;
          da.Fill(ds);
     }
     return ds.Tables[0];    
 }

ERP Pull process

The mobile applications has the ability to work in off-line mode, which means that they consume locally stored business data, and also they write the changes locally. However, it is important for the mobile device to be able to notify the ERP system for the changes. This is achieved via sending of synchronization packets from the mobile application to Dynamics Mobile Platform. The synchronization packets are stored in the cloud and can be "downloaded" by the ERP via calls to the integration REST api.

The ERP Pull process goes through the following steps.

1. Mobile User Interacts with the mobile app The mobile user uses the app to complete some activities - creating new Sales Order for example

2. The mobile app sends one or more sync packets The mobile application prepares and stores locally a synchronization packet , which contains description of the data change ( data insertions, modifications,deletions, etc. ). The packets are automatically sent to the cloud, once internet connection is detected.

3. Dynamics Mobile Platform stores the packets The Dynamics Mobile Platform receives the packets and stores them for later processing. The packets are now accessible from the integration REST API.

4. call ERP Pull REST API The ERP calls the ERP Pull REST API. We recommend the ERP to implement recurring polls if this API to check regularly for inbound mobile packets during the day. Please note that the frequency of the calls may not exceed the application area limits. ( e.g. call this API once per 5 minutes)

5. receive Pending Packets List The ERP receives a json (or xml) response containing the list of the pending packets received from the mobile applications. The list contains up to 10 sync packets per API call. If there are more than 10 sync packets pending, the next 10 packets will be received on the next call. The list may be returned in xml or json format depending on the format "preferred" from the ERP. The erp will start to iterate over the array of the received pending packets and execute the following steps for each packet from the list:

   1. call ERP Pull Download Link REST API The ERP calls the ERP Get Pull Download Link REST API for each packet to obtain temporary download link, which can be used within 15 minutes. This timeout may be changed in the future. The call returns a string representing temporary download url

   2. Download packet The ERP must download the packet content by executing GET https request against the temporary link, which will return the XML ( or json ) content of the SyncPacket.

   3. Process packet The ERP may now parse and process the downloaded sync packet content by creating corresponding transactions in the ERP based on the received content. The actual processing here is specific to the actual content received and the specifics of the ERP.

   ​

6. call Packet Status Done REST API Once all the packets from the list are processed, the ERP must call the Packet Status Done REST API to notify Dynamics Mobile Cloud that the last 10 packets were successfully processed. Dynamics Mobile Cloud will remove these packets from the queue and will not include them in the next poll to ERP Pull REST API

​

 //EXAMPLE PSUEDO CODE used to download pull packets from Dynamics Mobile Platform
 void pollForInboundDynamicsMobilePackets(string appArea, string restApiKey) {
   
​
   string pullAPIUrl = "https://api.portal.dynamicsmobile.com/erp/pull/"+appArea;
   string getDownloadLinkAPIUrl = "https://api.portal.dynamicsmobile.com/erp/pull/"+appArea+"/link";
   const inboundSyncPacketList = callRestApiWithGet(PullAPIUrl, restApiKey);
   foreach(var packet in inboundSyncPacketList){
   
         const packetDownloadLink = callRestApiWithGet(getDownloadLinkAPIUrl, restApiKey);
         const packetXmlContent = callRestApiWithGet(packetDownloadLink);
         XmlDocument doc = new XmlDocument();
         doc.LoadXml(packetXmlContent);
         processPacketXmlContent(doc); 
   } 
   
   MarkPacketAsDoneApiUrl = "https://api.portal.dynamicsmobile.com/erp/pull/"+appArea+"/done"   
   await callRestApiWithPost(MarkPacketAsDoneApiUrl ,restApiKey, inboundSyncPacketList );
 }
 

​