🧑‍💻 Metric Value Mappers

Metric Value Mappers are a powerful feature that allows you to transform raw, often cryptic, metric data into rich, human-readable information. By writing custom JavaScript functions, you can control how metric values are displayed on the Metrics page, and even pull in related data from other parts of the IXR Platform like End Users, Project Members, or the IXR Database.

🤔 How It Works

At its core, a Metric Value Mapper is a JavaScript function that you associate with a specific metricCode. When you view metrics on the Metrics page, if a mapper exists for the displayed metric, the system executes your function for each metric value.

The function's return value dictates what is displayed in the detailed view of a metric. This process happens in a secure sandbox, ensuring that the custom code cannot interfere with the main application.

✍️ Creating a Mapper

You can create and manage mappers in the project settings. The creation form has the following fields:

• Alias: A user-friendly name for your mapper.
• Metric Code: The code of the metric you want this mapper to apply to.
• Description: An optional description for the mapper's purpose.
• Function: A JavaScript code editor where you will write your transformation logic.

The page also features a Live Preview panel. As you select a Metric Code and write your function, the "Before" panel will show you sample raw data for that metric, and the "After" panel will instantly show you the result of your function's transformation.

📜 The Mapper Function

The mapper function is a standard JavaScript module with a default export.

📝 Signature

Your code must be an ES module that default exports a function. This function receives the raw metric value as its only argument.

export default (metric) => {
  // Your transformation logic here
  // Must return an array of objects.
  return [{ text: "A simple line of text" }];
};

The metric argument is the value payload of the metric record, which can be a string, number, or a JSON object.

↩️ Return Value

The function must return an array of objects (MetricValueMapperResultRow[]). Each object in the array represents a row to be displayed in the metric's detailed view. There are several types of rows you can return.

1️⃣ Simple Text Row

This is the most basic type of row. It's an object with a single text key.

export default (metric) => {
  // Assuming metric is { scenarioId: 'scn_123', step: 5 }
  return [
    { text: `Scenario: ${metric.scenarioId}` },
    { text: `Step Number: ${metric.step}` },
  ];
};

2️⃣ Data Rows for Data Fetching

For more advanced use cases, you can return special objects that instruct the system to fetch and display data from other sources. This is useful for replacing opaque IDs with meaningful data like names or emails.

The dataSource property on these objects tells the system which data source to query. It can be one of the following string values:

• 'END_USER': To fetch data from an End User record.
• 'PROJECT_MEMBER': To fetch data from a Project Member record.
• 'IXR_DATABASE': To fetch data from a document in the IXR Database.

👤 End User

To display data from an End User record, your returned object must have this structure:

• dataSource: Must be 'END_USER'.
• id: The ID of the end user.
• fieldName: The field from the user record you want to display (e.g., email, name, identity).
• label: A label to display before the fetched value (e.g., "User:").

export default (metric) => {
  // Assuming metric.userId is a valid end user ID
  return [
    {
      dataSource: "END_USER",
      id: metric.userId,
      fieldName: "email",
      label: "End User",
    },
  ];
};

This will result in a display like: End User: user@example.com.

👥 Project Member

To display data from a Project Member record, your returned object must have this structure:

• dataSource: Must be 'PROJECT_MEMBER'.
• id: The ID of the project member.
• fieldName: The field from the member record to display.
• label: A label to display before the value.

export default (metric) => {
  // Assuming metric.assignedTo is a project member ID
  return [
    {
      dataSource: "PROJECT_MEMBER",
      id: metric.assignedTo,
      fieldName: "name",
      label: "Assigned To",
    },
  ];
};

🗄️ IXR Database

To display a field from a document in the IXR Database, your returned object must have this structure:

• dataSource: Must be 'IXR_DATABASE'.
• collectionName: The name of the collection to query.
• key: The field in the collection to match against.
• value: The value to search for (usually an ID from your metric data).
• fieldName: The field from the found document that you want to display.
• label: A label for the output.

export default (metric) => {
  // Assuming metric.itemId is a key to a document in the 'products' collection
  return [
    {
      dataSource: "IXR_DATABASE",
      collectionName: "products",
      key: "productId",
      value: metric.itemId,
      fieldName: "productName",
      label: "Product",
    },
  ];
};

This will find the document in the products collection where productId matches metric.itemId and display the productName field.

🧪 Example: Combining Row Types

You can mix and match these row types in the returned array to build a comprehensive, detailed view for your metric.

export default (metric) => {
  // Assuming metric = { userId: 'usr_abc', productId: 'prod_123', action: 'purchase' }
  const rows = [];

  rows.push({ text: `Action: ${metric.action.toUpperCase()}` });

  rows.push({
    dataSource: "END_USER",
    id: metric.userId,
    fieldName: "email",
    label: "Customer",
  });

  rows.push({
    dataSource: "IXR_DATABASE",
    collectionName: "products",
    key: "_id", // Assuming we match by the document's _id
    value: metric.productId,
    fieldName: "name",
    label: "Item",
  });

  return rows;
};