TimeLine Viewer

Content

1. Timeline Viewer modules 2. Managing events types (Timeline Events) 2.1. Creating a new type of event 2.2. Modifying existing types of events 3. Managing the text of Timeline Viewer events 4. Managing the event generation logic 5. Managing the retention period of generated events 6. Deactivating the event 7. Importing Timeline Viewer records 8. Managing visibility of Timeline Viewer modules

Timeline Viewer modules

Timeline Viewer includes 3 modules: • Timeline events – module for defining types of events • Timeline – the events displayed on the timeline • Timeline comments – technical module for storing comments

Managing events types (Timeline Events)

Each event displayed on the timeline belongs to some event type. The event type for every generated event is used to: • Display the event’s icon
• Define how long to keep the event in the DB • Search events on recodrview, listview and dashlets

Event types are stored as records in Timeline Events Module.

Creating a new type of event

In general, the addition of a custom event type to the system consists of 2 steps: the creation of a Timeline Event record for the new event type and the implementation of event generation logic (either via code or via Logic Builder).

To create a record representing the new event type, you need to create a new record in Timeline Events module:

Name– specify the name of the event. Users will see the name when hovering over the event’s icon on the event’s record and will be able to perform search on generated events by the name of the event type. Icon – upload the icon which will be displayed on the timeline for this event. The picture must be a .png, at most 42px x 42px. Target Module – specify the module, to which the given event type pertains. Lifetime Units/Lifetime Duration – using these fields you can specify the retention period for the events of this type. Upon expiration of the specified time, the special scheduler job will delete the expired events. For more details see "Managing the retention period of generated events"
Description – specify the text description of the event if necessary.

When all parameters are specified, save your record.

Modifying existing types of events

To modify an existing event type you need to modify the corresponding Timeline Event record.
You can make the following modifications:

• Change the event name via the Name field Note: when changing the name of the event type, make sure to update the corresponding pieces of event generation logic, which rely on this event type’s name.
• Change the event icon via the Icon field. Just upload a new icon to replace the existing one.
• Change Target Module if this type of the event should be linked to another module.
• Change Lifetime Units and Lifetime Duration, thus changing the retention period of the events of this type.
• Change the event’s type Description

Any modifications made in Timeline Events module are immediately applied to all generated events. For example, if you change the event type icon, it will be displayed for all (including existing) events of this type.

Managing the text of Timeline Viewer events

The text of the generated events can be specified directly in Logic Builder. Also, Timeline Viewer supports template engine, which allows creating the text template with formatting, icons etc. for rich-text messages:

Besides visual text formatting, the template engine allows using variables within the template text, whose values can be populated from your Sugar data. With this you can output any data, not necessarily just from the records, to which the generated event is related.

The template can be specified in Sugar in LB Templates module, and the variables can be mapped to actual data in the Logic Builder flowchart, responsible for event generation.

Note: the Timeline Viewer package does not come with LB Templates module, therefore you should first download and install LB Templates.

Managing the event generation logic

You can use program code or Logic Builder to describe the logic according to which the event is generated. This section describes the special aspect that must be taken into account when describing the event in Logic Builder.
Each generated event is represented in the system by a record of Timeline module. That’s why to generate an event we have to create a new Timeline record.

For the event to be generated correctly, you need to specify the values for this record’s attributes. 1) Parent ID (parent_id). Here you need to specify the ID of the Target record, i.e. the ID of the record, on whose timeline this event will be displayed. 2) Target module (parent_type). Here you need to specify the Target Module, i.e. the module of the record, whose ID you specified as Parent ID. It’s recommended to use Dropdown Value operator with moduleList as its first parameter in order to reliably obtain the name of the module.

3) Event Type (ID) (event_id). Here you need to specify the ID of the event type – of the record from Timeline Events module.
You can get the record by using Retrieve Entities by attributes operator, for example:

4) Optional: for users’ convenience in filtering and information display in the interface, you should specify Object id (object_id) and Object Module (object_type). The values for these fields are specified similarly to Parent ID (parent_id)/Target module (parent_type) fields, but here you need to specify the record, in the context of which the event occurred.
For example, consider the event of the registration of the new case. The event is displayed in the Account timeline. Parent ID (parent_id) in this case is an id of the Account, Target module (parent_type) is Accounts, Object id (object_id) is an id of the newly registered Case, whereas Object Module (object_type) is Cases. 5) Rich-text message (name_html). Here you specify the text of the event to be displayed on the timeline for users. This text can be entered directly in Logic Builder:

However, for better readability we recommend using an HTML template and populating its variables in your flowchart. For more details see "Managing the text of Timeline Viewer events"

6) Context is what the user sees when they click the Preview button next to the event. If you don’t specify a value for this field, one of the two things will happen: if Object (ID and Type) is specified for the event, the quick view of Object record will be displayed by clicking Preview. If Object is not specified for the event, the Preview option will not be available to the user. You can provide your own value for the Context field, thus manually controlling what will be shown in the Preview. The way to create a custom context in Logic Builder is to define a structure with fields, corresponding to values you want to see on the preview, and then assigning values to those fields.

Note: if Object Module is a legacy module, the Object record will not be used by default for preview purposes and you will need to provide a custom context in order for the Preview option to be available. Standard preview for objects of legacy modules is not available. You can find an example of context generation for an Email event below:

A user can see it the following way:

Note: Record’s icon, as well as Name, Event Type and Action date fields cannot be set in the flowchart and are always displayed when custom context is used.

7) Action Date. By default, Timeline Viewer records are generated with Action Date containing the point in time when the event occurs. However, you can specify your own date, for example you can use an email’s Date Sent instead of the date of its record’s creation in the system.
8) Assigned to & Teams. By default, if the logic of setting Assigned to & Teams is not written in the flowchart, the corresponding variables are inherited automatically from the Target record. However, you have the ability to set your own values.

Note: If only [Assigned to] is specified in the flowchart, Teams are inherited from the Target record, and the relevant standard Sugar functionality kicks in (if Assigned to user doesn’t belong to inherited Teams, the private user team is automatically added as well).

If you need to set just one team, just specify a value for Timeline record’s Team Id field using Set Entity Attributes operator. If you need to specify more than one team, it’s necessary to use Link Entities operator, where Object Entity is the Timeline record, and Subject Entity is Teams, for example:

Once you build the flowchart, upload and install the package in Sugar. When all conditions are met, new timeline events will be generated.

Managing the retention period of generated events

You can specify the retention period of generated events in the system. Upon its expiration, the event is deleted from the system.
The retention period is set using Lifetime Units and Lifetime Duration fields of the event type. Each generated event is retained for the period, specified in the linked Timeline Event record. A special scheduler job, Clean Old Timeline History, deletes old events. To change the retention period of generated events, you must modify Lifetime Units and Lifetime Duration in the Timeline Event record. The new retention period will be applied to all existing events of this type.

Deactivating the event

To deactivate a certain event, you must disable Sugar package which is responsible for the event:

To find out which package is responsible for a particular event, switch to the Timeline Event record and look at the “Produced by” subpanel.

Importing Timeline Viewer records

You can migrate generated events from one environment to another using standard Sugar import. Note: if you export generated Timeline Viewer events from another instance, timeline version, installed on the source instance, must be 1.9 or higher. Hint: you can manually generate Timeline events in the import file, and then upload it to Sugar. Thus the timeline will display significant events which for any reason were not generated inside the system. NB: if a particular event’s Object Module or Target Module is a legacy module, it will not be possible to import such an event.
See fields description for import:

Header Row	Description
Plain-text message	Mandatory to import
Date Created	If you leave it blank, the record is created with Date Created = Import Date (however it is displayed on the timeline by Action Date).
Date Modified	If you leave it blank, the record is created with Date Modified = Import Date (however it is displayed on the timeline by Action Date).
Modified By ID	Optional
Created By ID	Please note that when importing from another instance, by default Do not map this field option is selected. You should manually choose Created by:
Rich-text message	Mandatory to import
Parent ID	Mandatory to import
Target Module	Mandatory to import
Context	Not mandatory to import if the value is not in the source-file
Object Id	Not mandatory to import if the value is not in the source-file
Object Module	Not mandatory to import if the value is not in the source-file
Event Type (ID)	Mandatory to import. Here you must specify the ID of the Timeline Event record, present in the destination instance.
Action Date	Mandatory to import
Assigned User ID	If user is not specified, the assigned user will be the one who performs the import.
Team ID	If Teams are not specified, Primary Default Teams of the user will be set for the record where the import is done.
Team Set ID	If Teams are not specified, Primary Default Teams of the user will be set for the record where the import is done.
Teams	If Teams are not specified, Primary Default Teams of the user will be set for the record where the import is done.
Assigned User	If user is not specified, the assigned user will be the one who performs the import.
Created By	It is necessary to manually disable the mapping for Created By.

Managing visibility of Timeline Viewer modules

Timeline Viewer includes a set of modules to which standard role restrictions can be applied.
Please note:
- Timeline Events. do not disable this module in the role matrix for users, otherwise icons on the timeline will not be displayed and users will not be able to search events by types. If you want to prevent the users from modifying the module, you can set the restriction to modify/delete.
Also, keep the List of the module accessible for users, otherwise users will not be able to filter events by types.
- Timeline. If you want to prevent the user from seeing the Timeline, set such a role for the user, where you disable Timeline events and Timeline modules. Please note that such a user, while unable to see the Timeline, will still be able to trigger event generation. - Timeline Comments. It is not recommended to set role restrictions for this module.