My Project
Api Services (Version 2)

Table of Contents

BookAJim API service provides services for communicating with Jims Franchise Management System (FMS) in order to book a job or enquiry to be a franchisee. The API services will take parameters from the entry screen, e.g. address, client name, contact detail and required service, then allocate the job to the available franchisee based on some factors

UPDATE

Two more functions for creating new booking and enquiry which log more detail on source for data tracking

Please note that the CreateNewBooking and CreateNewEnquiry functions are still available with a simple source Id given in Lead Source table.

INSTRUCTION

Connections

Following are the methods offer by BookAJim API for the connections

  1. Connecting via Visual Studio If you are developing your website by Visual Studio, you can access the BookAJim API by adding the Service Reference with the following URL

    http://newbookajim.jims.net:9090/BookAJimApiService/v2

  2. Connecting via Javascript The BookAJim Api service also offer a Javascript connection with JSON, URL is http://newbookajim.jims.net:9090/BookAJimApiService/v2/json/ following is an example for how to access the Api service
function CreateNewBooking() {
var xmlHttpRequest = new XMLHttpRequest();
var url = "http://newbookajim.jims.net:9090/BookAJimApiService/v2/json/CreateNewBooking?divisionId={your division id}";
xmlHttpRequest.open("GET", url, true);
xmlHttpRequest.onreadystatechange = function() {
if (xmlHttpRequest.readyState == 4 && xmlHttpRequest.status == 200) {
var responseText = xmlHttpRequest.responseText;
var jsonData = JSON.parse(responseText);
booking = jsonData.CreateNewBookingResult;
}
};
xmlHttpRequest.send(null);
}
function ValidateAddress(){
var xmlHttpRequest = new XMLHttpRequest();
var url = "http://newbookajim.jims.net:9090/BookAJimApiService/v2/json/ValidateAddress?bookingId={booking.Id}&requestedAddress={address}";
xmlHttpRequest.open("GET", url, true);
xmlHttpRequest.onreadystatechange = function() {
if (xmlHttpRequest.readyState == 4 && xmlHttpRequest.status == 200) {
var responseText = xmlHttpRequest.responseText;
var jsonData = JSON.parse(responseText);
booking = jsonData.CreateNewBookingResult;
}
};
xmlHttpRequest.send(null);
}

NOTE: For security reason, please provide the URL (e.g. http://yourwebsite.com.au) which will access the API services to Jim's Infotech, so it can be configured on the server. Otherwise you will not be able to access the API services.

BEFORE YOU GO

The BookAJim API Server may down or timeout some time due to the database or network traffic condition, please ensure you run the following to confirm the API is up and running before going ahead with the function

IsDatabaseRunning

WEB SERVICE FOR ONLINE QUOTE

Step 1: Create new booking object

CreateNewBooking

Parameter Type Description
DivisionId integer Id of your division
SourceId integer Id of the booking source
Return Type Description
Id integer Booking id
DivisionId integer Division id, should be same as what you passed in

CreateNewBookingWithTrackData

Parameter Type Description
DivisionId integer Id of your division
SourceId integer Set this to 0
JimsProvider string Jim's leads provider (e.g. Webtron, TMC...)
JimsProperty string Jim's digital property (e.g. jimsmowing.com.au, jimsdogwash.com.au...)
UtmSource string Campaign Source (e.g. Google, Facebook...)
UtmMedium string Campaign Medium (e.g. ppc...)
UtmCampaign string Campaign Name (e.g. spring-sale...)
UtmTerm string Campaign Term (e.g. mow-my-lawn...)
UtmContent string Campaign Content (e.g. call2action1, call2action2...)
Return Type Description
Id integer Booking id
DivisionId integer Division id, should be same as what you passed in

It is always the first step for creating a new booking object. By passing the DivisionId into the service, there will be a list of available services included in the returned Booking instance.

The BookingStatus is now set to AddressRequired.

Step 2: Validate address

ValidateAddress

Parameter Type Description
BookingId integer Booking Id return from CreateNewBooking service
RequestedAddress string Full address with unit number, street number, street name, suburb, postcode and state; Expected Format of "RequestedAddress": [UnitNumber][ForwardSlash](Only if there is a unit number)[StreetNumber][Space][StreetName][Comma][Space][StreetName][Comma][Space][Suburb][Space][PostCode][Comma][Space][State]

Example of "RequestedAddress": 32/8 Main St, Greensborough 3088, VIC

Return Type Description
BookingStatus integer The status of the address validation. See BookingStatus in step 5

Once the address has been entered, it must be validated by the ValidateAddress service before going any further. You need to pass the Booking Id that you receive from CreateNewBooking Service, then the service will return the Booking instance with the validated address information and appropreiate booking status

There are two values in Booking.Address indicating the result of the address valiadation: Booking.Address.IsCompleted and Booking.Address.AddressDescription.

The IsCompleted value should be True if the address is valid for booking job, otherwise it should be False. You can also see the reason by looking at the AddressDescription value.

The BookingStatus is set to OtherDetailsRequired if the address is ready to make a booking, so client should then be prompted to enter their contact details.

If the BookingStatus is set to AddressUnrecognized, therefore the address is invalid. However booking a job is still allowed if the Booking.CallCentreEmail is not empty in the case, this makes the entered job to be followed up by the Call Centre, so client should be advised to put in their valid mobile or any contact number for the call back.

Step 3: Select service(s)

GetServices

Parameter Type Description
DivisionId integer Id of your division

For displaying the services your page, you need to get the availabile services via GetServices service with Division Id. You can actually call the service at anytime, e.g. before you load the page, therefore only the Division Id is required.

This Api services will return you a list of service with service Id, service name and the service code.

The new BookAJim support multiple services to be selected, however only one service will be used for the job allocation, the rest will be mentioned in the lead message when SMS the franchisees.

NOTE: If you would like to have a specify list of services, please contact infot.nosp@m.ech@.nosp@m.jims..nosp@m.net for more details.

Step 4: Allocating job to Franchisee

DoAllocation

Parameter Type Description
BookingId integer Id for your booking
SelectedServiceId integer Required service Id. Must be populated for the allocation, therefore job will be allocated based on this service.
ClientFirstName string Client first name
ClientSurname string Client surname
Email string Client email
Mobile string Client contactable mobile
PhoneNumber string Alternative phone number, can be home phone, mobile or work phone
IsSubscribed boolean Wether the client would like to subscribe for Newsletter, special offers and survey
ExtraSelectedServices string If client would like to require more services, those services must be passed by the extraSelectedServices argument. the extraSelectedServices is a string field with all Service.Code with comma separator.
Comments string Comments from the client.
ExpectedCallbackDateTimestring A specify callback time that is required by the client. Franchisee who is working on that time will have an advantage on receiving the lead. Please leave it blank or empty string if it is not specified.
Return Type Description
BookingStatus integer The status of the address validation. See BookingStatus in step 5

It is an important Api service for the whole booking process, job must be allocated to franchisee by the DoAllocation service before logging the job into database. The DoAllocation process takes the client details and the selected services, then allocates the job to the soonest available franchisee based on rules and factors.

Step 5: Read the allocation result

The allocation result is stated by the following BookingStatus:

Result Description
ReadyForBooking Job is allocated successfully, the BookJob service in Step 7 should be called then.
ConfirmingPrevious Job is allocated successfully, however a previous job has been found and the system cannot identify whether this client has had the service before.

So the client should be prompted to confirm if they have had the same service previously. Unserviced | Job cannot be allocated because no available franchisee can be found around that area. The client can then nominate whether the nearby franchisee should be notified (set the Bookings.IsNotifyNearbyFranchise to true) or do nothing. Please leave the BookingStatus as Unserviced. FollowUpByCallCentre | Job cannot be allocated due to an unrecognized address, however the client details have been forwarded to the Call Centre, so client should be contacted to follow up the quote.

Step 6: Clarify for a previous client

If previous lead is found for the job and can be identified as a previous client, then the job will be allocated to the previous franchisee autmotically. However if previous lead is found but unable to be identifed as a previous client, e.g. the client name is different, then the BookingStatus will be set to ConfirmingPrevious, therefore client should be prompted to answer Yes, No or Unsure to clarify if they are the previous client

If client clarify that they ARE previous client, then call

IsPrevoiusClient

Parameter Type Description
BookingId integer Id of your booking
Return Type Description
BookingStatus integer The BookingStatus is then set to ReadyForBooking.

If client clarify that they ARE NOT previous client, then call

IsNotPreviousClient

Parameter Type Description
BookingId integer Id of your booking
Return Type Description
BookingStatus integer The BookingStatus is then set to ReadyForBooking.

If client is UNSURE if they are previous client, then call

UnsureForPreviousClient

Parameter Type Description
BookingId integer Id of your booking
Return Type Description
BookingStatus integer The BookingStatus is then set to ReadyForBooking.

Step 7: Book the job

BookJob

Parameter Type Description
BookingId integer Id for your booking
Comments string Comment from client
GoogleClickId string GCLID from Google.
NotifyNearbyFranchisee boolean This value must be TRUE or franchisee won't receive any SMS for the lead; For testing purpose
IsTest boolean This value must be FALSE or job will not be logged into FMS; For testing purpose
Return Type Description
BookingStatus integer After the booking is made, the BookingStatus is set to Booked. This means the job is booked successfully. You can then find and display the Callback Message from Booking.SelectedFranchisee.CallBackMessage

If the BookingStatus is set to TooSoon, that means the same service was booked by the same address and client in the last 24 hours, and therefore the job cannot be booked.

REFERENCE

Lead Source

Id Lead source
1 Newspaper Metro
2 Referral by Franchisee
4 Referral by Client
5 TV
7 Leaflet Drop
8 Yellow Pages Online
12 Yellow Pages Local
13 Other
18 White Pages
22 Website Divisional
29 Expo
34 Gift Voucher
47 Yellow Pages Connect
61 Jim's User
66 White pages online
67 Website National
85 Directory assistance
87 Website; Unspecified
88 Van/Trailer/Truck/Skip Bin
98 Local Business Directory
99 Hills Deal
114 Seek
117 True Local
122 Newspaper Local
125 Yellow Pages Metro
135 Unserviced Job
136 Fse Card or Magnet
146 Yellow Pages in Car
153 Radio
171 None
173 Direct Connect
176 Myerone
179 Knows Jim's
191 Rentaskip
193 Google
194 Trade Me
203 Billboard
205 Facebook
231 Rocklive
238 Realestate.com.au
239 Mowing Online Trial
242 Bookajim App
245 HI Pages
246 Betta Electrical
248 Drink Coaster
251 SMS to call us
252 Online Manual Entry
253 Live Chat Monitoring
254 Vuly
255 Connect Now
256 Red Energy

Following is the lead source table

Note this service must be called before the BookJob service is called.

WEB SERVICE FOR FRANCHISEE ENQUIRY

Step 1: Create new enquiry object

CreateNewEnquiry

Parameter Type Description
DivisionId integer Id of your division
SourceId integer Id of the booking source
Return Type Description
Id integer Enquiry id
DivisionId integer Division id, should be same as what you passed in

CreateNewEnquiryWithTrackData

Parameter Type Description
DivisionId integer Id of your division
SourceId integer Set this to 0
JimsProvider string Jim's leads provider (e.g. Webtron, TMC...)
JimsProperty string Jim's digital property (e.g. jimsmowing.com.au, jimsdogwash.com.au...)
UtmSource string Campaign Source (e.g. Google, Facebook...)
UtmMedium string Campaign Medium (e.g. ppc...)
UtmCampaign string Campaign Name (e.g. spring-sale...)
UtmTerm string Campaign Term (e.g. mow-my-lawn...)
UtmContent string Campaign Content (e.g. call2action1, call2action2...)
Return Type Description
Id integer Enquiry id
DivisionId integer Division id, should be same as what you passed in

It is always the first step for creating a new enquiry object.

Step 2: Validate Address

ValidateAddress

Parameter Type Description
BookingId integer Enquiry Id return from CreateNewBooking service
RequestedAddress string Full address with unit number, street number, street name, suburb, postcode and state
Return Type Description
BookingStatus integer The status of the address validation. See BookingStatus in step 4

Once the address has been entered, it must be validated by the ValidateAddress service before going any further. The Booking Id that you receive from the CreateNewBooking Service is required for the server, then a Booking instance with a validated address information and the appropreiate booking status wil be returned.

There are two values in Booking.Address indicating the result of the address valiadation: Booking.Address.IsCompleted and Booking.Address.AddressDescription.

The IsCompleted value should be True if the address is valid for booking job, otherwise it should be False. You can also see the reason by looking at the AddressDescription value.

The BookingStatus is set to OtherDetailsRequired if the address is ready to make a booking, so client should then be prompted to enter their contact details.

If the BookingStatus is set to AddressUnrecognized, therefore the address is invalid. However booking a job is still allowed if the Booking.CallCentreEmail is not empty in the case, this makes the entered job to be followed up by the Call Centre, so client should be advised to put in their valid mobile or any contact number for the call back.

Step 3: Allocating the enquiry to Franchisor

AllocateEnquiry

Parameter Type Description
EnquiryId integer Enquiry Id return from CreateNewBooking service

It is an important Api service for the whole process which takes the enquiry details, and allocates to the closest regional franchisor or divisional franchisor if none is found.

Step 4: Read the allocation result

The allocation result is stated by the following BookingStatus:

Result Description
ReadyForBooking Enquiry is allocated successfully, the Send enquiry service in Step 6 should be called then.
ConfirmingPrevious Enquiry is allocated successfully, however a previous enquiry has been found but cannot be identifed whether this client has had the enquiry before.

So the client should be prompted to confirm if they have had the same enquiry previously.

Step 5: Previous enquiry clarification

If a previous enquiry is found for the entered address, user should be prompted to confirm if they had enquired previously.

System assume the enquiry is always the previous enquiry, so nothing should be done in this step if it is correct.

However if client selected they have not had any enquiry previously, the following service should be called to mark the enquiry as a NEW enquiry.

IsNotPreviouslyEnquiry

Parameter Type Description
EnquiryId integer Enquiry Id return from CreateNewBooking service
Return Type Description
BookingStatus integer The EnquiryStatus is then set to ReadyForBooking.

Step 6: Submit the enquiry

SendEnquiry

Parameter Type Description
EnquiryId integer Id for your enquiry
ClientFIrstName string Client First Name
ClientSurname string Client Surname
Email string Client Email
Mobile string Client contactable mobile number
Comments string Comment from client
SendEnquiry boolean This value must be TRUE or franchisee won't receive any SMS for the enquiry; For testing purpose

CLASSES

Booking

Property Type Description
Id integer Id of your booking; Created automatically when CreateNewBooking is called
DivisionId integer Id of your division
LeadId integer Id of the booked lead
AllocationDecision Decision The allocated information, included the selected franchisee. Refer to
SelectedFranchise Franchise Selected Franchise. Refer to
Address Address Address information, including street number, suburb, postcode, geo information. Refer to
Client Person Client information, including Name, Phone number, email. Refer to
ServiceId integer Id of selected service
ExtraServicesCode string Services code that required additionally, separated by comma
BookingStatus BookingStatus Booking status
Comments string Comments from client
ShouldNotifyFranchisees boolean Boolean value to indicate should the nearby franchisee be notified; Default to true
GoogleClickId string The glcid from Google
ExpectedCallBackDateTime datetime Date and time that client required for a call back from Franchisee.
IsPreviousLead boolean Indicate whether the lead comes from a previous client (read-only)
IsFranchiseeEnquiry boolean Indicate whether it is a franchisee enquiry (for franchisee enquiry only)

Decision

Property Type Description
Id integer Id of this particular allocation
IfNew Franchise Selected Franchisee for new lead, this will be populated to Booking.SelectedFranchise if it is a new lead
IfPrevious Franchise Selected Franchisee for prevoius lead, this will be populated to Booking.SelectedFranchise if lead comes from a previous client
PrevoiusLeadId integer Id of the previous lead if any
People Person Information of the previous client
Notes List of Note List of notes for prevoius lead
PreviousLeads List of lead All leads information required from this address

Franchise

Property Type Description
Id integer Id of this particular allocation
IfNew Franchise Selected Franchisee for new lead, this will be populated to Booking.SelectedFranchise if it is a new lead
IfPrevious Franchise Selected Franchisee for prevoius lead, this will be populated to Booking.SelectedFranchise if lead comes from a previous client
PrevoiusLeadId integer Id of the previous lead if any
People Person Information of the previous client
Notes List of Note List of notes for prevoius lead
PreviousLeads List of lead All leads information required from this address

Address

Property Type Description
Id integer Id of the address
IsComplete boolean Indicate if the address is complete and valid
AddressDescription string Description for the address

Person

Property Type Description
Id integer Id of the person
Title string Person title
FirstName string Person first name
Surname string Person surname
FullName string Title + FirstName + Surname (read-only)
Mobile string Contactable mobile number
HomePhone integer Home phone or alternative contact number
Email string Email address
IsSubscribed boolean Indicate wether the client subscribe to newsletter, special offers and surveys

Note

Property Type Description
Id integer Id of the note
NoteTypeId integer Id of the note type
LeadId integer Relevant lead id
Text string Text body

Lead

Property Type Description
Id integer Id of the lead
DivisionId integer Id of the lead division
CurrentBusiness Franchise Allocated franchisee for the lead
Address Address Address that required the lead
Client Person Client who required the lead
LeadStatus LeadStatus Status of the lead
CurrentService Service Required service

Service

Property Type Description
Id integer Id of the serivce
FriendlyName string Service name
Code string Service code
IsSelected boolean Indicate wether the service is selected. Used when passing to the allocation process

Booking Status

Id status Description
1 AddressRequired Initial status for requiring address
2 AddresUnrecognized Entered address cannot be recognized
3 OtherDetailsRequired The entered address is accepted, now required more information
4 Unserviced Job goes unserviced.
5 ConfirmingPrevious Previous job found in the system for the same address but not identical as a same client, so it needs to be clarified
6 ReadyForBooking Job allocated, the lead is ready to be booked
7 Booked Job has been booked
8 Cancelled Job has been cancelled
9 ClientIsRedFlag There is an issue with the client, better to contact the call centre for further assistance
10 TooSoon A same division service has been booked within 12 hours, lead cannot be booked.
11 FollowUpByCallCentre Entered address is not recognized, so the booking is sent to the local call centre for the follow up. Call Centre may contact the client to clarify the details.

Lead Status

Id status Description
1 Ok Normal status
2 Suspended Lead is suspended
3 Cancel Lead is cancelled
4 Unserviced Unserviced lead
Generated by   doxygen 1.8.11