API: Add procedure 'getTaskByReference' and add 'reference' parameter for 'createTask/updateTask' methods

app/Api/Task.php

@@ -17,6 +17,11 @@ class Task extends Base
         return $this->taskFinder->getById($task_id);
     }
 
+    public function getTaskByReference($project_id, $reference)
+    {
+        return $this->taskFinder->getByReference($project_id, $reference);
+    }
+
     public function getAllTasks($project_id, $status_id = TaskModel::STATUS_OPEN)
     {
         return $this->taskFinder->getAll($project_id, $status_id);
@@ -50,7 +55,7 @@ class Task extends Base
     public function createTask($title, $project_id, $color_id = '', $column_id = 0, $owner_id = 0, $creator_id = 0,
                                $date_due = '', $description = '', $category_id = 0, $score = 0, $swimlane_id = 0,
                                $recurrence_status = 0, $recurrence_trigger = 0, $recurrence_factor = 0, $recurrence_timeframe = 0,
-                               $recurrence_basedate = 0)
+                               $recurrence_basedate = 0, $reference = '')
     {
         $values = array(
             'title' => $title,
@@ -69,6 +74,7 @@ class Task extends Base
             'recurrence_factor' => $recurrence_factor,
             'recurrence_timeframe' => $recurrence_timeframe,
             'recurrence_basedate' => $recurrence_basedate,
+            'reference' => $reference,
         );
 
         list($valid,) = $this->taskValidator->validateCreation($values);
@@ -79,7 +85,7 @@ class Task extends Base
     public function updateTask($id, $title = null, $project_id = null, $color_id = null, $column_id = null, $owner_id = null,
                                $creator_id = null, $date_due = null, $description = null, $category_id = null, $score = null,
                                $swimlane_id = null, $recurrence_status = null, $recurrence_trigger = null, $recurrence_factor = null,
-                               $recurrence_timeframe = null, $recurrence_basedate = null)
+                               $recurrence_timeframe = null, $recurrence_basedate = null, $reference = null)
     {
         $values = array(
             'id' => $id,
@@ -99,6 +105,7 @@ class Task extends Base
             'recurrence_factor' => $recurrence_factor,
             'recurrence_timeframe' => $recurrence_timeframe,
             'recurrence_basedate' => $recurrence_basedate,
+            'reference' => $reference,
         );
 
         foreach ($values as $key => $value) {

docs/api-json-rpc.markdown

@@ -1916,7 +1916,7 @@ Response example:
 
 ### getTask
 
-- Purpose: **Get task information**
+- Purpose: **Get task by the unique id**
 - Parameters:
     - **task_id** (integer, required)
 - Result on success: **task properties**
@@ -1975,6 +1975,69 @@ Response example:
 }
 ```
 
+### getTaskByReference
+
+- Purpose: **Get task by the external reference**
+- Parameters:
+    - **project_id** (integer, required)
+    - **reference** (string, required)
+- Result on success: **task properties**
+- Result on failure: **null**
+
+Request example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "getTaskByReference",
+    "id": 1992081213,
+    "params": {
+        "project_id": 1,
+        "reference": "TICKET-1234"
+    }
+}
+```
+
+Response example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 1992081213,
+    "result": {
+        "id": "5",
+        "title": "Task with external ticket number",
+        "description": "[Link to my ticket](http:\/\/my-ticketing-system\/1234)",
+        "date_creation": "1434227446",
+        "color_id": "yellow",
+        "project_id": "1",
+        "column_id": "1",
+        "owner_id": "0",
+        "position": "4",
+        "is_active": "1",
+        "date_completed": null,
+        "score": "0",
+        "date_due": "0",
+        "category_id": "0",
+        "creator_id": "0",
+        "date_modification": "1434227446",
+        "reference": "TICKET-1234",
+        "date_started": null,
+        "time_spent": "0",
+        "time_estimated": "0",
+        "swimlane_id": "0",
+        "date_moved": "1434227446",
+        "recurrence_status": "0",
+        "recurrence_trigger": "0",
+        "recurrence_factor": "0",
+        "recurrence_timeframe": "0",
+        "recurrence_basedate": "0",
+        "recurrence_parent": null,
+        "recurrence_child": null
+    }
+}
+```
+
 ### getAllTasks
 
 - Purpose: **Get all available tasks**

tests/functionals/ApiTest.php

@@ -977,4 +977,29 @@ class Api extends PHPUnit_Framework_TestCase
         $files = $this->client->getAllFiles(array('task_id' => 1));
         $this->assertEmpty($files);
     }
+
+    public function testCreateTaskWithReference()
+    {
+        $task = array(
+            'title' => 'Task with external ticket number',
+            'reference' => 'TICKET-1234',
+            'project_id' => 1,
+            'description' => '[Link to my ticket](http://my-ticketing-system/1234)',
+        );
+
+        $task_id = $this->client->createTask($task);
+
+        $this->assertNotFalse($task_id);
+        $this->assertInternalType('int', $task_id);
+        $this->assertTrue($task_id > 0);
+    }
+
+    public function testGetTaskByReference()
+    {
+        $task = $this->client->getTaskByReference(array('project_id' => 1, 'reference' => 'TICKET-1234'));
+
+        $this->assertNotEmpty($task);
+        $this->assertEquals('Task with external ticket number', $task['title']);
+        $this->assertEquals('TICKET-1234', $task['reference']);
+    }
 }