Depiction's Live reports capability allows you and your colleagues to add elements to your depiction via email. This provides a dynamic and collaborative way for people in multiple locations to make reports that populate one or more depictions.
To use Live reports you need to:
- Setup one or more email accounts to which to send emails
- Create a depiction that imports elements from those email account(s)
- Have people send emails to the email account(s)
You will need an email system that supports the POP3 method to access the emails. The following email systems are known to work with Depiction:
|Email system||"POP3 server"||"Use SSL"||Example format for
|Yahoo! Mail Plus||plus.pop.mail.yahoo.com||Noemail@example.com||The free version of Yahoo! email does not support POP3.|
|Hotmail||pop3.live.com||Yesfirstname.lastname@example.org||Free version of Hotmail only allows one login every 15 minutes.|
|Live.com||pop3.live.com||Yesemail@example.com||Live is basically Hotmail with a new name (one login every 15 min. free).|
|GMX||pop.gmx.com||Yesfirstname.lastname@example.org||GMX only allows one login at a time.|
|Internal mail server||mail.XXXX.com||No||myaccount||Replace "XXXX.com" with the appropriate address for your server (Microsoft Exchange or other type). See your network administrator for assistance in adding accounts or accessing them from Depiction.|
You may need the information in the POP3 Server Address and Use SSL fields when setting up the connection from Depiction to your email account, below.
Importing Elements from Email
To add elements via email, open Add Content and click on the Live reports button. The form looks like this:
Create or import by:
The left pane allows you to specify the connection for a specific email account. If your email provider is in the Email provider drop-down list, choose it. This list also shows any email accounts you have previously used for Live reports in Depiction.
If your new email address is one of the email providers from the list, simply enter your email account's name and its password.
Otherwise, you will need to enter the full address for the email account to read, such as email@example.com, the password for the email account, and the POP3 Server and Use SSL settings. You may choose one of the known POP3 servers, or type one in. See the above table for the settings of several popular email systems. You may use any system that supports the POP3 protocol.
as this element (by default):
The right pane allows you to select the default element definition to use for the elements created from the emails. If the email subject or body specifies an element definition, that definition will be used instead of the default choosen in Add Content.
A typical email that can be read by Depiction's Live reports could look like the following:
Subject: Plume: Gas Smell, 400 Pine Street, Seattle WA
Wind speed : 20
Wind direction : 225
Time : 1
Material Type : Natural Gas
When Depiction's Live reports Integrator reads the above email it will automatically create a Plume element and place it at the geographical location of 400 Pine Street, Seattle WA with a mouse-over display name of Gas Smell and with the four values for the four properties listed in the email's body: a wind speed of 20, a wind direction of 225, a time of 1 hour, and a material type of Natural gas. The element icon will pulsate to alert the user that a new Live report has been received. Any properties not specified in the body of the email will have the default value specified by the element type (e.g. Amount of Release of 100).
Following are the specifics of how to format an email that Depiction will understand.
Depiction expects the subject line to be like one of the following two examples:
The top example has three parts: element definition, name, location:
The first colon separates the element definition from the name.
The first comma separates the name from the location. By default, the name is displayed when the mouse hovers over the element. The name cannot contain a comma.
The location is everything after the first comma.
The element definition is optional. If missing, Depiction will use the default element type chosen when starting the Live reports connection to this email account.
If there is no location, or the location cannot be found, Depiction will put the new element in Manage Content under the need to geo-align tab, where you can view it by selecting the element and clicking on View/Edit.
The location may be specified in many ways. Common formats include:
|Type of location||Example|
|address||400 Pine Street, Seattle WA|
|latitude, longitude||47.61N, -122.33E|
|place name||The White House|
If the email's body includes a "location" property, it will be used if there is no location in the subject line.
Formatting an email's body
The body of the email may specify property values for the element to be created. The example email above specifies four property values. A colon (":") separates the property from its value. Each property and value is on a separate line.
When read, Depiction will assign that value to that property. If the property is not in the specified element definition, Depiction will add a new property with that value.
The units, such as "feet", for numeric values are those defined in the element definition.
Note that if the email's body has properties for latitude and longitude, these will be used to determine the element's location instead of the location information in the email's subject line.
The entire body of the email is included as the Email body property of each element created from a live report™.
What type of element will be created?
Every email will result in one element. The type of element created for an email depends upon the content of the email.
- If the subject line starts with the name of am element type followed by a colon (such as "Road barrier:"), Depiction will create an element of that type.
- Otherwise, if the email body includes a property named Element type, Depiction will use that property's value as the type.
- Otherwise, Depiction will create an element of the default type selected when you added the Live report connection from Add Content.
So, the choice is yours: you can use either the subject line; or an Element type property in the email's body.
Here's how to update the properties of an existing element via a Live reports email:
- Make sure the element you want to update has a property called "EID" (Element Identifier). This is a unique identifier for this element within your depiction. You can either include this EID property in the body of your original email used to create this element in Depiction, or add an EID property to your element after it comes into your depiction.
- To update this element via email, send a new email message to your Live reports email account and include in that email a line that specifies an EID property containing the same value. All depiction applications that are "scanning" that email account will update the element with that EID using the properties (and values) read from the email. The icon of the element being updated will pulsate to show that it has been updated with a Live report. (If Depiction does not find a matching element, it will create a new element for that email.)
For instance, the following email will create a vehicle at "400 Pine Street, Seattle WA":
Subject: Vehicle: Delivery van, 400 Pine Street, Seattle WA
EID: John Doe's truck
To update the location of this element, you could send the following email to the same Live report email address:
Subject: Disabled truck, 800 1st Ave, Seattle, WA
EID: John Doe's truck
This will move the vehicle element to the location of "800 1st Ave, Seattle, WA".
You also can move an element by specifying the new location via Latitude and Longitude properties in the email's body, such as:
Subject: Disabled truck
EID: John Doe's truck
Note: you cannot change an element's type (definition) via an update email.
Once started, Depiction reads every email from this email account. Depiction checks for new emails on a random time schedule designed for POP3 access.
Initially, Depiction reads every email in the account, and tries to create one element for each email.
If you do not want Depiction to read a particular email, use your email system to move or delete those emails out of the inbox.
Depiction allows you to send emails that communicate the element information content of one or more elements - one email per element. This is an efficient way to send updated information regarding an element to other Depiction users as each element email is sent in a format that Depiction's Live reports feature can interpret. All you have to do is send the element update to an email account that is being used as Live reports input by other depiction users. There are two ways to do this.
The first way is to open Manage Content and select the specific element(s) you wish to send via email. Then click the Send button. This will bring up a form where you need to fill in at least the first three fields:
- To - one or more email addresses (use commas to separate addresses), such as firstname.lastname@example.org
- From - a legitimate email address, such as email@example.com
- Outgoing email server - the name of your email server, such as mail.mycompany.com (ask your system administrator)
Needed only if your email server requires authentication (see a brief list of provider settings below):
- Use authentication - check this if your email server requires it (ask your system administrator)
- User name - for use during authentication, only (ask your system administrator)
- Password - for use during authentication, only (ask your system administrator)
The second way is by clicking on the Send button along the bottom of a Group Information or Element Information window:
Sending an email to update Depiction users on changes to an element's information (e.g. occupancy information for a shelter, as shown in the above example) is as easy as double clicking on the element's icon, editing the contents in the element's information window, and selecting Send.
- Hotmail Settings
- Hotmail Incoming Mail Server (POP3) - pop3.live.com (logon using Secure Password Authentification - SPA, mail server port: 995)
- Hotmail Outgoing Mail Server (SMTP) - smtp.live.com (SSL enabled, port 25)
- Yahoo! Mail Settings
- Yahoo Incoming Mail Server (POP3) - pop.mail.yahoo.com (port 110)
- Yahoo Outgoing Mail Server (SMTP) - smtp.mail.yahoo.com (port 25)
- Yahoo! Mail Plus email server settings
- Yahoo Plus Incoming Mail Server (POP3) - plus.pop.mail.yahoo.com (SSL enabled, port 995)
- Yahoo Plus Outgoing Mail Server (SMTP) - plus.smtp.mail.yahoo.com (SSL enabled, port 465, use authentication)
- Google GMail Settings
- Google Gmail Incoming Mail Server (POP3) - pop.gmail.com (SSL enabled, port 995)
- Outgoing Mail Server - smtp.gmail.com (SSL enabled, port 465)
- GMX Mail Settings
- GMX Incoming Mail Server (POP3) - pop.gmx.com
- GMX Outgoing Mail Server (SMTP) - mail.gmx.com (SSL enabled)
- MSN Mail Settings
- MSN Incoming Mail Server (POP3) - pop3.email.msn.com (port 110, using Secure Password Authentication - SPA)
- MSN Outgoing Mail Server - smtp.email.msn.com (select "My outgoing server requires authentication")
- Lycos Mail Settings
- Lycos Mail Incoming Mail Server (POP3) - pop.mail.lycos.com (port 110)
- Outgoing Mail Server - smtp.mail.lycos.com or use your local ISP SMTP mail server
- Netscape Internet Service Mail Settings
- Netscape Internet Service Incoming Mail Server (POP3) - pop.3.isp.netscape.com (port 110)
- Netscape Internet Service Outgoing Mail Server - smtp.isp.netscape.com (port 25, using a secure SSL connection)
- On occasion, Depiction won't be able to understand the format of an email's From field. This happens, for instance, if the email name includes spaces and is not properly quoted. In this case, the From property for that element will be given the value firstname.lastname@example.org.