Email Integration: Sending Emails to codebeamer

Email Integration allows you to send emails to codeBeamer. See the documentation about Notifications for information about emails you can receive from codeBeamer.

Please note that messages sent via MAPI/RPC are not supported.

Replying to codebeamer Notification Mails

Example:

1. John adds a comment to an issue in codeBeamer
2. codeBeamer sends a notification to all subscribers to the issue. Mary happens to be one of the subscribers
3. Mary receives a notification email from codeBeamer and replies to it
4. codeBeamer receives Mary's reply, adds it as comment to the issue and sends notification to all interested, including John
5. ... the collaboration can continue...

Depending on your subscriptions codeBeamer can send you a notification about changes in tracker issues, WikiPages, Forum posts or documents. See Notifications for details.

Once the Main Inbox has been configured, every subscriber will receive notification emails from the codeBeamer Main Inbox:

• The name of the user who made the change is in the From field of the change-related email
• The Reply-To field in the email will always contain the email address of the Main Inbox.

codeBeamer sends notifications on behalf of the author of changes. It allows you to organize your inbox e.g. with inbox assistant.

So if you receive an email about a Wiki page change or a tracker issue change simply reply to the incoming email, add your comments and send back to the provided "reply-to" mail address. These replies will be periodically read from email-accounts and if appropriate added to the Wiki or TrackerItems.

Take care - your reply will go to the codeBeamer's Main Inbox, not directly to the person shown in From field!

In special cases, when security guidelines of your mail provider do not allow sending emails on behalf of persons from different domains, you can configure codeBeamer in such a way that all emails are sent from the same address. The actual author's name is still shown as the name of the sender in the email, but the From field of the email is set to the one defined in codeBeamer's configuration.

Sending Mail to Trackers or Forums

If set up accordingly (see below), you can send emails to a codeBeamer tracker or forum, and codeBeamer will create a new tracker item/forum post according to the email's sender, subject, content and attachments.
You can find the email address for a tracker/forum (if any) in the title bar of a tracker or forum.

Configuration

• Create an email account for codeBeamer
• Configure codeBeamer MainInbox to read reply emails
• Create additional email accounts and associated inboxes for any trackers and forums you want to sent mails to
• Associate the additional inboxes with their target trackers and forums
• Mail Clients Configuration

Creating Email Accounts (POP3 or IMAP)

Consult your email provider (e.g. Gmail) about access data.

The accounts should be used by codeBeamer only. These accounts should not be used by any user, because codeBeamer will read and delete emails from there!

Configuring codebeamer to Read Emails

Switch to My Start | System Admin module, and click on the Email Inboxes and Polling link. You need to have codeBeamer System Administrator privileges to see the System Admin tab.

Define how often the inboxes should be polled by codeBeamer.

Main Inbox

Replies to codeBeamer emails are received in the Main Inbox. When the Main Inbox is configured, codeBeamer will be able to receive replies to emails sent by codeBeamer.

To configure it click on the Main Inbox tab, which shows the information about the Main Inbox. If the Main Inbox tab is not visible, click on the Create Main Inbox link, which moves you to the inbox configuration screen.

There you will need to configure the inbox's access parameters, most importantly:

• Email address: the valid email address of the Main Inbox. This email address will be automatically used as "reply-to" address in codeBeamer emails once the Main Inbox is set up.
• Account and Password: The log-in username and password if your mail server requires one.
• Server: the IP address or the host name of the POP3/IMAP mail server.
• Protocol: choose between the supported POP3 or IMAP protocols.
• Port: codeBeamer uses default port numbers

After entering all the details, use the Test Connection button to test if codeBeamer can connect to the email account, and if it's successful, save the configuration.

Configuring Trackers and Forums to Read From Inboxes

Besides the Main Inbox - which is used for handling email replies-, other email accounts can be used to send email (non-reply) directly to trackers or forums.




These Email Inboxes should first be configured in the same Email Inboxes and Polling page (in the System Admin tab) by clicking the name of the Inbox configuration, also you can Add new inbox configuration by clicking New Email Inbox.

After such an inbox is configured, go to the customization page of the target tracker or forum, and assign the inbox to the tracker/forum.




The tracker will then show the email address, that can be used to submit new tracker items via email.




Emails sent to tracker email addresses will create new tracker items with the following mapping:

Any email attachments will also be attached to the generated tracker item, along with the email itself (email.eml).

You can specify additional tracker item attributes via ${attribute : value [, ...] } in the email subject.

This may be necessary, if the target tracker has mandatory attributes.

For example: To send codebeamer bug reports via email to bugs@codebeamer.com, you must specify at least the version/release where the bug was detected:

   From: You
     To: bugs@codebeamer.com
Subject: Sending emails to trackers fails ${Detected: 5.7.0; Priority: High; Severity: Critical}

Bug description here

You can define multiple attribute values in a single ${ } block, by separating them with semicolon ";".
You can assign multiple values to an attribute by separating them by commas ",".
You can have any number of ${ } blocks in the email subject, but preferably at the begin and/or end.
You can separate attribute and value(s) by ":" or "=".

Attributes can be identified by any of the following:

• The Property name (to see Property names, check Show property names checkbox in Tracker configuration page Fields tab)
  e.g. priority, severities, assignedTo, startDate, endDate, estimatedHours, choiceList[0]
• The field Label
  e.g. Priority, Severity, Assigned to, Start Date, End Date, Planned Hours, Detected Version
• The field Title (if any)
  e.g. Detected
• The localized field Label and/or Title according to the Language configured in the codebeamer account of the email sender.
  e.g. for german language: Priorität, Auswirkung, Bearbeiter, Beginn, Ende, Gepl. Aufwand (h), Betroffene Version
• Any abbreviation of the (localized) Label and/or Title, as long as it uniquely identifies an attribute
  e.g. Prio, Start, End, Planned, Detected would be valid, but Assigned would be invalid because ambigous (Assigned to or Assigned at ?)

The format of attribute values depends on the Typeof the attibute (see screenshot above):

• Text is plain text, and must not contain commas, semicolons or curly braces.
  This restriction does not apply to the Summary, because the item summary is filled from the email subject.
• Integer and Decimal values are pure numeric with an optional sign. The Decimal point is "." , e.g. ${Planned Hours: 4.5}
• Boolean values can only be true or false
• Date values are specified as YYYY-MM-DD [hh:mm], the time-of-day part (24h) is optional.
  You can also use the localized date format configured in the codebeamer account of the email sender.
  e.g. ${End: 2011-07-30 20:00} or, if sender had a german account: ${Ende: 30.07.2011 20:00}
• Member values must identify project members and/or (if multiplefield values are allowed) project roles.
  • You can identify a user/memberby any of the following:
    • The interwiki link of the user, e.g. ${Assigned to: PTC Support}
    • The codebeamer user name, e.g. ${Assigned to: support}
    • The email address of the user (as defined in the codebeamer user account), e.g. ${Assigned to: support@intland.com}
  • You can identify a project roleby
    • The internal role name, e.g. Project Admin, Developer, Stakeholder
    • The localized role name according to the Language configured in the codebeamer account of the email sender.
      e.g. for german language: Projektleiter, Entwickler, Beteiligte
• Choice values can be either values from a static Choice listor items from a referenced tracker/category.
  • Static Choice list values (e.g. priority, severities) can be identified by
    • The choice option Id, e.g. ${Priority: 1} (where 1 is Highest priority and 5 is Lowest priority)
    • The choice option Name, e.g. ${Severity: Blocker}
    • The localized choice option Name according to the Language configured in the codebeamer account of the email sender.
      e.g. for german language: ${Priorität: Hoch; Auswirkung: Kritisch}
  • Dynamic reference values (e.g. Detected/Target Versioncan be identified by
    • The interwiki link of the referenced codebeamer object, e.g. ${Target Version: You must login to see this link. Register now, if you have no user account yet.}
    • The object Name, e.g. ${Detected: 5.7.0}

As a rule of thumb, simply specify additional attributes exactly as you see them on the appropriate CodeBeamer screen.
If you would report a New Bug via the codeBeamer GUI like this:




The same bug report via email could look like this :



Note:

• You specify the Tracker via it's email address in To.
• You will always receive a reply email
  • that either contains a link to the newly created tracker item,
  • or, in case of failure, describes the reason, why no tracker item could be created.

Mail Clients Configuration

You can configure your mail client to set a reply's format and to define whether the original message is included into the reply.

Outlook 2002/2003/2007: Recommendation: use Plain-Text formatting and configure Outlook to start quoted lines with ">".

If HTML formatting is used, lots of generated html code will appear in the replies. This may make the reply content difficult to read, and it may look different from other parts of the page (e.g. the tracker issue's comments).

To configure quoted lines to start with ">" go to the Tools menu and select Settings. Under the first tab (Preferences) choose the Email options button. In the next dialog select Prefix each line of the original message and in the edit box below set Prefix each line with: with ">" (using > without quotes!).

• ThunderBird 2.0: the default settings don't have to be changed since the default reply format is handled well by Email Integration in both HTML and plain-text formats.

Alternatively, you can:

• turn off including the original message
• when replying remove all unwanted content (such as the original message)

Formatting Replies

Replies to codeBeamer can be sent in two formats: Plain-Text or HTML format. Also email-clients can send the emails in both formats. In this case they will send the same content in both Plain-Text and HTML combined in one email. If the email arrives in both formats the Plain-Text is preferred and used and the HTML format is ignored (configurable).

For information on changing the format of the received email notifications, please see Customizing Notification Emails

Plain-Text Replies

Plain-Text replies can contain Wiki formatting which will be added as Wiki comments to tracker issues. When parsing Plain-Text replies the lines starting with ">" are automatically removed as they are considered quoted lines from the original message.

HTML Replies

HTML formatted replies are added as HTML format, and if they contain Wiki formatting it is ignored. During the processing of HTML email the codeBeamer inbox manager code tries to identify the quoted message of the original. If successful it will throw out all quoted parts of the original message. In case this parsing should fail the incoming message is inserted as sent.

Also when sending HTML formatted emails it is highly recommended that you only add your content before or after the original message. Mixing lines of the original message and comments will probably result in the new modifications being lost!

ThunderBird is recommended as a mail service. Outlook is not recommended, since different Outlook versions produce varying HTML content because of their Word based HTML editors.

Attachments

Attachments are handled as binary data, their file names are preserved, and they are added as attachments to the tracker issue or Forum Post. Emails may contain any number of attachments, however please keep in mind that the POP3/IMAP email account may not handle large amounts of data. Typically they don't allow more than a few megabytes of attachments.