The object read step definition is a child to the object definition type. 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.
Multiple object read steps can be run to retrieve the data for an object. During synchronization the Agentry Server will create instances of the object after the first set of return data that contains values for the object key property. Subsequent steps that return data for the object must also include the key property to indicate which object the data belongs with. These values will then be used to set the property values of the object. Any object read step can return any property value for the parent object type. A single step can return all of the data or multiple steps can be run to retrieve all of the data. This processing is defined by the developer and the nature of back end system and how data can be retrieved will dictate the proper way to retrieve the data.
The two key items to keep in mind when defining an object read step are that, first, the step definition being executed is separate from the object read step. The step being executed is a module level definition containing the processing logic desired. The step definition must be defined first, and then the object read step can be defined to run it. Depending on the step type this can be a SQL statement, Java logic, or HTTP-XML calls. The object read step references the step definition and specifies when and why it should be run. It does not define the actual processing or the back end system to use. This separation of the logic and the context is an intentional part of the overall architecture that allows for multiple steps defined for different back end systems to be used an executed to synchronize data for a single object type.
The step executed by an object read step has access to certain data about the object. The specific values that are in scope depends on how the object read step has been defined to be executed. To access the in-scope values the Syclo Data Markup Language (SDML) is used.
Any step executed as an object read step must be defined to return not only the data for the object properties in need of values, but must also return the value of the object key property. The key property is used by the Agentry Server to determine which object instance should be assigned to values in the return set. If a read step returns a key property that does not match an existing object a new object is instantiated and the other values in the return set are assigned to the new instance’s properties.
The purpose of an object read step is to return data for properties of the object. This includes object collection properties. While a collection contains object instances, from the context of the parent object the collection is simply another property containing data that is a part of the overall object instance. Therefore an object read step can return data to create instances of the object type stored in the child collection property. An object read step must be defined to read the data into that child collection. The data returned by the step must include the key property of the parent object and the key property of the object instances to be added or updated within the collection property.
As an example of reading data into a child collection property, consider a work order object that contains a collection of job plan steps. An object read step can be defined in the work order object that retrieves data for object instances within the job plan steps collection. The step executed to retrieve this data must return the work order objects key property and the job plan object’s key property. This data is needed by the Server to determine, first, which work order object contains the job plan step object and, second, which job plan object instance the data should be assigned to. Just as with any object read step, if a job plan object key property value is returned that does not match an existing object instance, a new job plan step object is instantiated and added to the collection property of the work order object.
Object read steps are run as a part of the synchronization process for objects and object collection properties. During Client-Server transmission, fetches are processed as the first part of object data synchronization. If the object type that makes up the collection targeted by the fetch contains read steps, those steps are processed after the fetch. In a common application architecture, the fetch will synchronize the exchange data and the object read steps will use that data to determine which object instances to retrieve from the back end system.
When object read steps are run as a part of fetch processing the steps executed are, in most cases, defined to retrieve data for all instances of the object in a single execution. The object read step is defined to run one time in this case, rather than to iterate over the object collection being synchronized. Note that this is the most common way object synchronization is defined, but is not a requirement. There are situations in which a portion of the object synchronization must be performed one object instance at a time, or iteratively. A ready example of such a situation is when file transfer, or “attached documents” functionality is being implemented.
Steps run as object read steps during fetch processing that are also defined to iterate over the object collection have access to the key property of each object instance in the collection and the last update value for each object. These values are sent by the Client to the Server at the beginning of the fetch processing during transmission.
Read steps may also be run after a transaction has been processed that targets an instance of the object. This processing only occurs when a server data state step or server update step within the transaction has been defined to replace the client object after transaction processing. In this situation the object read step is run for the object instance targeted by the transaction. Therefore the step executed should be defined to retrieve data for a single object. Read steps intended to retrieve data for object collection properties can still be defined to retrieve all data for objects within the collection.
When an object read step is run as a part of transaction processing, with the intent of replacing the object on the Client, the in-scope values for the step include the object’s key property, the object’s last update value.
The execution of a read step is controlled by the attribute Run. The Run attribute specifies how often to run the step in relation to the object instances currently being processed and in scope. This execution can be either once or iteratively. Running the step once means the step being processed is expected to return all of the needed data for all of the objects in a single execution. The Server is capable of processing such return sets to create or update multiple object instances.
For iterative processing there are two options. First, the step can run one time for each instance of the parent object currently in scope. For example, when processing a collection of work order objects, a read step within the work order object can be defined to run once for each work order object instance the Server currently contains.
The second option for iterative processing is to execute the step once for each object instance in a collection property of the parent object. This iteration then includes the parent object as well as the objects in the collection property. So if the work order object contains a collection property of job plan step objects, an object read step can be run once for each object within the job plan steps collection of each work order object.
In the case of iterative processing of the object read steps it is assumed a previous read step or one of the fetch steps has returned the data needed to create the objects. Read steps defined to be executed iteratively then run once for each of these object instances to continue the data synchronization process. If an object instance does not exist when the iterative read step is to be processed it will not be executed by the Server as there are no objects to iterate over.