task #7269
Updated by Andreas Kohlbecker about 6 years ago
The Redmine issue system will be used to establish asynchronous communication between *curator* and *submitters*, which are also referred to as **contributors**.
## Setup
Backups of the initial Redmine setup are found in `Y:/GRUPPEN/BDI/Algenregistrierung/Registrierungs-Redmine`
## Workflow
* All messages are stored in redmine.
* For each registration entity an issue is created in redmine, when ever a message needs to be passed to submitter or curator
* The `User` for the contributor is being created as long as it does not exist in redmine.
* Email-Notification in user account settings:
* Curator: `mail_notification: all`
* Submitter: `mail_notification: only_my_events`
* A comment to the issue will be created for each message, the user which is sending the message will become watcher of the issue.
* The user to which the message is dedicated to will be set as *Assignee* and the priority is set to **active**
* Once the Submitter has taken action in response of the message send by the curator, the issue should be returned to the curator by adding a comment, setting the curator as assignee.
* The status of the issue is synchronized with the `Registration.status`
* Setting the status to ready, published, or rejected will set the issue priority to **inactive**
* Submitter and Contributor will become watchers of the issue so that both can receive email notifications when a new message is posted.
**Message indicators in the registration UI:**
The message indicator shows a new message when `priority_id > 1` :
* Submitter: `Submitter_id == Assignee_id && priority_id > 1`
* Curator: `Submitter_id != Assignee_id && priority_id > 1'
## Redmine REST api
Redmine has a REST api for basic CRUD operations (https://www.redmine.org/projects/redmine/wiki/Rest_api).
* Authentication can be done using an API-key passed in as a "X-Redmine-API-Key" HTTP header (added in Redmine 1.1.0)
* The API key is provided per user and can be retrieved from the "My account" page: `./my/account`
* All operations can be done by an admin user on behalf of an ordinary user by using the HTTP header (X-Redmine-Switch-User: jsmith). This only works when using the API with an administrator account!
[Redmine Java API library](https://github.com/taskadapter/redmine-java-api) is a FREE third-party Java library that can be used to access the Redmine API. It is released under Apache 2 open-source license. (support until Redmine 2.6.0 using REST API), see https://www.redmine.org/projects/redmine/wiki/Rest_api_with_java
~~~
<dependency>
<groupId>com.taskadapter</groupId>
<artifactId>redmine-java-api</artifactId>
<version>3.1.0</version>
</dependency>
~~~
For our purpose the Issue and User services are relevant:
**[Users](https://www.redmine.org/projects/redmine/wiki/Rest_Users)**
* Create a user: `POST /users.json`
~~~json
{
"user": {
"login": "jplang",
"firstname": "Jean-Philippe",
"lastname": "Lang",
"mail": "jp_lang@yahoo.fr",
"password": "secret",
"mail_notification": "only_my_events|all"
}
}
~~~
**[Issues](https://www.redmine.org/projects/redmine/wiki/Rest_Issues)**, **[Issue Journals](https://www.redmine.org/projects/redmine/wiki/Rest_IssueJournals)**
* Create an issue: `POST /issues.json`
~~~json
{
"issue": {
"project_id": 1,
"tracker_id": 1,
"subject": "Registration: ${Registration.identifier}",
"description": "",
"priority_id": 1,
"custom_fields":
[
{"value":${Registration.identifier},"id":1},
{"value":${Submitter_id},"id":2}
]
"assigned_to_id": {user_id},
"watcher_user_ids": [1,2,3] /* Array of user ids to add as watchers */
}
}
~~~
* Add comment: `PUT /issues/[id].json`
~~~json
{
"issue": {
"notes": "Fixed in Revision 128"
}
}
~~~
* Change custom field `Unread`: `PUT /issues/[id].json`
~~~json
{
"issue":
{
"custom_fields":
[
{"value":"1","id":4} /* 1 for true or 0 for false */
]
}
}
~~~
* Find an issue by registrationId: `GET /issues.json?cf_1=${Registration.identifier}`
* here cf_1 refers to the custom field with id=1, which is the `Identifier` field
* Does the find also support journals or id a second request needed? `/issues/[id].json?include=journals`
### Ids in redmine.phycobank.org
* Project id = `phycobank-registry`
* Tracker *registration* = 1
* Custom field ids:
* Identifier = 1
* Submitter = 2
* ~~Curator = 3~~ *not needed, neither for managing the message indicator flag in the UI, nor for sending messages per email.*
* ~~Unread = 4~~ *will be handled via the priority field*
* Issue statuses:
* preparation = 1
* curation = 2
* ready = 3
* published = 4
* rejected = 5
* Issue priorities:
* inactive = 1
* active = 2
## Implementation requirements:
**Settings:**
* adminUserApiKey
* redmineURL
* projectId