Skip to main content

Blueprints

A blueprint is an entity type. It defines the properties an entity has, which of them are required, and the relations it can have to other entities. Every entity in the Context Graph belongs to exactly one blueprint.

There are three kinds:

KindWhat it isWho defines itCan you change it?
SystemThe core entity types: Service, Team, Person, Repository. Agents and the UI read these.AutohealNo
IntegrationOne type per kind of object an integration syncs, such as pagerduty_service. Holds source records.Autoheal, with each integrationNo
CustomEntity types for anything else you track, such as environments, APIs or cloud accounts.YouYes

Open Context Graph → Setup → Blueprints to see every blueprint in the project, where it comes from, and how many entities it has.

How the kinds join​

Integration blueprints are not a parallel graph. The resolver links each integration record to a system entity, and the relations between integration records become relations between system entities. Custom blueprints sit next to the system blueprints and can relate to them.

Integration blueprints, linked by the resolver
pagerduty_servicedatadog_serviceservicenow_servicejira_servicegithub_service
service
github_teampagerduty_teamslack_teamservicenow_teamdatadog_team
team
github_personpagerduty_personslack_personservicenow_personjira_person
person
github_repositorygitlab_repositorybitbucket_repositoryazuredevops_repository
repository
slack_channelservicenow_cmdb_ci
Their own entities
Custom blueprints relate to any blueprint
environment
Custom
service
System
api
Custom

Two integration blueprints have no system counterpart: slack_channel and servicenow_cmdb_ci. Each of their records is its own entity in the graph.

System blueprints​

Service​

A software service or application component. Identity: a declared service name, the service name a monitoring tool reports, or a repository's service property. See Identity rules.

PropertyTypeDescription
descriptionstringWhat the service does
tierstringtier-1, tier-2, tier-3 or tier-4
languagestringPrimary language
repository_urlstring, URLMain repository
documentation_urlstring, URLDocumentation
RelationTargetTargetsDescription
ownerteamoneThe team responsible for the service
depends_onservicemanyServices this service calls or needs
contributorspersonmanyPeople who work on the service. Each edge has a role.

Team​

An engineering team or squad. Identity: a link you make, or the normalized team name.

PropertyTypeDescription
descriptionstringWhat the team does
timezonestringThe team's main timezone
notification_channelsarraySlack channels for notifications tagged with this team. Each item has provider (slack), channel_id, channel_name, and integration_id for organizations with several Slack workspaces.
slack_team_idstringThe team's Slack user group ID
RelationTargetTargetsDescription
memberspersonmanyTeam members. Each edge has a role.

Person​

A member of your organization. Identity: verified email address, then single sign-on identity.

PropertyTypeDescription
emailstring, emailWork email address
display_namestringDisplay name
slack_user_id, slack_username, slack_timezonestringThe person's Slack account
routing_instructionsstringPlain-language description of what this person owns, for example "Owns checkout and the Stripe integration." Autoheal uses it to pick who to assign work to.
country_code, phone_numberstringPhone number for paging. Digits only, no +. Set both or neither.

A person has no relations of its own. Teams point to their members, and services point to their contributors.

Repository​

A source code repository from GitHub, GitLab, Bitbucket or Azure DevOps. Identity: provider, host and repository ID, so a renamed repository stays the same entity.

PropertyTypeDescription
full_namestringorg/repo, org/project/repo or namespace/project
providerstringgithub, gitlab, bitbucket or azuredevops
description, language, default_branchstringFrom the provider
visibilitystringpublic, private or internal
url, clone_urlstring, URLWeb and clone URLs
archived, is_forkbooleanRepository state
topicsarray of stringRepository topics
last_pushed_atstring, date-timeTime of the last push
stars, forks, open_issues, size_kbintegerActivity and size
integration_idstringThe integration connection that reads this repository. Agents clone with its credentials.
RelationTargetTargetsDescription
part_ofserviceoneThe service this repository builds
ownerteamoneThe team responsible for the repository

Every system blueprint also has a sources property: the integrations that supplied the entity. The entity's Sources tab shows the detail for each field.

Integration blueprints​

Each integration ships the blueprints for the objects it syncs. Their names are <integration>_<kind>. You cannot change or delete them.

IntegrationBlueprintLinked toNotable properties
GitHubgithub_repositoryrepositorygh_repo_id, gh_org, plus the repository properties
github_teamteamgh_team_slug, gh_org, gh_privacy, gh_permission
github_personpersongh_login, gh_user_id, email
github_serviceservicegh_repo_full_name, gh_topics
GitLabgitlab_repositoryrepositorygl_project_id, gl_namespace
Bitbucketbitbucket_repositoryrepositorybb_workspace, bb_slug
Azure DevOpsazuredevops_repositoryrepositoryado_repo_id, ado_org, ado_project
PagerDutypagerduty_serviceservicepd_service_id, status, tier, html_url
pagerduty_teamteampd_team_id, default_role
pagerduty_personpersonpd_user_id, email, role, time_zone, country_code, phone_number
Slackslack_personpersonslack_user_id, slack_team_id, email, slack_timezone
slack_teamteamslack_group_id, slack_group_handle, slack_member_count
slack_channel(its own entity)slack_channel_id, slack_channel_name, slack_is_private, slack_num_members
ServiceNowservicenow_serviceservicesnow_ci_id, operational_status, business_criticality
servicenow_teamteamsnow_group_id, email, active
servicenow_personpersonsnow_user_id, email, title, active
servicenow_cmdb_ci(its own entity)snow_ci_id, sys_class_name, environment, ip_address, fqdn
Datadogdatadog_serviceservicedd_service_name, dd_environment, tier, lifecycle, tags
datadog_teamteamdd_team_id, dd_team_handle, slack_channel
Jirajira_serviceservicejira_project_key, jira_project_type, jira_component_name
jira_personpersonjira_account_id, email, jira_active

Every integration blueprint also has raw_data: the original object from the integration's API, compressed. Open it from an entity's Sources tab.

When the resolver copies a value to the system entity, it converts it to the system blueprint's form. For example, PagerDuty and Datadog tiers critical, high, medium and low become tier-1 to tier-4.

Integration blueprints also relate to each other, for example pagerduty_service owner pagerduty_team. The resolver turns these into system relations. See Relations inside an integration.

Custom blueprints​

Define a custom blueprint for anything your agents should know about that the system blueprints do not cover: environments, APIs, cloud accounts, feature flags, data pipelines, customers.

Create a blueprint in the UI​

  1. Open Context Graph → Setup → Blueprints and select New blueprint.
  2. Enter a title, such as Environment. The name follows the title. Change the name before you create the blueprint, because it cannot change later: labels and relations refer to it.
  3. Choose an icon. The graph, filters and tables show the blueprint's entities with it.
  4. Enter a description.
  5. Add fields. Each field has a label, a key, a type, and can be required. The types are Text, Number, Whole number, Yes / no, Choice (a list of allowed values), URL, Email and Date.
  6. Select Review. Check the schema, then select Create blueprint.

The new blueprint appears at once in the Blueprints list, in Filters, and in the + menu on the graph, where you create its first entity. If the name is taken or the schema is not valid, the form shows the error and keeps what you entered. To change the icon later, select the icon on the blueprint's row in Blueprints.

To add relations to other blueprints, use the API.

Create a blueprint from a CSV file​

If the data is already in a spreadsheet, start from the file:

  1. Open Context Graph → Setup → Blueprints, select New blueprint, then From CSV.
  2. Upload the CSV file. Autoheal reads the header and sample rows, and suggests a property name and type for each column.
  3. Choose the column that holds each entity's name, and the one for its title.
  4. Correct property names, types and required fields. The preview shows sample rows as entities.
  5. Select Create and import. Autoheal creates the blueprint, then imports each row as an entity.

The result lists how many rows were imported and why each failed row was refused. A CSV import runs once. To keep the data current from a system of record, use the push API with a full run.

Create a blueprint with the API​

JSON
{
"name": "environment",
"title": "Environment",
"description": "A place where services run",
"icon": "globe",
"schema": {
"properties": {
"stage": {"type": "string", "title": "Stage", "enum": ["dev", "staging", "prod"]},
"region": {"type": "string", "title": "Region"},
"cloud_account": {"type": "string", "title": "Cloud account"}
},
"required": ["stage"]
},
"relations": {
"services": {"title": "Services", "target": "service", "many": true}
}
}

Save it as blueprint.json and create it with the CLI:

BASH
autoheal context-graph blueprints create --input blueprint.json

The CLI calls POST /api/v1/context-graph/blueprints. See Context Graph API.

After you create it, the blueprint name works as a label key. An agent labeled - environment: prod-us is associated with the prod-us environment. See Label associations.

Change or delete a custom blueprint​

  • You can change the title, description, icon, properties, required fields and relations. You cannot change the name.
  • A schema change does not rewrite existing entities. Each entity is checked against the new schema the next time it is written.
  • Removing a property from the schema keeps existing values on entities. They are no longer validated.
  • You can delete a blueprint only when it has no entities. Delete or move its entities first.

Rules​

  • A name starts with a lowercase letter and has up to 63 characters: lowercase letters, digits, - and _.
  • A name cannot be the name of a system or integration blueprint, or of a graph node kind: catalog_entity, integration, skill, agent, memory, artifact or run.
  • A property key starts with a lowercase letter and has up to 64 characters: lowercase letters, digits and _.
  • enum is allowed only on string properties. Its values cannot be empty or repeated.
  • Each key in required must be a property in the schema.
  • Each relation's target must be a blueprint in the project: system, integration or custom. A relation can also target its own blueprint.
  • An icon is a Phosphor icon name as the site shows it, such as database or hard-drives. The graph shows its default icon for a name it does not have.
  • A custom blueprint belongs to one project. Each project defines its own.
  • Creating a blueprint needs the blueprint:create permission, and changing one needs blueprint:update. The Project Admin role has both. See Roles.

Schema reference​

Blueprint​

FieldRequiredDescription
nameYesThe blueprint's permanent name.
titleNoDisplay name. Default: the name. Up to 200 characters.
descriptionNoUp to 2,000 characters.
iconNoA Phosphor icon name, for example database, hard-drives or globe.
schema.propertiesYesA map of property name to property definition.
schema.requiredNoProperty names every entity must have.
relationsNoA map of relation key to relation definition.

Property​

FieldDescription
typeRequired. string, number, integer, boolean, array or object.
titleDisplay name.
descriptionShown as help text in forms, and to agents that read the blueprint.
enumAllowed values.
formatFor strings: uri, email, date, date-time, markdown or yaml. Sets how the value is shown and checked.
defaultThe value used when an entity does not set one.
itemsFor arrays: the definition of each item.
minLength, maxLength, patternLimits for strings.
minimum, maximumLimits for numbers.

Relation​

FieldDescription
targetRequired. The target blueprint's name. It can be a system, integration or custom blueprint.
titleDisplay name.
descriptionShown as help text, and to agents.
manytrue for a list of targets. Default false: one target.
requiredtrue if every entity must have a target. Default false.
schema.propertiesProperties stored on each edge, such as a contributor's role. Same format as blueprint properties.

Validation​

Autoheal checks an entity against its blueprint each time the entity is created or updated, from any source:

CheckError
A property has the wrong type, is not in enum, or breaks a limit or format14102
A required property is missing14102
A relation key is not in the blueprint14112
A one-target relation has several targets14111
A required relation is missing14110
A relation target has the wrong blueprint14109

Properties that are not in the schema are kept, but they are not validated and do not appear in forms.