External Source integration use case: Converting Feedback Between Types Using External Sources
The External Sources integration allows for Projects within your Centercode implementation to receive data from outside systems to create actionable feedback tickets. Leveraging Webhooks from Centercode or outside systems, data can be sent to your External Source API endpoint to essentially move feedback from one feedback type to another. This enables the conversion of Issues to Ideas!
Note that while Centercode’s integration features are intended to be approachable by Project Managers, you may require help from an internal technical resource who understands webhook functionality and how to format JSON.
Can Centercode complete this setup on my behalf?
If you’d like the direct assistance with your configuration, you can submit a Centercode Success Service and an Integrations & API Consultant will work directly with you to create, test, and troubleshoot your integration. However, standard in-site chat support can also walk you through this setup using the below instructions.
How do I use this integration?
You must have Enhanced Integrations as part of your Centercode license in order to utilize Centercode’s suite of integration tools. If you’re unsure if you do, you can check your Community Tools to see if you have the API Keys tool available (#2 above). If you find that you don’t have Enhanced Integrations, you can reach out to your Centercode Success Manager to discuss this add-on. Centercode Support can also help direct you to the appropriate resources.
You must also create your External Sources configuration to generate your API endpoint to allow for outside systems to send HTTP Post requests to Centercode to create feedback tickets.
Once you’ve confirmed the above, follow the instructions below. Section 4, “Converting Feedback Between Types”, is where you’ll fire off the integration at-will to convert Issues into Ideas.
In this guide, you will:
- Create (or identify an existing) API Key at the Community level
- Configure an External Source to receive feedback in Ideas Feedback Type
- Create a POST Webhook Macro in your Issues Feedback Type to send tickets to your Ideas’ External Source API endpoint
In order to configure both sides of this integration, you will need:
- Access to an existing API Key or Community Manager access to create a new one
- Project Manager access in the project of your choice (or your project template)
If you follow this guide to completion, this is what converting an Issue to an Idea will look like from the admin perspective:
In this example, the following has occurred:
- The ticket is checked out by the administrator (in order to gain modify rights)
- The macro "Send to Ideas" is triggered. This Macro is custom configured to do several things:
- Set the ticket's Status to Closed
- Set the Closure Reason to Incorrect Feedback Type
- Leave a comment by the Macro creator, thanking the user and mentioning to follow their ticket in the correct Feedback Type
- A new Idea ticket is created. The Issue populates the Idea's main description body text. A side-by-side example is then shown.
1. Creating an API Key
From your Centercode implementation, the first step in any API integration is to ensure that you have an API Key available within your Centercode Community. API Keys are used to track and control how your API endpoints are accessed and how they’re leveraged by multiple simultaneous integrations. If one is already created and available for use, you may continue past this step.
If necessary, create a Community API Key by following steps outlined here.
2. Configure your External Source
To begin, you’ll need to navigate to and create an External Sources configuration within your desired Feedback Type. In this example, we’ll use Ideas.
From your Project homepage:
- Click Management>Project Configuration>Feedback Types
- Hover over your desired Feedback Type (Issues) & click the modify pencil
- Click External Sources
- Click Create an External Source
You’re now at the External Sources creation screen. At this point, it’s important to understand the concept of key-value pairs in relation to JSON. Technical help may be necessary - please work with an internal technical resource or Centercode support.
From the External Sources creation page:
- Create an (internally-facing) Name
- Provide a simple Key to help identify this External Source (ex: “Convert Issues to Ideas” - detailed below)
- Select the appropriate Workflow state for new feedback created via this source (typically “New”)
These fields define the Team submitting feedback and the Status in which it comes in
- Select Default Submitter for new feedback from this source
- Leaving this field blank will mark the Submitter parameter as required, matching on email address - that field must be a supplied Parameter by the incoming data and must be an existing email address in your Project
- Configure your Incoming Fields, mapping the Centercode Field with their matching Parameters (detailed in notes)
- Select the appropriate API Key from the list (if more than one is available)
- Copy / Save your API Endpoint URL - you’ll need it later!
- Click Submit
You’ve just configured your Issue’s External Source!
Send files to feedback tickets (optional)
If your feedback form contains file attachment elements, then your External Source configuration will have an API endpoint for each. Also, once data is sent from your outside system to your External Sources API endpoint to create feedback tickets, Centercode will send back a return response automatically that includes the API endpoints for your file attachment elements (placeholder screenshot). Please note that the API endpoint from the return response will not include the required project key.
It’s required that your External Source’s File Element Parameters are configured and that your outside system is capable of sending form-data HTTP Post requests containing files.
- Your Key can be a short, descriptive entry to separate this integration from other functions that use the same Community API key for easier use
- Incoming Fields map Parameters defined in your third-party system to the Centercode feedback form. Below is an example of incoming JSON data. Here you can see it matching these fields exactly.
- The Workflow section leverages the existing Workflow configured for your Feedback Type
- Selecting “No Selection” here will mark the Status parameter as required - that field must be a supplied Parameter by the incoming data. This means that your system is providing the custom status field of the incoming feedback. The Status your system is providing must be one existing in your Centercode feedback form.
- Single Choice, Multiple Choice, and Rating Scale values passed to Centercode via parameter must match the associated selection on the Feedback Form exactly.
- When feedback tickets are created through the External Source integration without a matching Submitter, it is attributed to the Default Submitter, which is an existing user account of your choosing.
- Advanced Options allow you to decide if your External Source should trigger existing Feedback Automation or Workflows (including External Destinations)
- Files sent through the file upload API have a 2 GB per file limit
- Please note that when sending a Post request to your Centercode API endpoint, the JSON body must be JSON encoded.
3. Creating Your Feedback Webhook Macro
In this example, we’re creating a Feedback Webhook Macro to send Issue data into Ideas’ External Source.
From the Project Homepage:
- Click Feedback, and select your desired feedback type
- If necessary, click the Switch to Advanced View button (top right corner)
- Click Feedback Resources
- Create a new Macro or modify an existing Macro
- Click Trigger Webhooks
At this point, it’s important to understand the concept of key-value pairs in relation to JSON and webhook usage. Technical help may be necessary - please work with an internal technical resource or Centercode support.
- Click Web Request to select POST
- Enter the Webhook URL provided by your External Source in Section 2, Step 7 above
- Add headers (discussed in Notes below), if needed
- Select JSON
- Add your JSON body (detailed below)
- Add Dynamic Tags
- Configure any additional desired automation (detailed in Notes below)
- Click Submit
The JSON Body
In the webhook of your Macro, the JSON body field determines which data from your Issues tickets to your Ideas. The fields on the left (e.g. “submitter” and “summary”) are the Parameters you’re matching to the External Source’s Parameters. The fields on the right are the values that will be mapped to every converted piece of feedback. The below example contains dynamic tags.
Additional Option Notes
- The Show in Feedback Management option will display the created Macro under the Actions on the Feedback Splash and List pages, and will give you the option to share the Macro with other Internal or Admin Teams for use in these locations.
- Run Once Per Feedback ensures that your Feedback Macro will only hit its target one time to protect you from redundancy, bloat, or macro spam.
- The Suppress Confirmation option will allow you to have the Macro trigger immediately when selected, without a confirmation page prompt. Use this option carefully and if you feel comfortable bypassing confirmation.
Headers for Authentication
Headers allow you to define additional static values sent with each request. Not all API calls require headers to be defined. A common use for headers is to provide authorization for your Webhook by adding your access key to your header and specify how you want returned values to be formatted. This scenario doesn’t require Headers.
Authorization Header Example:
Return value formatting example:
4. Converting Feedback Between Types
Like any Feedback Macro within Centercode, you can trigger your Feedback conversion Macro manually (individually or in bulk), as a Notice, or on an automated schedule. In this example, we’ll use a manual trigger. When viewing a piece of feedback, simply click your Macro on the left-hand menu.
5. Reviewing Your Webhook Results
If you find that when using your conversion Macro hasn’t created new feedback in your Ideas Feedback Type, you’ll want to review the Macro’s logs to troubleshoot issues. You can review your webhook Macros’ log to see your responses from sending the webhook Macro along with their individual Status Code results. Please see this article for Status Code definitions.
From Feedback Management:
- Click Feedback Resources
- Hover over your Macro and click Log
- Hover over Feedback ticket and click Log
What’s the structure of the API endpoints?
Every Centercode API endpoint is unique to your Centercode implementation. You have control over your project key, configuration names, and API key.
To create feedback tickets: https://<YourCentercodeURL>/api/v1/projects/<YourProjectKey>/feedback/<YourExternalSourcesConfigurationName>?apiKey=<YourAPIKey>
To add files to feedback tickets:
Common Troubleshooting Scenarios
The following return response indicates that your API endpoint is invalid. You’ll want to review the API endpoint your webhook Macro is sending to and ensure that it’s the correct API endpoint for your Ideas’ External Source. If you’ve changed any of the bolded keys in the above section, you must reference that change in your webhook Macro.
"description": "The requested resource could not be found."
The following indicates that the submitter user account is invalid, whether feedback is attempting to be submitted by an email address that doesn’t exist within the project or invalid submitter parameters are configured:
"description": "The feedback submission could not be saved.",
"description": "A valid submitter is required."
Please note that when sending a Post request to your Centercode API endpoint, the JSON body must be JSON encoded.