Smart Sync Introduction  |  Smart Sync API

 

Tutorial: Developing a simple Smart Sync Application

In this tutorial you will create a simple Smart Sync application to download master data on country information from the WebAS. In the course of the tutorial, you will

  1. Understand the business scenario
  2. Define a simple SyncBO, generate and enable it
  3. Create a Mobile Solution Descriptor that references the SyncBO
  4. Download the application's meta-data XML file
  5. Generate the client application using the Smart Sync Wizard in the MDK Plug-In for Eclipse
  6. Upload the generated application to the Web Console
  7. Assign the application to your user in the Web Console
  8. Synchronize your device to download the application
  9. Launch the application
  10. Generating demo data
  11. Running the Replicator
  12. Synchronization to receive the application's data
  13. Using the application
  14. Monitoring the data flow via the Smart Sync Monitor

The development process is a very shortened version of the steps described in the chapters Application Development Process and Defining SyncBO.

The step-by-step guides have not yet been adapted to the updated UI for the SyncBO Builder and Profile Dialog transactions in MI 2.5 (WebAS 6.40). While the guides will be updated as soon as possible, the reader should still be guided fairly smoothly throuhg the new UI by reading the online documentation on these tools in SAP Help Portal > NetWeaver > Mobile Infrastructure > MI 2.5.

 

Step 1: Scenario

Requirements

In this simplistic example, we'll download the short text and country code of certain countries available in the system in order to display them in a simple application. The application will later look like this:

Examination of BAPI Wrappers

For this tutorial, SAP already created a BAPI wrapper that is automatically available in any SAP system with mySAP Technology 6.20 or higher. The BAPI wrapper MEREP_COUNTRY_GETLIST reads a list of countries and their short texts from the tables MEREP_COUNTRY and MEREP_COUNTRYT.

You should read through the function module's code to get a better idea of this BAPI wrapper.

Step 2: Defining a SyncBO for downloading Country information

For downloading the country information, we create a SyncBO of synchronization type download. This SyncBO enables a client application to access the list of countries. Since a client application is not intended to add/modify/delete a country, this SyncBO simply needs a GetList BAPI wrapper.

The whole creation process for arbitrary SyncBO is described in chapter Defining SyncBO.

Instead of creating the SyncBO shown in this tutorial, you could also create a SyncBO for downloading contact information to your mobile device. In any SAP system with mySAP Technology 6.20 or higher, the following BAPI wrappers are provided for your convenience: MEREP_CONTACT_GETLIST, MEREP_CONTACT_GETDETAIL, MEREP_CONTACT_CREATE, MEREP_CONTACT_MODIFY and MEREP_CONTACT_DELETE. They access data from the tables MEREP_CONTACT and MEREP_CONTACTT. To fill these tables with demo data, you can use the reports MEREP_SAP_EXM002_DATA_GEN1 and MEREP_SAP_EXM002_DATA_GEN2.

 

Defining Attributes

The first step is to create a new SyncBO and assign some attributes such as the synchronization type and a method (BAPI wrapper). The standard procedure is described here.

Procedure

  1. Start the transaction merep_sbuilder.
  2. Enter a unique SyncBO ID (e.g. "ZXXX_EXM01" where "XXX" is your initials).
  3. Choose SyncBO > Create or F5.

    If the default backend system is set to another system, choose SyncBO > Create w/RFC dest or Shift + F5. Set a flag on the SyncBO Specific checkbox and leave the destination blank. For more information, refer to Setting SyncBO ID and Synchronization Type.


  4. Select D01 for Sync Type on the popup dialog.
  5. Choose the Continue icon or F8 on the popup dialog.
  6. Enter a description in the focused text box (for example, "Country SyncBO for Tutorial").
  7. Enter MEREP_COUNTRY_GETLIST in entry field Read List.
  8. Set a flag to the Type Check checkbox.
  9. Choose the Mapping screen buttonfrom the application bar or Ctrl + F3.

Result
The SyncBO Builder displays the Mapping Screen in the edit mode.

Mapping

The next step is to define the HEADER structure. In this example, the country long text is visible to the client. In addition, SYNC_KEY is also visible from the client, as is for any SyncBO. The standard procedure is described here.

Procedure

  1. Set a cursor on the text: MEREP_COUNTRY_GETLIST.
  2. Choose the Expand sub-tree icon from the application bar or Ctrl + F11 on the Mapping screen.
  3. Double-click the text: Tables.
  4. Set a flag on the Map column for LAND_TEXT field to specify the field visible to the client.
  5. Set a flag on the Filter column for LAND field to specify the filtering field.
  6. Set a flag on the Itab Key column for LAND field to specify the object key.
  7. Choose the Continue icon from the application bar or Ctrl + F3.
  8. Choose the Save icon or Ctrl + S to save the mapping.
  9. Choose the Back icon or F3 to go back to the SyncBO Builder initial screen

Result
The SyncBO Builder displays the initial screen.

The following shows the mapping result for the GetList function:

Table Tab


Setting default values

For the selection criteria, we will assign the default value of SY-LANG ABAP system variable.

Procedure

  1. Enter the SyncBO ID you have used (e.g. "ZXXX_EXM01" where "XXX" is your initials).
  2. Choose the Edit icon from the application bar or F6.
  3. Set a cursor on the text: MEREP_COUNTRY_GETLIST.
  4. Choose the Expand sub-tree icon from the application bar or Ctrl + F11 on the Mapping screen.
  5. Double-click the text: Importing.
  6. Set a cursor on the Value ID column of SPRAS field.
  7. Choose F4.
  8. Choose the Create icon or F5 on the popup dialog.
  9. Enter Value ID: LANG.
  10. Enter Text: Selection criteria.
  11. Choose the Continue icon or F8.
  12. Choose the Continue icon or F8 again.
  13. Choose the Continue icon from the application bar or Ctrl + F3.
  14. Choose the Save iconor Ctrl + S to save the mapping.
  15. Choose the Back icon or F3 to go back to the SyncBO Builder initial screen.
  16. Choose Environment g Default values.
  17. Enter Value for LANG: SY-LANG.
  18. Choose the Save icon or Ctrl + S.
  19. Choose the Back icon or F3 to go back to the SyncBO Builder initial screen

Result
The SyncBO Builder displays the initial screen.

The following shows the mapping result for GetList function after setting the Value ID:

 

Generation of synchronizer

After completing the mapping, the synchronizer needs to be generated. The standard procedure is described here.

Procedure

  1. Enter the SyncBO ID you have used (e.g. "ZXXX_EXM01" where "XXX" is your initials).
  2. Choose the Generate/Activate SyncBO icon from the application bar or Ctrl + F3

Result
The SyncBO Builder displays "SyncBO ZXXX_EXM01 has been successfully generated" on the message bar of the initial screen.

Setting filtering criteria

The last setting is to assign filtering criteria of the SyncBO. The standard procedure is described here. As an example, we will restrict the values to 3 countries (DE, JP or US).

Procedure

  1. Enter the SyncBO ID you have used (e.g. "ZXXX_EXM01" where "XXX" is your initials).
  2. Choose Environment g Filtering criteria.
  3. Enter the following on the SyncBO Dependent tab:



  4. Choose the Save icon from the application bar or Ctrl + S

Result
The SyncBO Builder displays the initial screen.

Enabling the SyncBO

The Synchronizer of a SyncBO needs to be manually enabled in the Profile Dialog in order to be an active runtime object.

Procedure

  1. Log on to the SAP Web Application Server
  2. Start the Profile Dialog by entering the transaction code /nmerep_pd into the transaction field in the top left corner of your SAP Gui.
  3. Choose tab Synchronizer
  4. Enter the SyncBO ID you have used (e.g. "ZXXX_EXM01" where "XXX" is your initials) and press Enter. The system will jump to the sub tab strip corresponding to your SyncBO type.
  5. Choose the Change<->Display icon from the application bar or F5.
  6. Check the check box in column Enabled for your SyncBO.
  7. Choose the Save icon from the application bar or Ctrl + S

Result
The Profile Dialog displays "Saved successfully" in the message bar. The SyncBO is now ready for productive usage.

Step 3: Register the Application

We now need to create a Mobile Solution Descriptor for this application. Among others, the MSD contains the information which SyncBO an application is using. To date, the MSD needs to be created via the procedure described here.

You should use the following input values

Parameter name

Proposed value (if no value is given, you should leave the field blank)
I_NAMESPACE  
I_NAME MDK_TUTORIAL
I_VERSION 01
I_TEXT Smart Sync Tutorial from MDK
I_APPTYPE JSP
I_BUILDNUMBER  
I_FRAMEWORK_FROM  
I_FRAMEWORK_TO  
I_HOMEPAGE_INVISIBLE  
I_ACTION A
I_SYNCBO

Enter the SyncBO ID you have used (e.g. "ZXXX_EXM01" where "XXX" is your initials) by doing the following:

  1. Click on the icon for parameter I_SYNCBO
  2. Enter the SyncBO ID in entry field in column SCENARIO.
  3. Click on or F3.

 

If everything was successful, the table RETURN should contain the message 'Saved successfully' after executing the function module. This means that the MSD was created successfully. You can also find it in the MI Web Console now.

Step 4: Downloading the Meta Data XML File

The application's object model defined in step 2 and step 3 is made available to the MI Client in the form of a so-called meta-data XML file. This file is generated from within the SyncBO Builder as describe here.

After successful download, double-click on the meta-data XML to display the file in a browser. It should look very much like this file. The file contains all information that the MI Client needs in order to interpret the Smart Sync data from the MI server. Specifically, you can find the information, that

For further information on the structure of the meta-data XML, click here.

Step 5: Create a the Client Application

With the XML file you can generate a complete client application that uses the MI SmartSync API by using the MDK Eclipse plugin as describe in Creating a New SmartSync Project. Be sure to adapt the web.xml file as described there.

After generating the application, you need to create a .war file for the application. To get the .war file, just use the Export functionality of the MDK Plug-In. When exporting the application, make sure that the application's file is copied to a folder DIFFERENT from <MI Home>/webapps and that the checkbox Run is not checked. This is mandatory, because otherwise the client application is deployed to MI Client directly without going via the Web Console. In our case, the application needs to be deployed via the Web Console to ensure that all necessary identifiers (Mobile ID, Device ID, Device Guid, Conversation ID) are generated.

Step 6: Upload Application

The war file now needs to be made ready for deployment via the Web Console by uploading the application's file.

Procedure

  1. Logon to the Web Console
  2. Switch to tab Upload Application
  3. Find the entry MDK_TUTORIAL in the list of applications
  4. Click the Change button
  5. In the field Application File, browse to the application's war file
  6. Submit by clicking the Change button

If you have problems performing the above procedure, you may need to delete the application first and then recreate it under the same name as described here.

Step 7: Assign the Application to a User

You now need to assign the application to your user or role as described here. During development, it's often simpler to use user-based deployment rather than role-based deployment.

Step 8: Synchronize your device to download the application

Synchronize your device to download the assigned application as described here. After successful download and restart of MI Client, the application is extracted, registered with the framework and is now ready for usage.

Step 9: Launch the Application

After restarting MI Client, you can launch the application by clicking its link on the MI Home page.

At the current stage, no demo data have been created yet. Therefore, no data have yet been downloaded to the device and can be displayed in the application as displayed in the grafic below.

Step 10: Generating Demo Data

We'll now create demo master data for country information using a special report that fills the tables MEREP_COUNTRY and MEREP_COUNTRYT. In normal Smart Sync applications, your business data would already be present of course and this generation step would not be necessary.

  1. Logon to the WebAS using SAP Gui.
  2. Start transaction SE38 by entering /nse38 into the entry field in the top left corner of your screen. Transaction SE38 allows you to start reports in the WebAS.
  3. Enter the report name MEREP_SAP_EXM001_DATA_GEN1 field Program and choose Execute (F8).

Result
Sample data is generated in the tables MEREP_COUNTRY and MEREP_COUNTRYT. The sample data can be viewed using the Data Browser (transaction SE16).

Two similar reports exist if you want to create a Contact SyncBO. The report are MEREP_SAP_EXM002_DATA_GEN1 and MEREP_SAP_EXM002_DATA_GEN2. They generate demo data for the tables MEREP_CONTACT and MEREP_CONTACTT. The BAPIs for accessing the data are MEREP_CONTACT_GETLIST, MEREP_CONTACT_GETDETAIL, MEREP_CONTACT_CREATE, MEREP_CONTACT_MODIFY and MEREP_CONTACT_DELETE.

Step 11: Executing the Replicator

The replicator is a function module generated by the Smart Synchronization code generator that is used to replicate application data from the backend system to the Smart Synchronization Replica DB.

We will now manually trigger the replicator in order to copy the 'application data' (that is the data in tables MEREP_COUNTRY and MEREP_COUNTRYT) into the Replica DB.

Procedure

  1. Logon to the WebAS using SAP Gui.
  2. Start transaction MEREP_EX_REPLIC by entering /nmerep_ex_replic into the entry field in the top left corner of your screen.
  3. Enter the SyncBO ID you have used (e.g. "ZXXX_EXM01" where "XXX" is your initials) into field SyncBO ID and choose the Execute icon or F8.

Result

A log is displayed with details on all changes performed on the Replica DB.

Step 12: Synchronization

Now that the Replica DB is filled, the data will automatically be sent down to the mobile device on next synchronization. Technically speaking, on synchronization each registered application sends a request to the Replica DB, asks for updates and sends down all changes that have happened locally on the device since last sync.

Synchronize your device as described here.

Step 13: Using the application

After synchronization and reception of its data, MI Client needs to be restarted. This is currently a short-coming in the generated code and will be overcome in the next edition of MDK.
Launch the application via the link on the MI home page. The screen flow is as in the grafic below. Use the Home button to return to the MI Home page, use the Back button to go one screen back.

Step 14: Smart Sync Monitoring

The complete data flow between MI Client and WebAS can be monitored closely using the Smart Sync Monitor. Please follow the administration documentation for more information.