Internal Errigal Collaboration Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Introduction to Dig Ticket Mailbox =====
Author: Eoin Joy\\ \\ 
The Dig Portal creates new Dig Tickets based on parsing emails from a mailbox that is setup as a recipient to a distribution list that receives hundreds of Dig Ticket Emails per day from Dig Centers across the US.
==== Dig Ticket Email Accounts ====
These Dig Ticket Email accounts are defined in the ''ticketer'' database's ''email_account'' table. These email accounts have the special ''dig_ticket_emails'' flag set to true and define a folder or label that contains the Dig Ticket Emails.\\
The production account is currently ''digportal@nextgnoc.net'' while the test account is ''fiberdig@errigal.com''.\\
**IMPORTANT: DO NOT enable a dig ticket email account without first ensuring it is not using the production mailbox**
=== Dig Ticket Emails ===
A Dig Ticket Email is received into this mailbox and has a particular format of information. Example Below:
<code>
From: irthnet@callsunshine.com via crowncastle.onmicrosoft.com
To: fiberdig.tickets@crowncastle.com
Subject: Seq# 30: 259604125 for NN1882

NN1882 07603 CALL SUNSHINE 09/15/16 10:40:03ET 259604125-000  GRID
Ticket : 259604125 Rev:000 Taken: 09/15/16 10:37ET

State: FL Cnty: ORANGE GeoPlace: ORLANDO
CallerPlace: ORLANDO
Subdivision:

Address : 2620
Street  : ORLANDO WEST DR
Cross 1 : SILVER STAR RD
Within 1/4 mile: Y

Locat: START LOCATE ON THE NORTH SIDE OF ADDRESS 2620 ORLANDO WEST DR GOING
NORTH FOR 25 FEET THEN RUNS EAST FOR 305 FEET TO THE RIGHT OF WAY OF ORLANDO
WEST DR
:
Remarks : *** LOOKUP BY MANUAL ***
:
Grids   : 2834B8126B   2834B8126C

Work date: 09/20/16 Time: 08:00ET  Hrs notc: 069 Category: 3 Duration: 24 HRS
Due Date : 09/19/16 Time: 23:59ET  Exp Date : 10/17/16 Time: 23:59ET
Work type: UNDERGROUND CONSTRUCTION  Boring: Y  White-lined: U
Ug/Oh/Both: U  Machinery: Y  Depth: UNKNOW  Permits: U  N/A
Done for : BRIGHT HOUSE

Company : ANGIES CONSTRUCTION SERVICES INC  Type: CONT
Co addr : PO BOX 518
City    : APOPKA State: FL Zip: 32714
Caller  : SHERRIE RYTELL Phone: 407-953-2460
Contact : ANTWAN COCHRAN Phone: 813-562-5667
BestTime: 8-5
Fax     : 321-972-6555
Email   : KNMAJM01@GMAIL.COM

Submitted: 09/15/16 10:37ET Oper: SHE Chan: WEB
Mbrs :  BH1956 COO600 FPLFEO L3C900 LS1104 NN1882 OC1332 OC1420 OCU596 OTC811
Mbrs :  OUC553 OUC582 PGSORL SBF02  TL2051 TSC364
This email may contain confidential or privileged material. Use or disclosure of it by anyone other than the recipient is unauthorized. If you are not an intended recipient, please delete this email.
</code>
==== Dig Ticket Call Centers ====
A Dig Ticket Call Center is a company that sends us Dig Ticket Emails. These companies generally (but not always) have jurisdiction over one State's Dig Tickets. The Primary visibility for a Dig Ticket Call Center and whatever Secondary visibilities they have should be assigned before Dig Ticket Emails are received.
=== Dig Ticket Call Center Email Addresses ===
Which Dig Ticket Call Center a particular Dig Ticket Email is linked to is determined by the Email Address it originated from. More than one email address can be assigned to a Dig Ticket Call Center.
==== Dig Ticket Email Parsing Rules ====
Parsing rules written in groovy are used to create Dig Tickets in the Dig Portal from the information provided in the Dig Ticket Emails. The particular rule that is run is determined by which Dig Ticket Call Center the Dig Ticket is for, which in turn is determined by the email address the Dig Ticket Email was received from.
=== CBYDEmailParsing project ===
There is a project [[https://bitbucket.org/errigal/cbydemailparsing/|on Bitbucket]] that can be used to perform some testing on new or updated email parsing rules.
=== Writing Email Parse Rules ===
The purpose of the Email Parsing Rules is to gather as much information as is possible from a Dig Ticket Email and return it as part of a DigTicketEmailGroovletResponse object. This object contains a ticket reference to a ticket you create using data from a ParsedDigTicketEmail object\\
The fields that can be filled in this ParsedDigTicketEmail object are as follows:\\
^ Name ^ Description ^
| digTicketEmailType | An Enum that represents what kind of email this is. Usually NORMAL or EMERGENCY, but there are other variations |
| ticketNumber | The Dig Ticket Identifier as given by the Dig Center |
| oldTicketNumber | The Dig Ticket Identifier of a previous ticket that is similar. Only useful in some markets |
| updateOfTicketNumber | The dig Ticket Identifier of the previous ticket that is being updated by this email |
| digStreet | The address of the dig site |
| crossStreet1 | The first crossing street. Used as extra information to further explain extent of work |
| crossStreet2 | The second crossing street. Used as extra information to further explain extent of work |
| county | The county location of the work. (Currently the customer has requested this value be populated with the City the work shall be done in) |
| state | The 2 character state that the work will be done in |
| zip | The zip code of the address of the work |
| latitude1 | The latitude of the first coordinate given in some dig ticket emails. When only one set is given this represents the point at which the work is centered |
| latitude2 | The latitude of the second coordinate given in some dig ticket emails. When two sets are given this represents the endpoint of a line |
| latitude3 | The latitude of the third coordinate given in some dig ticket emails. When two sets are given this is generated from those as the possible third corner of a rectangle |
| latitude3 | The latitude of the fourth coordinate given in some dig ticket emails. When two sets are given this is generated from those as the possible fourth corner of a rectangle |
| longitude1 | The longitude of the first coordinate given in some dig ticket emails. When only one set is given this represents the point at which the work is centered |
| longitude2 | The longitude of the second coordinate given in some dig ticket emails. When two sets are given this represents the endpoint of a line |
| longitude3 | The longitude of the third coordinate given in some dig ticket emails. When two sets are given this is generated from those as the possible third corner of a rectangle |
| longitude3 | The longitude of the fourth coordinate given in some dig ticket emails. When two sets are given this is generated from those as the possible fourth corner of a rectangle |
| workStartDateAndTime | The date and time at which the work will start |
| localizedWorkStartDate | The start date of the work |
| localizedWorkStartTime | The start time of the work |
| timeZone | The timezone of the work |
| contractorWorkType | The type of work to be performed |
| contractorCompany | The company performing the work |
| contractorPhone | The phone number of the contractor |
| contractorFax | The fax number of the contractor |
| contractorEmailAddress | The email Address of the contractor |
| comments | Any further comments in the email |
| fromCallCenterEmailAddress | The email address that this email came from |

To populate these values, you can parse the email body and email subject of the Dig Ticket Email using whatever string processing is necessary (regex or find and substring). The DigTicketEmailParsingUtils class is also passed into the binding for use in these parse rules.\\
Alongside the ParsedDigTicketEmail object, a few other pieces of information are needed to create the Ticket needed to return.

^ Name ^ Description ^
| workflowName | "Dig Ticket - Normal" or "Dig Ticket - Emergency" |
| status | "Dig Ticket Received" or "Dig Ticket Update Received" |
| creator | "auto" |
| summary | A string containing the name of the call center, the type of dig ticket email, and the dig ticket id |
| visibility | The market that the ticket should belong to |
| priority | default of 3 |
| emailBody | The body of the email you just parsed |

== Tips & Other information ==
  * Use regex ''<nowiki>\s+</nowiki>'' in place of literal whitespace where possible as these whitespace characters may for example display as one character and be encoded as two, or may not be always the same length of whitespace
  * A blank String "" is always preferable to return in an object as opposed to null. If you do not find something in the email, use the ternary operator ''?:'' to enable these blank string returns.
  * The CBYDEmailParsing project does not have exactly the same context as the Ticketer codebase. Always double check against a rule running in production for especially fully qualified objects and the dateLocalizer object
  * When testing, definitely test both Normal and Emergency/Rush tickets. Try to test for and account for as many variations on the emails as you can.
  * If you need to re-parse an email on production due to some error in parsing, you will need to move the first ticket to the archived tickets visibility, then alter the dig ticket id in the dig ticket form to be unique (perhaps append some string), and then set the email to be unread in the email inbox.

==== Assessment ====
  - How do you enable email parsing from a particular mailbox?
  - What determines which rule will be run for a particular email?
  - Write a parsing rule to parse the example email from this page.
Sidebar

Internal Errigal Collaboration Wiki

User Tools

Site Tools

Page Tools
