REST API Specification – Tasks

Note: In all API calls, replace the values between % and % with your own variable values.

Get Task

Replace %id% with the id of the task that you want to retrieve, %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by authentication process.

  • Description: Retrieve task by id.
  • URL structure: http://zurmo_url/index.php/tasks/task/api/read/%id%
  • Method: GET
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters: None
  • PHP sample
    $authenticationData = login('super','super');
    //Add code to check if user is logged successfully
    
    $id = 1; // Change this with value of task id
    
    $headers = array(
        'Accept: application/json',
        'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
        'ZURMO_TOKEN: ' . $authenticationData['token'],
        'ZURMO_API_REQUEST_TYPE: REST',
    );
    $response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/read/' . $id, 'GET', $headers);
    // Decode json data
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        $task = $response['data'];
        //Do something with task
    }
    else
    {
        // Error, for example if we provided invalid task id
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    Data contains task info.

    {
      "status":"SUCCESS",
      "data":{
        "id":1,
        "createdDateTime":"2012-05-08 10:57:41",
        "modifiedDateTime":"2012-05-08 10:57:41",
        "createdByUser":{
          "id":1,
          "username":"super"
        },
        "modifiedByUser":{
          "id":1,
          "username":"super"
        },
        "owner":{
          "id":1,
          "username":"super"
        },
        "latestDateTime":"2012-05-08 10:57:41",
        "completedDateTime":"2012-05-08 13:27:41",
        "completed":null,
        "description":"my test description",
        "dueDateTime":"2012-05-08 13:44:21",
        "name":"First Task"
      },
      "message":null,
      "errors":null
    }
    

Delete Task

Replace %id% with the id of task that you want to delete, %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by authentication process.

  • Description: Delete task by id.
  • URL structure: http://zurmo_url/index.php/tasks/task/api/delete/%id%
  • Method: DELETE
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters: None
  • PHP sample
    $id = 1; // Change this value to task id that you want to delete
    $authenticationData = login('super','super');
    //Add code to check if user is logged successfully
    
    $headers = array(
        'Accept: application/json',
        'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
        'ZURMO_TOKEN: ' . $authenticationData['token'],
        'ZURMO_API_REQUEST_TYPE: REST',
    );
    $response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/delete/' . $id, 'DELETE', $headers);
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        // Inform user that task is deleted
    }
    else
    {
        // Error, for example if we provided invalid task id
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    {
      "status":"SUCCESS",
      "data":null,
      "message":null,
      "errors":null
    }
    

Create New Task

Replace %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by authentication process.

  • Description: Create new task
  • URL structure: http://zurmo_url/index.php/tasks/task/api/create/
  • Method: POST
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters:
    $data = Array
    (
        [name] => Check bills
        [dueDateTime] => 2012-05-08 13:47:14
        [completedDateTime] => 2012-05-08 14:03:54
        [completed] => 0
        [description] => Task description
        [modelRelations] => Array
            (
                [activityItems] => Array
                    (
                        [0] => Array
                            (
                                [action] => add
                                [modelId] => 4
                                [modelClassName] => Contact
                            )
                    )
            )
    )
    
  • PHP sample
    $authenticationData = login('super','super');
    //Add code to check if user is logged successfully
    
    $headers = array(
        'Accept: application/json',
        'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
        'ZURMO_TOKEN: ' . $authenticationData['token'],
        'ZURMO_API_REQUEST_TYPE: REST',
    );
    $data = Array
    (
        'name' => 'Check bills',
        'dueDateTime' => '2012-05-08 13:47:14',
        'completedDateTime' => '2012-05-08 14:03:54',
        'completed' => '0',
        'description' => 'Task description',
        // Attach task to contact
        'activityItems' => array(
            array(
                'action' => 'add', 
                'modelId' => $contact->id, // Replace this with contact Id (or account/opportunity id to which you want to attach task)
                'modelClassName' => 'Contact' // Instead 'Contact' you can attach task to 'Account', 'Opportunity'
            ),
         ),
    );
    
    $response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/create/', 'POST', $headers, array('data' => $data));
    $response = json_decode($response, true);
    
    if ($response['status'] == 'SUCCESS')
    {
        $task = $response['data'];
        //Do something with task data
    }
    else
    {
        // Error
        $errors = $response['errors'];
        // Do something with errors, show them to user
    }
    
  • Return:
    {
      "status":"SUCCESS",
      "data":{
        "id":1,
        "createdDateTime":"2012-05-08 10:57:41",
        "modifiedDateTime":"2012-05-08 10:57:41",
        "createdByUser":{
          "id":1,
          "username":"super"
        },
        "modifiedByUser":{
          "id":1,
          "username":"super"
        },
        "owner":{
          "id":1,
          "username":"super"
        },
        "latestDateTime":"2012-05-08 10:57:41",
        "completedDateTime":"2012-05-08 14:03:54",
        "completed":0,
        "description":"Task description",
        "dueDateTime":"2012-05-08 13:47:14",
        "name":"Check bills"
      },
      "message":null,
      "errors":null
    }
    

Update existing task

Replace %id% with the id of the task that you want to update, %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by authentication process.

  • Description: Update existing task by id
  • URL structure: http://zurmo_url/index.php/tasks/task/api/update/%id%
  • Method: PUT
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters:
    All parameters are optional, so you can only provide properties that you want to update.
    For example:

    $data = Array
    (
        [completed] => 1
        [modelRelations] => Array
            (
                [activityItems] => Array
                    (
                        [0] => Array
                            (
                                [action] => add
                                [modelId] => 4
                                [modelClassName] => Contact
                            )
                    )
            )
    )
    
  • PHP sample
    $id = 1; // Change this value to task id that you want to change
    $authenticationData = login('super','super');
    //Add code to check if user is logged successfully
    
    $headers = array(
        'Accept: application/json',
        'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
        'ZURMO_TOKEN: ' . $authenticationData['token'],
        'ZURMO_API_REQUEST_TYPE: REST',
    );
    // Change task status
    $data['completed']                = 1;
    $data['modelRelations'] = array(
        'activityItems' => array(
            array(
                'action' => 'add', // Another option is to delete relationship, and it that case replace 'add' with 'remove'
                'modelId' => $contact->id,
                'modelClassName' => 'Contact'
            ),
        ),
    );
    $response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/update/' . $id, 'PUT', $headers, array('data' => $data));
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        $task = $response['data'];
        //Do something with task data
    }
    else
    {
        // Error, for example if we provided invalid task id
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    Code will return complete updated task info.

    {
      "status":"SUCCESS",
      "data":{
        "id":1,
        "createdDateTime":"2012-05-08 10:57:41",
        "modifiedDateTime":"2012-05-08 10:57:41",
        "createdByUser":{
          "id":1,
          "username":"super"
        },
        "modifiedByUser":{
          "id":1,
          "username":"super"
        },
        "owner":{
          "id":1,
          "username":"super"
        },
        "latestDateTime":"2012-05-08 10:57:41",
        "completedDateTime":"2012-05-08 14:03:54",
        "completed":"1",
        "description":"Task description",
        "dueDateTime":"2012-05-08 13:47:14",
        "name":"Check bills"
      },
      "message":null,
      "errors":null
    }
    

Search tasks

Replace %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by authentication process.

  • Description: Search tasks
  • URL structure: http://zurmo_url/index.php/tasks/task/api/list/filter/%searchFilter%
  • Method: GET
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Query parameters:
    $searchFilter = Array
    (
        [pagination] => Array
            (
                [page] => 1
                [pageSize] => 3
            )
        [search] => Array
            (
                [name] => Check bills
            )
        [sort] => name.desc
    )
    
  • PHP sample
    $authenticationData = login('super','super');
    //Add code to check if user is logged successfully
    
    $headers = array(
        'Accept: application/json',
        'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
        'ZURMO_TOKEN: ' . $authenticationData['token'],
        'ZURMO_API_REQUEST_TYPE: REST',
    );
    $searchParams = array(
        'pagination' => array(
            'page'     => 1,
            'pageSize' => 3,
        ),
        'search' => array(
            'name' => "Check bills",
        ),
        'sort' => 'name.desc',
    );
    // Get first page of results
    $searchParamsQuery = http_build_query($searchParams);
    $response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/list/filter/' . $searchParamsQuery, 'GET', $headers);
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        // Do something with results
        if ($response['data']['totalCount'] > 0)
        {
            foreach ($response['data']['items'] as $item)
            {
            // Print tasks
            }
        }
        else
        {
         // There are no tasks
        }
    }
    else
    {
        $errors = $response['errors'];
        // Do something with errors
    }
    // Now get second page (you might wanted to check if there are results on second page first)
    $searchParams = array(
        'pagination' => array(
            'page'     => 2,
            'pageSize' => 3,
        ),
        'search' => array(
            'name' => 'Check bills',
        ),
        'sort' => 'name.desc',
    );
    // Get second page of results
    $searchParamsQuery = http_build_query($searchParams);
    $response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/list/filter/' . $searchParamsQuery, 'GET', $headers);
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        // Do something with results
        if ($response['data']['totalCount'] > 0)
        {
            foreach ($response['data']['items'] as $item)
            {
            // Print tasks
            }
        }
        else
        {
         // There are no tasks
        }
    }
    else
    {
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    {
      "status":"SUCCESS", 
      "data":{
        "totalCount":"5",
        "currentPage":2,
        "items":[
          {
            "id":3,
            "createdDateTime":"2012-05-08 11:09:58",
            "modifiedDateTime":"2012-05-08 11:09:58",
            "createdByUser":{
              "id":1,
              "username":"super"
            },
            "modifiedByUser":{
              "id":1,
              "username":"super"
            },
            "owner":{
              "id":1,
              "username":"super"
             },
             "latestDateTime":"2012-05-08 11:09:58",
             "completedDateTime":"2012-05-08 13:39:58",
             "completed":null,
             "description":"my test description",
             "dueDateTime":"2012-05-08 13:56:38",
             "name":"First Task"
           },
           {
             "id":7,
             "createdDateTime":"2012-05-08 11:09:59",
             "modifiedDateTime":"2012-05-08 11:09:59",
             "createdByUser":{
               "id":1,
               "username":"super"
             },
             "modifiedByUser":{
               "id":1,
               "username":"super"
             },
             "owner":{
               "id":1,
               "username":"super"
             },
             "latestDateTime":"2012-05-08 11:09:59",
             "completedDateTime":"2012-05-08 13:39:59",
             "completed":null,
             "description":"my test description",
             "dueDateTime":"2012-05-08 13:56:39",
             "name":"Fifth Task"
           }
        ]
      },
      "message":null,
      "errors":null
    }
    

Tasks Dynamic Search

Replace %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by authentication process.

  • Description: Search tasks
  • URL structure: http://zurmo_url/index.php/tasks/task/api/list/filter/
  • Method: GET, POST
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Query parameters:
    $data = Array
    (
        [dynamicSearch] => Array
            (
                [dynamicClauses] => Array
                    (
                        [0] => Array
                            (
                                [attributeIndexOrDerivedType] => owner
                                [structurePosition] => 1
                                [owner] => Array
                                    (
                                        [id] => 3
                                    )
    
                            )
    
                        [1] => Array
                            (
                                [attributeIndexOrDerivedType] => name
                                [structurePosition] => 2
                                [name] => Fi
                            )
    
                        [2] => Array
                            (
                                [attributeIndexOrDerivedType] => name
                                [structurePosition] => 3
                                [name] => Se
                            )
    
                    )
    
                [dynamicStructure] => 1 AND (2 OR 3)
            )
    
        [pagination] => Array
            (
                [page] => 1
                [pageSize] => 2
            )
    
        [sort] => name.asc
    )
    
  • PHP sample
    $authenticationData = login('super','super');
    //Add code to check if user is logged successfully
    
    $headers = array(
        'Accept: application/json',
        'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
        'ZURMO_TOKEN: ' . $authenticationData['token'],
        'ZURMO_API_REQUEST_TYPE: REST',
    );
    $data = array(
        'dynamicSearch' => array(
            'dynamicClauses' => array(
            array(
                'attributeIndexOrDerivedType' => 'owner',
                'structurePosition' => 1,
                'owner' => array(
                    'id' => Yii::app()->user->userModel->id,
                ),
            ),
            array(
                'attributeIndexOrDerivedType' => 'name',
                'structurePosition' => 2,
                'name' => 'Fi',
            ),
            array(
                'attributeIndexOrDerivedType' => 'name',
                'structurePosition' => 3,
                'name' => 'Se',
            ),
            ),
            'dynamicStructure' => '1 AND (2 OR 3)',
        ),
        'pagination' => array(
            'page'     => 1,
            'pageSize' => 2,
        ),
        'sort' => 'name.asc',
    );
    // Get first page of results
    $response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/list/filter/', 'POST', $headers, array('data' => $data));
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        // Do something with results
        if ($response['data']['totalCount'] > 0)
        {
            foreach ($response['data']['items'] as $item)
            {
            // Print tasks
            }
        }
        else
        {
         // There are no tasks
        }
    }
    else
    {
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    {
      "status":"SUCCESS", 
      "data":{
        "totalCount":"5",
        "currentPage":2,
        "items":[
          {
            "id":3,
            "createdDateTime":"2012-05-08 11:09:58",
            "modifiedDateTime":"2012-05-08 11:09:58",
            "createdByUser":{
              "id":1,
              "username":"super"
            },
            "modifiedByUser":{
              "id":1,
              "username":"super"
            },
            "owner":{
              "id":1,
              "username":"super"
             },
             "latestDateTime":"2012-05-08 11:09:58",
             "completedDateTime":"2012-05-08 13:39:58",
             "completed":null,
             "description":"my test description",
             "dueDateTime":"2012-05-08 13:56:38",
             "name":"First Task"
           },
           {
             "id":7,
             "createdDateTime":"2012-05-08 11:09:59",
             "modifiedDateTime":"2012-05-08 11:09:59",
             "createdByUser":{
               "id":1,
               "username":"super"
             },
             "modifiedByUser":{
               "id":1,
               "username":"super"
             },
             "owner":{
               "id":1,
               "username":"super"
             },
             "latestDateTime":"2012-05-08 11:09:59",
             "completedDateTime":"2012-05-08 13:39:59",
             "completed":null,
             "description":"my test description",
             "dueDateTime":"2012-05-08 13:56:39",
             "name":"Fifth Task"
           }
        ]
      },
      "message":null,
      "errors":null
    }
    

Tasks Improved Search

Replace %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by authentication process.

  • Description: Search tasks – improved
  • URL structure: http://zurmo_url/index.php/tasks/task/api/search/filter/
  • Method: GET, POST
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Query parameters:
    $data = Array
    (
        [search] => Array
            (
                [modelClassName] => Task
                [searchAttributeData] => Array
                    (
                        [clauses] => Array
                            (
                                [1] => Array
                                    (
                                        [attributeName] => owner
                                        [relatedAttributeName] => id
                                        [operatorType] => equals
                                        [value] => 1
                                    )
    
                                [2] => Array
                                    (
                                        [attributeName] => name
                                        [operatorType] => startsWith
                                        [value] => Fi
                                    )
    
                                [3] => Array
                                    (
                                        [attributeName] => name
                                        [operatorType] => startsWith
                                        [value] => Se
                                    )
    
                            )
    
                        [structure] => 1 AND (2 OR 3)
                    )
    
            )
    
        [pagination] => Array
            (
                [page] => 1
                [pageSize] => 2
            )
    
        [sort] => name asc
    )
    
  • PHP sample
    $authenticationData = login('super','super');
    //Add code to check if user is logged successfully
    
    $headers = array(
        'Accept: application/json',
        'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
        'ZURMO_TOKEN: ' . $authenticationData['token'],
        'ZURMO_API_REQUEST_TYPE: REST',
    );
    $userId = 21;
    $data = array(
      'search' => array(
        'modelClassName' => 'Task',
        'searchAttributeData' => array(
          'clauses' => array(
            1 => array(
              'attributeName'        => 'owner',
              'relatedAttributeName' => 'id',
              'operatorType'         => 'equals',
              'value'                => $userId,
            ),
            2 => array(
              'attributeName'        => 'name',
              'operatorType'         => 'startsWith',
              'value'                => 'Fi'
            ),
            3 => array(
              'attributeName'        => 'name',
              'operatorType'         => 'startsWith',
              'value'                => 'Se'
            ),
          ),
          'structure' => '1 AND (2 OR 3)',
        ),
      ),
      'pagination' => array(
        'page'     => 1,
        'pageSize' => 2,
      ),
      'sort' => 'name asc',
    );
    // Get first page of results
    $response = ApiRestTestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/search/filter/', 'POST', $headers, array('data' => $data));
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        // Do something with results
        if ($response['data']['totalCount'] > 0)
        {
            foreach ($response['data']['items'] as $item)
            {
            // Print tasks
            }
        }
        else
        {
         // There are no tasks
        }
    }
    else
    {
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    {
      "status":"SUCCESS", 
      "data":{
        "totalCount":"5",
        "currentPage":2,
        "items":[
          {
            "id":3,
            "createdDateTime":"2012-05-08 11:09:58",
            "modifiedDateTime":"2012-05-08 11:09:58",
            "createdByUser":{
              "id":1,
              "username":"super"
            },
            "modifiedByUser":{
              "id":1,
              "username":"super"
            },
            "owner":{
              "id":1,
              "username":"super"
             },
             "latestDateTime":"2012-05-08 11:09:58",
             "completedDateTime":"2012-05-08 13:39:58",
             "completed":null,
             "description":"my test description",
             "dueDateTime":"2012-05-08 13:56:38",
             "name":"First Task"
           },
           {
             "id":7,
             "createdDateTime":"2012-05-08 11:09:59",
             "modifiedDateTime":"2012-05-08 11:09:59",
             "createdByUser":{
               "id":1,
               "username":"super"
             },
             "modifiedByUser":{
               "id":1,
               "username":"super"
             },
             "owner":{
               "id":1,
               "username":"super"
             },
             "latestDateTime":"2012-05-08 11:09:59",
             "completedDateTime":"2012-05-08 13:39:59",
             "completed":null,
             "description":"my test description",
             "dueDateTime":"2012-05-08 13:56:39",
             "name":"Fifth Task"
           }
        ]
      },
      "message":null,
      "errors":null
    }
    

List TaskAttributes

Replace %sessionId% and %token% with ‘sessionId’ and ‘token’ variables returned by authentication process.

  • Description: List task attributes.
  • URL structure: http://zurmo_url/index.php/tasks/task/api/listAttributes
  • Method: GET
  • HTTP header parameters:
    Accept: application/json
    ZURMO_API_REQUEST_TYPE: REST
    ZURMO_SESSION_ID: %sessionId%
    ZURMO_TOKEN: %token%
  • Parameters: None
  • PHP sample
    $authenticationData = login('super','super');
    //Add code to check if user is logged successfully
    
    $headers = array(
        'Accept: application/json',
        'ZURMO_SESSION_ID: ' . $authenticationData['sessionId'],
        'ZURMO_TOKEN: ' . $authenticationData['token'],
        'ZURMO_API_REQUEST_TYPE: REST',
    );
    $response = ApiRestHelper::createApiCall('http://zurmo_url/index.php/tasks/task/api/listAttributes', 'GET', $headers);
    // Decode json data
    $response = json_decode($response, true);
    if ($response['status'] == 'SUCCESS')
    {
        $taskAttributes = $response['data'];
        //Do something with task attributes
    }
    else
    {
        // Error
        $errors = $response['errors'];
        // Do something with errors
    }
    
  • Return:
    Data contains task attributes info.

Leave a Comment