Responding via TCP Connection
Requirements
Must be a MEMBER of DigAlert (or contracted with a member)
Must have a valid user account. User accounts are available by contacting the center PRIOR to any posting (live or test).
Connect to respapi.digalert.org via TCP/7377 (This URL is for PRODUCTION use only. All responses submitted to this URL will show on real active tickets and deliver to excavators
In the dialog below the ← (left arrow) means it comes from the server and the → (right arrow) means it is sent to the server
Multiple 'DATA' statements can be sent in a single logon session. However, a reply must be received BEFORE the next one is sent.
TESTING Automated EPR
For members needing to test Automated EPR via TCP Connection use the following URL
Connect to testresp.digalert.org via TCP/7377 (this URL is for TESTING purposes only. All responses submitted to this URL will NOT show on tickets or deliver to excavators
To verify the response was successful, first log into testresp.digalert.org via a web browser. Click https://newtint.digalert.org/newtinweb/gen_resp_inquiry_usas.nas , enter the ticket number and click Submit.
Components of the DATA command
REQUIRED commands
DATA Ticket,MemberCode,Respondent,ResponseCode
Optional commands
DATA Ticket,MemberCode,Respondent,ResponseCode,URL,Comments
Components of the DATA command
(These arguments are separated by commas. Space characters on either side of the comma are discarded)
Ticket | The complete ticket number EXCLUDING the revision (A121231234) |
MemberCode | The member code posting the response |
Respondent | The person's name or initials of who is entering the response. A minimum of three (3) characters are required. If the person only has two initials, send a space between them to fulfill the 3 character requirement. |
ResponseCode | The three digit code indicating the response of the locate request. These codes can be found → Electronic Positive Response Codes |
URL | This is an optional argument used to attached a link to the member's web site with additional information for this ticket. It has a maximum length of 255 characters and must be properly encoded according to RFC 3986 |
Comments | This is an optional argument used to add additional comments to store with the response. This has a maximum length of 255 characters |
After the socket is connected, normally a 220 reply will be seen. However, there can also be one of the following which will cause the server to immediately disconnect.
421 Service not availabe |
421 Error: <MachineName> Newtin delivery system too busy |
421 Error: <MachineName> Too many connections from same IP Address. |
If no valid response is entered within 45 seconds of logging in, or submitting a previous valid response, the connection will be disconnected after receiving;
522 Session expired |
Sequence of transmission
← 220 Response system ready
→ USER MemberCode
← 331 User name okay, need password
→ PASS password
← 230 User logged in, proceed
OR
← 530 Not logged in
→ DATA (Ticket,MemberCode,Respondent,ResponseCode)
OR
→ DATA (Ticket,MemberCode,Respondent,ResponseCode,URL,Comment)
NOTE
If you wish to send any optional fields, you must send all.
Example:
DATA A121231234,MBR,ME,010,,COMMENT
DATA A121231234,MBR,ME,010,URL,
DATA A121231234,MBR,ME,010,URL,COMMENT
Possible results:
← OK
← 251 Duplicate response (same response code that was already sent)
← 252 Ticket has been cancelled
← 450 Insufficient information
← 451 Invalid ticket
← 452 Ticket has expired
← 453 Invalid member code
← 453 Cannot respond for a contract locator
← 453 Cannot respond for an excluded member
← 454 Member not on ticket
← 454 Member not allowed for current login
← 455 Invalid response code
← 455 Invalid response code for ticket category
← 456 Invalid explanation code
← 457 Respondent name under 3 bytes (use "F L" if no middle initial)
← 457 Malformed URL
← 457 URL is too long
→ QUIT
← 221 Thank you for your response
NOTE
Replies beginning with 25x indicate the response was received.
Replies beginning with 45x indicates invalid data was sent.
Replies beginning with 5xx indicate an error and should try again later.
A reply code in the 450 to 459 range usually requires corrective action before attempting to resend the information. The single exception is the 451 response for an invalid ticket. Because the tickets are taken on more than one server, there may be latency or a temporary internet connectivity error in transferring the data between the server where the ticket was created and the server where the response is being posted. These responses should be resubmitted after a delay of a few minutes.
Important!
The application should not blindly resend responses that fail to be accepted. Any response that has been repeatedly rejected should be manually checked. Any response that has not been accepted for more than 7 days since it was entered should have its status cleared so that the application no longer tries to submit it.