Creating Entities

Creating entities in Legend follows a consistent four-step wizard that guides you through defining the entity, adding links, attaching documentation, and organizing with tags and relationships.

Creating Many Entities?

To create many entities at once, use the CSV import guide. CSV import is available on Starter and above and handles bulk landmark, person, and team creation with relationships.

Starting the Creation Wizard

To create a new entity:

1. Click the Add button in the top navigation bar
2. Select the entity type: Landmark, Person, or Team
3. The creation wizard opens with four steps

The wizard is the same for all entity types, though some fields appear only for specific types (for example, team membership fields appear only for person entities).

Step 1: Details

The first step collects the core information about your entity.

For all entity types:

• Name: The display name (required)
• Description: A brief summary of what this entity represents

For landmarks:

• Category: Select the category (service, resource, project, event, documentation, external, or custom)
• Icon: Choose an icon from FontAwesome or enter a custom URL
• Owner: Assign a team or person as the owner (optional but recommended)

For people:

• Email: Contact email address (required)
• Title: Job title or role
• Teams: Select one or more teams this person belongs to
• Avatar: Choose Gravatar (uses email) or enter a custom URL

For teams:

• Parent Team: Select a parent team if this team reports to another team (optional)
• Email: Team contact email address
• Icon: Choose an icon from FontAwesome or enter a custom URL

You Can Edit Later

Don’t worry about getting everything perfect in the wizard. You can edit any field after creation by opening the entity detail drawer and clicking Edit.

Click Next to proceed to Step 2.

Step 2: Links

The second step lets you add quick-access links to external resources. These links appear as buttons on the entity card, making it easy to jump to documentation, dashboards, repositories, or other relevant pages.

For each link, provide:

• Title: A short label for the link (e.g., “Documentation”, “Dashboard”, “Repository”)
• URL: The full URL to the resource
• Icon: Optional icon to display with the link

Best practices for links:

• Add 2-5 priority links that people access frequently
• Use clear, action-oriented titles (“View Dashboard” not “Click Here”)
• Include links to runbooks, monitoring dashboards, source code, and contact channels
• Order links by importance; the first link appears most prominently

Examples of useful links:

• Service dashboard (Grafana, Datadog)
• Runbook or operational guide
• Source code repository
• Deployment pipeline
• Slack channel or contact email
• Related documentation

Click Next to proceed to Step 3, or click Skip to skip this step.

Step 3: Documentation

The third step lets you attach markdown documentation files to the entity. These files are stored alongside the entity’s YAML definition and can be searched, viewed, and edited through the Legend interface.

For each documentation file:

• Title: A descriptive title (e.g., “Runbook”, “Architecture Notes”, “Onboarding Guide”)
• Content: Write or paste markdown content

What to document:

• Runbooks: Step-by-step procedures for operating or troubleshooting
• Architecture notes: Design decisions, system diagrams, technical details
• Onboarding guides: Information for new team members
• Incident playbooks: Procedures for handling specific types of incidents
• API documentation: Endpoint descriptions, authentication, examples
• Process documentation: Workflows, approval processes, escalation paths

Documentation features:

• Markdown formatting with full syntax support
• Code blocks with syntax highlighting
• Links to other entities using relative paths
• Searchable content (documentation is included in search results)
• Version controlled (stored as files in the data directory)

Documentation Is Optional

You can skip this step and add documentation later. Open the entity detail drawer and click the Docs tab to add or edit documentation files at any time.

Click Next to proceed to Step 4, or click Skip to skip this step.

Step 4: Organization

The final step lets you organize the entity with tags, categories (for landmarks), and relationships.

Tags:

• Enter tags to categorize and filter entities
• Tags are free-form labels (e.g., “production”, “critical”, “deprecated”, “beta”)
• Use consistent tag names across entities for effective filtering
• Tags appear on entity cards and can be used in search filters

Relationships (for landmarks):

• Depends On: Select other landmarks this entity depends on
• Related To: Select other landmarks that are related but not dependent
• Relationships create the knowledge graph that makes Legend powerful

Access Control (optional):

• Access Groups: Restrict who can view this entity (leave empty for public)
• Edit Groups: Restrict who can edit this entity (leave empty for default behavior)

Access Control Is Advanced

Access groups are an advanced feature. If you’re unsure, leave these fields empty. By default, all authenticated users can view all entities. See Group Management for details on access control.

Click Create to save the entity.

After Creation

After you click Create, the entity is saved and appears on the dashboard. You can:

• View the entity: Click the entity card to open the detail drawer
• Edit the entity: Click Edit in the detail drawer to modify any field
• Add relationships: Use the Relationships tab in the detail drawer
• Add documentation: Use the Docs tab in the detail drawer
• Explore topology: Click the Explore button to visualize relationships

Tips for Effective Entity Creation

Start with the essentials:

• Create entities for things that multiple people need to know about
• Include at least a name, description, and one or two links
• Assign an owner for landmarks to establish accountability

Build gradually:

• You don’t need to add everything at once
• Create the entity first, then enrich it over time
• Add documentation as you learn or as processes evolve
• Define relationships as you discover dependencies

Use consistent naming:

• Choose a naming convention and stick to it
• For services, use the service name (e.g., “Billing API”, “Auth Service”)
• For people, use full names (e.g., “Alex Johnson”, “Sam Rivera”)
• For teams, use the team name (e.g., “Platform Engineering”, “Product Design”)

Leverage categories:

• Use categories to distinguish between different types of landmarks
• Create custom categories if the defaults don’t fit your needs
• Categories help with filtering and organization

Related

Editing Entities

Deleting Entities

Relationships