Arkansas Medicaid Enterprise
WebBBS File Transfer System
Vendor Interface Specifications
WebBBS File Transfer System – Vendor Interface Specifications
Change history
Rev # / Date / Author / Section / Nature of Change /1.3 / 04/05/10 / Mike Morgan / All web service sections, 1.3, add appendix E / Added new section for DeleteFile Soap message, added XML nodes to all response layouts for days since last password change, and documentation for FTP over SSL supported commands.
1.4 / 05/03/10 / Mike Morgan / 1.3, 1.4, Appendix E and F / Sect 1.3 split into two sections; 1.3 (FTP over SSL) and 1.4 (FTP over SSH); prev. 1.4 Security Standards and Practices sec. is now sec. 1.5; added appendix E and F; added documentation of Base64encoding to uploading and downloading sections for NCPD files.
1.5 / 05/25/10 / Mike Morgan / All / Grammatical corrections for final review.
1.6 / 09/06/12 / Mike Morgan / Interface Standards, CORE web service specifications / Redesigned and added CORE documentation.
1.7 / 9/4/13 / Mike Morgan / FTPS (FTP over SSL) specification / Removed specifications for FTPS (FTP over SSL) protocol. This function is no longer supported.
1.8 / 9/18/2017 / Mike Morgan / All / Remove PES service specifications, Update website and core service URLs.
1.9 / 9/28/2017 / Bruce Dunn / Appendix A / Removed Appendix A – Supported FTP commands, as Arkansas Medicaid no longer supports FTP.
Preface
This document is intended for software vendors who wish to develop applications that interact with WebBBS, Arkansas Medicaid’s file delivery and retrieval system. It was created and is maintained by DXC Technology for the purpose of uploading and downloading HIPAA-compliant transactions.
Table of contents
1 Interface Standards 1
1.1 Web interface 1
1.1.1 Secure website 1
1.1.2 Secure CORE compliant web service 2
2 SFTP interface 3
3 CORE Web Services 4
3.1 HTTP/S envelope standards 4
3.2 Functionality at a glance 4
3.3 Production vs. model environments 5
3.4 Realtime vs. batch processing mode 5
3.5 Connecting to the Server 6
3.6 RealTime Processing 6
3.6.1 RealTimeRequestMessage 6
3.6.2 Sample XML and XML schema 8
3.6.3 RealTimeResponseMessage 10
3.6.4 Sample XML and XML schema 11
3.7 Batch processing 14
3.7.1 BatchSubmissionMessage 14
3.7.2 Sample XML and XML schema 16
3.7.3 BatchSubmissionResponseMessage 19
3.7.4 Sample XML and XML schema 20
3.7.5 BatchResultsRetrievalMessage 23
3.7.6 Sample XML and XML schema 24
3.7.7 BatchResultsRetrievalResponseMessage 27
3.7.8 Sample XML and XML schema 28
3.7.9 BatchSubmissionAckRetrievalMessage 31
3.7.10 Sample XML and XML schema 33
3.7.11 BatchSubmissionAckRetrievalResponseMessage 36
3.7.12 Sample XML and XML schema 37
4 Error Handling 41
4.1 HTTP level status 41
4.1.1 CORE envelope status/error codes and descriptions 42
5 Reserved 43
6 SFTP (FTP over SSH) Specification 44
6.1.1 Uploading files 44
6.1.2 Directory listing 44
6.1.3 Downloading files 44
7 Security Standards and Practices 45
7.1 Password creation requirements 45
7.2 New WebBBS client passwords 45
7.3 Password aging 45
7.3.1 Website password change procedures 45
7.3.2 Web service password change procedures 45
8 Appendix A: CORE Service Types 47
8.1 Processing Modes 47
8.2 RealTime Payload Types 47
8.3 Batch Payload Types 47
9 Appendix B: CORE sample programs 49
List of figures
Figure 1: Sample SOAP 1.2 RealTimeRequestMessage 8
Figure 2: Sample MIME Multi-part form data RealTimeRequestMessage 9
Figure 3: Sample SOAP RealTimeResponseMessage 11
Figure 4: Sample MIME Multi-part form data RealTimeResponseMessage 13
Figure 5: Sample SOAP 1.2 MTOM BatchSubmissionMessage 16
Figure 6: Sample MIME Multi-part form data BatchSubmissionMessage 18
Figure 7: Sample SOAP 1.2 MTOM BatchSubmissionResponseMessage 20
Figure 8: Sample MIME Multi-part form data BatchSubmissionResponseMessage 22
Figure 9: Sample SOAP 1.2 MTOM BatchResultsRetrievalMessage 24
Figure 10: Sample MIME Multi-part form data BatchResultsRetrievalRequest 26
Figure 11: Sample SOAP 1.2 MTOM BatchResultsRetrievalMessage 28
Figure 12: Sample MIME Multi-part form data BatchResultsRetrievalMessage 30
Figure 13: Sample SOAP 1.2 MTOM BatchSubmissionAckRetrievalRequestMessage 33
Figure 14: Sample MIME Multi-part form data BatchSubmissionAckRetrievalRequestMessage 34
Figure 15: Sample SOAP 1.2 MTOM BatchSubmissionAckRetrievalResponseMessage 37
Figure 16: Sample MIME Multi-part form data RealTimeResponseMessage 39
List of tables
Table 1: SOAP+WSDL web methods 5
Table 2: COREEnvelopeRealTimeRequest description 7
Table 3: COREEnvelopeRealTimeResponse description 10
Table 4: COREEnvelopeBatchSubmission description 14
Table 5: COREEnvelopeBatchSubmissionResponse description 19
Table 6: COREEnvelopeBatchResultsRetrieval description 23
Table 7: COREEnvelopeBatchResultsRetrievalResponse description 27
Table 8: COREEnvelopeBatchSubmissionAckRetrievalRequest description 31
Table 9: COREEnvelopeBatchSubmissionAckRetrievalResponse description 36
Table 10: WebBBS supports the following FTP commands for the purposes of integrity checking: 46
Table 11: WebBBS supports the following FTP command for the purpose of changing a password: 46
9/28/17 Page vi
© Copyright 2017 DXC Technology
WebBBS File Transfer System – Vendor Interface Specifications
1 Interface Standards
Arkansas Medicaid’s WebBBS interfaces support two of the most commonly used channels of communication, HTTP/S (web) and SFTP, giving clients a variety of interfaces to develop robust interchange solutions.
1.1 Web interface
The web interface is comprised of three independent HTTP/S application interfaces; two legacy applications that support only batch ASC X12 transactions; and a new CORE compliant interface capable of accepting both real-time and batch transactions. A diagram of the interaction flow is below.
1.1.1 Secure website
Arkansas Medicaid’s secure website is located at https://fts.mmis.arkansas.gov . The website is a batch-only interface integrated with file transfer wizards that allows users to upload and download files to and from the batch file repository. Once logged in, users can upload batch files to the secure server for processing. To upload batch files, navigate to the upload folder, and launch the upload/download wizard. To retrieve batch response files, navigate to the download folder, and click the download link next to each file displayed. Complete user interface documentation can be found by clicking on the “Online Manual” link found in the menu on the left of the home screen. A screenshot of the website is provided below.
NOTE: Batch ASC X12 files must be uploaded one at a time. Users cannot use the zip option within the upload/download wizard.
1.1.2 Secure CORE compliant web service
Arkansas Medicaid’s CORE compliant web interface is designed around CORE ACA 1104 Phase I and II rules, found at http://www.caqh.org/pdf/CLEAN5010/PIv5010Complete.pdf and http://www.caqh.org/pdf/CLEAN5010/PIIv5010Complete.pdf, respectively. This service is capable of accepting two different HTTP/S transport envelope specifications: HTTP MIME-Multipart Form Data and SOAP+WSDL. Along with batch capability, this service performs 270 and 276 real-time transactions. All data is transmitted using the Secure Socket Layer (SSL), which encrypts data over the network. Complete documentation can be found in the “CORE Web Service Specifications” section.
2 SFTP interface
The SFTP interface supports batch file uploads and downloads only. Users may use SFTP (SSH) clients such Filezilla, Putty, and WS_FTP Pro to transfer files or develop software that will logon and transfer files programmatically using SSH protocol. Complete specifications can be found in the “SFTP Specifications” section of this document.
3 CORE Web Services
Arkansas Medicaid’s CORE compliant web services are built around ACA 1104 Phase I and II rules which can be found at https://www.caqh.org/pdf/CLEAN5010/PIv5010Complete.pdf and https://www.caqh.org/pdf/CLEAN5010/PIIv5010Complete.pdf. These services also include:
· Acceptance of all Arkansas Medicaid approved batch transactions, including NCPDP D.0 and AR census (ARCN)
· Retrieval of NCPDP D.0 and Arkansas Medicaid specific ARCN supplemental reject results
The WSDL for the SOAP+WSDL service can be obtained from CORE at https://www.caqh.org/SOAP/WSDL/CORERule2.2.0.wsdl. Data contracts can be found at https://www.caqh.org/SOAP/WSDL/CORERule2.2.0.xsd. Security policies, application endpoints, and Arkansas Medicaid-specific method definitions can be found on the DXC Technology server at https://fts.mmis.arkansas.gov:9443/soap/COREservice.svc?wsdl.
3.1 HTTP/S envelope standards
Arkansas Medicaid’s CORE compliant web services are capable of accepting all Arkansas-approved transactions from the following two HTTP/S envelope standards: MIME-Multipart form data and SOAP+WSDL. Each envelope should conform to the CORE requirements listed below:
MIME-Multipart Form Data (IETF RFC 2388)
• HTTP/S version 1.1
• MIME version 1.0
• CORE envelope version 2.2.0
SOAP+WSDL
· HTTP/S version 1.1
· SOAP version 1.2
· WSDL version 1.1
· Web Service-Security 1.1
· CORE envelope version 2.2.0
3.2 Functionality at a glance
HTTP/S supports a request-response message pattern, meaning that the sender must submit a message and wait for a response from the recipient. This usage pattern applies to batch and real-time ASC X12 transactions. The response message varies based on whether the sender’s message was a real-time request, batch submission, or batch response retrieval request.
A list of the service functions can be seen below in Table 16. HTTP MIME-Multipart form data requests use the specified SOAP+WSDL methods. The functionality and CORE data envelope is inferred from the combination of processing mode and payload type. Request/response messages are described later in this guide.
Table 1: SOAP+WSDL web methods
Web Method / CORE / SupportedBatchSubmitTransaction / Yes / Yes
BatchSubmitAckRetrievalTransaction / Yes / Yes
BatchResultsRetrievalTransaction / Yes / Yes
BatchResultsAckSubmitTransaction / Yes / Yes
RealTimeTransaction / Yes / Yes
GenericBatchSubmissionTransaction / Yes / No
GenericBatchRetrievalTransaction / Yes / No
GenericBatchReceiptConfirmationTransaction / Yes / No
3.3 Production vs. model environments
There are 2 separate endpoints for production and test, which system you submit transactions to will determine how the will be processed.
WSDL can be obtained from the following URLs
· PROD: https://fts.mmis.arkansas.gov:9443/soap/coreservice.svc?wsdl
· TEST: https://fts-test.mmis.arkansas.gov:9443/soap/coreservice.svc?wsdl
When submitting transactions the endpoints are as follows
· PROD-BATCH : https://fts.mmis.arkansas.gov:9443/soap/coreservice.svc/batch
· PROD-REALTIME: https://fts.mmis.arkansas.gov:9443/soap/coreservice.svc/realtime
· TEST-BATCH: https://fts-test.mmis.arkansas.gov:9443/soap/coreservice.svc/batch
· TEST-REALTIME: https://fts-test.mmis.arkansas.gov:9443/soap/coreservice.svc/realtime
NOTE: From this point forward all connections will be in terms of production connection.
3.4 Realtime vs. batch processing mode
RealTime requests should contain only a single inquiry, i.e., only one eligibility inquiry per single information source for a single patient. RealTime responses for the receipt of an ASC X12 270 or 276 will be returned within 20 seconds. The response will be an error response or the corresponding ASC X12 response (e.g., ASC X12 v5010 TA1, v5010 999, or v5010 271, if the request submitted was a v5010 270). All RealTime ASC X12 transaction data submitted or returned via SOAP 1.2 messaging standards should be sent in-line (within the SOAP message XML) as plain text wrapped within an XML CDATA tag. When using MIME Multi-part form data, the transaction data should be sent in-line (within the form content) as plain text; however, it should not be wrapped within an XML CDATA tag. Batch requests can be sent in the same format as RealTime requests but are not limited to single inquiries.
Responses to batch requests will differ due to ASC X12 acknowledgment and transactional response time. An HTTP/S response message containing a CORE data envelope that indicates whether the request was accepted for processing or rejected will be returned within 60 seconds. Currently, Arkansas Medicaid only supports negative batch acknowledgements (a 999 or TA1 response). These responses will be available for download within one (1) hour of the submission of an ASC X12 270 or 276 batch transaction. An ASC X12 transactional response for the receipt of a batch v5010 270 or v5010 276 request submitted before 9:00 pm Eastern Time on any business day will be available for download no later than 7:00 am Eastern Time the following business day (seven (7) days a week, where a business day consists of a 24 hour period commencing at 12:00 am (Midnight or 00:00 hours) through 11:59 pm (23:59 hours) of the same day). Although not mandated by CORE operating rules, Arkansas Medicaid will have ASC X12 acknowledgements (if any to report) and transactional ASC X12 responses for other approved ASC X12 batch transactions (837I, 837P, 837D) available for download within the same time frame.
All batch transactions sent and returned via SOAP 1.2 messaging should incorporate the transmission optimization mechanism, MTOM. MTOM is the reorganization of a SOAP 1.2 message into a MIME-Multipart SOAP message which allows the attachment of large payloads of data. ASC X12 data should be sent as an MTOM MIME attachment comprised of a base64 encoded byte array. MTOM standards can be found at http://www.w3.org/TR/soap12-mtom/. When MIME Multi-part form data messaging is used, the payload should be transmitted in-line (within the form data content) as plain text.
3.5 Connecting to the Server
Users can connect to the web service using a network connection that provides access to the public internet. The envelope standards used determine the application endpoint URL that will be used to connect to and interact with Arkansas Medicaid’s CORE services. Each interface listed below uses TLS 1.1 and above.
Service requests using the MIME-multipart form data HTTP envelope should use https://fts.mmis.arkansas.gov:9443/mime/COREservice.aspx.
Service requests using SOAP 1.2 have a second determination for application end point. RealTime go to: https://fts.mmis.arkansas.gov:9443/soap/COREservice.svc/realtime, while batch requests go to https://fts.mmis.arkansas.gov:9443/Soap/COREservice.svc/batch.
3.6 RealTime Processing
RealTime transactions may use either HTTP/S envelope standard covered in the previous sections. When using SOAP 1.2 messaging, the web method (seen in the “Functionality at Glance” section) will determine the appropriate CORE data envelope. However, when using MIME Multipart form data, the CORE data and intended functionality are inferred using the combination of processing mode and payload type. All RealTime transactions must have a processing mode of RealTime and one of the acceptable RealTime payload types covered in Appendix B. An HTTP/S response containing a RealTime CORE data envelope with an appropriate payload transactional response and an error code or description of envelope processing will be returned within 20 seconds. Consult the “Error Handling” section for more information regarding error situations. Descriptions of the RealTime CORE request and response data envelopes are listed in Tables 17 and 18.
3.6.1 RealTimeRequestMessage
RealTime transactions with the server should use a RealTimeRequestMessage comprised of an HTTP/S envelope and the COREEnvelopeRealTimeRequest envelope as listed in Table 17. Only one ASC X12 envelope (ISA\IEA) containing a single inquiry may be submitted at a time and the total length in bytes of the entire message, including the HTTP/S envelope, must not exceed one (1) megabyte. If the message size exceeds this maximum, the entire request will be rejected. See Appendix B for a sample program.