Attachement_BB_COTS_REST_Specification_.pdf

ATTACHMENT B OF

PERFORMANCE WORK STATEMENT

CALL ORDER TRACKING SYSTEM (COTS)

REST SPECIFICATION

SNAP STORE VISIT CONTRACT

USDA FNS Call Order Tracking System (COTS) REST Specification

Call Order Tracking System (COTS)

REST 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

USDA FNS Call Order Tracking System (COTS) REST Specification i

TABLE OF CONTENTS

1. WHAT ARE RESTFUL WEB SERVICES?

2. WEB SERVICE TO PROVIDE CALL ORDER DATES FROM THE

CONTRACTOR TO STARS

2.1 SVC-COTS Integration

2.2 Functionality Description

2.3 Infrastructure Guidelines

2.4 Web Application Description Language (WADL)

APPENDIX A: COTS WEB SERVICE WADL

APPENDIX B: SAMPLE EMAIL GENERATED BY COTS WEB SERVICE. 7

APPENDIX C: ERROR CODES

USDA FNS Call Order Tracking System (COTS) REST Specification

1. WHAT ARE RESTFUL WEB SERVICES?

Web services are a request/ response mechanism that allows a client to remotely access/ modify data. Even a simple web page is a “web service”.

Web services are designed to allow applications built using different technologies to communicate with each other without issues. Similar to how web pages allow people to communicate and collaborate with each other, Web services allow programs to communicate and collaborate with each other.

Two approaches for interfacing to the web with web services are SOAP (Simple Object Access Protocol) and REST (Representational State Transfer).

SOAP uses a complex mechanism exchange data between webservice and the application. SOAP is the approach used for transmitting data from STARS to the Contractor.

REST uses a simpler approach( HTTP Get Method) to exchange data between webservice and the application.

REST standard will be used to implement a proposed new web service between the Contractor and STARS, whereby the Contractor will transmit a set of dates for each deliverable: the date the deliverable is uploaded to FNS (to be used as Received Date by FNS) and the date of the store visit.

2. WEB SERVICE TO PROVIDE CALL ORDER DATES FROM THE

CONTRACTOR TO STARS

2.1 SVC-COTS INTEGRATION

Summary: Capture Deliverable dates – Received, Visit and Accepted as transmitted by SVC Contractor through web services.

Background: Currently the COTS deliverable dates are manually entered by STARS Users. When User enters the Received Date and Visit date, system auto populates the Accepted Date=Received date, and creates the contact record with type of contact=Contracted store visit and Purpose=Purpose as Call order with Contact Date=Visit date of call order.

Description: This CER requests to automate the COTS deliverable date entry as transmitted by SVC Contractor. SVC Contractor shall send both the valid (mmddyyyy) Received Date and Visit Date to STARS for each/many FNS numbers (Stores) for a given Call Order.

On STARS, when dates are populated, the current functionality of populating the Accepted Date=Received Date and Creating Contact record shall be automated for each of the FNS Numbers for a Call Order as noted in the back ground above. In addition the user information for contact record shall be “COTS User (unknown)” similar to OSA user.

Alternate Flows:

1. When the SVC Contractor transfers the Received and Visit Dates for a Call Order/FNS Number combination which already has dates populated in STARS, STARS shall not accept the dates.

2. If invalid dates are sent, system shall not accept the date and send an email notification to the STARS/the Contractor personnel (TBD) for the Call Order/FNS Number/s.

3. If an exception occurs during the transmittal, an email notification shall be send to both parties.

2.2 FUNCTIONALITY DESCRIPTION

STARS and SVC (the Contractor) exchange data through the STARS web services to capture deliverable dates. STARS is the provider of a new REST-based web service and the Contractor will be the consumer of this web service. The Contractor will transmit the date the deliverable was uploaded to FNS and the date of the store visit ) to a secured STARS web service. The STARS web service can handle a call order with one store or a call order with multiple stores/dates up to a maximum of 30 stores.

2.3 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 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

Provider STARS systems should be sufficiently redundant such that there is minimal downtime and disruption to the normal business operations due to system failure. The new web service exposed by STARS system will be available in Integ, UAT environment for testing.

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 for each web service request from the Contractor

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

The username and password shall be provided by the STARS, and shall adhere to the following requirements:

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

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 STARS shall send an email (configurable email addresses) to users to notify the status of web service transmission. The email will contain the list of FNS numbers and status message for each FNS number. In case of any system exception during the web service transmission, a separate email will be sent to the production support team (configurable email addresses) which includes the exception details. Sample email is listed under Appendix B.

2.4 WEB APPLICATION DESCRIPTION LANGUAGE (WADL)

The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web applications (typically REST web services). WADL models the resources provided by a service and the relationships between them. WADL is intended to simplify the reuse of web services that are based on the existing HTTP architecture of the Web. It is platform and language independent and aims to promote reuse of applications beyond the basic use in a web browser.

More about wadl can be found @ http://www.w3.org/Submission/wadl/

Definition of the STARS WSDL is included in Appendix A.

APPENDIX A: COTS WEB SERVICE WADL

This appendix provides the WADL defining the COTS web service (cotsws.wadl).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<application xmlns="http://wadl.dev.java.net/2009/02">

<doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.14 09/09/2012 05:39 PM"/>

<grammars>

<include href="application.wadl/xsd0.xsd">

<doc xml:lang="en" title="Generated"/>

</include>

</grammars>

<resources base="http://localhost:8080/cotswsservices/services/">

<resource path="/cotsws">

<method name="POST" id="transmitDatesPOST">

<request>

<representation mediaType="application/x-www-form-urlencoded">

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="authUsername"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="authPassword"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="callOrderNumber"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="fnsNumber"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="receivedDate"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="visitDate"/>

</representation>

</request> http://www.w3.org/Submission/wadl/

<response>

<ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02" xmlns="" mediaType="application/xml" element="cotsWebServiceResponse"/>

</response>

</method>

<method name="GET" id="transmitDatesGET">

<request>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="authUsername"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="authPassword"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="callOrderNumber"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="fnsNumber"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="receivedDate"/>

<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="visitDate"/>

</request>

<response>

<ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02" xmlns="" mediaType="application/xml" element="cotsWebServiceResponse"/>

</response>

</method>

<resource path="/getstatus">

<method name="GET" id="getStatus">

<response>

<representation mediaType="text/html"/>

</response>

</method>

</resource>

</resource>

</resources>

</application>

The parameters of the method calls are provided below:

Parameter Name Description

Parameter Name Description authUsername The user name for authenticating to the STARS web service authPassword The password for authenticating to the STARS web service callOrderNumber Single Call order number for which the Contractor will be transmitting the Deliverable Dates.

fnsNumber List of FNS Numbers of the stores for which Received and Visit Dates to be populated receivedDate List of Received dates to be populated (mmddyyyy format).

visitDate List of Visit dates to be populated (mmddyyyy format).

APPENDIX B: SAMPLE EMAIL GENERATED BY COTS WEB SERVICE.

Subject: COTS Deliverable Dates Notification for SW2-00072

Call Order SW2-00072 Deliverable Dates Transmission Results:

FNS Number: 1234567 Received Date: 03/21/2013 Visit Date: 03/21/2013 Message: ERROR: Deliverable Dates already exist for Call Order Store.

FNS Number: 1111111 Received Date: 03/22/2013 Visit Date: 03/22/2013 Message: ERROR: Deliverable Dates already exist for Call Order Store.

FNS Number: 2222222 Received Date: 03/15/2013 Visit Date: 03/15/2013 Message: Post Deliverable Dates successful.

APPENDIX C: 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.

Error Code

Error Message Description

401 Authentication failed. User name/password supplied the REST service url is incorrect.

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

500 Internal Server Error Web service returns this error if there is any unexpected/unknown system error.

0 Success code Web service returns this code when dates are successfully posted.

1 Warning Code Web service returns this error when Deliverable dates are already posted for Call Order Store.

2.1

No Call Order number provided or Call Order does not exist.

Data Violation Codes

Web service returns this error when the supplied data is invalid. The code “2” is just for internal reference and is never returned from STARS, it is an indication of Data Violation, instead the separate error codes are returned based on the violation.

2.2 No FNS Numbers provided.

2.3 No Received Dates provided.

2.4 No Visit Dates provided.

2.5

Each FNS Number should have corresponding Received/Visit Dates provided.

2.6 Invalid Data: FNS Number

2.7 Invalid Data: Received Date.

2.8

Invalid Data: Visit Date.

3.1 Call Order must be in Cover Letter Issued status.

Business Rule Violation Codes

Web service returns this error when there are any business rule violations, for ex: “Received/Visit date cannot be in future or past 90 days in the past”.

The code “3” is just for internal reference and is never returned from STARS, it is an indication of Business

3.2

Received Date must be within 90 days in past and cannot be in future.

3.3 Received Date must be after the Order Date.

3.4

Visit Date must be within 90 days in past and cannot be in future.

Error Code

Error Message Description

3.5 Visit Date must be on or after the Order Date. Rule Violation, instead the separate error codes are returned based on the violation.

3.6 Visit Date must be on or before the Received date

3.7 FNS Number does not belong to this Call Order.