Difference between revisions of "Create Jobs"

From MyMobileWorkers API
Jump to: navigation, search
(→‎Summary)
(→‎JSON Contents)
 
(120 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
 
== Summary ==
 
== 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:
 +
*[[Datetime Formats]]
 +
 +
==== Multi Part Form Data ====
 
{| border="1" class="wikitable"
 
{| border="1" class="wikitable"
  
−
! Create Job
+
! Create Job - Multi Part Form
−
!  
+
! colspan="2" |
 
|-
 
|-
 
!  URL
 
!  URL
−
| colspan="2" | http://base_url/api_path/version/mobile_users
+
| colspan="2" | https://base_url/api_path/version/jobs
 
|-
 
|-
 
! Type
 
! Type
Line 19: Line 35:
 
!  
 
!  
 
| update_existing || optional (default = false)
 
| update_existing || optional (default = false)
 +
|-
 +
!
 +
| validate_only || optional (default = false)
 
|-
 
|-
 
! Response
 
! Response
Line 24: Line 43:
 
|}
 
|}
  
 +
==== 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
 +
|}
  
−
The create job method accepts an array of jobs to be added to the system. 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.
+
== JSON Contents ==
  
−
== JSON Parameters ==
+
The JSON is either passed in the post as the "file", or on its own as the "body".
  
 
{| border="1" class="wikitable"
 
{| border="1" class="wikitable"
−
|+ The JSON file is passed in the post as the "file"
+
|+ 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
 +
| 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) || &#10003;
+
| varchar(45) (7, 10 or 11 digits)
 +
|
 +
| &#10003;
 
|-  
 
|-  
−
! contact_number_2
+
! contact_number_2  
−
| varchar(45) ||
+
| varchar(45) (7, 10 or 11 digits)
 +
|
 +
|
 +
|-
 +
! contact_number_3
 +
| varchar(45) (7, 10 or 11 digits)
 +
|
 +
|
 +
|-
 +
! email
 +
| varchar(45)
 +
|
 +
|  
 
|-  
 
|-  
 
! timeslot
 
! timeslot
−
| datetime || &#10003;
+
| 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 ||  
+
| text
 +
|
 +
The HTML tags <nowiki><br> <ol> <ul> <li></nowiki> are considered to be valid within special_instructions and will adjust the layout accordingly
 +
|
 
|-  
 
|-  
−
! type <br />(type of job)
+
! duration
−
| "repair","podc","gassafe" || &#10003;
+
| integer (minutes)
 +
|  
 +
|
 
|-  
 
|-  
−
! mobile_user
+
! type
−
| "{"username":"<username>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>|| &#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;
 
|-  
 
|-  
−
! customer <br /><span style="font-size:80%; font-weight:normal">*must be a valid customer in MMW</span>
+
! branch
−
| varchar(45) ||  
+
| {"name":"<branchname>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
 +
|
 +
|
 
|-  
 
|-  
−
! colspan="3" | Repair Only Fields
+
! 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
 +
|
 
|-
 
|-
−
! product
+
! routeOrder
−
| varchar(255) ||  
+
| integer (route order for the job)
 +
|  
 
|-  
 
|-  
−
! fault
+
! priority
−
| varchar(255) ||  
+
| {"priority_name":"prioritytext"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>
 +
|
 
|-  
 
|-  
−
! colspan="3" | Gas Safe Only Fields
+
! 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
 
! owner_title
Line 111: Line 266:
 
|-   
 
|-   
 
! owner_contact_number
 
! owner_contact_number
−
| varchar(45) ||  
+
| varchar(45) (7, 10 or 11 digits) ||  
 
|-  
 
|-  
 
! owner_email
 
! owner_email
Line 118: Line 273:
 
! customer_email
 
! customer_email
 
| varchar(255) ||  
 
| 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 JSON ==
+
== 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
 +
|
 +
|-
 +
|}
 +
 
 +
== Example Input ==
 +
 
 +
==== Multi Part Form Data ====
  
 
<source lang="java">
 
<source lang="java">
 
{"jobs":[{
 
{"jobs":[{
−
"job_number":"SEJOB9",
+
"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",
 +
        "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"
 +
            }
 +
        ]
 +
      }
 +
  ]
 +
}
 +
</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_1":"Rover Lane",
 
"address_2":"Glasgow",
 
"address_2":"Glasgow",
Line 131: Line 409:
 
"contact_number_1":"0770999999",
 
"contact_number_1":"0770999999",
 
"contact_number_2":"",
 
"contact_number_2":"",
−
"mobile_user":{"username":"MOB_01"},
+
"mobile_user":{"username":"Darren_test32"},
−
"postcode":"G71 8TS","type":"repair",
+
"postcode":"G71 8TS","type":"podc",
−
"timeslot":"2013-04-09 17:54:39",
+
"timeslot":"2013-09-15 17:54:39",
 
"special_instructions":"Door bell is faulty so knock on the door",
 
"special_instructions":"Door bell is faulty so knock on the door",
−
"repair_description":"Replace U Bend"
+
"repair_description":"Replace U Bend",
−
}]}  
+
"assets":["serialNo456","serialNo789"]
−
 
+
}]}' https://api.mymobileworkers.com:8181/api/1/jobs
 
</source>
 
</source>
−
 
−
== Example curl request ==
 
  
 
== Responses ==
 
== 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>

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