Configure and trigger Centercode emails to create tickets in Jira / issue tracking systems
This article applies to Team and Legacy editions.
This article covers Centercode's legacy integration tool to allow Centercode to send emails and basic POST requires to an internal system outside Centercode. This serves as an alternative to Centercode's first-class Jira integration tool, which requires basic authentication through the web to your Jira instance. Jira's documentation for this function can be found here.
This tool heavily leverages Centercode's Dynamic Tag functionality. Dynamic Tags are used to represent information that can vary each time an External Destination is executed.
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 system’s 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 publicly available.
And finally, you may also want to have:
- A firm understanding of Centercode Feedback Types, as well as an understanding of Feedback Workflow may also be necessary because Feedback Workflow is used to trigger an External Destination.
Note: A Centercode user account having Project Manager Access is required; Feedback External Destination is a feature available to all Centercode Enterprise and Standard Edition customers.
Feedback Type Overview
Feedback Types are used to collect many distinct types of information from end users, most commonly Issues and Ideas. For the purposes of this document, we will follow the case of Issues, 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. This option is used as an alternative to Centercode's first-class Jira integration.
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 (alternative to the first-class Jira Integration)
From Feedback Management tool within your Project:
- Hover over your desired Feedback Type (typically Issues)
- Click the Modify pencil
- Click External Destinations
- Click either HTML Email or Text Email
- Complete the required fields to configure the email template that Centercode will send to the inbox of your system. It's recommended to include Dynamic Tags in the subject and body of your email.
- Title refers to the name of your integration only for identification purposes (does not impact your email)
- Recipient Email refers to the email addresses that will receive your emails
- Each address that you define here will receive their own individual email message, so these addresses will not be exposed to each other.
- From refers to the name that is sending your email
- From/Reply Email refers to the email address that's sending your email
- Subject refers to the subject line of your email - you may include Dynamic Tags
- Body refers to the structure of your email body - please include Dynamic Tags
Note: Some issue tracking systems use the “From Email Address” to identify a posting account.
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.
(Legacy) 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. This is a legacy integration feature that is still supported and available. If your Centercode license includes Enhanced Integrations, please find documentation here.
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