---
title: Custom rules
description: >-
  Create custom Scorecard rules with a DDSQL query, the Scorecards API, or
  Workflow Automation to codify your organization's expectations for software
  components.
breadcrumbs: Docs > Internal Developer Portal > Scorecards > Custom rules
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Custom rules

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

Custom rules allow you to codify your organizations' expectations about your software components, teams, and more. You decide the evaluation criteria, frequency, and data input. You can create custom rules by writing a [DDSQL](https://docs.datadoghq.com/ddsql_reference.md) query or by sending outcomes through the [Scorecards API](https://docs.datadoghq.com/api/latest/service-scorecards.md) or [Datadog Workflow Automation](https://docs.datadoghq.com/actions/workflows.md).

## Create custom rules{% #create-custom-rules %}

1. Navigate to the [Scorecards page](https://app.datadoghq.com/software/scorecards) and click Create Rule.
1. Specify the name of the rule, the scorecard it belongs to, a rule description, the owning team, and which level the rule belongs to.
1. Under Define evaluation logic, choose how Datadog evaluates the rule:
   - Write a DDSQL Query: Use this option for rules that evaluate data available in Datadog. See Evaluate custom rules using DDSQL.
   - Use a Workflow or Scorecards API: Use this option to evaluate entities and send outcomes from outside Scorecards. See Evaluate custom rules using Workflow Automation and Evaluate custom rules using the Scorecards API or the UI.

The scope defines which entities a rule applies to. For rules that use a workflow or the Scorecards API, specify the scope after you choose the evaluation method. The scope must include at least one entity kind, and can use metadata from entity definitions in IDP Catalog such as `kind`, `team`, or `tier`. For rules that use DDSQL, define the scope in the query's `WHERE` clause instead. For more information, see [Scope scorecard rules](https://docs.datadoghq.com/internal_developer_portal/scorecards/scorecard_configuration.md#scope-scorecard-rules).

To change how an existing rule is evaluated, edit the rule and select a different option under Define evaluation logic. If you switch a rule to DDSQL, you must run a successful test before you can save it, and Datadog removes any linked workflow from the rule. If you switch a rule from DDSQL to a workflow or the Scorecards API, Datadog removes the DDSQL query from the rule.

## Evaluate custom rules using DDSQL{% #evaluate-custom-rules-using-ddsql %}

Your query must:

- Return an `entity_kind`, an `entity_key`, and a `state` for each entity.
- Set `state` to `pass`, `fail`, or `skip`.
- Use the `WHERE` clause to define the scope of the rule.

After you select Write a DDSQL Query:

{% image
   source="https://docs.dd-static.net/images/internal_developer_portal/scorecards/custom_rule_ddsql.a95eb9708713101d12dc77fe6a7f3092.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/internal_developer_portal/scorecards/custom_rule_ddsql.a95eb9708713101d12dc77fe6a7f3092.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The New Rule page with a DDSQL query that checks whether each service has a docs link, a successful test result, and a preview of passing and failing entities." /%}

1. Write your query in the editor. Replace each placeholder in the query template, or copy a complete query from the Examples tab in the DDSQL Help panel. Use the Data Sources tab to view the available data sources and columns.
   - Optionally, click Ask Bits to open Bits Chat and draft a query from your prompt.
1. Click Run Test to evaluate the query against all entities in scope. You must run a successful test before you can save the rule.
1. Review the results in the Preview pane.
1. Click Create Rule. Datadog evaluates the query every 4 hours and updates an outcome only if it changed.
1. On the rule page, view the query and an overview of outcomes:
   - The Evaluation section shows when the query last ran successfully.
   - The Last Updated column shows the last time an outcome changed.
   - To edit the query, click Edit.

## Evaluate custom rules using the Scorecards API or the UI{% #evaluate-custom-rules-using-the-scorecards-api-or-the-ui %}

You can send outcomes for a custom rule from your own systems through the Scorecards API, or set them manually for each entity in the Scorecards UI.

### Use the Scorecards API{% #use-the-scorecards-api %}

To add and evaluate custom rules using the [Scorecards API](https://docs.datadoghq.com/api/latest/service-scorecards.md):

1. Specify the rule's name, scorecard, description, owner, level, and scope. Pass these values to `/scorecard/rules`.
1. For each `{rule, entity}` tuple that you evaluate, send an outcome of `pass`, `fail`, or `skip` to `/scorecard/outcomes/batch`. Optionally, include a remark that describes the reason for the outcome.
1. View an overview of outcomes and remarks in the Scorecards dashboard.

After initial setup, rules can also be enabled or disabled through the API.

### Use the Scorecards UI{% #use-the-scorecards-ui %}

To evaluate a custom rule manually in the Scorecards UI, first create the rule as described in Create custom rules. Then:

1. Navigate to the rule you created and select Edit Outcome next to the entity that you want to evaluate.
1. Select the relevant outcome of `pass`, `fail`, or `skip` and add an optional remark describing the reason for the outcome.
1. View an overview of outcomes and remarks in the Scorecards dashboard.

## Evaluate custom rules using Workflow Automation{% #evaluate-custom-rules-using-workflow-automation %}

Workflow Automation allows you to automate the evaluation of your custom rules in Datadog using the [Update scorecard rule outcome action](https://app.datadoghq.com/workflow/action-catalog#com.datadoghq.dd/com.datadoghq.dd.software_catalog/com.datadoghq.dd.software_catalog.updateScorecardRuleOutcome).

### Create workflow{% #create-workflow %}

After creating your custom rule, choose the Add Workflow option when prompted to configure its evaluation criteria. From there, you can create a workflow from scratch or use a blueprint.

{% collapsible-section #workflow-from-scratch %}
#### From scratch

{% image
   source="https://docs.dd-static.net/images/tracing/software_catalog/scorecards_workflow_example.e86517617909b7bececbb49dd4f099bd.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/software_catalog/scorecards_workflow_example.e86517617909b7bececbb49dd4f099bd.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Workflow evaluating whether an entity has a tier defined in Catalog" /%}

To create a workflow from scratch:

1. Set a schedule for your workflow to run on.
1. Click the plus (+) icon to add a step.
1. Select the [List entity definitions action](https://app.datadoghq.com/actions/action-catalog#/com.datadoghq.dd.softwarecatalog.listCatalogEntity) to fetch all defined entities from Catalog.
1. Click the plus (+) icon to add a step.
1. Select the [For loop](https://app.datadoghq.com/workflow/action-catalog#//com.datadoghq.core.forLoop) to iterate over each entity one-by-one.
1. Select the action needed to fetch your evaluation data (for example: List monitors or Get repository content from GitHub).
1. Transform the returned data using a custom JavaScript function to generate pass/fail outcomes for each entity.
1. Use the [Update scorecard rule outcome action](https://app.datadoghq.com/workflow/action-catalog#com.datadoghq.dd/com.datadoghq.dd.software_catalog/com.datadoghq.dd.software_catalog.updateScorecardRuleOutcome) to send results to Scorecards.
1. Run the workflow to see your evaluations appear in Scorecards for your custom rule.
1. Publish the workflow; unpublished workflows do not run automatically.

{% /collapsible-section %}

{% collapsible-section #workflow-from-blueprint %}
#### From blueprint

Instead of creating a workflow from scratch, you can start with a Scorecards blueprint:

1. Explore [Scorecards blueprints](https://app.datadoghq.com/workflow/blueprints?selected_category=SCORECARDS) and select one.

1. Edit the blueprint to create your custom workflow.

**Note**: All Scorecards blueprints include the [Update scorecard rule outcome action](https://app.datadoghq.com/workflow/action-catalog#com.datadoghq.dd/com.datadoghq.dd.software_catalog/com.datadoghq.dd.software_catalog.updateScorecardRuleOutcome) to send results to Scorecards. Do not delete this step.

1. Run the workflow to see your evaluations appear in Scorecards for your custom rule.

1. Publish the workflow; unpublished workflows do not run automatically.

{% /collapsible-section %}

After the workflow is created, it is automatically linked to the Scorecard rule. Click the link to open the workflow, make changes, and view details such as the owner, run history, and last modified date.

{% image
   source="https://docs.dd-static.net/images/internal_developer_portal/scorecards/linked-workflow.bb1c30e084a3e86b4b99d55f7d70e747.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/internal_developer_portal/scorecards/linked-workflow.bb1c30e084a3e86b4b99d55f7d70e747.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The detailed panel for an individual Scorecard, highlighting the linked workflow automation" /%}

All Workflows created from the Scorecards page or from a Scorecards blueprint are automatically tagged with `source: scorecards` for searching and filtering.

**Note**: Clicking the red unlink button on a Scorecard rule removes the workflow from the rule but does not automatically unpublish the workflow. To prevent evaluations from running, you should also unpublish any unlinked workflows.

### Link existing workflow{% #link-existing-workflow %}

After creating your custom rule, choose the Add Workflow option to configure its evaluation criteria. Search for and select an existing workflow to link to the rule.

You can also link an existing workflow to any custom rule that already generates outcomes:

1. Click the custom rule.
1. Select Link Workflow.
1. Search for a workflow and select it to link it to the rule.

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Catalog](https://docs.datadoghq.com/internal_developer_portal/catalog.md)
- [Scorecards API](https://docs.datadoghq.com/api/latest/service-scorecards.md)
- [Prioritize and promote service observability best practices with Scorecards](https://www.datadoghq.com/blog/service-scorecards/)
- [Formalize best practices with custom Scorecards](https://www.datadoghq.com/blog/datadog-custom-scorecards/)
- [Track DORA Metrics with Datadog](https://docs.datadoghq.com/delivery_performance/dora_metrics.md)
