Electronic Data Exchange
Transmissions: Unattended Mode
October 26, 2011
Minnesota Department of Revenue
Tax Operations – Electronic Information
600 N Robert Street
Saint Paul, MN 55146-4130
Disclaimer
The information contained is deemed reliable and complete. Developers should not expect to receive any assistance from the Minnesota Department of Revenue, as the standards used do not reflect specific technology requirements. If developers find information that is inaccurate or incomplete, the department will consider revising this document to provide details of how the system responds to requests.
Version Control – Changes
Revision / Date / Author /Revision to exclude ‘Expect’ header parameter since it may result in Server 500 error / January 5, 2005 / Howard Dodd
Revision for EP integration into EDE / October 20, 2005 / Richard Sloss
Minor corrections (typos & grammar), added title page and disclaimer, and removed use case (UC03) references / October 21, 2005 / Bill Grewe
Corrected specification and example script to remove preceding hyphens when designating boundary (i.e., “boundary=--7d15037fc” changed to “boundary=7d15037fc”), and to use closing hyphens on final boundary marker. Corrected “--boundary marker” to reflect actual boundary maker choice,
“boundary_marker”, in specification. / November 7, 2005 / Bill Grewe
Added sample of data that will be returned by system. / November 8, 2005 / Bill Grewe
Updated host information and URLs in sample data to reflect activity directed at the certification region. Clarified that host is same for production and certification except for subdirectory (“/cm/” versus “/cc/”). / November 14, 2005 / Bill Grewe
Updated interface change information for the EZ application transmitters. / August 7, 2006 / Richard Sloss
Updated to provide specific interface parameters for tax year 2006. / November 29, 2006 / Bill Grewe
Updated example to reflect changes to interface parameters for tax year 2006. / December 11, 2006 / Bill Grewe
Revision to implement project change order and recreate the previous split between Certification (TEST) and Production (LIVE), which will eliminate the need to specify mode. Updates URL specification and samples. / December 13, 2006 / Bill Grewe
Revision to make split between Certification (TEST) and Production (LIVE) permanent. Eliminates alternate URLs. Removed revision history for 2004 from this record. / December 27, 2006 / Bill Grewe
Revision to correct example and remove references to mode. / February 15, 2007 / Bill Grewe
Added new file types for Department of Natural Resources. / March 15, 2007 / Bill Grewe
Corrected mistakes on pages 4 & 9 / January 15, 2008 / Justine Schindeldecker
Introduced “/unattended” context as a replacement for “/exchange”. Removed spaces from File Type Code for CompressedW2 and CompressedW2Test. / January 16, 2008 / Richard Sloss
S-Corp, Corp and Partnership filings will no longer be coming in through EDE. / October 5, 2009 / Nancy Rose
Withholding EDI returns and client updates will no longer be coming in through EDE. / October 5, 2009 / Nancy Rose
Withholding RTN, ZippedWithholdingRTN, WithholdingUPD and ZippedWithholdingUPD will be accepted. / October 5, 2009 / Nancy Rose
Fiduciary filings will no longer be submitted through Individual Type. Fiduciary filings should be submitted under the new Fiduciary Type. / October 5, 2009 / Nancy Rose
Added DPSLiquor files. / October 5, 2009 / Nancy Rose
Change ZippedWithholdingRTN to CompressedWithholdingRTN and ZippedWithholdingUPD to CompressedWithholdingUPD / November 9, 2009 / Nancy Rose
Added instructions for two new operations:
listAvailable ( returns trackingIDs of available files posted by the DOR for pickup by the ETIN )
downloadAvailable ( allows an available file, identified by the trackingId, to be downloaded to the transmitter’s machine ) / January 7, 2010 / Richard Sloss
Add Certification (test) document types: Homestead-Dup-test, Homestead-PTR-test, WithholdingRTN-test, CompressedWithholdingRTN-test,
WithholdingUPD-test, CompressedWithholdingUPD-test, Fiduciary-test, W2-test, CompressedW2-test / January 12, 2009 / Nancy Rose
Add Production document types: FIDMFilestoDOR , MNAnnualReportsRR, ApportionmentWorksheetsRR, AnnualSTBClass1ReportsRR, AirflightAnnualReports, MNAnnualReportsRRxls, Homestead-Dup, Homestead-PTR, HomesteadDupResponse, MunicipalBondReporting, GenTaxSLIRegistration and GenTaxSLITransactions / January 12, 2009 / Nancy Rose
Changed List Types: ECTransmission and EPTransmission to Individual-test and Individual / February 17, 2011 / Fakarudin Mohamed
Transmit return data using ‘Unattended Mode’
This information describes how a transmitter connects to the Electronic Data Exchange (Exchange) system web site directly in unattended (‘batch’) mode without the web user interface. It details how to perform the following system functions:
· File transmission upload
· List tracking IDs for waiting acknowledgement files
· Download acknowledgement files
· List files available to download from the DOR
· Download available file
Actors
· A transmitter registered with the DOR
· A business registered for eFILE Minnesota
Assumptions / Preconditions
· The user must have been registered as a transmitter with sufficient privileges to upload files, and download acknowledgements.
· These rights must exist for each type of transmission file for which the transmitter wishes to upload and receive acknowledgments.
· The DOR web service will provide file transfers over https – http will not be supported.
· The unattended mode interface does not support changing user passwords or retrieving history of transmissions.
Functions
These are the functions that will be supported by the Unattended Mode:
· Transmit return data
· Retrieve a list of all transmissions with acknowledgements not yet retrieved
· Retrieve acknowledgements for a specific transmission
· Retrieve a list of available files to download from the DOR
· Retrieve an available files ‘posted’ to the user from the DOR
Assumptions
· User has established a connection to the DOR via some ISP (Internet Service Provider)
· The user will make file transfer requests using some type of http client, including browsers. The DOR service will not have a preference or constraint for any client implementation.
· The user’s http client must be capable of accepting cookies, since the DOR security policy is transferred in a session-cookie.
· The request from the user’s http client contains an http request with the DOR required fields set (Refer to Http Request Configuration for details).
· The user may periodically be required to change their password according to DOR’s security policy. This is done through EDE’s web browser interface login-in screen (URL: https://www.mndor.state.mn.us/exchange-live). The user’s browser must be capable of accepting cookies, since the DOR security policy is transferred in a session cookie.
DOR Http Request Configuration
Method:
The Batch Transmission interface supports both HTTP POST and GET methods. However, uploading a transmission should be done through a POST using “multipart/encrypted encoding”.
Parameters:
The following are HTTP request parameter name-value pairs that must be passed as part of a specific transmission operation request:
Name / Possible values / Description /operation / upload; list; downloadAck; listAvailable; downloadAvailable / String identifying a supported function.
type / {transmission file type} / String value identifying the transmission type. See Appendix A for specific transmission type information.
trackingID / {etin}20060705123456 / The DOR provided trackingID tied to a previously sent transmission and related to electronic transmitter ID.
filename / {file upload data} / References the file to be uploaded.
Operation / parameter matrix:
operation / type / trackingID / filename /upload / X / X
list / X
downloadAck / X
listAvailable
downloadAvailable / X
Required Header Fields:
"Host" ":" host
Host is the server to which the URL connects.
Valid DOR host URL: / mndor.state.mn.us“Authorization: BASIC” credentials
Credentials is a string made up of the transmitter’s (DOR supplied) user_id and password encoded in base64. The base64 encoded string has the user_id and password arranged as user_id “:” password.
The transmitter will be expected to provide a valid user_id and password combination that is registered with MNDOR.
URI:
base_transfer_url – The base URI pointing to the batch controller application.
base_transfer_url / Certification (TEST) System:/unattended-test/transmissionController
Production (LIVE) System:
/unattended-live/transmissionController
concatenated_transfer_url – concatenated string forming the target URI for a GET made up of the base_transfer_url and name/value pairs required to request an operation. For more detailed information please see RFC 2616: http://www.ietf.org/rfc/rfc2616.txt.
concatenated_transfer_url / Certification (TEST) System:/unattended-test/transmissionController?operation=list&type=Individual-test
Production (LIVE) System:
/unattended-live/transmissionController?operation=list&type=Individual
Basic HTTP request structure:
POST {base_transfer_url} “HTTP/ 1.1”
[header-info]
[body] - includes parameters and data
GET {concatenated_transfer_url} “HTTP/ 1.1”
[header-info]
Uploading files:
“Content-Type: multipart/form-data; boundary=” boundary_marker
Boundary_marker is a string which must appear at the beginning of a line to indicate the start of the uploaded file contents.
The transmitter is free to select a boundary marker. Refer to the specification “Hypertext Transfer Protocol: http://www.ietf.org/rfc/rfc1945.txt?number=1945” for guidance on the acceptable characters, format and positioning of the field within the Http header.
A specific DOR example header containing the boundary marker field is provided.
The body of the http request must contain the following fields formatted according to the indicated structure.
--boundary_marker--
“Content-Disposition: form-data; name="filename"; filename=transmitter’s local data filename
“Content-Type: text/plain”
Tax return data starts here.
...
...
...
...
Sample tax return data ends here.
--boundary_marker--
General request header notes:
In order to reduce the possibility of receiving Server 500 errors in the DOR response, do not include the following header fields in the request:
“Expect: 100 Continue”
The inclusion of this header field in the client request is known to trigger Http server errors. Many client-side http libraries include this field on multi-part requests (such as the file upload). Those default inclusions should be disabled if possible. Please note that although the field triggers an http Server 500 error, currently the client request continues to be processed correctly. This behavior, generating an error while still processing the request, may change unpredictably based on the vendor implementation of http servers. The DOR makes no guarantee that a client response containing a Server 500 error has actually been processed.
DOR Response Configuration
All responses from the DOR service will contain the following parameters. Typically, a developer should check and interpret the httpStatus code. As much as possible the DOR has attempted to align the service response code to the W3C standard http response codes. Please refer to the following section that details the responses for a particular request.
“HttpStatus=” http response code
“HttpStatusCode” =http response code, descriptive text
“body=” response content
Main Flow: Uploading a file
The transmitter creates the http request according to the DOR Http Request Configuration.Example:
POST /unattended-test/transmissionController?operation=upload&type=Individual-test HTTP/ 1.1Host: mndor.state.mn.us
Authorization: BASIC MTIzNDpteXBhc3M=
Content-Type: multipart/form-data; boundary=7d15037fc
Content-Length: 629 {# of bytes in body}
--7d15037fc
Content-Disposition: form-data; name="filename"; filename="c:/testdata.txt"
Content-Type: text/plain
{data from c:\testdata.txt}
--7d15037fc
Content-Disposition: form-data; name="operation”
upload
--7d15037fc
Content-Disposition: form-data; name="type”
Individual-test
--7d15037fc--
DOR Service Responses:
There are two classes of response.1. The upload request was successful.
httpStatus=“200”
httpStatusCode=“OK”
http response body=tracking ID
Where “tracking ID” indicates the DOR tracking ID assigned to the uploaded file.
Sample response body:
user_id2005102115218402. The upload request was not successful.
httpStatus/httpStatusCode are set to one of :
“400” / “Bad Request”
“401” / “Unauthorized”
“503” / “Service Unavailable”
http response body is empty
Alternative Flow: Listing files with available acknowledgements
The transmitter creates the http request according to the DOR Http Request Configuration.Example:
GET /unattended-test/transmissionController?operation=list&type=Individual-test HTTP/ 1.1Host: mndor.state.mn.us
Authorization: BASIC MTIzNDpteXBhc3M=
DOR Service Responses:
There are two classes of response.1. The list request was successful.
httpStatus=“200”
httpStatusCode=“OK”
http response body=list of tracking IDs
Where “list of tracking IDs” is a line separated list of DOR tracking IDs that have acknowledgements waiting for a particular transmission type.
*** Please note that it is possible to get an empty list.
Sample response body:
user_id200510211521840’\n’user_id200510211521841’\n’
user_id200510211521842’\n’
user_id200510211521843’\n’
user_id200510211521844’\n’
Sample empty response body:
’\n’Empty result
2. The list request was not successful.
httpStatus/httpStatusCode are set to one of :
“400” / “Bad Request”
“401” / “Unauthorized”
“503” / “Service Unavailable”
http response body is empty
Alternative Flow: Retrieving the acknowledgement for a file
The transmitter creates the http request according to the DOR Http Request Configuration.Example:
GET /unattended-test/transmissionController?operation=downloadAck&trackingID=trackingID HTTP/ 1.1Host: mndor.state.mn.us
Authorization: BASIC MTIzNDpteXBhc3M=
DOR Service Responses:
There are two classes of response.1. The downloadAck request was successful.
httpStatus=“200”
httpStatusCode=“OK”
http response body=acknowledgement for transmission
Where “acknowledgement for transmission” is a transmission-type specific formatted document that contains the acknowledgement content.
*** Please note that it is possible to get an unprocessed response.
Sample response body:
0120****TRANA 999999999SOME SOFTWARE DEVELOPER SOMEWHERE Preparer's AgentS20051108GREWE0031201AVGREWEB T #’\n’0120****TRANB 9999999991234 NEWBEE BLVD ST PAUL MN 55123 6515561234 #’\n’
0120****AMN M1400001002GREWE00312010001000000001228A C2005110800GREWEB00013500 200412 MN#’\n’
0120****AMN M1400001004GREWE00312010002000000000805A C2005110800GREWEB00010500 200412 MN#’\n’
0120****AMN M1400001011GREWE00312010003000000002292A D2005110800GREWEB14001500 200412 MN#’\n’
0120****AMN M1400001012GREWE00312010004000000001350R D2005110800GREWEB14002501 200412 MN#’\n’
Sample unprocessed response body:
user_id200510211521840 has not completed processing yet2. The downloadAck request was not successful.
httpStatus/httpStatusCode are set to one of:
“400” / “Bad Request”
“401” / “Unauthorized”
“503” / “Service Unavailable”
http response body is empty
Alternative Flow: Listing available files from the DOR
The transmitter creates the http request according to the DOR Http Request Configuration.Example:
GET /unattended-test/transmissionController?operation=listAvailable HTTP/ 1.1Host: mndor.state.mn.us
Authorization: BASIC MTIzNDpteXBhc3M=
DOR Service Responses:
There are two classes of response.1. The listAvailable request was successful.
httpStatus=“200”
httpStatusCode=“OK”
http response body=list of tracking IDs
Where “list of tracking IDs” is a line separated list of DOR tracking IDs which represent files from the DOR which are available to the transmitter for download (see downloadAvailable).
*** Please note that it is possible to get an empty list.
Sample response body:
dor_200510211521840’\n’dor_200510211521841’\n’
dor_200510211521842’\n’
dor_200510211521843’\n’
dor_200510211521844’\n’
Sample empty response body:
’\n’Empty result
2. The listAvailable request was not successful.
httpStatus/httpStatusCode are set to one of :
“400” / “Bad Request”
“401” / “Unauthorized”
“503” / “Service Unavailable”
http response body is empty
Alternative Flow: Retrieving an available file from the DOR
The transmitter creates the http request according to the DOR Http Request Configuration.Example:
GET /unattended-test/transmissionController?operation=downloadAvailabletrackingID=trackingID HTTP/ 1.1Host: mndor.state.mn.us
Authorization: BASIC MTIzNDpteXBhc3M=
DOR Service Responses:
There are two classes of response.1. The downloadAvailable request was successful.
httpStatus=“200”
httpStatusCode=“OK”
http response body=content of file
Where the content of the available file is returned for storage on the client system.
*** Please note that it is possible to get a ‘Bad Request’ response if the file is no longer available.
Sample response body: