JobHandler

This class contains the functions to perform the following:

- Retrieve Job(s)

- Insert Job(s) - Update Job Details, Job Flag, Job Description

api
package simPROAPI
subpackage Projects
author Nathan Muir, Isaac Martin
version 2011-07-18

 Methods

JobDeleteAttachment

DeleteAttachment(int $CompanyID, int $JobNo, string $FileName) : array
Static

This function deletes an attachment for the provided job no

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$JobNo

int

The job to retrieve attachments for

$FileName

string

the File Name.

Returns

array

JobDeleteScheduleBlock

DeleteScheduleBlock(int $CompanyID, int $JobNo, int $DepartmentNo, int $StaffID, string $Date, string $StartTime, string $EndTime) : bool
Static

Parameters

$CompanyID

int

the company id

$JobNo

int

the job number

$DepartmentNo

int

the department to insert the schedule on

$StaffID

int

the staff member to schedule

$Date

string

Date to schedule the employee. (Y-m-d)

$StartTime

string

must be validated by /^([0-1]?[1-9]|2[0-4]):([0-5][0-9])$/

$EndTime

string

must be validated by /^([0-1]?[1-9]|2[0-4]):([0-5][0-9])$/

Returns

bool

JobFlag

Flag(int $CompanyID, int $JobNo) : bool
Static

This function flags a particular job as exported

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$JobNo

int

The job to flag as exported

Returns

bool

JobFlagList

FlagList(int $CompanyID, array $JobNos) : bool
Static

This function flags particular jobs as exported

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$JobNos

array

The jobs list to flag as exported

Returns

bool

JobInsert

Insert(int $CompanyID, array $JobDetails) : int
Static
<?php
$JobDetails =
array(
"CustomerID"=>0, //Required
"OrderNo"=>0,
"RequestNo"=>"",
"Description"=>"",
"Notes"=>"",
"IssuedDate"=>"Y-m-d",
"DueDate"=>"Y-m-d",
"DueTime"=>"h:m:s",
"SiteID"=>0, // Required
"TagIDs"=>array(),
"Type"=>0, //0 = Project Job, 1 = Service.
"SalesPerson"=>0,
"ProjectManager"=>0,
"Technician"=>0,
"Stage"=>2, // exclude if the status shouldn't be modified. 2 = Pending, 3 = Progress, 4 = Complete, 5 = Archived
"StatusID"=>0, // may change the job stage, depending on status-triggers
"ResponseTime"=>0, // Response Time ID
"Sections"=>array(
  array(
    "Name"=>"",
    "Description"=>"",
    "CostCentres"=>
    array(
      array(
        "CostCentreID"=>0,
        "Description"=>"",
        "Notes"=>"",
        "Locked"=>0, // not-implemented
        "Items"=>
          array(
             array(
               "Type"=>"CatalogItem",
               "StockItemID"=>0,
               "Quantity"=>0, // default = 1
               "BasePrice"=>0,
               "Markup"=>0,
               "SellPrice"=>0,// not implemented
               "Time"=>0
             ),
             array(
               "Type"=>"OneOffItem",
               "Description"=>"",
              "Quantity"=>0, // default = 1
               "EstCost"=>0,
               "ActCost"=>0,
               "Markup"=>0, // provide either sell price or markup (not both)
               "SellPrice"=>0,
               "Time"=>0,
             ),
             array(
               "Type"=>"PrebuildItem",
               "PrebuildID"=>0,
               "Quantity"=>0, // default = 1
               "CostPrice"=>0, // not implemented
               "Markup"=>0, // not implemented
               "SellPrice"=>0, // not implemented
               "Time"=>0
             ),
              array(
               "Type"=>"LabourItem",
               "LabourID"=>0,
               "LabourRate"=>0,
               "Markup"=>0,
               "SellPrice"=>0, // not implemented
               "Time"=>0
             )
          )
        )
      )
    )
  )
 "CustomFields"=>array(
    "FieldName"=>"Value" // FieldName is the name of the custom field and value is the value to set it to
  )
);
?>

Parameters

$CompanyID

int

the company id

$JobDetails

array

an associative array of job information.

Returns

int

JobInsertScheduleBlock

InsertScheduleBlock(int $CompanyID, int $JobNo, int $DepartmentNo, int $StaffID, string $Date, string $StartTime, string $EndTime, string $LabourMultiplier = "1.0", string $ScheduleRateID = null) : bool
Static

Parameters

$CompanyID

int

the company id

$JobNo

int

the job number

$DepartmentNo

int

the department to insert the schedule on

$StaffID

int

the staff member to schedule

$Date

string

Date to schedule the employee. (Y-m-d)

$StartTime

string

must be validated by /^([0-1]?[1-9]|2[0-4]):([0-5][0-9])$/

$EndTime

string

must be validated by /^([0-1]?[1-9]|2[0-4]):([0-5][0-9])$/

$LabourMultiplier = "1.0"

string

For backwards compatability - will accecpt 1.00, 1.50 and 2.00. Will use the original default multiplier @deprecated

$ScheduleRateID = null

string

The ID of the schedule muliplier to use. If definded then $LabourMultiplier will be ignored

Returns

bool

LogSearch

LogSearch(int $CompanyID, int $JobNo = null, string $StartDate = null, string $EndDate = null, int $StaffID = null, string $Search = '%', int $Limit = 1000, int $Offset = 0) : array
Static

This function retrieves logs from Jobs whether a specific number is supplied or not.

Parameters

$CompanyID

int

The Company ID. In single company builds, this is 0.

$JobNo = null

int

The Job Number to retrieve (Optional). Null/Empty will ignore this parameter.

$StartDate = null

string

Date start (inclusive) to search. Null/Empty will ignore this parameter.

$EndDate = null

string

Date end (inclusive) to search. Null/Empty will ignore this parameter.

$StaffID = null

int

The employee ID. Null/Empty will ignore this parameter.

$Search = '%'

string

The search text for the log message. Can use % for wildcards.

$Limit = 1000

int

the total number of logs to return (0 - 1000)

$Offset = 0

int

how many results to skip, before returning {@link $Limit}

Returns

array

JobRetrieve

Retrieve(int $CompanyID, int $JobNo) : array
Static

This function retrieves a job with a specific number

uses \JobHandler::RetrieveList()

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$JobNo

int

The job Number to retrieve

Returns

array

JobRetrieveAllocated

RetrieveAllocated(int $CompanyID, array $Detail = null, int $CustomerID = null, string $StartDate = null, string $EndDate = null, int $Limit = 10, int $Offset = 0) : array
Static

This function retrieves the job that the current staff has been allocated [Scheduled, Technician, Salesman, Manager(?)]

uses \JobHandler::RetrieveList()

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$Detail = null

array

The detail of the job object, advanced will return schedules. Null/Empty will ignore this parameter.

$CustomerID = null

int

the customer's id. Null/Empty will ignore this parameter.

$StartDate = null

string

Date start (inclusive) to search. Null/Empty will ignore this parameter. {@link http://php.net/manual/en/function.strtotime.php}

$EndDate = null

string

Date end (inclusive) to search. Null/Empty will ignore this parameter. {@link http://php.net/manual/en/function.strtotime.php}

$Limit = 10

int

how many results to return

$Offset = 0

int

how many results to skip, before returning {@link $Limit}

Returns

array

JobRetrieveAttachmentKey

RetrieveAttachmentKey(int $CompanyID, int $JobNo, string $Filename, bool $Email = false, bool $Public = false) : string
Static

Retrieve an attachment key for the specified job. Once the key has been obtained, it can then be sent with the attachment as a HTTP POST, with content encoded as multipart/form-data to /api/addAttachment.php

See http://api.simpro.co/index.html#fileuploads for more information on how to upload

Parameters

$CompanyID

int

the company id

$JobNo

int

the job number

$Filename

string

the filename

$Email = false

bool

set whether the attachment should be emailed in corespondence with clients

$Public = false

bool

set whether the attachment is visible on job-cards, etc.

Returns

string

JobRetrieveAttachments

RetrieveAttachments(int $CompanyID, int $JobNo) : array
Static

This function retrieves the list of attachemnts for the provided job no

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$JobNo

int

The job to retrieve attachments for

Returns

array

JobRetrieveDepartments

RetrieveDepartments(int $CompanyID, int $JobNo) : array
Static

This function retrieves a list of departments for a job

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$JobNo

int

The Job Number.

Returns

array

JobRetrieveExport

RetrieveExport(int $CompanyID, string $StartDate = null, string $EndDate = null) : array
Static

This function retrieves a list of jobs that are ready for export

uses \JobHandler::RetrieveList()

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$StartDate = null

string

Date start (inclusive) to search. Null/Empty will ignore this parameter. {@link http://php.net/manual/en/function.strtotime.php}

$EndDate = null

string

Date end (inclusive) to search. Null/Empty will ignore this parameter. {@link http://php.net/manual/en/function.strtotime.php}

Returns

array

JobRetrieveList

RetrieveList(int $CompanyID, array $JobNos, array $Detail = null, int $StaffID = null) : array
Static

This function retrieves details on the provided list of job numbers

uses \CompanyHandler::Retrieve()
used_by \JobHandler::Search()
used_by \JobHandler::SearchFields()
used_by \JobHandler::Retrieve()
used_by \JobHandler::RetrieveAllocated()
used_by \JobHandler::RetrieveExport()

Parameters

$CompanyID

int

the Company ID. In single company builds, this is 0.

$JobNos

array

list of Job Numbers to search for.

$Detail = null

array

the specification of which details to return - ("PurchaseOrders","Attachments","Audits","Items","LabourItems","Stock","Assets","JobNotes","Schedules","JobCards","Signatures","MobileStatusLogs","OnlyScheduledDepartments", "ProfitLoss"). Null/Empty will return all details except for ProfitLoss details, array(null) array will return none.

$StaffID = null

int

The ID for restricting schedules and departments to return. Null/Empty will ignore this parameter.

Returns

array

JobRetrieveSchedules

RetrieveSchedules(int $JobNo, int $DepartmentNo, int $StaffID = null, string $Date = null) : array
Static

Parameters

$JobNo

int

The job to retrieve Schedules for.

$DepartmentNo

int

The department to retrieve Schedules for. - SectionCostCentreID

$StaffID = null

int

the staff ID for which to search. Null/Empty will ignore this parameter.

$Date = null

string

the date for which to search. Null/Empty will ignore this parameter.

Returns

array

JobSearchFields

SearchFields(mixed $CompanyID, array $Detail = null, array $SearchTerms = array(), string $StartDate = null, string $EndDate = null, int $Limit = 10, int $Offset = 0, bool $SortAsc = true, bool $RestrictSchedules = true) : array
Static

This function retrieve's a list of jobs who's set of fields match their associated values

Implemented Search Terms are: Stage, OrderNo, RequestNo, Currency, SiteID, TagID, StaffID, JobID, CustomerID, Salesperson, CostCentreID, Scheduled, DateFilterType

SearchFields[DateFilterType] can take values of 'ScheduledDate','IssuedDate', 'DueDate' and defaults to 'ScheduledDate'

uses \JobHandler::RetrieveList()

Parameters

$CompanyID

mixed

the Company ID. In single company builds, this is 0.

$Detail = null

array

The detail to be returned about the jobs {@see JobHandler::RetrieveList}

$SearchTerms = array()

array

An associative array of Search Fields[key] and their search terms [value], values can be arrays to retrieve multiple

$StartDate = null

string

Date start (inclusive) to search for jobs. Null/Empty will ignore this parameter. {@link http://php.net/manual/en/function.strtotime.php}

$EndDate = null

string

Date end (inclusive) to search for jobs. Null/Empty will ignore this parameter. {@link http://php.net/manual/en/function.strtotime.php}

$Limit = 10

int

how many results to return

$Offset = 0

int

how many results to skip, before returning {@link $Limit}

$SortAsc = true

bool

which direction to sort the results

$RestrictSchedules = true

bool

determines whether the schedules returned should only be for the current employee

Returns

array

JobUpdate

Update(int $CompanyID, int $JobNo, array $JobDetails) : bool
Static
<?php
$JobDetails =
array(
"CustomerID"=>0,
"OrderNo"=>0,
"RequestNo"=>"",
"Description"=>"",
"Notes"=>"",
"IssuedDate"=>"Y-m-d",
"DueDate"=>"Y-m-d",
"DueTime"=>"h:m:s",
"SiteID"=>0,
"TagIDs"=>array(),
"Type"=>0, //0 = Project Job, 1 = Service.
"SalesPerson"=>0,
"ProjectManager"=>0,
"ClearSections"=>false,
"Stage"=>2, // exclude if the status shouldn't be modified. 2 = Pending, 3 = Progress, 4 = Complete, 5 = Archived
"StatusID"=>0, // may change the job stage, depending on status-triggers
"ResponseTime"=>0, // Response Time ID
"Sections"=>array(
  array(
    "SectionID"=>0, // must match to update this section, omit to add a new section to the quote
    "Name"=>"",
    "Description"=>"",
    "ClearCostCentres"=>false,
    "CostCentres"=>
    array(
      array(
        "SectionCostCentreID"=>0, // must match to update, omit to add a new cost centre to the quote
        "CostCentreID"=>0,
        "Description"=>"",
        "Notes"=>"",
        "Locked"=>0, // not-implemented
       "ClearItems"=>false,
       "MergeItems"=>false, // items already on the job which match exactly will increase in quantity rather than add separate line
        "Items"=>
          array(
             array(
               "Type"=>"CatalogItem",
               "StockItemID"=>0,
               "Quantity"=>0, // default = 1
               "BasePrice"=>0, // not implemented
               "Markup"=>0,// not implemented
               "SellPrice"=>0,// not implemented
               "Time"=>0
             ),
             array(
               "Type"=>"OneOffItem",
               "Description"=>"",
               "EstCost"=>0,
               "ActCost"=>0,
               "Markup"=>0, // provide either sell price or markup (not both)
               "SellPrice"=>0,
               "Time"=>0,
             ),
             array(
               "Type"=>"PrebuildItem",
               "PrebuildID"=>0,
               "Quantity"=>0, // default = 1
               "BasePrice"=>0, // not implemented
               "Markup"=>0, // not implemented
               "SellPrice"=>0, // not implemented
               "Time"=>0
             ),
              array(
               "Type"=>"LabourItem",
               "LabourID"=>0,
               "LabourRate"=>0,
               "Markup"=>0,
               "SellPrice"=>0, // not implemented
               "Time"=>0
             )
          )
        )
      )
    )
  )
"CustomFields"=>array(
  "FieldName"=>"Value" // FieldName is the name of the custom field and value is the value to set it to
  )
);
?>

Parameters

$CompanyID

int

the company id

$JobNo

int

the job to update

$JobDetails

array

an associative array of job information.

Returns

bool