Admin Info

EN | Administrator guide for configuration of UPPS! Extension Smart Insert.

---

Overview

What is my appropriate role as a reader?

• You are a user with read/write access to the Polarion system or project administration.

What should I already know?

• You should be familiar with working in the Polarion administration environment.
  

What will I learn from reading? 

• You will learn how to configure the behaviour and functionality of the UPPS!E Extension Smart Insert, either globally for all projects on the server or specifically for selected projects.
  

Table of contents

For technical reasons this wiki page does not contain an embedded table of contents.
Please use the navigation panel on the left-hand side of this page to navigate.

Introduction

The Smart Insert (SI) allows users to dynamically insert content, such as script-generated text, query results, or usernames directly while typing in Polarion text fields.

Users can activate the Smart Insert by typing any configured group symbol (such as %, #, or @) while editing a text field. This opens the Smart Insert menu and displays the categories linked to that group. Each category represents a specific type of contentthat can be inserted into the field.

Alternatively, users can press Ctrl + Space to open the Smart Insert menu. This displays all available group symbols, which the user can select to insert the desired type of content.

Each category defines the type of content that can be inserted into the field.

Example

An administrator can define groups using symbols like %, #, or @, each with their own categories. For example:

• %timeStamp inserts the current date and time.
• #workitems lists the Work Items within the current LiveDoc and allows the user to insert the selected one as a cross-reference.
• @projectUsers lists all users of the current Polarion project and inserts the selected user name and ID as text.

Each Smart Insert installation includes a predefined set of groups and categories. Administrators can modify or extend these as needed.

Quick Start

Follow these steps to configure the Smart Insert in the Global or Project Administration page:

1. Define a Group

Create a group by selecting one of the category types: Query, Script, Users.
Assign a unique and easy-to-type symbol (for example %, #, or @ ).
Optionally, specify a Title and Description for each group to help administrators and users understand its purpose.

A group contains one or more categories, which are displayed when the symbol is typed.

2. Add Categories to the Group

Define one or more categories that specify what type of content can be inserted.
Each category is identified by a command that follows the group symbol (for example %timeStamp, #workitems, or @projectUsers).
Optionally add a Title and Description to clarify the behavior of each category.

Tip: If a group contains only one category, you can enable the Standalone attribute. When active, typing the group symbol immediately triggers that category. No additional command or confirmation required.

Note: See the chapter "Category Types" for detailed configuration instructions for each category type.
Also, the Standalone groups still keep an internal command value so that global and project configurations can merge reliably, even if users never type the command explicitly.

3. Save Changes

Save the configuration on the administration page.
Configurations saved in the Global Administration are automatically available in all Polarion projects where the Smart Insert is enabled.
Additional groups and categories can be created in the Project Administration.
If a project defines a group symbol that already exists globally, the global and project configurations are merged within that project.
If a category command exists in both layers, the project configuration overrides the global one.

Once configured, users can type in one of the group symbols or press Ctrl + Space while typing in text fields to activate the Smart Insert and insert the desired content.

Tip: Test your configuration with a single group and category first. Once verified, expand it to include more categories and symbols as needed.

Note: Smart Insert must be enabled both globally and for each relevant project by selecting the checkbox on the upper-right corner of the administration page.

Tips

• Choose symbols that are easy for users to remember, and avoid reusing the same symbol for unrelated content.
• Use the Title and Description fields to help users understand the purpose and behavior of each category.
• Prefer Query categories for data that changes over time, and Script categories for computed or generated output.
• Start with a small, focused set of groups, gather user feedback, and refine the configuration as needed.
• Watch for validation highlights. Fields marked in red must be corrected before saving.

Category Types

Query Category

Overview

A Query category performs a filtered search for the selected Polarion object type (WorkItem, LiveDoc, TestRun).
The results are based on the chosen object type and an optional query expression.

Fields

• Scope: The object type to be filtered (WorkItem, LiveDoc, TestRun).
• Query: Optional query expression to refine the results.
• Query Coverage: Defines the scope for the query (Global, Project, Module).
• Fallback to broader scope:
  • Enabled: Automatically broadens the scope if the user is in a higher-level context.
  • Disabled: Returns no results if the user is outside of the defined scope.
• Limit: Maximum number of results displayed.

Tips

• Start with an empty query to confirm the scope and data set, then refine the expression.
• Use the limit to keep result sets manageable for users.
• Pick clear commands, for example #open-requirements, so users know what the query returns.

Script Category

Overview

A Script category dynamically generates text by executing a script in the selected engine.

Fields

• Engine: The execution engine (Velocity Template, JavaScript).
• Script: The script body that generates the output.

Context Variables

• project – The current project the user is working in.
• module – The current LiveDoc being edited.
• workItem – The Work Item currently in focus.
• user – The logged-in user.
• fieldType – The target field type ( "richtext", "multiline", "singleline" ).

Tips

• Start simple. Begin with a literal string before adding complex logic.
• Return intermediate values during development to quickly validate assumptions.
• Avoid long-running loops or blocking operations to keep insertions responsive.

Result Structure

Scripts can return either a plain string or an array of objects that follow the Smart Insert Item Data structure (See Field Reference below for more details). Each item must define a unique id and the data string to be inserted. Optional fields can provide metadata, navigation helpers, or control visibility.

Field Reference

Basic: Return a String

Good for quick prototypes or when the script always inserts the same value.

new Date().toISOString();

Intermediate: Single Item Object

Returns a single item object to include metadata (subtitle, tooltip) while still inserting one value.

const now = new Date();

{
    id: `stamp_${now.getTime()}`,
    data: now.toISOString(),
    title: 'Today',
    subtitle: 'ISO Date',
    tooltip: 'Inserts the current date in ISO-8601 format.',
};

Advanced: Multiple Choices

Returns an array of SmartInsertClientItem objects so users pick the variant that fits their context without switching categories.

const formatterDate = new java.text.SimpleDateFormat('yyyy-MM-dd');
const formatterDateTime = new java.text.SimpleDateFormat('yyyy-MM-dd HH:mm');
const now = new java.util.Date();
const currentDate = formatterDate.format(now);
const currentTime = formatterDateTime.format(now);
const userId = user.getId();
const userName = user.getName() || userId;

[
    {
        id: 'stamp_date',
        data: currentDate,
        title: 'Current Date',
        subtitle: 'Date',
        tooltip: 'Insert the current date.',
    },
    {
        id: 'stamp_date_author',
        data: `${currentDate} | ${userName}`,
        title: 'Date + Author',
        subtitle: 'With author name',
        tooltip: "Insert the current date and the current user's name.",
        marker: 'author',
    },
    {
        id: 'stamp_time_id',
        data: `${currentTime} | ${userName}`,
        title: 'Date + Time',
        subtitle: 'With timestamp',
        tooltip: "Insert the current date, time, and current user's name.",
        hidden: false,
        disabled: false,
    },
];

Further Reading

• Scripting Guide and Examples (PDF)
• Velocity (Widget) Guide (PDF)
• Polarion SDK Index

Users Category

Overview

A Users category returns a filtered list of users based on selected roles, inclusion/exclusion lists, and an optional query.

Fields

• Roles: Optional list of Polarion User Roles.
• Included Users: Users always included in the returned list.
• Excluded Users: Users explicitly removed from the returned list.
• Users Query: Optional query for additional filtering.
• User Coverage: Defines the search scope (Global / Project).
• Fallback to broader scope:
  • Enabled: Expands the search scope automatically if the user is in a higher-level context.
  • Disabled: Returns no results if the user is outside of the defined scope.
• Limit: Maximum number of users returned.

Tips

• Use roles and queries for broad targeting, and keep included or excluded lists short.
• Set a reasonable result limit to keep suggestions fast and relevant.
• Choose clear, descriptive commands such as @reviewers or @mentors.