Better know a feature: the fightin' postInstallPage

One of my favorite shows, that is sadly not on the air anymore, was The Colbert Report with Steven Colbert. He would do a regular segment called "Better know a District" where Colbert would interview a United States Congressman from one of the 435 congressional districts.

It was a great segment as we would learn a lot about another district that we would most likely have never heard of. These segments either would hurt the congressman politically as it showed how out of touch with reality they were or it showed how down to earth they were and represented their district with humility, as only one could while being interviewed by Steven Colbert.

In the clip below, Colbert interviews Congresswoman Marcia Fudge of Ohio's 11th District (Cleveland, OH), or as Colbert calls it, the fightin' 11th:

Better know a feature

In Developer Relations, I get asked many questions from integrators and I'll occasionally stumble across little features of Atlassian Connect while researching an answer. Today, I bring to you a new blog segment called "Better know a Feature". In this first segment, let's touch on a little known feature called postInstallPage, the FIGHTIN' POSTINSTALLPAGE.

Tell me about the fightin' postInstallPage

In JIRA and Confluence, when an admin installs your add-on into their Cloud instance you may want to walk them through how to use your add-on. One way to do that is to use a Page module called postInstallPage. When you include the postInstallPage in your descriptor a Getting Started button will link to the page specified in both the add-on's entry in Manage Add-ons and from the dialog that the user is shown when they successfully install the add-on.

In your atlassian-connect.json descriptor file, you declare a postInstallPage module:

"modules": {
  "postInstallPage": {
    "key": "better-know-a-feature",
    "name": {
      "value": "Better know a feature"
    },
    "url": "/better-know-a-feature.html"
  }
}

Unlike generalPages or adminPages you can only have one postInstallPage. Which means you can't assign an array of page objects, postInstallPage expects only one object.

After your add-on has been installed the user will get a dialog box with a Getting Started button:

Additionally, a Getting Started button will appear on the Manage Add-on screen for your add-on.

And each of those buttons will take you to a page where you can style and add content to introduce new users to your add-on.

It's a great way to make your add-on user friendly from the start.

Try it out

Feel free to install this add-on yourself. To install:

  1. Copy the url: https://better-know-a-feature-postinstallpage.aerobatic.io/atlassian-connect.json
  2. Go to your Manage Add-ons page in your Cloud Development Environment.
  3. Click on Upload add-on. (Don't see Upload add-on? Make sure to enable Developer Mode)
  4. Paste the url you copied and click Upload.
  5. After you're done, you can uninstall the add-on by clicking the Uninstall button on Manage Add-ons for the Fighting postInstall Page add-on.

You can also check out the source code at https://bitbucket.org/rwhitbeck/better-know-a-feature-postinstallpage.

Know of an interesting feature of Connect? Let me know in the comments below or follow me on Twitter, @RedWolves. For more tips like this follow us @atlassiandev.