Tutorial: Notify users about major updates

One of the biggest problems with the current app versioning system is that customers often stay on old versions because admins don’t update apps manually when new major updates are available.

I found a way to notify users about major updates that you can use until Atlassian ships improvements to the versioning system.

Prerequisites

  • The app must use the native Node.js runtime.
  • You need an API token for testing.
  • This method doesn’t need additional scopes or egress permissions.

Getting the current version

The getAppContext function returns an object that includes the environment and the app version under which a Forge function is executed:

import { getAppContext } from "@forge/api";

const context = getAppContext();
console.log(context.environmentType); // e.g., "PRODUCTION"
console.log(context.appVersion); // e.g., "2.1.0"

Getting the latest version

To find out if the current version differs from the latest deployed version, you can fetch the latest version using the GraphQL API:

query App {
  app(id: "ari:cloud:ecosystem::app/<YOUR_APP_ID>") {
    environments {
      type # e.g., "PRODUCTION"
      versions(first: 1) { # We only need the latest version.
        nodes {
          version # e.g., "3.0.0"
        }
      }
    }
  }
}

To make the request, use the native Node.js fetch function:

const response = await fetch("https://api.atlassian.com/graphql", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query // This is the query string from above.
  })
});

It’s important that you don’t use the api.[asUser|asApp]().requestGraph function to make this request because it uses an authentication method that’s not supported by this part of the GraphQL schema. Luckily, the GraphQL API returns details about the production environment of your app without authentication if the app is published on the Marketplace. For example:

{
  "data": {
    "app": {
      "environments": [
        {
          "type": "PRODUCTION",
          "versions": { "nodes": [{ "version": "3.0.0" }] }
        }
      ]
    }
  }
}

To use the query in a development or staging environment or for an app that is not on the Marketplace, you can add an Authorization header to the request:

const response = await fetch("https://api.atlassian.com/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Basic <BASE64_EMAIL_AND_TOKEN>"
  },
  body: JSON.stringify({
    query // This is the query string from above.
  })
});

Finally, you can compare the version from the app context with the latest version for the respective environment and show a message in your front end if users need to update manually. :tada:

21 Likes