How-to Guide - Rest API - Administration

Introduction

The purpose of this guide is to provide an understanding of the REST Administration APIs provided by Enactor for use with external Web Sites and for Customer integration. It is separated out into functional areas, with each section related to a specific service. Note that the final URL used to access the service will be determined based on how the Enactor REST Administration API is deployed.

Following are the Enactor REST Administration APIs areas covered in this document:

• Conversion API.

  • JSON to XML Conversion.
  • XML to JSON Conversion.

• Formatting API.

  • Format to an Alpha encoded value.
  • Parse an Alpha encoded value.

• Retail API.

  • Get Device.

  • Get Location.

Conversion API

The Conversion API is used to convert Enactor entities across XML and JSON formats. Following is the list of Conversion APIs covered in this section:

• JSON to XML Conversion.
• XML to JSON Conversion.

JSON to XML Conversion

This service creates an XML Enactor entity by converting a JSON Enactor entity. The JSON is deserialized using the class name (FQCN) and the relevant JSON format. The JSON format is specified by the optional query parameter jsonFormat (this defaults to Enactor).

Request

Request Service URL

POST /conversion/xml/{className}?jsonFormat={jsonFormat}

Request Tokens

• className:
  Fully qualified class name of the Enactor entity. Refer to the section "How to determine Fully Qualified Class Name of an Enactor Entity" for more details on this.
  Eg: com.enactor.mfc.productMedia.ProductMedia

Request Parameters

• jsonFormat:
  String. The format of the JSON payload which are ENACTOR, TYPED, SIMPLE, QNAME, CLASS.
  Eg: jsonFormat=SIMPLE

Request Header

Type: application/json

Request Body

This would be a JSON string of the Enactor entity.

Response

Response Headers

Content-type: application/xml

Response Body

An XML of the Enactor entity would be generated as the response.
Type: application/xml

Request & Response Examples

Request:

POST: http://[SWARM_LEADER_IP]/WebRestApi/rest/conversion/xml/com.enactor.mfc.productMedia.ProductMedia?jsonFormat=SIMPLE
 
{
  "@qname": "retail:productMedia",
  "productMediaId": "FPCS7PX-M1",
  "productId": {
    "@qname": "retail:productKey",
    "id": "FPCS7PX"
  },
  "sortIndex": 1,
  "mediaType": "IMAGE",
  "mediaSubtype": "LARGE",
  "name": "FPCS7PX-M1",
  "mediaKey": {
    "imageKey": {
      "category": "PRODUCT",
      "id": "1_FPCS7PX",
      "type": "jpg"
    }
  }
}

Response:

Status: 200 OK
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:productMedia xmlns:ns2="http://www.enactor.com/retail" xmlns:ns3="http://www.enactor.com/core" xmlns:ns4="http://www.enactor.com/crm" xmlns:ns5="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:ns6="http://www.enactor.com/retail/storedRestaurantSaleTransaction/service" xmlns:ns7="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:ns8="http://www.enactor.com/retail/restaurantTableStatus/service" xmlns:ns9="http://www.enactor.com/orders" xmlns:ns10="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:ns11="http://www.enactor.com/addressLookup/service" xmlns:ns12="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:ns13="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns14="http://www.enactor.com/crm/customerLoyalty/service" xmlns:ns15="http://www.enactor.com/tools">
<ns2:productMediaId>FPCS7PX-M1</ns2:productMediaId>
<ns2:productId>FPCS7PX</ns2:productId>
<ns2:sortIndex>1</ns2:sortIndex>
<ns2:mediaType>IMAGE</ns2:mediaType>
<ns2:mediaSubtype>LARGE</ns2:mediaSubtype>
<ns2:name>FPCS7PX-M1</ns2:name>
<ns2:imageKey type="jpg" category="PRODUCT">1_FPCS7PX</ns2:imageKey>
</ns2:productMedia>

XML to JSON Conversion

This service creates a JSON Enactor entity by converting an XML Enactor entity. The JSON is deserialized using the class name (FQCN) and the relevant JSON format. The JSON format is specified by the optional query parameter jsonFormat (this Defaults to Enactor).

Request

Request Service URL

POST /conversion/json?jsonFormat={jsonFormat}

Request Tokens

There are no request tokens.

Request Parameters

• jsonFormat:
  String. The format of the JSON payload which are ENACTOR, TYPED, SIMPLE, QNAME, CLASS.
  Eg: jsonFormat=SIMPLE

Request Header

Type: application/xml

Request Body

This would be an XML of the Enactor entity.

Response

Response Headers

Content-type: application/json

Response Body

A JSON of the Enactor entity would be generated as the response.
Type: application/json

Request & Response Examples

Request:

POST: http://[SWARM_LEADER_IP]/WebRestApi/rest/conversion/json>jsonFormat=QNAME
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:productMedia xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns11="http://www.enactor.com/retail/restaurantTableStatus/service" xmlns:ns13="http://www.enactor.com/crm/customerLoyalty/service" xmlns:ns3="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:ns6="http://www.enactor.com/crm" xmlns:ns8="http://www.enactor.com/addressLookup/service" xmlns:ns9="http://www.enactor.com/retail/storedRestaurantSaleTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <retail:productMediaId>FPCS7PX-M1</retail:productMediaId>
    <retail:productId>FPCS7P34534543X</retail:productId>
    <retail:mediaType>IMAGE</retail:mediaType>
    <retail:mediaSubtype>LARGE</retail:mediaSubtype>
    <retail:name>FPCS7PX-M1</retail:name>
    <retail:imageKey type="jpg" category="PRODUCT">1_FPCS7PX</retail:imageKey>
</retail:productMedia> 

Response:

Status: 200 OK
 
{
  "@qname": "retail:productMedia",
  "productMediaId": "FPCS7PX-M1",
  "productId": {
    "@qname": "retail:productKey",
    "id": "FPCS7P34534543X"
  },
  "sortIndex": 1,
  "mediaType": "IMAGE",
  "mediaSubtype": "LARGE",
  "name": "FPCS7PX-M1",
  "mediaKey": {
    "imageKey": {
      "category": "PRODUCT",
      "id": "1_FPCS7PX",
      "type": "jpg"
    }
  }
}

How to determine Fully Qualified Class Name of an Enactor Entity

The easiest way to find out the fully qualified class name of an Enactor entity is to search for it in the jar files. For instance:

> jar tf mfc-2.7-SNAPSHOT.jar | grep "/ProductMedia.class"
 
com/enactor/mfc/productMedia/ProductMedia.class

Or to search in all jar files (e.g. navigate to the enactor-lib folder of an Enactor POS):

> find . -name "*.jar" | xargs -n 1 jar tf | grep "/ProductMedia.class"
 
com/enactor/mfc/productMedia/ProductMedia.class

The fully qualified class name is then obtained by replacing the slash by dot:

com.enactor.mfc.productMedia.ProductMedia

Formatting API

The Formatting API is used to encode and decode an Alpha value. Following is the list of Formatting APIs covered in this section:

• Format to an Alpha encoded value.
• Parse an Alpha encoded value.

Format to an Alpha encoded value

This service is used to encode any value into an Alpha encoded value.

Request

Request Service URL

GET /formatting/formatAlphaEncoded/{originalValue}

Request Tokens

• originalValue:
  The alpha encoded value to be formatted.

Request Parameters

There are no request parameters.

Request Body

There is no request body.

Response

Response Headers

There are no response headers.

Response Body

There is no response body.

Request & Response Examples

Request:

GET: http://\[SWARM_LEADER_IP\]/WebRestApi/rest/formatting/formatAlphaEncoded/1299

Response:

Status: 200 OK
 
{
    "originalValue": 1299,
    "formattedValue": "TFX"
}

Parse an alpha encoded value

This service is used to parse any Alpha encoded value to its original value.

Request

Request Service URL

GET /formatting/parseAlphaEncoded/{encodedValue}

Request Tokens

• encodedValue:
  The alpha encoded value to be parsed.

Request Parameters

There are no request parameters.

Request Body

There is no request body.

Response

Response Headers

There are no response headers.

Response Body

There is no response body.

Request & Response Examples

Request:

GET:
http://\[SWARM_LEADER_IP\]/WebRestApi/rest/formatting/parseAlphaEncoded/TFX

Response:

Status: 200 OK

{
"parsedValue": 1299,
"originalValue": "TFX"
}

Retail API

Following is the list of Retail APIs covered in this section:

• Get Device.
• Get Location.

Get Device

This service loads the Device with the Device ID.

Request

Request Service URL

GET /devices/{deviceId}

Request Tokens

• deviceId:
  The ID of the Device to return.

Request Parameters

There are no request parameters.

Request Body

There is no request body.

Response

Response Headers

There are no response headers.

Response Body

GetDeviceResponse

Element	Type	Description
device	IDevice	The details of the requested Device.

Request & Response Examples

Request:

GET: http://[SWARM_LEADER_IP]/WebRestApi/rest/devices/pos1@0001.enactor

Response:

Status: 200 OK
 
{
    "@type": "getDeviceResponse",
    "device": {
        "@type": "device",
        "deviceId": "pos1@0001.enactor",
        "deviceName": "POS 1@ 0001",
        "deviceNotInUse": false,
        "deviceType": "POS",
        "hostName": "localhost",
        "locationId": {
            "@type": "locationKey",
            "id": "0001"
        },
        "dataSource": {
            "@type": "dataSource"
        },
        "lastUpdated": 1606127787675
    }
}

Get Location

This service loads the Location with the Location ID.

Request

Request Service URL

GET /locations/{locationId}

Request Tokens

• locationId:
  The ID of the Location to return.

Request Parameters

There are no request parameters.

Request Body

There is no request body.

Response

Response Headers

There are no response headers.

Response Body

GetLocationResponse

Element	Type	Description
location	ILocation	The details of the requested Location.

Request & Response Examples

Request:

GET: http://[SWARM_LEADER_IP]/WebRestApi/rest/locations/0001 

Response:

Status: 200 OK
 
{
    "@type": "getLocationResponse",
    "location": {
        "@type": "store",
        "description": "Enactor Store",
        "failedSignOnAttemptsAllowed": 0,
        "failedSignOnAttemptsWarningCount": 0,
        "locationType": "store",
        "startDate": 1399503600000,
        "locationAddress": {
            "@type": "address",
            "countryCodeId": {
                "@type": "countryCodeKey",
                "id": "GB"
            },
            "organisation": "Enactor",
            "typeId": {
                "@type": "contactTypeKey"
            },
            "county": "Hertfordshire",
            "email": "info@enactor.co.uk",
            "phone1": "01992 500881",
            "postCode": "SG14 1PB",
            "street1": "Enactor House",
            "street2": "1 Bluecoats",
            "town": "Hertford",
            "referenceName": "locationAddress",
            "isTemplate": false
        },
        "locationId": "0001",
        "emailConfiguration": {
            "@type": "locationEmailConfiguration",
            "locationId": "0001",
            "referenceName": "emailConfiguration",
            "isTemplate": false
        },
        "purgeDetails": {
            "@type": "purgeDetails",
            "isTemplate": false
        },
        "failedSignOnAction": "TEMPORARY_LOCK_OUT",
        "disableInactiveUserAccountDays": 0,
        "isLive": true,
        "volumetricWeightFactor": 0,
        "customerForwarderSurcharge": 0,
        "exchangeRateConversionMethod": "INDIRECT",
        "isTemplate": false,
        "lastUpdated": 1606127787782,
        "autoFinaliseCashedUpSessions": false,
        "autoGenerateSealNumbers": false,
        "branchNumber": 1,
        "cashManagementMethod": "TERMINAL",
        "denominationEntryMethod": "EITHER",
        "suppressSpotcheckSummary": false,
        "tenderBagsOption": "DISALLOWED",
        "headerLinesCentred": false,
        "maximumCashupRecounts": 0,
        "performFloatCheckAfterSignOn": false,
        "trailerLines": "Thankyou for shopping at Enactor",
        "trailerLinesCentred": true,
        "dayEnd": [
            {
                "@type": "dayEnd",
                "day": 2
            },
            {
                "@type": "dayEnd",
                "day": 3
            },
            {
                "@type": "dayEnd",
                "day": 4
            },
            {
                "@type": "dayEnd",
                "day": 5
            },
            {
                "@type": "dayEnd",
                "day": 6
            },
            {
                "@type": "dayEnd",
                "day": 7
            },
            {
                "@type": "dayEnd",
                "day": 1
            }
        ],
        "locationBankDetails": {
            "@type": "bankDetails",
            "bankAddress": {
                "@type": "address",
                "countryCodeId": {
                    "@type": "countryCodeKey"
                },
                "typeId": {
                    "@type": "contactTypeKey"
                },
                "isTemplate": false
            },
            "isTemplate": false
        },
        "currencyId": {
            "@type": "currencyKey",
            "id": "GBP"
        },
        "localeId": {
            "@type": "localeKey",
            "id": "en",
            "country": "GB"
        },
        "systemUserId": {
            "@type": "userKey"
        },
        "groupId": {
            "@type": "groupKey",
            "id": "UK",
            "groupTypeId": "region",
            "groupHierarchyId": "All"
        },
        "defaultMenuGroupId": {
            "@type": "groupKey"
        },
        "menuGroupId": {
            "@type": "groupKey",
            "id": "FRAGRANCE",
            "groupTypeId": "menuGroup",
            "groupHierarchyId": "All",
            "variantGroupTypeId": "region",
            "variantGroupId": "All",
            "variantGroupHierarchyId": "All"
        },
        "priceGroupId": {
            "@type": "groupKey",
            "id": "UK",
            "groupTypeId": "priceGroup",
            "groupHierarchyId": "ALL",
            "variantGroupTypeId": "region",
            "variantGroupId": "All",
            "variantGroupHierarchyId": "All"
        },
        "mmGroupHierarchyId": {
            "@type": "groupKey",
            "id": "COSMETICS",
            "groupTypeId": "mmGroup",
            "groupHierarchyId": "COSMETICS",
            "variantGroupTypeId": "region",
            "variantGroupId": "All",
            "variantGroupHierarchyId": "All"
        },
        "fiscalProductGroupHierarchyId": {
            "@type": "groupKey"
        },
        "exchangeRateGroupId": {
            "@type": "groupKey"
        },
        "taxRegionId": {
            "@type": "groupKey",
            "id": "UK",
            "groupTypeId": "taxRegion",
            "groupHierarchyId": "ALLREGIONS",
            "variantGroupTypeId": "region",
            "variantGroupId": "All",
            "variantGroupHierarchyId": "All"
        },
        "taxSchemeId": {
            "@type": "taxSchemeKey",
            "id": "UK"
        },
        "nearestStores": [
            {
                "@type": "locationKey",
                "id": "0003"
            }
        ],
        "safe": [
            {
                "@type": "safe",
                "insuranceLimit": 0,
                "safeId": "1",
                "name": "Store Safe"
            }
        ],
        "fasciaId": {
            "@type": "groupKey"
        },
        "receiptHeaderImageId": {
            "@type": "imageKey",
            "id": "ENACTOR",
            "category": "RECEIPT",
            "type": "bmp"
        },
        "defaultWarehouseId": {
            "@type": "locationKey",
            "id": "0100"
        }
    }
}