The Adaptavist Group LogoDocumentation

Work with Application Links

HAPI provides a simpler method of working with other Atlassian products that have been connected via Application Links (app link).

HAPI is optimized for the most common integration solutions, such as making requests over an app link configured with OAuth (with impersonation) authentication.

The steps to making a request over an app link are:

  1. Select the app link.

    For example ApplicationLinks.primaryJiraLink, or ApplicationLinks.getByName('Dogfood Jira')

  2. Execute a request using the extension method com.adaptavist.hapi.jira.extensions.ApplicationLinkExtensions#executeRequest

Working with Confluence

Create a page and add an attachment to the page

In the following example, we're using the Confluence REST API to create a page and then add an attachment to that page.

Tip: To find the key for your Confluence space, go to Space tools > Overview.
Use the following script:
import static com.atlassian.sal.api.net.Request.MethodType.POST
import com.atlassian.sal.api.net.RequestFilePart

def confluenceLink = ApplicationLinks.primaryConfluenceLink
def pageResponse = confluenceLink.executeRequest(POST, 'rest/api/content') {
    setHeader('Content-Type', 'application/json')
    setEntity([
            type : 'page',
            title: 'new page',
            space: [
                    key: 'AAA'
            ],
            body : [
                    storage: [
                            value         : "<p>This is <br/> a new page</p>",
                            representation: "storage"
                    ]
            ]
    ])
} as Map

def pageId = pageResponse.id

def filePart = new RequestFilePart(new File('/path/to/screenshot.png'), 'file')
confluenceLink.executeRequest(POST, "rest/api/content/${pageId}/child/attachment") {
    addHeader("X-Atlassian-Token", "no-check")
    setFiles([filePart])
}

Create a page for every subtask of a Jira issue and add a label

  1. Run the following script in the Script Console to create a page with labels for Jira issues:
    import static com.atlassian.sal.api.net.Request.MethodType.GET

def spaceToCreatePagesIn = 'HT'
def issueKey = 'HAPI-1'

def subTasks = ApplicationLinks.primaryJiraLink.executeRequest(GET, "/rest/api/2/issue/$issueKey/subtask") as List<Map<String,String>>

subTasks.each {
    Pages.create(spaceToCreatePagesIn, "${it.key} - ${it.fields.summary}") {
        setLabels("hapi")
    }
}

    After you run the script and open the space, you'll see a page with labels created for each sub-task on the issue that you assigned in the script:

    The Jira task and subtasks are untouched and appear like this:

  2. You can customize the Confluence space, the Jira issue key, and the label of this script:
    import static com.atlassian.sal.api.net.Request.MethodType.GET

def spaceToCreatePagesIn = 'SPACEKEY'
def issueKey = 'ISSUEKEY'

def subTasks = ApplicationLinks.primaryJiraLink.executeRequest(GET, "/rest/api/2/issue/$issueKey/subtask") as List<Map<String,String>>

subTasks.each {
    Pages.create(spaceToCreatePagesIn, "${it.key} - ${it.fields.summary}") {
        setLabels("LABEL")
    }
}

Working with Jira

In the following example, make a request to get the current user via the primary Jira app link. The primary Jira app link is the Jira application link that is marked with PRIMARY when you're on the Application Links page.

import static com.atlassian.sal.api.net.Request.MethodType.GET
            
def result = ApplicationLinks.primaryJiraLink.executeRequest(GET, '/rest/auth/1/session') as Map 
            
def userName = result.name

The result is coerced to a map, list, or whatever is appropriate. If you request XML, you will be returned a groovy.util.slurpersupport.GPathResult .

Making requests as a different user

You can make the request as a different user by utilizing Users.runAs. For example:

import static com.atlassian.sal.api.net.Request.MethodType.GET

def result = Users.runAs('anuser') {
    ApplicationLinks.primaryJiraLink.executeRequest(GET, '/rest/auth/1/session') as Map
}

assert result.name == 'anuser'

Making a POST request

You can make a post request as well as GET requests (as we have done previously). To make a POST request set the Content-Type header, typically to application/json, and provide a Map or List to setEntity, this converts to JSON automatically. In the following example, we're making a POST request and creating an issue in the connected Jira instance.

Note: See the documentation for Creating an Issue.
import static com.atlassian.sal.api.net.Request.MethodType.POST

def result = ApplicationLinks.primaryJiraLink.executeRequest(POST, '/rest/api/2/issue') {
    setHeader('Content-Type', 'application/json')
    setEntity([
            fields: [
                    project  : [
                            key: 'SR',
                    ],
                    summary  : 'Help me!',
                    issuetype: [
                            name: 'Task'
                    ]
            ]
    ])
} as Map

def issueKey = result.key

Creating attachments in Jira

In the following example, we're creating an attachment for a specific issue in the connected Jira instance.

import static com.atlassian.sal.api.net.Request.MethodType.POST
import com.atlassian.sal.api.net.RequestFilePart

// note the 'file' string as the second argument is important, and should not be anything other than 'file'
def filePart = new RequestFilePart(new File('/path/to/screenshot.png'), 'file')

def issueKey = 'SR-100'
ApplicationLinks.primaryJiraLink.executeRequest(POST, "/rest/api/2/issue/${issueKey}/attachments") {
    addHeader("X-Atlassian-Token", "no-check")

    setFiles([filePart])
}

Handling errors

If a request is not successful (that is, a response status code greater than 400 or less than 200), an exception is thrown. The response body will be parsed into a map or whatever is appropriate. In the following example, not all mandatory fields have been entered for creating an issue.

import static com.atlassian.sal.api.net.Request.MethodType.POST
import com.adaptavist.hapi.platform.applinks.exceptions.AppLinkResponseException

try {
    def result = ApplicationLinks.primaryJiraLink.executeRequest(POST, '/rest/api/2/issue') {
        setHeader('Content-Type', 'application/json')
        setEntity([
                fields: [
                        // note: project is missing
                        summary  : 'Help me!',
                        issuetype: [
                                name: 'Task'
                        ]
                ]
        ])
    } as Map
} catch (AppLinkResponseException e) {
    assert (e.entity as Map<String, Map>).errors.project == 'project is required'

    assert e.response.statusCode == 500
}

You also have access to the Response object through the exception, as shown.

Search documentation

Start typing to search the docs.