Adding support for groupID field in Jira REST APIs, expressions types

Jira Development Jira Cloud Announcements
, , , ,
1

G’day Atlassian Developer community!

As shared earlier in Adding support for group ID along with group name in REST APIs and Jira Cloud Platform changelog, Jira Cloud is moving towards using groupID s as unique identifier for groups instead of group name s.

We have provided support for groupID field in all Jira Public APIs that use group name as an identifier. We will be removing the support for group name field from such Jira Public APIs starting from February 28 2023, as described below.

Why is it changing?

As you may know, Jira does not offer the functionality to rename groups. To enable that, we want groups to be identified by an identifier with is immutable. Currently, group name is used as an identifier, which is inherently mutable. Thus, we need to remove the use of group name as the identifier.

What is changing?

We have been using group name as group identifiers across all Jira Cloud public APIs. We are moving towards using groupID as the unique identifier for a group instead. All APIs that use group names across Jira Cloud like get notification schemes paginated, get all application roles, create permission scheme etc., including Jira expressions types and Connect conditions will be affected by this change. The REST API documentation The Jira Cloud platform REST API has been updated with this change.

There are also a few exceptions to it. More details on sample changes and exceptions are given below:

Examples

  1. Request type

This is an example of comment Visibility API (https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-links/#api-rest-api-3-issuelink-post)

Old behaviour: The request payloads used group name for mutation operations (like adding visibility, in the below example).

"comment": {
    "visibility": {
      "type": "group",
      "value": "jira-software-users"
    }

New behaviour: Now, these support use of groupID as identifier for all such operations. Similar changes have been made across all the APIs.

"comment": {
    "visibility": {
      "identifier": "276f955c-63d7-42c8-9520-92d01dca0625",
      "type": "group",
      "value": "jira-software-users"
    }
  1. Response type

This is an example of Bulk Get Groups API (https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups/#api-rest-api-3-group-bulk-get)

Old behaviour: Previously, the API responses had only group names.

"values": [
    {
      "name": "developers"
    },
    {
      "name": "juvenal-bot"
    }
  ]

New behaviour: Now, these will include groupIDs in addition to group names.

"values": [
    {
      "name": "developers",
      "groupId": "276f955c-63d7-42c8-9520-92d01dca0625"
    },
    {
      "name": "juvenal-bot",
      "groupId": "6e87dc72-4f1f-421f-9382-2fee8b652487"
    }
  ]

Exceptions

There are a few exceptions to these, where the APIs won’t get impacted by this change.

  1. This change won’t be applicable to APIs where group names are used as query parameters for search/ create operations etc.
  1. This change won’t be applicable for Workflow APIs. Changes to them will be released later, and a separate deprecation period will be given after that.

We have tried to be exhaustive in identifying these APIs, and providing support for groupIDs in them. In case you identify any APIs which do not support groupIDs in it, please reach out to us by replying on this thread.

When is the change happening?

The support for groupID has been already added. You might have already noticed these changes in the REST APIs and their documentation. Currently we support both group names and groupIDs to enable testing out these changes. We will be removing the support for group name field from such Jira Public APIs starting February 28, 2023.

What do I need to do?

We ask you to migrate away from using group name s and start using the groupID s in these APIs. We request you to start reviewing these changes and plan to incorporate them into your app to give yourself the maximum opportunity for a smooth transition.

The new behaviour is now available in all Jira Cloud APIs. If you encounter any issues or have questions, please respond to this post.

By when do I need to do it?

We are beginning the 6 month deprecation notice period with this announcement. We will switch off the old behaviour (supporting group names) starting February 28, 2023 . Meanwhile, we will keep you updated on any changes.

Please feel free to reply to this thread in case of any queries or suggestions once you try out the changes.

Thanks,

Varad,
Jira Cloud PM

2 Likes
2

Hi @VaradPingale ,
thanks for sharing this. However, how do you suggest workflow apps like JMWE or JSU handle such a changes in existing customer workflows? If customers have configured workflow extensions (conditions, validators and post-functions) that refer to a group, they will be referring to the group by name. Once support for group names disappears, these workflow extensions will simply stop working unless they reconfigure them.

When Atlassian released a similar change around users (introducing accountId instead of username/user key), a new API was introduced to fetch an accountId from a username or user key, to allow apps to maintain compatibility with older configs (since apps couldn’t update workflows behind the back of users). Are you going to introduce a similar API to get a groupID from a group name? The Find Groups API cannot be used for that purpose, as it may not return all groups whose name “contain” the string and so some groups might never be found by name.

Did you consider this impact?

Thanks,
David

6 Likes
3

Hi @VaradPingale ~ the bullet point under the 2nd Exceptions mentions the list of workflow APIs which are not affected: Workflow API group.

I don’t see any group returned in the example response section so was wondering why is it mentioned under the Exceptions above if the group is not returned in the response. Can you please clarify it?

Thanks

4

Hi @david2
Thanks for the question.

If I understand correctly, you want an API to get groupID using a group name.
In that case, I suppose you can use the Bulk get groups API.

Eg: If you want to get groupID for group named “abc”, you can use following endpoint:
/rest/api/2/group/bulk?groupName=abc

Please let me know if this is not what you were looking for.
Happy to discuss it in more detail.

5

Hi @ajay1
Thanks for the question

That’s correct, the Workflow API group does not contain the group name in response.

Although it contains a group name in the request payload. That’s the reason we have added that to the exceptions list.
Hope I answered your question. Happy to discuss more on this.

6

Hi @VaradPingale ,
yes, that endpoint should work, I didn’t notice earlier that you could query it by groupName. However, it is still marked as “Experimental”. Will it soon “graduate” to Stable?
Thanks,
David

7

Hi @VaradPingale ,
are you talking specifically about this: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-workflows/#user-is-in-any-group-condition ?

Thanks,
David

8

Some of the APIs have been marked with the “Experimental” tag, but those are widely used by ecosystem apps. I don’t have the exact timeline on when the API will graduate to “Stable”, but it’s totally fine to use it.

9

Hi @david2

It’s not specific to The Jira Cloud platform REST API (UserInAnyGroupCondition) but applicable to all the conditions and validators that use group names like The Jira Cloud platform REST API (UserInGroupCondition) and The Jira Cloud platform REST API (FieldChangedValidator).
Hope this answers your question.

10

Hi @VaradPingale ,
right, that’s exactly what I thought you meant: built-in Workflow Extensions that are returned by the workflow APIs and can be modified by the workflow APIs. It’s basically the same problem third-party workflow extensions have: right now these 3rd-party workflow extensions contain group names in their configurations and now we need to update them to user group IDs instead.

1 Like
11

Hi, @VaradPingale ~ JCMA has a group mapping table that currently returns group names. With this change, will it be returning the group ids as well?

12

Hi @ajay1
It will remain the same.
We don’t expose group ids as part of JCMA mappings. It’s only group names.

13

@VaradPingale that is not acceptable, as all Jira REST APIs are retiring the use of group names and replacing them with group IDs. Also, the whole idea of this group mapping table is to map P2-side groups with their Cloud-side equivalents, so it only makes sense to return the group IDs on the Cloud side.

Please reconsider your decision, which is not consistent with this announcement.

14

Hey @david2
Yes, we are retiring group names usage in the Jira REST APIs (Except a few as mentioned in the post).
This API is used while migrating from Server to Cloud. We want to keep using group names, as groupIDs are randomly generated strings and will be different for server and cloud instances. Hence, we won’t be able to use them to map.
If you have a specific use case where you want groupIDs only, please let us know so that we can take that into consideration.
Happy to have a call as well if that helps.
Thanks

15

Hi @VaradPingale ,
isn’t actually the whole point of having mapping tables to map server-side IDs with their cloud equivalent?
When we convert JMWE P2 workflow extensions to their Cloud equivalents, we need to convert P2 group names to their Cloud equivalents. Until now, that meant using the mapping table to transform the P2 group name to the Cloud group name. But since we now need to replace group names with group IDs in workflow extension configurations, we now need to map from a P2 group name to a Cloud group ID. Which the mapping table should be doing.

1 Like
16

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.

17

Hi @david2
After our conversation, I checked with the team owning the JCMA mappings. They confirmed that the table is mapping server-side group name to Cloud group ID. So no rework will be required from your side to convert group names to groupIDs.

19

Hello everyone,

It’s almost a month until the deadline, but the bulk API permission issue is still not addressed, which is a blocker for many people to implement group id support and perform data migrations
https://jira.atlassian.com/browse/JRACLOUD-79363

1 Like
21

@VaradPingale I am working on migrating to group IDs and I’ve encountered issue with the entity_property_contains_any_user_group Connect condition. It doesn’t work for me if I put group ids into entity property, but works with group names.

What is the migration path for this condition? I hoped that Connect will support both group names and group ids until February 28th, but this seems to not be the case.

1 Like