Add watching and rating controls to server apps

Atlassian product administrators can install apps from the Marketplace website or through the Universal Plugin Manager (UPM). Similarly, they can can watch or rate apps from either location.

You can add features to your app to let users watch or rate it inside your interface.

To create reviews and watch apps from an app, you use the AtlassianMarketplaceUriFactory interface in the UPM API. Behind the scenes, the calls use a REST API presented by UPM on the local Atlassian product instance. In your implementation, therefore, you are assembling URIs and posting them to the UPM API.

Note that the ability to review, rate, and watch apps through the UPM API is available in UPM 2.8 and later. The API checks that 2.8 is installed in the Atlassian instance, along with ensuring other requirements are met. The same requirements apply as rating and watching apps from UPM, that is, the Atlassian product instance must have a valid SEN and the current user must be an administrator with a contact email domain associated with the SEN on MAC.

Create a review

To create a review from your plugin code, follow these steps:

1. Make sure your pom.xml defines the following dependency. If your app includes Atlassian UPM licensing, this dependency may already be present:

   1
   2
   <dependencies>
       ...
       <dependency>
           <groupId>com.atlassian.upm</groupId>
           <artifactId>plugin-license-storage-lib</artifactId>
           <version>${upm.license.compatibility.version}</version>
       </dependency>
       ...
   </dependencies>
   

The upm.license.compatibility.version should be set to 2.8 and later in the POM properties.

1. Import the following package into your source file:

   1
   2
   import com.atlassian.upm.license.storage.lib.AtlassianMarketplaceUriFactory;
   

2. Use the AtlassianMarketplaceUriFactory interface to construct a message based on the user input and post it, as in the following example:  

   1
   2
   ...
   if (uriFactory.canReviewPlugin())
   {
       // make sure review form is only shown when uriFactory.canReviewPlugin() returns true
       ...
       URI reviewUri = uriFactory.getReviewPluginUri(4 /*stars*/, some("This is my review message"));
       PostMethod post = new PostMethod(reviewUri);
       post.setRequestHeader("Content-Type","application/vnd.atl.plugins.available.plugin+json")
       httpClient.execute(post);
       ...
   }
   ...
   

In this case, we've hard-coded the rating value and review text. In your own app, replace these values with user-provided values.

Watch and unwatch an app

Apps can similarly expose UI controls that enable users to watch your app. A user who watches an app receives email notifications when an update to the app is available.

Implementing app watch controls is similar to setting up app ratings. It uses the same interface, AtlassianMarketplaceUriFactory. If you haven't already, follow the steps above to add the required POM dependency and import the appropriate package.

The following sample shows the code for watching and stop watching the app:

1
2
...
if (uriFactory.canWatchPlugin())
{
    // make sure watch link is only shown when uriFactory.canWatchPlugin() returns true
    ...
    // to watch an app
    URI watchUri = uriFactory.getWatchPluginUri();
    PostMethod post = new PostMethod(watchUri);
    post.setRequestHeader("Content-Type","application/vnd.atl.plugins.available.plugin+json")
    httpClient.execute(post);
    ...
 
    // to unwatch an app
    URI unwatchUri = uriFactory.getWatchPluginUri();
    DeleteMethod delete = new DeleteMethod(unwatchUri);
    httpClient.execute(delete);
}
...