A step definition reference for retrieving data from the back-end system.
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
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
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.
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
- 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
- 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.