Metric Write Rules

Note: This is an advanced developer feature only available for customers on the Enterprise plan.

Metric Write Rules is an advanced feature that lets developers define granular logic for tracking various KPIs (called “Metrics”) across the system.

It is a useful feature for agencies that have their own highly custom reporting requirements, who are building custom reports outside of Rex and want to be able to systematically track KPIs against users based on granular conditional logic over a long period of time.

There are two discrete concepts with this feature:

• A Metric Write Rule defines when and how certain Metrics should be automatically logged/tallied.
• A Metric itself is the actual KPI event logged against a specific user. You would then pull these Metrics out via the API to build custom reports. In most cases it would be a simple tally, but it could also be e.g. a dollar value.

Creating a Metric Write Rule

A Write Rule dictates when and how a certain Metric should be logged. To create a write rule, go to Settings > Metric Write Rules and click the + button.

• Rule name: The name you want to give the rule, for internal reference only.
• Rule description: A description of the rule’s logic. Generally, this should be a brief summary of when your Write Rule is triggering.
• Record type: The type of system record this rule should trigger off.
• Trigger: What type of record change event should fire this Write Rule
• Run conditions: The actual logic for determining whether or not a Metric should be logged when the trigger is hit. Returning true will log a Metric.
• Triggering user must specify user for attribution: Checking this will show a popup to any user who happens to trigger this Write Rule, and will explicitly ask them who the Metric should be assigned to.
• Metrics: configuration for the Metrics that should be logged when this Write Rule is triggered.
• Note that when defining fields for Metrics, you can select the type “Jsonpath” which lets you use the Jsonpath syntax to refer to data from the triggered write rules.

Writing code for run conditions

This field accepts ES6 JavaScript (assume Node v8). It should export a single function that takes a data argument. On that argument exists several fields:

• pre: The data of the triggering record before the update/creation occurred. Null if it’s a Creation (i.e. there was no previous record).
• post: The data of the triggering record after the update/creation occurred.
• changes: A summary of which exact attributes changed. Look for keys under the changes.attributes property.

Requiring extra modules

To help you out with writing run conditions, we expose the popular lodash & moment packages, which can be referenced by using a standard CommonJS require

Getting Metrics from the API

The /metrics/search API method is the primary way to pull data from the API for Metrics that have been triggered. You can view the API docs for this method here.

Note that you will need to provide at least some criteria before getting results. If you’re fetching several different types of Metrics than time (provided as a UNIX timestamp) is usually the easiest (e.g. “give me all Metrics where time > 30 days ago”). Pagination also applies just like our other services.

A Metric returned from the API looks like this:

{
    "metric": "VIEW",
    "time": 1617859063,
    "recorded_at": 1617859063,
    "value": 1,
    "recorded_by_user": {
        "id": "102",
        "name": "Rex Software Support Team",
        "first_name": "Rex Software",
        "last_name": "Support Team",
        "email_address": "support@rexsoftware.com.au"
    },
    "labels": [
        {
            "label": "service_name",
            "value": "CalendarEvents"
        },
        {
            "label": "record_id",
            "value": "befbbdf6-9829-11eb-a5ab-86704a6dc544"
        }
    ],
    "user_attributions": [
        {
            "percentage": 100,
            "user": {
                "id": "30901",
                "name": "Meghan Warne",
                "first_name": "Meghan",
                "last_name": "Warne",
                "email_address": "meghan.warne@rexsoftware.com.au"
            }
        }
    ],
    "id": 3640546
}