APIs

Key Concepts

Product information is held in a number of views.

The Formulation View holds the recipe and calculated data based on it. The Formulation view calculations are dynamically recalculated each time the record is accessed, so are reactive to changes made to lower levels of the formulation.

The Product Specification View holds the information to be published about a product. This may differ from the calculated information in the Formulation View. In contrast to the dynamic calculations in the Formulation View, the Product Specification View information for an approved record is static and will not change unless a new version is approved.

Therefore, API interactions for product information are normally based on approved finished product data from Product Specification View, rather than the Formulation View. In the application's user interface users can switch between these views using the view selector. When making API calls, a Product Specification View is referenced by appending _PS to the record code.

Patterns & Practices

Typically, customers are looking to extract finished product information for recently approved records. A typical pattern for this is:

1. Get references to Product Specifications for approved finished products (possibly modified since a certain date)

2. For each Product Specification, extract the information you require

query={

"_comment": "Gets references to product specifications for approved finished products",

"Conditions": [

{

"_comment": "Limits results to Approved items",

"item": "Status",

"fieldPath": "Status Code",

"valueFrom": "Approved",

"isCommonOption": true,

}

],

"Choices": [

{

"_comment": "Include the code in results",

"item": "Code",

"isCommonOption": true

},

{

"_comment": "Include the project ID in results (this is '1' for approved items)",

"item": "Location",

"isCommonOption": true

},

{

"_comment": "Include the status in results",

"item": "Status",

"isCommonOption": true

},

],

"Locations": [

{

"folderid": "1",

"includechildren": true

}

],

"_comment": "Get results for 'Product Specifications'",

"TemplateName": "Product Specification"

}

1. Getting the references to approved Product Specifications

You can use the

POST https://hgapi.azure-api.net/odata/api/Get_Report_Specification()

operation with the following body.

,{

"_comment": "Limits results to those modified since a certain date",

"item": "Modified",

"fieldPath": "Modified Date",

"valueFrom": "01/01/2019",

"isConditionFrom": true,

"isCommonOption": true

}

To limit this to items approved since a certain date, you would add this section to the Conditions section:

query={

"Conditions": [

{

"_comment": "Set the Code for the Product Specification required",

"item": "Code",

"fieldPath": "Code",

"valueFrom": "FP00000024_PS",

"isConditionEquals":true,

"isCommonOption": true

},

{

"_comment": "Limits results to Approved items",

"item": "Status",

"fieldPath": "Status Code",

"valueFrom": "Approved",

"isCommonOption": true,

}

],

"Choices": [

{

"_comment": "Return the code",

"item": "Code",

"isCommonOption": true

},

{

"_comment": "Return the location ID",

"item": "Location",

"isCommonOption": true

},

{

"_comment": "Return the version number",

"item": "Version",

"isCommonOption": true

},

{

"_comment": "Return the ingredient list",

"szTag": "ilist_fin",

"fieldPath": "Ingredients List"

}

],

"Locations": [

{

"folderid": "1",

"includechildren": true

}

],

"ShowMatchingTablesLinesOnly": false,

"TemplateName": "Product Specification"

}

2. Get product information for each of the returned records

Example A: Get the ingredients list

You can use the

POST https://hgapi.azure-api.net/odata/api/Get_Report_Specification()

operation with the following body.

"Conditions": [

{

"_comment": "Limit to items modified since a date",

"item": "Modified",

"fieldPath": "Modified Date",

"valueFrom": "01/01/2019",

"isConditionFrom": true,

"isCommonOption": true

},

{

"_comment": "Limit to approved items",

"item": "Status",

"fieldPath": "Status Code",

"valueFrom": "Approved",

"isCommonOption": true,

}

]

To return the ingredient lists for all records approved after a certain date you would change the Conditions section as below:

query={

"Conditions": [

{

"_comment": "Set the Code for the Product Specification required",

"item": "Code",

"fieldPath": "Code",

"valueFrom": "FP00000024_PS",

"isConditionEquals":true,

"isCommonOption": true

},

{

"_comment": "Limits results to Approved items",

"item": "Status",

"fieldPath": "Status Code",

"valueFrom": "Approved",

"isCommonOption": true,

}

],

"Choices": [

{

"_comment": "Return the code",

"item": "Code",

"isCommonOption": true

},

{

"_comment": "Return the location ID",

"item": "Location",

"isCommonOption": true

},

{

"_comment": "Return the version number",

"item": "Version",

"isCommonOption": true

},

{

"_comment": "Return the component name",

"szTag": "cmps_nm",

"fieldPath": "Component Name"

},

{

"_comment": "Return component information",

"szTag": "cmps_grp",

"fieldPath": "Component Group"

},

{

"_comment": "Return component information",

"szTag": "cmps_pctot",

"fieldPath": "Component Avg % of total"

},

{

"_comment": "Return component information",

"szTag": "cmps_dcld",

"fieldPath": "Component Declared"

},

{

"_comment": "Return component information",

"szTag": "cmps_algn",

"fieldPath": "Component Allergens Contained"

},

{

"_comment": "Return component information",

"szTag": "cmps_tp",

"fieldPath": "Component Type"

},

{

"_comment": "Return component information",

"szTag": "cmps_add",

"fieldPath": "Component Additive Number"

}

],

"Locations": [

{

"folderid": "1",

"includechildren": true

}

],

"ShowMatchingTablesLinesOnly": false,

"TemplateName": "Product Specification"

}

Example B: Get the Components table

You can use the

POST https://hgapi.azure-api.net/odata/api/Get_Report_Specification()

operation with the following body.

Reference

The POST https://hgapi.azure-api.net/odata/api/Get_Report_Specification() operation has the ability to bring back any specification view field for product information, and any field for extended information type. Fields are included in the return values by including the following section in the Choices section.

{

"_comment": "Return component information",

"szTag": "cmps_add",

"fieldPath": "Component Additive Number"

}

- szTag is the field tag for the information you wish to extract.

- fieldPath is the name you wish the data to have in the return json structure.

In this way you can extract information with the references for foreign systems.

Field tags for the Product Specification are below.

Section

Product Information

Product Information - Weight

Product Information - Barcodes

Label Information

Label Information - Instructions

Label Information

Composition

Composition - Components

Allergens

Allergens - May Contain

Allergens

Allergens - Substances of interest

Nutritional Information

Nutritional Information - Nutrients

Claims & Suitability - Organic

Claims & Suitability - Non-GMO

Claims & Suitability - Kosher

Claims & Suitability - Halal

Claims & Suitability - Gluten Free

Claims & Suitability - Vegetarian

Claims & Suitability - Vegan

Claims & Suitability - Lactose Free

Claims & Suitability

Claims & Suitability - Other Standards

Type

text

dropdown

numeric

dropdown

text

table

column - text

text

table

column - text

column - dropdown

column - numeric

column - dropdown

column - multiselect

column - dropdown

column - multiselect

table

column - dropdown

column - text

text

table

column - dropdown

column - text

text

numeric

table

column - numeric

column - text

column - dropdown

dropdown

text

dropdown

text

dropdown

text

dropdown

text

dropdown

text

dropdown

table

column - text

column - date

column - text

Name

Suppliers Product Code

Suppliers Product Description

Label Description

Product Country of Origin

Weight type

Weight

Weight Unit

Primary Unit Barcode

Case Barcode

Pallet Barcode

Ingredient List

Ingredient List Notes

Instructions

Steps

Settings

Notes

Other label text

Components

Name

Group

Avg % of total

Declared

Allergens contained

Type

Country of origin

Additive Number

Allergens - May Contain

May Contain

Comments

Sulphur Dioxide and Sulphites (ppm)

Substances of interest

Contains

Comments

Serving Size Name

Serving Size Amount (g)

Nutrients

Per 100g

Per Serving

Comments

Source of Nutrition

Organic Suitable

Organic Certifying Body

Non-GMO Suitable

Non-GMO Certifying Body

Kosher Suitable

Kosher Certifying Body

Halal Suitable

Halal Certifying Body

Gluten Free Suitable

Gluten Free Certifying Body

Vegetarian Suitable

Vegan Suitable

Lactose Free Suitable

Other Standards

Name

Certifying Body

Expiry Date

Comments

Tag

pcode_splr

desc_splr

desc_lbl

Product_Count_9EB

prd_wt_tp

prd_wt_vl

prd_wt_uom

bcode_pu

bcode_cs

bcode_plt

ilist_fin

ilist_nts

instr_tbl

instr_steps

instr_stgs

instr_nts

lbl_add

cmps_tbl

cmps_nm

cmps_grp

cmps_pctot

cmps_dcld

cmps_algn

cmps_tp

cmps_coo

cmps_add

algn_mc_tbl

algn_mc_vl

algn_mc_nts

algn_ppm_slph

soi_tbl

soi_cnt_vl

soi_cnt_nts

Serving_Size__3E0

svsz_vl

ntr_tbl

ntr_vl_100g

Per_Serving_3E1

ntr_vl_nts

ntr_vl_src

cl_org_vl

cl_org_crtbdy

cl_gmofr_vl

cl_gmofr_crtbdy

cl_ksh_vl

cl_ksh_crtbdy

cl_hll_vl

cl_hll_crtbdy

cl_gtnfr_vl

cl_gtnfr_crtbdy

cl_vgtn_vl

cl_vegan_vl

cl_lctfr_vl

cl_add_tbl

cl_add_nm

cl_add_crtbdy

cl_add_exp

cl_add_nts