Info

icon	false

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:

Table of Contents

maxLevel	5
minLevel	5

In this section

Table of Contents

maxLevel	1

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.

Button Hyperlink

title	Submit a support request
type	primary
url	https://chicago.herzum.com/jira/plugins/servlet/desk/portal/44
target	true

Panel

Using Postman

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

Button Hyperlink

title	VIEW INTERACTIVE DOCUMENTATION
type	primary
url	https://documenter.getpostman.com/view/11380402/T1Djmfg7?version=latest

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

HTML

<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":

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

Get Issue Approvals

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

UI Expand

expanded	true
title	Search Issue Approvals

Status
colour Green
title GET
/rest/herzum-hap-services/1.0/api/issueapprovals

UI Expand

title	Parameters

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

UI Expand

expanded	true
title	Requests / Responses

Code

Request

Status


colour	Green
title	200

UI Expand

expanded	true
title	Successful Request

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

Code Block

[
    {
        "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
    }
]

Status


colour	Red
title	400

UI Expand

title	Wrong Approval Name

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

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

Status


colour	Red
title	400

UI Expand

title	Empty Approval Name

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

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

Status


colour	Red
title	400

UI Expand

title	Wrong User Name

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

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

Status


colour	Red
title	400

UI Expand

title	Empty User Name

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

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

Status


colour	Red
title	400

UI Expand

title	Wrong Status

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

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

Status


colour	Red
title	400

UI Expand

title	Empty Status

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

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

Status


colour	Red
title	402

UI Expand

title	Invalid License

Code Block
{ "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.

UI Expand

expanded	true
title	Operate on Issue Approval

Status
colour Blue
title POST
/rest/herzum-hap-services/1.0/api/issueapprovals/{approvalId}/action

UI Expand

title	Parameters

Name

Type

Description

Optionality

approvalId

Path Parameter

The id of the IssueApproval we want to operate

Mandatory

ActionRequest

BodyParameter

Example

Code Block
{ "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

UI Expand

expanded	true
title	Requests / Responses

Code

Request

Status


colour	Green
title	200

UI Expand

expanded	true
title	Successful Request

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

Request

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

Response

Code Block

{
    "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
}

Status

colour	Red
title	400

UI Expand

title	WRONG ACTION

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

Request

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

Response

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

Status

colour	Red
title	400

UI Expand

title	WRONG issueApprovalId

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

Request

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

Response

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

Status

colour	Red
title	404

UI Expand

title	WRONG username

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

Request

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

Response

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

Status

colour	Red
title	403

UI Expand

title	Username and Password mismatch

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

Request

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

Response

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

Status

colour	Red
title	403

UI Expand

title	Username different than loggedin user

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

Request

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

Response

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

Status

colour	Red
title	403

UI Expand

title	Action not allowed or the user does not have permission

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

Request

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

Response

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

Status

colour	Red
title	400

UI Expand

title	Action Required

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

Request

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

Response

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

Status

colour	Red
title	400

UI Expand

title	Password Required by configuration

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

Request

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

Response

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

Status

colour	Red
title	400

UI Expand

title	Username Required by configuration

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

Request

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

Response

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

Status

colour	Red
title	400

UI Expand

title	Comment Required by configuration

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

Request

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

Response

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

Status


colour	Red
title	403

UI Expand

title	Forbidden Action on OWls Issue Approvals

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

Request

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

Response

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

Status


colour	Red
title	403

UI Expand

title	Action disabled by configuration

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

Request

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

Response

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

Status

colour	Red
title	402

UI Expand

title	Invalid License

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

Page tree

Versions Compared

Old Version 3

New Version 4

Key

Overview

Using Postman

Get Issue Approvals

Status
colour Green
title GET
/rest/herzum-hap-services/1.0/api/issueapprovals

Act on Requested Approvals

Status
colour Blue
title POST
/rest/herzum-hap-services/1.0/api/issueapprovals/{approvalId}/action

Page tree

Page History

Versions Compared

Old Version 3

New Version 4

Key

Overview

Using Postman

Get Issue Approvals

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

Act on Requested Approvals

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

Status
colour Green
title GET
/rest/herzum-hap-services/1.0/api/issueapprovals

Status
colour Blue
title POST
/rest/herzum-hap-services/1.0/api/issueapprovals/{approvalId}/action