Requirements for Use

Use of the Feedback External Destination feature requires an expansive knowledge of the system(s) to which you are sending the Feedback data, as well as its applicable technologies. These technologies may include the inner workings of an HTML form, the capabilities of a systems’ Web Services or the E-mail capabilities of the receiving system or individual. An understanding of networking limitations or restrictions may also be necessary since many internal systems are not publically available.

A decent understanding of Connect Feedback Types, as well as a decent understanding of Feedback Workflow may also be necessary because Feedback Workflow is used to invoke an External Destination.

Feedback External Destination is a feature available to all Connect Enterprise and Standard Edition customers.

Note: A Connect user account having Project Manager Access is required.

Feedback Type Overview

Feedback Types are used to collect many distinct types of information from end users, most commonly Bug Reports and Feature Suggestions. For the purposes of this document we will follow the case of Bug Reports, but the same concepts can be applied to any type of Feedback.

Unlike any other form type found within Connect, Feedback has a unique customizable Workflow. With customized Workflow you can define ownership of Feedback as well as procedural rules for each step from submission to final closure. Any Feedback status can be configured to relay information about that bug to another system. The mechanism that is used to relay that information is called an “External Destination”.

External Destination Overview

An External Destination contains all of the information that Connect needs to know in order to communicate with an external system, including how to connect to that system, and what specific information should be sent to that system.

Connect is capable of communicating with external systems in one of two ways, by E-mail or by the use of an HTTP Post. Which External Destination Type you choose to use would depend on your external system's existing capabilities, as well as your individual use case requirements.

The E-mail External Destination Type is capable of sending a standard E-mail message in either Plain Text or HTML format. Connect can only send information outbound and can not receive a reply from the external system when E-mail External Destination is used.

The HTTP Post External Destination Type simulates the use of a typical Web Form or Web Service and can not only send information but can also receive a reply from the external source as well. This reply functionality comes in handy when, for example, you want to reference a Bug ID issued by the outside system within the Bug Form found within Connect. When this External Destination is initiated your Connect Implementation Server will connect directly to your external server’s web form or web service. The end user’s browser itself will remain connected to the Connect Implementation. This is important to note because often the systems to which Connect is instructed to Post are located on non-public servers. Since this connection is made from server to server any applicable Firewall rules that may be necessary would be crafted between your Connect Implementation server and your external system.

To get started, enter your Connect Project, navigate to Feedback Type Management and choose the Edit icon of the Feedback Type to which you would like to add the new External Destination. Next, choose the External Destination icon, and then choose “Create a New External Destination”. Next, you will be prompted to choose the External Destination Type, E-mail or HTTP Post.

Create a New E-mail External Destination

From the External Destination Type list select E-mail and then click the “Next” button.

Give the External Destination a “Title”. This title will be used to identify this External Destination later when applying to this Feedback Type Workflow.

Provide one or more “Send to E-mail” addresses. The address(s) that you define here are the E-mail addresses to which Connect will send the Bug information when this External Destination is invoked. Each address that you define here will receive their own individual E-mail message, so these addresses will not be exposed to each other.

Provide the E-mail’s “From Name” and “From/Reply E-mail”. The E-mail message that Connect sends will appear to be “From” this value. If the E-mail is “Replied” to, the reply will be sent to the E-mail address that is defined here.

Note: Some bug systems use the “From E-mail Address” to identify a posting user. Advanced Tip: You can use Dynamic Tags in both of these fields! You will need to ensure the use of a Dynamic Tag in each of these fields will yield a valid From Name and a valid E-mail Address or the E-mail will not be sent. Typically when this advanced ability is used it is to identify the original Connect- side Submitter as the Submitter in the external system.

Provide a “Subject” for this E-mail. The Subject can include Dynamic Tags (see E-mail Dynamic Tags section below).

Provide your E-mail “Body”. This Body can be structured in any way that you would like, and can include Dynamic Tags (see E-mail Dynamic Tags section below).

Note: By default the Body allows HTML, and the WYSIWYG editor is used. If your system expects the E-mail message to be sent in Plain Text then you will need to click the “Send as Text” checkbox found towards the bottom of the page.

E-mail Dynamic Tags

Dynamic Tags are used to represent information that can vary each time an External Destination is executed.

When sending HTML Formatted E-mail (see Settings and Advanced Options below) First, enter some text into the WYSIWYG “Body” field, for this example type “Bug ID: ” and then press enter. Next click the WYSIWYG Body just to the right of the text that you just entered… this is where we will insert the Dynamic Tag. Open the Dynamic Tags group and then select the “Data Set” named “Feedback Type”. Next select the “Item” named “ID” which can be found toward the bottom of the Item-List under the heading “Basic Information”. Click the button labeled “Insert at Cursor”.

When sending Plain Text Formatted E-mail (see Settings and Advanced Options below) First, enter some text into the “Body” field, for this example type “Bug ID: ” and then press enter. Next, open the Dynamic Tags group and then select the “Data Set” named “Feedback Type”. Next select the “Item” named “ID” which can be found toward the bottom of the Item-List under the heading “Basic Information”. Click the button labeled “Insert at Cursor”. You will notice some text has appeared under the “Tag Value:” heading. Select the entire text that appeared, right click and choose “Copy”. Select the location within your “Body” that you would like to place this Dynamic Tag, right click and select “Paste”. When this External Destination is executed the E-mail body will appear as “BugID: bug-123”, where bug-123 is the ID for the Connect Bug.

Settings and Advanced Options

When the “Include Files” checkbox is checked any files attached to your Feedback form will be included with your E-mail message as a file attachment.

Note: This will only include files up to 10 megabytes.

The “Send as Text” option will eliminate the WYSIWYG editor from this page and will replace it with a plain text box. This option will also change the defined format of the resulting E-mail message.

Some systems have a limit to the number of characters that can exist on any one ‘line’ within an E-mail message. If your system has this limitation then choose the “Wrap Dynamic Fields” option, then specify the maximum number of characters that can exist on one line of text in the “Character Wrap Value” field.

Performance Note: This option should only be used if your system has this limitation, and should be set to a value within a few characters of your system’s limit. The lower this value the more work the E-mail sender will have to perform to process your message.

Create a New HTTP Post External Destination

Note: This External Destination Type can often be used with technical interfaces such as POST, REST and SOAP Web Services.

Technical Note: This interface does not currently support dynamic ‘GET’ parameters or dynamic URL components.

From the External Destination Type list select HTTP Post and then click the “Next” button.

Give the External Destination a “Title”. This title will be used to identify this External Destination later when applying to this Feedback Type Workflow.

If your system requires a “Network Credential” type of login then select the “Use Login” option and provide the necessary “Username” and “Password”.

Technical Note: This login will not work with “Forms Based” or custom authentication types. Systems requiring such authentication will need to employ an alternate means of identifying user context.

Define the URL to which Connect will Post when this External Destination is invoked.

Technical Note: When interfacing with a HTML form note that the URL of the page that displays the form is not always the same URL that receives the form data. Check the <form action= tag to identify the correct URL.

Technical Note: When interfacing with a Web Service specify the URL for the specific Web Method, along with any URL Parameters that may be necessary here.

Post Header

Interfacing with a HTML Form

When interfacing with a HTML form use the “Post Header” field to create a technical representation of your form.  The format of a HTML Post Header is Name=Value, and each name/value pair is separated by an ampersand (&).  If you enter non-dynamic values you will need to ensure the value is properly URLEncoded.  For example if you were to have a form that has three fields named “Title” (textbox), “User” (textbox) and “Create” (submit button), and your values for those three fields would be “Connect Feedback Type: Title”, “Static User ‘Joe_Smith’” and “Static Value ‘submit’” your post header would appear as “Title=<dynamic_tag>&User=Joe%5FSmith&submit=submit”.

Interfacing with a Web Service

If your Web service accepts HTTP Post formatted requests then the use case is very similar to the case described in the “Interfacing with a HTML Form” section.

It is possible to create a REST or SOAP formatted POST header, but there are some limitations to consider:

• A “content-type” header with the value of “application/x-www-form-urlencoded” is always included.
• All Dynamic Values are URLEncoded as well so your system will need to be capable of understanding this format.
• It will be necessary to understand the technical structure of the POST Header that your system is willing to accept.  The Post Header field that is provided on this page is sent exactly as you enter it with the exception of Dynamic Tags being replaced with their respective values and those values being URLEncoded.
• The only HTTP method that is currently supported is POST… this system currently does not support GET, PUT or DELETE requests, and the “Post URL” to which the request is sent does not accept Dynamic Tags.

Tip: You can assign multiple dynamic tags to the same item within your post header.  For example: …&description=<dynamic_tag>%20<dynamic_tag>…

Data Return

It is possible to “parse” information from the return text that the external system sends after successfully accepting the Post.  This can be particularly useful when you want to return a reference number or identifier from your other system to make it easier to cross-reference Feedback later.  There is no limit to the number of distinct values that you can return.  Once a value is isolated from the return you can add the value to a field on your Connect Feedback form.

Tip: You can configure your Feedback Type so that this value can not be edited or entered by a Connect user.  When creating the Form Element that the data will be returned to assign “View” access to the appropriate teams, but do not assign “Modify” access at all.

To add a new Data Return, select the “Add New Dynamic Data Return” link.  Give the return a “Title” (used in the list of defined Data Return configurations).  Next, provide a Regular Expression that will isolate the data from the Response Text that the external system sends back (see Regular Expressions below).  Choose the Feedback Form Element that the isolated value will be returned to.  If necessary, provide a “Default Value” for use when your Regular Expression does not match a value within the Response Text.

Regular Expressions

A Regular Expression is a pattern that will be used to identify a specific value of text that may exist within a larger block of text.  These patterns can range from very simple to extremely complex, and can be very powerful.  The first consideration when creating a Regular Expression is weather or not the value that you are trying to isolate has any unique features surrounding it.  For example, it will be very difficult to parse the phrase “unique characteristics” from the following paragraph by identifying the HTML bold (pattern: “<b>?+.</b>”) tags alone because other parts of the paragraph also include matches to this pattern:

The primary consideration for <b>anyone</b> attempting to build a Regular Expression pattern is to determine <b>unique characteristics</b> of the specific data that they are attempting to identify.

It may be necessary to add identifiable characteristics to your Response Text in order to make it possible to isolate the exact value that you need to return.  When parsing HTML Response Text you can parse values that are not necessarily visible to a user that is viewing the web page within their browser.  A common approach is to ‘embed’ HTML Comments that include the information that you are attempting to parse, including the necessary easily identifiable characters.

Refer to the following site for an extensive Regular Expression reference and tutorial.

http://www.regular-expressions.info/tutorial.html