View source for Create Items by External Id

== Summary ==

This method is a copy of the normal create items except it will locate and update items by their external id as primary key rather than the item name . 

If you attempt to create an item with no external ID provided an exception will be thrown, also if there are more than one item with the same external id only the first will be updated

An item 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 'create item' method accepts an array of items to be added to the system. If the 'update_existing' parameter is set, then any existing items will be updated in the system. If set to false or not provided, then any item where the item name is not unique will be rejected.

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

The item name is the primary key so if the item already exists it will be updated rather than duplicated.

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

! Create Item
! colspan="2" | 
|-
!  URL
| colspan="2" | https://base_url/api_path/version/items/external
|-
! 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 Item - JSON
! colspan="2" | 
|-
!  URL
| colspan="2" | http://base_url/api_path/version/items/external
|-
! Type
| colspan="2" |POST
|-
! 
| JSON <br /> {key, validate_only(optional), update_existing(optional), items[]}   ||| required    
|-
! Response
| colspan="2" | JSON
|}

== JSON Contents ==

{| border="1" class="wikitable"
|+ The JSON file is passed in the post as the "file"
! colspan="3" | Standard Fields
|-
! Field
! Expected Data
! Required
|-
! external_id
| varchar(45) || &#10003;
|-
! category_id
| {"name":"<categoryName>"} <br /><span style="font-size:80%; font-weight:normal">*nested JSON object</span>|| &#10003;
|- 
! name
| varchar(255) <br /><span style="font-size:80%; font-weight:normal">* must be unique</span>|| &#10003;
|-
! notes
| text ||
|-  
! product_code
| varchar(45) || 
|- 
! price
| float(10,2) || 
|- 
|}

{| 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">
{"items":[{
"external_id":"ss303",
"category_id":{"name":"Test1"},
"name":"darrenItem",
"notes":"notesnotes",
"product_code":"productCodeTest",
"price":"2.50"
}]}
</source>

==== JSON As Body ====

<source lang="java">
{
   "key":"darrenwebapi",
   "validate_only":"false",
   "update_existing":true,
   "items":[
      {
         "external_id":"ss303",
         "category_id":{
            "name":"test2"
         },
         "name":"darrenItem",
         "notes":"notesnotesnotes",
         "product_code":"productCodeTest",
         "price":"2.50"
      }
   ]
}
</source>


== Example Curl Requests ==

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

curl -F validate_only=false -F update_existing=true -F api_key=darrenwebapi -F file=@/Users/darrenatherton/Desktop/webAPICurling/create_item.txt https://api.mymobileworkers.com:8181/api/1/items/external

==== JSON As Body ====

curl -X POST -H "Content-Type: application/json" -d '{"key":"darrenwebapi", "validate_only":"false", "update_existing":true,"items":[{"external_id":"ss303","category_id":{"name":"test2"},"name":"darrenItem","notes":"notesnotesnotes","product_code":"productCodeTest","price":"2.50"}]}' https://api.mymobileworkers.com:8181/api/1/items/external

== Responses ==

=== Example JSON ===

<source lang="java">
{
	"successful":
	[
		{"item_name":"testItem"},
		{"item_name":"testItem2"}
	],
	"failed":
	[
		{
			"item_name":"testItem3",
			"errors": 
			[
				{
					"error_code":"ITE012",
					"error_msg":"name cannot be null."
				}
			]
		}
	]
}
</source>