Overview

Herzum Approval exposes its data via REST Application Programming Interfaces (API) which allows you to build your own integrations with the app.

API Capabilities at the moment include:

Search information about approval items filtering by user, status and approval name
Operate on the issue approvals (APPROVE, REJECT, ABSTAIN, RESET)

Authentication

The Approval API relies on the underlying JIRA Authentication mechanism and the following are supported

OAuth
Basic Auth
Cookie Based Authentication

For detailed information about the Authentication mechanisms please refer to Atlassian JIRA Security Documentation

In particular:

In this section

Related Documentation

Here you can find some links to our customer documentation illustrating the effect of these customizations:

Herzum Approval Database

Need support?

We would love to help.

Submit a support request

Using Postman

Postman is a popular tool for working with APIs. We have published a collection for testing and documentation using Postman.

VIEW INTERACTIVE DOCUMENTATION

Download the latest version of Postman from https://www.getpostman.com/ and then click this button to import our collection:

<div class="postman-run-button"
data-postman-action="collection/import"
data-postman-var-1="0465ad55d530bf5df5ab"></div>
<script type="text/javascript">
  (function (p,o,s,t,m,a,n) {
    !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
    !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
      (n = o.createElement("script")),
      (n.id = s+t), (n.async = 1), (n.src = m), n
    ));
  }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
</script>

You are also able to DOWNLOAD THE COLLECTION.

The collection is available from the sidebar under "Collections":

Herzum Approval Documentation > REST API > image2020-5-12_13-4-27.png

The Collection comes with various example requests, that have been set up with Collection specific variables

Herzum Approval Documentation > REST API > image2023-1-20_10-55-7.png

Get Issue Approvals

The following API is for retrieving information about items still hanging into the approval stage.

/rest/herzum-hap-services/1.0/api/issueapprovals

Name	Type	Description	Optionality
appname	Query Parameter	Return only the Issues Approvals configured with the Approval with name = appname	Optional
username	Query Parameter	Return only the Issue Approvals for which the Jira User can act	Optional
status	Query Parameter It can be one of: APPROVED REJECTED PENDING ABSTAINED	Filter the returned Issue Approvals by status	Optional
issuekey	Query Parameter	Filter the returned Issue Approvals by issue key	Optional
issuekeys	Query Parameter	Filter the returned Issue Approvals by issue keys in issuekeys set	Optional
issueids	Query Parameter	Filter the returned Issue Approvals by issue ids in issueids set	Optional
startAt	Query Parameter	Select the returned Issue Approvals starting from the element in position startAt. The first element has position 0	Optional
maxResults	Query Parameter	Limit the number of Issue Approvals sectioned to a maximum of maxResults elements	Optional

Code

Request

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?username=admin&status=PENDING&appname=Tech

[
    {
        "id": 13,
        "issueId": 10600,
        "approvalId": 5,
        "approvalName": "restricted",
        "issueStatus": "10001",
        "approvalStatus": "PENDING",
        "transitionId": "11",
        "transitionName": "To Do",
        "notificationDate": "Not Sent",
        "sourceStatusId": "10001",
        "type": "WORKFLOW",
        "defineCustomApproval": false,
        "awt": false,
        "awtr": false,
        "awtad": false,
        "arn": false,
        "nac": false,
        "rac": false,
        "errorTransit": false,
        "mra": -1,
        "mrr": -1,
        "conditionalRuleId": -1,
        "submittedDate": "08/05/2020 13:40:53",
        "sortSa": 1,
        "sa": false,
        "saad": false,
        "abstainActionStatus": 0,
        "isOptionalApproval": false
    },
    {
        "id": 21,
        "issueId": 10500,
        "approvalId": 1,
        "approvalName": "tech",
        "issueStatus": "10001",
        "approvalStatus": "PENDING",
        "transitionId": "11",
        "transitionName": "To Do",
        "notificationDate": "Not Sent",
        "sourceStatusId": "10001",
        "type": "WORKFLOW",
        "defineCustomApproval": false,
        "awt": false,
        "awtr": false,
        "awtad": false,
        "arn": false,
        "nac": false,
        "rac": false,
        "errorTransit": false,
        "mra": -1,
        "mrr": -1,
        "conditionalRuleId": -1,
        "submittedDate": "11/05/2020 10:09:18",
        "sortSa": 1,
        "sa": false,
        "saad": false,
        "abstainActionStatus": 0,
        "isOptionalApproval": false
    }
]

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?issuekey=TEST-1

[
    {
        "id": 75,
        "issueId": 12305,
        "approvalId": 2,
        "approvalName": "Marco Polo",
        "issueStatus": "1",
        "approvalStatus": "PENDING",
        "transitionId": "11",
        "transitionName": "Start Progress",
        "notificationDate": "Not Sent",
        "sourceStatusId": "1",
        "type": "SINGLE_ISSUE",
        "defineCustomApproval": false,
        "awt": false,
        "awtr": false,
        "awtad": false,
        "arn": false,
        "nac": false,
        "rac": false,
        "errorTransit": false,
        "mra": -1.0,
        "mrr": -1.0,
        "conditionalRuleId": -1,
        "submittedDate": "20/01/2023 09:59:16",
        "sortSa": 1,
        "sa": false,
        "saad": false,
        "abstainActionStatus": 0,
        "isOptionalApproval": false,
        "showAppStatusJsd": false,
        "showAppButtonsJsd": false
    },
    {
        "id": 76,
        "issueId": 12305,
        "approvalId": 3,
        "approvalName": "Roberto Pupo",
        "issueStatus": "1",
        "approvalStatus": "PENDING",
        "transitionId": "111",
        "transitionName": "Stop progress",
        "notificationDate": "Not Sent",
        "sourceStatusId": "3",
        "type": "SINGLE_ISSUE",
        "defineCustomApproval": false,
        "awt": false,
        "awtr": false,
        "awtad": false,
        "arn": false,
        "nac": false,
        "rac": false,
        "errorTransit": false,
        "mra": -1.0,
        "mrr": -1.0,
        "conditionalRuleId": -1,
        "sortSa": 1,
        "sa": false,
        "saad": false,
        "abstainActionStatus": 0,
        "isOptionalApproval": false,
        "showAppStatusJsd": false,
        "showAppButtonsJsd": false
    }
]

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?issuekeys=TEST-1,TEST-2&issueids=12500

[
    {
        "id": 75,
        "issueId": 12305,
        "approvalId": 2,
        "approvalName": "Marco Polo",
        "issueStatus": "1",
        "approvalStatus": "PENDING",
        "transitionId": "11",
        "transitionName": "Start Progress",
        "notificationDate": "Not Sent",
        "sourceStatusId": "1",
        "type": "SINGLE_ISSUE",
        "defineCustomApproval": false,
        "awt": false,
        "awtr": false,
        "awtad": false,
        "arn": false,
        "nac": false,
        "rac": false,
        "errorTransit": false,
        "mra": -1.0,
        "mrr": -1.0,
        "conditionalRuleId": -1,
        "submittedDate": "20/01/2023 09:59:16",
        "sortSa": 1,
        "sa": false,
        "saad": false,
        "abstainActionStatus": 0,
        "isOptionalApproval": false,
        "showAppStatusJsd": false,
        "showAppButtonsJsd": false
    },
    {
        "id": 76,
        "issueId": 12305,
        "approvalId": 3,
        "approvalName": "Roberto Pupo",
        "issueStatus": "1",
        "approvalStatus": "PENDING",
        "transitionId": "111",
        "transitionName": "Stop progress",
        "notificationDate": "Not Sent",
        "sourceStatusId": "3",
        "type": "SINGLE_ISSUE",
        "defineCustomApproval": false,
        "awt": false,
        "awtr": false,
        "awtad": false,
        "arn": false,
        "nac": false,
        "rac": false,
        "errorTransit": false,
        "mra": -1.0,
        "mrr": -1.0,
        "conditionalRuleId": -1,
        "sortSa": 1,
        "sa": false,
        "saad": false,
        "abstainActionStatus": 0,
        "isOptionalApproval": false,
        "showAppStatusJsd": false,
        "showAppButtonsJsd": false
    },
    {
        "id": 77,
        "issueId": 12400,
        "approvalId": 3,
        "approvalName": "Roberto Pupo",
        "issueStatus": "1",
        "approvalStatus": "PENDING",
        "transitionId": "11",
        "transitionName": "Start Progress",
        "notificationDate": "Not Sent",
        "sourceStatusId": "1",
        "type": "WORKFLOW",
        "defineCustomApproval": false,
        "awt": false,
        "awtr": false,
        "awtad": false,
        "arn": false,
        "nac": false,
        "rac": false,
        "errorTransit": false,
        "mra": -1.0,
        "mrr": -1.0,
        "conditionalRuleId": -1,
        "submittedDate": "20/01/2023 10:02:30",
        "sortSa": 1,
        "sa": false,
        "saad": false,
        "abstainActionStatus": 0,
        "isOptionalApproval": false,
        "showAppStatusJsd": false,
        "showAppButtonsJsd": false
    },
    {
        "id": 78,
        "issueId": 12500,
        "approvalId": 3,
        "approvalName": "Roberto Pupo",
        "issueStatus": "1",
        "approvalStatus": "PENDING",
        "transitionId": "11",
        "transitionName": "Start Progress",
        "notificationDate": "Not Sent",
        "sourceStatusId": "1",
        "type": "WORKFLOW",
        "defineCustomApproval": false,
        "awt": false,
        "awtr": false,
        "awtad": false,
        "arn": false,
        "nac": false,
        "rac": false,
        "errorTransit": false,
        "mra": -1.0,
        "mrr": -1.0,
        "conditionalRuleId": -1,
        "submittedDate": "23/01/2023 10:09:38",
        "sortSa": 1,
        "sa": false,
        "saad": false,
        "abstainActionStatus": 0,
        "isOptionalApproval": false,
        "showAppStatusJsd": false,
        "showAppButtonsJsd": false
    }
]

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?issuekeys=TEST-1,TEST-2&issueids=12500&startAt=1&maxResults=1

{
    "startAt": 1,
    "maxResults": 1,
    "total": 4,
    "issueApprovals": [
        {
            "id": 76,
            "issueId": 12305,
            "approvalId": 3,
            "approvalName": "Roberto Pupo",
            "issueStatus": "1",
            "approvalStatus": "PENDING",
            "transitionId": "111",
            "transitionName": "Stop progress",
            "notificationDate": "Not Sent",
            "sourceStatusId": "3",
            "type": "SINGLE_ISSUE",
            "defineCustomApproval": false,
            "awt": false,
            "awtr": false,
            "awtad": false,
            "arn": false,
            "nac": false,
            "rac": false,
            "errorTransit": false,
            "mra": -1.0,
            "mrr": -1.0,
            "conditionalRuleId": -1,
            "sortSa": 1,
            "sa": false,
            "saad": false,
            "abstainActionStatus": 0,
            "isOptionalApproval": false,
            "showAppStatusJsd": false,
            "showAppButtonsJsd": false
        }
    ]
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?appname=wrongappname

{
    "errorCode": "issueapproval.approval.notexist",
    "errorMessage": "The approval referenced by the issueApproval does not exist",
    "status": 404
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?username=admin&status=PENDING&appname=

{
    "errorCode": "issueapproval.appname.empty",
    "errorMessage": "If the paramenter appname is present it cannot be empty ",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?username=wronguser

{
    "errorCode": "issueapproval.user.notfound",
    "errorMessage": "The user does not exists",
    "status": 404
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?username=

{
    "errorCode": "issueapproval.username.empty",
    "errorMessage": "The username cannot be empty",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?status=WRONGSTATUS

{
    "errorCode": "issueapproval.status.notexist",
    "errorMessage": "The specified status does not exist. Use APPROVED, REJECTED, ABSTAINED, PENDING",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?status=

{
    "errorCode": "issueapproval.status.empty",
    "errorMessage": "If the paramenter status is present it cannot be empty ",
    "status": 400
}

{
    "errorCode": "issueapproval.approval.notexist",
    "errorMessage": "The approval referenced by the issueApproval does not exist",
    "status": 404
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?issuekey=

{
    "errorCode": "issue.keys.empty",
    "errorMessage": "If the issuekey parameter is present it cannot be empty",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?issuekey=wrongIssueKey

{
    "errorCode": "issue.notexist.or.noperm",
    "errorMessage": "The issue does not exist or you do not have permission to view it. Invalid issue key set: (wrongIssueKey).",
    "status": 404
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?issuekeys=

{
    "errorCode": "issue.keys.empty",
    "errorMessage": "If the issuekeys parameter is present it cannot be empty",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?issueids=

{
    "errorCode": "issue.ids.empty",
    "errorMessage": "If the issueids parameter is present it cannot be empty",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?issuekeys=wrongIssueKey, wrongIssueKey2&issueids=wrongIssueId, wrongIssueId2

{
       "errorCode": "issues.notexist.or.noperm",
       "errorMessage": "Some issues do not exist or you do not have permission to view them. Invalid issue key set: (wrongIssueKey,wrongIssueKey2). Invalid issue id set: (wrongIssueId,wrongIssueId2).",
       "status": 404
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?startAt=

{
    "errorCode": "start.at.empty",
    "errorMessage": "If the startAt parameter is present it cannot be empty",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?startAt=WrongStartAt

{
    "errorCode": "invalid.start.at",
    "errorMessage": "startAt parameter is invalid",
    "status": 404
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?maxResults=

{
    "errorCode": "max.results.empty",
    "errorMessage": "If the maxResults parameter is present it cannot be empty",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?maxResults=WrongMaxResults

{
    "errorCode": "invalid.max.results",
    "errorMessage": "maxResults parameter is invalid",
    "status": 404
}

{
	"errorCode": "license.invalid",
	"errorMessage": "License is invalid",
	"status": 402
}

Act on Requested Approvals

The following API is for performing operations on the items still hanging into the approval stage.

/rest/herzum-hap-services/1.0/api/issueapprovals/{approvalId}/action

Name

Type

Description

Optionality

approvalId

Path Parameter

The id of the IssueApproval we want to operate

Mandatory

ActionRequest

BodyParameter

Example

{
	"action"   : "APPROVE",
	"username" : "username", 
	"password" : "password" ,
	"comment" : "comment"
}

Optional

action

Part of Action Request

It can be one of APPROVE, REJECT, ABSTAIN, RESET

Mandatory

username

Part of Action Request

The username of the current logged in user

Optional**

It can be required if configured into Approval Configuration

password

Part of Action Request

The password of the current logged in user

Optional**

It can be required if configured into Approval Configuration

comment

Part of Action Request

The comment to be set with the approval action

Optional**

It can be required if configured into Approval Configuration

Code

Request

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"username" : "Name", 
	"password" : "Pwd" ,
	"comment" : "comment"
}

Response

{
    "id": 11,
    "issueId": 10500,
    "approvalId": 3,
    "issueStatus": "10001",
    "approvalStatus": "APPROVED",
    "date": "08/05/2020 15:24:28",
    "approverUser": "admin",
    "transitionId": "21",
    "transitionName": "In Progress",
    "notificationDate": "Not Sent",
    "sourceStatusId": "10001",
    "type": "WORKFLOW",
    "defineCustomApproval": false,
    "awt": false,
    "awtr": false,
    "awtad": false,
    "arn": false,
    "nac": false,
    "rac": false,
    "errorTransit": false,
    "mra": -1,
    "mrr": -1,
    "conditionalRuleId": -1,
    "submittedDate": "08/05/2020 12:43:52",
    "sortSa": 1,
    "sa": false,
    "saad": false,
    "abstainActionStatus": 0,
    "isOptionalApproval": false
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "WRONG",
	"username" : "Name", 
	"password" : "Pwd" ,
	"comment" : "comment"
}

Response

{
    "errorCode": "issueapproval.action.notexist",
    "errorMessage": "The specified action does not exist. Use APPROVE, REJECT, ABSTAIN, RESET",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/214124214/action

Request

{
	"action"   : "APPROVE",
	"username" : "adminName", 
	"password" : "adminPwd" ,
	"comment" : "comment"
}

Response

{
    "errorCode": "issueapproval.notexist",
    "errorMessage": "The specified issueApproval does not exist",
    "status": 404
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"username" : "userdoesnotexist", 
	"password" : "adminPwd" ,
	"comment" : "comment"
}

Response

{
    "errorCode": "issueapproval.user.notfound",
    "errorMessage": "The user does not exists",
    "status": 404
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"username" : "user", 
	"password" : "wrongpwd" ,
	"comment" : "comment"
}

Response

{
    "errorCode": "issueapproval.credentials.wrong",
    "errorMessage": "The username and the password do not match",
    "status": 403
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"username" : "differentusername", 
	"password" : "pwd" ,
	"comment" : "comment"
}

Response

{
    "errorCode": "username.notcorrespond",
    "errorMessage": "The username does not correspond to the loggedin user",
    "status": 403
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"username" : "username", 
	"password" : "pwd" ,
	"comment" : "comment"
}

Response

{
    "errorCode": "issueapproval.action.unauthorized",
    "errorMessage": "The user cannot perform the required action",
    "status": 403
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"username" : "username", 
	"password" : "pwd" ,
	"comment" : "comment"
}

Response

{
    "errorCode": "issueapproval.action.required",
    "errorMessage": "The action parameter is required",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"comment" : "comment"
}

Response

{
    "errorCode": "issueapproval.pwd.required",
    "errorMessage": "The password is required by the General Configuration",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"password"   : "password",
	"comment" : "comment"
}

Response

{
    "errorCode": "issueapproval.username.required",
    "errorMessage": "The username is required by the General Configuration",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"username" : "username", 
	"password" : "pwd"
}

Response

{
    "errorCode": "issueapproval.comment.required",
    "errorMessage": "The comment is set to be required by Configuration",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"username" : "username", 
	"password" : "pwd"
}

Response

{
    "errorCode": "issueapproval.action.owls",
    "errorMessage": "Action on configuration issueApprovals (OWLs) are on allowed",
    "status": 400
}

http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals/11/action

Request

{
	"action"   : "APPROVE",
	"username" : "username", 
	"password" : "pwd"
}

Response

{
    "errorCode": "issueapproval.action.disabled",
    "errorMessage": "The action is disabled by Configuration",
    "status": 403
}

{
	"errorCode": "license.invalid",
	"errorMessage": "License is invalid",
	"status": 402
}