Simple Search Macro
The Simple Search macro is an interactive issue searcher that can be configured for any Custom Jira Charts macros on your Confluence page.
Use Simple Search to filter linked Custom Charts at the click of a button.
The Simple Search macro and the Custom Charts macro are 2 separate macros with unique configuration settings, though the user interface and customization options are very similar. Adding the interactive searching capability of Simple Search to your Custom Charts macros happens in 2 parts:
Part 1 - Adding and configuring the Simple Search Macro
Part 2: Adding the Custom Charts Macro and connecting it to the Simple Search macro
Add the Custom Charts macro
Set the Simple Search macro as the Source on your Custom Charts macro
Configure the Custom Charts macro
Steps for each part are broken down below.
Part 1: Adding and Configuring the Simple Search Macro
Adding Simple Search to your Confluence page
To use Simple Search, add the Custom Charts - Simple Search macro to your page as you would add any macro.
Click Insert at the top of the Confluence page
In the search box, type Custom Charts
Select the Custom Jira Charts - Simple Search macro
Customizing Simple Search
To set up your Simple Search:
Start by setting a Source for the Simple Search gadget - select a Project, Saved filter or JQL query (For more information on Simple Search Source, check out https://ossapps.atlassian.net/wiki/spaces/CCFC/pages/2119958533 in our FAQ)
If you need some help writing your JQL query check out our quick getting started guide
Select fields to display under Simple Search Fields on the right side of the screen. Select from custom fields in your Jira instance or from Simple Search fields.
You can drag and drop to reorder the fields, click on the pencil to customize how the fields display, or click the trash can to remove a field that you’ve added.
Once the fields are displayed on the left side in the Live Preview you can select options from the fields. Whatever you select here in the editor will be saved as the default configuration for users viewing the page.
If you want to create another default configuration, simply turn on Tabs and repeat steps 1 & 2.
When selecting your default configuration, you can choose your operator to adjust the JQL to be AND, OR, NOT. This allows you to do things like easily exclude certain values from the results returned.
Up to 5 tabs can be added, and the default configuration is unique per tab. Each tab can be renamed or reordered by dragging and dropping. Select the trash can to remove a tab and its configuration.
Enter in a Title along the top to customize your Simple Search even further!
Using Simple Search Fields
In addition to selecting from custom fields in your instance, there are a few special Simple Search fields that are available to be added.
Simple Search Field | Description | |
|---|---|---|
| 1 | Custom JQL toggle | This field allows you to enter in your own JQL to appear as a button on the Simple Search view. You can display the JQL as written, or give it a name that’s easier to read. |
| 2 | Saved Filters - Single toggle | This field allows you to directly link to an existing Saved Filter, rather than entering the JQL into Simple Search. |
| 3 | Saved Filters - Multi-select | This field allows users viewing the dashboard to select from existing Saved Filters. |
| 4 | Contains text search | This field searches Summary, Description, Comments, and text custom fields. |
Dark Mode
Just like Custom Charts, Simple Search can be viewed in Dark mode or Light mode. Dark mode changes the colors of your Simple Search macro for all users viewing the page. There are two ways to turn dark mode on/off.
Select the Sun/Moon icon in the Live Preview
Toggle Dark Mode on/off in the Display Settings
Light Mode | Dark Mode |
|---|---|
Display Options
Setting | Description |
|---|---|
Show Order by selector | Disabling this option will remove the ability to sort the issues filtered by the Simple Search macro. |
Allow users to add fields in view mode | Disabling this option will prevent users from being able to add other fields to Simple Search while viewing the page. |
Show description | This option will show/hide the text entered on the Description tab. You also have the ability to display the description at the top or bottom of the Simple Search macro. |
Dark Mode | Dark Mode can be enabled and disabled using this option, or under display options or by selecting the moon/sun icons on Live Preview. |
Import/Export
Just like with the Custom Charts macro, you can export your Simple Search macro configuration, then import it into another Simple Search macro on the current page or on another page. To do this:
While in the macro editor, click the Import/Export button in the configuration section on the right side
Click Copy to clipboard
Navigate to the other desired Simple Search macro
Click the Pencil icon to open the Editor
Click the Import/Export button in the configuration section on the right side of the Editor
In the “Import Simple Search Configuration” section, paste the configuration into the text box, then click Import Configuration
Use the Live Preview on the left side of the editor to review the imported configuration, which will include the Source, fields, and defaults from the original Simple Search macro configuration
Part 2: Connecting the Simple Search macro to a Custom Charts macro
Once you’ve customized the Simple Search macro, the next step is to connect it to your Custom Charts macros so it can act as the interactive searcher for your charts.
To connect a Simple Search macro to a Custom Chart macro:
Add a Custom Jira Charts for Confluence macro to your dashboard
Edit the Custom Charts macro
Select Simple Search macro from the Source dropdown selector
Once selected, you’ll see the Reference ID from each Simple Search macro on the page
If you have multiple Simple Search macros on one page, simply edit the Simple Search to find the Reference ID
Tip! Multiple Custom Charts can be connected to a single Simple Search macro.
Using Simple Search
Once the macro is saved and connected to Custom Charts, users can select from the fields that are shown, and if enabled, filter by adding custom fields.
These fields won't be saved when the page is refreshed, so each user can create their own custom search.
Clicking the “Search” button on the Simple Search macro updates all the linked charts to be filtered by your selections.
Sort the results to order the issues returned in each of the linked charts. Order by ascending or descending.
Select Show JQL to view the full JQL query used by the Simple Search macro.
Edit the JQL query used by the Simple Search macro for more granular control.
Reset the search and view the Simple Search ID using the actions menu.
Try it yourself!