- Created by Antonella Capalbo on Jan 26, 2021
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
Version 1 Next »
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.
You will need to contact your administrator.
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:
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.
GET /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:
| Filter the returned Issue Approvals by status | Optional |
| Code | Request |
|---|---|
200 | 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
}
]
|
400 | 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 | 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 | 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 | http://{{hostname}}/rest/herzum-hap-services/1.0/api/issueapprovals?username=
{
"errorCode": "issueapproval.username.empty",
"errorMessage": "The username cannot be empty",
"status": 400
}
|
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
}
|
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
}
|
402 | {
"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.
POST /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 |
|---|---|
200 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | {
"errorCode": "license.invalid",
"errorMessage": "License is invalid",
"status": 402
}
|
- No labels