Changes to SEN availability in Connect app install payload

Announcements
, , , ,
1

What is changing?

Earlier, we foreshadowed that there are changes coming in the install payload to replace the SEN field with new identifiers. This notice describes the final form of this change. There are some differences between what we foreshadowed and what will actually change.

Why is it changing?

As described in Introducing New Cloud Identifiers, Atlassian is transitioning to new identifiers for app licenses. We had intended to add these new fields to the install payload but we have now decided to remove these fields from the install payload altogether.

The license information used to source both the SEN and entitlement IDs is, in many cases, not available at the time an app is installed. Rather than provide this information for some installs and not for others we feel it is better to provide a consistent mechanism apps can use to get license identifiers.

The preferred method to get app license information is to use the /addons endpoint: License API for cloud apps

Output from this endpoint will include a license block for a licensed app. An example is as follows:

   "license": {
        "active": true,
        "type": "COMMERCIAL",
        "evaluation": true,
        "supportEntitlementNumber": "SEN-9468998",
        "entitlementId": "e2dab8c3-7d0a-4b59-a4bd-c55f92862b07",
        "entitlementNumber": "E-3XJ-WYD-KA7-HBJ"
    },

What do I need to do?

If you are currently relying on the SEN field in the app install payload you should take two actions:

  1. Transition to getting this information from the REST endpoint indicated above.
  2. Transition from using SEN to using the new entitlement identifiers. You will be able to correlate values as both SEN and the new identifiers will be returned for a six month period.

By when do I need to do it?

New entitlement identifiers will be available from: Jan 04, 2022

The SEN information will be remove from the install payload and the license block in the REST endpoint.

SEN Removal Date: Jun 30, 2022

1 Like
2

Any known impacts to ACE?

3

Hi @cmacneill ,
this is actually a very bad idea. We log (instrument) everything that happens within our apps, and that includes the installation of the app by a new tenant. And we always include the SEN (and soon the entitlement ID) in these logs.
When we don’t have the SEN or entitlement ID in the installed payload, we use the License API to get it. However, license information takes a variable amount of time to become available through that API (5, 10, sometimes more seconds), and that creates a huge issue for us, as any user action taking place while we wait for the license info to become available (for the SEN to be returned) will be missing that SEN (or entitlement ID).

Bottom line is: we really need the SEN/entitlement ID as soon as the app is installed, and the easiest would be to receive it consistently through the installed call. I just don’t understand why license information cannot be collected by Jira/Confluence before the /installed webhook is called.

Please reconsider your decision.

Thanks,
David

3 Likes
4

@cmacneill can you please elaborate more on the rationale between what was foreshadowed and the actual implementation?

You never warned us about removing the SEN/EntitlementNumber from the payload and moving it to an API call, so we never had the ability to object. Making this announcement without consulting us and without giving any background information is antithetical to the whole concept of Atlassian Marketplace Partners. Let’s put the “Partners” back in “Partners”!

5 Likes
5

@cmacneill it has been 23 days since this comment
 can I still expect an answer, or are we just going to pretend it never happened?

6

@remie my apologies. I ended up taking some holiday leave and neglected to get back to you.

This change is mostly about transitioning from SEN to the new entitlementIds. It became clear during that work that in many cases the licence information from which both of these fields is derived is not always present at the time an app is installed.

Given that reality, passing the new ids, or indeed the SEN, does not make that much sense. I felt it was better to fetch the license information from the REST endpoint and recognize that it does not appear there immediately following installation.

I know it can take a little time to appear there but the fact is that the content of the install payload and the REST endpoint response are both driven from the same information.

7

At might not make much sense, but there is also no harm in doing it anyway. There is a difference between being able to use it right away when available, and fetch later if not available versus always having to fetch it.

Also, and this is a common thread within Atlassian, the root problem is not really whether or not it makes sense for the SEN to be inconsistently available. The root problem is that there is a disconnect between the asynchronous processes of SEN creation(?) and installation webhook execution.

The solution to just simply remove the SEN and have vendors poll an API hoping that it will become available at some point is very very lazy and puts the burden entirely on the community.

If Atlassian really cares about consistent delivery of SEN, you should fix the underlying race condition problem, not move that problem to the partners.

3 Likes
8

@HanjooSong is the ACS impacted?

9

I wonder why there are no changes in endpoint documentation? It’s easy to miss important changes such as this using only API docs.

2 Likes
10

@cmacneill I am calling the endpoint, but the new fields are nowhere to be seen

"license": {
        "active": true,
        "type": "COMMERCIAL",
        "evaluation": false,
        "supportEntitlementNumber": "SEN-1234567"
    },

is what I get.
Any idea?

11

It is rolled out for Jira and is being progressively rolled out now for Confluence. I should be complete within a week.

12

8d days later in Confluence still only supportEntitlementNumber and no entitlementId or entitlementNumber

13

Now entitlementId and entitlementNumber are there also for the Confluence instance I have tried.
The communication on this topic could be improved 
 and as Sergei pointed out the endpoint documentation isn’t updated

2 Likes
14

I did a progressive rollout which completed yesterday.

I will take care of the documentation - thanks.

1 Like
15

And thank you for doing so :handshake:

What I meant is that the “communication” - i.e. the message that started this thread - does not convey that, it just states

will be available from: Jan 04, 2022

So the progressive rollout isn’t obvious here.
Consider you would have written ‘we will start the progressive rollout in early January and expect to complete it end of February’ - at least my expectation would have been very different. Or - if the timeline wasn’t clear - the ‘we will start the progressive rollout in early January’ might have been followed with ‘and will update this thread with progress information’.
Thanks for considering and also thanks for replying so promptly to my questions, Chris

1 Like
16

@cmacneill can you update the Connect descriptor documentation to reflect the changes to the payload? It currently still lists serviceEntitlementNumber

https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/

2 Likes
17

The serviceEntitlementNumber will continue to be present in the install payload for the deprecation period. It is scheduled to be removed on June 30th.

18

I hope you will not be offended by this little whispered reminder from the irritating vendor in the corner.

19

All good @david.pinn - I will get to it.

1 Like
20

What’s the difference in purpose between entitlementId and entitlementNumber?