[JAVA] What I was addicted to with the Redmine REST API

background

This year I had the opportunity to do the following with the Redmine REST API:

• Migration management from Excel to Redmine
• Automatically draft test cases failed in CI regression test to Redmine

Purpose

I've never used the Redmine REST API before, and I learned while implementing it. I would like you to share what you were addicted to and avoid the traps that I was addicted to.

Premise

• I understand java reasonably well
• I have a decent understanding of Redmine's features

environment

Redmine Version

Environment:
  Redmine version                3.4.6.stable

java Version

java version "1.8.0_221"
Java(TM) SE Runtime Environment (build 1.8.0_221-b11)
Java HotSpot(TM) 64-Bit Server VM (build 25.221-b11, mixed mode)

pom.xml

        <dependency>
            <groupId>com.taskadapter</groupId>
            <artifactId>redmine-java-api</artifactId>
            <version>4.0.0.preview.1</version>
        </dependency>

I was addicted to

1. API functions are also limited to the privileges granted to the user

First generate the RedmineManager class to use the Redmine REST API. At this time, we use something called ʻAPI KEY`.

RedmineManager manager = RedmineManagerFactory.createWithApiKey(REDMINE_URL, API_KEY);

This ʻAPI KEY` is given to each Redmine user. At that time, my user privileges were not administrator privileges. Some API methods require Redmine system administrator privileges.

Get all users

    /**
     * Load list of users from the server.
     * <p><strong>This operation requires "Redmine Administrator" permission.</strong>
     * <p>
     * This method calls Redmine with "include = memberships,groups" parameter.
     *
     * @return list of User objects
     * @throws RedmineAuthenticationException invalid or no API access key is used with the server, which
     *                                 requires authorization. Check the constructor arguments.
     * @throws NotFoundException
     * @throws RedmineException
     */
    public List<User> getUsers() throws RedmineException {
        return transport.getObjectsList(User.class, new BasicNameValuePair(
                "include", "memberships,groups"));
    }

If you want to use it flexibly, we recommend that you have system administrator privileges.

2. Requires Transport

It seems to be a concept taken from version 4 or later of redmine-java-api. You can get it from the RedmineManager class.

RedmineManager redmineManager = RedmineManagerFactory.createWithApiKey(REDMINE_URL, API_KEY);
Transport transport = redmineManager.getTransport();

Without Transport, the exception" Transport is not set! "Is thrown when creating / updating tickets. So please set Transport to the instance of ʻIssue` before creating / updating.

Create new ticket

//Set Transport
Issue issue = new Issue(manager.getTransport());
//(Omitted)
issue = issue.create();

Update existing ticket

Issue issue = manager.getIssueManager().getIssueById(fetchedIssue.getTicketId());
//Set Transport
issue.setTransport(manager.getTransport());
//(Omitted)
issue.update();

3. How to use Params

When updating an existing ticket, you may want to get a "ticket that meets these conditions". In that case, "this condition" can be expressed by using Params.

The title of the ticket is"actual.getFileName"Condition that matches

Params().add("set_filter", "1")
        .add("f[]", "subject")
        .add("op[subject]", "=")
        .add("v[subject][]", actual.getFileName());

I was addicted to the following three points.

What is the key value when it is not the title (example: person in charge)?

I couldn't find the document, so I used brute force to identify it. If you set the desired conditions in the ticket list filter, the filter conditions will be displayed as URL parameters. You can determine the value of the key by decoding the parameters.

What if it does not match (eg, does not match, includes)?

Analyze by the above method.

I want to get all the tickets, so if I get them without any conditions, I can only get 500 tickets

The current situation is unknown. If anyone knows how to do this, please let me know.

4. Clear once when updating custom fields of existing tickets

Get the custom field of the existing ticket once and update the value. After that, I had to clearCustomFields and then add the custom fields of the existing ticket to update it successfully.

//This process gets the custom field from the existing ticket, updates it, and returns it.
Collection<CustomField> customFieldCollection = setEachCustomField(issue, fetchedIssue);
issue.clearCustomFields();
issue.addCustomFields(customFieldCollection);

5. Format when setting values for custom date fields

yyyy-MM-dd is an option. Otherwise, you will get a parse error.

Above (I will add it when I come up with it.)

reference

• What is Redmine
• Redmine REST API