Skip to main content

Blueprint

What is a Blueprint?

A Blueprint is our basic building block in Port. It represents assets that can be managed in Port, such as Microservice, Environments, Packages, Clusters, Databases, and many more.

Blueprints are completely customizable, and they support any number of properties the user chooses, all of which can be modified as you go.

Defining your blueprints

Before you start, there are a few things to consider when defining your Blueprints:

  1. What part of your infrastructure do you want to manage, or in other words, what is the best way to catalog your software and infrastructure to reflect the architecture that matters for the developer portal experience? For example, in one organization, the focus could be managing microservices (with clusters, deployments, etc...). While in another, it could be understanding what dev environments the organization has in a given moment.

  2. What properties characterize your assets? For example, a microservice’s characteristics could be its owner, a link to its Github repository, a relevant slack channel and a health check status.

  3. What are the relationships between the different assets? For example, relations between microservices and deployments that track where each microservice is deployed.

note

By the end of this section, you should have a Blueprint architecture similar to this in mind:

Example Blueprints and Relations Layout

Blueprint structure

Blueprint JSON schema

Each Blueprint is represented by a Json schema, as shown in the following section:

{
"identifier": "UniqueID",
"title": "Title",
"description": "Description",
"icon": "Service",
"formulaProperties": {},
"calculationProperties": {},
"schema": {
"properties": {
"foo": {
"type": "string",
"title": "Foo"
},
"bar": {
"type": "number",
"title": "Bar"
},
"date": {
"type": "string",
"format": "date-time",
"title": "Date"
}
},
"required": []
},
"relations": {}
}

Structure table

FieldTypeDescriptionOptional Values
identifierStringUnique identifier.
Note that while the identifier is unique, it can be changed after creation
titleStringThe Blueprint's name
descriptionStringDescription for the Blueprint.
This value is visible to users when hovering on the info icon in the UI.
iconStringIcon for the Blueprint's graph node, and Entities of the BlueprintIcon options: Airflow, Ansible, Argo, Aws, Azure, Blueprint, Bucket, Cloud,...

See the full icon list below.
formulaPropertiesObjectContains the properties that are defined using formula templatesExample: "repo-link": "https://github.com/{{$identifier}}"
schemaObjectObject containing two more nested fields, including properties and requiredSee the schema structure here.
changelogDestinationObjectDefines the destination where events that happen within the Blueprint's context will be deliveredSee the object structure here.

Special blueprint fields

FieldTypeDescriptionOptional Values
relationsObjectContains the Relations of the Blueprint
mirrorPropertiesObjectBecomes available when a Relation is defined between two blueprints.
A Mirror Property represents additional data queried from the related Entity.
See more details on the Mirror Properties page.

Full icon list

Available Icons

Airflow, Ansible, Argo, Aws, Azure, Blueprint, Bucket, Cloud, Cluster, CPU, Customer, Datadog, DefaultEntity, DefaultProperty, DeployedAt, Deployment, DevopsTool, Docs, Environment, Git, Github, GitVersion, GoogleCloud, GPU, Grafana, Jenkins, Lambda, Link, Lock, Microservice, Moon, Node, Okta, Package, Permission, Server, Service, Terraform

Blueprint schema

    "schema"; {
"properties": {},
"required": []
}
Schema fieldTypeDescription
propertiesObjectSee our properties section for more details.
requiredListA list of the required properties, out of the properties object list.
These are mandatory fields to fill in the UI form.

Blueprint properties

Each Blueprint has a properties section under its schema. In this section, you can define all of the unique properties that describe your asset.

For Example:

"string_prop": {
"title": "My String Property",
"type": "string",
"default": "foo",
"icon": "Microservice",
"description": "This is a string property"
}

Now let's look at the structure of this property definition and also explore the entire set of options for a single property:

FieldTypeDescription
titleStringProperty name
typeStringMandatory field. The data type of the property. You can explore all available types in the Property Types section
formatStringSpecific data format to pair with some of the available types. You can explore all formats in the String Formats section
patternStringRegular expression (regex) pattern to specify the set of allowed values for the property. You can see an example in the String regular expression patterns section
defaultShould match the typeDefault value for this property in case an Entity is created without explicitly providing a value.
iconStringIcon for the property column in the Blueprint page, in the Entity page and in the Entity creation form

See the full icon list above.
descriptionStringDescription of the property.
This value is visible to users when hovering on the info icon in the UI. It provides detailed information about the use of a specific property.
enumColorsObjectDefine colors for enum fields.
Can be added only if an enum field exists.
Each key is one of the defined enum options and each value is one of the following colors:
[blue, turquoise, orange, purple, lightBlue, pink, yellow, green, red, darkGray]

Notice: In case enum is defined and enumColor field is not default colors will be set
tip

We highly recommend you set a description, so your developers will understand the property’s context.

Property Description Tooltip Example

Property types

"string_prop": {
"title": "My String Property",
"type": "string",
"default": "foo",
"description": "This is a string property"
}

We currently support the following types:

typeDescriptionExample values
stringA free-text string value"This is a string field"
numberNumeric field (including integers, doubles, floats, etc...)1, 2.3, 5e3,...
booleanBoolean fieldA true or false
objectA well formatted object (i.e. python dictionary, javascript object, JSON, etc...){ 'key1': 'value1', 'key2': 'value2', ...}
arrayA multi-element array[1,2,3], ["a","b","c"]
note

Those are the properties that our API supports. See API reference.

We support the following additional props:

DescriptionExample values
enumField with a pre-defined set of allowed values. Can be used with properties of type string or number["Option 1", "Option 2", "Option 3"]
specField with a pre-defined set of allowed values. A property with a spec key will be displayed as a separate tab in the Specific Entity Page.open-api, embedded-url

Examples

Here is how property definitions look like for all available types (remember that only the type field is mandatory):

String

{
"title": "String Property",
"type": "string",
"description": "A string property",
"default": "foo"
}

Number

{
"title": "Number Property",
"type": "number",
"description": "A number property",
"default": 42
}

Boolean

{
"title": "Boolean Property",
"type": "boolean",
"description": "A boolean property",
"default": true
}

Object

{
"title": "Object Property",
"type": "object",
"description": "An object property",
"default": {
"foo": "bar"
}
}

Array

{
"title": "Array Property",
"type": "array",
"description": "An array property",
"default": [1, 2, 3]
}

Objects Array

{
"title": "Array of Objects",
"type": "array",
"items": {
"type": "object"
},
"description": "An array property",
"default": [
{
"foo": "bar",
"version": 1
}
]
}

URLs Array

{
"title": "Array of URLs",
"type": "array",
"items": {
"type": "string",
"format": "url"
},
"description": "An array of URLs property"
}

Enum

{
"title": "Enum field",
"type": "string",
"enum": ["Option 1", "Option 2", "Option 3"],
"enumColors": {
"Option 1": "red",
"Option 2": "green",
"Option 3": "blue"
},
"description": "Enum dropdown menu"
}

Spec

{
"title": "Swagger",
"type": "object",
"spec": "open-api",
"description": "Open-API Prop"
}

String property formats

"string_prop": {
"title": "My String Property",
"type": "string",
"format": "url",
"default": "foo",
"description": "This is a string property"
}

We currently support the following string formats:

formatDescriptionExample values
urlFormatted URL"https://getport.io"
emailFormatted Email"port@getport.io"
userFormatted Email"port@getport.io"
date-timeFormatted ISO string datetime"2022-04-18T11:44:15.345Z"
ipv4Standard IPv4 address127.0.0.1
ipv6Standard IPv6 addressFE80:CD00:0A20:0CDE:1257:1C34:211E:729C
yamla YAML file contenta: 123
markdownString in markdown language formatAn Example of **bold text**.
note

Those are the format types that our API supports. See API reference.

Examples

Here is how to use property formats:

URL

{
"title": "URL Property",
"type": "string",
"format": "url",
"description": "A URL property",
"default": "https://getport.io"
}

Email

{
"title": "Email Property",
"type": "string",
"format": "email",
"description": "An Email property",
"default": "mor@getport.io"
}

User

{
"title": "User Property",
"type": "string",
"format": "user",
"description": "A User property"
}
note

Even though the input is the same in both email and user formats, their presentation is different:

  • email format displays the raw email string;
  • user format displays the user's name and avatar from Port's list of known users.

In addition, user format distinguishes between users by their status:

User StatusExample
ActiveActive user
InvitedInvited user
UnregisteredExternal user

Date Time

{
"title": "Datetime Property",
"type": "string",
"format": "date-time",
"description": "A datetime property",
"default": "2022-04-18T11:44:15.345Z"
}

IPv4

{
"title": "IPv4 Property",
"type": "string",
"format": "ipv4",
"description": "An IPv4 property",
"default": "127.0.0.1"
}

IPv6

{
"title": "IPv6 Property",
"type": "string",
"format": "ipv6",
"description": "An IPv6 property",
"default": "0000:0000:0000:0000:0000:0000:0000:0000"
}

Yaml

"config": {
"title": "Microservice Config",
"type": "string",
"format": "yaml",
"description": "The configuration to use when deploying the service"
}

You can see below a python code snippet that parses a yaml formatted property as a dictionary object:

Click here to see the code

The Entity used in the example:

{
"identifier": "my-cool-service-prod",
"title": "Cool Service Production",
"properties": {
{...} // some properties
"config": "do_awesome_things: true\nthings_not_to_do:\n - fail\n - be slow\n - have bugs"
}
}

Snippet to fetch the config property and parse it from yaml to a python dictionary:

# pip install pyyaml requests
import yaml
import requests

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

target_blueprint = 'Microservice'
target_entity = 'my-cool-service-prod'

credentials = {'clientId': 'YOUR_CLIENT_ID', 'clientSecret': 'YOUR_CLIENT_SECRET'}
token_response = requests.post(f'{API_URL}/auth/access_token', json=credentials)
access_token = token_response.json()['accessToken']

headers = {
'Authorization': f'Bearer {access_token}'
}
response = requests.get(f'{API_URL}/blueprints/{target_blueprint}/entities/{target_entity}', headers=headers)

config_prop = yaml.safe_load(response.json()["entity"]["properties"]["config"])

print(config_prop["do_awesome_things"]) # prints: True

Markdown

{
"title": "Markdown Property",
"type": "string",
"format": "markdown",
"description": "A Markdown property"
}

String regular expression patterns

In order to use a regex pattern for a property value, both the "type": "string" and the "pattern": "[REGEX_PATTERN]" keys need to be used in the property JSON.

A regex pattern will limit the set of legal values only to ones that are matched by the specified [REGEX_PATTERN]:

"regex_prop": {
"title": "Regex Pattern Property",
"type": "string",
"pattern": "[a-zA-Z0-9]",
"description": "A property that supports values specified by a regex pattern",
"default": "Port1337"
}

In the example above, the pattern [a-zA-Z0-9] sets the following rules:

  • Letters in the range a-z will be matched, in both lowercase and uppercase form
  • Digits in the range 0-9 will be matched
  • Any combination of characters and digits from the previous rules will be matched
tip

Port supports standard Javascript regex syntax (ECMA 262), for quick reference of some of the available regex syntax, refer to the JSON Schema docs

Property icons

You can add icons to properties:

"string_prop": {
"title": "My String Property",
"type": "string",
"icon": "Github",
"default": "foo",
"description": "This is a string property"
}

The icon will be displayed in the column header of the property (in the example above - repoUrl):

Blueprints graph with new Microservice

For a list of available icons refer to the full icon list

Changelog destination

The changelogDestination object controls whether events that happen in the context of the Blueprint are reported to a user configured destination, and if so to which destination.

Events that the changelogDestination configuration will report on include:

  • Changes to the Blueprint schema'
  • Creation of new Entities that match the type of the Blueprint;
  • Changes to Entities that match the type of the Blueprint;
  • And more.

The changelogDestination supports 2 configurations:

tip

If you don't want to send changelog events to any destination, you can simply remove the changeLog destination from the Blueprint JSON.

Changelog destination structure fields

FieldTypeDescriptionExample values
typestringDefines the changelog destination typeEither WEBHOOK or KAFKA
urlstringDefines the webhook URL where Port sends changelog events to via HTTP POST request.
Can be added only if type is set to WEBHOOK
https://example.com

For more information about Port's changelog capabilities, refer to the Port execution architecture page.

Mirror properties

When two Blueprints are connected via a Relation, a new set of properties becomes available to Entities in the source Blueprint.

Those new properties are called mirrorProperties, you can learn more about them in the mirrorProperties page.

Next Steps

Explore How to Create, Edit, and Delete Blueprints with basic examples

Dive into advanced operations on Blueprints with our API ➡️