Core Schema v1.1 Best Practices Guide

Overview

This guide provides comprehensive best practices for implementing and managing the Core Schema v1.1 in Jira Service Management Assets. The Core Schema serves as the foundational master data layer for your entire CMDB ecosystem, providing shared definitions for people, organizational structures, locations, vendors, applications, and financial units that all domain-specific schemas reference.

Who should read this guide:

• CMDB Administrators responsible for schema design and maintenance
• IT Asset Managers implementing organizational data structures
• Service Desk Managers needing quick access to ownership and escalation data
• Procurement Teams managing vendor relationships
• Security Teams establishing business context for assets
• Finance Teams tracking cost allocation and budget ownership

What you will learn:

• How to effectively use each of the seven object types in the Core Schema
• The purpose and significance of every attribute
• Common implementation patterns and anti-patterns
• Troubleshooting guidance for frequent issues
• Decision frameworks for configuration choices

Prerequisites:

• JSM Premium or Enterprise license (Assets requires Premium tier minimum)
• Object Schema Manager or Jira Admin permissions
• Familiarity with basic JSM Assets concepts (object types, attributes, references)

Schema Architecture

The Single Source of Truth Principle

The Core Schema implements a fundamental CMDB design principle: master data should exist in exactly one place. Instead of each domain schema (Cloud Infrastructure, SaaS Portfolio, Cybersecurity, DevOps) maintaining its own copies of Person, Team, or Vendor records, they all reference the Core Schema.

Benefits of this approach:

• No duplicate maintenance: Update a person's job title once, and it reflects everywhere
• Cross-schema reporting: Query all assets owned by a specific team across every schema
• Referential integrity: Relationships remain consistent as data changes
• Simplified auditing: One location to verify data accuracy

Reference Types in This Schema

The Core Schema defines 14 custom reference types that describe relationships between objects. Reference types are not functionally different from one another, but they provide semantic meaning and visual organization through color-coding.

Object Type 1: Person

Purpose and Business Context

The Person object type represents all human entities relevant to your IT and business operations: employees, contractors, and external contacts. This is the most referenced object type in any CMDB because ownership, accountability, and escalation all ultimately trace back to people.

Why Person records matter:

• Incident Management: Who owns the affected application?
• Change Management: Who needs to approve this change?
• Problem Management: Who has deep knowledge of this system?
• Asset Management: Who is responsible for this equipment?
• Security: Who has access to sensitive data?

Attribute Reference

Implementation Best Practices

1. Establish a Primary Data Source

Person records should flow from your authoritative HR system (Workday, BambooHR, SAP SuccessFactors) rather than being manually created. This ensures accuracy and reduces duplicate maintenance.

Recommended data flow:
HR System -> Scheduled Import -> Assets Person Objects

2. Status Management Protocol

Never delete Person records. Instead, change Status to "Terminated" and populate the End Date. This preserves historical relationships for audit trails.

-- Find all active employees
objectType = "Person" AND Status = "Active"

-- Find contractors whose contracts are ending within 30 days
objectType = "Person" AND "Employment Type" = "Contractor" AND "End Date" < now(30d) AND Status = "Active"

3. Manager Hierarchy Validation

Ensure no circular references exist in the Reports To relationship. A person cannot report to themselves or to someone who reports to them.

Common Mistake: Importing manager data before the manager record exists. Import in two passes: first create all Person records with basic attributes, then update with Manager references.

4. Handling External Contacts

External contacts (vendor representatives, consultants) should have:

• Employment Type = "External"
• No Employee ID
• No Department assignment
• Vendor relationship documented separately

Troubleshooting

Object Type 2: Team

Purpose and Business Context

Teams are functional groups that own assets, receive tickets, and take operational responsibility. The Team object type is distinct from Department because it represents work units rather than organizational structure. A single Department might contain multiple Teams, and Teams may span Departments in matrix organizations.

Why Team records matter:

• Ticket Routing: Which group handles database incidents?
• Asset Ownership: Who is responsible for this server cluster?
• On-Call Escalation: How do we reach the team outside business hours?
• Capacity Planning: How many assets does each team manage?

Attribute Reference

Implementation Best Practices

1. Team Naming Conventions

Establish and enforce a naming standard:

• Use full words: "Platform Engineering" not "Plat Eng"
• Avoid abbreviations that require institutional knowledge
• Include functional area: "Security Operations" not just "SecOps"
• Avoid individual names: "Database Team" not "John's Team"

2. Team Lead Assignment

The Team Lead should be a Person with Status = "Active". When a Team Lead leaves:

1. Update the Team Lead to the new lead (or temporary lead)
2. Update the former lead's Status to appropriate value
3. Document the transition date in the Description field temporarily

3. Communication Channel Standards

Email: team-name@company.com (distribution list)
Slack: #team-name (public) or #team-name-internal (private)
On-Call: https://pagerduty.com/schedules/team-name

4. Inactive vs. Deleted

Never delete Team records if they have historical ticket assignments or asset ownership. Set Status to "Inactive" to:

• Preserve audit trails
• Maintain historical reporting accuracy
• Allow reference resolution in old tickets

Integration with Ticket Routing

Teams integrate with JSM's ticket routing through Assets custom fields. When a user selects an application in a service request, the Owning Team attribute can populate the assignee group.

-- Find all applications owned by a specific team
objectType = "Application" AND "Owning Team".Name = "Platform Engineering"

-- Find teams without an on-call rotation defined
objectType = "Team" AND "On-Call Rotation" is EMPTY AND Status = "Active"

Troubleshooting

Object Type 3: Department

Purpose and Business Context

Departments represent the official organizational structure as defined by HR. Unlike Teams (which are functional work units), Departments reflect reporting hierarchies, budget ownership, and corporate governance. A Department hierarchy typically mirrors your organizational chart.

Why Department records matter:

• Organizational Reporting: How is headcount distributed?
• Budget Allocation: Which units have cost responsibility?
• Access Control: Department-based permission structures
• Compliance: Regulatory reporting by business unit
• Cost Center Mapping: Financial tracking and chargebacks

Attribute Reference

Implementation Best Practices

1. Mirror HR System Exactly

Department records should match your official HR hierarchy precisely. Discrepancies cause confusion and undermine trust in CMDB data.

Recommended hierarchy example:
Technology (Parent: NULL)
  |- Engineering (Parent: Technology)
      |- Platform Engineering (Parent: Engineering)
      |- Application Development (Parent: Engineering)
  |- IT Operations (Parent: Technology)
      |- Service Desk (Parent: IT Operations)
      |- Infrastructure (Parent: IT Operations)

2. Department Code Standards

Establish a consistent code format:

• 3-4 uppercase letters
• Unique across the organization
• Stable (codes should not change when names change)

Examples:
Engineering = ENG
Human Resources = HR or HUM
Finance = FIN
Information Technology = IT

3. Cost Center Relationship

Departments should reference Cost Centers, not the reverse. This allows multiple departments to share a cost center when appropriate, and enables cost center changes without restructuring departments.

4. Handling Reorganizations

When departments reorganize:

1. Create the new department structure first
2. Update Person.Department references to new departments
3. Update Team.Department references
4. Set old departments to Status = "Inactive"
5. Never delete departments with historical references

Hierarchy Depth Considerations

Most organizations should limit department hierarchy to 4-5 levels. Deeper hierarchies create:

• Navigation complexity
• Query performance issues
• Maintenance burden

-- Find all sub-departments under Engineering
objectType = "Department" AND "Parent Department".Name = "Engineering"

-- Find departments without a Head assigned
objectType = "Department" AND Head is EMPTY AND Status = "Active"

-- Find departments without Cost Center assignment
objectType = "Department" AND "Cost Center" is EMPTY AND Status = "Active"

Troubleshooting

Object Type 4: Location

Purpose and Business Context

Locations represent physical places where people work and assets reside. A well-structured Location hierarchy enables geographic reporting, timezone-aware automation, compliance management, and physical asset tracking.

Why Location records matter:

• Asset Placement: Where is this server physically located?
• Employee Assignment: Which office does this person work from?
• Timezone Management: When can we schedule maintenance?
• Regional Compliance: What regulations apply to assets here?
• Facility Planning: How is capacity distributed?
• Disaster Recovery: Which locations are affected by an outage?

Attribute Reference

Location Type Values

Implementation Best Practices

1. Hierarchy Design

Structure locations to support your physical hierarchy and reporting needs:

Headquarters (Type: Headquarters)
  |- Building A (Type: Office, Parent: Headquarters)
      |- Floor 1 (Type: Office, Parent: Building A)
          |- Server Room 1A (Type: Data Center, Parent: Floor 1)
      |- Floor 2 (Type: Office, Parent: Building A)

2. Handling Remote Workers

Create logical "Remote" locations for geographic regions rather than individual home addresses:

• "Remote - Americas"
• "Remote - EMEA"
• "Remote - APAC"

This enables:

• Timezone-based grouping
• Regional compliance tracking
• Headcount reporting by region

3. Timezone Standards

Always use IANA timezone identifiers, not abbreviations:

• Correct: America/New_York, Europe/London, Asia/Tokyo
• Incorrect: EST, GMT, JST (these are ambiguous and don't handle daylight saving)

4. Data Center Locations

For cloud providers, create Location records for each region you use:

• "AWS us-east-1 (N. Virginia)"
• "Azure West Europe (Netherlands)"
• "GCP europe-west1 (Belgium)"

This enables:

• Regional infrastructure reporting
• Data residency compliance
• Disaster recovery planning

AQL Query Examples

-- Find all active offices in EMEA
objectType = "Location" AND Type = "Office" AND Region = "EMEA" AND Status = "Active"

-- Find all data centers
objectType = "Location" AND Type = "Data Center" AND Status = "Active"

-- Find locations without timezone defined
objectType = "Location" AND Timezone is EMPTY AND Status = "Active" AND Type != "Remote"

-- Find all child locations of a specific building
objectType = "Location" AND "Parent Location".Name = "Stockholm Office"

Troubleshooting

Object Type 5: Vendor

Purpose and Business Context

Vendors represent external organizations you purchase from, contract with, or partner with. Comprehensive vendor records enable procurement efficiency, risk management, support escalation, and contract compliance tracking.

Why Vendor records matter:

• Procurement: Who supplies this equipment?
• Support Escalation: How do we contact vendor support?
• Risk Management: What is our exposure to this vendor?
• Contract Management: When does this agreement renew?
• Compliance: Does this vendor meet our security requirements?
• Spend Analysis: How much do we pay this vendor across all products?

Attribute Reference

Vendor Type Values

Implementation Best Practices

1. Relationship Owner Assignment

Every active vendor should have an internal Relationship Owner who:

• Receives vendor communications
• Approves purchase requests
• Manages contract renewals
• Escalates support issues

-- Find vendors without a relationship owner
objectType = "Vendor" AND "Relationship Owner" is EMPTY AND Status = "Active"

2. Risk Level Assessment

Assess vendors based on:

• Critical: Single point of failure, no alternatives
• High: Significant business impact if unavailable
• Medium: Moderate impact, alternatives exist
• Low: Minimal impact, easily replaceable

Factors to consider:

• Data access (do they hold customer data?)
• System integration depth
• Revenue dependency
• Replacement difficulty

3. Review Cadence

Establish vendor review schedules based on risk:

• Critical: Quarterly reviews
• High: Semi-annual reviews
• Medium/Low: Annual reviews

-- Find critical vendors not reviewed in 90 days
objectType = "Vendor" AND "Risk Level" = "Critical" AND "Last Review Date" < now(-90d)

-- Find all vendors due for annual review
objectType = "Vendor" AND "Last Review Date" < now(-365d) AND Status = "Active"

4. Support Contact Standards

Maintain complete support information to enable efficient escalation:

• Support Email: Primary channel for non-urgent issues
• Support Phone: For urgent/outage situations
• Support Portal: For ticket tracking and documentation
• Account Number: Required for vendor authentication

Troubleshooting

Object Type 6: Application

Purpose and Business Context

Applications represent software used by the organization, from SaaS platforms to custom-built systems. The Application object type is the bridge between business operations and technical infrastructure, capturing ownership, dependencies, and compliance attributes.

Why Application records matter:

• Service Desk: Which team supports this application?
• Change Management: What depends on this application?
• Security: What data classification does this application handle?
• Licensing: Are we compliant with license terms?
• Business Continuity: How critical is this application?
• Access Management: Does this application use SSO/MFA?

Attribute Reference

Application Type Values

Implementation Best Practices

1. Criticality Assessment Framework

Use consistent criteria for Criticality assignment:

2. Dual Ownership Model

Applications should have both:

• Business Owner: Responsible for requirements, budget, business value
• Technical Owner: Responsible for architecture, operations, security

This separation ensures both business needs and technical health are addressed.

3. Dependency Mapping

Document dependencies to enable change impact analysis. Focus on runtime dependencies, not build dependencies:

Example dependency chain:
Customer Portal
  |- Depends On: Payment Gateway
  |- Depends On: Customer Database
  |- Depends On: Identity Provider

-- Find all applications that depend on a specific application
objectType = "Application" AND Dependencies.Name = "Identity Provider"

-- Find applications without any team ownership
objectType = "Application" AND "Owning Team" is EMPTY AND Status = "Active"

-- Find critical applications without SSO
objectType = "Application" AND Criticality = "Critical" AND "SSO Enabled" != true AND Status = "Active"

4. Data Classification Guidelines

5. Security Posture Tracking

SSO Enabled and MFA Required attributes support security compliance:

• All Confidential/Restricted applications should have SSO Enabled = true
• All Confidential/Restricted applications should have MFA Required = true

-- Security audit: Find confidential apps without MFA
objectType = "Application" AND "Data Classification" in ("Confidential", "Restricted") AND "MFA Required" != true AND Status = "Active"

Troubleshooting

Object Type 7: Cost Center

Purpose and Business Context

Cost Centers are financial units used for budget tracking, cost allocation, and chargeback processes. The Cost Center object type was added in v1.1 to prevent data inconsistency from freetext input in Department records and to enable proper financial governance.

Why Cost Center records matter:

• Budget Tracking: Which unit is responsible for this expense?
• Chargeback: How do we allocate IT costs to business units?
• Financial Reporting: What is the total spend by cost center?
• Governance: Who approves expenses for this budget?
• Forecasting: What are the spending trends by cost center?

Attribute Reference

Status Values Explained

Implementation Best Practices

1. Code Standardization

Cost Center Codes must match your financial system exactly. Work with Finance to establish the code format:

Examples:
CC-001, CC-002, CC-003  (Sequential)
IT-100, IT-200, MKT-100  (Department prefix)
1000-100, 1000-200  (Numeric hierarchy)

2. Owner Assignment

Every active Cost Center should have an Owner who:

• Approves purchase requisitions
• Reviews monthly cost reports
• Authorizes budget transfers
• Escalates budget issues

-- Find cost centers without an owner
objectType = "Cost Center" AND Owner is EMPTY AND Status = "Active"

3. Department Linkage

Departments reference Cost Centers through the "Funded By" relationship. This is a many-to-one relationship: multiple departments can share one cost center.

Common patterns:
1:1 - Each department has its own cost center
N:1 - Multiple departments share a cost center (shared services)
1:N - One department splits across cost centers (rare, consider restructuring)

4. Financial System Integration

Cost Center records should be synchronized with your ERP or financial system:

• Import from finance system as source of truth
• Never create Cost Centers manually without finance approval
• Validate Codes against finance system during import

-- Find departments without cost center assignment
objectType = "Department" AND "Cost Center" is EMPTY AND Status = "Active"

-- Find all departments funded by a specific cost center
objectType = "Department" AND "Cost Center".Code = "IT-100"

5. Handling Budget Freezes

When a cost center exceeds budget or requires review:

1. Set Status to "Frozen"
2. Document reason in Description
3. Notify Owner
4. Finance reviews and either:
   • Returns to Active with adjusted budget
   • Leaves Frozen pending resolution
   • Sets to Inactive if closing

Troubleshooting

Cross-Object Best Practices

Data Import Strategy

JSM Assets supports CSV and JSON imports for bulk data population. Follow this sequence for initial data load:

Import Order (Critical):

1. Cost Centers - No dependencies
2. Locations - No dependencies (import top-level first, then children)
3. Departments - Depends on: Cost Centers (import top-level first, then children)
4. Persons - Depends on: Departments, Locations
5. Vendors - Depends on: Persons (for Relationship Owner)
6. Teams - Depends on: Persons (for Team Lead), Departments
7. Applications - Depends on: Vendors, Persons, Teams

Sandbox Testing

Always test bulk imports in your JSM Sandbox before production:

1. Export current production data
2. Import to sandbox
3. Validate object counts
4. Verify reference resolution
5. Test AQL queries
6. Confirm automation triggers

Naming Conventions

Establish organization-wide naming conventions:

AQL for Cross-Schema Queries

Leverage AQL dot notation to traverse references:

-- Find all active employees in Engineering department
objectType = "Person" AND Department.Name = "Engineering" AND Status = "Active"

-- Find applications owned by teams in a specific department
objectType = "Application" AND "Owning Team".Department.Name = "Engineering"

-- Find all critical applications provided by a high-risk vendor
objectType = "Application" AND Criticality = "Critical" AND Vendor."Risk Level" = "High"

-- Find persons who manage a cost center but are not active
objectType = "Cost Center" AND Owner.Status != "Active" AND Status = "Active"

Troubleshooting Guide

Reference Resolution Issues

Symptom: Reference fields show "Unknown" or are empty after import.

Causes and Solutions:

1. Object doesn't exist: Import referenced objects first (see Import Order above)
2. Label mismatch: Ensure you import using the Label attribute value, not Name or Key
3. Case sensitivity: AQL is case-insensitive, but import matching may be case-sensitive
4. Special characters: Escape quotes in values: 15\" Screen

Performance Issues

Symptom: AQL queries are slow or timing out.

Solutions:

1. Add filters to reduce result set: AND Status = "Active"
2. Avoid deep dot notation chains (3+ levels)
3. Use object type filters: objectType = "Person" before other conditions
4. Order results only when necessary

Circular Reference Detection

Symptom: "Circular reference detected" error.

Causes:

• Department A has Parent = Department B, and Department B has Parent = Department A
• Person reports to someone who reports to them
• Location hierarchy loops back

Solution: Map the hierarchy on paper first, then correct the errant reference.

Data Quality Degradation

Symptom: Reports show unexpected results; data is stale.

Prevention:

1. Implement scheduled imports from authoritative sources
2. Establish ownership for each object type (see Governance Playbook)
3. Create automated health check queries (see Dashboards documentation)
4. Set review cadences for manual-entry objects

FAQ

Q1: Should I create separate schemas or use one Core schema for everything?

Answer: The Core Schema is intentionally minimal, containing only master data that multiple domain schemas reference. Domain-specific objects (servers, laptops, licenses, network devices) belong in their respective domain schemas (Cloud Infrastructure, Hardware Assets, SaaS Portfolio) that reference Core objects. This separation provides:

• Clear ownership boundaries
• Easier permission management
• Focused reporting
• Simpler maintenance

Q2: How do I handle contractors who work for multiple departments?

Answer: The Person object has a single Department reference representing primary department. For contractors with multi-department assignments:

1. Assign their primary department (where they spend most time)
2. Document additional departments in the Description field or a custom attribute
3. Use Team membership to track functional group assignments across departments

Q3: What happens if I delete a Person who owns Applications?

Answer: You should never delete Person records. Instead:

1. Set Status to "Terminated"
2. Set End Date to their departure date
3. Before termination, transfer ownership references to new owners
4. Run AQL queries to find orphaned ownership:

   objectType = "Application" AND "Business Owner".Status = "Terminated"

Q4: How do I model matrix organizations where teams report to multiple departments?

Answer: The Team object has a single Department reference. For matrix organizations:

1. Assign the primary (budget-holding) department
2. Document secondary reporting in the Description field
3. Consider creating a custom "Secondary Department" attribute if this is common
4. Use the "Used By Teams" relationship on Applications to show cross-department collaboration

Q5: How often should vendor records be reviewed?

Answer: Review frequency should align with risk level:

• Critical vendors: Quarterly (every 90 days)
• High-risk vendors: Semi-annually (every 180 days)
• Medium-risk vendors: Annually
• Low-risk vendors: Every 2 years or at contract renewal

Use the Last Review Date attribute and automated reports to track review compliance.

Q6: Can I have locations without physical addresses?

Answer: Yes. Use the "Remote" location type for:

• Remote worker groupings by region ("Remote - EMEA")
• Cloud regions ("AWS us-east-1")
• Virtual environments

Leave Address, City, and Country empty for these locations, but always set Timezone for cloud regions.

Q7: How do I model application dependencies correctly?

Answer: The Dependencies attribute captures runtime dependencies - applications that must be available for this application to function. Best practices:

• Focus on direct dependencies, not transitive (if A depends on B and B depends on C, A's Dependencies should only list B)
• Include infrastructure services: identity providers, databases, message queues
• Exclude build-time or development dependencies
• Review dependencies after any major architecture change

Related Resources

This guide is part of the Core Schema v1.1 documentation suite:

• Governance Playbook: Enterprise governance framework including roles, review cadences, data quality metrics, and escalation procedures
• JSM Forms Specification: Detailed form configurations for each object type, including field validation, conditional logic, and workflow integration
• Automation Examples: Automation rule patterns for lifecycle management, notifications, and data maintenance

For platform documentation:

• Atlassian Assets Documentation
• AQL Syntax Reference
• Assets Automation Guide

Version History

This documentation was created by Schema Forge Team for Schema-Forge. For questions or feedback, contact the Schema-Forge team.