VManager Pro

Introduction

This page describes the usage of VUSION Manager Pro API (manager-pro).

The main page can be found here. Please read the overview before using this page (for security, URL, etc.). Moreover, universal item schema used be VusionGroup is described here.
All URL examples are given for Europe, see this section for more details.

Search items, labels & events

Search items

To search an item, you have to call following operation:

GET https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/items 
Response is 
{ 
   "query": { 
       "pageSize": 10,
       "page": 1 
},
 "count": 13, "values": [ { "margin": { "indicator": "" }, "custom": { "features": "• Fuel Type: Electric
• Capacity (cu ft) 5.9 cu. ft.
• No. of Elements/Burner Cooking Zones: 5
• Burner/Element Configuration: (2) 6\" 1200W; (1) 6\"/9\" 3000W; (1) 9\"/12\" 3000W
• Width: 29.88 in.", 
      "depth": "25.97 in.", 
      "width": "29.88 in.", 
      "testEnd": "2019-11-04", 
      "testStart": "2019-09-12", 
      "height": "47.09 in." 
   }, 
   "description": "", 
   "storeId": "${storeId}", 
   "itemId": "NE59M4320SS", 
   "multimedia": { 
       "image": "http:/xxxx/media/brands-logos/Samsung.png", 
       "url": "http://xxxx/search/NE59M4320SS" 
   }, 
   "modificationDate": "2020-01-08T15:45:58.345Z", 
   "deletionDate": null, 
   "inPromotion": false, 
   "price": 542, "customerReview": { 
          "reviewCount": null, 
          "rating": null 
   }, 
   "name": "Samsung 30\" Freestanding Electric Range", 
   "currency": "€", 
   "id": "NE59M4320SS", 
   "stock": { 
           "current": 6, 
           "level": null, 
           "minimum": null 
    }, 
    "fresh": { 
           "origin": "" 
    }, 
    "newArticle": false, 
    "brand": "Samsung", 
    "order": { 
            "quantity": null, 
            "nextDelivery": null 
    }, 
     "promotion": { 
            "regularPrice": 789.95, 
            "start": "2019-09-12T00:00:00.000Z", 
            "end": null, 
            "text": "" 
    }, 
    "status": "ACTIVE", 
    "_score": 1 
 }, 
    ... 
    ] 
}

Get next page

Result has a next page, so to get next page:

GET https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/items?page=2 
Response is 
{ 
    "page": 2, 
    "pageSize": 10, 
    "values": [ 
   ... 
   ] 
}

Search a label with labelId

GET https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/labels/{labelId} 
Response is 
{
	"labelId": "C51E99EC",
	"modificationDate": "2020-01-16T16:04:40.444Z",
	"transmission": {
		"lastSuccessfulTransmissionDate": "2020-01-15T14:30:57.633Z",
		"registrationDate": "2020-01-03T14:18:29.971Z",
		"transmissionDate": "2020-01-15T14:30:57.633Z",
		"lastFailedTransmissionDate": "2020-01-03T14:23:40.106Z"
	},
	"connectivity": {
		"rssi": -55,
		"modificationDate": "2020-01-03T14:37:10.716Z",
		"lqi": 51,
		"signalQuality": "GOOD",
		"lastOfflineDate": "2020-01-03T14:23:40.663Z",
		"lastOnlineDate": "2020-01-16T16:04:44.561212Z",
		"status": "ONLINE"
	},
	"storeId": "${storeId}",
        "creationDate": "2020-01-03T14:18:29.971Z",
	"matching": {		
        "scenario": {
			"name": "Template_1",
			"scenarioId": "TEMPLATE_1"
		},
		"matchingDate": "2020-01-16T09:37:27.257Z",
		"items": [
			{
				"id": "3000000000502",
				"name": "Cola bottle 33cl",
				"price": 1.25,
				"status": "ACTIVE"
			}
		]
	},
	"status": "SYNCHRONIZED",
	"hardware": {
		"naturalOrder": "6.0",
		"pageCount": 13,
		"imageName": "G1_4.2_BWR.png",
		"typeName": "4.2 BWR",
		"pattern": "C[5][0-9a-fA-F]{6}",
		"battery": "GOOD",
		"defaultOrientation": "LANDSCAPE",
		"displayType": "PORTRAIT_LANDSCAPE",
		"screenTechnology": "E_PAPER",
		"transmissionTechnology": "HIGH_FREQUENCY",
		"screenColor": "BLACK_WHITE_RED",
		"width": "400",
		"animated": "false",
		"typeId": "HF_G1_4.2_BWR",
		"dpi": "120",
		"firmware": "3.1.0",
		"height": "300",
		"unitaryUpdateDuration": "12000"
	},
	"_score": 1
}

Search all labels with a specific query

Examples:

  1. https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/labels?search=status:UNREACHABLE to search unreachable labels ("equals" operator is ":")

  2. https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/labels?search=coca to search labels with any field equals to "coca" (textual search is not case sensitive except for enum values)

  3. https://api-eu.vusion.io/vlink-pro/v1/stores/${storeId}/labels?search=matching.item.name:coca* to search labels matched with items whose name starts with "coca" ("start with" operator is "*")

  4. https://api-eu.vusion.io/vlink-pro/v1/stores/${storeId}/labels?search=matching.item.itemId:${itemId} to search labels matched with a given item

GET https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/labels?search=name:coca&pageSize=50 
Response is 
{ 
  "query": { 
     "search": "matching.items.name:coca*", 
     "pageSize": 50, 
     "page": 1, 
     "sort": null 
}, 
"count": 10, 
"values": [ 
    { 
      "labelId": "C52A1FEB", 
      "modificationDate": "2020-01-14T10:35:00.002Z", 
      "transmission": { 
              "lastFailedFlashingDate": "2020-01-08T12:53:40.089Z", 
              "registrationDate": "2019-11-29T09:31:27.462Z", 
              "transmissionDate": "2020-01-14T10:35:00.002Z", 
              "flashingDate": "2020-01-08T12:53:40.089Z", 
              "lastFailedTransmissionDate": "2020-01-14T10:35:00.002Z" 
     }, 
     .... 
   }, 
   ...] 
}

Use correlations

All GET call are synchronous, all DELETE, PUT and POST are asynchronous, you will get a correlationId in return. To know if your request succeed or not, you have to request API with the correlationId.

Correlation object contains many fields, all are described into the Schema tab of online documentation.

Main elements are:

  • status: indicate if actions are FINISHED or not.

  • items: indicate how many items has been impacted by the action

  • labels: indicate how many labels has been impacted and how many transmissions and nfcs sync has been done.

E.g:

GET https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/events/fd4d4229-1b41-4f7b-800a-58459739c471?statistics=true 
Response is 
{
	"modificationDate": "2020-01-17T09:13:46.449Z",
	"lastImageTransmissionStartDate": "2020-01-17T09:13:46.449Z",
	"records": {
		"valid": 2,
		"duration": 3518,
		"ignored": 0,
		"processingSpeedPerHour": 2046,
		"endDate": "2020-01-17T09:13:39.87Z",
		"count": 2,
		"invalid": 0,
		"invalidRecords": [],
		"labelsModificationCount": 2,
		"startDate": "2020-01-17T09:13:36.352Z",
		"status": "SUCCESS"
	},
	"externalId": "fd4d4229-1b41-4f7b-800a-58459739c471",
	"correlationId": "fd4d4229-1b41-4f7b-800a-58459739c471",
	"eventType": "MATCHING",
	"storeId": "${storeId}",
	"creationDate": "2020-01-17T09:13:36.024Z",
	"status": "SUCCESS",
	"_score": 1,
	"statistics": {
		"items": {
			"modification": {
				"count": 0,
				"modified": 0,
				"untouched": 0,
				"deleted": 0,
				"created": 0
			},
			"unmatched": {
				"count": 0,
				"success": 0,
				"failure": 0
			},
			"matched": {
				"count": 1,
				"success": 1,
				"failure": 0
			}
		},
		"labels": {
			"creation": {
				"count": 0,
				"success": 0,
				"failure": 0
			},
			"modification": {
				"count": 2,
				"modified": 2,
				"untouched": 0,
				"deleted": 0,
				"created": 0
			},
			"deletion": {
				"count": 0,
				"success": 0,
				"failure": 0
			},
			"unmatched": {
				"count": 0,
				"success": 0,
				"failure": 0
			},
			"matched": {
				"count": 2,
				"success": 2,
				"failure": 0
			},
			"imagesTransmission": {
				"count": 4,
				"created": 0,
				"noChange": 0,
				"inProgress": 2,
				"success": 2,
				"replaced": 0,
				"failure": 0
			}
		}
	}
}

Deeper in correlations

It is also possible to get transmissions result with timeline API

  • https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/labelsTimeline?search=correlationId:fd4d4229-1b41-4f7b-800a-58459739c471 AND timelineType:IMAGE_TRANSMISSION To get transmissions related to a correlation (" AND " operator)

  • https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/labelsTimeline?search=correlationId:fd4d4229-1b41-4f7b-800a-58459739c471 AND timelineType:IMAGE_TRANSMISSION AND status:FAILED To get failed transmissions related to a correlation

E.g:

GET https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/labelsTimeline?search=correlationId:fd4d4229-1b41-4f7b-800a-58459739c471 AND timelineType:IMAGE_TRANSMISSION 
Response is 
{
	"query": {
		"search": "correlationId:fd4d4229-1b41-4f7b-800a-58459739c471 AND timelineType:IMAGE_TRANSMISSION",
		"pageSize": 50,
		"page": 1
	},
	"count": 4,
	"values": [
		{
			"metadata": {
				"externalIdHf": "157925242469500",
				"retry": 0
			},
			"timelineId": "IMAGE_TRANSMISSION.fd4d4229-1b41-4f7b-800a-58459739c471.BB0A77F8.PAGE_0",
			"externalId": "fd4d4229-1b41-4f7b-800a-58459739c471",
			"storeId": "${storeId}",
			"creationDate": "2020-01-17T09:13:44.695Z",
			"message": "Task was executed successfully",
			"duration": 10887,
			"timelineType": "IMAGE_TRANSMISSION",
			"modificationDate": "2020-01-17T09:13:55.582Z",
			"pages": 1,
			"labelId": "BB0A77F8",
			"correlationId": "fd4d4229-1b41-4f7b-800a-58459739c471",
			"status": "SUCCESS",
			"statistics": {
				"labels": 1
			},
			"_score": 10.155648
		},
		{
			"metadata": {
				"externalIdHf": "157925242469501",
				"retry": 0
			},
			"timelineId": "IMAGE_TRANSMISSION.fd4d4229-1b41-4f7b-800a-58459739c471.C51E99EC.PAGE_0",
			"externalId": "fd4d4229-1b41-4f7b-800a-58459739c471",
			"storeId": "${storeId}",
			"creationDate": "2020-01-17T09:13:44.695Z",
			"message": "Task was executed successfully",
			"duration": 10886,
			"timelineType": "IMAGE_TRANSMISSION",
			"modificationDate": "2020-01-17T09:13:55.581Z",
			"pages": 1,
			"labelId": "C51E99EC",
			"correlationId": "fd4d4229-1b41-4f7b-800a-58459739c471",
			"status": "SUCCESS",
			"statistics": {
				"labels": 1
			},
			"_score": 10.155648
		}
	]

System integration with web-hooks - Matching

Concept

VUSION Cloud allows system integration with web-hooks, which are user-defined HTTP callbacks, triggered by an event. When that event occurs, VUSION Cloud site makes an HTTP request to the URL configured. The request body will contains key information on said event, especially the correlation id to track all impacts within the platform.

Data Integration based on matchings

The goal is avoid sending hundred thousands of items to VUSION Cloud, which will not be used. With this approach, only active products, meaning associated to a label, are sent. The advantages are:

  • Limit bandwith

  • Increase overall system performance

  • Limit exposal of complete internal item database to external system

  • Know in your system which products are linked to a label and which is not

Hooks configuration & management

Create a web-hook by posting the details, as shown below. You can specify some parameters if you need (see request documentation).

{ 
     "storeId": "${storeId}", 
     "hookId": "hook-01", 
     "event": "MATCHING", 
     "callbackUrl": "https://myApi/stores/${storeId}/matching/callback?apiKey={apiKey}", 
     "name": "Matching hook" 
}

Once the hook is set up, you can query it (GET by id or GET all) and remove it (DELETE by id).

Hook configuration update could take until 5 minutes to be taken into account.

Hook notification

for each matching, hook targetUrl will receive following data. You can use the correlationId to follow the event accross the system (generation of label, transmission, etc.)

{
	"details": [
		{
			"labelId": "BB0A7724",
			"itemIds": [
				"4"
			],
			"originalItemIds": [
				"4"
			],
			"scenario": {
				"scenarioId": "STANDARD_PRICE",
				"name": "STANDARD"
			},
			"creationDate": "2020-09-22T08:45:40.503Z"
		}
	],
	"impacted": {
		"labels": 1,
		"matchedItems": 1,
		"items": 1
	},
	"correlationId": "ae57aea4-df2d-459e-95dd-fa8dd6ab2438",
	"storeId": "${storeId}",
	"eventType": "MATCHING",
	"date": "2020-09-22T08:45:40.503Z",
	"callbackDate": "2020-09-22T08:45:40.878Z"
}

System integration with web-hooks - Item Input

Concept

VUSION Cloud allows system integration with web-hooks, which are user-defined HTTP callbacks, triggered by an event. When that event occurs, VUSION Cloud site makes an HTTP request to the URL configured. The request body will contains key information on said event, especially the correlation id to track all impacts within the platform.

Hooks configuration & management

Create a web-hook by posting the details, as shown below. You can specify some parameters if you need (see request documentation).

{
	"storeId": "${storeId}",
	"hookId": "hook-01",
	"event": "ITEM_INPUT",
	"callbackUrl": "https://myApi/stores/${storeId}/matching/callback?apiKey={apiKey}",
	"name": "ITEM_INPUT hook"
}

Once the hook is set up, you can query it (GET by id or GET all) and remove it (DELETE by id).

Hook configuration update could take until 5 minutes to be taken into account.

Hook notification

for each item input, hook targetUrl will receive following data. You can use the correlationId to follow the event accross the system

{
	"file": {
		"name": "${fileName}"
	},
	"records": {
		"valid": 1,
		"count": 1,
		"invalid": 0,
		"startDate": "2020-09-22T08:51:22.725Z",
		"endDate": "2020-09-22T08:51:23.244Z",
		"invalidRecords": []
	},
	"eventType": "ITEM_INPUT",
	"externalId": "60e2e42a-8d62-453a-8410-9b06408d302d",
	"storeId": "TAB.store1",
	"correlationId": "60e2e42a-8d62-453a-8410-9b06408d302d",
	"callbackDate": "2020-09-22T08:51:23.698Z"
}

Tips & tricks

Paginated search

When executing a query that needs pagination, to make sure you paginate over all results, you have to use a sort criteria stable in time.
For eg., we recommend you to use a sorting parameter based on "creationDate, {functionalId}"

  • For labels: creationDate, labelId

  • For items: creationDate, itemId

Advanced search

When searching items, labels, timelines & correlations it possible to use the POST operation to build complex queries.
For this, don't use the "search" field, use "query" instead. The following keywords are accepted:

  • must: means the result MUST contain the following terms (operator "=")

  • must_not: means the result MUST NOT contain the following terms (operator "<>")

  • should: means the result SHOULD contain the following terms (operator "or")

Note: the query body is limited to 4 Kb.

example:

  • select items with (itemId = '3770016210027' or itemId = '5021991938818') and storeId = 'my.storeId' and status <> 'DELETED'

      "query": { 
          "bool": { 
             "should": [ 
                   {"term":{"itemId": "3770016210027"}} , {"term":{"itemId": "5021991938818"}}} 
             ], 
             "must": [ 
                 {"term":{"storeId": "my.storeId"}} 
             ], 
             "must_not": [ 
                 { 
                     "term": { 
                         "status": "DELETED" 
                      } 
                 } 
             ] 
      } 
    }

Fields filtering

To save bandwith, it is possible to filter fields returned by search APIs. Accoreding to your needs, you can either:

  • Specify a list of fields you want (for eg. add the following query parameter: &includes=labelId,connectivity.status to only return the labelId and connectivity.status fields)

  • Exclude a list of fields you don't want (for eg. add the following query parameter: &excludes=connectivity,matching to return all fields but connectivity and matching)

To get labelIds and their connectivity, you can use the following query GET https://api-eu.vusion.io/manager-pro/v1/stores/${storeId}/labels?pageSize=500&page=2&includes=labelId,connectivity.status 
Response is 
{
	"query": {
		"includes": [
			"labelId",
			"connectivity.status"
		],
		"pageSize": 5,
		"page": 1,
		"search": null,
		"sort": null
	},
	"count": 42,
	"values": [
		{
			"labelId": "C51E96EB",
			"connectivity": {
				"status": "OFFLINE"
			},
			"_score": 1
		},
		{
			"labelId": " C51E971C",
			"connectivity": {
				"status": "ONLINE"
			},
			"_score": 1
		},
		{
			"labelId": "0112E0E0",
			"connectivity": {
				"status": "OFFLINE"
			},
			"_score": 1
		},
		{
			"labelId": "C51E9711",
			"connectivity": {
				"status": "OFFLINE"
			},
			"_score": 1
		},
		{
			"labelId": "C52A1FEB",
			"connectivity": {
				"status": "OFFLINE"
			},
			"_score": 1
		}
	]
}

Manage infrastructure

Transmitter statuses

You can get the statuses of transmitters in a given store via the query

GET https://api-eu.vusion.io/manager-pro/v1/stores/{storeId}?includes=storeId,transmissionSystems 
{
	"transmissionSystems": {
		"highFrequency": {
			"memory": {
				"total": "775 MB",
				"availableProcessors": 1,
				"max": "775 MB",
				"threadCount": 57,
				"used": "423 MB",
				"free": "499 MB"
			},
			"transmitters": [
				{
					"modificationDate": "2020-01-08T15:35:57.352Z",
					"connectivity": {
						"lastOfflineDate": "2020-01-08T15:35:57.352Z",
						"status": "OFFLINE"
					},
					"id": "fdgdfgd gdfgfd gfdgdf gdfgdf",
					"creationDate": "2020-01-08T15:35:57.352Z",
					"status": "UNREACHABLE"
				},
				{
					"modificationDate": "2020-03-30T06:35:14.506Z",
					"transmissionTechnology": "HIGH_FREQUENCY",
					"connectivity": {
						"lastOfflineDate": "2020-03-30T06:35:11.891Z",
						"status": "ONLINE",
						"lastOnlineDate": "2020-03-30T06:35:14.506Z"
					},
					"name": "91.174.195.214",
					"channel": "3",
					"id": "37274",
					"creationDate": "2020-02-11T10:09:18.568Z",
					"provisionning": {
						"dns": ";",
						"channel": 0,
						"eth0Address": "",
						"gateway": "",
						"eth0Dhcp": true,
						"eth0Netmask": ""
					},
					"version": "3.1.1",
					"url": "http://91.174.195.214:80",
					"status": "OK"
				}
			],
			"configuration": {
				"licensedLabels": 10000000,
				"serial": "2xysbwwzz3tNRxX2BBxNw",
				"licensedAccessPoints": 10000,
				"fastFlash": {
					"durationInMs": 1200000,
					"profile": "ULTRA_FAST_RESPONSE",
					"status": "ACTIVE"
				}
			},
			"registeredAccessPoints": 3,
			"ip": "10.2.0.7",
			"creationDate": "2019-09-25T13:35:21.211Z",
			"type": "HIGH_FREQUENCY",
			"version": "2.1.1-rc4",
			"modificationDate": "2020-03-30T13:29:14.472Z",
			"connectivity": {
				"lastOnlineDate": "2020-03-30T13:29:14.395221Z",
				"status": "ONLINE"
			},
			"port": "8001",
			"id": "56810369105",
			"registeredLabels": 5094,
			"tasks": {
				"waiting": 0,
				"size": 0,
				"sizeReadable": 0,
				"count": 0,
				"error": 5002
			},
			"status": "OK",
			"flash": {
				"lastProfileChangeCorrelationId": "d58308ac-ba67-48e2-8e24-6a45df556ac0",
				"lastProfileChangeExternalId": "d58308ac-ba67-48e2-8e24-6a45df556ac0",
				"activeProfile": "NORMAL",
				"lastProfileChangeStartDate": "2020-03-30T12:20:13.776Z",
				"lastFlashDate": "2020-03-30T12:20:24.827Z",
				"lastProfileChangeEndDate": "2020-03-30T12:40:14.146Z",
				"lastProfileChangeDurationInMs": 1189319
			}
		}
	},
	"storeId": "${storeId}",
	"_score": 1
}

Add a transmitter

You can add a transmitter via the following query. The AP ID is used in the URL. The provisionning configuration is specified in the body. If nothing is provided, the system will use a default configuration with dhcp and autochannel

POST https://api-eu.vusion.io/manager-pro/v1/stores/{storeId}/transmitters/{id} 
BODY: 
{ 
      "eth0Dhcp": false, 
      "eth0Address": "10.121.56.40", 
      "eth0Netmask": "255.255.254.0", 
      "gateway": "10.121.56.1", 
      "dns": "4.4.4.4;8.8.8.8", "channel": 4 
} 
Response is 
{ 
     "correlationId": "2d90b256-0423-ba32-873c-01582ef51790" 
}