Jira Custom Field Search Suggestions

Forge Forge UI Kit and Custom UI
, , ,
1

Hi all!
I’m trying to implement searchSuggestions functionality for my Custom Field Type according to the atlassian documentation.
Can anybody explain me how it should work? I get only three parameters (query, accountId, cloudId) in function and expression, the last two of which are useless. I can’t even identify the field. What is the idea of implementing this feature?

2

Hi @Alex_Basatski, thank you for reaching out!
It really depends on the type of your field and the logic you want to implement. The main idea behind this feature is to provide human readable suggestions in JQL search.

Basic example could return just a list of available values. Let’s take a look at an example app manifest: https://developer.atlassian.com/platform/forge/manifest-reference/modules/jira-custom-field-type/#example

jira:customFieldType:
  - key: progress-bar-field-type
    name: Progress bar
    description: A custom field that shows a progress bar.
    type: number
    validation:
      expression: value == null || value >= (configuration?.minValue || 0) && value <= (configuration?.maxValue || 100)
      errorMessage: Only numbers between the maximum and minimum values are allowed.
    formatter:
      expression: |-
        let abs = x => x < 0 ? -x : x ;
        let round = x => Number((x+'').replace('\.\d+', '')) ;
        let MIN = configuration?.minValue || 0 ;
        let MAX = configuration?.maxValue || 100 ;
        let PERCENT = (value + abs(MIN)) / (abs(MAX) + abs(MIN)) * 100 ;
        `${'▰'.repeat(PERCENT / 10).padEnd(10, '▱')} (${round(PERCENT)}%)`
    searchSuggestions:
      expression: '["0", "25", "50", "75", 100"]'
    function: displayProgressBar
    edit:
      function: editProgressBar
    contextConfig:
      function: configureProgressBar

The custom field is a progress bar and as a suggestion it returns just a list of numbers.

If the value of the field is rather obscure, you can return a list of objects with 2 fields:

[
  {
    "value": "340f8126-50f7-4fe7-8765-1a151678b917",
    "label": "Value 1"
  }
]

where value is actual value of the field and label will be displayed as a human readable string.

Regarding function arguments - it really depends on the use case if they are needed or not.

I hope it helps. You can also share your use case here, if you need advice how to implement suggestions in your app.

Best regards,
Łukasz

3

Hi @ljarzabek.
Thank you for your reply.
However, I would like to clarify one detail.
Does this mean that we can return a fixed list of values through searchSuggestions only for Сustom field type, not for Сustom field instances?
In other words, we cannot get the key of field which values are being searched, so we cannot identify the field.

4

Hi @Alex_Basatski,
searchSuggestions property is available for both jira:customField and jira:customFieldType modules. Please take a look at example apps:

I believe that field id/key is not required to implement it. However, if your use case requires such data, you can get them from the context: https://developer.atlassian.com/platform/forge/manifest-reference/modules/jira-custom-field-type/#extension-data (please use different method depending on whether you are using UI Kit or Custom UI).

5

I believe that field id/key is not required to implement it.

Why? Do you really think that custom fields of the same type can have the same set of values for all their implementations?

So @ljarzabek I’ll try to explain a third time. From documentation

This is achieved by adding the searchSuggestions section into the field definition in the manifest. The suggestion provider can be either a Jira expression, or a Forge function.

Only those parameters that I wrote above are available in the expression ( query, accountId, cloudId), the rest are undefined. It’s a fact from the documentation and my experience.
In the Forge function we cannot use an useProductContext() method just because it’s a REACT hook. This is obvious.
Next. We cannot use a view.getContext() method from @forge/bridge because this method can be implemented only in a module (in static directory).
And the main question is How I can get the context with all parameters you linked above in the Forge function of search suggestion?

6

Thank you @Alex_Basatski for the clarification. I’ve created the public ticket for this: [FRGE-955] - Ecosystem Jira - you can track the progress there.
If you have any other feedback/suggestion, it would be the best to include them as a comment within the issue.

Best regards,
Łukasz

1 Like
7

@ljarzabek thanks for your help.