Methods

new JobsAPI($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 'sftasklist' module.'
//
angular.module('sftasklist', [])
     // inject API as a service
     .service('SFjobsApi', ['$rootScope', '$http', JobsAPI]) 
     .controller('SFtasklistCtrl', TaskListCtrl);
     .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

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

Retrieves an array of the previously selected autocompletion tasks (if any) from the backend.

Example

$scope.completeExceptionTask = function () {
     var params = {
         jobid: $scope.currentTask.job_id
     };
     SFjobsApi.postAutoCompletionTasks(params, handlePostAutoCompletionTasks);
};

function handlePostAutoCompletionTasks(result) {
     if ('0' === result.status) {
         if (result.autotasks && angular.isArray(result.autotasks)) {
             SFStorage.saveCurrentAutoTasks(result.autotasks);
         } else {
             SFStorage.saveCurrentAutoTasks([]);
         }
         $location.path('/acchoicetask');
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object providing the selected jobid and the taskid of the task at which the autocompletion task selection was made.


var params = {
     jobid: $scope.currentTask.job_id,
     taskid: task.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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called]
};

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

Retrieve the brands defined in the system for a given affiliate, client company and category. Each affiliate in the system can define a set of company data arranged as a hierarchy of values:


                         Affiliate
                             |
                      Client Companies
             ________________|________________
             |                               |
   Distribution Channels                 Categories
             |                               |
         Products                          Brands
             |
           Parts

Example

$scope.getCategoryBrands = function () {
     var params = {
         client: $scope.client_company.value,
         category: $scope.category.value
     };
     SFjobsApi.getCategoryBrands(params, handleGetCategoryBrands);
};

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

Parameters

Name Type Optional Description

params

object

 

An object providing the selected client company.


var params = {
     client: $scope.client_company.value,
     category: $scope.category.value
};

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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     brandsList: [Array containing the client category values]
};

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

Retrieve the channel products defined in the system for a given affiliate, client company and distribution channel. Each affiliate in the system can define a set of company data arranged as a hierarchy of values:


                         Affiliate
                             |
                      Client Companies
             ________________|________________
             |                               |
   Distribution Channels                 Categories
             |                               |
         Products                          Brands
             |
           Parts

Example

$scope.getChannelProducts = function () {
     var params = {
         client: $scope.client_company.value,
         channel: $scope.distribution_channel.value
     };
     SFjobsApi.getChannelProducts(params, handleGetChannelProducts);
};

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

Parameters

Name Type Optional Description

params

object

 

An object providing the selected client company and distribution channel.


var params = {
     client: $scope.client_company.value,
     channel: $scope.distribution_channel.value
};

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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     productsList: [Array containing the channel product values]
};

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

Retrieve the client categories defined in the system for a given affiliate and client company. Each affiliate in the system can define a set of company data arranged as a hierarchy of values:


                         Affiliate
                             |
                      Client Companies
             ________________|________________
             |                               |
   Distribution Channels                 Categories
             |                               |
         Products                          Brands
             |
           Parts

Example

$scope.getClientCategories = function () {
     var params = {
         client: $scope.client_company.value
     };
     SFjobsApi.getClientCategories(params, handleGetClientCategories);
};

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

Parameters

Name Type Optional Description

params

object

 

An object providing the selected client company.


var params = {
     client: $scope.client_company.value
};

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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     categoriesList: [Array containing the client category values]
};

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

Retrieve the client distribution channels defined in the system for a given affiliate and client company. Each affiliate in the system can define a set of company data arranged as a hierarchy of values:


                         Affiliate
                             |
                      Client Companies
             ________________|________________
             |                               |
   Distribution Channels                 Categories
             |                               |
         Products                          Brands
             |
           Parts

Example

$scope.getClientChannels = function () {
     var params = {
         client: $scope.client_company.value
     };
     SFjobsApi.getClientChannels(params, handleGetClientChannels);
};

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

Parameters

Name Type Optional Description

params

object

 

An object providing the selected client company.


var params = {
     client: $scope.client_company.value
};

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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     channelsList: [Array containing the client channel values]
};

getClientCompanies(successHandler[, failureHandler]) → object

Retrieve the client companies defined in the system. Each affiliate in the system can define a set of company data arranged as a hierarchy of values:


                         Affiliate
                             |
                      Client Companies
             ________________|________________
             |                               |
   Distribution Channels                 Categories
             |                               |
         Products                          Brands
             |
           Parts

Example

$scope.getClientCompanies = function () {
     SFjobsApi.getClientCompanies(handleGetClientCompanies);
};

function handleGetClientCompanies(result) {
     if ('0' === result.status) {
         $scope.clientCompanyList = result.clientCompanyList;
     } 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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     clientCompanyList: [Array containing the client company values]
};

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

Retrieves the distinct task performers (user IDs) of completed tasks for a given job.

Example

$scope.getJobPerformers = function () {
     var params = {
         jobid: $scope.currentTask.job_id
     };
     SFjobsApi.getCompletedTaskPerformers(params, handleGetCompletedTaskPerformers);
};

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

Parameters

Name Type Optional Description

params

object

 

An object providing the selected job.


var params = {
     jobid: $scope.currentTask.job_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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     performers: [array of job performers that have completed tasks]
};

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

Retrieve the extended metadata for a given job.

Example

function getExtendedJobMetadata(jobid) {
     var params = {
         jobid: jobid
     };
     SFjobsApi.getExtendedJobMetadata(params, handleGetExtendedJobMetadata);
}

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

Parameters

Name Type Optional Description

params

object

 

An object providing the job name.


var params = {
     jobid: [full SmartFlo™ name of job]
};

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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     extendedMetadata: [obkject containing the extended metada field values]
};

extendedMetadata { affiliate: [SmartFlo™ affiliate in which job was started - e.g., smartflo], team: [SmartFlo™ team assigned to job - e.g., SmartFlo [smartflo_features_bugs_wp1]], account_name: [], art_due_date: [], creative_agency: [], customer_position: [], file_destination: [], master_artwork_template: [], production_schedule: [], program_classification: [], program_type: [], retail_start_date: [], retail_end_date: [], states_program: [], program_manager_owner: [], program_owner: [], number_of_units: [], prize_logic_owner: [], legal_owner: [], alliance_owner: [] };

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

Retrieve the digital attachments associated with a given job (i.e., its "job bag").

Example

function getJobAttachments() {
     var params = {
         jobid: $scope.currentTask.job_id, // job ID of currently selected task
         taskid: $scope.currentTask.task_id // task ID of currently selected task
     };
     SFjobsApi.getJobAttachments(params, handleGetJobAttachments);
}

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

Parameters

Name Type Optional Description

params

object

 

An object providing jobid and task id of the currently selected task.


var params = {
     jobid: [job ID of currently selected task],
     taskid: [task ID of currently selected task]
};

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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


 result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     currentAttachments: [Array of attachments],
};

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™] };

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

Retrieve a range (or page) of tasks. This may include tasks not assigned to the current user so their display should be guarded by membership in a SmartFlo™ group (e.g., Project Manager or Job Manager).

Example

$scope.datasourceCallback;
function createTasksDatasource() {
     var dataSource = {
         pageSize: $scope.pageSize,
         getRows: function (gridparams) {
             $scope.datasourceCallback = gridparams.successCallback;
             var params = {
                 startrow: gridparams.startRow,
                 pagesize: gridparams.endRow - gridparams.startRow
             };
             SFjobsApi.getJobboardTasks(param, getJobboardTasksHandler);
         }
     };
     $scope.gridOptions.api.setDatasource(dataSource);
}

function getJobboardTasksHandler(result) {
     if ('0' === result.status) {
         $scope.datasourceCallback(result.jobboard, result.totalNumberOfTasks);
         $scope.numTasks = result.totalNumberOfTasks;
         $scope.currentTasks = result.jobboard;
     } else {
         $scope.errorCode = result.status;
         $scope.errorMessage = result.statusMessage;
     }
}

Parameters

Name Type Optional Description

params

object

 

An object providing the start position and page size for the set of tasks returned. In this example, ag-Grid (Copyright © 2017 ag-Grid Ltd, All rights reserved) is used to provide paging.


var params = {
     startrow: gridparams.startRow,
     pagesize: gridparams.endRow - gridparams.startRow
};

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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

See also
getTask for a description of the task data.
Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     totalNumberOfTasks: [the total number of tasks assigned to the user],
     jobboard: [Array holding the current page of task data objects]
};

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

Retrieves the possible job performers (user IDs) originally assigned to a given job and task.

Example

$scope.getJobPerformers = function () {
     var params = {
         jobid: $scope.currentTask.job_id,
         taskid: task.task_id
     };
     SFjobsApi.getJobPerformers(params, handleGetJobPerformers);
};

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

Parameters

Name Type Optional Description

params

object

 

An object providing the selected job and task.


var params = {
     jobid: $scope.currentTask.job_id,
     taskid: task.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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     performers: [array of possible performers]
};

getJobTeams(successHandler[, failureHandler]) → object

Retrieve the resource teams ([name].[workflow definition]) that this user has chosen from those available to this user's affiliate.

Example

$scope.getJobTeams = function () {
     SFjobsApi.getJobTeams(handleGetJobTeams);
};

function handleGetJobTeams(result) {
     if ('0' === result.status) {
         $scope.resourceTeamList = result.resourceTeamList;
     } 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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

Throws

(string) "missing.callback.exception"

$http errors

Returns

object A result object.


result {
     date: [time API call was completed],
     status: ['0' for success, otherwise failure],
     statusMessage: [message indicating reason for status value],
     api: [the API that was called],
     resourceTeamList: [Array containing the SmartFlo™ resource teams]
};

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

Retrieve a range (or page) of tasks. This may include tasks not assigned to the current user so their display should be guarded by membership in a SmartFlo™ group (e.g., Project Manager or Job Manager).

Tries to match specified query terms against various job data fields. Query terms are comma (,) separated.

  • job data
  • brand, category, client_company, distribution_channel, item_description, item_id, product, project_id, task_id, task_name, project_manager, project_name, workflow_id, workflow_definition, resource_group, status

  • extended job metadata
  • account_name, art_due_date, creative_agency, customer_position, file_destination, master_artwork_template, num_of_units, production_schedule, program_owner, team, states_program, program_classification, program_type, legal_owner, alliance_owner, prize_logic_owner, program_manager_owner

    Example

    $scope.datasourceCallback;
    function createTasksDatasource() {
         var dataSource = {
             pageSize: $scope.pageSize,
             getRows: function (gridparams) {
                 $scope.datasourceCallback = gridparams.successCallback;
                 var params = {
                     startrow: gridparams.startRow,
                     pagesize: gridparams.endRow - gridparams.startRow
                 };
                 SFjobsApi.getMatchingJobboardTasks(param, getJobboardTasksHandler);
             }
         };
         $scope.gridOptions.api.setDatasource(dataSource);
    }
    
    function getJobboardTasksHandler(result) {
         if ('0' === result.status) {
             $scope.datasourceCallback(result.jobboard, result.totalNumberOfTasks);
             $scope.numTasks = result.totalNumberOfTasks;
             $scope.currentTasks = result.jobboard;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the query terms, the start position and page size for the set of tasks returned, and a request that the query be expanded or not. In this example, ag-Grid (Copyright © 2017 ag-Grid Ltd, All rights reserved) is used to provide paging.

    
    var params = {
         tomatch: [comma separated list of query terms],
         startrow: gridparams.startRow,
         pagesize: gridparams.endRow - gridparams.startRow,
         expand: [true | false - whether to use terms as elements
         of an "OR" (expand === true) query or an
         "AND" (expand === false) query.
    };

    For non-expanding queries: all running or suspended job tasks in the pan-affiliate group for which one of the target columns matches ALL of the comma separated search terms.

    For expanding queries: all running or suspended job tasks in the pan-affiliate group for which any of the target columns match ANY of the comma separated search terms.

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    See also
    getTask for a description of the task data.
    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         totalNumberOfTasks: [the total number of tasks assigned to the user],
         jobboard: [Array holding the current page of task data objects]
    };
    

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

    Retrieve a range (or page) of tasks. This may include tasks not assigned to the current user so their display should be guarded by membership in a SmartFlo™ group (e.g., Project Manager or Job Manager).

    Tries to match specified query terms against various job data fields. Query terms are comma (,) separated.

  • job data
  • brand, category, client_company, distribution_channel, item_description, item_id, product, project_id, task_id, task_name, project_manager, project_name, workflow_id, workflow_definition, resource_group, status

  • extended job metadata
  • account_name, art_due_date, creative_agency, customer_position, file_destination, master_artwork_template, num_of_units, production_schedule, program_owner, team, states_program, program_classification, program_type, legal_owner, alliance_owner, prize_logic_owner, program_manager_owner

    Example

    $scope.datasourceCallback;
    function createTasksDatasource() {
         var dataSource = {
             pageSize: $scope.pageSize,
             getRows: function (gridparams) {
                 $scope.datasourceCallback = gridparams.successCallback;
                 var params = {
                     startrow: gridparams.startRow,
                     pagesize: gridparams.endRow - gridparams.startRow
                 };
                 SFjobsApi.getMatchingJobboardTasks(param, getJobboardTasksHandler);
             }
         };
         $scope.gridOptions.api.setDatasource(dataSource);
    }
    
    function getJobboardTasksHandler(result) {
         if ('0' === result.status) {
             $scope.datasourceCallback(result.jobboard, result.totalNumberOfTasks);
             $scope.numTasks = result.totalNumberOfTasks;
             $scope.currentTasks = result.jobboard;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the query terms, the start position and page size for the set of tasks returned, and a request that the query be expanded or not. In this example, ag-Grid (Copyright © 2017 ag-Grid Ltd, All rights reserved) is used to provide paging.

    
    var params = {
         tomatch: [comma separated list of query terms],
         startrow: gridparams.startRow,
         pagesize: gridparams.endRow - gridparams.startRow,
         expand: [true | false - whether to use terms as elements
         of an "OR" (expand === true) query or an
         "AND" (expand === false) query.
    };

    For non-expanding queries: all running or suspended job tasks in the pan-affiliate group for which one of the target columns matches ALL of the comma separated search terms.

    For expanding queries: all running or suspended job tasks in the pan-affiliate group for which any of the target columns match ANY of the comma separated search terms.

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    See also
    getTask for a description of the task data.
    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         totalNumberOfTasks: [the total number of tasks assigned to the user],
         jobboard: [Array holding the current page of task data objects]
    };
    

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

    Retrieve the milestone templates defined for the affiliate in the SmartFlo™ system.

    Example

    $scope.getMilestoneTemplates = function () {
         var params = {
             jobteam: $scope.job_team.value
         };
         SFjobsApi.getMilestoneTemplates(params, handleGetMilestoneTemplates);
    };
    
    function handleGetMilestoneTemplates(result) {
         if ('0' === result.status) {
             $scope.milestoneTemplateList = result.milestoneTemplateList;
         } else {
             $scope.errorCode = milestoneTemplateData.status;
             $scope.errorMessage = milestoneTemplateData.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected job team.

    
    var params = {
         jobteam: $scope.job_team.value
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         milestoneTemplateList: [Array containing the SmartFlo™ milestone template names] for the user's affiliate.]
    };
    

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

    Retrieve the role overrides defined for the affiliate and workflow definition in the SmartFlo™ system.

    Example

    $scope.getOverrideRoles = function () {
         var params = {
             jobdefinition: $scope.job_team.value
         };
         SFjobsApi.getOverrideRoles(params, handleGetOverrideRoles);
    };
    
    function handleGetOverrideRoles(result) {
         if ('0' === result.status) {
             var overrideRoles = result.roleOverrides;
             // alliance role
             if (overrideRoles.alliance_role) {
                 $scope.jobData.alliance_role = overrideRoles.alliance_role;
                 $scope.overrideRoleAssignmentsLists.allianceRole = overrideRoles.allianceRole;
             } else {
                 $scope.jobData.alliance_role = "";
                 $scope.overrideRoleAssignmentsLists.allianceRole = [];
             }
    
             // program (client assignment) role
             if (overrideRoles.program_role) {
                 $scope.jobData.program_role = overrideRoles.program_role;
                 $scope.overrideRoleAssignmentsLists.programRole = overrideRoles.programRole;
             } else {
                 $scope.jobData.program_role = "";
                 $scope.overrideRoleAssignmentsLists.clientAssignmentRole = [];
             }
    
             // legal role
             if (overrideRoles.legal_role) {
                 $scope.jobData.legal_role = overrideRoles.legal_role;
                 $scope.overrideRoleAssignmentsLists.legalRole = overrideRoles.legalRole;
             } else {
                 $scope.jobData.legal_role = "";
                 $scope.overrideRoleAssignmentsLists.legalRole = [];
             }
    
             // prize logics role
             if (overrideRoles.prize_logic_role) {
                 $scope.jobData.prize_logic_role = overrideRoles.prize_logic_role;
                 $scope.overrideRoleAssignmentsLists.prizeLogicRole = overrideRoles.prizeLogicRole;
             } else {
                 $scope.jobData.prize_logic_role = "";
                 $scope.overrideRoleAssignmentsLists.prizeLogicRole = [];
             }
    
             //program manager role
             if (overrideRoles.program_manager_role) {
                 $scope.jobData.program_manager_role = overrideRoles.program_manager_role;
                 $scope.overrideRoleAssignmentsLists.programManagerRole = overrideRoles.programManagerRole;
             } else {
                 $scope.jobData.program_manager_role = "";
                 $scope.overrideRoleAssignmentsLists.programManagerRole = [];
             }
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected job team.

    
    var params = {
         jobdefinition: $scope.job_team.value
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         roleOverrides: [Object containing the SmartFlo™ program role overrides]
    };
    

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

    Retrieve the product parts defined in the system for a given affiliate, client company, distribution channel and product. Each affiliate in the system can define a set of company data arranged as a hierarchy of values:

    
                             Affiliate
                                 |
                          Client Companies
                 ________________|________________
                 |                               |
       Distribution Channels                 Categories
                 |                               |
             Products                          Brands
                 |
               Parts
    
    

    Example

    $scope.getProductParts = function () {
         var params = {
             client: $scope.client_company.value,
             channel: $scope.distribution_channel.value,
             product: $scope.product.value
         };
         SFjobsApi.getProductParts(params, handleGetProductParts);
    };
    
    function handleGetProductParts(result) {
         if ('0' === result.status) {
              $scope.partsList = result.partsList;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected client company, distribution channel and product.

    
    var params = {
         client: $scope.client_company.value,
         channel: $scope.distribution_channel.value,
         product: $scope.product.value
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         partsList: [Array containing the channel product values]
    };
    

    getProgramClassifications(successHandler[, failureHandler]) → object

    Retrieve the program classifications defined for the affiliate in the SmartFlo™ system.

    Example

    $scope.getProgramClassifications = function () {
         SFjobsApi.getProgramClassifications(handleGetProgramClassifications);
    };
    
    function handleGetProgramClassifications(result) {
         if ('0' === result.status) {
             $scope.programClassificationsList = result.programClassificationsList;
         } 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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         programClassificationsList: [Array containing the SmartFlo™ program classifications]
    };
    

    getProgramTypes(successHandler[, failureHandler]) → object

    Retrieve the program types defined for the affiliate in the SmartFlo™ system.

    Example

    $scope.getProgramTypes = function () {
         SFjobsApi.getProgramTypes(handleGetProgramTypes);
    };
    
    function handleGetProgramTypes(result) {
         if ('0' === result.status) {
             $scope.programTypesList = result.programTypesList;
         } 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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         programTypesList: [Array containing the SmartFlo™ program types]
    };
    

    getProjectManagers(successHandler[, failureHandler]) → object

    Retrieve the members of the "Project Manager" group defined in the system for the user's affiliate.

    Example

    $scope.getProjectManagers = function () {
         SFjobsApi.getProjectManagers(handleGetProjectManagers);
    };
    
    function handleGetProjectManagers(result) {
         if ('0' === result.status) {
             $scope.projectManagerList = result.projectManagerList;
         } 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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         projectManagerList: [Array containing the affiliate project managers]
    };
    

    getSmartFloProjects(successHandler[, failureHandler]) → object

    Retrieve the members of the "Project Manager" group defined in the system for the user's affiliate.

    Example

    $scope.getSmartFloProjects = function () {
         SFjobsApi.getSmartFloProjects(handleGetSmartFloProjects);
    };
    
    function handleGetSmartFloProjects(result) {
         if ('0' === result.status) {
             $scope.smartfloProjectsList = result.smartfloProjectsList;
         } 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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         smartfloProjectsList: [Array containing the affiliate SmartFlo™ projects]
    };
    

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

    Retrieve the task data specified by a given jobid [alt: workflowid]and taskid pair.

    Example

    function displayTask() {
         var params = {
             jobid: $rootScope.jobid, 
             taskid: $rootScope.taskid
         };
         SFtaskApi.getTask(params, handleGetTask);
    }
         
    function handleGetTask(result) {
         if ('0' === result.status) {
             result.currentTask.task_priority = $translate.instant(result.currentTask.priority);
             SFStorage.saveCurrentTask(result.currentTask);
         
             var currentTasks = [];
             currentTasks[0] = result.currentTask;
             var action = "/approvaltask"; // default task detail view
             if (result.currentTask.task_action) {
                 // see if a task detail view is defined other than default
                 var na = $translate.instant(result.currentTask.task_action);
                 if (na) { // non-default task detail view is defined so show it
                     action = "/" + na;
                 }
             }
             $location.path(action); //load task detail page
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the jobid and taskid to retrieve a given instance of task data.

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         currentTask: [the data asociated with the requested task]
    };

    task { affiliate: [the name of the affiliate that launched the job], job_id: [the SmartFlo™ unique SFID for the job], job_name: [the complete (long) name for the job], job_definition: [the workflow definition that the job instantiates], started_date: [the time in GMT when the job was started], launch_date: [the launch (due) date for job completion], dwell_hours: [the amount of time the current task has been running], task_id: [the SmartFlo™ ID of the task], task_name: [the SmartFlo™ name of the task], task_action: [the SmartFlo™ task detail screen to load], status: ['Running' or 'Suspended'], performer_list: [an object with 2 fields:
    performer_list { owner: [SmartFlo™ owner if one exists] performer: [list of 1 or more SmartFlo™ groups assigned to the task] }], priority: [a deliniated string identifying the priority of the task - e.g., "label.priority.normal": "Normal", "label.priority.high": "High", "label.priority.low": "Low" ], comments: [Array of job comments], instruction: [an instruction for completing the task], complete_button: [the translation key for the label of the complete task button], project_manager: [the SmartFlo™ ID of the project manager for the job], project_id: [job data prividing the project ID for the job], project_name: [job data providing the long name (description) for the project], smartflo_project: [SmartFlo™ project ID for the job], next_milestone: [the id of the next milestone event], milestone_date: [ the due date for the next_milestone], and_routes: [Array of 0 or more 'and-route' variables], or_routes: [Array of 0 or more 'or-route' variables], auto_routes: [Array of 0 or more 'auto-route' variables], item_id: [job data identifying the job item], item_description: [job data describing of the job item], client_company: [company data naming the client], category: [company data naming the product category], channel: [company data naming the channel], product: [company data naming the product], brand: [company data naming the brand] };

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

    Retrieve a range (or page) of tasks currently assigned to the user.

    Example

    $scope.datasourceCallback;
    function createTasksDatasource() {
         var dataSource = {
             pageSize: $scope.pageSize,
             getRows: function (gridparams) {
                 $scope.datasourceCallback = gridparams.successCallback;
                 var params = {
                     startrow: gridparams.startRow,
                     pagesize: gridparams.endRow - gridparams.startRow
                 };
                 SFjobsApi.getUserTasks(params, getUserTasksHandler);
             }
         };
         $scope.gridOptions.api.setDatasource(dataSource);
    }
    
    function getUserTasksHandler(result) {
         if ('0' === result.status) {
             $scope.datasourceCallback(result.taskList, result.totalNumberOfTasks);
             $scope.numTasks = result.totalNumberOfTasks;
             $scope.currentTasks = result.taskList;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the start position and page size for the set of tasks returned. In this example, ag-Grid (Copyright © 2017 ag-Grid Ltd, All rights reserved) is used to provide paging.

    
    var params = {
         startrow: gridparams.startRow,
         pagesize: gridparams.endRow - gridparams.startRow
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    See also
    getTask for a description of the task data.
    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         totalNumberOfTasks: [the total number of tasks assigned to the user],
         taskList: [Array holding the current page of task data objects]
    };
    

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

    Posts selected tasks to the backend to be autocompleted - i.e., completed without a user seeing them in their task list.

    Example

    $scope.completeExceptionTask = function () {
         var params = {
             jobid: $scope.currentTask.job_id,
             taskid: task.task_id,
             routes: taskid1, taskid2
         };
         SFjobsApi.postAutoCompletionTasks(params, handlePostAutoCompletionTasks);
    };
    
    function handlePostAutoCompletionTasks(result) {
         if ('0' === result.status) {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected jobid, the taskid of the task at which the selection is made and a comma separated list (routes) of taskids identifying tasks to be autocompleted.

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

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called]
    };
    

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

    Post a claim on the task or for all tasks handled by the task role.

    Example

    $scope.postNewJobComment = function () {
         var params = {
             jobid: $scope.currentTask.job_id,
             taskid: $scope.currentTask.task_id,,
             forrole: [false | true]
         };
         SFjobsApi.postClaimTask(params, handlePostClaimTask);
    };
    
    function handlePostClaimTask(result) {
         if ('0' === result.status) {
             var userid = $scope.credential.userid;
             $scope.owner = userid;
             $scope.owned = true;
             $scope.currentTask.performer_list.owner = userid;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected job team.

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

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called]
    };
    

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

    Completes a given Exception Task in a given job. An Exception Task is a unuique, ad hoc task type created for the general purpose of correcting an issue in a job without the requirement to route the job back to an earlier task. It copies its job data from a selected running task on the Job Board. Exception Tasks are not defined or configured as part the the workflow administration and configuration process.

    Example

    $scope.completeExceptionTask = function () {
         var params = {
             jobid: $scope.currentTask.job_id,
             taskid: task.task_id
         };
         SFjobsApi.postCompleteExceptionTask(params, handlePostCompleteExceptionTask);
    };
    
    function handlePostCompleteExceptionTask(result) {
         if ('0' === result.status) {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected jobid and taskid of the Exception Task that will be completed.

    
    var params = {
         jobid: $scope.currentTask.job_id,
         taskid: task.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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called]
    };
    

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

    Posts a change to the job item description.

    Example

    $scope.postJobDescription = function () {
         var params = {
             jobid: $scope.currentTask.job_id,
             description: $scope.itemDescription
         };
         SFjobsApi.postJobDescription(params, handlePostJobDescription);
    };
    
    function handlePostJobDescription(result) {
         if ('0' === result.status) {
             $scope.currentTask.item_description = = $scope.itemDescription;
             SFStorage.saveCurrentTask($scope.currentTask);
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected job and new item description.

    
    var params = {
         jobid: $scope.currentTask.job_id,
         description: $scope.itemDescription
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called]
    };
    

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

    Posts a change of the selected job task performer.

    Example

    $scope.postJobPerformer = function () {
         var params = {
             jobid: $scope.currentTask.job_id,
             taskid: task.task_id,
             forrole: $scope.forRole, [true|false]
             performer: $scope.selectedPerformer
         };
         SFjobsApi.postJobPerformer(params, handlePostJobPerformer);
    };
    
    function handlePostJobPerformer(result) {
         if ('0' === result.status) {
             $scope.currentTask.performer_list = $scope.selectedPerformer;
             SFStorage.saveCurrentTask($scope.currentTask);
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected job and task, a flag indicating whether to assign all other tasks in the job with the same role to the selected performer, and the selected performer.

    
    var params = {
         jobid: $scope.currentTask.job_id,
         taskid: task.task_id,
         forrole: $scope.forRole, [true|false]
         performer: $scope.selectedPerformer
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called]
    };
    

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

    Posts a change to the job status. Valid status options are:

    
    $scope.statusOptions = [
         "label.jobboard.complete", [completes the job and removes all tasks]
         "label.jobboard.start", [restarts a job that has been suspended]
         "label.jobboard.suspend", [suspends a running job]
         "label.jobboard.kill" [cancels a job]
    ];
    

    Example

    $scope.postJobStatus = function () {
         var params = {
             jobid: $scope.currentTask.job_id,
             status: $scope.selectedStatus
         };
         SFjobsApi.postJobStatus(params, handlePostJobStatus);
    };
    
    function handlePostJobStatus(result) {
         if ('0' === result.status) {
             $scope.currentTask.status = $translate.instant($scope.selectedStatus);
             SFStorage.saveCurrentTask($scope.currentTask);
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected job and the selected status.

    
    var params = {
         jobid: $scope.currentTask.job_id,
         status: $scope.selectedStatus
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called]
    };
    

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

    Post a new job comment for the selected job.

    Example

    $scope.postNewJobComment = function () {
         var isPublicComment = true;
         if ($scope.credential.isPrivateCommentsUser) {
             isPublicComment = $scope.projectComments.ispublic;
         }
         var params = {
             jobid: $scope.currentTask.job_id,
             taskid: $scope.currentTask.task_id,,
             ispublic: isPublicComment,
         };
         SFjobsApi.postNewJobComment(params, handlePostNewJobComment);
    };
    
    function handlePostNewJobComment(result) {
         if ('0' === result.status) {
             $scope.newJobComment = result.newJobComment;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected job team.

    
    var isPublicComment = true;
    if ($scope.credential.isPrivateCommentsUser) {
         isPublicComment = $scope.projectComments.ispublic;
    }
    var params = {
         jobid: $scope.currentTask.job_id,
         taskid: $scope.currentTask.task_id,,
         ispublic: isPublicComment,
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         newJobComment: [object containing the new comment fields]
    };
    

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

    Starts an Exception Task in a given job. An Exception Task is a unuique, ad hoc task type created for the general purpose of correcting an issue in a job without the requirement to route the job back to an earlier task. It copies its job data from a selected running task on the Job Board. Successful creation of an Exception Task automatically notifies the given user via Email that they should complete the Exception Task. Exception Tasks are not defined or configured as part the the workflow administration and configuration process.

    Example

    $scope.startExceptionTask = function () {
         var params = {
             jobaffiliate: $scope.currentTask.affiliate,
             jobid: $scope.currentTask.job_id,
             taskid: $scope.currentTask.task_id,
             assignto: [userid handling Exception Task],
             explanation: [explanation/description of task]
         };
         SFjobsApi.postStartExceptionTask(params, handlePostStartExceptionTask);
    };
    
    function handlePostStartExceptionTask(result) {
         if ('0' === result.status) {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         } else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the selected jobaffiliate, jobid, copy-from-taskid, user assignment and explanation for the Exception Task creation.

    
    var params = {
         jobaffiliate: [job-affiliate],
         jobid: [job_id],
         taskid: [task_id],
         assignto: [userid handling Exception Task],
         explanation: [explanation/description of task]
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called]
    };
    

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

    Posts XML formatted job data to start a job. For conveniance a JavaScript class is provided as part of this API that simplifies managing the many data fields and includes a method (renderJobXML) to convert its field values to the appropriate SmartFlo™ XML start job format. A second conveniance method (clear) clears the values set on the class, except for the affiliate value. Only 3 fields must be set - affiliate, launch_date and job_team. If any of the 3 has not been set, the attempt to render to XML will throw a "required.job.fields.missing" Error.

    
    // Example of creating and initializing a JobData class for managing start job data fields.
    $scope.jobData = new JobData(); // create the data class
    $scope.jobData.affiliate = $rootScope.credential.affiliate; // set the affiliate
    
    // Example of converting the JobData class to the appropriate XML format.
    var jobxml = $scope.jobData.renderJobXML();
    
    // Example of clearing the JobData class.
    $scope.jobData = $scope.jobData.clear();
    
    // This class requires requires XMLWriter       
    class JobData {
         constructor() {
             return {
                 affiliate: '' [REQUIRED],
                 launch_date: '' [REQUIRED],
                 job_team: '' [REQUIRED],
                 project_manager: '',
                 smartflo_project: '',
                 project_id: '',
                 project_name: '',
                 item_id: '',
                 item_description: '',
                 milestone_lag_days: 0,
                 milestone_template: '',
                 program_manager_role: '',
                 program_manager_role_owner: '',
                 program_role: '',
                 program_owner: '',
                 legal_role: '',
                 legal_owner: '',
                 alliance_role: '',
                 alliance_owner: '',
                 prize_logic_role: '',
                 prize_logic_owner: '',
                 customer_position: '',
                 client_company: '',
                 distribution_channel: '',
                 category: '',
                 brand: '',
                 product: '',
                 part: '',
                 job_comment: '',
                 art_due: '',
                 account_name: '',
                 number_of_units: '',
                 file_destination: '',
                 creative_agency: '',
                 master_artwork_template: '',
                 production_schedule: '',
                 retail_start_date: '',
                 retail_end_date: '',
                 states_program: '',
                 program_type: '',
                 program_classification: ''
                 renderJobXML: function (),
                 clear: function()
             };
         }
    }
    

    Example

    $scope.startJob = function () {
         var jobxml = $scope.jobData.renderJobXML();
         var params = {
             joborder: jobxml 
         };
         SFjobsApi.postStartJob(param, handlePostStartJob);
    }
         
    function handlePostStartJob(result) {
         if ('0' === result.status) {
             var msg = $translate.instant('message.job.started');
             $scope.feedbackMessage = msg + ' ' + result.jobid;
         else {
             $scope.errorCode = result.status;
             $scope.errorMessage = result.statusMessage;
         }
    }

    Parameters

    Name Type Optional Description

    params

    object

     

    An object providing the XML for starting the job .

    
    var jobxml = $scope.jobData.renderJobXML();
    var params = {
         joborder: jobxml 
    };
    

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called],
         jobid: [the full name of the newly started job]
    };

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

    Post a request to complete the selected task.

    Example

    $scope.postTaskCompletion = function () {
         var params = {
             jobid: $scope.currentTask.job_id,
             taskid: $scope.currentTask.task_id,
             routes: routes.length > 0 ? routes : null
         };
         SFjobsApi.postTaskCompletion(params, handlePostTaskCompletion);
    };
    
    function handlePostTaskCompletion(result) {
         if ('0' === result.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 providing the selected job team.

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

    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. On failure however, the only valid fields returned are: status, statusMessage, api and date.

    Throws

    (string) "missing.callback.exception"

    $http errors

    Returns

    object A result object.

    
    result {
         date: [time API call was completed],
         status: ['0' for success, otherwise failure],
         statusMessage: [message indicating reason for status value],
         api: [the API that was called]
    };