Oktul home
  • English
  • Estonian

The documentation is in English only.

Contact us

Create a Work Item Selector field

Creating an Oktul Work Item Selector field in Jira Cloud, choosing single or multi select, configuring its context and putting it on a screen.

Choose single or multi select when you create the field. You cannot switch it later.

Field type Holds
Oktul Work Item Selector (Single Select) exactly one work item
Oktul Work Item Selector (Multi select) up to 100 work items

100 is Forge’s limit for a list field. The picker shows up to 25 matches per search; typing narrows the list.

Create the field

  1. Open Settings, the gear icon at the top right, then Work items
  2. Select Fields in the left menu
  3. Select Create new field, at the top right
  4. Choose Oktul Work Item Selector, single or multi select, then name it

    Name it for the relationship it records, such as Blocked by. The name appears in JQL and exports.

Jira's Create field dialog with Oktul Work Item Selector (Multi select) chosen as the field type, and empty Name and Description boxes.
The field types sit in Jira's own list, beside the built-in ones.
Jira's Create field dialog with Oktul Work Item Selector (Multi select) chosen as the field type, and empty Name and Description boxes.

Configure the field context

The field offers nothing until its context has a JQL scope. Columns and permission mode are set there too.

  1. Open Settings, the gear icon at the top right, then Work items
  2. Select Fields in the left menu
  3. Find the field you created, then select the three dots beside it and Contexts and default values
  4. Select Edit custom field config
  5. Set the work item scope, and whatever else the field needs

    Five sections: Work item scope, Permissions, Columns, Picker and Jira links. Only the JQL scope is required; the rest have defaults.

The field context settings: a JQL scope using the {{user.accountId}} placeholder with its syntax confirmed valid, then the Permissions, Columns, Picker and Jira links sections, closed.
Everything specific to one field context lives on this screen: the scope, whose permissions the search runs with, the columns, the picker's placeholder and the Jira links.
The field context settings: a JQL scope using the {{user.accountId}} placeholder with its syntax confirmed valid, then the Permissions, Columns, Picker and Jira links sections, closed.
The configuration screen documents itself

Below Save, the Knowledge base covers Automation, Filtering (JQL), Reverse lookups and Workflow validation. Every example uses this field’s own id, ready to copy.

Put it on a screen

A custom field is hidden until it is on a screen.

  1. Open Settings, the gear icon at the top right, then Work items
  2. Select Work type screen schemes in the left menu
  3. Open the screen scheme used by the space you want the field in
  4. Select the screen scheme for the work type that should carry the field
  5. Choose the relevant screen

    A screen scheme either has one default screen or a separate screen per operation: creating, editing and viewing a work item.

  6. Search for your field, with Add the field to the field schemes of all projects using these screens selected

    The field is on the work item once this is saved.

A screen is rarely used by only one thing

One screen can serve several spaces, work types and operations, so a field added here can reach people who did not ask for it.

Columns

One to seven, any of them optional. A new field starts with work type, key, summary, priority, status and assignee.

  • Order is fixed: work type, key, summary, priority, status, assignee, then other fields in the order of the configuration screen. This matches how Jira draws a work item everywhere.
  • Each column looks as it does in Jira: status lozenges, priority and work type icons, dates in the site’s format, up to three avatars then a count, tags, Assets objects by label.
  • When space runs out, the summary shrinks. Key, status, priority and assignee stay whole.
  • In the picker, each column is cut at 40 characters. Cards on the work item are not.
  • A multi select field shows ten cards, then +3 more.

Under IGNORE_USER the columns are all a person sees of a work item they cannot open.

Placeholder text

The Picker section sets the empty search box text, up to 100 characters. The default, Search work items…, follows each person’s language. Your own text is shown as written. Clear it to return to the default.

Off by default. Turn on Create a Jira link for each selection and choose a link type. The screen shows an example: this work item [blocks] the selected work items.

  • Selecting a work item creates the link. Removing it deletes the link.
  • Deleting the link by hand removes the work item from the field.
  • The app removes only links it created. A matching link someone made by hand is adopted, not duplicated.
  • Changing the setting applies to each work item the next time its selection changes.

Test it as an editor

Open a work item, edit the field and type three characters. The picker matches summaries; a key such as IT-12 finds that work item.

A New task dialog with three work items selected in the Related Work Items field and more listed below it as plain text.
A multi select field on a create screen: each option is plain text, its columns joined with a middle dot.
A New task dialog with three work items selected in the Related Work Items field and more listed below it as plain text.

Under RESPECT_USER a person sees the scope minus what they cannot browse. Under IGNORE_USER they see the whole scope. Test with an account that has less access than yours; an administrator sees everything in both modes.

A problem or a question? Write to support@oktul.com or open a request in the Help Center (opens in a new tab).