Use JEMH Public REST API

SINCE 4.1.23

JEMH previously had a public REST API in JEMH 3.x however this has been revised for Jira 9 in JEMH 4.1.x. The public API for JEMH Auditing and Profile management has been revised and is now available in JEMH 4.1.23 +. The following page details the Rest API Methods and their functionality.

REST Basics

Request URL Structure

All of JEMH’s REST end point URLs are prefixed with the Plugin’s name, similar to Jira’s REST API Endpoint URLs i.e. ‘rest/jemh/latest/’. A full REST URL is comprised of the Domain/Plugin/Class/Method path for example:

• https://localhost:2990/jira/rest/jemh/latest/public/profile/list

• Domain {https://localhost:2990/jira} Plugin {rest/jemh/latest} Class {/public/profile} Method {/list}

Authentication

Almost all of JEMH’s REST end points use Basic Authentication and require a username and password to be provided with the request. As many of the functions of JEMH are restricted to Administrators, only users with appropriate permissions are authorised to use JEMH’s public API.

Public Auditing API

Class Path: /api/auditing

getLatest

Method Type: GET

Method Path: /latest

This method is used to retrieve the latest Audit Events and is useful for monitoring Auditing as emails are processed. For more focused Audit Event retrieval the search method is more useful. We by default return 10 Audit Events at a time, and limit to 100 Events to prevent excessively large requests. If more than 100 Audit Events should be retrieved the offset can be used in successive requests to pull more Audit Events in multiple requests.

Example Path: https://localhost:8080/rest/jemh/latest/api/auditing/latest?pageSize=10&offset=0

search

Method Type: POST

Method Path: /search

This method consumes a JSON objectand returns a list of Audit Events that match the parameters defined in the JSON object. This method is useful for retrieving specific Audit Events, for example retrieving all audit events sent form a specific email address.

Example Path: https://localhost:8080/rest/jemh/latest/api/auditing/search

Example Request Body:

This would return the latest 10 Audit Events for all Projects the requesting user was authorised to manage.

Valid Request JSON Object:

The Request must have a valid JSON object provided in the request body. The syntax of this object as well as valid values are listed here:

Required Fields

Each field requires a value, even if that value is an empty string or 0 (for an empty int)

• pageSize

• filteredProjects

• offset

• query

• type

• before

• after

pageSize

Page size is an integer that defines the max number of Audit Events that should be returned in this request. This value is limited to a maximum of 100. For example, a value of 110 would be treated as 100.

filteredProjects

Filtered Projects is a string array of the Project Keys that this request should be scoped to. For example including nothing will allow any project to be returned, however passing a value of [“BLUE”] would only allow Audit Events associated to the Project with the Project Key BLUE.

offset

Offset defines how many of the latest Audit Events should be ignored when building the list of Audit Events. for example if the request would return 10 Audit Events form a list of 20 an offset of 0 would return the latest 10 Audit Events, setting the offset to 10 would result in the latest 10 being ignored and returning the second half of the list of 20.

query and type

The query and type parameters relate to each other and as such have been grouped together here. The type parameter defines which specific field should be queried in relation to an Audit Event. The query therefore must be related to the type of query being made. For example the default type is ID which would query a specific Audit Event based on its id. a Query of “test” would not be valid for a ID type. The following lists the different query types and valid queries that can be used:

before and after

These fields are very similar and thus have been grouped. These fields represent a range of dates that the Audit Event must have been created in in order to be returned by this request. The Request value follows the following pattern: “YYYY-MM-DD” i.e. 2023-08-22 for the 22nd of August 2023.

doReanimate

Method Type: POST

Method Path: /reprocessing/reanimate

This method triggers the reprocessing of a single Audit Event. This can be helpful if an email did not result in the creation of an issue or comment due to a configuration, or permission issue. Once the configuration or permission has been adjusted the email can be re-processed to create a comment/ new issue.

Example Path: https://localhost:8080/rest/jemh/latest/api/auditing/reprocessing/reanimate?id=0

deleteAuditEvent

Method Type: DELETE

Method Path: /delete

This method triggers the deletion of a single Audit Event.

Example Path: https://localhost:8080/rest/jemh/latest/api/auditing/delete?id=0

createTestcase

Method Type: POST

Method Path: /testcase

This method triggers the the creation of a new JEMH Test Case using the email associated to a specified Audit event. This is helpful for testing configuration changes. For more info on Test cases please see:

• https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/2850884

Example Path: https://localhost:8080/rest/jemh/latest/api/auditing/testcase?id=0

getProcessingReport

Method Type: GET

Method Path: /report

This method is used to retrieve the Processing Report of a specific Audit Event. The processing report provides insight on how JEMH Processed an email and is helpful for diagnosing email processing failures.

Example Path: https://localhost:8080/rest/jemh/latest/api/auditing/report?id=0

export

Method Type: GET

Method Path: /export

This method is used to retrieve export the email associated to a specific email address.

Example Path: https://localhost:8080/rest/jemh/latest/api/auditing/export?id=0&processed=false

Public Profile API

Class Path: /public/profile

getList

Method Type: GET

Method Path: /list

This method is used to retrieve a list of JEMH Profiles.

Example Path: https://localhost:8080/rest/jemh/latest/public/profile/list

exportProfile

Method Type: GET

Method Path: /export

This method is used to export a specific Profile which it exports as an XML file. This can be used in tandem with the updateProfileXML method which consumes an XML file

Example Path: https://localhost:8080/rest/jemh/latest/public/profile/export?id=0

deleteProfile

Method Type: DELETE

Method Path: /delete

This method is used to delete a specific Profile

Example Path: https://localhost:8080/rest/jemh/latest/public/profile/delete?id=0

importProfile

Method Type: POST

Method Path: /improt

This method is used to import a valid XML file as a JEMH Profile.

Example Path: https://localhost:8080/rest/jemh/latest/public/profile/import?fixProjects=true&fixCustomFields=true&fixUsers=true&fixIssue=true

updateProfileXML

Method Type: POST

Method Path: /update

This method is used to update an existing JEMH Profile from a valid XML file.

Example Path: https://localhost:8080/rest/jemh/latest/public/profile/update?profileId=0