Hey Compass team, meet the Atlassian Ecosystem 👋🏻

[remie]

Hey Compass team!

Nice to meet you here on the Atlassian Developer Community.

I guess you’ve never actually released a real feature unless it has broken multiple Atlassian apps In this case, I’m talking specifically about the new components implementation of Jira Software projects, announced here: Compass Components in Jira Software are coming! - Atlassian Community

Probably the Jira team should have told you more about the Ecosystem, but given their complete lack of providing any context with regard to this change in the changelog, I guess we can’t really blame you. You’re in good company with regard to breaking apps.

For those not initiated yet into this new feature: newly created company managed Jira projects will now have “Compass Components” instead of the classic native Jira components. I expect this is also going to be enabled by default for previously created company managed Jira projects that have not yet used Components. But I haven’t played with it enough to know all the use cases of how this change will break apps.

Oh right, I should tell you why this actually breaks apps. This is because the Jira REST API will no longer accept any mutations to project components if the Jira project is using “Compass components”. Given that this is the default, this means that the native Jira project component REST API endpoints will not work by default. A customer will need to actively switch back to native Jira components first.

This will break synchronisation apps like our Version & Component Sync app, Version Sync by codefortynine, Backbone Sync by k15t and probably Octo by Jexo/App fire

Obviously, I get you want to upsell your brand new product. But perhaps it would be good to consider how these type of changes might impact Marketplace Partners. I mean, it’s not like there isn’t a long-running jira issue open about working with Components.

Anyway, as always it’s a great pleasure to spent the festive season scrambling to fix completely avoidable issues that could have been prevented with proper communications!

Happy holidays!

PS: special thanks to @NicoFrossard for bringing this up in the partner channels, and @matthias for also confirming that this is disrupting their apps.

[matthias]

Hey Compass team,

I think it’s great that you work on an integration between Jira and Compass and wish you tons of success with it.
As Remie mentioned, our app, Backbone Issue Sync, is somewhat affected to this change and I’d like to raise a couple of questions/topics:

1. New company-managed components are used by default
Is this a conscious decision that Compass components are the new default for components? I assume that most Jira customers out there don’t use Compass yet and probably also have no concrete plans to do so. So as an administrator of a Jira instance, I’d now need to take care for every new project I create to switch back to Jira components before I use it?
If you want to do a marketing push for Compass, feel free to apply some (aggressive) marketing text on the Components screen, but please don’t use the Compass components as a default.
I’d ask you to revisit this decision.

2. How can we determine via the API which type of components a project uses?
I can see in the UI which components a project uses, but there doesn’t seem to be an API to determine that via the API. Is there one? The project feature API unfortunately doesn’t include it.

3. Is there some API we can use as a Jira Connect app to create or update Compass versions?
Our app offers to create components while synchronizing issues, however the error messages seem to tell me that I can only use the Compass API to create or update components. However, this is a GraphQL API - and I don’t see how I could call it from my Jira Connect app. Do you have a solution for me?

4. Thank you for the support of get/update issue
Thank you that the usual Jira REST API is able to return Compass components and also add components to issues.

Hope to hear from you soon.

Cheers,
Matthias.

[NicoFrossard]

@matthias regarding your second question “How can we determine via the API which type of components a project uses?”: it seems you can fetch the Project property jira.global.components.

The property seems to be set to true if the project uses Compass components, and to false if it uses Jira components. If the whole feature is not available yet on the Jira instance, the property will be missing.

Please note that this is only based on my observation, I haven’t found anything in the documentation.

[KatieSilver]

Hi @remie, @matthias, @NicoFrossard, and others,

Thank you for reaching out and sharing your concerns about the new integration bringing Compass components into Jira Software. This is our first major venture into the Jira world, and as you mentioned, it hasn’t been completely smooth. I agree that we made a mistake in our Ecosystem communications, and we are working to provide a more detailed update in the change log as soon as possible.

Internally and externally, we refer to Compass as a “developer experience platform.” Our goal is to ensure that developers enjoy their work and achieve success. I hope this conveys how much respect and appreciation we have for developers - within Atlassian, our ecosystem, and beyond. We genuinely want to make it easy for all of you to work with Compass and our integrations (and even build apps for Compass - which benefits both sides).

It is intentional that Compass components will be the default on new projects going forward. I’ll give you some context into why we made that decision. Our research shows that, while there are many different uses for the Components field, many customers already use it to track software components. The existing Components field functionality can be replicated using Automation and Custom Fields, while the Compass integration brings new value by providing information about components in context within Jira. The Compass team has the time and capacity to invest in significant improvements; for example, we plan to bring Compass components into Team-Managed projects. Lastly, our Compass catalog is free - and will remain so. Users of JSW only need Basic Compass Access to use the catalog, and no license is required to use the field. I hope this clarifies some of our reasoning.

You’re correct that users who want to continue using Jira components on Company-Managed projects will have to opt-out per project. We included this opt-out functionality because we understand that many users (including app creators) utilize Components differently from how they are used with Compass. I apologize if we didn’t fully meet your expectations. Would it be helpful if we included a site-level opt-out to simplify the process? I’m also curious to know if you have considered how your users might adapt to global components. Is that something they have requested, or do you think most of them will choose to opt-out and continue using the Jira functionality?

I believe there are other opportunities for apps like yours to synchronize with Compass as well. For instance, we receive requests for syncing Compass catalogs between multiple sites, which seems like an excellent fit for a synchronization app. What do you think?

@andrei2 , our principal engineer on Compass, is going to follow up with some specific answers to your questions.

To sum up, I’m sorry we dropped the ball on the ecosystem communications, and we’ll fix that as quickly as possible. I’m hopeful that we can learn from your experiences as app developers as we connect Jira Software and Compass in the future, and make working with our integration easier as well.

Katie - Compass PM

[andrei2]

Hi Nico, thanks for posting this, that is accurate. It’s the property we’re using in order to determine whether a given project has Compass components enabled or not.

Technically what we check for is simply whether the value of the property is “true” or not, but that is very much the source of truth for that behavior.

[andrei2]

Hi Matthias, thank you for your questions and apologies for the lack of documentation around this. We’re working on adding more detail to our documentation as quickly as we can and will hopefully have more things to point to soon. We’re actively monitoring user feedback about this functionality, and we’re open to suggestions on how we could improve.

Now, to your questions:

As Nico posted above, the canonical way to tell which components a project uses is through the Project property API ( https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-properties/#api-rest-api-3-project-projectidorkey-properties-propertykey-get ) using the jira.global.components property. We’re actively working on adding more documentation around this to make interacting with this feature easier.

Is there some API we can use as a Jira Connect app to create or update Compass versions?

We don’t have a great solution for you here. Compass doesn’t have support for Connect so creating the components in Compass would need to go through an API key or a user session.

The other thing to figure out is whether the things you’re trying to create are the sort of things Compass cares about or are better suited to being Jira components, or even custom fields of a different type.

Can you tell me more about the use case you’re trying to cover here? I can potentially see if we have any options we could explore or some other mitigations that we may be able to put in place.

Thank you again for calling all of these out and keeping us honest.

[roman.lutsiv]

@KatieSilver , @andrei2 , thank you for the prompt follow up.

Component API changes turn to be backward incompatible - that requires a deprecation period to be followed, see Atlassian REST API policy. I am in particular referencing to this part:

Publicly accessibly REST APIs must be given reasonable notice of deprecations. Any deprecated REST API in the cloud environment MUST be available in its original form for at least 6 months, UNLESS there are critical security vulnerabilities or these APIs are provided by plugin extensions as noted above.

As these changes are related to new feature development, and not critical security issues, could you please consider reverting them and follow the expected deprecation process with clear communication on when changes are coming into effect, so vendors can get the apps ready?

[KatieSilver]

Hey @roman.lutsiv ,

Thanks for voicing your concern. We reviewed our options internally, and we’ve decided to roll out a change to temporarily relax some of the restrictions on how the Project components API works to provide a longer transition period. Specifically, in both the v2 and v3 API, turning Compass components on will no longer prevent API users from creating, updating or deleting project components for that project.

CRUD Project component operations will continue to not be exposed in the UI, as projects can only use one component type at a time (Jira or Compass.) For the same reason, we’re keeping the restrictions on the issues API in place. We want to keep the functionality clear for users, so we feel it’s important that this restriction stay in place. Users can still opt out of Compass Components if they’d like.

This change will be announced in the changelog as soon as it’s live (ETA this week.) We will leave this access open for a period of 6 months, at which point at which point we will return to the new behavior, and reject CRUD operations on Jira components for projects that have opted into Compass components.

I hope this helps.

I’m still very curious though for your (and everyone on the thread’s) thoughts about how you might adapt your apps to work with Compass components. Have you looked at the new functionality added? Are there any predictions you have based on previous user experience? If you have thoughts on how we can help make this transition easier, I’d love to hear them.

[matthias]

Hi @andrei2 & @KatieSilver,

thank you for being so responsive and actively working on our feedback, this is really appreciated.

• The API with the jira.global.components property works fine for us.
• In understand that creating Compass components for Jira Connect apps is not the easiest thing to support.

Our use case
Backbone Issue Sync is an issue syncing app which allows to synchronize issues between projects on the same or also different Jira instances.

When we sync within the same instance, it is quite straight forward. We can retrieve the Compass components via the get issue endpoint and update them also via the update issue endpoint.

For syncing across instances, we’re missing the part to create Compass components automatically. I’m grateful that you’ve added support for getting compass components via the get project components endpoint. This way, we can look up the components by name (if they’re already existing) and assign the correct ids to them.
So, as a workaround, our customers can create their components manually.

Our plans
So, with the APIs we have, we plan on adding support for synchronizing Compass components between Jira issues some time soon.

@KatieSilver / @andrei2 if you want to have a deeper discussion about any of these scenarios, happy to chat with you, just send me DM.

[roman.lutsiv]

hi @KatieSilver , thank you for the response and action planned.

There is the problem with setting/updating Component field in case if it’s provided by Compass. E.g. we are using the component’s name to set Component on Jira issue by calling PUT /rest/api/3/issue/<id> API. Currently it’s possible to update component by providing this value in the API request body:
{ "fields": { "components": [ { "name": "My Component" } ] } }

When Compass feature is enabled that method does not longer work. It looks like component’s Id is required. Of course we can switch to Ids everywhere, however that is non zero effort, and it’s another undocumented API change.

Finally, answering your question:

Have you looked at the new functionality added? Are there any predictions you have based on previous user experience?

We have been checking Compass REST APIs (https://developer.atlassian.com/cloud/compass/rest/api-group-events/#api-group-events) but there were not many updates there. And now Jira APIs are impacted instead - so instead of focusing on potential adoption scenarios we temporary need to focus on fixing things

[KatieSilver]

Awesome, thanks @matthias . That’s super helpful. I have had several customers request cross-site linking recently; I think the idea is that they’d want a single compass instance that they could use with multiple Jiras. Could be a good use case to consider. I’ll reach out if we have more questions in the new year!

[andrei2]

Hi @roman.lutsiv,

Thanks for calling that out, that was a change from the prior behavior, we’ll be sure to update the documentation and call that out explicitly.

The reason is that Compass components do not enforce name uniqueness, so just passing in the name doesn’t do a good enough job to help us land on the right component to set for that particular issue. We were kicking around the idea of just grabbing the first one that matches for a bit, but that seems like it would be significantly worse since it might result in nondeterministic behavior.

Note that for projects without Compass components enabled, there should be no change in behavior.

[LeoNunes]

@KatieSilver our app have a feature to create cross-project components. If you enable Compass for a project that was part of cross-project component then after sync runs it will not be part of the cross-project component anymore. This happens because when Compass is enabled the Get project components API will not return the Jira components anymore and we think that it was deleted.

You mentioned that soon “creating, updating or deleting” Jira components will still work if Compass is enabled, this will give us time to fix other parts of the app that is partially not working properly. What about the get component API? If we can’t get the Jira components with the current API this is a big problem for us.

[matthias]

@LeoNunes, you can use the project property jira.global.components mentioned by @andrei2 to check whether the project uses Compass components or usual ones.

However, this adaptation also needs time. I appreciate the API change to the get project components API in general, but it should get the guaranteed 6 months transition period so that everyone has enough time to react.

Ideally for me, the API stays available in the EAP Jira Cloud instances, so that we can test and develop against it, but will only be rolled out after the 6 months to the production instances.

[KatieSilver]

Hey @matthias , we are going to give the 6 month notice period once the restrictions are rolled back from the API.

@LeoNunes was Matthias able to answer your questions or did you still have any outstanding?

[RafaelFerreira]

Hello everyone , Rafael one of the EMs working on Compass here.

I just wanted to update everyone on the corrective changes @KatieSilver had announced:

This change will be announced in the* changelog as soon as it’s live (ETA this week.) We will leave this access open for a period of 6 months, at which point at which point we will return to the new behavior, and reject CRUD operations on Jira components for projects that have opted into Compass components.

Unfortunately, this work took a little longer than we expected and we missed getting the changes in before we hit the Atlassian holiday change freeze. We now expect this change to go live by the week of Jan 8.

Apologies for the delay on this and happy holidays everyone!

[LeoNunes]

Hi @KatieSilver, keeping the option to switch to Compass components will still require us to adapt some part of our app. We will check the jira.global.components but when Compass is enabled our app will need to behave differently, so requires some adaptations.

[bartlomiejlewandowsk]

Hi folks, how does one turn this feature on so I can test the behavior in my app? I have a developer version of Jira (free for 5 users), but the components page for a company project do not show a button to switch to compass.

I’ve also created a compass instance for the same tenant and created a few components there. Still no way to turn this on. Is this feature behind a feature flag and I need to opt in somehow?

[ibuchanan]

Welcome to the Atlassian developer community @bartlomiejlewandowsk,

At this time, the feature flag is not exposed for users or developers to switch on their own. Assuming the original plan goes through, the feature flag would be rolled out to all Jira sites by end of this month.

[bartlomiejlewandowsk]

Hi Ian, I understand that is the case - can I request the feature flag to be turned on my instance though? I am blocked with the testing as of now.