Forge jql function documentation

Forge
,
1

I’m looking into building a jql function but can’t find enough docs… will someone please point me in the right direction? I see this… https://developer.atlassian.com/cloud/jira/platform/forge/ and https://developer.atlassian.com/platform/forge/manifest-reference/modules/jql-function/ but where do I find more info? What data type do I need to return? I would love to see more info and definitely more examples.

Also, why isn’t forge tunnel logging a simple console.log('Hello, World!'); when I search using my function? Is that a limitation of jql functions? The tunnel worked fine when I played around with a UI based test.

Thanks in advance for any advice!

2

Hi @GeneC, thank you for reaching out!

Here you can find more information about JQL function modules: https://developer.atlassian.com/cloud/jira/platform/jql-functions/
(The examples section is at the very bottom of the page)

console.log() should work fine; there is no limitation in the JQL function module that could affect that. Please ensure you are using the latest Forge CLI version.

Best regards,
Łukasz

3

Thanks for the reply.

I figured out the issue with logging/tunnels. This is probably something people should talk about more in this community when helping with this question because all I ever see is “make sure you’re running the latest cli version”.

It’s the precomputation of the function. So when I searched for issue in weekOf("foo"), it most likely worked once. But then the stored mapping of that was saved and subsequent searches never logged anything to my console. One fix is to just simply change your search term: issue in weekOf("bar") and it should log.

Hopefully this helps others in the same situation.

4

RE: examples…

Thanks for the link to a couple more examples, however this appears to be a common pattern in the docs and I figured it was worth mentioning:

When you create a new app forge create, it creates a new folder with some basic code. The code from that template is very often a 1:1 of the “example code” in the docs (bottom of this page).

I’m trying to add another argument but don’t see any ‘real’ docs other than just describing what name and required do. I’ve tried:

arguments:
  - name: text
     required: true
  - name: absolute
     required: false

but that doesn’t seem to even allow me to pass in a second arg at all.
image

5

Ok it looks like name: should actually be type: or something. Changing absolute to text worked.

arguments:
  - name: text
     required: true
  - name: text
     required: false
6

How do permissions work with no UI component?

I guess I need:

permissions:
  scopes:
    - read:jira-work
    - read:jira-user

Once I added that things stopped logging/working. How do I grant permissions for a jql function?

8

Hi @GeneC,

I figured out the issue with logging/tunnels. This is probably something people should talk about more in this community when helping with this question because all I ever see is “make sure you’re running the latest cli version”.

That’s true, but problems with logging/tunnels are very often related to the old version of Forge CLI; that’s why I asked if you were using the latest one.

Regarding your case, as you already found out, after the first successful invocation of the function, there is a precomputation stored in Jira, so there is no need to perform subsequent invocations for the same search clause. You can read more about this concept here: https://developer.atlassian.com/cloud/jira/platform/jql-functions/#precomputations

Thanks for the link to a couple more examples, however this appears to be a common pattern in the docs and I figured it was worth mentioning:

There is also a second Forge app, implementing a more advanced function: subtaskOf, I hope that you might find it helpful: Bitbucket

I’m trying to add another argument but don’t see any ‘real’ docs other than just describing what name and required do.

We really appreciate your feedback. If you feel that the current shape of documentation is insufficient, could you share how we can extend it to make it better for the future?

Regarding the list of arguments, this is just a list of pairs: argument name + required flag. We don’t check the types of arguments.

Ok it looks like name: should actually be type: or something. Changing absolute to text worked.

The previous name, “absolute” should also work; as I mentioned, we don’t check types of arguments. However, after modification of the manifest, you should run forge deploy and forge install --upgrade. It is also worth refreshing the page in Jira after upgrading an app. Sometimes, there is a short delay before the latest app changes will be available. I believe you hit this problem here.

How do permissions work with no UI component?

JQL function app doesn’t need any specific permissions. However, if you are using Jira REST API, you will need to add proper scopes, depending on the endpoint you are using.

9

Thanks Łukasz!

Hopefully one last question. I have this all working for the most part except the results I’m getting using it…

The result that I’m going for is something like this (which works and gives me results):

statusCategoryChangedDate >= 2023-10-29 AND statusCategoryChangedDate <= 2023-11-04 order by created DESC

This is how I’m using it but getting no search results:

issue in weekOf("4", "statusCategoryChangedDate") order by created DESC

weekOf({number of weeks offset from now}, {property to query}, {*optional param* is absolute)) is the function signature.

I’m guessing here but is the issue in whats throwing off the result? After the precompute and replace, is the full jql this?:

issue in statusCategoryChangedDate >= 2023-10-29 AND statusCategoryChangedDate <= 2023-11-04 order by created DESC

Is there a way to configure my app so that I can just simply type:

weekOf("4", "statusCategoryChangedDate") order by created DESC

… without the issue in?

Maybe I’m off on why it’s not working.

For what it’s worth, this is what I’m returning from the app:

{
  jql: 'statusCategoryChangedDate >= 2023.10.29 AND statusCategoryChangedDate <= 2023.11.04'
}
10

Hi @GeneC,

I believe that the problem is that you are returning the date in an incorrect format from your function. It should be 2023-10-29 instead of 2023.10.29. If you put such a query directly into JQL search, it will return an error:

image
image1238×162 15.8 KB

We should probably improve this on our side, and if the function returns the JQL fragment with this incorrect format, the error should also be displayed on the UI. I will take a look at that; sorry for the inconvenience.

I quickly tested my instance, and changing the date format fixed the problem. Remember that precomputation has probably been created already with an incorrect JQL fragment. To verify that your function works properly after the fix, change an input argument (you can also update the precomputation value using REST API https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-jql-functions--apps-/#api-rest-api-3-jql-function-computation-post).

Best regards,
Łukasz

1 Like
11

Oh my goodness. Thanks for helping my tired eyes! I truly appreciate your help on all this!