Difference between revisions of "Create Jobs"

From MyMobileWorkers API
Jump to: navigation, search
(→‎Java 1.8 differences)
Line 293: Line 293:
 
== Java 1.8 differences ==
 
== Java 1.8 differences ==
  
−
In order to use this call with our new Java 1.8 API there are 2 differences which need to be factored in.
+
In order to use this call with our new Java 1.8 API there are changes to 2 field names.
  
  
 
{| border="1" class="wikitable"
 
{| border="1" class="wikitable"
 
|+ New field names (for both JSON or multi-part):
 
|+ New field names (for both JSON or multi-part):
−
! colspan="4" | Standard Fields
+
! colspan="5" | Standard Fields
 
|-
 
|-
 
! Old Field
 
! Old Field

Revision as of 16:27, 29 September 2020

Contents

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:

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

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

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

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 field names (for both JSON or multi-part):
Standard 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

Example Input

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

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

Example Curl Requests

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

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

Responses

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=1176’
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox