Object Read Step

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 Agentry Server during a transmit. The step being referenced can be executed once per transmit or iteratively.

The data returned by the object read step is expected to be identified to match the property values of the object. How this data is identified is dependent on the type of step being executed. A given read step need not return all data values, but must always include the key property of the object type for which it is retrieving data and the key property of any parent objects up to the top-level object in the module’s data structure.

Object read steps are executed by the Agentry Server in any of the following situations related to the parent object definition:
  • When a fetch is processed that is defined to target a collection of the read step’s parent object type.
  • When a push defined to target a collection of the read step’s parent object type polls the back end for data changes and finds this to be true, and when that push is defined to use the object’s read steps to retrieve the data rather than the push read steps.
  • When the processing of a transaction targeting the read step’s parent object type sends a client response of replace client object.

In any of these situations, the read steps for an object will be run and the data returned will be used to either create new object instances or replace existing object instances that will ultimately be sent to the Client.

It is important to note that the step being executed by the read step must account for which situation it is being run. The read step definition itself is not aware of the synchronization context in which it is being executed.

Object Read Step Attributes

  • Step: This attribute references the step definition within the same module to run as an object read step for the parent object.
  • Run: This attribute specifies how to run the read step during a single transmit. This may be set to one of the following values:
    • Run one Time: This setting will run the read step a single time for a given synchronization context. This setting assumes the step need be executed only once to return the data for all object instances to be added or replaced during synchronization, or the step being executed is not returning data but rather is being run in support of synchronization.
    • Run once per Object: This setting will execute the read step once for each object instance in the collection that is being synchronized. This includes both those object instances sent by the Client to the Server, as well as any that may have been added by previous synchronization steps. For push processing the step will be executed once for each object instance created prior to the read step’s execution. For transaction processing this setting will have the same behavior as “Run one Time.”
    • Run once per Collection Object: This setting will execute the object once for each object instance in the child collection referenced by the Read Into attribute. This child collection is assumed to have been populated with object instances prior to the read step’s execution. Note that this setting is primarily intended for file transfer functionality, though it is not limited to this purpose.
  • Read Into: This attribute specifies the child or descendent object collection property of the read step’s parent object into which the data returned by the step should be read. This attribute has a default setting of “None.” This default means the data will not be read into a child collection but will instead be used to create object instances of the read step’s parent object. Other valid options for this attribute are any child collection properties of the read step’s parent object, or any descendent collections (e.g. collections within collections) of the parent object.
Parent topic: Module-Level Data Definitions Overview