Define the data source

  • Release version: Australia
  • Updated March 12, 2026
  • 4 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Define the data source

    Before calculating health, product adoption, or product usage scores in ServiceNow, you must define the data source from which the relevant data will be collected. Data can be gathered via key performance metrics, external sources, or calculated dynamically. Defining the data source sets the foundation for accurate and timely metric evaluation.

    Show full answer Show less

    Steps to Define a Data Source

    • Access: Log in with the snacctlc.customersuccessapplicationadmin role.
    • Navigation: Go to All > Data Context Engine > Data Sources > Create New.
    • Specify details including:
      • Name: Provide a name for the data source.
      • Source: Choose the data origin:
        • PA indicator: Collect performance analytics data at intervals and create records in the Context Engine Data table.
        • External: Define how to retrieve data from an external source or use the Table API to save information.
        • Calculated: Use formulas to compute metrics dynamically from base metrics.
        • Table: Retrieve and analyze data from internal or external tables (requires Workflow Data Fabric Hub for external tables).
      • Frequency: Select how often data is collected (Daily, Weekly, Monthly, Quarterly). For PA indicators, frequency must be equal to or greater than the PA Indicator’s own collection frequency.
      • Other key fields:
        • PA indicator: Select the relevant metric (if applicable).
        • Breakdown and Breakdown table: Define grouping attribute and source table, especially for calculated metrics.
        • Target table mapping (optional): For calculated sources, map where calculated scores are written.
        • Unit of measurement: Specify units like minutes, hours, days, etc.
        • Aggregate: Choose how to calculate aggregate scores (Average, Sum, Max, Min, Count) for table sources.
        • Source table, Group by fields, Conditions, Source value, Source reference: Relevant for table data sources to define data retrieval, grouping, filtering, and aggregation.
    • Submit: After completing the form, submit to create the data source.

    Context Association

    After creating the data source, associate it with one or more context tables by navigating to the Contexts related list and adding new entries. The context table selection depends on the score type being calculated:

    • Health score: Engagement table
    • Success outcome: Success Outcome table
    • Product adoption: Sold Products table
    • Product capability: Product Capability Usage table

    Activate the data source by enabling the Active checkbox and submitting.

    Additional Configuration

    • Define color bands for health metric visualization, which appear in the Health tab on the Engagement homepage.
    • Next, configure the Context Engine Mapper to complete setup and enable data processing.

    Importance for ServiceNow Customers

    Defining the data source properly ensures accurate, timely, and context-relevant metric calculations that drive insights into customer health, product adoption, and usage. It enables integration of diverse data types and sources, flexible aggregation, and tailored reporting, supporting effective customer success management.

    Before calculating the health, product adoption, or product usage score, you must specify the source from which data is to be collected. Data can be collected either through key performance metrics and external sources, or can be calculated.

    To define the data source, follow these steps:
    1. Login as a user with the sn_acct_lc.customer_success_application_admin role.
    2. Navigate to All > Data Context Engine > Data Sources > Create New.
    3. Enter the following details:
      Field Description
      Name Enter a name for the data source.
      Source Select the source from which the data is to be collected from the list.
      • PA indicator: Select this option to use a PA indicator to collect performance analytics data at regular intervals and create records in the Context Engine Data table.
      • External: Specify the external data source from which the data is to be collected. You must define how this data can be retrieved from the external source or use the Table API to save this information in the Context Engine data table.
      • Calculated: Select this option to calculate the metric values dynamically using formulas based on a combination of existing base metrics. For more details, see Define a calculated metric data source.
      • Table: Select this data source type to retrieve and analyze data from internal and external tables. To retrieve data from external sources, you must install the Workflow Data Fabric Hub application and create data fabric tables. For more details, see Define a table data source.
      Note:
      The sequence in which the metrics are calculated is based on the Execution order that defines which metrics are evaluated first. The Execution order is defined as follows:
      • PA Indicator and External: 0 (Metrics from these data sources are calculated first).
      • Calculated metrics: 1 + Max(The child or dependent metrics associated with the parent metric are calculated first followed by the parent metric).
      Frequency Select the frequency at which the data should be collected from the list.
      • Daily
      • Weekly
      • Monthly
      • Quarterly
      Note:
      If you select PA Indicator as your data source, you must select a frequency equal to or greater than the PA Indicator collection frequency. For example, if the PA Indicator is collecting data once a week, you can't select a frequency that is lower than Weekly here.
      PA indicator Select the metric for which the data is being collected.
      Breakdown Select the attribute or category by which the health or risk score is to be grouped. This can be account, product, and so on.
      Breakdown table Select the source table against which the score is calculated.
      Note:
      This field is applicable only if the Source type is Calculated See Define a calculated metric data source for details.
      Target table mapping (Optional) If the Source type is Calculated, you can optionally specify the Target table, Target field, and Target query field. After data collection, the calculated score is written into the matching records where the context aligns with the Target query field. See Define a calculated metric data source for more details.
      Unit of measurement Select the unit of measurement for the PA indicator that can be minutes, hours, days, months, and so on.
      Aggregate Select how the aggregate score should be calculated from the list.The Aggregate score is useful if you select a Frequency that is different from the collection frequency of the PA indicator. For example, suppose the PA indicator collection frequency is set to Daily, and the Frequency is set to Weekly, and you want to calculate the aggregate score for the week. In this case, you can use the average or sum option to calculate the score.
      The following fields are applicable only if you select the Source as Table.
      Source table Select the table from which the source data is to be retrieved. This can be an internal ServiceNow table or an external table.
      Group by fields If you select the Table type data source, you must specify the fields by which the data should be grouped.
      Note:
      You can use up to two fields for grouping.
      Conditions Specify the conditions or filters that will be used while retrieving the data. For example, you can choose to retrieve records for a specified period of time.
      Source value Select the field on which the aggregation is to be performed.
      Source reference

      The source record used to resolve the Group by fields. This field is automatically populated if you selected a single reference type field in the Group by fields option.

      You must update the Source reference resolver script and specify the fields that are to be mapped if the Group by fields contains:
      • Two fields (maximum allowed)
      • A non-reference field.
      • An external field.
    4. Select Submit to create this data source.
    5. Navigate to the Contexts related list and select New.
    6. In the Context page, select the table for which this data source is applicable. This relationship enables the Data Content Engine to collect data from the specified table. Depending on the type of score being calculated, select the table as follows:
      • Health score: Select the Engagement table.
      • Success outcome: Select the Success Outcome table.
      • Product adoption: Select the Sold Products table.
      • Product capability: Select the Product Capability Usage table.
      Note:
      You can define multiple context tables for a single data source.
    7. Enable the Active check box and select Submit to create the data source. You can associate the data source with one or more context tables.
    8. Define color bands as necessary. See the Set up the color banding table for details. The color banding is applied to the health metric data displayed in the Health tab on the Engagement home page.

    After setting up the data source and the context, the next step is to configure the context engine mapper. See the Configure the Context Engine Mapper for details.