J.1.4 RGMS Vendor Service Interface 19 0408 (1).pdf

Attachment J.1.4 Residential Generators Management System

Remote Service Call with Supported Vendors v1.07 4-08-2019

Introduction (general overview of the service): The Vendor communication service is a method by which the RGMS system can communicate with the Vendor’s (generator manufacturers) information systems in regards to generator information, manufacturing and delivery status on awarded task orders.

This communications link will allow the RGMS system located on the State Department’s local network to update its internal database which in turn will allow the software to show the status of each generator in the procurement cycle from award date to arrival at the defined despatch location. This service is expected to run once a day in order to update all open task order information requirements.

There will be a single reference key used for each generator being procured. This key will be supplied in the contract award letter.

Service Flow (describes the flow of information back and forth):

Initial Handshake Request is made by RGMS to Remote Vendor System (SystemID, Callback function, and Procurement Number Supplied)

The communication begins with an initial call from the RGMS system to the vendors supplied web address over the internet (https). In this initial contact, RGMS will supply in the request a unique key and the procurement number to the service address supplied by the Vendor. The Vendor’s service will then return a simple acknowledgement receipt of the data (see appendix for example). If the RGMS does not receive the expected acknowledgment in return it will assume an error has occurred and a second attempt will be made the next day. This unique key will be supplied in the task order award letter.

Re-occurring Requests (Callback Function and SystemID Supplied)

Daily, RGMS will connect to each vendors service address requesting the status data for current task orders that are in process. Several calls could be made to a single vendor depending on how many individual generator procurements are active. Each generator will have its own unique key thus resulting in a single call per generator. See Requested Data below and the appendix for the needed data.

Once the data being returned specifies all the data elements are complete the RGMS system will stop sending daily information requests.

Requested Data

This data will be returned from the Vendor for each request initiated by RGMS (except for the handshake). All unknown data needs to be supplied as "na". See example of a JSONP document in appendix 1.

Data Field JSONP Label Type FKey Association/lookup Example System_ID SystemId Numeric 1234567 Manufacturer Manufacturer Numeric (2) 1 = Cummins/Onan

2 = Olympian(Cat) 3 = other

Manufacturer Location ManufacturerLocation Numeric (2) 1 = United States 2 = Europe

Remote Service Call with Supported Vendors v1.07 4-08-2019

3 = Other Model Number ModelNumber Varchar (50) 196T Serial Number SerialNumber Varchar (50) 1234ABC Fuel Type FuelType Numeric 1 = gas

2 = diesel

Rating (in KVA) Rating Numeric 50 Transfer Switch Number TransferSwitchNumber Varchar (50) OCAT4321_A Expected Ship Date ExpectedShipDate Datetime 3/14/2015 Expected Arrival Date ExpectedArrivalDate Datetime 3/28/2015 Ship To Destination ShipToDestination Numeric 1 = Hagerstown

2 = Miami 3 = Belgium 4 = Other

Test Results Complete TestResultsComplete Numeric 1 = not run 2 = run/passed 3 = run/failed

Test Results Date TestResultsDate Datetime 3/10/2015

Technical Considerations

All communication is initiated by RGMS from the State LAN.

A SystemID is sent in the request call from RGMS each time a data request is made

The SystemID is used in communication as an added layer of security – only the RGMS system and the Vendor will know this key. The SystemID will be unique to a single generator and will be supplied to the manufacturer in the contract award letter.

The Procurement Order Number will also be supplied in the initial handshake from RGMS and will be in the request.

The initial handshake communication returned data (JSONP) document is different as it is only used as an acknowledgement that the Vendor’s service recognizes the request and the supplied key.

The path to the vendor’s service (http/https address) will need to be supplied to the State Department RGMS contact prior to receiving any communication.

Values unknown at need to be stated as "na" (example "ExpectedArrivalDate":"na")

Because any data could be "na", all fields will be sent as text as seen in the examples.

JSONP returned data labels are case sensitive, including the call back function names (example handshakeCallBack).

Callback functions (statusCallBack, handshakeCallBack) must be included in the return JSONP file (see examples).

Dates will need to be in this forward slashed "\"escaped format (example "mm\/dd\/yyyy").

Remote Service Call with Supported Vendors v1.07 4-08-2019

Appendices

A. Sample of INITIAL HANDSHAKE call made by RGMS (three parameters sent):

https://Vendors.address.com/service/service.svc?key=1234567&procurementnumber= PCN123456& callback=handshakeCallBack

B. Sample HANDSHAKE returned data from Vendor (in JSONP format):

handshakeCallBack({"SystemId":"1234567", "ProcurementNumber": "PCN123456","Accepted”:1} );

C. Sample of STATUS call made by RGMS (two parameters sent):

https://Vendors.address.com/service/service.svc?key=1234567&callback=statusCallBack

D. Sample returned data from a STATUS Call (above) early in process (in JSONP format):

Unknown data is specified as “na”.

statusCallBack({"SystemId":"1234567", "Manufacturer":"2", “ManufacturerLocation”:

"1","ModelNumber":"196T", "SerialNumber":"na", "FuelType":"2", "Rating":"50", "TransferSwitchNumber":

"na", "ExpectedShipDate":"na", "ExpectedArrivalDate":"na", "ShipToDestination":"na", "TestResultsComplete": "1", "TestResultsDate": "na" } );

F. Sample returned data from Vendor when all data is COMPLETE (in JSONP format):

statusCallBack({"SystemId":"1234567","Manufacturer":"2", "ManufacturerLocation": "1","ModelNumber":

"196T", "SerialNumber": "1234ABC", "FuelType": "2", "Rating": "50", "TransferSwitchNumber":

"OCAT4321_A", "ExpectedShipDate": "3\/14\/2015", "ExpectedArrivalDate": "3\/2\/2015", "ShipToDestination": "1", "TestResultsComplete": "2", "TestResultsDate": "3\/10\/2015" } );