NerdGraph tutorial: View and manage Scorecards

New Relic lets you to use NerdGraph Scorecards GraphQL mutations to manage Scorecards and rules. These mutations let you create, update, delete, and retrieve Scorecards and their associated rules in your existing workflows and integrations.

This tutorial provides examples of how to use NerdGraph to manage Scorecards and rules. You can use these examples to automate Scorecard management tasks, such as creating Scorecards, adding rules, and updating Scorecard details. If you need to set up custom permissions for managing Scorecards, see Create custom roles for Scorecards.

Mutations

New Relic provides various NerdGraph mutations to create and manage Scorecards and related rules.

You can also organize a Scorecard's rules into maturity levels and give each rule a weight. In the API, maturity levels are called progress levels:

A Scorecard defines its maturity levels with the progressLevels field. Creating custom (non-default) levels is only available through the API, see Create or update maturity levels.
A rule is assigned to a level with the progressLevel field, which takes the id of one of the Scorecard's progress levels.
A rule's weight in the Scorecard's weighted-average score is set with the impactWeight field. For how weighting works, see weighted scoring.

For managing Scorecards and rules, you need to provide your organization ID. You can retrieve your organization ID using the actor query.

Sample request

query FetchYourOrgId {
  actor {
    organization {
      id
    }
  }
}

You can create your own Scorecard using the entityManagementCreateScorecard mutation.

Input parameters

Parameter	Data Type	Is it Required?	Description
`name`	String	Yes	The name of the Scorecard.
`description`	String	No	A brief description of the Scorecard.
`organizationId`	String	Yes	Your organization ID.
`progressLevels`	`[EntityManagementProgressLevelDefinitionCreateInput!]`	No	The maturity (progress) levels for this Scorecard. See Create or update maturity levels for the field details.

Sample request

mutation CreateScorecard(
  $name: String!
  $desc: String
  $organizationId: ID!
  $progressLevels: [EntityManagementProgressLevelDefinitionCreateInput!]
) {
  entityManagementCreateScorecard(
    scorecardEntity: {
      description: $desc
      name: $name
      scope: { type: ORGANIZATION, id: $organizationId }
      progressLevels: $progressLevels
    }
  ) {
    entity {
      id
      progressLevels {
        id
        name
      }
      rules {
        id
      }
    }
  }
}

// PARAMETERS
{
  "description": "Test test Best Practices",
  "name": "Test Engineering Best Practices",
  "organizationId": "xxxxxxxx-yyyy-0000-aaaa-0123456789qwe",
  "progressLevels": [
    {
      "id": "BASIC",
      "name": "Basic",
      "description": "Minimum operational standard",
      "hexColorCode": "#9C5D00"
    },
    {
      "id": "INTERMEDIATE",
      "name": "Intermediate",
      "description": "Expected standard for mature services",
      "hexColorCode": "#0E7C7B"
    },
    {
      "id": "ADVANCED",
      "name": "Advanced",
      "description": "Excellence and optimization",
      "hexColorCode": "#11845C"
    }
  ]
}

The progressLevels field is optional. The default BASIC, INTERMEDIATE, and ADVANCED levels are added only when you create a Scorecard in the UI. When you create one through the API, use progressLevels to define its maturity levels.

To add custom levels or change levels on an existing Scorecard, see Create or update maturity levels.

Maturity levels are defined by a Scorecard's progressLevels. Set them when you create a Scorecard, or update them later using the entityManagementUpdateScorecard mutation.

The API is the only way to create custom levels (like adding a 4th level or renaming the defaults) because the UI only supports the default 3.

To add a new maturity level to an existing scorecard:

Run the Scorecard read query to get your current levels.
Call the entityManagementUpdateScorecard mutation with the complete progressLevels array. Make sure to include the existing levels you want to keep, plus your new one.
중요
The update mutation replaces the scorecard's entire set of levels. Any level you leave out of the array is permanently deleted.

Keep in mind:

Limits: A scorecard can have 1–5 levels.
Hierarchy: The order of the array sets their hierarchy, from lowest to highest maturity.

Each item in the progressLevels array accepts the following fields.

Input parameters

Parameter	Data type	Is it required?	Description
`id`	String	Yes	A stable identifier for the level, referenced by a rule's `progressLevel`. The default levels use `BASIC`, `INTERMEDIATE`, and `ADVANCED`. For custom levels, you can define your own, for example, `EXPERT`.
`name`	String	Yes	The display name of the level, such as `Basic`.
`description`	String	No	A user-facing description of the level.
`hexColorCode`	String	No	The hex color code used to represent the level in the UI, such as `#11845C`.

Sample request

mutation UpdateScorecardProgressLevels(
  $id: ID!
  $name: String!
  $description: String!
  $progressLevels: [EntityManagementProgressLevelDefinitionUpdateInput!]
) {
  entityManagementUpdateScorecard(
    id: $id
    scorecardEntity: {
      name: $name
      description: $description
      progressLevels: $progressLevels
    }
  ) {
    entity {
      id
      progressLevels {
        id
        name
        description
        hexColorCode
      }
    }
  }
}

// PARAMETERS
{
  "id": "SCORECARD_ID",
  "name": "Test Engineering Best Practices",
  "description": "Test test Best Practices",
  "progressLevels": [
    {
      "id": "BASIC",
      "name": "Basic",
      "description": "Minimum operational standard",
      "hexColorCode": "#9C5D00"
    },
    {
      "id": "INTERMEDIATE",
      "name": "Intermediate",
      "description": "Expected standard for mature services",
      "hexColorCode": "#0E7C7B"
    },
    {
      "id": "ADVANCED",
      "name": "Advanced",
      "description": "Excellence and optimization",
      "hexColorCode": "#11845C"
    },
    {
      "id": "EXPERT",
      "name": "Expert",
      "description": "A custom level beyond the defaults",
      "hexColorCode": "#005054"
    }
  ]
}

You can create a new rule for a Scorecard using the entityManagementCreateScorecardRule mutation.

Input parameters

Parameter	Data Type	Is it Required?	Description
`name`	String	Yes	The name of the rule.
`description`	String	No	A brief description of the rule.
`query`	String	Yes	A NRQL query to evaluate compliance.
`accounts`	Int	Yes	List of account IDs where the rule should execute the query.
`joinAccounts`	Int	No	List of account IDs that need to be joined with each account where the query is executed.
`organizationId`	String (ID)	Yes	Your organization ID, see Fetch your organization ID above to know how to fetch it
`progressLevel`	ID	No	The `id` of the maturity (progress) level this rule belongs to, such as `BASIC`. Must match one of the Scorecard's `progressLevels` — see Create or update maturity levels to define them.
`impactWeight`	Int	No	The rule's weight in the Scorecard's weighted-average score, as an integer from `1` to `100` (default `1`). See weighted scoring.
`runInterval`	Int	No	How often the rule runs, in minutes. Allowed values: `60` (1 hour), `360` (6 hours), `720` (12 hours), and `1440` (1 day).

Sample request

mutation CreateRule(
  $name: String!
  $description: String
  $query: String!
  $accounts: [Int!]!
  $joinAccounts: [Int!]
  $organizationId: ID!
  $progressLevel: ID
  $impactWeight: Int
  $runInterval: Int
) {
  entityManagementCreateScorecardRule(
    scorecardRuleEntity: {
      name: $name
      description: $description
      enabled: true
      progressLevel: $progressLevel
      impactWeight: $impactWeight
      runInterval: $runInterval
      nrqlEngine: {
        accounts: $accounts
        joinAccounts: $joinAccounts
        query: $query
      }
      scope: { id: $organizationId, type: ORGANIZATION }
    }
  ) {
    entity {
      id # RULE Id
    }
  }
}

// PARAMETERS
{
  "name": "APM Services Have Alerts Defined",
  "description": "Check that APM services have alerts associated with them",
  "accounts": [1, 2, 3],
  "query": "SELECT if(latest(alertSeverity) != 'NOT_CONFIGURED', 1, 0) AS 'score' FROM Entity WHERE type = 'APM-APPLICATION' AND tags.nr.team IS NOT NULL AND tags.environment IS NOT NULL FACET id AS 'entityGuid', tags.nr.team AS 'team', tags.environment AS 'environment' LIMIT MAX SINCE 1 day ago",
  "organizationId": "xxxxxxxx-yyyy-0000-aaaa-0123456789qwe",
  "progressLevel": "BASIC",
  "impactWeight": 2,
  "runInterval": 1440
}

You can associate a rule with a Scorecard using the entityManagementAddCollectionMembers mutation.

Input parameters

Parameter	Data Type	Is it Required?	Description
`collectionId`	String	Yes	The Scorecard's ID to add the rules.
`rules`	String	Yes	List of rule IDs to be added to the Scorecard.

Sample request

mutation AddRuleToCollection($collectionId: ID!, $rules: [ID!]!) {
  entityManagementAddCollectionMembers(collectionId: $collectionId, ids: $rules)
}

// PARAMETERS
{
  "collectionId": "", // Collection ID is from the rule.id from scorecard entity
  "rules": [] // Provide list of all rule ids which are generated during rule creation.
}

You can update the details of an existing Scorecard using the entityManagementUpdateScorecard mutation.

Input parameters

Parameter	Data Type	Is it Required?	Description
`id`	String	Yes	The unique identifier of the Scorecard.
`description`	String	No	Updated description of the Scorecard.
`name`	String	Yes	Updated name of the Scorecard.

Sample request

mutation UpdateScorecard($id: ID!, $description: String, $name: String!) {
  entityManagementUpdateScorecard(
    id: $id
    scorecardEntity: { description: $description, name: $name }
  ) {
    entity {
      name
      id
      rules {
        id
      }
    }
  }
}

You can update a rule for the Scorecard using the entityManagementUpdateScorecardRule mutation.

Input parameters

Parameter	Data Type	Is it Required?	Description
`ruleId`	ID	Yes	The unique identifier of the rule.
`name`	String	Yes	The name of the rule.
`description`	String	No	A brief description of the rule.
`query`	String	Yes	A NRQL query to evaluate compliance.
`queryAccounts`	Int	Yes	List of account IDs where the rule should execute the query.
`joinAccounts`	Int	No	List of account IDs that need to be joined with each account where the query is executed.
`enabled`	Boolean	No	Enable or disable the rule.
`progressLevel`	ID	No	The `id` of the maturity (progress) level this rule belongs to, such as `BASIC`. Must match one of the Scorecard's `progressLevels` — see Create or update maturity levels to define them.
`impactWeight`	Int	No	The rule's weight in the Scorecard's weighted-average score, as an integer from `1` to `100` (default `1`). See weighted scoring.
`runInterval`	Int	No	How often the rule runs, in minutes. Allowed values: `60` (1 hour), `360` (6 hours), `720` (12 hours), and `1440` (1 day).

Sample request

mutation UpdateRule(
  $ruleId: ID!
  $name: String!
  $description: String
  $query: String!
  $queryAccounts: [Int!]!
  $joinAccounts: [Int!]
  $enabled: Boolean
  $progressLevel: ID
  $impactWeight: Int
  $runInterval: Int
) {
  entityManagementUpdateScorecardRule(
    id: $ruleId
    scorecardRuleEntity: {
      description: $description
      name: $name
      enabled: $enabled
      progressLevel: $progressLevel
      impactWeight: $impactWeight
      runInterval: $runInterval
      nrqlEngine: {
        accounts: $queryAccounts
        joinAccounts: $joinAccounts
        query: $query
      }
    }
  ) {
    entity {
      id
      name
      description
      progressLevel
      impactWeight
      nrqlEngine {
        accounts
        joinAccounts
        query
      }
    }
  }
}

You can delete an existing Scorecard or rule using the entityManagementDelete mutation.

Input parameters

Parameter	Data Type	Is it Required?	Description
`id`	ID	Yes	The target Scorecard or rule ID to be deleted.

Sample request

mutation DeleteEntity($id: ID!) {
  entityManagementDelete(id: $id) {
    id
  }
}

NerdGraph queries for Scorecards

You can retrieve all rules associated with a specific Scorecard using the FetchScorecardDetails query.

Input parameters

Parameter	Data Type	Is it Required?	Description
`scorecardId`	String	Yes	The Scorecard's ID to fetch the rules.

Sample request

query FetchScorecardDetails($scorecardId: ID!) {
  actor {
    entityManagement {
      entity(id: $scorecardId) {
        ... on EntityManagementScorecardEntity {
          name
          description
          progressLevels {
            id
            name
            description
            hexColorCode
          }
          rules {
            id
          }
        }
      }
    }
  }
}

`FetchRulesCollection` query

You can retrieve the details of collection using the FetchRulesCollection query, which requires the rules ID obtained from the FetchScorecardDetails response.

Input parameters

Parameter	Data Type	Is it Required?	Description
`rulesId`	String	Yes	The ID obtained from the `Get rules in a Scorecard` response.

Sample request

query FetchRulesCollection($rulesId: ID!) {
  actor {
    entityManagement {
      collectionElements(filter: { collectionId: { eq: $rulesId } }) {
        items {
          ... on EntityManagementScorecardRuleEntity {
            id
            name
            progressLevel
            impactWeight
            nrqlEngine {
              accounts
              joinAccounts
              query
            }
          }
        }
        nextCursor
      }
    }
  }
}

NerdGraph tutorial: View and manage Scorecards

Mutations

Fetch your organization ID

Sample request

Create a Scorecard

Input parameters

Sample request

Create or update maturity levels

중요

Input parameters

Sample request

Create a rule

Input parameters

Sample request

Add a rule to a Scorecard

Input parameters

Sample request

Update a Scorecard

Input parameters

Sample request

Update a rule

Input parameters

Sample request

Delete a Scorecard or Rule

Input parameters

Sample request

NerdGraph queries for Scorecards

Get rules in a Scorecard

Input parameters

Sample request

Retrieve Scorecard Details Associated with a Rule

`FetchRulesCollection` query

Input parameters

Sample request

NerdGraph tutorial: View and manage Scorecards

Mutations .css-21sua1{background:none;border:none;width:0;padding:0;}

Create a Scorecard

Create or update maturity levels

Create a rule

Add a rule to a Scorecard

Update a Scorecard

Update a rule

Delete a Scorecard or Rule

NerdGraph queries for Scorecards

Get rules in a Scorecard

Retrieve Scorecard Details Associated with a Rule

Mutations