Back to Core Schema

JSM Forms Specification

Complete Jira Service Management portal forms for creating and updating objects in the Core Schema. These forms serve as the primary interface between end-users and your Configuration Management Database, enabling self-service data management while maintaining data quality and governance controls.

📖 For Core Schema v1.1 📝 16 comprehensive forms ☁️ JSM Cloud with Assets

Overview

Audience: CMDB Administrators, Service Desk Managers, JSM Project Administrators, IT Governance Teams

Prerequisites:

  • Core Schema v1.1 deployed via Schema-Forge
  • JSM Cloud with Assets enabled
  • Understanding of JSM request types and workflows
  • Access to JSM project settings for form configuration

Form Architecture

Portal Structure

Organize your forms into logical portal groups to improve discoverability:

Portal Group Forms Description
People & Organization Person, Team, Department, Cost Center Organizational master data
Locations Location Physical site management
Vendors & Applications Vendor, Application External relationships and software
Employee Lifecycle Onboarding, Offboarding Composite workflow forms

Form Naming Convention

Adopt a consistent naming pattern for request types:

  • Create forms: New [Object Type] (e.g., "New Person", "New Application")
  • Update forms: Update [Object Type] (e.g., "Update Vendor", "Update Location")
  • Lifecycle forms: [Process Name] (e.g., "Employee Onboarding", "Vendor Review")

Object Creation Forms

Form 1: New Person

Purpose: Register employees, contractors, and external contacts in the CMDB. This form captures essential identity and organizational placement information.

Portal Placement: People & Organization

Request Type Settings:

  • Issue Type: Task
  • Priority: Medium (default)
  • Approvers: HR Manager (for employees), Hiring Manager (for contractors)

Field Specification

Field Type Required Help Text Validation
Full Name Text Yes Enter first and last name as it appears in HR systems Min 2 characters, max 100
Email Address Email Yes Corporate email address (must match domain policy) Valid email format, must match @company.com or approved domains
Employee ID Text No Internal employee number (leave blank for contractors/external) Alphanumeric, max 20 characters
Job Title Text No Official job title from HR Max 100 characters
Department Assets Object Picker No Select the primary department this person belongs to Filter: objectType = Department AND Status = Active
Manager Assets Object Picker No Direct reporting manager Filter: objectType = Person AND Status = Active
Location Assets Object Picker No Primary work location Filter: objectType = Location AND Status = Active
Employment Type Select No Options: Employee, Contractor, External -
Status Select Yes Default: Active. Options: Active, On Leave Terminated only via offboarding form
Start Date Date No Employment or contract start date Cannot be more than 30 days in the past
Phone Text No Format: +1-555-555-1234 (international format preferred) Pattern: ^\+?[\d\s\-\(\)]+$

Conditional Logic

  • When Employment Type = "Contractor": Show "End Date" field (required for contract end tracking)
  • When Employment Type = "External": Hide "Employee ID" field and "Manager" field (external contacts don't have internal managers)

Workflow Steps

  1. Submitted - Request received
  2. HR Review - HR validates employment data (Approver: HR Manager)
  3. Manager Approval - Manager confirms organizational placement
  4. In Progress - CMDB Admin creates object
  5. Completed - Object created, requestor notified

Form 2: New Team

Purpose: Register functional teams that own assets and receive tickets. Teams are distinct from Departments (organizational structure).

Portal Placement: People & Organization

Field Specification

Field Type Required Help Text
Team Name Text Yes Official team name (avoid abbreviations)
Description Textarea No Describe the team's purpose, responsibilities, and scope
Team Lead Assets Object Picker No Person who leads this team
Department Assets Object Picker No Parent department for organizational alignment
Team Email Email No Distribution list or shared mailbox
Slack Channel Text No Primary communication channel (e.g., #platform-team)
On-Call Rotation URL No Link to PagerDuty, Opsgenie, or similar rotation page
Status Select Yes Default: Active. Options: Active, Inactive

Form 3: New Department

Purpose: Register organizational structure units aligned with HR's view of the company hierarchy.

Priority: High (organizational changes require visibility)

Form 4: New Cost Center

Purpose: Register financial units for budget tracking and allocation. Cost Centers are referenced by Departments for financial governance.

Form 5: New Location

Purpose: Register physical places where people work and assets reside. Supports hierarchical location modeling (Building > Floor > Room).

Form 6: New Vendor

Purpose: Register external organizations for procurement, support, and relationship management.

Form 7: New Application

Purpose: Register software applications in the master registry. Applications link to Vendors, Owners, and Teams.

Object Update Forms

Update forms mirror creation forms but with pre-populated values and change-tracking workflows. JSM supports editing Assets object attributes through automation actions.

Update Form Design Principles

  1. Pre-populate all fields with current object values using Assets Object field lookups
  2. Highlight changes using automation to compare old vs. new values
  3. Require change reason for audit trail (mandatory textarea)
  4. Route approvals based on what changed (e.g., Status changes require manager approval)

Forms 8-14 cover updates for each object type (Person, Team, Department, Cost Center, Location, Vendor, Application).

Employee Lifecycle Forms

Form 15: Employee Onboarding

Purpose: Composite form that creates a Person record and triggers downstream provisioning across Teams, Applications, and Locations.

SLA: 3 business days before start date

Workflow Steps

  1. Submitted - Hiring Manager submits onboarding request
  2. HR Review - HR validates employment data, creates Person object
  3. IT Provisioning - IT provisions equipment and accounts (creates sub-tasks)
  4. Manager Setup - Manager confirms team assignment and first-week schedule
  5. Ready - All provisioning complete, welcome package sent
  6. Completed - New hire's first day confirmed

Form 16: Employee Offboarding

Purpose: Composite form that transitions a Person record and triggers deprovisioning. Handles equipment return, access revocation, and knowledge transfer.

SLA: Complete by last day of employment

Form Design Best Practices

Field Organization

Group related fields into logical sections:

  1. Identity Section - Name, Email, ID fields
  2. Organizational Context - Department, Team, Manager
  3. Classification - Type, Status, Criticality
  4. Contact Information - Phone, Slack, URLs
  5. Metadata - Dates, Review information

Help Text Guidelines

Write help text that:

  • Explains why the field matters, not just what to enter
  • Provides examples of valid input
  • States consequences of incorrect data
  • References where to find the information if not obvious
Example: "Employee ID: Enter the 6-digit ID from your HR profile. This links your CMDB record to payroll and access systems. Leave blank for contractors."

Validation Strategy

Layer validations for data quality:

  1. Format validation - Regex patterns for emails, phone numbers, codes
  2. Uniqueness validation - AQL queries to check for duplicates
  3. Referential validation - Ensure selected objects exist and are active
  4. Business rule validation - Automation rules for complex logic

Troubleshooting

Common Issues and Resolutions

Issue: Assets Object Picker shows no results

Resolution: Verify the AQL filter is correct. Common problems include:

  • Object type name mismatch (case-sensitive)
  • Status filter excluding all objects
  • Schema permissions not granting access to the request type

Issue: Conditional sections not showing/hiding

Resolution: JSM conditional logic requires:

  • Trigger field must be radio, checkbox, or single-select (not multi-select)
  • Conditional section must be below the trigger field
  • Only single-condition triggers are supported natively

Issue: Automation not updating Assets object attributes

Resolution: Check that:

  • The rule uses "Edit Assets field attributes" action (not "Edit issue")
  • The Assets field is correctly mapped
  • The object is the focus of the rule (for global automations)
  • No more than 50 objects are being updated in a single run

Frequently Asked Questions

Q1: Can I create an Assets object directly from a form submission?

A: Not directly. JSM forms submit data to Jira issues, not to Assets. Use automation rules triggered by issue creation to create or update Assets objects. The typical pattern is: Form submission creates issue > Automation reads form/custom fields > Automation creates Assets object or updates attributes.

Q2: How do I filter Assets object pickers based on another field's selection?

A: Cascading/dependent Assets fields are supported in JSM Data Center through custom field configuration. In Cloud, this requires automation workarounds: populate a hidden field on first selection, then use that to filter the second picker.

Q3: Can I require manager approval based on the selected Manager in the form?

A: Yes, but it requires a two-step approach. First, link the form's Manager field to a Jira custom field. Then, use automation to set the Approver field based on that custom field value.

Q4: How many forms should I create for each object type?

A: At minimum, create one "New [Object]" form and one "Update [Object]" form per object type. For high-volume objects like Person and Application, consider creating specialized forms: "New Employee" vs. "New Contractor" vs. "New External Contact".

Q5: What happens if an approval chain breaks (approver leaves company)?

A: Implement these safeguards:

  1. Always configure fallback approvers (e.g., "Manager's Manager" or "Department Head")
  2. Use automation to detect stale approvals and reassign
  3. Run weekly reports on pending approvals older than 5 days

Related Resources

Previous Document
← Best Practices Guide
Next Document
Governance Playbook →