Overview
It is possible to use the API to take advantage of our "Unmatched Items" workflow, by sending lines with placeholder IDs and providing Aliases.
Basic Principles
Usually when posting data to our API, you need to know the unique IDs of certain items in advance.
For example, if you are creating a Bulk Receival you would need to know the Contact Num of the Other Party, as well as the Stock Item Numbers of any additives you wish to include.
The Vinsight App generally fulfills this requirement by presenting drop down boxes for the user to search for and select existing items via the API.
However, it is possible to avoid this requirement if you send API requests with in a pre-defined format, which tells Vinsight what you do know about the item, without having to provide the actual ID.
This will show up in the Vinsight App as "Unmatched" items, and offers an in-app experience for matching inbound data to existing data.
Additionally, if the user has previously completed a match and you send the same API request again, Vinsight will automatically substitute the placeholder items in your API call with the real items that the user has previously matched.
This means you can post API data without looking up IDs in advance, and also means you can post API data when items don't even exist yet in the client Vinsight Account.
This is especially useful when you are copying data from another system (e.g. copying an order from Shopify to Vinsight).
API POST Data Structure
To tell Vinsight you are wanting to use the Unmatched Items workflow on an item you are posting, there are a couple of things you need to provide in your API request:
- Use the placeholder ID of
0(zero) in place of a real ID. - Send an Alias record attached to the line item, identifying the property you are wanting to match on, and some information about the item.
The placeholder ID of 0 (zero) does actually map to a real item in everyone's Vinsight Account. By convention it is used to denote an unmatched item.
You cannot create this placeholder item yourself as IDs normally start at 1 (one).
This means it is possible to just send the placeholder ID without any Alias information and the item will still show up as "Not Matched".
However if you omit the Alias information, then the user will be unable to match the inbound item and will see an error instead if they try.
It is always possible for the user to edit the document manually and replace an unmatched item with one in their account, however it would need to be done every time and would be tedious.
The Alias record properties required to initiate the Unmatched Items workflow are as follows:
| Alias Property | Description |
|---|---|
EntityUniqifier |
Required, String, Case Sensitive, Max length 100. Used to specify the Vinsight Property Name on the parent that you are providing information about (e.g. "ContactNum" on a Bulk Receival, or "StockItemNum" on an Additive line) |
Domain |
Required, String, Max length 20. Used to help identify the App or Source where this data originated from (e.g. "Shopify" or "EZYWine") |
SubDomain |
Required, String, Max length 50. Used to identify the unique account in Domain that relates to the source. For Example a Shopify Store ID, an Organisation GUID, or a Winery Short Code. |
DomainEntityType |
Required, String, Max length 40. Used to specify the type of the source item in Domain ( e.g. "Debtor" or "Product" ) |
DomainEntityId |
Required, String, Max length 50. Used to uniquely identify the source item of type DomainEntityType in SubDomain belonging to Domain.The combination of Domain, SubDomain, DomainEntityType, and DomainEntityId is used to remember previous matches and perform automatic matching if you send the same combination again for a different API request. |
DomainEntityCode |
Optional, String, Max length 100. Used to show a nicer code to the user during the matching process, so they can understand what the item is meant to be. (e.g. "My Product 01" ) |
DomainEntityDescription |
Optional, String, Max Length 255. Used to show a nicer description to the user during the matching process, so they can understand what the item is meant to be. (e.g. "Our First Ever Product" ) |
DomainData |
Optional, String, JSON Encoded Object. Any properties on the JSON object stored under DomainData will be deserialised and shown to the user during the matching process.This is useful if you want to send through some extra information apart from Code and Description that the user might want to know while they are matching, e.g. a Unit Of Measure Code. Please try to keep it as brief as possible. Smaller objects work best for conveying extra information and we don't want to be storing entire JSON copies of other system's items if it's not required. |
JSON Example - Creating a Bulk Receival via API using Unmatched Items workflow
In this example, we are taking a Bulk Despatch from a different Vinsight user and copying it as a Bulk Receival in our account.
As such, all their unique Stock Item and Contact Numbers can be treated as having come from "another source". It is likely that they don't even exist in the destination account yet.
Note if you actually want to do this we already have a .vinsight file format that can be exported from a Bulk Despatch in one account and imported as a Bulk Receival to another account.
We use the unmatched items workflow internally to accomplish this, so it is a good example of what you can acheive.
>> Extra Help
{
"DateCompleted": "2020-08-02T00:00:00",
"TransferVolume": 5000.0,
"AlcoholVolume": 0.0,
"ABV": 0.0,
"Comments": null,
"ContactNum": 0, // We are using the "Not Matched" placeholder ID here
"CarrierContactNum": 0, // We are using the "Not Matched" placeholder ID here
"TruckOrCompartment": "24",
"Reference": null,
"BulkReceivalComponents": [{
"VarietyCode": "CH",
"RegionCode": "HB",
"Vintage": 2017,
"Percentage": 1.0
}],
"ComponentSources": [{
"OwnerType": "BulkReceival",
"ComponentType": "StockItem",
"ComponentId": 0, // We are using the "Not Matched" placeholder ID here
"ComponentCode": "KMS",
"LotCode": "L2212-a",
"RateAdded": 15.3,
"RateAddedUnitOfMeasure": "ppmSO2 as KMS",
"Quantity": 0.153,
"QuantityAddedUnitOfMeasure": "Kg",
"Aliases": [{
"EntityUniqifier": "ComponentId", // We are targeting ComponentId property for replacement, on the object
"Domain": "Vinsight", // Came from another Vinsight Organisation
"SubDomain": "c663e81d-57e2-4ba6-a40c-6c587101ae95", // The other Vinsight Org ID
"DomainEntityType": "StockItem", // Their Vinsight System calls this a "StockItem"
"DomainEntityId": "KMS", // We could use the StockItemNum from the other Vinsight System,
// but have chosen to use the StockItemCode instead in case it is renamed
"DomainEntityCode": "KMS"
}]
}, {
"OwnerType": "BulkReceival",
"ComponentType": "StockItem",
"ComponentId": 0,
"ComponentCode": "Yeast-EC1118",
"LotCode": null,
"RateAdded": 128.0,
"RateAddedUnitOfMeasure": "ppm",
"Quantity": 0.64,
"QuantityAddedUnitOfMeasure": "Kg",
"Aliases": [{
"EntityUniqifier": "ComponentId",
"Domain": "Vinsight",
"SubDomain": "c663e81d-57e2-4ba6-a40c-6c587101ae95",
"DomainEntityType": "StockItem",
"DomainEntityId": "Yeast-EC1118",
"DomainEntityCode": "Yeast-EC1118",
"DomainEntityDescription": "Wine Yeast EC 1118"
}]
}],
"Aliases": [{
// This Alias is telling us where the document came from, not required for the Matching process
"Domain": "Vinsight",
"SubDomain": "c663e81d-57e2-4ba6-a40c-6c587101ae95",
"DomainEntityType": "BulkDespatch",
"DomainEntityId": "1"
}, {
// This Alias is telling us about the ContactNum property.
// The Contact is intended to represent the other Vinsight Company
"EntityUniqifier": "ContactNum",
"Domain": "Vinsight",
"SubDomain": "c663e81d-57e2-4ba6-a40c-6c587101ae95",
"DomainEntityType": "Organisation",
"DomainEntityId": "c663e81d-57e2-4ba6-a40c-6c587101ae95",
"DomainEntityDescription": "Other Wine Co"
}, {
// This Alias is telling us about the CarrierContactNum property.
// The Contact is intended to represent the Carrier Contact from the other Vinsight System.
"EntityUniqifier": "CarrierContactNum",
"Domain": "Vinsight",
"SubDomain": "c663e81d-57e2-4ba6-a40c-6c587101ae95",
"DomainEntityType": "Contact",
"DomainEntityId": "48",
"DomainEntityDescription": "Freddies Freight"
}]
}