QuoteHandler

This class contains the functions to perform the following:

  • Retrieve Quote(s)
  • Insert Quote(s)
  • Update Quote Details, Quote Flag(?), Reject Quote, Accept Quote, Convert Quote, Quote Description
api
package simPROAPI
subpackage Projects
author Nathan Muir
version 2011-07-18

 Methods

QuoteAccept

Accept(int $CompanyID, int $QuoteNo, string $OrderNo = null) : bool
Static

This function flags a particular quote as accepted by the customer

Parameters

$CompanyID

int

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

$QuoteNo

int

The quote to flag as accepted

$OrderNo = null

string

Client provided purchase order number

Returns

bool

QuoteConvert

Convert(int $CompanyID, int $QuoteNo, string $OrderNo = null) : int
StaticNot Implemented

This function converts a quote to a job

Parameters

$CompanyID

int

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

$QuoteNo

int

The quote to convert

$OrderNo = null

string

optional order number

Returns

int

QuoteDecline

Decline(int $CompanyID, int $QuoteNo) : bool
Static

This function flags a particular quote as rejected

Parameters

$CompanyID

int

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

$QuoteNo

int

The quote to flag as rejected

Returns

bool

QuoteDeleteAttachment

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

This function deletes an attachment for the provided quote no

Parameters

$CompanyID

int

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

$QuoteNo

int

The quote to retrieve attachments for

$FileName

string

the File Name.

Returns

array

QuoteDeleteScheduleBlock

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

Parameters

$CompanyID

int

the company id

$QuoteNo

int

the quote 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

QuoteInsert

Insert(int $CompanyID, array $QuoteDetails) : int
Static
<?php
$QuoteDetails =
array(
"CustomerID"=>0,
"CustomerContractID"=>0,
"OrderNo"=>0,
"RequestNo"=>"",
"Description"=>"",
"Notes"=>"",
"IssuedDate"=>"Y-m-d",
"ExpiryDate"=>"Y-m-d",
"QuoteStage"=>0, // 0 = In-Progress, 1 = Complete, 2 = Approved
"Forecast"=> array ( "Year"=>2012 , "Month"=> 12 , "Percent"=>50 ),
"SiteID"=>0,
"TagIDs"=>array(), // empty removes all, tags id adds to list
"Type"=>0, //0 = Project Job, 1 = Service.
"SalesPerson"=>0,
"ProjectManager"=>0,
"Technician"=>0,
"StatusID"=>0,
"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,// not implemented
               "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
             )
           )
        )
      )
    )
  )
);

// TODO apply data type check over function values

Parameters

$CompanyID

int

the company id

$QuoteDetails

array

an associative array of task information.

Returns

int

QuoteInsertScheduleBlock

InsertScheduleBlock(int $CompanyID, int $QuoteNo, 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

$QuoteNo

int

the quote 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 $QuoteNo = 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 Quotes whether a specific number is supplied or not.

Parameters

$CompanyID

int

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

$QuoteNo = null

int

The Quote 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

QuoteMerge

Merge(int $CompanyID, int $QuoteNo, int $JobNo) : bool
StaticNot Implemented

This function merges a quote in to a job

Parameters

$CompanyID

int

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

$QuoteNo

int

The quote to merge from

$JobNo

int

the job to merge to

Returns

bool

QuoteRetrieve

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

This function retrieves a quote with a specific number

uses \QuoteHandler::RetrieveList()

Parameters

$CompanyID

int

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

$QuoteNo

int

The quote Number to retrieve

Returns

array

QuoteRetrieveAllocated

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

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

uses \QuoteHandler::RetrieveList()

Parameters

$CompanyID

int

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

$Detail = true

bool

The detail of the quote object. 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}

$SortAsc = true

bool

which direction to sort the results

Returns

array

QuoteRetrieveAttachmentKey

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

Retrieve an attachment key for the specified quote. 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

$QuoteNo

int

the quote 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

QuoteRetrieveAttachments

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

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

Parameters

$CompanyID

int

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

$QuoteNo

int

The quote to retrieve attachments for

Returns

array

QuoteRetrieveDepartments

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

This function retrieves a list of departments for a Quote

Parameters

$CompanyID

int

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

$QuoteNo

int

The Quote Number.

Returns

array

QuoteRetrieveList

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

This function retrieves details on the provided list of quote numbers

used_by \EformsHandler::RetrieveProject()
used_by \QuoteHandler::SearchOpen()
used_by \QuoteHandler::SearchClosed()
used_by \QuoteHandler::Search()
used_by \QuoteHandler::SearchFields()
used_by \QuoteHandler::Retrieve()
used_by \QuoteHandler::RetrieveAllocated()

Parameters

$CompanyID

int

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

$QuoteNos

array

list of Quote Numbers to search for.

$Detail = null

array

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

$StaffID = null

int

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

Returns

array

QuoteRetrieveSchedules

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

Parameters

$QuoteNo

int

The quote to retrieve Schedules for.

$DepartmentNo

int

The department to retrieve Schedules for.

$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

QuoteSearchClosed

SearchClosed(int $CompanyID, array $Detail = null, int $CustomerID = null, int $Limit = 10, int $Offset = 0, bool $SortAsc = true) : array
Static

This function searches for the list of quotes are archived.

uses \QuoteHandler::RetrieveList()

Parameters

$CompanyID

int

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

$Detail = null

array

The detail of the quote object. Null/Empty will ignore this parameter

$CustomerID = null

int

the customer id, Empty / Null returns all customers

$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

Returns

array

QuoteSearchFields

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

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

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

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

uses \QuoteHandler::RetrieveList()

Parameters

$CompanyID

int

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

$Detail = null

array

The detail of the quote object. Null/Empty will ignore this parameter

$SearchTerms = array()

array

An associative array of Search Fields[key] and their search terms [value]

$StartDate = null

string

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

$EndDate = null

string

Date end (inclusive) to search for quotes. 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

Returns

array

QuoteSearchOpen

SearchOpen(int $CompanyID, array $Detail = null, int $CustomerID = null, int $Limit = 10, int $Offset = 0, bool $SortAsc = true) : array
Static

This function searches for the list of open quotes

uses \QuoteHandler::RetrieveList()

Parameters

$CompanyID

int

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

$Detail = null

array

The detail of the quote object. Null/Empty will ignore this parameter

$CustomerID = null

int

the customer id, Empty / Null returns all customers

$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

Returns

array

QuoteUpdate

Update(int $CompanyID, int $QuoteNo, array $QuoteDetails) : bool
Static
<?php
$QuoteDetails =
array(
"CustomerID"=>0,
"CustomerContractID"=>0,
"OrderNo"=>0,
"RequestNo"=>"",
"Description"=>"",
"Notes"=>"",
"IssuedDate"=>"Y-m-d",
"ExpiryDate"=>"Y-m-d",
"QuoteStage"=>0, // 0 = In-Progress, 1 = Complete, 2 = Approved
"Forecast"=> array ( "Year"=>2012 , "Month"=> 12 , "Percent"=>50 ),
"SiteID"=>0,
"TagIDs"=>array(), // empty removes all, tags id adds to list
"Type"=>0, //0 = Project Job, 1 = Service.
"SalesPerson"=>0,
"ProjectManager"=>0,
"StatusID"=>0,
"ClearSections"=>false,
"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 lin
         "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"=>"",
               "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
             )
           )
        )
      )
    )
  )
);
?>

Parameters

$CompanyID

int

the company id

$QuoteNo

int

the quote to update

$QuoteDetails

array

an associative array of task information.

Returns

bool