new CollabAPI($rootScope, $http)

Warning! The SmartFlo™ APIs assume 2 global variables are set in $rootScope prior to using the APIs:

  1. $rootScope.credential
  2. set implicitely by the AuthAPI class upon success of the authenticate method
  3. $rootScope.site
  4. set by the calling application to the
    domain (e.g., www.smartflo.biz) or IP address of the target SmartFlo™ system, possibly when initializing the module that declares an API service

Example

//
// Warning! The global '$rootScope.site' field value must be set 
// to the target SmartFlo™ domain prior to using theSmartFlo™ APIs. In this 
// example it is set by the configuration block of the 'sfcollaboration' 
// module.
//
angular.module('sfcollaboration', [])
     // inject API as a service
     .service('SFcollaborationApi', ['$rootScope', '$http', CollabAPI])
     .controller('SFcollaborationsListCtrl', CollaborationsReportCtrl);
     .run(function ($rootScope, $location) { 
     // store the site for use by APIs
         $rootScope.site = $location.host();
         if ($location.port !== null & $location.port !== 80) {
         $rootScope.site += ':' + $location.port().toString();
    }
});

Parameters

Name Type Optional Description

$rootScope

object

 

The topmost parent scope in AngularJS.

$http

service

 

The core AngularJS service that facilitates communication with the remote HTTP servers via the browser's XMLHttpRequest object or via JSONP.

Copyright
© Chalex Corp. 2002 - 2017. All rights reserved.
Returns

class A constructor that will be instantiated.

Methods

getAffiliateAndPublicGroups(successHandler[, failureHandler]) → object

Get's all the groups accessible by the user.

Example

function getAffiliateAndPublicGroups() {
     SFcollaborationApi.getAffiliateAndPublicGroups(handleGetAffiliateAndPublicGroups);
}

function handleGetAffiliateAndPublicGroups(result) {
     if ('0' === status) {
         $scope.affiliateGroups = groupData.affiliateGroups;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


var result {
     status: 0,
     statusMessage: "auth.no.errors", 
     api: "auth::post::users::passwords", // name of the call
     date: [Date object providing time call was made],
     affiliateGroups: [list of groups]
};

getCollaborations(params, successHandler[, failureHandler]) → object

Get's a table of the current collaborations for a given job ID and task ID.

Example

function getCollaborations() {
     var params = {
         jobid: $scope.currentTask.job_id,
         taskid: $scope.currentTask.task_id,
         currentonly: true
     };
     SFcollaborationApi.getCollaborations(params, handleGetCollaborations);
}

function handleGetCollaborations(result) {
     if ('0' === status) {
         $scope.collabortionsList = result.collabortionsList;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object that provides the job ID and task ID as well as a flag indicating whether to restrict the query to the current round of collaborations or include all rounds.


var params = {
     jobid: $scope.currentTask.job_id,
     taskid: $scope.currentTask.task_id,
     currentonly: true | false
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


var result {
     status: 0,
     statusMessage: "auth.no.errors", 
     api: "auth::post::users::passwords", // name of the call
     date: [Date object providing time call was made],
     collabortionsList: [list of collaborations]
};

getCurrentCycleAttachments(params, successHandler[, failureHandler]) → object

Retrieves all the attachments currently assigned to a collaboration review task.

Example

function getCurrentCycleAttachments() {
     var params = {
        jobid: $scope.currentTask.job_id,
        taskid: $scope.currentTask.task_id
     };
     SFcollaborationApi.getCurrentCycleAttachments(params, handleGetCurrentCycleAttachments);
}

function handleGetCurrentCycleAttachments(result) {
     if ('0' === status) {
         $scope.currentAttachments = result.currentAttachments;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object that the selected job ID and task ID.


var params = {
     jobid: $scope.currentTask.job_id,
     taskid: $scope.currentTask.task_id
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


var result {
     status: 0,
     statusMessage: "auth.no.errors", 
     api: "auth::post::users::passwords", // name of the call
     date: [Date object providing time call was made],
     currentAttachments: [attachments assigned to the current collaboration round]
};

var attachment {
     affiliate: [SmartFlo™ affiliate to which the attachment belongs],
     accessible_by: [SmartFlo™ user ID or group access control],
     attachment_id: [unique SmartFlo™ ID for attachment],
     creator:SmartFlo™ user ID of user who uploaded the attachment content],
     creation_date: [date and time attachment content was uploaded],
     attachment_approval_status: [one of: 
         attachment.no.status (1)
         attachment.rejected (2)
         attachment.approved (3)
         attachment.pending (4)
         attachment.canceled (5)],
     attachment_approval_status_number: [one of: 1, 2, 3, 4, 5],
     display_name: user edited name given to attachment],
     checked_out_by: [if checked out, the user ID of the user who has checked it out],
     joinId: [full name of job to which the attachment belongs],
     comments: [Array of attachment comments],
     tags: [Array of attachment tags],
     properties: [Array of attachment properties],
     content: [URL to original content],
     content_mime_type:[MIME type of content],   
     content_low_res: [URL to reduced version of content suitable for use as a preview -
             for video content, an flv formated low-res movie, otherwise a reduced 
             image of bitmapped content and pdfs],
     content_preview: [URL to reduced version of content, used only for video files - 
             a still shot image from the video, suitable for use as a static preview],
     content_thumbnail: [URL to a reduced bitmapped image suitable for display as a thumbnail in a content gallery],
     size_in_bytes: [size of original content],
     previewImage: [URL to recommended content to display in web preview of image types - null if video type],
     previewVideo: [URL to recommended content to display in web preview of image types - null if image type],
     unsupportedMIME: [true or false depending upon whether the MIME type is supported in SmartFlo™]
};

getUsersInGroup(params, successHandler[, failureHandler]) → object

Retrieves all the users that belong to a specified group.

Example

function getUsersInGroup() {
     var params = {
         group: $scope.currentAffiliateGroup
     };
     SFcollaborationApi.getUsersInGroup(params, handleGetUsersInGroups);
}

function handleGetUsersInGroup(result) {
     if ('0' === status) {
         $scope.performers = result.performers;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object that provides the name of the group to provide the users.


var params = {
     group: $scope.currentAffiliateGroup
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


var result {
     status: 0,
     statusMessage: "auth.no.errors", 
     api: "auth::post::users::passwords", // name of the call
     date: [Date object providing time call was made],
     performers: [users in the specified group]
};

postCollaboratorTaskCompletion(params, successHandler[, failureHandler]) → object

Completes a Collaborator task, thereby submitting the user's "vote" (as in voter pattern), i.e., input in the form of a comment and a judgement about whether the attachments under review are suitable.

Example

function postCollaboratorTaskCompletion() {
     var params = {
         jobid: $scope.currentTask.job_id,
         taskid: $scope.currentTask.task_id,
         cyclename: $scope.currentCollaborationCycle,
         decision: $scope.reviewDecision,
         comment: comment
     };
     SFcollaborationApi.postCollaboratorTaskCompletion(params, handlePostCollaboratorTaskCompletion);
}

function handlePostCollaboratorTaskCompletion(result) {
     if ('0' === status) {
         $scope.taskStatus = $translate.instant('label.yes');
         $scope.taskCompleted = true;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object that provides the job ID, task ID, cyclename, review decision and comment.


var params = {
     jobid: $scope.currentTask.job_id,
     taskid: $scope.currentTask.task_id,
     cyclename: $scope.currentCollaborationCycle,
     decision: $scope.reviewDecision,
     comment: comment
};

The possible review decisions are:
  • cycle.no.response
  • cycle.accepted
  • cycle.rejected

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


var result {
     status: 0,
     statusMessage: "auth.no.errors", 
     api: "auth::post::users::passwords", // name of the call
     date: [Date object providing time call was made],
};

postCollaboratorTaskCompletion(params, successHandler[, failureHandler]) → object

Completes a Private Collaborator task, thereby submitting the user's "vote" (as in voter pattern), i.e., input in the form of a comment and a judgement about whether the attachments under review are suitable.

Since the task is "private', the reviewer can also upload attachments that can only be viewed by the Monitor Task or Initiator Task and the current reviewer (i.e., not by any other reviewer).

Since the task is "private', the reviewer can also upload attachments that can only be viewed by the Monitor Task or Initiator Task and the current reviewer (i.e., not by any other reviewer).

Example

function postPrivateCollaboratorTaskCompletion() {
     var params = {
         jobid: $scope.currentTask.job_id,
         taskid: $scope.currentTask.task_id,
         cyclename: $scope.currentCollaborationCycle,
         decision: $scope.reviewDecision,
         comment: comment
     };
     SFcollaborationApi.postPrivateCollaboratorTaskCompletion(params, handlePostPrivateCollaboratorTaskCompletion);
}

function handlePostPrivateCollaboratorTaskCompletion(result) {
     if ('0' === status) {
         $scope.taskStatus = $translate.instant('label.yes');
         $scope.taskCompleted = true;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object that provides the job ID, task ID, cyclename, review decision and comment.


var params = {
     jobid: $scope.currentTask.job_id,
     taskid: $scope.currentTask.task_id,
     cyclename: $scope.currentCollaborationCycle,
     decision: $scope.reviewDecision,
     comment: comment
};

The possible review decisions are:
  • cycle.no.response
  • cycle.accepted
  • cycle.rejected

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


var result {
     status: 0,
     statusMessage: "auth.no.errors", 
     api: "auth::post::users::passwords", // name of the call
     date: [Date object providing time call was made],
};

postInitiatorTaskCompletion(params, successHandler[, failureHandler]) → object

Completes a collaboration Initator task and thereby posts a new collaboration cycle using selected users and selected attachments.

A collaboration cycle implements the "voter pattern" whereby a set of 1 or more reviewers (collaborators) comment on a set of documents until a collaboration monitor ends the collaboration.

Example

function postInitiatorTaskCompletion() {
     var params = {
         jobid: $scope.currentTask.job_id,
         taskid: $scope.currentTask.task_id,
         cyclename: cyclename,
         collaborators: collaborators [comma separated list of SmartFlo™ user IDs],
         duedate: $scope.decisionDueDateStr,
         instruction: $scope.reviewInstruction,
         attachmentids: attachmentids [comma separated list of attachment IDs]
     };
     SFcollaborationApi.postInitiatorTaskCompletion(params, handleGetCollaborations);
}

function handlePostInitiatorTaskCompletion(result) {
     if ('0' === status) {
         $scope.taskStatus = $translate.instant('label.yes');
         $scope.taskCompleted = true;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object that provides the job ID, task ID, cyclename, collaborator IDs, due date, instruction and attachment IDs of the attachments to be reviewed.


var params = {
     jobid: $scope.currentTask.job_id,
     taskid: $scope.currentTask.task_id,
     cyclename: cyclename,
     collaborators: collaborators [comma separated list of SmartFlo™ user IDs],
     duedate: $scope.decisionDueDateStr,
     instruction: $scope.reviewInstruction,
     attachmentids: attachmentids [comma separated list of attachment IDs]
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


var result {
     status: 0,
     statusMessage: "auth.no.errors", 
     api: "auth::post::users::passwords", // name of the call
     date: [Date object providing time call was made],
};

postMonitorTaskCompletion(params, successHandler[, failureHandler]) → object

Completes a collaboration Monitor task, thereby ending the current collaboration cycle. Also completes all open Collaborator tasks for the given collaboration.

Example

function postMonitorTaskCompletion() {
     var params = {
         jobid: $scope.currentTask.job_id,
         taskid: $scope.currentTask.task_id,
         routes: routes.length > 0 ? routes : null
     };
     SFcollaborationApi.postMonitorTaskCompletion(params, handlePostMonitorTaskCompletion);
}

function handlePostMonitorTaskCompletion(result) {
     if ('0' === status) {
         $scope.taskStatus = $translate.instant('label.yes');
         $scope.taskCompleted = true;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object that provides the job ID, task ID and routing selections.


var params = {
     jobid: $scope.currentTask.job_id,
     taskid: $scope.currentTask.task_id,
     routes: routes.length > 0 ? routes : null [selection of 
         AND and OR routes defining the tasks that the job will  
         transition to.]
};

successHandler

function()

 

A function that is called back upon success.

failureHandler

function()

Yes

An optional function that is called back upon failure. If none is specified, the success callback is called with failure data. status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


var result {
     status: 0,
     statusMessage: "auth.no.errors", 
     api: "auth::post::users::passwords", // name of the call
     date: [Date object providing time call was made],
};