Data composer provides tags to provide a descriptor of a piece of data. These tags can be used in configuration or in the tagging of documents. This page provides example of tags and explains how those tags are constructed.
When using data composer these tags will never need to be constructed manually but it is helpful to understand them to gain an understanding of how the data composer and document tagging works.
General Format
Data composer tag descriptors are built up of different elements that describe the journey from the current context to get to a piece of data.
Each element of a tag is separate by a . character.
!1 formats are used to indicate first, second etc when referring to lists where there may be more than one entry
? indicates that a query will be applied to the date e.g. looking for items that are of a particular work type etc.
Work Item Data Contexts
| Tag | Description of Tag | Explanation |
|---|---|---|
| workitem.title | Title of the work Item |
workitem - indicates the current work item title - indicates the field on the current work item |
| workitem.phase.name | Phase Name of Work Item (e.g. In Progress) |
workitem - indicates the current work item phase - indicates looking phase data element name - indicates the name field from the phase data element. |
| workitem.phase.isOpen | If true indicates the phase of the work item means it is open. This is taken from the |
workitem - indicates the current work item phase - indicates looking phase data element isOpen - indicates the field on the phase data item that indicates if the field represents an open phase or not |
| workitem.subtype.name | The sub type of the work item (e.g. Leasehold, Freehold) |
workitem - indicates the current work item subtype - indicates looking at the subtype data element (which ultimately links to an option set but is configured in work type modeller) name - the display name of the option set value that is selected |
| workitem.roles.client.ods.name | The name of the entity holding the client role. For organisations this will be the organisation name, teams the team name or people the first name and last name. |
workitem - indicates the current work item roles - indicates that we want to look at the participant roles on the work item client - indicates that we are specifically looking at the client role*. For your usage this will be the system name of the role you want to query. ods - indicates that we want to look at data on the master data record for the client name - indicates we want to show the name for the client** * in this instance the client role is configured to NOT allow multiple clients on a work type. If multiple entities can be assigned to a role then the tag will follow the patterns for buyer detailed below. **this name field will bring back the name agnostic of whether the participant is an organisation, person or team. If you would like to for example bring back the first name then you will need to go to the person record (workitem.roles.client.ods.person.firstName). This process is described in common queries - names. |
| workitem.roles.client.locations.5002500.formatted | Formatted correspondence address for the client |
workitem - indicates the current work item roles - indicates that we want to look at the participant roles on the work item client - indicates that we are specifically looking at the client role locations - indicates that we want to look at the locations (address) data element 5002500 - this is the option set id of the location type that we chose (e.g. correspondence, billing)* formatted - indicates that we have chosen to take the formatted address data item from the address (this shows all the fields formatted in an letter friendly way). * Location types are completely configurable in the application and so the option set id must be used in this tag as it ensures uniqueness in the tag. You will not need to manually construct these tags and when selecting the information in the data composer context explorer you will be present with a user friendly name such as 'correspondence' or 'billing' |
| workitem.roles.buyer!1.ods.name | Name of the first buyer |
workitem - indicates the current work item roles - indicates that we want to look at the participant roles on the work item buyer - indicates that we are specifically looking at the client role !1 - indicates that we want to only take data from the first buyer in the list (working with lists explains how to do this). So any data returned in this list will only refer to the first buyer - you could use !2 for the second buyer. If you have an unknown number of buyers and want to list them in a document that you would need to bind the list of buyers to a table in word. ods - indicates that we want to look at data on the master data record for the buyer name - indicates we want to show the name for the buyer |
| workitem.roles.buyer!1.ods.contact.email!1.value | Email address for the first buyer |
workitem - indicates the current work item roles - indicates that we want to look at the participant roles on the work item buyer - indicates that we are specifically looking at the client role !1 - indicates that we want to only take data from the first buyer in the list (working with lists explains how to do this). So any data returned in this list will only refer to the first buyer - you could use !2 for the second buyer. If you have an unknown number of buyers and want to list them in a document that you would need to bind the list of buyers to a table in word. ods - indicates that we want to look at data on the master data record for the buyer contact - indicates we want to look at the master data contact information for the buyer* email - indicates that we only want to look at email address contact information !1 - indicates we only want to look at the first email address (there can be multiple) value - indicates we want to display the value field, for email this would display the email address *contact types are configurable in the application which is why this level of detail is required in the tag description. |
| workitem.ancestors!q?path=statement-of-work!1.title | Title of the statement of work (ancestor work type) associated with a work type |
workitem - indicates the current work item ancestors - indicates we want to look at any ancestor work types* q? - means we are going to add a query to this tag path - means we are going to only look for items of a certain work type hierarchy path = statement-of-work - means we are only looking for ancestors that are work types of type statement of work or work types that sit underneath a statement of work in the work type hiearchy !1 - indicates only the first statement of work that is returned will be used title - is the data field that should be returned *ancestor work types can be parents, grand parents etc. For example a client may have a contract, a child of that may be a statement of work under which pieces of work are undertaken, and then service tickets which appear under the statement of work. Both the statement of work and contracts would be ancestors. |
|
Example formbuilder (custom data capture) field workitem.form-690400db-9a9d-47ca-870c-f5e5fe682780-AcquisitionDetails.property-valuation |
Custom data field added via formbuilder. |
workitem - indicates the current work item form-690400db-9a9d-47ca-870c-f5e5fe682780-AcquisitionDetails - indicates this is a custom form then the guid (unique identifier) and name of the form) property-valuation - the system name of the field on the custom data form that is being referred to |
| workitem.priority.name |
workitem - indicates the current work item priority - the name of the data element (which has a type of option set value and corresponds with the name of a drop down list) name - the element from the option set data element that is to be displayed |
ODS Entity Contexts
Sortable Table
| Tag | Description of Tag | Explanation |
|---|---|---|
| ods.name | The display name of an ods entity - this is used where the type of the ods entity is unknown e.g. could be a person or an organisation. The system will automatically display the correct name format. |
ods - indicates the information is held on an ods master data record name - is the element from the master data record to be shown |
| ods.organisation.name | The organisation name of an ods entity. The name of the organisation - this should be the same as the ods.name shown above as for organisations this is the same |
ods - indicates the information is held on an ods master data record organisation - the date element for organisations - holding all organisation information* name - the data field from organisation we wish to show *this differentiation between ods types such as organisation, team, person is required as the information for each of these types differ. For example the name of a person is made up of first name, middle name, last name - whereas an organisation has a single field. |
| ods.person.firstName | The first name of an ods record of type person |
ods - indicates the information is held on an ods master data record person - the data element for people - holding all person information firstName - the date field from the person record we wish to show |
| ods.type.name | The type of entity the ods record is e.g. team, organisation, person |
ods - indicates the information is held on an ods master data record type - the data element for ods type information name - the field from the ods type information we want to show - this could be used for example to change wording on a letter depending on whether the recipient is an organisation or a person. |
| ods.locations.correspondence!1.formattedCsv | Formatted correspondence address for an ods entity |
ods - indicates the information is held on an ods master data record locations - indicates that we want to look at the locations (address) data element* correspondence - indicates the address type we wish to query !1 - indicates only the first instance of the address will be returned formattedCsv - indicates the address will be formatted in a comma separated format *it important not to confuse master data location information with location information linked specifically to a work type for a participant. See common queries - address data for more information. |
| ods.contact.mobile!1.value | First mobile number specified for an ods entityl |
ods - indicates that we want to look at data on the master data record contact - indicates we want to look at the master data contact information email - indicates that we only want to look at mobile contact information* !1 - indicates we only want to look at the first mobile number (there can be multiple) value - indicates we want to display the value field, for email this would display the email address *contact types are configurable in the application which is why this level of detail is required in the tag description. |
| ods.user.connections.supervisor!1.user.name | The supervisor name for a user |
ods - indicates that we want to look at data on the master data record user - indicates we want to look at data that is held in the user entity connections - we want to look at data around connections a user may have (e.g supervisor, delegator)* supervisor - the name of the connection we want to look at !1 - we only want to look at the first connection user - we want to look at the supervisors user data name - we want to get the name of the supervisor *ODS connections can be configured within modeller |