Developer

Property Data Tags Overview

The data tags for property values within the application have unique, additional behaviors to the other data tags within Agentry. There are common items to all property data tags, including access to raw values and indicator of the property value in relation to its defined special value. There are also behaviors for data tags specific to the data type of the property the tag represents. Another aspect unique to property data tags is their scope. The property values available within the SDML will vary depending on which synchronization definition is referencing the tag.

The first item to be aware of with property data tags is that they are only available in step definitions. The specific properties in scope for a step will depend on which step usage definition is running the step during synchronization. No property data tags are available to any other synchronization component beyond the step definitions of a module.

Property Data Tag Parameters

Data tags for properties, regardless of data type, support two parameters specific to properties. These are the .isSpecial and .raw parameters. The syntax for these parameters is as follows:
<<object.propertyName.isSpecial>>
<<object.propertyName.raw>>

The .isSpecial parameter returns a true or false value indicating whether or not the current property value is equal to the property’s defined special value. True indicates it is equal to the special value. False will be returned when the property value is anything other than the special value or if the property does not have a special value.

The .raw parameter is available to all property data tags regardless of data type, though its exact behavior will be data type-specific. The purpose of the .raw parameter is to return the value of the property without any formatting of the data. By default many of the property data tags will return the value in a formatted manner befitting the data type of the property. As an example, string properties are automatically dequoted during expansion. If the .raw parameter is used, the value will not be dequoted during expansion. Other data types have different behaviors related to the formatting and therefore the value returned by .raw will be different for each data type.

Data Tags for Fetch Client Exchange and Server Exchange Steps

Steps run by fetch definitions will have access to all properties defined for the fetch. Object key properties for the object instances in the collection targeted by the fetch may also be available depending on how the step usage definition’s Run attribute setting.

The following lists describe the data tags in scope for each of the fetch step usage definition Run attribute settings.
Table 31: Run Attribute: Run One Time
Tag Description
<<collectionName>> This tag returns the collection targeted by the fetch. This tag may be passed to the <<foreach...>> function tag to iterate over the object instances within the collection. For each object instance, the tags available include the key property of the object type, and the last update (<<lastUpdate>>) value of each object.
Either:
  • <<fetch.propertyName>>
  • <<fetchName.propertyName>>
Any properties defined within the fetch definition are available using the syntax shown.
<<fetch.messageNumber>> This data tag returns the fetch’s message number as recorded in the messages.log file generated by the Agentry Server. This is typically used for debugging and similar purposes.
Table 32: Run Attribute: Run Once per Object
Tag Description
<<object.keyPropertyName>> This tag returns the key property of the object instance currently being processed by the step.
<<lastUpdate>> This tag returns the last update value of the object instance currently being processed by the step.
<<fetch.messageNumber>> This data tag returns the fetch’s message number as recorded in the messages.log file generated by the Agentry Server. This is typically used for debugging and similar purposes.

Data Tags for Transaction Step Usage Definitions

All step usage definitions within transactions include the same data tags within their scope. Following is a list of these data tags:
Tag Description
<<timestamp>> Returns the date and time when the transaction was applied on the Agentry Client. This value is obtained from the client device.
<<transaction.propertyName>> Returns the value of the transaction property, propertyName. All properties within a transaction are available via data tags.
<<objectName.keyPropertyName>> Returns the key property of the object targeted by the transaction. The object name must be used in this syntax, as the generic object designation is not valid in this context.
<<transaction.messageNumber>> Returns the value of the transaction’s message number as recorded in the messages.log file generated by the Agentry Server. Typically used for debugging and similar purposes.

Property Data Tags for Push Step Usage Definitions

Steps run as push retrieval and push removal steps are either once per poll period or once per user per poll period. For either run setting, these steps do not have access to object properties and therefore have no available property data tags.

For a given poll, push read steps can be run once, once per user, once per object, or once per collection object. When run once per object, the steps will be able to use property data tags to access the key property of any object for the target collection created by the push retrieval steps or previous push read steps. When run once per collection object, the data tag for that child object type’s key property will be available to the step. The child objects in the collection must have been defined before the step that needs to reference the key property.

Push response and error steps are both always run once per object. Therefore these steps have access to the key property of the object for which they are run.

Property Data Tags for Service Event Step Usage Definitions

The step usage definitions for service events include read steps, data state steps, update steps, and error handling steps.

Service event read steps can be defined to run once or to run once per object. When defined to run once, the read step will have access to the collection created by the service event’s synchronization components.

When defined to run once per object, the read steps the property data tags for the object type will be available. These will expand to the property value of the object instance currently be processed by the error handling step. For all of these values the syntax of the SDML property data tag is <<object.propertyName>>.

Data state steps and update steps within service events are always run once per object and will have access to all property values of the object instance being processed.

Error handling steps can be defined to run one time or run once per object. When defined to run one time, the error handling steps will have access to the object collection being synchronized by the service event. When defined to run once per object, the property data tags for the object type will be available. These will expand to the property value of the object instance currently be processed by the error handling step. For all of these values, the syntax of the SDML property data tag is <<object.propertyName>>.

Property Data Tags for Object Read Steps

Object read steps are run as a part of downstream synchronization that may occur for various synchronization processes, including fetch, push, service event, and transaction processing. Also, the read step itself may be defined to run one time or run once per object. Both of these aspects of an object read step can impact the property data tags available to the step.

When the object read step is run after a fetch, any fetch properties will be in scope for the object read step. These must be referenced as <<fetch.propertyName>>.

For all four situations, the read step will be run either in the context of a target collection, for a specific object instance, or for an instance of an object in a collection property of the object definition that contains the read step, based on the run attribute.

When defined to run one time the object read step will have access to the collection targeted by the fetch, push, or service event run immediately before the object read steps. If run one time the object read steps will have access to the key property and last update values for the object currently being processed. If defined to run once per collection object, the properties of the object collection property available to the read step include the key property of the child object, as well as the key property of the step’s parent object. In this case, both objects must be referenced by their definition names, as in: <<customer.customerID>>, <<order.orderID>>.