Order Integration Specification Ver1.9

29 June 2021 13:19

This document is to assist suppliers of food and other goods to organisations using Cypad Kitchen Manager TM to integrate with it, enabling orders to be placed using a tablet within Kitchen Manager and sent to the supplier.
When the order is received by the supplier an Order Confirmation is sent back to the tablet. When the delivery is to be made a delivery Note is sent out. When the recipient has checked the goods have been received a Goods Received Note (GRN) is sent from the tablet back to the supplier. Not all steps may be used.

INFO

The preferred method of document transfer is SFTP and the preferred document layout is XML.

Ordering Process

An order is initially placed on a tablet. Once the tablet is synced, the order is transmitted over 3G/4G or Wi-Fi and received into the Cypad database. This is then sent to the supplier via an XML order request document. Depending on the arrangements agreed with the supplier, several communications will occur regarding the order. These are as follows:

Initial order request
Order confirmation
Delivery note
Goods received note

The preferred method of sending and receiving these documents is through the SSH File Transfer Protocol (SFTP). Generally, it is the supplier’s responsibility to maintain the SFTP server.

Order Document Construction

All order documents should be constructed in XML. Cypad uses its own XML schema. The XSD representations can be requested.

Setting Up the Server

Three separate folders should be created in the root of the SFTP server for order documents to be uploaded and downloaded. Name these as Upload, Download and Archive. Within the Download folder create two folders and name them Confirmation and Delivery. Within the Upload folder create two folders and name them Order and GRN. Cypad will place order documents in the Upload folder and the supplier should place order documents in the Download folder. The structure looks as follows:

Upload
- Order
- GRN
Download
- Confirmation
- Delivery
Archive

File Naming

Order request document names are structured as follows:

ORD--Cypad order reference number--Date of the document.xml

Here are some examples

The file name contains a GUID:

ORD--00000000-0000-0000-0000-000000000000--01-09-2014.xml

A goods received note will begin with the letters GRN:

GRN--00000000-0000-0000-0000-000000000000--01-09-2014.xml

An order confirmation document name starts with CON:

CON--00000000-0000-0000-0000-000000000000--01-09-2014.xml

A delivery note with DEL:

DEL--00000000-0000-0000-0000-000000000000--01-09-2014.xml

File Uploading

Cypad will upload the order request document to the Order folder. And the goods receive notes will be uploaded to the GRN folder. While the document is being uploaded, the file name will begin with UPL (e.g. UPL<restofthefilename>.xml). Once the file is fully uploaded the file will be renamed and the UPL will be removed. Make sure files with names beginning with UPL do not get processed as this will result in failures.

Removal of Processed Files

Once an order request has been read and processed the relevant file should be removed from its folder and moved to the Archive folder. This will be retained for future reference.

File Downloading

Once an order has been confirmed or rejected, this should be indicated by uploading an order confirmation document into the Confirmation folder within the Download folder.

Similarly a deliver note document should be uploaded to the Delivery folder within the Download folder.

During the uploading process, the file name should start with UPL. Once the file uploading is completed the file should be renamed and UPL removed to indicate that it is ready for processing.

Order Request Document

INFO

The XSD version is available at https://app.cypad.net/schemas/order.xsd

The schema for the order document is as follows:

<order>
  <header>
    <testStatus>Y</testStatus>
    <supplierIdentifier>007</supplierIdentifier>
    <purchaseOrderReference>SiteID-101</purchaseOrderReference>
    <internalOrderReference>HTML</internalOrderReference>
    <purchaseOrderDate>20140901</purchaseOrderDate>
    <requestedDeliveryDate>20140930</requestedDeliveryDate>
    <deliverySlotStartTime></deliverySlotStartTime>
    <deliverySlotEndTime></deliverySlotEndTime>
    <deliveryLocationContact></deliveryLocationContact>
    <deliveryAddress1>1 Test Drive</deliveryAddress1>
    <deliveryAddress2>City</deliveryAddress2>
    <deliveryAddress3></deliveryAddress3>
    <deliveryAddress4></deliveryAddress4>
    <deliveryAddress5></deliveryAddress5>
    <deliveryAddressPostCode>BS1 1SB</deliveryAddressPostCode>
    <numberOfOrderItems>1</numberOfOrderItems>
    <orderTotalValue>10.00</orderTotalValue>
    <locationIdentifier>SiteID</locationIdentifier>
    <locationAccountCode>1010</locationAccountCode>
    <globalLocationNumber>5060397700018</globalLocationNumber>
    <orderingOrganisationName></orderingOrganisationName>
  </header>
  <orderItems>
    <item>
      <itemName>A Product</itemName>
      <itemCode>700</itemCode>
      <itemNote></itemNote>
      <itemQuantityPerUnit>5</itemQuantityPerUnit>
      <itemQuantity>1</itemQuantity>
      <itemUnitPrice>10.00</itemUnitPrice>
      <itemLineTotalPrice>10.00</itemLineTotalPrice>
      <externalIdentifier></externalIdentifier>
    </item>
  </orderItems>
</order>

Header Section

testStatus	During the testing phase, the value should be set to Y. Once the live data processing begins, the value should be set to N
supplierIdentifier	Supplier specific identifier
purchaseOrderReference	Purchase order identifier for the given order
internalOrderReference	The Cypad reference number for the given order
purchaseOrderDate	The date the order was generated
requestedDeliveryDate	Required delivery date
deliverySlotStartTime	Currently not in use
deliverySlotEndTime	Currently not in use
deliveryLocationContact	Currently not in use
deliveryAddress1 - 5	Requested delivery address
deliveryAddressPostCode	Requested delivery address’ postcode
numberOfOrderItems	Total number of items contained in the order
orderTotalValue	Total value of the order
locationIdentifier	Identifier of the site the order is generated for
locationAccountCode	Supplier assigned code for the location
globalLocationNumber	Cypad assigned number for the organisation
orderingOrganisationName	Optional supplier assigned name for the organisation
supplierCode	Optional supplier identifier
locationAccountCode2	Optional supplier assigned secondary code for the location

Items Section

itemName	Order item description
itemCode	Order item identifier
itemNote	Additional information
itemQuantityPerUnit	Quantity of items within a unit
itemQuantity	Required quantity
itemUnitPrice	Price of single unit
itemLineTotalPrice	Total value of the items
externalIdentifier	Optional additional item identifier

Order Confirmation Document

INFO

The XSD version is available at https://app.cypad.net/schemas/confirmation.xsd

The schema for the order document is as follows:

<orderConfirmation>
  <header>
    <testStatus>Y</testStatus>
    <purchaseOrderReference>SiteID-101</purchaseOrderReference>
    <purchaseOrderDate>20140901</purchaseOrderDate>
    <orderStatus>MODIFIED</orderStatus>
    <orderStatusReason>Item out of stock</orderStatusReason>
    <confirmedDeliveryDate>20140930</confirmedDeliveryDate>
    <globalLocationNumber>5060397700018</globalLocationNumber>
  </header>
  <orderItems>
    <item>
      <itemCode>700</itemCode>
      <itemQuantity>1</itemQuantity>
      <itemPrice>10.00</itemPrice>
      <itemStatus>C</itemStatus>
      <itemReasonForChange>Out of stock</itemReasonForChange>
      <itemSubstitute>701</itemSubstitute>
    </item>
  </orderItems>
</orderConfirmation>

Header Section

testStatus	During the testing phase, the value should be set to Y. Once the live data processing begins, the value should be set to N
purchaseOrderReference	The Cypad reference number as per order request
purchaseOrderDate	The date the order was generated as per order request
orderStatus	If the order can be fulfilled in its entirety the status should be set to ACCEPTED. If a change has been made, such as offering an alternative for a product, the status should be set to MODIFIED. If the order cannot be fulfilled the status should be set to REJECTED
orderStatusReason	Description of the order status. Only required in MODIFIED and REJECTED instances
confirmedDeliveryDate	Delivery date confirmed by the supplier
globalLocationNumber	Cypad assigned number for the organisation

Items Section

IMPORTANT

This section is only needed for a modified order. ACCEPTED and REJECTED orders should only contain the header section. All tags except for itemSubstitute and itemReasonForChange are compulsory. When an ordered item has been altered, itemReasonForChange tag must be included. When an alternative product is offered itemSubstitute tag must be included.

itemCode	Order item identifier as per the order request
itemQuantity	Confirmed quantity of items
itemPrice	Confirmed price of the item
itemStatus	This should be set to A for accepted items, R for rejected and C for Changed if an amendment has been made such as an alternative product being offered
itemReasonForChange	Description of the nature of the change
itemSubstitute	If an alternative product is offered, the product identifier should be inserted.

Delivery Note

INFO

The XSD version is available at https://app.cypad.net/schemas/confirmation.xsd

The schema for the order document is as follows:

<orderDeliveryNote>
  <header>
    <testStatus>Y</testStatus>
    <purchaseOrderReference>SiteID-101</purchaseOrderReference>
    <purchaseOrderDate>20140901</purchaseOrderDate>
    <confirmedDeliveryDate>20140930</confirmedDeliveryDate>
    <globalLocationNumber>5060397700018</globalLocationNumber>
  </header>
  <orderItems>
    <item>
      <itemCode>700</itemCode>
      <itemQuantity>1</itemQuantity>
      <itemPrice>10.00</itemPrice>
      <itemSubstitute>701</itemSubstitute>
      <itemReasonForChange>Out of stock</itemReasonForChange>
    </item>
  </orderItems>
</orderConfirmation>

Header Section

testStatus	During the testing phase, the value should be set to Y. Once the live data processing begins, the value should be set to N
purchaseOrderReference	The Cypad reference number as per order request
purchaseOrderDate	The date the order was generated as per order request
confirmedDeliveryDate	Delivery date confirmed by the supplier
globalLocationNumber	Cypad assigned number for the organisation

Items Section

IMPORTANT

All tags except for itemSubstitute and itemReasonForChange are compulsory. When an ordered item has been altered, itemReasonForChange tag must be included. When an alternative product is offered itemSubstitute tag must be included.

itemCode	Order item identifier as per the order request
itemQuantity	Confirmed quantity of items
itemPrice	Confirmed price of the item
itemSubstitute	If an alternative product is offered, the product identifier should be inserted.
itemReasonForChange	If an alternative product is offered, description of the nature of the change

Goods Received Note

INFO

The XSD version is available at https://app.cypad.net/schemas/grn.xsd

The schema for the order document is as follows:

<orderGRN>
  <header>
    <testStatus>Y</testStatus>
    <supplierIdentifier>007</supplierIdentifier>
    <purchaseOrderReference>SiteID-101</purchaseOrderReference>
    <internalOrderReference>00000000-0000-0000-0000-000000000000</internalOrderReference>
    <purchaseOrderDate>20140901</purchaseOrderDate>
    <requestedDeliveryDate>20140930</requestedDeliveryDate>
    <actualDeliveryDate>20140930</actualDeliveryDate>
    <deliverySlotStartTime></deliverySlotStartTime>
    <deliverySlotEndTime></deliverySlotEndTime>
    <deliveryLocationContact></deliveryLocationContact>
    <deliveryAddress1>1 Test Drive</deliveryAddress1>
    <deliveryAddress2>City</deliveryAddress2>
    <deliveryAddress3></deliveryAddress3>
    <deliveryAddress4></deliveryAddress4>
    <deliveryAddress5></deliveryAddress5>
    <deliveryAddressPostCode>BS1 1SB</deliveryAddressPostCode>
    <numberOfOrderItems>1</numberOfOrderItems>
    <orderTotalValue>10.00</orderTotalValue>
    <locationIdentifier>SiteID</locationIdentifier>
    <locationAccountCode>1010</locationAccountCode>
    <globalLocationNumber>5060397700018</globalLocationNumber>
    <orderingOrganisationName></orderingOrganisationName>
    <supplierCode></supplierCode>
    <locationAccountCode2></locationAccountCode2>
  </header>
  <orderItems>
    <item>
      <itemName>A Product</itemName>
      <itemCode>700</itemCode>
      <itemNote></itemNote>
      <itemQuantityPerUnit>5</itemQuantityPerUnit>
      <itemQuantity>1</itemQuantity>
      <itemUnitPrice>10.00</itemUnitPrice>
      <itemLineTotalPrice>10.00</itemLineTotalPrice>
      <externalIdentifier></externalIdentifier>
    </item>
  </orderItems>
</orderGRN>

Header Section

testStatus	During the testing phase, the value should be set to Y. Once the live data processing begins, the value should be set to N
supplierIdentifier	Supplier specific identifier
purchaseOrderReference	Purchase order identifier for the given order
internalOrderReference	The Cypad reference number for the given order
purchaseOrderDate	The date the order was generated
requestedDeliveryDate	Required delivery date
actualDeliveryDate	Actual delivery date
deliverySlotStartTime	Currently not in use
deliverySlotEndTime	Currently not in use
deliveryLocationContact	Currently not in use
deliveryAddress1 - 5	Requested delivery address
deliveryAddressPostCode	Requested delivery address’ postcode
numberOfOrderItems	Total number of items contained in the order
orderTotalValue	Total value of the order
locationIdentifier	Identifier of the site the order is generated for
locationAccountCode	Supplier assigned code for the location
globalLocationNumber	Cypad assigned number for the organisation
orderingOrganisationName	Optional supplier assigned name for the organisation
supplierCode	Optional supplier identifier
locationAccountCode2	Optional supplier assigned secondary code for the location

Items Section

itemName	Order item description
itemCode	Order item identifier
itemNote	Additional information
itemQuantityPerUnit	Quantity of items within a unit
itemQuantity	Required quantity
itemUnitPrice	Price of single unit
itemLineTotalPrice	Total value of the items
externalIdentifier	Optional additional item identifier

Testing

The following table illustrates the testing scenarios that should be demonstrated by the application, supplier develops.

ID	Test Case	Pre-Conditions	Steps	Expected Result
1	Fully confirmed order	All the products are correct All products are in stock Correct account code Correct delivery date	Send an order where account code and delivery date are correct	Receive an order confirmation indicating all the ordered products are in stock and can be delivered for the given date
2	Partially correct order – Account code is incorrect	All the products are correct All products are in stock Incorrect account code Correct delivery date	Send an order where account code is wrong and delivery date is correct	Receive order rejection notice indicating order has been rejected due to wrong account code
3	Partially correct order – Delivery date is incorrect	All the products are correct All products are in stock Correct account code Incorrect delivery date	Send an order where delivery date is wrong and account code is correct	Receive order rejection notice indicating order has been rejected due to wrong delivery date
4	Incorrect order – Delivery date and account code are incorrect	All the products are correct All products are in stock Incorrect account code Incorrect delivery date	Send an order where delivery date is wrong and account code is correct.	Receive order rejection notice indicating order has been rejected due to wrong delivery date and wrong account code
5	Verify out of stock status for a single item order	Product is correct Requested order product is not in stock Correct account code Correct delivery date	Send and order with one item which is out of stock	Receive order rejection notice indicating order has been rejected due to insufficient stock
6	Verify out of stock status for multiple line order – Substitute products are unavailable	Order should contain multiple products Order consists of a combination of in-stock and out of stock products Correct account code Correct delivery date	Send an order with a combination of in-stock and out of stock products	Process the order with available items. Receive order conformation by indicating certain products are unavailable and only the available products will be delivered
7	Verify out of stock status for multiple line order – Substitute products are available	Order should contain multiple products Order consists of a combination of in-stock and out of stock products Correct account code Correct delivery date	Send an order with a combination of in-stock and out of stock products	Process the order with available items Receive order conformation by indicating certain products are unavailable and substitutes will be delivered
8	Verify discontinued items in an order - Substitute products are available	Order should contain multiple products One or several products should be discontinued Substitute products for discontinued products are available	Send an order with a combination of discontinued and live products	Receive an order confirmation with discontinued products being replaced by substitute products
9	Verify discontinued items in an order - Substitute products are unavailable	Order should contain multiple products One or several products should be discontinued Substitute products for discontinued products are unavailable	Send an order with a combination of discontinued and live products	Receive an order confirmation with discontinued products being indicated as unavailable and the live products as being delivered
10	Verify the validity of the product codes for multiple products order	Order should contain multiple products with invalid product codes	Send an order with both valid product codes and invalid product codes	Receive an order confirmation with valid items and indicate invalid product codes exist
11	Verify the validity of the product code for a single product order	Order should contain a single product with an invalid product code	Send an order with an invalid product code	Receive order rejection notice indicating order contains an invalid product code
12	Verify the order process for the ordered products that are below the ordered quantity	Ordered products are in stock Available quantity is less than ordered quantity	Send the order	Receive order conformation by indicating product quantities are below the available quantity and the available quantity will be delivered

Order Integration Specification Ver1.9.pdf
(1000 KB)