Developer

Fetch Development Using the Exchange Data Model

The design and development of fetch to synchronize an object collection should always be based on the exchange data model. The child definitions of a fetch, as well as object read steps and the object itself, are organized and architected with the intent of using this model. The main tasks to accomplish when developing a fetch to use the exchange data model are:
  1. Create or configure the exchange components in the back end system to be used both during the synchronization process, as well as to track changes to the back end system between client transmits. These components should track the unique identifier values for each business entity, the date and time of the change, and the nature of the change. This last includes tracing the addition of new instances, modification of existing data, or the removal or other modification to be treated as a removal by the Agentry application.
  2. Define the fetch to determine and record in the exchange components what objects the Client contains at the beginning of the synchronization process. This includes the date and time when each object was last retrieved from the back end system.
  3. Define the fetch to use the exchange and tracking components in the back end system to determine what object-related data has been added or modified since the last time the Client synchronized.
  4. Define the fetch to use the exchange data generated in the previous steps to determine the differences between the Client objects and the back end data. Retrieve only those objects that need to be added or replaced, and define the fetch removal steps to retrieve the key property values of those objects to be deleted from the Client.

Back End Exchange Data and Tracking Components

The design and creation or configuration of the back end components used in the exchange data model have certain general requirements. These requirements hold true regardless of the contents of the object data being synchronized.

Beginning with the tracking components, the purpose of these items is to track changes of interest to the object data in the back end system that occur between transmits from the Client. These components should track changes to the object data in the back end system. Depending on the nature of the back end system, changes to track can include adding new objects, modifying the data of an existing object to be reflected on the Client, or the deletion or modification of an object that should result in that object being removed from the Client.

When one of these changes occurs, the information recorded must include:
  • The value or values that uniquely identify the modified object in both the back end system and the Agentry application.
  • The date and time, as provided by the back end system, when the change occurred.
  • The nature of the change, that is, is it a new object, a modification, or a removal.

The Object Last Update Value

The object definition type is capable of storing a date and time value called lastUpdate. This data value is separate and in addition to the defined properties of the object. The date and time value it stores must be returned with the object data during synchronization and aliased as “lastUpdate.” The proper source for this value is the current date and time of the back end system when the object data is retrieved.

The purpose of the lastUpdate value is to store the date and time of the back end system when the object was retrieved. Each object instance has its own lastUpdate value. This value is stored with the object instance on the Client. It is accessible during subsequent synchronizations via the SDML tag <<lastUpdate>> and is intended to be used to determine whether changes have occurred on the back end system for the object since it was retrieved for the Client. It should be compared with the date and time value recorded by the back end tracking components for the same object.

This value is only accessible during synchronization and, while stored with the object instance on the Client, it is not exposed on the Client. It is not a property value and cannot be displayed to the user nor modified as a result of any client-side processing.

Client Exchange Steps in the Exchange Data Model

A fetch client exchange step defines how information about the target collection is processed bySAP Mobile Platform Server. This definition references a step definition within the same module. This step has access to information about the target collection, as well as to any data captured in fetch properties. A client exchange step can be defined to execute once or iteratively, and can return data for an object collection. A fetch can contain multiple client exchange step definitions, which are processed by the Server in a defined order.

When a client exchange step is executed iteratively, its iterations are based on the object instances sent to the Server by the Client. The client exchange step then has access to the object’s key property value and the object’s lastUpdate value. If fetch properties have been defined, the client exchange steps of that fetch will also have access to all of these property values, regardless of how the client exchange step has been defined to execute.

The intended purpose of client exchange steps is to update the back end exchange data components with information about what object instances currently exist on the Client in the target collection of the fetch. This information should include the key property of each object and the lastUpdate value. Along with these values the client exchange step should also provide information about the user to whom the object belongs (SDML tag: <<user.agentryID>>). Finally it is a recommended practice that the Agentry Server instance also be uniquely identified (SDML tag: <<server.serialNumber>>).

Another task commonly handled by the client exchange steps is to clear out the exchange data for the current user from the previous synchronization. The step defined to accomplish this task should delete this data based on the user ID and, in most cases, also the Server’s serial number. This client exchange step is run as the first step for the fetch. It is then followed by the client exchange step defined to provide the exchange data about the current objects on the Client.

When the client exchange steps of a fetch have completed processing during synchronization, the back end exchange data components should contain the information about what object instances currently exist on the Client and the date and time each was last retrieved from the back end system.

Server Exchange Steps in the Exchange Data Model

A fetch server exchange step defines how information about the back-end system’s data is processed. This definition references a step definition within the same module. This step has access to information about the target collection, as well as to any data captured in fetch properties. A server exchange step can be defined to execute once or iteratively, and can return data for an object collection.

Server exchange steps are always processed after client exchange steps. The intended purpose of a server exchange step is to determine what changes have occurred in the back end system to the object data for the user and to then either mark the objects in the exchange data components as those in need of retrieval, or to perform the actual retrieval of the object data. Which behavior is defined is dependent on the type of back end system and its capabilities and behaviors, as well as the overall needs of the mobile application being developed.

Changes or differences between the Client objects and the back end data are found by comparing the information about the current Client-side object instances provided by the back end exchange data component with the information captured in the back end tracking components. The tracking components will contain the date and time when any object data has changed on the back end system, along with the unique identifier for that object. The exchange component will contain the date and time when the object instances were retrieved. The server exchange steps then should contain the logic to compare the information in the tracking components with the information in the exchange components. When an object is found to have been changed in the back end system more recently then it was downloaded to the Client, that object is one in need of replacement on the Client. Any new objects created in the back end system will not have a corresponding item in the exchange component. Such objects should also be treated as those in need of retrieval for the Client.

When differences are found, the functionality can take one of two directions. First, any changes for existing objects result in the object record in the exchange component being flagged or marked in some manner indicating the object should be replaced. Any new objects in the back end system not found in the exchange data components are added to the exchange component. This information includes the unique identifier, or key property of the object, the user ID, the server ID, the current date and time, and finally the same flag or indicator that the object should be retrieved. In this scenario, the actual object data is not yet retrieved. This logic is most common with SQL systems. In this scenario the data retrieval is then left to either additional server exchange steps, or, more commonly is handled by object read steps.

The second option is define the steps used as server exchange steps to make the determination about which objects need to be retrieved and to retrieve that data at the same time. In this situation, the server exchange steps do not update the exchange component with the information about the new changes in the back end. Instead, the data in the back end exchange component as provided by the client exchange steps is used only for comparison purposes with the tracking components. This logic is most common with Java and Web Service (HTTP-XML) systems.

Fetch Removal Steps in the Exchange Data Model

A fetch removal step is defined to determine which objects should be removed from the collection targeted by the parent fetch. A removal step references a step definition within the same module. This step has access to information about the target collection, as well as to any data captured in fetch properties. The step referenced by a removal step definition is expected to return the key property of any object(s) that should be deleted from the target collection on the Agentry Client.

The removal steps defined within the exchange data model should use the exchange data components to determine what objects the client has. It should interrogate the corresponding data in the back end system to determine if any of those objects should be removed from the Client. The removal of a Client object can occur in many situations, only one of which is the actual deletion of the dat in the back end system. In point of fact, this is usually the least likely situation, as most enterprise systems do not remove data once it has been added.

The removal steps can use the data in the back end exchange data component to look for object data for a user in need of removal. As an example, if a user currently has work order 123 on his Client and that same work order has been reassigned in the back end system to a different user, the removal step can return the key property of that work order object so that it is removed.

Object Read Steps in the Exchange Data Model

An object read step references a step definition within the same module. Its purpose is to retrieve data for instances of the object from the back-end system. The steps are processed by the server during a transmit. The step being referenced can be executed once per transmit or iteratively.

Object read steps may be run at different times during a transmit. One of these times is as a part of fetch processing. Object read steps are not required to retrieve data during fetch processing, as both client exchange and server exchange steps can accomplish this task. However, it is common to use object read steps for this purpose. In the exchange data model, the fetch is processed to determine what changes have been made to the back end data and the object read steps are then run to perform the actual retrieval. One of the primary reasons for this division is simple organization of the project.

When used in the exchange data model the steps executed as object read steps should contain logic to use the exchange data generated by the fetch processing. The object read steps should retrieve only that object data related to objects in need of retrieval or replacement on the Client. The processing of the object read steps and the logic executed should be the final culmination of all exchange data model processing performed to this point. The read steps take advantage of the information generated and gathered by the child definitions for the fetch, retrieving only the objects needed by the Client and excluding the retrieval of any unchanged objects.