Developer

Push Retrieval Step

A step definition for retrieving data if it changes at the source.

A push retrieval step references a step definition run to determine if data has changed in the back-end system and how that data is retrieved. A retrieval step can be executed either once, or iteratively based on the number of users logged in to receive push data. A push retrieval step is run as a part of the back-end polling performed by the push. The step referenced by a push retrieval step is expected to return the key property of any object instances to be pushed to the Agentry Client. It may also return additional property values for the object type. If defined to one run once per poll period it is also expected to return the Client user ID to which the object will be sent.

A push retrieval step can also return data for the object type targeted by the fetch, as well as for its child objects. However, it is recommended that child, or nested collections be synchronized by the push read steps or the object read steps (depending on how the push is defined). Since retrieval steps are run every poll period, the step definitions they use should be defined to perform the least amount of processing necessary to determine if new object data needs to be retrieved. Non-collection property values for the target object type can also be retrieved by the retrieval step in this model, but no additional data should be retrieved here for the sake of efficiency of the push’s polling activity.

The retrieval step may be executed, or run, in one of two ways for a given poll. First it may be defined to run once per user currently logged in to receive push data. For this type of execution, the data returned by the retrieval step will be organized internally by the Server for each user. The step being run should then include logic that includes retrieving data specific to each user, matching the criteria for the implementation related to how objects are synchronized. The step itself will then be executed multiple times, once for each user, during a single poll of the back end. Note that this can be a significant number of executions in a production environment, where it is common for hundreds of users to be connected to the Server for push processing. When run in this manner, the user ID value for each user is accessible via the <<userID>> SDML data tag.

The second option for running push retrieval steps is to run them once per poll period. This behavior will run the step a single time for a given poll regardless of the number of users currently connected to the Server for push data. In this scenario, the data returned by the step must include the user ID specifying which client user will receive a given object. This value should be identified to the Server as UserID. Once the object instance has been created by the Server and the synchronization of the push overall is completed, the object instance will be pushed to that user. When run in this manner individual user ID’s are not available to the step.

When a push retrieval step returns the key property of the push’s target object type, the push read steps or the object read steps (depending on the definition of the push) will be run to continue the synchronization of the target object collection. If no key property is returned by any push retrieval step, it is assumed no new data needs to be pushed to the Client. No read steps will be run in this situation.

Retrieval Step Attributes

  • Step: This attribute references the step definition within the same module to be run as a push retrieval step. These steps may return values for any property within the targeted object type of the push, but must return the key property of that object to indicate that one or more objects should be synchronized by the push and sent to the Client. For steps run once, the data returned by the step must also include the Client user ID to which the object will be sent.
  • Run: This attribute specifies how often to run the referenced step during a single poll interval. This may be set to either Run One Time, or Run Once Per User. The former will execute the step once for a given poll period and the user ID value is not available. The latter will execute the step once per user currently connected to the Server for push data during a given poll period and the user ID value is available.
  • Read Into: This attribute specifies for which object within the data structure of the targeted object collection the step will return data. While retrieval steps can return data for nested collections, it is recommended that this be handled by the push read steps, as these will only be run when the retrieval steps indicate new data is needed.