Forge Jira custom fields related events and value function

[ljarzabek]

We are happy to announce that improvements to the Forge Jira custom fields module are now available

Product events for custom field and its context lifecycle.

Forge application can now subscribe to Jira events for:

• custom fields
• custom field context
• custom field context configuration

Your Forge app must have permission from the site admin to access the data it provides within the event payload. The OAuth scope required for each event is documented below.

https://developer.atlassian.com/platform/forge/events-reference/jira/

Custom field value function

Forge apps can provide a value function that computes the value of the field. It gives the opportunity to introduce to the user computed value which will appear every time the issue will be revisited (only for the initial render).

https://developer.atlassian.com/platform/forge/manifest-reference/modules/jira-custom-field/#value-function

[takafumiohtake]

Thank you for the big improvements!

I’m interested in the Custom field value function.
I have some questions about the feature.

The document says,

Note that the issue view is the only view where the value function is invoked.

So, the function will be called only when users open the normal single issue view, right?
And, the function won’t be called when users open the issue navigator, rest API, or somewhere else.
The payload sample has multiple issues. I wonder why the payload has multiple issues.

This function is invoked on every issue render and the result is provided to the default rendering component, the formatter or the UI kit custom component. So, on the issue view, the user is always presented with the most up-to-date value returned by the function. Once the value function is invoked the value is saved in the database, so it is available in searches. This means the app does not have to store the value when running the function.

Does it mean the function is called every time an issue is rendered? So, can the value function be used for the use case like each user should get a different value?
And, the returned value is persisted but is it only used for JQL search?

[ljarzabek]

Hi @takafumiohtake,

So, the function will be called only when users open the normal single issue view, right?
And, the function won’t be called when users open the issue navigator, rest API, or somewhere else.

Correct. For now, value function is supported only on issue view and will be invoked only on the issue view.

The payload sample has multiple issues. I wonder why the payload has multiple issues.

It was designed in this way with future extensibility and improvements in mind. On the issue view, there will be only one issue in the payload list (the current one).

Does it mean the function is called every time an issue is rendered?

Yes, correct.

So, can the value function be used for the use case like each user should get a different value?

Since the calculated value is stored in database, I believe it would be cumbersome to achieve such behaviour.

And, the returned value is persisted but is it only used for JQL search?

One of the benefits is that application itself doesn’t need to store the value anywhere. And as you mentioned, since the value is persisted it can be used in searches.

I hope it answers your questions. Feel free to share your feedback or reach out if anything else is unclear.

[takafumiohtake]

Hi @ljarzabek,
Thank you for your answer.

It was designed in this way with future extensibility and improvements in mind. On the issue view, there will be only one issue in the payload list (the current one).

I’m looking forward to the future extension, especially the navigator view.
I guess this feature is related to [FRGE-135] - Ecosystem Jira.

Since the calculated value is stored in database, I believe it would be cumbersome to achieve such behaviour.
One of the benefits is that application itself doesn’t need to store the value anywhere. And as you mentioned, since the value is persisted it can be used in searches.

Our use case is this case. It’s important to show different values for different users. And, JQL search isn’t important for our app.
So, I wish there would be an option to disable persisting calculated values.

[ljarzabek]

Hi @takafumiohtake,
We will analyse your use case (disabling persisting calculated fields) together with [FRGE-135] - Ecosystem Jira. I’ll keep you posted about the progress.

Best regards,
Łukasz

[MaxGroe]

I think the documentation for value functions is a little bit lacking. I would like to see what exactly a value function should return. A simple example would be incredibly helpful. @ljarzabek

[ljarzabek]

Hi @MaxGroe, thank you for reaching out and for your feedback regarding documentation.

From the docs: https://developer.atlassian.com/platform/forge/manifest-reference/modules/jira-custom-field/#value-function

The function receives a list of issue IDs and returns a list of values for those issues. The values returned must be compatible with the format expected by the Edit Issue REST API operation. For example, for users the value must be an object that contains accountId.

For a number field from the question you posted here: Setting number custom field value with value function

it should look like below:

export const renderNumber = (args) => {
  return args.issues.map((issue) => calculateNumber(args.field, issue.id));
};

const calculateNumber = (field, issueId) => {
  return 5;
};

We will improve an example in our documentation. Once again, thank you for the feedback!

[MaxGroe]

Is there a way to force Jira/Forge to calculate an intial value for every issue? I’m asking because I would like to add a custom field and then use the value of this field in JQL searches.
However as far as I understand it, when I add a Forge custom field, then the value for each issue will only be calculated when a user views the issue and until then, the value is empty .

[ljarzabek]

Hi @MaxGroe,
Unfortunately, currently there is no such option to trigger value function for all issues when field is created - value function is invoked only on issue render.

As a workaround you could try to listen to Custom field product events: https://developer.atlassian.com/platform/forge/events-reference/jira/#custom-field-events
and then update values using e.g. REST API: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-values--apps-/#api-group-issue-custom-field-values--apps-

Hope it helps. Best regards,
Łukasz