Attachment_AA_COTS_Web_Services_Data_Exchange_Specifications_.pdf

May 12, 2015 i

ATTACHMENT A OF

PERFORMANCE WORK STATEMENT

CALL ORDER TRACKING SYSTEM (COTS)

WEB SERVICES DATA EXCHANGE

SPECIFICATION

SNAP STORE VISIT CONTRACT

May 12, 2015 ii

Call Order Tracking System (COTS)

Web Services Data Exchange Specification

March 17, 2015

Prepared for:

U.S. Department of Agriculture Food and Nutrition Service (FNS)

Information Technology Division (ITD)

3101 Park Center Drive

Alexandria, Virginia 22302

TABLE OF CONTENTS

May 12, 2015 iii

1. WEB SERVICES OVERVIEW

2. COTS WEB SERVICE

2.1 Functionality Description

2.2 Infrastructure Guidelines

2.3 WSDL

2.4 XML Schema Definition

APPENDIX A: COTS WEB SERVICE WSDL

APPENDIX B: CALL ORDER DATA

1. Call Order Data Table

2. Call Order Data (sample XML)

3. Call Order Data (XSD)

APPENDIX C: CALL ORDER CONFIRMATION DATA

1. Call Order Confirmation Data Table

2. Call Order Confirmation Data (sample XML)

3. Call Order Confirmation Data (XSD)

APPENDIX D: ERROR CODES

USDA FNS Call Order Tracking System (COTS) Web Services Specification

May 12, 2015 1

1. WEB SERVICES OVERVIEW

The term "Web service" refers to a piece of code implementing an XML interface to an application resource accessible over open protocols. Web services support integration of loosely coupled applications that are language-neutral and platform independent. They are based on open standards and are easy to deploy over a standard transport protocol such as HTTP. Web Services are XML-based which facilitates interoperability.

The core aspects of a Web service might be an application component that:

Communicates via open protocols (HTTP, SMTP, etc.)

Processes XML messages framed using SOAP

Describes its messages using XML Schema

Provides an endpoint description using WSDL

Can be discovered using UDDI

The COTS Web service will have each of these aspects represented.

The web service itself will require no Graphical User interface, since it is intended to be called from software.

Some platforms provide a simplistic, vanilla User Interface (UI) for development and testing purposes, but a UI is not required for a web service. All that is required is the ability to receive HTTP SOAP requests, service the request appropriately, and return an HTTP SOAP response over the same connection. These requests will run over a secure channel (HTTPS) and each request will most likely contain authentication credentials (username/password).

A SOAP request is like a standard HTTP request from a browser, but it is formatted as XML and represents a "function call" on the server. The implementation of the web service performs this function and returns a SOAP response--which is also a standard HTTP response formatted as XML.

Additional information on Web Services can be found on http://msdn.microsoft.com/webservices/webservices/default.aspx.

2. COTS WEB SERVICE

2.1 FUNCTIONALITY DESCRIPTION

The Call Order Tracking System (COTS) in STARS will utilize Web Services technology to provide data electronically to the Store Visit Contractor systems. Specifically, two sets of data will be exchanged:

1. Call Order

2. Call Order Confirmation

The real-time exchange of data over web services will replace the data files that are currently sent via email. In the new system, no data files will be generated by COTS. The data that will be transmitted is described in Appendix B and Appendix C.

Using a web service-based technology for data exchange, the Call Order process will work as follows:

1. (STARS) The user initiates and issues the Call Order (generates the Call Order Letter).

2. (STARS) The system generates a PDF file of the Call Order Letter with Store Listing and attaches to an email sent to the user.

3. The user forwards the email to the Contractor. (This is true only for deficiency letter)

4. (STARS) The system builds a HTTP SOAP request with the contents formatted as XML and communicates via web services, sending the Call Order data to the Contractor systems.

5. (Contractor system) The system receives the message and processes the contents of the message through to the internal systems.

http://msdn.microsoft.com/webservices/webservices/default.aspx

May 12, 2015 2

6. (Contractor system) The system returns an XML-formatted, HTTP SOAP response back to STARS acknowledging successful receipt and processing of the message.

7. The Contractor performs the Store Visits and provides Deliverables to FNS.

8. (STARS) The user enters Deliverables data in STARS and issues the Confirmation Letter.

9. (STARS) The system generates a PDF file of the Confirmation Letter with Store Listing and attaches to an email sent to the user.

10. The user forwards the email to the Contractor.

11. (STARS) The system builds a HTTP SOAP request with the contents formatted as XML and communicates via web services, sending the Confirmation Letter data to the Contractor systems.

12. (Contractor system) The system receives the message and processes the contents of the message through to the internal systems.

13. (Contractor system) The system returns an XML-formatted, HTTP SOAP response back to STARS acknowledging successful receipt and processing of the message.

14. (Contractor system) The system processes the Call Order confirmation data (approved costs).

15. (Contractor) The Contractor generates an invoice and submits to FNS.

2.2 INFRASTRUCTURE GUIDELINES

Architecture

Web services communication utilizes a set of foundation protocols that share a common architecture and are meant to be realized in a variety of independently developed and deployed systems. Therefore as the host of the web service, the Store Visit Contractor have the flexibility to provide a technology infrastructure using software that is already running or favored by your organization. The restriction is that the infrastructure must support web services.

In the event that no current environment exists that supports web services, there are alternative platforms, many of them very simple and inexpensive, which can be used to implement the web service if necessary. We have some knowledge of these other platforms and the levels of effort required, but we will limit researching them further unless it becomes necessary.

Environment Failover

Both the source (STARS) and target (Store Visit Contractor) systems should be sufficiently redundant such that there is minimal downtime and disruption to the normal business operations due to system failure.

Security

Two methods of security will be employed to ensure only authorized access of the web service:

1. Transmission over secure channel (HTTPS)

2. Username/password Authentication of each request

The web service implementation provided by the Store Visit Contractor shall authenticate each request as part of processing the request.

The username and password shall be provided by the Store Visit Contractor, and shall adhere to the following requirements:

1. The username shall be at least six characters long, not to exceed 14 characters.

May 12, 2015 3

2. The password shall be at least eight characters long, not to exceed 20 characters. The password shall comply with FNS password complexity rules (e.g. it shall contain at least two of the following:

uppercase; numbers; and punctuation).

Response/Error Handling

The web service implementation provided by the Store Visit Contractors shall provide a simple string response as the return for the web service call to indicate the outcome of the request. It is expected that the target web service return with the appropriate error code at the first detection of an error condition, multiple errors should not be processed and returned. The string that should be returned as the response from the web service calls for both the Order and Confirmation should be one of:

1. SUCCESS

2. FAIL <error code> <message> where <error code> is the appropriate code from Appendix D, and <message> is a technical description of the failure from Appendix D so an application administrator may work with the Store Visit Contractors to further diagnose the issue. SUCCESS indicates that the request was processed correctly without error.

An example of a failure message may be: FAIL –100 Authentication failed. User name/password supplied are incorrect.

2.3 WSDL

The WSDL for a web service defines the functions (operations) provided by the service, mainly involving the various types of data to be exchanged and the authentication/security protecting that interaction. A complete WSDL definition contains all of the information necessary to invoke a Web service.

The WSDL can be used by most platforms and web service libraries to generate both server and client code, or the code can be created by hand if such a tool is not available. At any rate, the web service must conform to the provided WSDL. Conformity guarantees compatibility. The WSDL file defines everything required to write a program to work with an XML Web service.

The notation that a WSDL file uses to describe message formats is based on the XML Schema standard which means it is both programming-language neutral and standards-based, making it suitable for describing XML Web services interfaces that are accessible from a wide variety of platforms and programming languages.

A sample structure of the WSDL is shown in the first table below. Each of the elements of the WSDL is briefly described in the table that follows.

WSDL definition structure

<definition>

<!-- abstract definitions -->

<types> ...

<message> ...

<portType> ...

<!-- concrete definitions -->

<binding> ...

<service> ...

</definition>

May 12, 2015 4

WSDL Elements

Element Name Description Types A container for abstract type definitions defined using XML

Schema.

message A definition of an abstract message that may consist of multiple parts, each part may be of a different type.

PortType An abstract set of operations supported by one or more endpoints (commonly known as an interface); operations are defined by an exchange of messages.

Binding A concrete protocol and data format specification for a particular portType. Describes how to invoke the service.

Service A collection of related endpoints, where an endpoint is defined as a combination of a binding and an address (URI). Names the service.

The STARS Contractor has defined the contents of the WSDL. This is included in Appendix A.

2.4 XML SCHEMA DEFINITION

The XML content of the web service call will have a separate definition in the form of an XSD file--XML Schema Definition. Most platforms can use an XSD file to generate code and parsers to work with XML, as well as use the XSD for validation. The XML developed by the STARS Contractor will all conform to the XSD, so the XSD should be used to parse and validate. The XML will be a "dumb" payload for each of the web service calls that send the letter data.

XML Schema makes it possible to describe the type and structure of XML documents. An XML Schema definition serves as the official documentation for a set of XML messages.

A schema definition simply tells you what XML messages may be used but not how they relate to each other.

The WSDL provides an XML grammar for describing the interrelation of the XML elements.

All content in the COTS XML will be provided as text within XML elements of the appropriate name. The text content, where appropriate, will be wrapped in CDATA sections to avoid problems with XML-prohibited characters.

The STARS Contractor has defined the contents of the XSD files. These are included in Appendix B (Call Order Data) and Appendix C (Call Order Confirmation Data).

May 12, 2015 5

APPENDIX A: COTS WEB SERVICE WSDL

This appendix provides the WSDL defining the COTS web service (cots_contractor.wsdl).

<?xml version="1.0" encoding="utf-8"?> <wsdl:definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://stars.fns.usda.gov/stars/cots" xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" targetNamespace="http://stars.fns.usda.gov/stars/cots" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"> <wsdl:types> <s:schema elementFormDefault="qualified" targetNamespace="http://stars.fns.usda.gov/stars/cots"> <s:element name="SubmitCallOrder"> <s:complexType> <s:sequence> <s:element minOccurs="1" maxOccurs="1" name="username" type="s:string" /> <s:element minOccurs="1" maxOccurs="1" name="password" type="s:string" /> <s:element minOccurs="1" maxOccurs="1" name="identifier" type="s:string" /> <s:element minOccurs="1" maxOccurs="1" name="content" type="s:string" /> </s:sequence> </s:complexType> </s:element> <s:element name="SubmitCallOrderResponse"> <s:complexType> <s:sequence> <s:element minOccurs="1" maxOccurs="1" name="SubmitCallOrderResult" type="s:string" /> </s:sequence> </s:complexType> </s:element> <s:element name="SubmitCallOrderConfirmation"> <s:complexType> <s:sequence> <s:element minOccurs="1" maxOccurs="1" name="username" type="s:string" /> <s:element minOccurs="1" maxOccurs="1" name="password" type="s:string" /> <s:element minOccurs="1" maxOccurs="1" name="identifier" type="s:string" /> <s:element minOccurs="1" maxOccurs="1" name="content" type="s:string" /> </s:sequence> </s:complexType> </s:element> <s:element name="SubmitCallOrderConfirmationResponse"> <s:complexType> <s:sequence> <s:element minOccurs="1" maxOccurs="1" name="SubmitCallOrderConfirmationResult" type="s:string" /> </s:sequence> </s:complexType> </s:element> </s:schema> </wsdl:types> <wsdl:message name="SubmitCallOrderSoapIn"> <wsdl:part name="parameters" element="tns:SubmitCallOrder" /> </wsdl:message> <wsdl:message name="SubmitCallOrderSoapOut"> <wsdl:part name="parameters" element="tns:SubmitCallOrderResponse" /> </wsdl:message> <wsdl:message name="SubmitCallOrderConfirmationSoapIn"> <wsdl:part name="parameters" element="tns:SubmitCallOrderConfirmation" />

May 12, 2015 6

</wsdl:message> <wsdl:message name="SubmitCallOrderConfirmationSoapOut"> <wsdl:part name="parameters" element="tns:SubmitCallOrderConfirmationResponse" /> </wsdl:message> <wsdl:portType name="COTSContractorServiceSoap"> <wsdl:operation name="SubmitCallOrder"> <wsdl:input message="tns:SubmitCallOrderSoapIn" /> <wsdl:output message="tns:SubmitCallOrderSoapOut" /> </wsdl:operation> <wsdl:operation name="SubmitCallOrderConfirmation"> <wsdl:input message="tns:SubmitCallOrderConfirmationSoapIn" /> <wsdl:output message="tns:SubmitCallOrderConfirmationSoapOut" /> </wsdl:operation> </wsdl:portType> <wsdl:binding name="COTSContractorServiceSoap" type="tns:COTSContractorServiceSoap"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" /> <wsdl:operation name="SubmitCallOrder"> <soap:operation soapAction="http://stars.fns.usda.gov/stars/cots/SubmitCallOrder" style="document" /> <wsdl:input> <soap:body use="literal" /> </wsdl:input> <wsdl:output> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> <wsdl:operation name="SubmitCallOrderConfirmation"> <soap:operation soapAction="http://stars.fns.usda.gov/stars/cots/SubmitCallOrderConfirmation" style="document" /> <wsdl:input> <soap:body use="literal" /> </wsdl:input> <wsdl:output> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="COTSContractorService"> <documentation xmlns="http://schemas.xmlsoap.org/wsdl/" /> <wsdl:port name="COTSContractorServiceSoap" binding="tns:COTSContractorServiceSoap"> <soap:address location="http://localhost/COTSContractorService/dummy.do" /> </wsdl:port> </wsdl:service> </wsdl:definitions>

The parameters of the method calls are provided below:

Parameter Name Description username The user name for authenticating to the Contractors web service password The password for authenticating to the Contractors web service identifier The identifier parameter is a placeholder to allow flexibility to uniquely describe the contents of the data set. It is currently provided as the Call Order Number. For instance, the identifier could be used by your web service as a part of a file name if you choose to save the xml data to a file. It can be ignored since all the data that is necessary will be provided in the xml data.

content The raw XML data containing call order or confirmation data

May 12, 2015 7

APPENDIX B: CALL ORDER DATA

This appendix lists and describes the data that is exchanged electronically via web services to the Store Visit Contractor systems for submission of the Call Order (Cover Letter). This corresponds to the SubmitCallOrder method in the web service.

The format of the data is represented in a record format for ease of description. The actual structure and layout of the data will be XML-based and defined in more detail in the callOrder.xsd file.

1. CALL ORDER DATA TABLE

Data Element Description Length Additional Information

Call Order Level Data

Call Order Type The type of the Call Order – Routine or Expedited.

1 “R” for Routine “E” for Expedited

Work Center Identification

This will be work-center code 3 Replace FO code with 3-letter, Work Center code

Call Order Number The unique number assigned to the Call Order.

9 The call order number will have 3-letter alpha numeric work center code, not the field office code

Order Date Date that the Call Order was completed and issued to the Contractor.

10 YYYY-MM-DD format (use leading 0 for months and days < 10)

Due Date Date that the Call Order is due back to the FO. Determined based on the number of days permitted by the Contract for the type of Call Order.

10 YYYY-MM-DD format (use leading 0 for months and days < 10)

Cover letter issued by User

The user-name who issued Cover Letter

30 This information can be used by contractor to communicate back when visit is done, otherwise if they have any problem with call order.

Cover letter issued by user’s email address

Email address of user who issued cover letter

40 This information can be used by contractor to communicate back when visit is done, otherwise if they have any problem with call order.

Total Number of Visits Ordered

Stores count in this transmission 2 The stores count can be one, up to maximum of 30 stores

Store Level Data

FNS Number FNS Number of the Store. 10 Populate FNS Number in left most characters; remaining spaces shall be blank characters.

Store Name Name of the Store. 50 No concatenation of Store Number.

Chain Store Number Number of the store 10 Do not display if store has no number.

Owner Name Oldest, currently associated Owner or Officer if the Store is owned by a Corporation.

50 First and Last Name concatenated “None” if no Owner or Officer exists as appropriate or if Store is owned by a

May 12, 2015 8

Data Element Description Length Additional Information Public Corporation.

Street Name and Number

The Street Number and Street Name of the Store Location Address.

48 If the combined total of both fields attain the maximum character length, the Street Name field will be reduced by one character at the last character.

Additional Address Information (2nd line of address)

Additional address information for the Store Location Address such as suite number, floor, unit, mail stop, stall number.

40 None

County Name The County of the Store Location Address.

50 None

City The City of the Store Location Address.

30 None

State The State of the Store Location Address.

2 None

Zip Code The Zip Code of the Store Location Address.

5 Zip Code Suffix is not included.

Phone Number The Phone Number of the Store. 12 Unformatted phone number

Hours of Operation The operating hours and days for the Store.

100 Field 12d (Operating Hours) on the 252 Application. If 12c on the 252 Application identifies the Store as “Open 7 days, 24 hours” the system should default the Hours of Operation as “Open 7 days, 24 hours” in place of actual Store hours.

Information Free-form text entered by the user. 255 Information to the Contractor for the specific Store.

2. CALL ORDER DATA (SAMPLE XML)

The following is a sample representation of the Call Order data in an XML format.

<fns_CallOrder> <callOrderType>R</callOrderType> <workCenterCode>WC1</workCenterCode> <callOrderNumber>WC1-00267</callOrderNumber> <orderDate>2004-04-05</orderDate> <dueDate>2004-04-15</dueDate> <visitsOrdered>30</visitsOrdered> <coverLetterIssuedBy>John Doe (ABCD, XX)</coverLetterIssuedBy> <emailAddress>john.doe@usda.fns.gov<emailAddress> <stores> <store> <fnsNumber>0001234</fnsNumber> <storeName><![CDATA[CARLOCK MARKET]]></storeName> <chainStoreNumber><![CDATA[603]]></chainStoreNumber> <ownerName><![CDATA[HUGH CARLOCK]]></ownerName>

May 12, 2015 9

<streetAddress><![CDATA[286 S MAIN]]></streetAddress> <additionalStreetAddress><![CDATA[SUITE 100]]></additionalStreetAddress> <city><![CDATA[CHANDLERVILLE]]></city> <state>IL</state> <zip>62627</zip> <county><![CDATA[CASS]]></county> <phone>2174582302</phone> <hours><![CDATA[MON-THUR 10A-12P]]></hours> </store> <store> <fnsNumber>0006789</fnsNumber> <storeName><![CDATA[SAMS MARKET]]></storeName> <ownerName><![CDATA[HUGH JONES]]></ownerName> <streetAddress><![CDATA[123 S MAIN]]></streetAddress> <city><![CDATA[CHICAGO]]></city> <state>IL</state> <zip>62627</zip> <county><![CDATA[CASS]]></county> <phone>2171232302</phone> <hours><![CDATA[MON-FRI 10A-12P]]></hours> <information><![CDATA[This is MORE information.

]]></information> </store> </stores> </fns_CallOrder>

3. CALL ORDER DATA (XSD)

The following is the XML Schema Definition (XSD) of the Call Order data (callOrder.xsd).

<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:element name="fns_CallOrder"> <xs:complexType> <xs:sequence> <xs:element ref="callOrderType"/> <xs:element ref="workCenterCode"/> <xs:element ref="callOrderNumber"/> <xs:element ref="orderDate"/> <xs:element ref="dueDate"/> <xs:element ref="visitsOrdered"/> <xs:element ref="coverLetterIssuedBy"/> <xs:element ref="emailAddress"/> <xs:element ref="stores"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="callOrderType" type="xs:string"/> <xs:element name="fieldOfficeCode" type="xs:string"/> <xs:element name="callOrderNumber" type="xs:string"/>

May 12, 2015 10

<xs:element name="orderDate" type="xs:date"/> <xs:element name="dueDate" type="xs:date"/> <xs:element name="visitsOrdered" type="xs:int"/> <xs:element name="coverLetterIssuedBy" type="xs:string"/> <xs:element name="emailAddress" type="xs:string"/> <xs:element name="stores"> <xs:complexType> <xs:sequence> <xs:element maxOccurs="30" ref="store"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="store"> <xs:complexType> <xs:sequence> <xs:element ref="fnsNumber"/> <xs:element ref="storeName"/> <xs:element ref="ownerName"/> <xs:element ref="streetAddress" minOccurs="0"/> <xs:element ref="additionalStreetAddress" minOccurs="0"/> <xs:element ref="city"/> <xs:element ref="state"/> <xs:element ref="zip"/> <xs:element ref="county"/> <xs:element ref="phone"/> <xs:element ref="hours"/> <xs:element ref="information" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="fnsNumber" type="xs:string"/> <xs:element name="storeName" type="xs:string"/> <xs:element name="chainStoreNumber" type="xs:string"/> <xs:element name="ownerName" type="xs:string"/> <xs:element name="streetAddress" type="xs:string"/> <xs:element name="additionalStreetAddress" type="xs:string"/> <xs:element name="city" type="xs:string"/> <xs:element name="state" type="xs:string"/> <xs:element name="zip" type="xs:string"/> <xs:element name="county" type="xs:string"/> <xs:element name="phone" type="xs:string"/> <xs:element name="hours" type="xs:string"/> <xs:element name="information" type="xs:string"/> </xs:schema>

May 12, 2015 11

APPENDIX C: CALL ORDER CONFIRMATION DATA

This appendix lists and describes the data that is exchanged electronically via web services to the Store Visit Contractor systems for submission of the Call Order Confirmation (Confirmation Letter). This corresponds to the SubmitCallOrderConfirmation method in the web service.

The format of the data is represented in a record format for ease of description. The actual structure and layout of the data will be XML-based and defined in more detail in the orderConfirm.xsd file.

1. CALL ORDER CONFIRMATION DATA TABLE

Data Element Description Length Additional Information

Call Order Level Data

Call Order Type The type of the Call Order – Routine or Expedited.

1 “R” for Routine “E” for Expedited

Work Center Identification

Three letter work center code (do we need this?)

Call Order Number The unique number assigned to the Call Order.

9 The three letter code in call order numbers will be work center code

Order Date Date that the Call Order was completed and issued to the Contractor.

10 YYYY-MM-DD format (use leading 0 for months and days < 10)

Due Date Date that the Call Order is due back to the FO. Determined based on the number of days permitted by the Contract for the type of Call Order.

10 YYYY-MM-DD format (use leading 0 for months and days < 10)

Visits Ordered The total number of Stores in the Call Order for which visits were expected.

3 None

Deliverables Received The total number of visits for which Deliverables were provided to and received by FNS.

3 None

Completed Status The status of the Call Order. 40 Display “Confirmation Letter Issued”.

Cover Letter Issued By: Enter the name of the Field Specialist.. 30 Trim to field length.

Specialist Email address

Enter the Specialists’ email address for communication and follow-up purposes.

40 Use the appropriate email validation to ensure a valid FNS email address is entered.

Store Level Data

FNS Number FNS Number of the Store. 10 Populate FNS Number in leftmost characters; remaining spaces shall be blank characters.

Store Name The name of the Store in the Call Order. 50 None

Chain Store Number Number of the store 10 Do not display if store has no number.

County Name The County of the Store Location Address. 50 None

May 12, 2015 12

Data Element Description Length Additional Information

Received Date Date that the Call Order Deliverables were received by FNS personnel.

10 YYYY-MM-DD format (use leading 0 for months and days < 10)

Accepted Date Date that the Call Order Deliverables were deemed by FNS personnel to be complete and met all necessary requirements.

10 YYYY-MM-DD format (use leading 0 for months and days < 10)

Contracted Visit Rate The rate per the Contract for the each state Store Visit based on the Call Order Type.

14 Decimal format 0.00.

Liquidated Damages The amount of liquidated damages for late or deficient Deliverables for the Store Visit.

14 Decimal format 0.00.

Due Per Deliverable The Contracted Visit Rate minus Liquidated Damages.

14 Decimal format 0.00.

Can be negative amount.

2. CALL ORDER CONFIRMATION DATA (SAMPLE XML)

The following is a sample representation of the Call Order Confirmation data in an XML format.

<fns_OrderConfirm> <callOrderType>R</callOrderType> <workCenterCode>WC1</workCenterCode> <callOrderNumber>WC1-00267</callOrderNumber> <orderDate>2004-04-05</orderDate> <dueDate>2004-04-15</dueDate> <visitsOrdered>5</visitsOrdered> <deliverablesReceived>100</deliverablesReceived> <confirmedBy>John Doe (ABCD, XX)</confirmedBy> <emailAddress>john.doe@usda.fns.gov<emailAddress> <completedStatus>CONFIRMATION LETTER ISSUED</completedStatus> <stores> <store> <fnsNumber>0001234</fnsNumber> <storeName><![CDATA[CARLOCK MARKET]]></storeName> <chainStoreNumber><![CDATA[603]]></chainStoreNumber> <county><![CDATA[CASS]]></county> <receivedDate>2004-04-05</receivedDate> <acceptedDate>2004-04-15</acceptedDate> <contractedVisitRate>111.90</contractedVisitRate> <liquidatedDamages>10.00</liquidatedDamages> <duePerDeliverable>90.00</duePerDeliverable> </store> <store> <fnsNumber>1256775</fnsNumber> <storeName><![CDATA[Jim’s Shack]]></storeName> <county><![CDATA[SPRINGFIELD]]></county> <receivedDate>2004-04-05</receivedDate> <acceptedDate>2004-04-15</acceptedDate> <contractedVisitRate>111.90</contractedVisitRate>

May 12, 2015 13

<liquidatedDamages>10.00</liquidatedDamages> <duePerDeliverable>90.00</duePerDeliverable> </store> </stores> </fns_OrderConfirm>

3. CALL ORDER CONFIRMATION DATA (XSD)

The following is the XML Schema Definition (XSD) of the Call Order Confirmation data (orderConfirm.xsd).

<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:element name="fns_OrderConfirm"> <xs:complexType> <xs:sequence> <xs:element ref="callOrderType"/> <xs:element ref="workCenterCode"/> <xs:element ref="callOrderNumber"/> <xs:element ref="orderDate"/> <xs:element ref="dueDate"/> <xs:element ref="visitsOrdered"/> <xs:element ref="deliverablesReceived"/> <xs:element ref="completedStatus"/> <xs:element ref="pointOfContact"/> <xs:element ref="confirmedBy"/> <xs:element ref="emailAddress"/> <xs:element ref="stores"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="callOrderType" type="xs:string"/> <xs:element name="workCenterCode" type="xs:string"/> <xs:element name="callOrderNumber" type="xs:string"/> <xs:element name="orderDate" type="xs:date"/> <xs:element name="dueDate" type="xs:date"/> <xs:element name="visitsOrdered" type="xs:int"/> <xs:element name="deliverablesReceived" type="xs:int"/> <xs:element name="completedStatus" type="xs:string"/> < <xs:element name="confirmedBy" type="xs:string"/> <xs:element name="emailAddress" type="xs:string"/> <xs:element name="stores"> <xs:complexType> <xs:sequence> <xs:element maxOccurs="30" ref="store"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="store"> <xs:complexType> <xs:sequence> <xs:element ref="fnsNumber"/> <xs:element ref="storeName"/> <xs:element ref="chainStoreNumber"/>

May 12, 2015 14

<xs:element ref="county"/> <xs:element ref="receivedDate" minOccurs="0"/> <xs:element ref="acceptedDate" minOccurs="0"/> <xs:element ref="contractedVisitRate"/> <xs:element ref="liquidatedDamages"/> <xs:element ref="duePerDeliverable"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="fnsNumber" type="xs:string"/> <xs:element name="storeName" type="xs:string"/> <xs:element name="chainStoreNumber" type="xs:string"/> <xs:element name="county" type="xs:string"/> <xs:element name="receivedDate" type="xs:date"/> <xs:element name="acceptedDate" type="xs:date"/> <xs:element name="liquidatedDamages" type="xs:decimal"/> <xs:element name="contractedVisitRate" type="xs:decimal"/> <xs:element name="duePerDeliverable" type="xs:decimal"/> </xs:schema>

May 12, 2015 15

APPENDIX D: ERROR CODES

This appendix lists and describes the error codes that are expected in response to an error condition during the processing of the web service request at the target site. It is expected that the target web service return with the appropriate error code at the first detection of an error condition, multiple errors should not be processed and returned. More information on the error handling approach is described in Section 2.3.

Error Code Error Message Description

-100 Authentication failed. User name/password supplied are incorrect.

Web service returns this error due to a failure in the authentication of the credentials provided in the request.

-200 Content is not well formed or is invalid Web service returns this error upon receipt of XML data that does not conform to the specifications of the appropriate XSD.

-300 Invalid or missing Call Order information Web service returns this error when Call Order data is not valid. For example, the Field Office Code may not match a known office or the Call Order Type is not one of the valid options.

-400 Invalid or missing Store information Web service returns this error when the Store data is not valid. For example, the FNS Number is not unique within the Call Order.

Appendix D: Error Codes