An OBJECT CODE is a way of referencing properties of objects of the system.

SYNTAX

Objects can be nested, so it is possible to access subobject properties using a syntax like OBJECT.SUBOBJECT.PROPERTY

It is also possible to include some modifiers that allow more tailored references to objects. The complete syntax is (square brackets denote optional parameters)

       ROOT.SUBOBJECT[{SELECTOR}][:SCOPE].PROPERTY[{OPTION}][:PROPERTY_SCOPE]

1. ROOT: MANDATORY. No all objects can act as a root node in the OBJECT CODE syntax. See OBJECT CODE NODES for more information

2. SUBOBJECT{SELECTOR}:SCOPE. This block must appear at least once and can be repeated N times (nested subobjects)

   1. SUBOBJECT: MANDATORY. The name of a valid subobject. See OBJECT CODE NODES

   2. {SELECTOR}: OPTIONAL. Some nodes admit the possibility of specifying a selector to narrow the list of objects to which they can refer. Each type of object has its particular selectors. The name of the SELECTOR can have the following characters: letters A to Z, numbers 0 to 9, special characters: ". - _ #"

   3. :SCOPE: OPTIONAL. In some cases it is also possible to limit the scope of the referenced object. Normally the scope refers to a date range (see OBJECT CODES#SCOPE). Only some objects admit the SCOPE modifier, and each object accepts a different set of scope values..

3. PROPERTY{OPTION}:PROPERTY_SCOPE

   1. PROPERTY: MANDATORY. determines the property for which we want to obtain the value. The range of properties is completely dependent of the object type. Take into account that a property can return a single value or an array (see RETURNED VALUES).

   2. {OPTION}: OPTIONAL. Some properties admit a modifier that allow to define which feature of the property must be returned. For example, when retrieving the value of an ITEM of type RADIO BUTTON, it is possible to obtain the literal description of the option selected (ITEM.ANSWER{DESC]), the value assigned to the option selected  (ITEM.ANSWER{VALUE}) or the order of the selected option in the list of available options ((ITEM.ANSWER{ORDER}). The name of the OPTION can have the following characters: letters A to Z, numbers 0 to 9, special characters: ". - _ #"

   3. :PROPERTY_SCOPE: OPTIONAL. Some properties can return multiple values instead of a single value. In those cases it is possible to specify a "property scope" to select only one or a subset of the returned values

EXECUTION CONTEXT

When any OBJECT CODE is evaluated, the WS-API sets a context that delimits where the affected objects requested can be found. For example, when the OBJECT CODE ITEM{n}.ANSWER is evaluated, the execution context will force to find the value only into the FORM where it is defined. This prevents retrieving information from other FORMS, TASKS, ADMISSIONS etc.

For extended information about the execution context, see "CONTEXT" OBJECT CODE .

RETURNED VALUES

The value that results from the evaluation of an object code can be of two types:

1. Single (scalar) value: the OBJECT CODE refers to single object in the system which has a unique value. For example USER.GIVEN will return only one string with the name of the USER

2. Array: In the following situations the return value will be an array

   1. When the OBJECT CODE refers to multiple objects in the system. In this case the array will contain the property value of each of the found objects. For example, TASK.FORM.NAME returns the names of all the FORMs of a TASK (if there were only one FORM, then a single value would be returned instead of an array)

   2. When the OBJECT CODE refers to a single object in the system, but the property is inherently multi-valued. For example FORM.ITEM.OPTIONS refers to the list of options of multi-option ITEMS (radio buttons, check boxes, CODE items...)

Language considerations

Those properties that admit localization will be returned in the active session language.

For example, in ITEMS of type CODE the internally stored value is a code which can have a description in multiple languages (see CODES WEB SERVICES). Then, when asking for the description ob such objects, the returned value will be translated to the corresponding language.

As a general rule of thumb, most of the literals in the SYSTEM OBJECTS and LIBRARY OBJECTS are language dependent.

OBJECT CODE NODES

The following table shows the available OBJECT CODE base objects, and states which of them can act as a root object or as a sub-object