The object definition is the primary data definition for a module. All production data for the module is stored in instances of the object definitions created in the application project. The definition of the objects includes not only the data to be stored within each object type, but also the relationship between the objects within the module. These relationships are hierarchical in nature, with one object type the parent to another.
The beginning point of a module’s data structure is the module’s MainObject definition. This object is a part of all modules, added automatically by the Agentry Editor whenever a new module definition is created. The intended purpose of the MainObject is to contain the top-level object collection property or properties, as well as other module-level data.
The primary object of the module is the one around which most or all of the functionality within the module revolves. This includes both client-side behavior and data synchronization. It is important to note that there is no setting or attribute within the application structure that indicates an object is the primary object. Rather, this is a logical term reflective of the design of the module, its objects, and its functionality and behaviors. Examples can include a work order object for a work management module, or a customer object for a customer relations module. When a new module is defined, the Editor will prompt you to create an object definition as well as a collection property within the MainObject. The object created at this point should be the module’s primary object.
Other object definitions can and likely will exist within the module. These definitions are then associated with the primary object as child objects. This is accomplished by defining collection properties. An object is comprised of properties that define the data the object stores. These properties are of various data types, one of which is collection. A collection can store multiple instances of an object definition. When one object contains a collection of other objects, those objects are said to be child objects of the first.
The reason for defining a collection within a parent object is to indicate that those child objects are data that is a part of the parent, but that are also themselves business entities in need of encapsulation. Examples of this can include the two object definitions work order and job plan step. For a work management module, the work order object is likely to be the primary object. Instances of the work order object would then be stored in a collection property of the module main object. Instances of the job plan step object would then be stored in a collection property of the work order object. The job plan step objects within a given work order object would be those representing the steps for that work order’s job plan. Each work order instance then has its own collection of job plan step objects specific to that work order.
This structure can continue to several levels deep within the application structure. As an example a job plan step may require certain parts are used. The job plan step object, then, could contain a collection property of a third object type created to encapsulate a part. In practice it is usually not necessary to create an object hierarchy within a module that is more than three or four levels deep. The term nested collection is commonly used to refer to any collection property that is not an immediate child of the module’s main object. In the preceding examples, the work orders collection would be a top-level collection, and the job plan steps collection would be a nested collection.
When working with collections it is important to keep in mind that the collection is a property of the object. This means the object instances stored within a collection are data that make up that parent object, just as any other property data type. Also, a collection property itself is not an object. When working with other definition types that affect objects and/or collections, be sure to note this distinction. An attribute, argument, or definition that is expecting an object will not accept an object collection property. Likewise an object collection property cannot be used where a single object instance is expected.