Difference between revisions of "Create Jobs"

From MyMobileWorkers API
Jump to: navigation, search
(→‎JSON Contents)
(→‎JSON Contents)
 
(24 intermediate revisions by 4 users not shown)
Line 5: Line 5:
 
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.
 
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.
+
The timeslot of a job can be inputted either as a timeslot (datetime) or separately as a job_date and/or a job_time. 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 the update_existing param is set then any existing jobs will be updated in the system.
Line 63: Line 63:
 
== JSON Contents ==
 
== JSON Contents ==
  
−
{| border="1" class="wikitable"
+
The JSON is either passed in the post as the "file", or on its own as the "body".
−
| 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):
 
|+ Standard fields (for both JSON or multi-part):
−
! colspan="3" | Standard Fields
+
! colspan="4" | Standard Fields
 
|-
 
|-
 
! Field
 
! Field
 
! Expected Data
 
! Expected Data
 +
! Notes
 
! Required
 
! Required
 
|-
 
|-
 
! job_number
 
! job_number
−
| varchar(45) <br /><span style="font-size:80%; font-weight:normal">* must be unique</span>|| &#10003;
+
| varchar(45)
 +
| must be unique
 +
|| &#10003;
 
|-
 
|-
 
! external_id
 
! external_id
−
| varchar(45) ||
+
| varchar(45)  
 +
|
 +
|
 
|-  
 
|-  
 
! address_1
 
! address_1
−
| varchar(45) || &#10003;
+
| varchar(45)  
 +
|
 +
| &#10003;
 
|-  
 
|-  
 
! address_2
 
! address_2
−
| varchar(45) ||
+
| varchar(45) |||
 +
|
 
|-  
 
|-  
 
! address_3
 
! address_3
−
| varchar(45) ||  
+
| varchar(45) |||
 +
|
 
|-  
 
|-  
 
! address_4
 
! address_4
−
| varchar(45) ||  
+
| varchar(45) |||
 +
|
 
|-  
 
|-  
 
! postcode
 
! postcode
−
| varchar(45) || &#10003;
+
| varchar(45)  
 +
|
 +
| &#10003;
 
|-  
 
|-  
 
! contact_name
 
! contact_name
−
| varchar(45) || &#10003;
+
| varchar(45)  
 +
|
 +
| &#10003;
 
|-
 
|-
 
! contact_number_1  
 
! contact_number_1  
−
| varchar(45) (7, 10 or 11 digits) ||
+
| varchar(45) (7, 10 or 11 digits)  
 +
|
 +
| &#10003;
 
|-  
 
|-  
 
! contact_number_2  
 
! contact_number_2  
−
| varchar(45) (7, 10 or 11 digits) ||
+
| varchar(45) (7, 10 or 11 digits)  
 +
|
 +
|
 
|-  
 
|-  
 
! contact_number_3  
 
! contact_number_3  
−
| varchar(45) (7, 10 or 11 digits) ||
+
| varchar(45) (7, 10 or 11 digits)  
 +
|
 +
|
 
|-  
 
|-  
−
! 'timeslot' OR 'date'/'time'
+
! email
−
| datetime(timeslot) OR date(yyyy-MM-dd)/time(HH:mm:ss)  ||  
+
| varchar(45)
 +
|
 +
|
 +
|-
 +
! 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
 
! special_instructions
−
| text - The following HTML tags <br> <ol> <ul> <li> are considered to be valid within special_instructions and will adjust the layout accordingly||  
+
| 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 (minutes)
+
! duration
−
| integer ||  
+
| integer (minutes)
 +
|  
 +
|
 
|-  
 
|-  
−
! type <br />(type of job)
+
! type
−
| Workflow name. Note- Legacy customers can continue to use "repair", "gassafe" and "podc". New customers should use the exact case when referring to template names || &#10003;
+
| 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
 
! branch
−
| {"name":"<branchname>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>||
+
| {"name":"<branchname>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
 +
|
 +
|
 
|-  
 
|-  
 
! mobile_user
 
! mobile_user
−
| {"username":"<username>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>||
+
| {"username":"<username>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
 +
| or route
 +
|
 
|-  
 
|-  
 
! route
 
! route
−
| {"route_code":"<routecode>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>||
+
| {"route_code":"<routecode>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
 +
| or mobile_user
 +
|
 
|-
 
|-
 +
! routeOrder
 +
| integer (route order for the job)
 +
|
 +
|-
 
! priority
 
! priority
−
| {"priority_name":"prioritytext"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>||
+
| {"priority_name":"prioritytext"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
 +
|
 
|-  
 
|-  
 
! weight
 
! weight
−
| float (in quotes) ||  
+
| float (in quotes) ||
 +
|
 
|-  
 
|-  
 
! customer
 
! customer
 
| {"name":"<customer name>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>||
 
| {"name":"<customer name>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>||
 +
|
 
|-  
 
|-  
−
! product <br /><span style="font-size:80%; font-weight:normal">*If applicable</span>
+
! product
−
| varchar(255) ||  
+
| varchar(255)
 +
| if applicable
 +
|
 
|-  
 
|-  
−
! task<br /><span style="font-size:80%; font-weight:normal">*If applicable</span>
+
! task
−
| varchar(255) ||  
+
| varchar(255)  
 +
| if applicable
 +
|
 
|-
 
|-
 
! assets
 
! assets
 
| array of serial numbers - "assets":["123","456"] ||
 
| 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"
 
{| border="1" class="wikitable"
Line 204: Line 293:
 
| boolean ||
 
| boolean ||
 
|-  
 
|-  
 +
|}
 +
 +
== Java 1.8 differences ==
 +
 +
In order to use this call with our new Java 1.8 API there are changes to 2 field names.
 +
 +
{| border="1" class="wikitable"
 +
! colspan="5" | New Fields
 +
|-
 +
! Old Field
 +
! New Field
 +
! Expected Data
 +
! Notes
 +
! Required
 +
|-
 +
! date
 +
! job_date
 +
| yyyy-MM-dd
 +
| or combined date & time as timeslot
 +
|
 +
|-
 +
! time
 +
! job_time
 +
| HH:mm:ss
 +
| or combined date & time as timeslot
 +
|
 +
|-
 
|}
 
|}
  
Line 244: Line 360:
 
         "contact_name":"Joe Bloggs",
 
         "contact_name":"Joe Bloggs",
 
         "contact_number_1":"0770999999",
 
         "contact_number_1":"0770999999",
 +
        "email":"email@gmail.com",
 
         "contact_number_2":"",
 
         "contact_number_2":"",
 
         "mobile_user":{
 
         "mobile_user":{
Line 277: Line 394:
 
==== Multi Part Form Data ====
 
==== Multi Part Form Data ====
  
−
curl -F validate_only=false -F update_existing=true -F api_key=lee_test -F file=@/Users/user/Desktop/webAPICurling/create_job.txt  https://live.mymobileworkers.com:8181/api/1/jobs
+
<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 ====
 
==== JSON As Body ====
  
 +
<source lang="php">
 
curl -X POST -H "Content-Type: application/json" -d '{"key":"test", "validate_only":"true", "update_existing":"true", "jobs":[{
 
curl -X POST -H "Content-Type: application/json" -d '{"key":"test", "validate_only":"true", "update_existing":"true", "jobs":[{
 
"job_number":"sss05",
 
"job_number":"sss05",
Line 295: Line 415:
 
"repair_description":"Replace U Bend",
 
"repair_description":"Replace U Bend",
 
"assets":["serialNo456","serialNo789"]
 
"assets":["serialNo456","serialNo789"]
−
}]}' https://live.mymobileworkers.com:8181/api/1/jobs
+
}]}' https://api.mymobileworkers.com:8181/api/1/jobs
 +
</source>
  
 
== Responses ==
 
== Responses ==

Latest revision as of 09:52, 20 January 2023

Contents

[edit] 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/or a job_time. 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:

[edit] Multi Part Form Data

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

[edit] JSON As Body

Create Job - JSON
URL https://base_url/api_path/version/jobs
Type POST
JSON
{key, validate_only(optional), update_existing(optional), jobs[]} 		required
Response JSON

[edit] JSON Contents

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

Standard fields (for both JSON or multi-part):
Standard Fields
Field Expected Data Notes Required
job_number varchar(45) must be unique ✓
external_id varchar(45)
address_1 varchar(45) ✓
address_2 varchar(45)
address_3 varchar(45)
address_4 varchar(45)
postcode varchar(45) ✓
contact_name varchar(45) ✓
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)
email varchar(45)
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 <br> <ol> <ul> <li> 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. ✓
branch {"name":"<branchname>"}
*nested JSON object
mobile_user {"username":"<username>"}
*nested JSON object 		or route
route {"route_code":"<routecode>"}
*nested JSON object 		or mobile_user
routeOrder integer (route order for the job)
priority {"priority_name":"prioritytext"}
*nested JSON object
weight float (in quotes)
customer {"name":"<customer name>"}
*nested JSON object
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
Gas Safe (nested) object:
Standard Fields
Field Expected Data Required
owner_title varchar(45)
owner_name varchar(45) ✓
owner_address_1 varchar(45) ✓
owner_address_2 varchar(45)
owner_address_3 varchar(45)
owner_address_4 varchar(45)
owner_postcode varchar(45) ✓
owner_contact_number varchar(45) (7, 10 or 11 digits)
owner_email varchar(255)
customer_email varchar(255)
Fields exclusive to JSON body format:
Standard Fields
Field Expected Data Required
key string - company api key ✓
update_existing boolean
validate_only boolean

[edit] Java 1.8 differences

In order to use this call with our new Java 1.8 API there are changes to 2 field names.

New Fields
Old Field New Field Expected Data Notes Required
date job_date yyyy-MM-dd or combined date & time as timeslot
time job_time HH:mm:ss or combined date & time as timeslot

[edit] Example Input

[edit] Multi Part Form Data 

{"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"}]
}]}

[edit] JSON As Body 

{
   "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",
         "email":"email@gmail.com",
         "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"
            }
         ]
      }
   ]
}

[edit] Example Curl Requests

[edit] Multi Part Form Data 

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

[edit] JSON As Body 

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

[edit] Responses

[edit] Example JSON 

{
	"successful":
	[
		{"job_number":"A0103"},
		{"job_number":"A0245"}
	],
	"failed":
	[
		{
			"job_number":"A0384",
			"errors": 
			[
				{
					"error_code":"WAJ003",
					"error_msg":"Job number already exists."
				}
			]
		}
	]
}
Retrieved from ‘https://docs.mymobileworkers.com/index.php?title=Create_Jobs&oldid=1186’
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox