> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msportal.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# How to Create a Ticket Template
> Learn how to create, customize, and manage ticket templates with company branches and import/export
Ticket templates streamline repetitive ticket creation by providing pre-configured forms with custom fields. This guide covers creating templates using AI assistance or manual configuration, managing company-specific branches, and importing/exporting templates.
## Prerequisites
* You must have "Manage Tickets" permission
* PSA integration should be configured if using external ticketing systems
* Categories should be set up in Ticket Settings
## Creating a New Template
Go to **Tickets** in the sidebar, click the menu button, and select **Templates**.
Click the **New Template** button in the top-right corner.
Fill in the basic information:
* **Template Name**: A descriptive name (e.g., "New Employee Setup")
* **Category**: Select from available categories
* **Description**: Brief explanation of when to use this template
* **Active Status**: Toggle whether the template is available for use
## Template Configuration Sections
The template editor is organized into expandable accordion sections:
### Template Details
Configure the basic template information:
| Field | Description |
| ----------------- | --------------------------------------------------------- |
| **Template Name** | Display name shown when selecting the template |
| **Category** | Group templates by type (Incident, Service Request, etc.) |
| **Description** | Help text explaining when to use this template |
| **Active Status** | Whether the template is available for users |
### PSA Integration Settings
Configure default PSA values for tickets created from this template:
* **Service Board**: Select the board for tickets
* **Default Priority**: Set initial priority level
* **Default Status**: Set initial status
* **Ticket Type**: Select type classification
* **Ticket Subtype**: Select subtype (if applicable)
* **Queue**: Select the ticket queue
* **Default Priority**: Set initial priority level
* **Default Status**: Set initial status
* **Ticket Type**: Select type classification
* **Ticket Category**: Select category
* **Team/Queue**: Select the team or queue
* **Default Priority**: Set initial priority level
* **Default Status**: Set initial status
* **Halo Category**: Select Halo-specific category
* **Halo Impact**: Set impact level
* **Halo Urgency**: Set urgency level
PSA settings are only available after configuring your PSA integration in Settings.
### Company Visibility
Control which companies can see and use this template:
**Default Visibility Setting:**
At the top of the visibility section, configure the default behavior for new companies:
* **Enabled (default)**: New companies automatically have access to this template
* **Disabled**: New companies must be manually enabled
**Per-Company Controls:**
Each company can be individually toggled on or off:
* Search for companies using the search box
* Toggle the switch to enable or disable access
* Companies with branches are highlighted with a branch indicator
**Bulk Actions:**
| Action | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| **Enable All** | Grant access to all companies |
| **Disable All** | Revoke access from all companies |
| **Enable All Except Branched** | Enable for all companies that don't have a custom branch (recommended when using branches) |
When using company branches, click **Enable All Except Branched** to ensure companies with custom branches use their branch while all other companies use the parent template.
Companies with branches are shown with an orange branch badge. These companies will use their branch version regardless of whether the parent template is enabled for them.
### Company Gating (Types and Industries)
For more flexible access control than per-company toggles, restrict a template to companies that match specific **types** or **industries**. Gating is checked everywhere a template is offered: the new ticket page, the AI ticket assistant, and the browser extension.
From the template editor, click **Manage Gating** in the Company Visibility section.
Under the **Types** header, select one or more company types this template should be available for. The picker lists every type in your tenant, both manual and PSA-synced. Leave it empty if you don't want to gate by type.
Under the **Industries** header, select one or more company industries. The picker lists every distinct industry in use across your tenant (sourced from manual edits or PSA syncs).
Click **Save**. The template now appears only for companies that match the gating rules.
**How Type and Industry Gating Combine:**
* Types and industries are ANDed together. A template gated to type "Managed Services" AND industry "Healthcare" only shows for companies that are both
* Within a single axis, the values are ORed. Picking three types means the template shows for any company in any of the three
* Industry comparisons are case-insensitive, so PSA capitalization differences ("healthcare" vs "Healthcare") do not matter
* A template with no gating rules behaves as before: visible to every company unless toggled off in per-company controls
Use **types** for service-tier gating ("Managed Services Client" only) and **industries** for compliance gating ("Healthcare" or "Financial Services" only). The two axes compose well: type gating handles your service contracts, industry gating handles regulatory variations.
Gating is enforced everywhere the template is offered. If you remove a company from a gated type or change its industry, the template stops appearing for that company on the next page load. Existing tickets created from the template are not affected.
### Company Branches
Create company-specific versions of a template with customized fields and settings.
Company branches allow you to customize a template for specific companies while keeping the parent template as the default for all other companies. Branches inherit the parent template structure but can have different fields, labels, help text, and PSA routing.
**When to Use Branches:**
* A client needs additional custom fields not relevant to other companies
* A client requires different PSA routing (different board, queue, or priority)
* A client wants simplified fields with some sections hidden
* A client needs different field labels or terminology
**Creating a Branch:**
Click the **Company Branches** accordion section in the template editor.
Click the **Create Branch** button in the top-right of the section.
Use the search box to find the company, then click to select it. Companies that already have branches are not shown.
Click **Create & Edit** to create a full copy of the template and open it for editing.
**Editing a Branch:**
When editing a branch, you can:
* Add, remove, or modify fields and sections
* Change field labels, help text, and default values
* Configure different PSA routing settings
* Give the branch a custom name (optional)
The branch is a complete, independent copy of the parent template. Changes to the parent template do not affect existing branches.
**Managing Branches:**
| Action | Description |
| ----------------- | ------------------------------------------------------------------------------ |
| **Edit Branch** | Click the external link icon to open the branch in the template editor |
| **Delete Branch** | Click the trash icon, then confirm. The company reverts to the parent template |
| **View Status** | Inactive branches are labeled with a badge |
**Viewing Branches from the Template List:**
In the Templates table, templates with branches show an expandable row. Click the chevron to see all company branches for that template, including:
* Branch name and company name
* Number of companies with visibility enabled/disabled
* Quick actions to edit or delete each branch
Deleting a branch is permanent and cannot be undone. The company will immediately revert to using the parent template.
### Import / Export
Export templates for backup or sharing, or import templates from JSON/CSV files. Access the Import/Export dialog from the accordion section in the template editor or from the row actions menu in the templates list.
**Export Options:**
Complete template backup including all sections, fields, rules, PSA defaults, and optionally company branches.
**Includes:**
* Template name, key, description, category
* All sections and fields with their configuration
* Conditional rules and validation settings
* PSA default values (board, priority, status, type)
* Company branches (optional)
**Use Cases:**
* Backup before making major changes
* Share templates between tenants
* Version control for template configurations
Spreadsheet format for bulk editing field properties.
**Includes:**
* Section and field identifiers
* Field labels, help text, placeholders
* Default values and options
* Field ordering
**Use Cases:**
* Bulk editing field labels in Excel or Google Sheets
* Reviewing all fields in a flat format
* Translating templates to different languages
**Import Options:**
Create new templates or replace existing ones from a JSON file.
**Import Modes:**
* **Replace existing**: Overwrites all content of an existing template with the same key
* **Create new**: Creates a new template (fails if the key already exists)
**Options:**
* **Generate New Key**: Adds a timestamp suffix to avoid key conflicts
* **Include Branches**: Import company branches (requires matching company names in your tenant)
**Diff Preview:**
When importing to an existing template, a preview shows:
* Added sections and fields (green)
* Modified sections and fields (yellow)
* Removed sections and fields (red)
Review the diff before confirming to understand exactly what will change.
Update existing field properties from a CSV file.
**Requirements:**
* Template must already exist (CSV cannot create templates)
* CSV must include the template key column for validation
**Updates:**
* Field labels and help text
* Placeholder text
* Default values
* Dropdown/multi-select options
**Preserves:**
* Template structure (sections and field types)
* Conditional rules
* PSA mappings
Export templates to JSON before making major changes. You can always import the backup to restore the previous version.
## Sections & Fields
### Adding Sections
Click **Add Section** to create logical groupings of fields:
* Employee Information
* Hardware Requirements
* Software Requirements
* Access Requirements
### Adding Fields
Within each section, click **Add Field** to create a new field.
**Available Field Types:**
| Type | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Short Text** | Single-line text input |
| **Long Text** | Multi-line text area |
| **Dropdown** | Single selection from options |
| **Multi-select** | Multiple selections from options |
| **Date** | Date picker |
| **Number** | Numeric input |
| **Checkbox** | Yes/No toggle |
| **User Select** | Choose from users list |
| **File Upload** | File attachment |
| **Embedded Template** | Pull another template's questions inline as a sub-card. Each embedded template fires its own separate ticket on submit. See [Embedded Templates](#embedded-templates) below. |
**Field Properties:**
| Property | Description |
| ----------------- | ------------------------------------ |
| **Label** | Display name for the field |
| **Key** | Internal identifier (auto-generated) |
| **Help Text** | Guidance shown below the field |
| **Required** | Never, Always, or Conditional |
| **Default Value** | Pre-filled value |
| **Options** | Choices for dropdown/multi-select |
### Conditional Fields
Make fields appear based on other field values:
Change the field's Required setting to "Conditional".
Choose which field triggers this field's visibility.
Define what value makes this field appear.
### Reordering
* **Drag sections** to reorder their position
* **Drag fields** within sections to reorder
* Click **Collapse All** to minimize sections while organizing
## Embedded Templates
The **Embedded Template** field type lets one template pull in another template's questions inline, gated by the parent field's conditional logic. Each embedded template fires its own separate ticket on submit using its own PSA routing.
Use embedded templates when a single user request can spawn multiple PSA tickets that need different routing. Classic example: a "New Hire" parent template asks "Will this person need a new computer?" and "Will this person need software access?" — each "Yes" reveals an embedded template (New Computer Request, Software Access Request) and each lands a separate ticket on its own service board with its own approver workflow.
### How Embedded Templates Behave
| Behavior | Detail |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Visibility** | The parent field's conditional logic gates the embed. If the parent field isn't visible, the embed doesn't render and no child ticket fires. |
| **One ticket per embed** | Every visible embedded template field creates exactly one separate PSA ticket. Two embed fields pointing at the same target template create two tickets. |
| **PSA routing** | Each embed uses the **embedded template's** own service board, priority, status, ticket type, ticket subtype, and category — not the parent's. |
| **Same PSA integration** | Both parent and embed land in the tenant's currently selected PSA integration. There is one selected PSA per tenant. |
| **Attachments** | File uploads, screenshots, and attachment fields placed inside an embedded template are uploaded to that embed's PSA ticket, not the parent's. |
| **Company gating inheritance** | Embedded templates do **not** need to be enabled for every company the parent applies to. The parent's gating rules already govern visibility; the embed is treated as part of the parent flow. |
| **Parent ticket reference** | Every child ticket prepends "Related to ticket #N in template Foo" to its description so support staff can trace the relationship in the PSA. |
| **Parent ticket summary note** | After the embed loop runs, MSPortal posts an internal note on the parent PSA ticket listing every related ticket number, fallback-emailed embed, and any failures. |
### Adding an Embedded Template Field
Click **Add Field** in the section that should host the embed, then click the field row to expand the editor.
Open the **Type** dropdown and select **Embedded Template**.
A teal **Embedded template** picker appears below the field's Help Text. Choose the template you want to embed. The picker lists every other active template in your tenant. Templates that already contain their own embedded templates are disabled in the picker (depth-1 cap, see below).
Set **Required** to **Conditional** so the embed only renders when a specific parent field has the right value. For example: parent field "Need a new computer?" equals "Yes". Without a conditional, the embed always renders and always fires a child ticket.
Click **Save Template**. MSPortal validates the embed reference before saving and surfaces clean inline errors if anything is wrong (missing target, cross-tenant reference, depth-1 violation).
### The Depth-1 Cap
An embedded template **cannot** itself contain embedded templates. This is enforced at three layers so it cannot be bypassed:
* The picker disables any candidate template that already has an embed reference, with a `(contains embeds)` label so admins know why
* The save flow blocks the upsert with a clear inline error if the picker is bypassed
* The runtime renderer drops nested embeds defensively, surfacing a soft-warning card so the issue is visible
If you need a deeper hierarchy, model it with conditional fields inside the embedded template instead of trying to nest a third level. Conditional fields support arbitrary depth and don't change the ticket count.
### Embedded Templates and PSA Routing
Each embedded template is a normal ticket template, so all of its PSA settings apply when the embed fires:
* **Service board / queue** — the embed's `default_board` is used. If the parent goes to "Service Desk" and the embed's default board is "Procurement", the parent ticket lands on Service Desk and the embed lands on Procurement.
* **Priority and status** — the embed's `default_priority` and `default_status` are used.
* **Ticket type / subtype / category** — the embed's defaults are used.
* **Halo Category / Impact / Urgency** — the embed's Halo-specific routing is used.
* **Use client's PSA defaults toggle** — if the embed has this toggle on, the embed reads board/priority/status from the client's company-level defaults instead of the embed's own template defaults.
* **Per-company branches on the embed** — if the embed has a branch for the parent's company, the branch's overrides apply.
**ConnectWise specifically:** the embed's default status must be active on the embed's default board. If they don't match, the embed throws a clear error like "Template status X is not active on the selected ConnectWise board" and the child ticket fails. The parent ticket still succeeds. Verify each embed's board+status combination in the editor's PSA Integration Settings.
### Attachments Inside Embeds
File Upload, Screenshot, and Attachment fields placed inside an embedded template attach their files to the **embed's** PSA ticket — not the parent's. This lets you capture supporting documents per child request:
* Parent: "New Hire" template — no attachments
* Embed 1: "New Computer Request" — attach the approved hardware quote
* Embed 2: "Software Access Request" — attach the user's training certificate
Each PSA ticket receives only the attachments uploaded to its corresponding form section.
### Form Preview Renders Embeds
The Form Preview pane (right-side preview button in the template editor) renders embedded templates inline as teal-bordered sub-cards. The preview runs the embed's own conditional engine against the values you fill in, so you can verify show/hide behavior before saving.
If the embed reference can't be resolved (deleted target, depth-1 cap drop, cross-tenant), the preview shows a clear warning instead of silently rendering nothing.
### What Happens on Submit
When a user submits a parent ticket form:
1. The parent ticket is validated and created in the PSA first.
2. For each embedded template whose parent field's conditional is satisfied, MSPortal fires a separate `submitTicketFromTemplate` call using the embed's templateId.
3. Each child ticket is created with its own routing, attachments, and "Related to ticket #N" prefix on the description.
4. After the embed loop completes, MSPortal posts a single internal note on the parent ticket summarizing each child:
* Successes with their PSA ticket numbers
* Embeds that fell back to email (when the PSA call failed)
* Embeds that failed to create (with the error so support can manually retry)
5. The submitter sees a toast indicating how many related tickets were created, fell back, or failed.
If only some embeds succeed, the parent ticket is still created and tracked. Use the parent's summary note to find which embeds need manual follow-up.
### Validation Errors When Saving
When you save a template with embedded fields, MSPortal validates each embed reference and shows clean inline errors next to the offending field if anything is wrong:
| Reason | What it means | Fix |
| --------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Missing target** | The referenced template no longer exists or was deleted | Pick a different template |
| **Self-reference** | The field tries to embed the template into itself | Pick a different template |
| **Depth-1 violation** | The referenced template itself contains embedded templates | Pick a non-embedding template, or restructure the deeper template |
| **Cross-tenant** | The referenced template is in a different tenant (rare; usually only seen during template imports) | Pick a template from your own tenant |
The error appears as a red banner inside the embed picker card and clears optimistically as soon as you pick a different template.
## Using AI to Generate Templates
Click the floating purple **AI** button on the right side of the screen.
Type a description of what the template should do, e.g., "Create a template for new employee onboarding that captures hardware needs, software requirements, and access permissions."
The AI will create sections and fields based on your description.
Modify, add, or remove fields to match your exact requirements.
The AI designer works iteratively. You can request changes like "Add a section for emergency contacts" and it will modify the existing template.
## Saving and Activating
1. Review all sections and fields
2. Ensure PSA settings are configured if using integrations
3. Click **Save Template**
4. Enable the **Active** toggle to make the template available
## Best Practices
Name templates clearly so users can quickly identify the right one. Include the purpose in the name (e.g., "Password Reset - Standard" vs "Password Reset - VIP").
Organize fields into logical sections. Users can collapse sections they don't need, making long forms more manageable.
Reduce form clutter by showing fields only when relevant. For example, show "Manager Approval" only when the request is over a certain budget.
Create templates as inactive, test with a few tickets, then activate once you're confident the fields capture the right information.
Only create company branches when there are significant differences. Minor variations can often be handled with conditional fields.
Reach for **Embedded Template** fields when one user request should spawn multiple PSA tickets that need different routing (different boards, priorities, or assignees). For variations that share routing, conditional fields inside a single template are simpler and create only one ticket.
Each embed's default board, priority, status, and type must form a valid PSA combination — especially for ConnectWise, where the status must be active on the chosen board. Use the Form Preview to walk through the conditional path that triggers each embed and review the embed template's PSA Integration Settings before going live.
## Troubleshooting
| Issue | Solution |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Template not appearing** | Verify the template is marked as Active |
| **Conditional field not showing** | Check the trigger field and value are correctly configured |
| **PSA fields not loading** | Verify your PSA integration is connected and synced |
| **Branch not saving** | Ensure you have permission to manage templates |
| **Import fails** | Check JSON format matches export format; CSV requires existing template |
| **Embedded template option disabled in picker** | The candidate template already contains its own embedded templates (depth-1 cap). Pick a non-embedding template, or restructure the deeper one |
| **"Embedded template references need attention" on save** | One or more embed fields point to a missing, cross-tenant, or self-referencing template. The red banner inside each embed picker explains which one. Pick a different target and save again |
| **Embed ticket failed but parent succeeded** | Open the parent ticket in your PSA; MSPortal posts a summary note listing each embed's fate. Common cause for ConnectWise is a default status that isn't active on the embed's default board. Fix the embed's PSA Integration Settings and re-fire the missing ticket manually |
## Related Resources
Configure categories, defaults, and ticket behavior
Use AI to quickly create tickets from descriptions
Bulk import and export data
Set up PSA integration for ticket sync