Documentation notes/questions

English Forum Developers & API App Components
1

Here’s a list of some initial notes and questions as I started going through the Workflow Apps docs.

  • Docs say

An App Server is required for working with Webhooks and Platform UI (UI Hooks).

but the Platform UI link doesn’t go anywhere.

  • In “Workflow Apps Overview”:

You can see the available templates in the Enumerated Values section of response schema.

The only value I see is summary_with_details_v0 - is that the only available template format at the moment?

  • In same section:

The contents of a widget may change, but the overall format stays consistent across apps.

When you say “stays consistent across apps”, it’s maybe a bit unclear - does that really mean “stays consistent across an app”?

  • Here’s a broken link, under “App Form”: See the on_change field in the response to the form metadata request.

  • Under “App Form”, the bottom link should be labeled on submit callback:
    image

  • Similarly, under “App Action” the bottom link should be labeled on action submit callback:
    image

  • Under “Workflow App Authorization”:

Multiple users of Asana will hit the UI Hooks and send requests to the App Server, but the server will likely only have the token for 1 user.

I’m trying to wrap my brain around this point - is it the same concept as webhooks where the webhook is authorized for one user’s account but can receive changes made by any number of users; or is this a fundamentally different concept here that I’m not getting?

  • In “Being Secure”, I think there’s a typo at the end of this sentence:

Additionally, your app should respect the timeliness of requests. Without this, attackers can replay requests to your server after.


  • Under “Deploying” - hey, you mention the #1 and #3 cloud platforms but left out #2 in market share, namely Microsoft Azure (the one I use)! Hey let’s not be anti-Redmond here… :wink:

  • Under “Forms > Get form metadata”, in the 200 Response sample, it looks like the on_submit_callback isn’t the right value:
    image

The same issue is found in “Forms > On change callback”.

3 Likes
2

Thank you Phil! I’ll see how many of these I can clean up ASAP!

1 Like
3

Resolved!

Yeah that’s correct. I was hoping we’d have another one before the Alpha started, but I think that’s all we’re using for now.

I meant “across apps”, as the template is the thing that dictates the format, not the app. Saying “across an app” makes sense here as well.

Resolved!

Resolved!

It basically works like this:
An Asana user installs your app in their domain, where they OAuth with your app if you declared they should (usually this happens when trying to activate your app in a project for the first time). Then, any Asana User can activate your app onto any project in the domain, they may or may not be sent through your OAuth flow during activation (if your app tells them to). Either way, the app will be activated in the project.

Now, whenever any Asana user goes to that project, they will see your app and the UI Hooks will be sent from the user that navigated to tasks in the project. Your app likely doesn’t have tokens for all of these users.

You coulldddd return 400s on unique user’s requests which will prompt them to OAuth with your app, but that’s likely overkill/not what you want.

Reworded!

Haha fair point. I did quite a bit of Azure at previous jobs. :stuck_out_tongue:

Resolved!

(All the changes might take a few minutes to deploy)

4

I’m a little confused I think.

Let’s say this is John; he happens to not have access to Project XYZ.

Let’s say this user is Mary; she installs it in Project XYZ. She then triggers a UI hook to my app on a task in that project.

When my app gets that message, it wants to retrieve details about that task. When it tries, won’t it get an “Unauthorized” error because it’s using John’s OAuth token and he doesn’t have access to that task?

1 Like
5

I think my next response is more concise: Documentation notes/questions - #6 by Ross_Grambo

My understanding is:

  1. John installed your App within the Workspace.
  2. Mary authorized your app within Project XYZ.

Asana is happy because:

  1. John had access to the Workspace.
  2. Mary had access to the Project.

When Bill goes to a Task within Project XYZ, we check that he has permission to see the Task. If he does, we send a request to your app with user=bill (Note that John and Mary are not a part of this as far as Asana is concerned).

The “Authentication” here is just standard visibility within Asana: If the active user can see a task that should have a Platform UI widget, send a request to the app and ask for the widget. Projects determine the “should have a Platform UI widget”.

If John goes to a Task within Project XYZ, even though he doesn’t have access to Project XYZ, he will still see the widget.

Maybe a more concise way to describe this is:

  1. Does the Active User have access to the task?
  2. Does that task live in a project that has your app installed?

Wait then what’s the point of John or Mary’s Authentication?

As far as Asana is concerned, John had access to the Domain and Mary had access to the project, so they have permission to install your app. When John tries to install your app, we might send him through your OAuth flow (if your app wants people to oauth with it). Asana doesn’t care what happens, as long as you return a postMessage.send("success");.

You probably had him OAuth with your app and/or Asana. Those would have given you a token for John. Maybe you sent him to authenticate with GMail for some reason? Maybe you just showed him a picture of a cat! Doesn’t matter! As long as you return “success”, Asana installs the app how John requested.

This same thing is true for Mary.

You still didn’t describe why

The likely scenario is: Imagine you’re writing a connector between Asana and Slack. You want to show the most recently pinned Slack message within the widget.

During OAuth, you’ll need to have John and/or Mary OAuth with Slack. Then, when Bill comes along, you’ll use John or Mary’s Slack Token to get the required information from Slack.

I kind of just word vomited a lot here, so let me know if one of these explanations is more useful than the others and I can consider adding it to the docs.

6

I synced with the Workflow App team, and here’s a hopefully better synopsis:

If a task is in a project with your Workflow App installed, it will display the widget for any user looking at it. Displaying the widget causes a request to be sent to your app directly from the visiting user.

Asana offers Authorization hooks at different times to give your app a chance to get tokens on behalf of some users. These times are:

  • Activating the app within a project
  • Creating an Automation Rule with an action from your app
  • Creating a resource using the Create Resource Form

Here’s a likely scenario:

  • Say your app connects Asana to Slack.
  • User A activates your app for Project A. Your app sends them through the Slack OAuth flow.
  • Next, User B goes to a task within that project. They should see the widget. Your app will need to look up the Slack Token for User A and use that to get the required data for User B’s request.
1 Like
7

Sorry to interfere, but here by postMessage you mean that an app should send a POST request to asana URL with Body containing text “success”, right?

8

Not an HTTP POST request, but a browser postMesage. For example, I have an ASP,NET MVC app; I haven’t implemented actual authentication yet so in my authentication page, I do this to tell Asana my authentication is A-OK:

<script>
    window.onload = function () {
        window.opener.postMessage("success", "https://app.asana.com");
        window.close();
    };
</script>
1 Like
9

I need to clear up the docs. It’s not a HTTP POST request, but a “postMessage”, which is a cross-window browser request.

10

Good point, @Ross_Grambo, my reply wasn’t very clear, either. Sorry @iliaZelenkin. I just edited it.

11

Hi @Ross_Grambo and @Phil_Seeman

Thanks for the clarification. We’ve implemented a POST message but nothing happens. We just see the “Connecting” message.

Screenshot 2021-05-30 at 14.58.09
Screenshot 2021-05-30 at 14.58.091766×1144 71.9 KB

This is the postMessage.

Screenshot 2021-05-30 at 14.58.22
Screenshot 2021-05-30 at 14.58.221468×348 122 KB

Should it have some extra parameters? Maybe, a different URL?

12

Here is the Loom video:
https://www.loom.com/share/95cd96b5cef64c8aabecca2968285746?sharedAppSource=personal_library

13

Hi @iliaZelenkin,

From what I can see, it looks like you’re doing things correctly. I’d say “no” to the extra parameters or other URL, as my app has the exact same thing you’re showing and it works. I think something else is going on.

I’d recommend posting this in the workflow-apps-alpha Slack group; the Asana team working on this feature is more likely to see and respond to it there. (Keeping in mind that Monday is a holiday in the U.S.)

14

Hey @iliaZelenkin !

Sorry for the late reply here. I think the issue is on our side in this case (Ran into something similar with another dev).

I just made a fix and deployed. You should be unblocked during our deploy tomorrow.

1 Like
15

hi @Ross_Grambo , unfortunately, it did not work. I have a question: what URL should be sender of the success message? is it the AUTH one that we specified in the Workflow app application form?

It would be great if you would post full GIST how to go through the AUTH process so we can replace the token and some values and run on our side.

16

@iliaZelenkin, while writing my response here, I found the issue.

The actual check here is against “siteUrl”, which was originally set to www.bitskout.com.
Per my previous comment, I saw that your app’s auth url is ngrok, so I changed your siteUrl to https://bitskout.eu.ngrok.io and thought that would fix it.

Now that I watch your loom again, I noticed that the url changes to api.bitskout.com:8443 before closing, meaning the postMessage is likely coming from here. I can either fix this by deploying a change that sets your site url to the api.bit... url, or you’ll have to make changes that cause the postMessage to come from https://bitskout.eu.ngrok.io instead.

Happy to meet about this if it would help.

1 Like
17

Hi @Ross_Grambo , thanks for coming back so fast. We suspected the URL issue. Please, set our site URL to https://api.bitskout.com:8443, the response will come from it.

1 Like
18

This was merged in today. It should be available tomorrow evening, possibly the next day.

1 Like
19

Thanks, Ross. That fix did the trick. all is working now.