This article concerns a technical Integration between Centercode and an internal system outside Centercode control. Assistance from your IT team may be required.

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 email 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 Centercode 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 Centercode Enterprise and Standard Edition customers.

Note: A Centercode 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 Centercode, 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 Centercode 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.

Centercode is capable of communicating with external systems in one of two ways, by email 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 Email External Destination Type is capable of sending a standard email message in either Plain Text or HTML format. Centercode can only send information outbound and can not receive a reply from the external system when Email 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 Centercode. When this External Destination is initiated your Centercode 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 Centercode Implementation. This is important to note because often the systems to which Centercode 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 Centercode Implementation server and your external system.

To get started, enter your Centercode 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, Email or HTTP Post.

Create a New Email External Destination

From the External Destination Type list select Email 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 email” addresses. The address(s) that you define here are the email addresses to which Centercode will send the Bug information when this External Destination is invoked. Each address that you define here will receive their own individual email message, so these addresses will not be exposed to each other.

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

Note: Some bug systems use the “From Email 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 Email Address or the email will not be sent. Typically when this advanced ability is used it is to identify the original Centercode-side Submitter as the Submitter in the external system.

Provide a “Subject” for this email. The Subject can include Dynamic Tags (see Email Dynamic Tags section below).

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

Note: By default the Body allows HTML, and the WYSIWYG editor is used. If your system expects the email 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.

Email Dynamic Tags

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

When sending HTML Formatted Email (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 Email (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 email body will appear as “BugID: bug-123”, where bug-123 is the ID for the Centercode Bug.

Settings and Advanced Options

When the “Include Files” checkbox is checked any files attached to your Feedback form will be included with your email 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 email message.

Some systems have a limit to the number of characters that can exist on any one ‘line’ within an email 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 email 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 Centercode 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 “Centercode 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 Centercode Feedback form.

Tip: You can configure your Feedback Type so that this value can not be edited or entered by a Centercode 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: “?+.”) tags alone because other parts of the paragraph also include matches to this pattern:

The primary consideration for anyone attempting to build a Regular Expression pattern is to determine unique characteristics 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

Did this answer your question?