Manage scorecards

Define scorecards

Port offers a variety of ways to create, edit and delete scorecards:

UI

To create a scorecard from the UI:

1. Go to the Data model page of your portal.

2. Expand the relevant blueprint, and click on the Scorecards tab.

3. Click on the + New scorecard button.

4. In the Basic Details tab, specify the scorecard's basic details:

   • Title - The scorecard's title.
   • Identifier - The scorecard's identifier.
   • Blueprint - Set to the blueprint you selected.
   • Filter - Filter which entities the scorecard applies to.

5. In the Rules tab, define the scorecard's rules:

   • Add or remove levels, as well as edit their names.
   • Add rule elements to each level:
     • Title - The rule's title.
     • Identifier - The rule's identifier.
     • Description - The rule's description.
     • Conditions - The rule's conditions.

6. Click Save to create the scorecard.

Scorecard JSON structure

Instead of using the form, you can also create or edit scorecards in JSON format.
Click on the {...} Edit JSON button in the top right corner of the scorecard creation form.

Below is an example of a scorecard in JSON format:

Ownership scorecard example (click to expand)

{
  "identifier": "Ownership",
  "title": "Ownership",
  "rules": [
    {
      "identifier": "hasSlackChannel",
      "title": "Has Slack Channel",
      "level": "Silver",
      "query": {
        "combinator": "and",
        "conditions": [
          {
            "operator": "isNotEmpty",
              "property": "slackChannel"
          }
        ]
      }
    },
    {
      "identifier": "hasTeam",
      "title": "Has Team",
      "level": "Bronze",
      "query": {
        "combinator": "and",
        "conditions": [
          {
            "operator": "isNotEmpty",
            "property": "$team"
          }
        ]
      }
    }
  ]
}

API

Access token required

Remember that an access token is necessary in order to make API requests. If you need to generate a new token, refer to Getting an API token.

Create scorecards

In order to create a scorecard from the API, you will make a PUT request to the following URL: https://api.getport.io/v1/blueprints/{blueprint_identifier}/scorecards.

Here are some request examples that will create the Scorecard of Ownership on the microservice Blueprint:

Python

Create scorecards python example (click to expand)

# Dependencies to install:
# $ python -m pip install requests

# the access_token variable should already have the token from previous examples

import requests

API_URL = 'https://api.getport.io/v1'

blueprint_name = 'microservice'

scorecards = [
  {
    'identifier': 'Ownership',
    'title': 'Ownership',
    'rules': [
      {
        'identifier': 'hasSlackChannel',
        'title': 'Has Slack Channel',
        'level': 'Silver',
        'query': {
          'combinator': 'and',
          'conditions': [{'operator': 'isNotEmpty', 'property': 'slackChannel'}]
        }
      },
      {
        'identifier': 'hasTeam',
        'title': 'Has Team',
        'level': 'Bronze',
        'query': {
          'combinator': 'and',
          'conditions': [{'operator': 'isNotEmpty', 'property': '$team'}]
        }
      }
    ]
  }
]

headers = {
    'Authorization': f'Bearer {access_token}'
}

response = requests.put(f'{API_URL}/blueprints/{blueprint_name}/scorecards', json=scorecards, headers=headers)

Javascript

Create scorecards javaScript example (click to expand)

// Dependencies to install:
// $ npm install axios --save

// the accessToken variable should already have the token from previous examples

const axios = require("axios").default;

const API_URL = "https://api.getport.io/v1";

const blueprintName = "microservice";

const scorecards = [
    {
        identifier: "Ownership",
        title: "Ownership",
        rules: [
            {
                identifier: "hasSlackChannel",
                title: "Has Slack Channel",
                level: "Bronze",
                query: {
                    combinator: "and",
                    conditions: [
                        {
                            operator: "isNotEmpty",
                            property: "slackChannel",
                        },
                    ],
                },
            },
            {
                identifier: "hasTeam",
                title: "Has Team",
                level: "Silver",
                query: {
                    combinator: "and",
                    conditions: [
                        {
                            operator: "isNotEmpty",
                            property: "$team",
                        },
                    ],
                },
            },
        ],
    },
];

const config = {
    headers: {
        Authorization: `Bearer ${accessToken}`,
    },
};

const response = await axios.put(
    `${API_URL}/blueprints/${blueprintName}/scorecards`,
    scorecards,
    config
);

After creating the Scorecards, you will see a new tab in the profile Entity page of each of your Blueprint's Entities, showing the various scorecards levels.

For example, we can create the entity below

{
    "identifier": "cart-service",
    "title": "Cart Service",
    "icon": "Microservice",
    "properties": {
        "slackChannel": "https://slack.com",
        "repoUrl": "https://github.com"
    },
    "relations": {}
}

And then look at the specific page of this entity, on the scorecards tab

We can see that the hasSlackChannel rule passed because we provided one to that entity, while the hasTeam failed because we didn't provide any team.

Therefore the level of the entity is Bronze because it passed all the rules in the Bronze level (hasSlackChannel)

Update scorecards

To update a scorecard you can use 2 different URLs:

1. Update a single Scorecard using the URL https://api.getport.io/v1/blueprints/{blueprint_identifier}/scorecards/{scorecard_identifier}. The request body will be the full Scorecard + the wanted changed values
2. Make a PUT request to the URL https://api.getport.io/v1/blueprints/{blueprint_identifier}/scorecards. to multiple scorecards at once

The request body will include the existing body of the Scorecard, after the desired updates to the existing Scorecard have been applied.

Delete scorecards

danger

A Scorecard cannot be restored after deletion!

• Make an HTTP PUT request and remove it from the array of the scorecards via the URL https://api.getport.io/v1/blueprints/{blueprint_identifier}/scorecards
• Make an HTTP DELETE request to the URL https://api.getport.io/v1/blueprints/{blueprint_identifier}/scorecards/{scorecard_identifier} the scorecard_identifier is the identifier of the scorecard we want to delete

note

When using the multiple update Scorecards https://api.getport.io/v1/blueprints/{blueprint_identifier}/scorecards PUT request, keep in mind that you will see a new id property. This is used via Port to identify the Scorecard in order to be able to update its properties

Terraform

Create scorecards

In order to create a scorecard from the Terraform provider , you will need to use the port_scorecard resource.

Here is an example of how to create an Ownership scorecard with the Terraform provider:

Terraform create example (click to expand)

resource "port_scorecard" "ownership" {
  blueprint = "microservice"
  identifier = "Ownership"
  title = "Ownership"
  rules = [
    {
      identifier = "hasSlackChannel"
      title = "Has Slack Channel"
      level = "Silver"
      query = {
        combinator = "and"
        conditions = [
          jsonencode({
            operator = "isNotEmpty"
            property = "slackChannel"
          })
        ]
      }
    },
    {
      identifier = "hasTeam"
      title = "Has Team"
      level = "Bronze"
      query = {
        combinator = "and"
        conditions = [
          jsonencode({
            operator = "isNotEmpty"
            property = "$team"
          })
        ]
      }
    }
  ]
}

Update scorecards

In order to update a scorecard with the Terraform provider, you will need to run the terraform apply -target=port_scorecard.<resourceId> command with the updated scorecard resource.

Delete Scorecards

danger

A Scorecard cannot be restored after deletion!

In order to delete a scorecard using the Terraform provider, use the terraform destroy -target=port_scorecard.<resourceId> command with the scorecard resource you want to delete. (remember that it is also possible to remove the definition of the port_scorecard resource from the .tf file and run terraform apply)

Scorecards as blueprints

With the scorecards as blueprints feature, you can manage scorecards as blueprints and entities. This approach provides rich customization, visualization, and automation capabilities for your scorecards.

Since scorecards are now blueprints (which can be extended with additional properties) and their instances are entities, use the following endpoints and Terraform resources to manage them.

When this feature is enabled, you can use either of the following methods to manage scorecards:

UI

To create a scorecard from the UI, you can use either one of the following methods:

Method 1: From the scorecards catalog page

1. Navigate to the Software Catalog page.

2. Go to the Scorecards page.

3. Click the + Scorecard button in the top right corner of the page.

4. Fill in the form and click Save.

Method 2: From the Data model page

1. Go to the Data model page of your portal.

2. Expand the relevant blueprint, and click on the Scorecards tab.

3. Click on the + New scorecard button.

4. Fill in the form and click Save.

API

Manage scorecards through the standard blueprints and entities API endpoints:

• Update scorecard blueprints.
• Create, update, or delete scorecard entities.

Terraform

Manage scorecards using Terraform resources:

• Update scorecard blueprints.
• Create, update, or delete scorecard entities.

To learn more, refer to the scorecards as blueprints page.

Next steps

Dive into advanced operations on Scorecards with our API ➡️