One final try on giving feedback with regard to App Access

General
,
1

Hi @JustinThirkell / @AngelinaIgnatova,

I’m going to try and give one more shot at conveying my concerns with regard to the App Access implementation. I would have loved to be able to discuss it during a Q&A session at AtlasCamp Copenhagen, but unfortunately your presentation did not include that.

I have talked about Atlassian inconsistency from an Atlassian Marketplace Partner perspective before in the multiple RFCs with regard to App Access. That inconsistency does not only include introducing new formats or libraries (like CloudEvents), it also applies more broadly.

Throughout the years, concepts have come and gone, but the one concept that has been persistently used within Atlassian (for better or worse) is the concept of Projects / Issues in Jira and Spaces / Pages in Confluence.

As part of the App Access project, your team has taken it upon herself to create a new structuring of Atlassian products, introducing more abstract terms as Organisation, Workspace, Container and Object. These new terms are obviously not engrained within the rest of Atlassian, meaning that we won’t be seeing them in any of the other developer resources, nor will they be represented in any of the other API’s (except for specific App Access endpoints and web hooks).

You have taken this so far that even the web hook data itself is going to be ambiguous. If we look at the example you have given in the RFC:

{
  "specversion": "1.0",
  "type": "avi:ecosystem.app_policy:blocked:app_access_to_objects_in_container.v1",
  "source": "com.atlassian/ecosystem.app_policy",
  "id": "7a6796c0-746d-4504-92cd-819eca234306",
  "time": "2023-10-24T08:08:08Z",
  "data": {
    "site": { 
      "url": "https://site_name.atlassian.net"
    },
    "blockedContainer": "12345"
  }
}

You will see that there is no reference here to the host project. It has been completely abstracted away from the actual data you are sending. The only way to infer whether this is Jira and not Confluence is because the site URL does not contain the /wiki suffix. As a developer, we just need to guess that container in this event refers to a Project.

Fun side-note: even this event example is not consistent with the new terminology. The event is still referring to site even though based on the slides shown at AtlasCamp, shouldn’t this be workspace instead? And why is it called blockedContainer and not just container?

The App Access team is so disconnected from the Atlassian Ecosystem that you are not only introducing new technologies, you are also silently rewriting established terminology without there being any indication that this is going to be adopted by Atlassian as a whole.

I sincerely wish to implore that you either reconsider, or take it upon yourself to be the change you seek and make sure to implement these newly introduced technologies and terminologies within the entire Atlassian organisation.

17 Likes
2

Hi Remie,

I would have loved to be able to discuss it during a Q&A session at AtlasCamp Copenhagen, but unfortunately your presentation did not include that.

Indeed, we had already needed to bump someone else out and ask for a double speaking slot as there was a lot to cover, and so we did take the entire timeslot just for the presentation.

I am truly sorry we did not have the chance to meet in person as that would have been a lot better than async communication - I was certainly hoping that we would have an opportunity to discuss App Access Rules in person with you at some point during the week. I did look out for you each day after Monday and in the Atlas Camp slack but only discovered later in the week that you had needed to return home (for good reason I hear :slight_smile:) - if I had known you wouldn’t be there after the first day I would have ensured we connected then. So the fact we didn’t discuss App Access Rules in person was not because we were trying to avoid it - in fact the very opposite! :sweat_smile:

I’ve had covid the past few days and I’m off on annual leave from today (it’s summer holidays down here) but I’ll try and set up a zoom catchup in the new year in lieu of connecting at Atlas Camp.

introducing new formats or libraries (like CloudEvents)

It seems you may be misunderstanding what we have said to date. To recap; The encoding of events as json has not changed. There is no new library requirement to handle events. And as far as I am aware there is no existing event envelope standard defined, let alone evolving to a new format.

Developers can use exactly the same process they do today to write code that handles and processes these new events. And you can completely (please do) ignore CloudEvents - perhaps just consider it coincidental these events happen to include the same attribute names as those defined in the CloudEvents specification.

Where we are introducing a new format is in the way we represent event schema. I have not been able to find any existing machine-readable event schema on developer.atlassian.com. So the use of AsyncAPI is a first effort to provide the same kind of contract-first development available for web APIs to event-driven architecture as well - you should be able to use this new format to create client-side stubs and dynamic mocks for events.

abstract terms as Organisation, Workspace, Container and Object…. are obviously not engrained within the rest of Atlassian, meaning that we won’t be seeing them in any of the other developer resources, nor will they be represented in any of the other API’s (except for specific App Access endpoints and web hooks).

It is inevitable as further non-product-specific platform capabilities are built (and in some cases exposed via APIs) that you will see these terms used more often - if we made public the APIs used to configure Data Security Policies (of which App Access Rules is only one of several policy rule types) you would find those APIs also use the same terminology. Use of these abstract terms rather than the product nomenclature you are more familiar with is a natural consequence of the introduction of platform capabilities that must work across multiple products.

There are clearly new concepts, resources, and data elements in the API. The abstractions help keep the API simpler with fewer elements and lower coupling to products. In DDD terms we could say that Data Security Policies are a new subdomain, with a new bounded context to match. And by definition, a new bounded context means the appearance of new language.

[referencing the example event:] there is no reference here to the host project. It has been completely abstracted away from the actual data you are sending. The only way to infer whether this is Jira and not Confluence is because the site URL does not contain the /wiki suffix. As a developer, we just need to guess that container in this event refers to a Project.

If an app is installed for a single product is any inference actually required? For example, won’t an app installed for Jira know of containers that can only be projects…? I can see your point though in it being a problem for apps that work across both Jira and Confluence. :+1:

Regardless, this event schema was a late addition and I think your argument might make sense - if developers to have to infer anything that’s usually a problem, so we may have missed something here. Thanks, we’ll look to clarify and fix that up.

While we are trying to anticipate the use cases as best we can, learning how developers actually intend to use these events is most useful - can you describe your use case please and why you need the host project? That will help us design the right event shape and attribute names.
And do you have any suggestion yourself for what event attribute(s) would fix this up and remove the ambiguity?

why is it called blockedContainer and not just container?

Probably because I was thinking about how an event handler would be implemented. Given a method signature of handle(SomeEventType e){}, when writing code in the middle of the method it can be helpful to have the semantics made explicit as part of the property name. It’s then clear in-place that the property being accessed refers to a blocked container and not just any container. It could be the other way :man_shrugging:, just a matter of API design (art not science right?! :grinning:).

If you have reasoning why container is a materially better attribute name please let us know - we’re happy to consider proposed alternatives.

The event is still referring to site even though based on the slides shown at AtlasCamp, shouldn’t this be workspace instead?

Yes, I think you’re right here - good catch thanks. We’ll look to fix this up. :+1:

introducing new technologies

For App Access Rules we are providing new events using existing encoding and transports, and new RESTful web APIs resources, also using existing HTTP protocols. Can you elaborate on which new technologies you are thinking of here?

Finally, thanks for your feedback about those event properties - that’s really helpful.

And one question I have for you! I am really curious to know how app developers develop implementations for the events they receive via webhooks.
I know there are textual descriptions of event payloads (for eg Confluence webhooks) but how do people generate stubs (especially for non-typescript apps) and mocks, etc? Is there any way you have come up with other than manually maintaining event stubs direct from the textual documentation? I’d love to know. :smile:

cheers, Justin

5 Likes