Period Metrics

Overview

Period Metrics is a special record type that stores JSON configuration for automated period-based data calculations. This configuration defines which records to query, which fields to calculate, what type of calculation to run (count, sum, average, or snapshot), and which time intervals to use for the data.

Once configured, Period Metrics enables a daily scheduled workflow that automatically calculates and populates data across all period entries based on your defined metrics. Period recordings are then generated to capture these calculated values over time.

Core Records

The Period Recording adds four core records to the Clevero instance:

Custom Fields Setup

Before configuring the JSON, create custom fields on your records. Each calculation needs a field to store its value in.

For example, if you want to store an invoice count, create a field called invoice-count on your records. Field types to create:

• Number fields: For counts and totals
• Currency fields: For money amounts

Workflows

The Period Recording module includes three workflows:

JSON Configuration

The Period Metrics record holds a JSON array that defines all calculations. Each object in the array targets a specific record and lists the calculations to run against it.

Top-Level Structure

Each item in the array represents one record source and contains:

• record: The API name of the record to query.
• dateField: The date field used to filter records into the correct period. This is not required for snapshot calculations.
• calculations: An array of calculation objects.

Calculation Types

Calculation Options

Filters

Each calculation can optionally include a filters array to narrow down which records are included. Each filter object contains:

Full JSON Example

The following is an example configuration covering multiple record types, calculation types, filters, and snapshot usage:

[
  {
    "record": "support-requests",
    "dateField": "issued-at",
    "calculations": [
      {
        "type": "count",
        "options": {
          "fieldToStoreValue": "support-case-count",
          "updateQuarterly": false,
          "updateYearly": false
        }
      },
      {
        "type": "count",
        "options": {
          "fieldToStoreValue": "test-field"
        },
        "filters": [
          {
            "field": "parent-support-case",
            "operator": "not_empty",
            "type": "array"
          }
        ]
      }
    ]
  },
  {
    "record": "kalysys-invoices",
    "dateField": "date-issued",
    "calculations": [
      {
        "type": "count",
        "options": {
          "fieldToStoreValue": "invoice-count",
          "updateQuarterly": true,
          "updateYearly": true
        }
      },
      {
        "type": "sum",
        "options": {
          "sumField": "net-total",
          "fieldToStoreValue": "invoice-total",
          "updateQuarterly": true,
          "updateYearly": true
        }
      },
      {
        "type": "average",
        "options": {
          "averageField": "net-total",
          "fieldToStoreValue": "invoice-average",
          "updateQuarterly": true,
          "updateYearly": true
        }
      },
      {
        "type": "sum",
        "options": {
          "sumField": "net-total",
          "fieldToStoreValue": "subscription-revenue"
        },
        "filters": [
          {
            "field": "invoice-type",
            "operator": "contains",
            "value": 1672706,
            "type": "array"
          }
        ]
      }
    ]
  },
  {
    "record": "clevero-subscriptions",
    "calculations": [
      {
        "type": "count",
        "snapshot": true,
        "options": {
          "fieldToStoreValue": "current-customers"
        },
        "filters": [
          {
            "field": "status",
            "operator": "contains",
            "value": 293227,
            "type": "array"
          }
        ]
      },
      {
        "type": "sum",
        "snapshot": true,
        "options": {
          "fieldToStoreValue": "current-mrr",
          "sumField": "mrr-net"
        },
        "filters": [
          {
            "field": "status",
            "operator": "contains",
            "value": 293227,
            "type": "array"
          }
        ]
      }
    ]
  }
]

Implementation Steps

Step 1: Add the Module to the Instance

Navigate to the client's Clevero instance and add the Period Recording module. This installs the four records: Years, Quarters, Periods, and Period Metrics. The associated workflows are also installed in the system.

Step 2: Create Required Custom Fields

1. Identify all the metrics the client wants to track. For each metric, create the appropriate custom field on the relevant record:
   1. Periods record: required for all calculations
   2. Quarters record — required if updateQuarterly: true is set
   3. Years record — required if updateYearly: true is set
2. Make sure the API name of each field exactly matches the fieldToStoreValue value you plan to use in the JSON configuration.

Step 3: Create a Year Entry

1. Navigate to the Years record and create a new entry for the relevant year.
2. Set the start date and end date for the year. The workflow uses this entry to automatically generate all quarters and periods for that year.

Step 4: Run the Generate Quarters and Periods Workflow

With the Year entry open, trigger the button workflow:

1. Open the Year entry.
2. Click the button to run [SC-07353] Generate Quarters and Periods from Year Entry.
3. The workflow automatically creates all Quarter and Period records for that year based on the start and end dates.

Step 5: Configure the Period Metrics JSON

1. Open the Period Metrics record and update the JSON configuration field.
2. This is the core configuration that drives all calculations. See the JSON Configuration section for full details and examples.

Step 6: Activate the Daily Scheduled Workflow

1. Make sure the Periods - Update Period Metrics scheduled workflow is active. This workflow runs daily and performs all calculations defined in the Period Metrics JSON, writing the results to the appropriate Period, Quarter, and Year records.
2. Confirm that the workflow is set to Active in the workflow settings.

📌 Need Help?

If you require assistance or encounter any issues, please don't hesitate to contact us for further support.

I need support