In the previous article we discussed how to install and configure the kbsali-php-redmine library. Today we’ll focus on the methods responsible for creating issues in Redmine project management system.
Let’s start with creating a project to which we’ll later add issues.
$client->api('project')->create(array( 'name' => 'Test project', 'identifier' => 'ID', 'tracker_ids' => array(), ));
Bear in mind that $client variable is an instance of Redmine/Client class containing the following information:
- Redmine address
Once we execute the above code, a new project will appear in Redmine with the project name – “Test project”, and identifier – “ID”.
So we have our project and now we’d like to create an issue with the following settings:
- Issue subject: “New functionality”
- Issue description: “Description of the functionality that is to be added to the project”
- Assignee (e.g. developer who will work on the assignment)
a) Issuer (person ordering the work)
b) Issuer’s phone number
c) Issuer’s email address
- Watchers (e.g. persons who receive notifications on the progress of the work)
Let’s try to write a method, then, that will let us add this issue to the project management system. In order to add an issue to the project we created, we should once again use the instance of the Redmine/Client class, this time expanding it with an “issue” class, since we want to create is an issue. We can do it using “create” method.
$client->api('issue')->create(array( 'project_id' => 'ID', 'subject' => ‘issue subject', 'description' => 'issue description', 'assigned_to_id' => $userId, 'custom_fields' => array( array( 'id' => 2, 'name' => 'issuer', 'value' => $_POST['ISSUER'], ), array( 'id' => 5, 'name' => 'phone', 'value' => $_POST['PHONE'], ), array( 'id' => '8', 'name' => 'email', 'value' => $_POST['EMAIL'], ), ), 'watcher_user_ids' => array(), ));
The first piece of information we should provide is the project ID, then the issue subject and description. Finally, we should assign the issue we’re creating to someone.
Redmine is a very flexible system, so we can also add custom fields, which can be helpful when we want to provide additional information.
In the code presented above, we add the following fields: Issuer, Phone and Email with the data fetched from the form.
'custom_fields' => array( array( 'id' => 2, 'name' => 'issuer', 'value' => $_POST['ISSUER'], ), array( 'id' => 5, 'name' => 'phone', 'value' => $_POST['PHONE'], ), array( 'id' => '8', 'name' => 'email', 'value' => $_POST['EMAIL'], ), ),
The last element that we should add in our example is: ‘watcher_user_ids’ => array() field, where we put the IDs of the users who are to be notified e.g. on the progress of the work.
Well done! We’ve just created our first issue in the project. But what if the scope of our task is so big that we want to divide it into smaller pieces? This is where Redmine child issues function comes in handy.
So let’s assume that we want to add a child issue to the main one.
$client->api('issue')->create(array( 'project_id' => 'ID', 'tracker_id' => 'tracker ID', 'subject' => 'subject’, 'parent_issue_id' => 'parent issue ID', 'estimated_hours' => 'estimated time for completing the assignment', 'description' => 'description of the assignment' ));
The above code enables us to relate the parent issue (created at the beginning) to the newly made child one. As a result we’ll have a tree of issues, which makes issues management much easier.