GS1 US Data Hub Product

Size: px

Start display at page:

Download "GS1 US Data Hub Product"

Steven Fowler
5 years ago
Views:

1 GS1 US Data Hub 3.4 Product via This guide is specifically written for Solution Partners who are certified under the CCP program and augments current GS1 US Developer documentation. For information on the program, please contact us at 1 Page

2 Contents Solution Provider Job Aids... 3 How a Brand Owner selects a Solution Provider Job Aid... 3 How a Brand Owner assigns an In Use Product record to a Solution Provider Job Aid... 5 Getting Started... 7 How to retrieve assigned products from a Brand Owner Job Aid How to add enhanced content to an assigned product record via the Job Aid How to retrieve an existing image from a product record using the How to add an enhanced image to the product record via the Job Aid How to determine the status of approved and rejected records How to retrieve a list of records a Brand Owner unassigned APPENDIX Commands for the CCP Data Dictionary for the Enhanced Content Attributes Page

3 Solution Provider Job Aids How a Brand Owner selects a Solution Provider Job Aid After you negotiate your business agreement, a Brand Owner must take steps to ensure they select you as their CCP. These are the initialization steps they will need to take to get started. A Brand Owner will assign their chosen Solution Provider from the main menu in GS1 Data Hub in the Administration screen: GS1 US Data Hub main screen Step Action 1. Under Solution Provider Settings towards the middle of the page, click Manage. 3 Page

4 2. The Select Solution Providers will display all of the available Solution Providers. Check mark each Solution Provider the Brand Owner has contracted with. 3. Click Save. 4. A confirmation Solution Provider Settings dialog box appears confirming they have Successfully added Solution Provider. Click OK A CCP Selection will automatically be sent to the Solution Provider informing them the they have been selected. 4 Page

5 How a Brand Owner assigns an In Use Product record to a Solution Provider Job Aid Now that the Brand Owner selected you as their CCP, they will now need to select the product(s) to assign to you. The Brand Owner selects In Use product(s) and assigns them to a Solution Provider. The Brand Owner, completes the following: In GS1 Data Hub Product, from the main menu, click Product --> Manage Step 1. Select the In Use tab. Action. 2. Click the Assign/Review Enhanced Content button. 5 Page

6 3. When a Brand Owner selects Assign/Review Enhanced Content, a new set of tables appear. The first is called Select Products. This table displays all In Use products, along with their Enhanced Status (first column). Visual indicators help the Brand Owner to easily identify which product(s) have been assigned and completed, or which products have yet to be assigned. 4. After selecting the product(s), the Brand owner clicks the Assign Solution Provider button. User can select multiple product records using shift control or clickinig on the Select All button. 6 Page

7 5. From the dropdown menu in the dialog box, the Brand Owner chooses the Solution Provider to assign the designated product(s) to enhance content or image. Note: only Solution Provider(s) that have been assigned from the Administration field will appear. 6. A Products Assigned will automatically be generated and sent to the Solution Provider informing them to login via the to retrieve the product record(s) to enhance. The notification you receive is located in the Message Center within Data Hub. If you checked CCP Notice in your preferences, you will also receive an alerting you to check notifications. The entitygln information provided is necessary for setting up your. Getting Started It s recommended to use the Advanced REST client (ARC) interface downloadable from or Postman from Once the Advanced REST client (ARC) interface has been installed, the following information will be needed to work with your assigned products: 7 Page

8 Step 1. Locating your key(s) Action Retrieve or use the Key(s) assigned to you Log into Data Hub and click on the Developer Portal, click on your company name and then Profile to retrieve your Key(s). The values provided are unique to your company and you will use these in setting up the header for your calls. 2. Application Keys Application credentials or keys (Key) are used to authenticate HTTP GETAssignedProducts requests. Your Keys are provided in the Developer Portal. Your application must pass this key to GS1 US using the requests to authenticate your application. This key should be kept secret between you and GS1 US and never made public nor passed to other companies. 3. The type of Method you will choose (example: GET or POST) From the ARC interface, click Method at the top and select GET or POST. The GET Method retrieves product detail information. The POST Method allows you to add the content for the enhanced attributes. 8 Page

9 5. The request URL will map to the type of action you are taking, such as getting a list of assigned products from a Brand Owner using its unique identifier, Entity GLN Owner entity GLN> See Appendix for a list of commands you will use for the CCP program. 9 Page

10 How to retrieve assigned products from a Brand Owner Job Aid Please note: Version 2 (api.gs1us.org) of the GS1US Data Hub uses the RESTful endpoint structure. Data will be exchanged in JSON format using standard HTTP verbs (in this scenario, getassignedproducts is used). To determine what products have been assigned to the Solution Provider, use this method to retrieve assigned product record details from the Brand Owner s Data Hub product list. Step 1. Action On the home page of the Developer Portal, click on your company name and then Profile to retrieve your Key(s) that will be used in the Header field. The values are unique to your company and you will use these in setting up the file Headers. Each Product has its own key. 2. To retrieve assigned records, you will use the GET method using the command getassignedproducts in the request URL along with the entitygln of the Brand Owner provided as a parameter in the notification message. 3. Use REQUEST URL: Owner entity GLN> Change the < Brand Owner entitygln> to the value provided in the notification. 4. Add a Header field. Enter in the Header Name: Key In the Header Value enter the appropriate key. 5. Click SEND to submit the request to Data Hub. 6. If successful, the response will return the product details as a reference, shown in the example below: Response: 200 OK ms DETAILS "success": true, "productinformation": "gtin": "XXXXXXXnnnnnn", 10 Page

11 "products": [ "brandname": "Brian's Best", "description": "Reserved Item", "state": "In Use", "status": "Assigned", "actiondate": " T09:13:50.5", "gtin": "XXXXXXXX000733", "gtin13": "", "gtin12": "XXXXXXX00733", "industry": "General", "height": null, "width": null, "depth": null, "dimensionmeasure": null, "grossweight": null, "netweight": null, "weightmeasure": null, "sku": null, "companyname": "GS1 US Enterprises 1", "entitygln": "XXXXXXX000009", "CompanyURI": "/company/v2/company/xxxxx ", "ancestors": [], "descendants": [], 7. One or more product detail records may be retrieved in a single query against the entitygln, if the Brand Owner assigns them. 8. You must submit changes one record at a time. See job aid How to add enhanced content to an assigned product record via the Job Aid 11 Page

12 How to add enhanced content to an assigned product record via the Job Aid Please note: Versions 2 (api.gs1us.org) of the GS1US Data Hub uses the RESTful endpoint structure. Data will be exchanged in JSON format using standard HTTP verbs (in this example, postproductcontent is used). To add enhanced content to the assigned products use the POST method using the command postproductcontent in the request URL, follow these steps: Step Action 1. On the home page of the Developer Portal, click on your company name and then Profile to retrieve your Key(s) that will be used in the Header field. The values are unique to your company and you will use these in setting up the file Headers. Each Product has its own key. 2. To retrieve assigned records, you will use the GET method using the command getassignedproducts in the request URL along with the entitygln of the Brand Owner provided as a parameter in the notification message. 3. Use REQUEST URL: Change the < Brand Owner entitygln> to the value provided in the notification. 4. Add a Header field. Enter in the Header Name: Key In the Header Value field enter the appropriate key. 5. Body Content Type: Application JSON 6. The Body Content Type updates Data Hub enhanced content attributes. Use the following code to change the enhanced content. (Recommendations: Copy and paste the syntax below, then change the individual field values. Save the syntax as a named template for repeated use. We are using the 14-digit placeholder, XXXXXXXXXXXXXX, to represent the GTIN number in this example. "gtin" : "XXXXXXXXXXXXXX", "enhancedfields": [ "fieldname": "GlobalProductClassification", "fieldvalue": " " "fieldname": "LABELDESCRIPTION", 12 Page

13 ] } "fieldvalue": "Test labeldescription" "fieldname": "netcontent1countstr", "fieldvalue": "1.0000" "fieldname": "netcontent1uom", "fieldvalue": "lbs" "fieldname": "Descriptionshort", "fieldvalue": "test update from " "fieldname": "LABELDESCRIPTION", "fieldvalue": "Test labeldescription" "fieldname": "netcontent1countstr", "fieldvalue": "1.0000" "fieldname": "netcontent1uom", "fieldvalue": "lbs" "fieldname": "Descriptionshort", "fieldvalue": "test update from " "fieldname": "subbrandname", "fieldvalue": "test update from " "fieldname": "netcontent2countstr", "fieldvalue": "123333" "fieldname": "netcontent3countstr", "fieldvalue": "123333" "fieldname": "netcontent2uom", "fieldvalue": "lbs" "fieldname": "NetContent3UOM", "fieldvalue": "oz" } 13 Page

14 7. Receive confirmation that the request was successful. Response: 200 OK ms DETAILS "Success 8. Scroll to Body for data 14 Page

15 How to retrieve an existing image from a product record using the Please note: Versions 2 (api.gs1us.org) of the GS1US Data Hub uses the RESTful endpoint structure. Data will be exchanged in JSON format using standard HTTP verbs (in this example, getimage is used). To retrieve an existing image file for the assigned product s record, use the following steps: Step Action 1. On the home page of the Developer Portal, click on your company name and then Profile to retrieve your Key(s) that will be used in the Header field. The values are unique to your company and you will use these in setting up the file Header. Each Product has its own key. 2. Use Method: GET This method retrieves an existing image file from the Data Hub record. This method takes a valid GTIN of the Brand Owner as its parameter. 3. Use Request URL: Change the <GTIN> for the product record from which you want to retrieve image. For example, retrieving Eric s Diabetic Peanut Butter Cookies image. The GTIN for this product is XXXXXX The Request URL becomes: 4. Add a Header field. Enter in the Header Name: Key In the Header Value field enter the appropriate key Browse for and select the picture file to upload. Note: file size not to exceed 1MB. Update the Field Name with File. Click SEND to submit the request to Data Hub. Receive confirmation that the request was successful. 15 Page

16 Response: 200 OK ms DETAILS "Success" If a record is pending approval, Data Hub will return an error that the record could not be found. Wait to resubmit, or until that record has been approved. Scroll to the Body for data. 16 Page

17 How to add an enhanced image to the product record via the Job Aid Please note: Versions 2 (api.gs1us.org) of the GS1US Data Hub uses the RESTful endpoint structure. Data will be exchanged in JSON format using standard HTTP verbs (in this example, postimage is used). To add an enhanced image file to the assigned product s record, use the following steps: Step 1. Action On the home page of the Developer Portal, click on your company name and then Profile to retrieve your Key(s) that will be used in the Header field. The values are unique to your company and you will use these in setting up the file Header. Each Product has its own key. 2. Use Method: POST This method adds an enhanced image to the Data Hub record. This method takes a valid GTIN as its parameter. 3. Use Request URL: Change the <GTIN> to the product you want to add an image to. For example, updating Eric s Diabetic Peanut Butter Cookies image. The GTIN for this product is XXXXXX The Request URL becomes: 4. Add Header field Use Header Name: ApiKey In the Header Value type your key 5. The Body will display a Choose File field. Click to search for your file 6. Browse for and select the picture file to upload. Note: file size not to exceed 1MB Update the Field Name with File Click Send to submit the request to Data Hub 9. Receive confirmation that the request was successful 17 Page

18 Response: 200 OK ms DETAILS "Success" 11. If a record is pending approval, Data Hub will return an error that the record could not be found. Wait to resubmit or until that record has been approved. 12. Scroll to the Body for data 13. Only one image file may be posted to a product record. Only one image file can be conveyed in a single submission. 18 Page

19 How to determine the status of approved and rejected records Please note: Versions 2 (api.gs1us.org) of the GS1US Data Hub uses the RESTful endpoint structure. Data will be exchanged in JSON format using standard HTTP verbs (in this example, getcontentstatus is used). This step provides a way for you to determine the status of records assigned to you by the Brand Owner. Step Action 1. On the home page of the Developer Portal, click on your company name and then Profile to retrieve your Key(s) that will be used in the Header field. The values are unique to your company and you will use these in setting up the file Header. Each Product has its own key. 2. Use Method: GET This method enables you to retrieve a list of approved and rejected records for a given Brand Owner. This method takes the valid entity GLN of the Brand Owner as its parameter. 3. Use Request URL: Owner entitygln> Change the <Brand Owner entitygln> to the value provided in the notification 4. Add a Header field Use the following under Header Name: Apikey In the Header Value type your key 5. Click SEND to submit the request to Data Hub. 6. Receive confirmation that the request was successful and scroll through the file to review results. Response: 200 OK ms DETAILS "Success" If a record is pending approval, Data Hub will return an error that the record can not be found. Wait to resubmit or until that record has been approved. Scroll to the Body for data 19 Page

20 How to retrieve a list of records a Brand Owner unassigned Please note: Versions 2 (api.gs1us.org) of the GS1US Data Hub uses the RESTful endpoint structure. Data will be exchanged in JSON format using standard HTTP verbs. (in this example, getunassignedproducts is used) This step provides a way for you to determine the status of records that were unassigned by the Brand Owner. Step Action 1. On the home page of the Developer Portal, click on your company name and then Profile to retrieve your Key(s) that will be used in the Header field. The values are unique to your company and you will use these in setting up the file Header. Each Product has its own key. 2. Use Method: GET This method enables you to retrieve a list of unassigned records for a given Brand Owner. This method takes the valid entity GLN of the Brand Owner as its parameter. 3. Use Request URL: Owner entitygln> Change the < Brand Owner entitygln> to the value provided in the notification 4. Add Header field Use Header Name: ApiKey In the Header Value type your Key 5. Click SEND to submit the request to Data Hub. 6. Receive confirmation that the request was successful and scroll through the file to review results. Response: 200 OK ms DETAILS "Success" If a record is pending approval, Data Hub will return an error that the record could not be found. Wait to resubmit or until that record has been approved. Scroll to the Body for data 20 Page

21 APPENDIX 21 Page

22 Commands for the CCP Request URL: 22 Page

23 Data Dictionary for the Enhanced Content Attributes Notes: 1. When a Net Content field name is part of the record, both countstr and UOM field values must be entered. 2. Net Content fields are entered in sequence (e.g., Net Content 1 always first, then Net Content 2, then Net Content 3). 23 Page

GS1 US Data Hub 3.4 Product. Brand Owner s Guide to Managing Enhanced Content

GS1 US Data Hub 3.4 Product. Brand Owner s Guide to Managing Enhanced Content GS1 US Data Hub 3.4 Product Brand Owner s Guide to Managing Enhanced Content Table of Contents Contents Frequently Asked Questions by Brand Owners... 3 What is Enhanced Content?... 3 What is a GS1 US Certified