Developer

Push

A push definition defines how to implement push notification behavior.

A push defines when it is necessary to push an object from the back-end system to the Agentry Client and how that object’s data is retrieved. A push provides real-time data synchronization for server-to-client data transfer, targeting a top-level object collection property within the same module. The push determines if changes have been made to the back-end system and also retrieves the needed data to send those changes to the client. Part of the push definition is the optional behavior to notify users when data has been pushed to their clients.

There are five child definitions to the push, each a step usage definition. These steps provide the behaviors of polling the back end system for data changes that include new or modified business objects, polling and retrieving data for objects to be removed from clients, steps to retrieve data when changes have been found during a poll, updating the back end system after the new objects have been processed, and error handling steps.

The push itself defines how often to poll the back end system for changes, whether or not to display notifications on the Client of data after is has been pushed down and the nature of that notification, and an optional action that may be executed for each object pushed down to a Client.

The Push definition is the primary definition for implementing push behavior, but it is not the only definition type involved. The application-level definition transmit configuration also plays a part in this behavior. Specifically, a transmit configuration must be defined to maintain a constant connection between the Agentry Client and Agentry Server.

Additionally, if the system connection to be used for push processing is a SQL Database connection type, the configuration file SqlBE.ini for the Agentry Server is likely to need modification. Two sections within this file, EnablePushUser and DisablePushUser are processed by the Server as a part of the overall push processing for a database system. For other system connection types this file is not involved. Information on this configuration file can be found in the Agentry Implementation Guide for both Windows and Linux.

Push Child Definitions

  • Retrieval Step: A push retrieval step references a step definition run to determine if object data has changed in the back-end system and how that data is retrieved.
  • Removal Step: A push removal step references a step definition run to determine what objects should be removed from the collection on the Agentry Client.
  • Read Step: A push read step references a step definition to be run to continue the data retrieval for the object collection targeted by the push.
  • Response Step: A push response step references a step to be run after SAP Mobile Platform Server receives notification from the Agentry Client that an object has been successfully pushed down.
  • Error Step: A push error step references a step definition to be executed when one of the other step usage definitions within the push return an error.

Push Attributes

General Attributes
  • Collection: This attribute specifies the target object collection for which the push will synchronize data. This must be a top-level object collection property within the same module as the push definition.
  • Name: This is the internal definition name for the push. This must be unique among all push definitions within the same module.
  • Display Name: This is the default display value for the push definition when reference is made to it on the Agentry Client.
  • Poll Interval: This attribute contains a duration value in hours, minutes and seconds, specifying how often to poll the back end system for modifications. At each poll interval the push retrieval steps and push removal steps will be processed by the Agentry Server. The value of the Poll Interval must be less than the transmit configuration attribute Inactive Time attribute of the transmit configuration defined to support the push behavior.
  • Read Steps: This attribute specifies whether to use the read steps defined in the object type for the push’s target collection property. When this attribute is checked, the read steps in the object type will be processed to synchronize data rather than the push read steps.
  • Queue Messages: This attribute allows for push messages from the Agentry Server to the Agentry Client to be queued if they are not successfully sent after the first attempt or if the Agentry Client indicates it is still processing the previously received message.
Notification Attributes
  • Dialog Pops Up: This attribute specifies whether or not a notification dialog is displayed on the Agentry Client after an object has been pushed down to the Client and when that dialog should be displayed. The options for this attribute are:
    • After all data received: This setting will display the notification after all objects have been successfully pushed to the Client.
    • Immediately: This setting will display the notification after each object has been successfully pushed to the Client. If multiple objects are pushed based on a single poll, the notification dialog will displayed once for each object.
    • No Dialog (sound only): This setting will not display any notification dialog to the user, with the client’s default system sound being the only one played.
    • When user clicks icon: This setting will display an icon on the Agentry Client after objects have been pushed down. The notification dialog will then not be displayed until the user clicks this icon.
  • Data Received Text: This attribute specifies whether or not to display notification text for new or replaced object instances and, if enabled, the contents of the notification message. This includes both the message to display to the user and the text in the notification dialogs title bar.
  • Data Removed Text: This attribute specifies whether or not to display notification text when object instances are removed and, if enabled, the contents of the notification message. This includes both the message to display to the user and the text in the notification dialogs title bar.
  • Rec’d & Rem’d Text: This attribute specifies whether or not to display notification text when both new object instances received from the push and other object instances are removed. If enabled, the contents of the notification message are also a part of this attribute setting. This includes both the message to display to the user and the text in the notification dialogs title bar.
  • Notification: This attribute enables or disables the external notification behavior. When enabled, the client device’s hardware LED light will be activated by the Agentry Client. This attribute has no affect on client devices without such hardware.
  • Play Sound: This attribute enables or disables the system’s default sound for notification when objects are synchronized by the push. When this attribute is enabled, the option for how many times to play the sound is set. This will also enable the Interval Between Sounds attribute.
  • Interval Between Sounds: This attribute is enabled when the Play Sound attribute is enabled and it specifies the sound be played multiple times. The Interval Between Sounds attribute then specifies the duration of time between each instance of the sound.
Action Attributes
  • Action After Object Received: This attribute references an action to execute when an object is pushed down to the Agentry Client. When an action is selected here, that action will be executed for each object instance pushed to the Client, targeting that object. This action is not executed when objects are removed based on the push synchronization. If the user is currently executing an action when an object is pushed to the client (for example, the user is viewing a transaction wizard), the action defined for the push is queued and will be executed when the current action is completed.
  • Action When Push Completes: This attribute references an action to execute when the push has finished pushing down all object instances to the Agentry Client. This action targets the object collection targeted by the push.
  • Cancel Action: This attribute specifies whether or not any action currently being executed on the Agentry Client is canceled when objects are pushed down. If this option is disabled and an action is being executed while an object is being pushed down to the Agentry Client, the object will not be received by the Agentry Client.