Collection Mapping

Sample Files

Two sample collection .docx templates can be found at the following links. Each contains various examples of how a Word template can be formatted to obtain a highly customized collection report export.

• Sample File 1 shows all the major fields and formats exportable from a collection.
• Sample File 2 shows how to work with specific helpers to target the export of specific custom fields, events, and data fields.

Syntax Overview

Several basic data fields are easily referenced in the .docx file. Refer to a collection data field in your template by wrapping a data field name with the following syntax:

+++= data-field +++

note

Many fields on a collection that are exportable will require that you also know how to work with loops.

Basic Fields

Basic fields are easily mapped using the following syntax:

Data Field	Syntax
title	+++= title +++
description	+++= description +++
numItems	+++= numItems +++
priority	+++= priority +++
id	+++= id +++

Tags

Tags require a specified output format and can be mapped using the following syntax:

Data Field	Loop Required?	Syntax
primaryTag	-	+++= primaryTag.tagOption +++
additionalTags	Yes	+++= additionalTags.tagOption +++
additionalTagsList	-	+++= additionalTagsList +++

When using primaryTag or additonalTags, you must specify a tag option. Replace tagOption with any of the following:

Option	Output Example
id	3741e133-d830-4931-845e-49333b4f519d
name	LE/CI - Complete
color	#37e04d
order	15
type	SYSTEM

tip

To get the primary tag's name:

+++= primaryTag.name +++

To loop through all additional tags and output the tag name:

+++FOR tag IN additionalTags +++

+++= $tag.name +++

+++END-FOR tag+++

Users

When using createdByUser,assignedToUser, or participants, you must specify an output format. Replace userOption with any valid User Option.

Data Field	Loop Required?	Syntax
createdByUser	No	+++= createdByUser.userOption +++
assignedToUser	No	+++= assignedToUser.userOption +++
participants	Yes	+++= participants +++

tip

Get the name of a collection's assigned user and their email in two separate lines.

+++= assignedToUser.fullName +++

+++= assignedToUser.email +++

Loop through all participants and output their full name and last login date in local time (at the time the export was performed):

+++FOR person IN participants +++

+++= $person.fullName +++

+++= $person.lastLoginAt.dateTimeLocal +++

+++END-FOR person+++

Datetime Fields

Datetime fields require you to specify the output format. Replace dateTimeOption with any valid Date Time Option.

Data Field	Loop Required?	Syntax
archivedAt	No	+++= archivedAt.dateTimeOption +++
createdAt	No	+++= createdAt.dateTimeOption +++
updatedAt	No	+++= updatedAt.dateTimeOption +++
deletedAt	No	+++= deletedAt.dateTimeOption +++

tip

Output a collection's createdAt time in date time local format:

+++= createdAt.dateTimeLocal +++

Custom Fields

Users have the option of:

• Picking specific custom fields to export by referring to a Custom Field's key (found in Workstation).
• Exporting all Custom Fields in a collection.

Regardless of the method used, the following custom field options must be specified to output a specific value.

Custom Field Options

Each Custom Field in Workstation contains the following options that can be output:

Option	Output Example	Notes
id	34b830b0-ee6b-4646-87a3-cf0d2925fb41	N/A
key	toohzx	N/A
type	CHECKBOX	N/A
name	Type of Case	N/A
value	Domestic Violence, Burglary	N/A
values	---	Helpful for looping through checkboxes and multichips for custom formatting.

Referencing Specific Custom Fields

Custom fields do not require a loop if you do not need specific control of the output format.

To reference a custom field:

1. Find the key for the desired custom field template in Designer > Custom Field Templates in the edit mode for the template.
2. Reference this key in your doc template with the syntax: +++= customFieldByKey.keyhere.option +++, where option is any of the available custom field options.

tip

Suppose there is a Subject SSN custom field with a key of ABCDEF. To output the name and value of this field:

+++= customFieldByKey.ABCDEF.name +++   // Outputs 'Subject SSN'

+++= customFieldByKey.ABCDEF.value +++  // Outputs the value

Custom fields of the checkbox or multichip type output multiple selections as a concatenated string separated by commas. A loop is required for more advanced control over data outputs (such as bulleted or numbered lists of checkbox values).

Rich Text Fields

When exporting rich text custom fields, the tool attempts to maintain the format of the rich text content and styling. However, there may be situations in which Microsoft Word overrides specific formatting, such as indentation levels within bulleted and numbered lists or section headers.

Additionally, it is generally recommended to use the _html helper to ensure that the output of the rich text content closely resembles its appears in Workstation.

tip

Output a rich text field using the HTML rendering method (defaults to Arial font and 12pt font size):

+++HTML _html(customFieldByKey.keyhere.value) +++

Looping through Checkboxes and Multichip Fields

Checkbox and Multichip custom fields may possess multiple selected options. This requires working with a loop. Looping through either field requires the values option instead of value.

tip

Suppose there is a Case Category Custom Field with a key of ABCDE. To output the name of this field and each applied value as a numbered list:

+++= customFieldByKey.ABCDE.name +++          // Outputs the name "Case Category".

+++ FOR val in customFieldByKey.GHIJK.values  // Starts the loop.

1. +++= $val +++                              // Outputs the value.

+++END-FOR val+++                             // Closes the loop.

Exporting All Custom Fields

If desired, you may choose to output all custom fields in a collection. This is achieved by doing a loop on the customFields data field.

tip

Loop through all custom fields and output their names and values:

+++ FOR field in customFields +++             // Starts the loop.

+++= $field.name +++                          // Outputs the field name.

+++HTML _html($field.value) +++               // Outputs the field value and parses HTML (for rich text fields).

+++ END-FOR field +++                         // Closes the loop.

If needed, the value of the custom field can also be wrapped in the HTML renderer or the HTML Helper. This is useful for handling rich text custom fields.

Items (Events)

Items are data elements in a collection that represent the events added to a collection. Items can only be accessed with a FOR-loop.

Data Field	Output Example	Notes
eventTypeTitle	Behavior Profiles	N/A
coreId	021a773e-de6e-2029-0a9d-5d528022065a	N/A
primaryTitle	John Doe	N/A
createdAt	August 7th, 2023 at 11:54 AM	N/A
updatedAt	October 24th, 2023 at 11:10 AM	N/A
riskScore	91	N/A
lexicons	compare, financial, bank	N/A
eventDetails	---	Loop within the Items loop. See Event Detail Options.
eventTypeTopic	behavior_profiles	N/A
eventTypeProjectName	Project Name Here	N/A
eventTypeDataSource.id	021a773e-de6e-2029-0a9d-5d528022065a	N/A
eventTypeDataSource.connectString	kafka.confluent.svc.cluster	N/A
eventTypeDataSouce.name	default	N/A
eventTypeDataSource.type	kafka	N/A

tip

Loop through all attached events in a collection and output the event type name, then display the core ID and risk score as a bulleted list:

+++ FOR event in items +++           // Starts the loop.

 +++= $event.eventTypeTitle +++      // Outputs the event name.
- +++= $event.coreId +++             // Outputs core ID as a bullet point.
- +++= $event.riskScore +++          // Outputs risk score as a bullet point.

+++END-FOR event +++                 // Closes the loop.

Event Detail Options

The eventDetails data fields on Items are also loops. You can access these loop while looping through Items and output any event's detailed fields.

Event Detail Field	Output
type	string
path	string
name	string
value	string
key	string

tip

Loop through all attached events on a collection and output the event type name, then each event detail field's name and value as an indented list:

+++ FOR event in items +++                       // Starts the items loop.

+++= $event.eventTypeTitle +++

+++ FOR field in $event.eventDetails +++         // Starts a second loop in the event details.

- +++= $field.name +++: +++= $field.value +++    // Outputs the bolded field name and value as a bullet point.

+++ END-FOR field +++                            // Closes the second event details loop.

+++END-FOR event +++                             // Closes the items loop.

Outputting Specific Event Types and Fields

It is possible to identify specific event types to output as well as specific fields in each type of event. This is more advanced, but is possible through several helper functions with a loop:

1. Find the key for the desired Event Detail Field.
   1. Navigate to the Admin page of Workstation.
   2. Click the Options button for the desired Event Type and select View Event Definition.
   3. Locate the key for the appropriate field among the displayed data field and event metadata keys.
2. Reference this key in your doc template with the syntax: +++= _get($event, 'eventDetailByKey.keyhere.option') +++, where option is any of the available event detail options. The _get helper is highly recommended for this use case.

tip

Suppose a collection has numerous types of events added, and you desire to:

• Only export the Behavior Profiles events.
• Only output the SSN (key of ABCD) and Description (key of EFGH) fields.
• Manually show the field names Social Security Number and Short Description.

To achieve this, use the following code:

// Start the loop and only keep Behavior Profile events.

+++FOR events IN _keep(items, ‘eventTypeTitle’, ‘Behavior Profiles’)+++

Social Security Number

+++= _get($events, 'eventDetailByKey.ABCD.value') +++     // Get the SSN data field.

Short Description

+++= _get($events, 'eventDetailByKey.EFGH.value') +++     // Get the Description data field.

+++END-FOR events +++                                     // Close the loop.

Comments

Comments on a collection can only be accessed with a loop.

Option	Output	Syntax
id	c940f633-2158-487a-a7db-bbab57b7de6e	+++= $comment.id +++
contentHTML	---	+++= $comment.contentHTML +++
contentPlain	---	+++= $comment.contentPlain +++
createdAt	See Date Time Options	+++= $comment.createdAt.dateTimeOption +++
deletedAt	See Date Time Options	+++= $comment.deletedAt.dateTimeOption +++
updatedAt	See Date Time Options	+++= $comment.updatedAt.dateTimeOption +++
user	See Users	+++= $comment.user.userOption +++
replies	Loop-able within comments	See example below.

tip

Output each comment on the collection and include:

• The user's full name and email.
• The date and time the comment was created.
• The comment rendered in plain text format.
• If there is a reply to a comment, output the:
  • Full name of the reply author.
  • Date and time the reply was made.
  • The content of the reply rendered in plain text format.

+++ FOR comment in comments +++                        // Start the comments loop.

By: +++= $comment.user.fullNameAndEmail +++            // Output name and email of commenter.

Created: +++= $comment.createdAt.dateTimeLocalTZ +++   // Output "Created At" time.

+++= $comment.contentPlain +++                         // Output comment content in plain text.

+++ FOR reply in $comment.replies +++                  // Start loop for replies

    +++= $reply.user.fullName +++                      // Output name of reply author

    +++= $reply.createdAt.dateTimeLocalTZ +++          // Output date/time reply was made

    +++= $reply.contentPlain +++                       // Output reply content in plain text.

++ END-FOR reply +++                                   // Close the reply loop.

+++END-FOR comment+++                                  // Close the comments loop.

Related Collections

Related collections are other collections that are linked to the exported collection. Basic information from related collections can also be pulled into the export.

Related collections require a loop and are called using relatedCollections.

Data Field	Loop Required?	Syntax
title	No	+++= $col.title +++
description	No	+++= $col.description +++
shortId	No	+++= $col.shortId +++
status	No	+++= $col.primaryTag.name +++
comment (how the collection is related)	No	+++= $col.comment +++
priority	No	+++= $col.priority +++
# of events	No	+++= $col.numItems +++
id	No	+++= $col.id +++
additionalTagsList	No	+++= $col.additionalTagsList +++
createdAt	No	+++= $col.createdAt.dateTimeOption +++
updatedAt	No	+++= $col.updatedAt.dateTimeOption +++
archivedAt	No	+++= $col.archivedAt.dateTimeOption +++
assignedToUser	No	+++= $col.assignedToUser.userOption +++
participants	Yes	+++= $col.participants +++
additionalTags	Yes	+++= $tag.name +++

tip

Here is an example of starting a loop on Related Collections. In this example, we attempt to export each related collection's:

• name, description, status, and Short ID
• The date and time the collection was created and last updated.
• Assigned user
• Participants by full name in a bullet list
• The name of each Additional Tag in a bullet list

+++ FOR col in relatedCollections +++                   // Starts the relatedCollections loop.

Name: +++= $col.title +++
Description: +++= $col.description +++
Status: +++= $col.primaryTag.name +++
Short ID: +++= $col.shortId +++

Created On: +++= $col.createdAt.dateTimeUTC +++         // In UTC format
Updated On: +++= $col.updatedAt.dateTimeUTC +++.        // In UTC format

Assigned To: +++= $col.assignedToUser.fullName +++      // Specifically the full name

Participants

+++ FOR person in $col.participants +++                 // Start loop for participants
   - $person.fullName                                   // Specifically the full name
++ END-FOR person +++                                   // Close the participants loop.

Additional Tags

+++ FOR tag in $col.additionalTags +++                  // Start loop for additionalTags
   - $tag.name
++ END-FOR tag +++                                      // Close the additionalTags loop.

+++END-FOR col+++                                       // Ends the relatedCollections loop.