Herzum Approval Documentation
Page tree
Skip to end of metadata
Go to start of metadata

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:

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:



(info) 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.


Search Issue Approvals

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


Parameters
NameTypeDescriptionOptionality
appnameQuery ParameterReturn only the Issues Approvals configured with the Approval with name = appnameOptional
usernameQuery ParameterReturn only the Issue Approvals for which the Jira User can actOptional
status

Query Parameter

It can be one of:

  • APPROVED
  • REJECTED
  • PENDING
  • ABSTAINED
Filter the returned Issue Approvals by statusOptional
issuekeyQuery ParameterFilter the returned Issue Approvals by issue keyOptional
issuekeysQuery ParameterFilter the returned Issue Approvals by issue keys in issuekeys setOptional
issueidsQuery ParameterFilter the returned Issue Approvals by issue ids in issueids setOptional
startAtQuery ParameterSelect the returned Issue Approvals starting from the element in position startAt. The first element has position 0Optional
maxResultsQuery ParameterLimit the number of Issue Approvals sectioned to a maximum of maxResults elementsOptional
Requests / Responses
CodeRequest

200

Successful 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
    }
]

200

Successful Request 
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
    }
]

200

Successful Request 
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
    }
]

200

Successful Request 
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
        }
    ]
}

400

Wrong Approval Name 
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
}

400

Empty Approval Name 
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
}

400

Wrong User Name 
http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?username=wronguser   
{
    "errorCode": "issueapproval.user.notfound",
    "errorMessage": "The user does not exists",
    "status": 404
}

400

Empty User Name 
http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?username=      
{
    "errorCode": "issueapproval.username.empty",
    "errorMessage": "The username cannot be empty",
    "status": 400
}

400

Wrong Status 
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
}

400

Empty Status 
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
}

404

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

400

Empty Issue Key 
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
}

404

Wrong Issue Key 
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
}

400

Empty Issue Keys 
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
}

400

Empty Issue Ids 
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
}

404

Wrong Issue Keys and Issue Ids 
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
}

400

Empty Start At 
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
}

404

Wrong Start At 
http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?startAt=WrongStartAt
{
    "errorCode": "invalid.start.at",
    "errorMessage": "startAt parameter is invalid",
    "status": 404
}

400

Empty Max Results 
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
}

404

Wrong Max Results 
http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?maxResults=WrongMaxResults
{
    "errorCode": "invalid.max.results",
    "errorMessage": "maxResults parameter is invalid",
    "status": 404
}

402

Invalid License 
{
	"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.


Operate on Issue Approval

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


Parameters
NameTypeDescriptionOptionality
approvalIdPath ParameterThe id of the IssueApproval we want to operateMandatory
ActionRequestBodyParameter

Example

{
	"action"   : "APPROVE",
	"username" : "username", 
	"password" : "password" ,
	"comment" : "comment"
}
Optional
actionPart of Action RequestIt can be one of APPROVE, REJECT, ABSTAIN, RESETMandatory
usernamePart of Action RequestThe username of the current logged in user

Optional**

It can be required if configured into Approval Configuration

passwordPart of Action RequestThe password of the current logged in user

Optional**

It can be required if configured into Approval Configuration

commentPart of Action RequestThe comment to be set with the approval action

Optional**

It can be required if configured into Approval Configuration

Requests / Responses
CodeRequest

200

Successful 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
}

400

WRONG ACTION 
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
}

400

WRONG issueApprovalId 
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
}

404

WRONG username 
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
}

403

Username and Password mismatch 
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
}

403

Username different than loggedin user 
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
}

403

Action not allowed or the user does not have permission 
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
}

400

Action Required 
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
}

400

Password Required by configuration 
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
}

400

Username Required by configuration 
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
}

400

Comment Required by configuration 
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
}

403

Forbidden Action on OWls Issue Approvals 
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
}

403

Action disabled by configuration 
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
}

402

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



  • No labels