Data Objects

OVERVIEW

Important Note:

Custom Objects offer a newer, more scalable and overall superior solution to Data Objects by offering icons, detail views with dynamic property cards, full collaboration options (discussions, file attachments), field indexing, and overall better reporting experience which overcome the limitations encountered when implementing solutions using Data Objects.

The Data Object further enhances Clarizen's configuration capabilities by allowing you to display new types of data in the system, either creating new objects or storing data on existing objects. Data Objects are a flexible repository that stores (for example, and not limited to) time-based snapshot and trend data and are populated only by workflow, API, or other automation.

The Data object stores as much log-type data as you need for your visualizations, charts and reports.

Data objects have no default workflow, business logic or user roles. No alerts or notifications are generated by the system for data objects and, by default, data objects do not affect any other Clarizen behaviors or layouts.

Example use cases:

Use Scheduled or event-triggered Workflow to capture the key data points you need for your business questions

• Administrators may want to log every time a user logs into Clarizen for User Analytics for licensing purposes.  
• Every time an issue or request is changed can be collected for tracking audit trails.
• Project Managers may want to schedule workflows to capture remaining effort on a project for Burndown analysis 
• Project Managers may want to capture Earned Value for a project on an EV graph.

The Data Object enables you to snapshot the key data you are looking to track, via the New Item action in workflows, and use or visualize it in Related Panels, Custom Panels or Reports.

Like Discussions, Data can not be a standalone item and must be related to a container "Source" item.

Like Discussions, Data can be linked to the following types of source items: 

• Work Item (Project, Milestone, Task)
• Group (User Group & Discussion Group)
• Cases (Issue, Risk, Request, Bug)
• File
• Expense Sheet
• User
• Customer
• Expense
• Topic
• Folder and Report

Creating Data Objects

Viewing and Using Data Objects

As Data objects are conceived as flexible and generic way to store many types of data records, Data objects cannot be viewed in a "Data Objects" panel as it is likely there will be a mix of data types which may not make sense to be displayed together. However, Data Objects can be viewed or edited in the Content Layout. The simplest way to access an item's related Data objects, is to configure a Reference to Object field on Data with a Reverse Reference to the relevant source item - which will expose the related Data items in a Related Items Panel  - click here to learn more about how to configure this. 

Protect data in Data object custom fields by using Read Only option when configuring the fields. 

Deleting Related Data Objects

Data Objects can be deleted if the owner of the Data Object's container has Delete permissions. 

The Data Object allows you to add time snapshot data with Scheduled Workflow Rules, without over-extending other Clarizen items such as Notes and Discussions. 

Organizing Data Objects

Use the “Type” picklist field on the Data Object to distinguish between the different types of logged data.

The Type picklist is editable and you should add data type labels to suit your data type, such as: "State Change", "Audit Trail", "User Login".

Configurations for Data Objects

Clarizen supports the following Configuration types for the Data items:

• Scheduled Workflows
• Workflow Rules
• Custom Panels
• Custom Fields
• Validation Rules

How to Create A New Data Object

The Data Object being created in the example below is to track Cases (Issues, Requests, or Bugs) via a Workflow when a user changes an Issue, Request, or Bug's state.This is an example of a simple audit trail. 

You could also use Scheduled Workflow Rules, Custom Actions, Interact, Data Loader and the API.

The example below describes capturing data every time the user changes the "State" of a Case, which means that if the state changes for Issues, Risks, Requests and Bugs it will be captured. 

1. Go to Settings > Configure > Data 
   
   
   
   
2. The Type picklist field is a standard field of the Data Object that can be editable so you can add data type labels to suit your data needs such as "State Changes", "Audit Trail", and "User Login".
   
   
3. Click on Type from Settings> Configure> Data> Standard Fields.
   
   
   
   
4. Description, Tooltip, Reading, Financial and Sort Order can be edited.
   
   
5. It is recommended that you use the Type Value field to distingush between logged and snapshotted data such as "Burn Down Chart", "User Analytics", "EV Graph", "Audit Trail". 
   
   
6. Values can be entered individually or you can choose a file to insert a number of values.
   
   
   1. Type in a Value and click Add. This adds values to the Type picklist that can be retrieved in the Workflow, Custom Panel or Scheduled Workflow rules, Custom Actions, Interact, Data Loader and API.
      
      
   2. Each value can have an Image and/or Color to highlighting important information at a glance.
      
      

      Note:

      The Data Object is completely customizable. You can use any of the Data Object standard fields shown below in the Workflow Rule and Custom Panel as well as create new custom fields to suit your business needs.

       
      
      
   3. Create any Custom Fields you may want to use for the Data Object. These fields store data and can be defined in the Workflow Rule to be later displayed and used or visualized in the Custom Panel or Report. Below are the custom fields that were created for this Data Object.
      
       
      
      
7. In Settings> Configure choose the relevant Source Item type, in this example we will using Cases.
   
   
8. Click on Create New > Workflow Rule for Cases.
    
   Note: 

   You can relate Data Objects to the relevant Source Object such as: Work Item (Project, Milestone, Task), Group (User Group and Discussion Group,  Cases (Issues, Requests, Bugs), File, Expense Sheet, User, Customer, Expense, Topic, Folder and Report.

9. Type in the Name of the Workflow Rule.
   
   
   
   
10. Set the Run Time, in this example, to Every Time a Record is created or edited to capture the user action of either creating the "State" or Changing the "State".
    
    
    
    
11. Set the Evaluation Criteria to Run only when the following conditions are met  when the state, isChanged(State). In this step you are determining when to execute the Workflow rule, so this rule will only run when the Case's state is changed.
    
    
    
    
12. Set Actions for creating a New Item (new record) in the System to run on the CurrentObject, which in this example is "Cases".
    
    
    
    
13. For NewObject1 = New select Data, since is is a new Data Object.
    
    
    
    
14. The $SourceObject is the CurrentObject() or the current record you are working on. In this example the Cases record that the User edited. This is a required field.
    
    
15. You can add standard or custom fields of the Data Object to the Workflow. These fields are defined in the Workflow and will be stored in the Data Object. These stored fields can be displayed for usage and visualization in Custom Panels and Reports. Below are the fields that were added to the "Cases" Workflow.
    
    
    1. DataObjectType, which in this example would be 'Case State Change', this value is stored in the Type field. This field was edited In the Report or Custom Panel and will be labeled as 'Case State Change'.
       
       
       
       
    2. Name is 'State Change', one of the Standard Fields.
       
       
       
    3. New Value of the object 'toString($State)' is a custom field that captures the New Value of the State change of the individual Case.
       
       
    4. Previous Value of the object 'toString(GetPreviousValue($State))' is a custom field that captures the previous value of the individual Case.
       
       
    5. SourceItemID of the Current Object is '$SYSID' or System ID. This will display the system id and it is a custom field.
       
       
    6. SourceItemType of the Current Object 'toString($EntityType)'. This is a custom field.
       
       
    7. Description of the Current Object will display in HTML table rows "From the previous state value to the new state value". This is a standard field.
       
       
       
       
16. Save your changes 
    
    

Exposing the data object in the content layout

Administrators can create a custom field of the Data Object with a field type of Reference to Object and a Reverse Reference to the parent object. This custom field will reference the parent object and automatically display field values of the Data Object in the Related Panels of modules if added in the View Editor. Upon creation of this custom field, users can add, edit and delete field values of the Data Object in the Content Layout such as Projects, and Work Items modules. Administrators need to create a custom field with a field type Reference to Object. 

See also Predefined Lookup Rules in Reference to Object Fields

How to Create a Custom Field of the Data Object to view as a Relation

1. In the Navigation bar click on Settings > Configuration > Data
2. Click on Create New > Custom Field 
   1. In the Field Type section select Reference to Object for the Field Type of the Custom Field
      
   2. In Referenced Entity, select the parent object, in this example the Cases object is selected
   3. In Field Properties enter the name of the Field Label
      
      
      1. The API Label and Tooltip are automatically entered after the Field Label is entered
         

         Note:

         In the API label,  "C_" is always present preceding the name so it does not interfere with existing API names
   4. Optionally you can enter a Description of the custom field
   5. Enable Reverse Reference by clicking the checkbox, meaning that the custom field in this example will access all case items and will be added automatically as a relation
      
      
      1. Enter a Field Label name for the Reverse Reference, this name will be shown in the relation
      2. The API Name is automatically entered after the Field Label is entered
         

         Note:

         In the API Name, "R_" is always present preceding the name so it does not interfere with existing API names
   6. Optionally you can click on the Read Only checkbox if you do not want to allow users to edit or delete field values as a relation
      
   7. Optionally you can click on the Financial checkbox if you want only Financial Users to view and update this field
      
   8. Click  to save the new custom field

How to view Custom Fields in the View Editor

1. In the Navigation bar click on Cases, or the appropriate parent module.
2. Open the View Navigator
3. The currently selected view is highlighted in blue
4. Click Edit
5. Scroll down in the Related Items Panels to ensure that the new custom field appears as a relation
6. Save changes
   

   Note:

   You may not see the relation immediately if field values do not exist

7. In this example to view data in the Data Object's custom field in Cases you will need to make changes to the state of issues, bugs, risks, or requests
   1. Change the state for a few items
   2. Click on the item to view the new relation
8. You will see the Custom Field name of the Data Object in the Related Items Panel
   
9. Users can now expand the Related Item to edit or delete field values in the data object
   
10. Example of a read only custom field of a Data Object
    
11. Items cannot be edited or updated via Relations because Read Only was checked
12. All fields have a lock indication next to it noting the value is not editable
    

How to Display The Data Object In A Report

A report can be created to view the field values of the new Data Object defined above. You should only see data that you have permissions on, which is determined by the View permissions on the Container object (Work Item, Group, Cases, File, Expense Sheet, User, Customer, Expense, Topic, Folder and Report).  

1. In the Navigation bar click on Reports>  New Report
   
   
2. Enter the Report Name, in this case Audit Trail
   
   
3. Select Data from the Report on dropdown
   
   
   
   
4. Alternatively you can select the custom field of the Data Object, in the example below a custom field of Login was created on the parent object, User
   
5. View of the Login custom field
   
6. Select the columns you want to display in the Report, note these are the same fields we defined in the workflow
   
   
7. Display of the Data Item Report for Cases
   
   
   

   Note:

   The description 'work was changed' was added to the Data object that was created so it is included in report

For more information see Creating Reports.

How to Create A Custom Panel Exposing Data Objects

Custom Panels uses stored fields in the Data Object to display data. The Custom Panel uses variables to “run on related” Data Object to generate tabular lists, aggregate data such as KPIs or Javascript (such as Google charts) Review more information on Custom Panels.

1. Go to Settings>Configure> Cases
   
   
2. Click on Create New> Custom Panel
   
   
3. Type in the Custom Panel Name, "State Changes" in this case
   
   
   
   
4. In the Permissions section select All Users
   
   
   1. You can select Allowed By then you will have to select the users to grant access 
      
      
   2. Click on 
      
      
   3. A dialog box will open for you to select the Users to access the panel. Note multiple selections can be inserted, you can choose from Roles, People, Groups, etc.
      
      
      
      
5. In Visibility Rules click Show without conditions, meaning no conditions are required to show the information
   
   
6. In Set Actions, Set a New Variable 
   
   
7. Fill in the required field name of the New Variable to "statechanges"
   
   
8. Fill in the required fields, Type which is text and Value is null. This new field will be referenced in the HTML display table of selected fields.
   
   
   
   
9. Set the second Variable to run on the new Data Object and Filter Related Items on the Data Object Type of 'Case State Change'. This step will filter the Data Object Type for only records with 'Case State Change' in the Type field.
   
   
   
   
10. After the records have been filtered the following information will be appended to the statechanges variable: Date and Time, Created By and a description. The Value is written in HtML format so it will display each record as a row. You can specify the format of the date and time.
    
    
    
    
11. You can set the content in HTML format to display an HTML table. You need to specify the HTML table tags with the "statechanges" variable to display the data from the Data Object.
    
    
    
    
12. The Custom Panel will be displayed in Cases
    
    
    
    

    For more information see Custom Panels.

    Note:

    You can work with Third Party Charts in Custom Panels

    If you are using Google Charts you need to store your main data as text, so you can create a custom formula based text field
    
    
    
    

    You can use JsonObjects for a Custom Panel
    
    

Best Practices 

• As with Notes and Discussions, if you delete the main object you lose the Data too as it has nothing to be attached to. If you need to persist the data after items are deleted, you can protect the main objects with Validation rules or link the Data to an item that will never be deleted.