View source for Create Jobs


== Summary ==

The create job method accepts an array of jobs to be added to the system. 
A job can be created via two different methods - either as multi-part form data with a JSON file attached and the API key as a parameter, or as JSON content on it's own, with the API key supplied within the JSON.

The timeslot of a job can be inputted either as a timeslot (datetime) or separately as a job_date and a job_time separately. This caters for jobs which may have a listed day but not a specified time.

If the update_existing param is set then any existing jobs will be updated in the system.
If set to false or not provided then any job where the job number is not unique will be rejected.

If validate_only is set the jobs will only be validated but not actually inserted. This can be used to check an entire dataset for errors before submitting.

When creating a job, the following formats are allowed date/time:
*[[Datetime Formats]]

==== Multi Part Form Data ====
{| border="1" class="wikitable"

! Create Job - Multi Part Form
! colspan="2" | 
|-
!  URL
| colspan="2" | https://base_url/api_path/version/jobs
|-
! Type
| colspan="2" |POST
|-
! Params:
| api_key || required 
|-
! 
| file || required
|-
! 
| update_existing || optional (default = false)
|-
! 
| validate_only || optional (default = false)
|-
! Response
| colspan="2" | JSON
|}

==== JSON As Body ====
{| border="1" class="wikitable"
! Create Job - JSON
! colspan="2" | 
|-
!  URL
| colspan="2" | https://base_url/api_path/version/jobs
|-
! Type
| colspan="2" |POST
|-
! 
| JSON <br /> {key, validate_only(optional), update_existing(optional), jobs[]}   ||| required    
|-
! Response
| colspan="2" | JSON
|}

== JSON Contents ==

The JSON is either passed in the post as the "file", or on its own as the "body".

{| border="1" class="wikitable"
|+ Standard fields (for both JSON or multi-part):
! colspan="4" | Standard Fields
|-
! Field
! Expected Data
! Notes
! Required
|-
! job_number
| varchar(45)
| must be unique
|| &#10003;
|-
! external_id
| varchar(45) 
|
|
|- 
! address_1
| varchar(45) 
|
| &#10003;
|- 
! address_2
| varchar(45) |||
|
|- 
! address_3
| varchar(45) |||
|
|- 
! address_4
| varchar(45) |||
|
|- 
! postcode
| varchar(45) 
|
| &#10003;
|- 
! contact_name
| varchar(45) 
|
| &#10003;
|-
! contact_number_1 
| varchar(45) (7, 10 or 11 digits) 
|
|
|- 
! contact_number_2 
| varchar(45) (7, 10 or 11 digits) 
|
|
|- 
! contact_number_3 
| varchar(45) (7, 10 or 11 digits) 
|
|
|- 
! timeslot
| datetime
| or separate date & time
|| 
|- 
! date
| yyyy-MM-dd
| or combined date & time as timeslot
|
|- 
! time
| HH:mm:ss
| or combined date & time as timeslot
|
|- 
! special_instructions
| text
|
The HTML tags <nowiki><br> <ol> <ul> <li></nowiki> are considered to be valid within special_instructions and will adjust the layout accordingly
|
|- 
! duration
| integer (minutes)
| 
|
|- 
! type
| Workflow name
| Type of job. Legacy customers use "repair", "gassafe" or "podc". New customers should use the exact case when referring to template names.
| &#10003;
|- 
! branch
| {"name":"<branchname>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
|
|
|- 
! mobile_user
| {"username":"<username>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
| or route
|
|- 
! route
| {"route_code":"<routecode>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
| or mobile_user
|
|-
! priority
| {"priority_name":"prioritytext"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
|
|- 
! weight
| float (in quotes) ||
|
|- 
! customer
| {"name":"<customer name>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>||
|
|- 
! product
| varchar(255)
| if applicable 
|
|- 
! task
| varchar(255) 
| if applicable 
|
|-
! assets
| array of serial numbers - "assets":["123","456"] ||
|
|-
! gas_safe_inspection
| "gas_safe_inspection":[{"owner_name":"Fred Bloggs","owner_address_1":"16","owner_postcode":"MK11 1NZ"}]
| nested JSON object, see below
|
|-
! secondary_address
| "secondary_address":{"customer":{"name":"Audrey's"},"contact_name":"Audrey Roberts","address_1":"2 Coronation Street","postcode":"M10 9KC", "contact_number": "01610005292"}
| nested JSON object
|
|-
! custom_fields
| "custom_fields":[   {   "value_key":"AssignedHireGroup",   "value":"T10" }, {   "value_key":"AssignedVRM",  "value":"HiHo" }]
| nested JSON object
|
|-
! additional_addresses
| "additional_addresses":[   {   "order":1, "contact_name":"Craig Purssey - Ascot Cab Company", "address_1":"1 - 3 Blackhorse Road", "address_2":" London",  "address_3":"", "address_4":"", "postcode":"SE8 5HY", "contact_number":"020 7732 1120"}]
| nested JSON object
|
|-
! job_positions
|  "job_positions": {"lat": "51.28028972635642","lng": "51.28028972635642"}
| nested JSON object
|
|-



{| border="1" class="wikitable"
|+ Gas Safe (nested) object:

! colspan="3" | Standard Fields
|-
! Field
! Expected Data
! Required
|-
! owner_title
| varchar(45) || 
|- 
! owner_name
| varchar(45) || &#10003;
|- 
! owner_address_1
| varchar(45) || &#10003;
|- 
! owner_address_2
| varchar(45) || 
|- 
! owner_address_3
| varchar(45) || 
|- 
! owner_address_4
| varchar(45) || 
|-
! owner_postcode
| varchar(45) || &#10003;
|-  
! owner_contact_number
| varchar(45) (7, 10 or 11 digits) || 
|- 
! owner_email
| varchar(255) || 
|-
! customer_email
| varchar(255) || 
|- 

{| border="1" class="wikitable"
|+ Fields exclusive to JSON body format:

! colspan="3" | Standard Fields
|-
! Field
! Expected Data
! Required
|-
! key
| string - company api key || &#10003;
|-
! update_existing
| boolean ||
|- 
! validate_only
| boolean ||
|- 
|}

== Example Input ==

==== Multi Part Form Data ====

<source lang="java">
{"jobs":[{
"job_number":"1813325",
"address_1":"16",
"address_2":"Willey Court",
"address_3":"Galley Hill,Stony Stratford",
"contact_name":"Joe Bloggs",
"contact_number_1":"0770999999",
"mobile_user":{"username":"Unassigned_Jobs_WCS"},
"postcode":"MK11 1NZ",
"special_instructions":"null",
"route":{"route_code":"BLACKPOOL AM"},
"timeslot":"2013-09-12 23:54:39",
"weight":"100",
"type":"gassafe",
"gas_safe_inspection":[{"owner_name":"Fred Bloggs","owner_address_1":"16","owner_postcode":"MK11 1NZ"}]
}]}
</source>

==== JSON As Body ====

<source lang="java">
{
   "key":"test",
   "validate_only":"true",
   "update_existing":"true",
   "jobs":[
      {
         "job_number":"sss05",
         "external_id":"hello",
         "address_1":"Rover Lane",
         "address_2":"Glasgow",
         "contact_name":"Joe Bloggs",
         "contact_number_1":"0770999999",
         "contact_number_2":"",
         "mobile_user":{
            "username":"_test32"
         },
         "postcode":"G71 8TS",
         "type":"podc",
         "weight":"100",
         "route":{
            "route_code":"BLACKPOOL AM"
         },
         "timeslot":"2013-09-15 17:54:39",
         "special_instructions":"Door bell is faulty so knock on the door",
         "repair_description":"Replace U Bend",
         "assets":[
            "serialNo456",
            "serialNo789"
         ],
         "gas_safe_inspection":[
            {
               "owner_name":"leej",
               "owner_address_1":"exampleAddress",
               "owner_postcode":"examplePostcode"
            }
         ]
      }
   ]
}
</source>

== Example Curl Requests ==

==== Multi Part Form Data ====

<source lang="php">
curl -F validate_only=false -F update_existing=true -F api_key=lee_test -F file=@/Users/user/Desktop/webAPICurling/create_job.txt  https://api.mymobileworkers.com:8181/api/1/jobs
</source>

==== JSON As Body ====

<source lang="php">
curl -X POST -H "Content-Type: application/json" -d '{"key":"test", "validate_only":"true", "update_existing":"true", "jobs":[{
"job_number":"sss05",
"external_id":"hello",
"address_1":"Rover Lane",
"address_2":"Glasgow",
"contact_name":"Joe Bloggs",
"contact_number_1":"0770999999",
"contact_number_2":"",
"mobile_user":{"username":"Darren_test32"},
"postcode":"G71 8TS","type":"podc",
"timeslot":"2013-09-15 17:54:39",
"special_instructions":"Door bell is faulty so knock on the door",
"repair_description":"Replace U Bend",
"assets":["serialNo456","serialNo789"]
}]}' https://api.mymobileworkers.com:8181/api/1/jobs
</source>

== Responses ==

=== Example JSON ===

<source lang="java">
{
	"successful":
	[
		{"job_number":"A0103"},
		{"job_number":"A0245"}
	],
	"failed":
	[
		{
			"job_number":"A0384",
			"errors": 
			[
				{
					"error_code":"WAJ003",
					"error_msg":"Job number already exists."
				}
			]
		}
	]
}
</source>