--- title: NerdGraph tutorial: View and manage Scorecards source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-scorecards-tutorial --- New Relic lets you to use NerdGraph [Scorecards](https://docs.newrelic.com/docs/service-architecture-intelligence/scorecards/getting-started) 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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-scorecards-custom-tutorial). ## Mutations [#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](https://docs.newrelic.com/docs/service-architecture-intelligence/scorecards/service-maturity) 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](#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](https://docs.newrelic.com/docs/service-architecture-intelligence/scorecards/service-maturity#weighted-scoring). **Fetch your organization ID** For managing Scorecards and rules, you need to provide your organization ID. You can retrieve your organization ID using the `actor` query. #### Sample request ```graphql query FetchYourOrgId { actor { organization { id } } } ``` **Create a Scorecard** 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](#maturity-levels) for the field details. | #### Sample request ```graphql 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 } } } } ``` ```json // 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). **Create or update maturity levels** Maturity levels are defined by a Scorecard's `progressLevels`. Set them when you [create a Scorecard](#create-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:** 1. Run the [Scorecard read query](#fetch-scorecards) to get your current levels. 2. Call the `entityManagementUpdateScorecard` mutation with the _complete_ `progressLevels` array. Make sure to include the existing levels you want to keep, plus your new one. > #### ⚠️ IMPORTANT > > 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 ```graphql 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 } } } } ``` ```json // 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" } ] } ``` **Create a rule** 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 | The account IDs targeted for rule evaluation. The NRQL query executes against each account specified in this list to assess compliance. | | `joinAccounts` | Int | No | Auxiliary account IDs to include during query execution. Enables cross-account NRQL queries by joining data from these secondary accounts with each primary target account. | | `organizationId` | String (ID) | Yes | Your organization ID, see [Fetch your organization ID](#fetch-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](#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](https://docs.newrelic.com/docs/service-architecture-intelligence/scorecards/service-maturity#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 ```graphql 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 } } } ``` ```json // 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 } ``` **Add a rule to a Scorecard** 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 ```graphql mutation AddRuleToCollection($collectionId: ID!, $rules: [ID!]!) { entityManagementAddCollectionMembers( collectionId: $collectionId ids: $rules ) } ``` ```json // 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. } ``` **Update a Scorecard** 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 ```graphql mutation UpdateScorecard($id: ID!, $description: String, $name: String!) { entityManagementUpdateScorecard( id: $id scorecardEntity: {description: $description, name: $name} ) { entity { name id rules { id } } } } ``` **Update a rule** 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 | The account IDs targeted for rule evaluation. The NRQL query executes against each account specified in this list to assess compliance. | | `joinAccounts` | Int | No | Auxiliary account IDs to include during query execution. Enables cross-account NRQL queries by joining data from these secondary accounts with each primary target account. | | `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](#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](https://docs.newrelic.com/docs/service-architecture-intelligence/scorecards/service-maturity#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 ```graphql 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 } } } } ``` **Delete a Scorecard or Rule** 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 ```graphql mutation DeleteEntity($id: ID!) { entityManagementDelete( id: $id ) { id } } ``` ### NerdGraph queries for Scorecards **Get rules in a Scorecard** 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 ```graphql query FetchScorecardDetails($scorecardId: ID!) { actor { entityManagement { entity(id: $scorecardId) { ... on EntityManagementScorecardEntity { name description progressLevels { id name description hexColorCode } rules { id } } } } } } ``` **Retrieve Scorecard Details Associated with a Rule** ### `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`](#fetch-scorecards) response. | #### Sample request ```graphql query FetchRulesCollection($rulesId: ID!) { actor { entityManagement { collectionElements(filter: { collectionId: { eq: $rulesId } }) { items { ... on EntityManagementScorecardRuleEntity { id name progressLevel impactWeight nrqlEngine { accounts joinAccounts query } } } nextCursor } } } } ```