Turn Issues Into Ideas
Note that while Centercode’s integration features are intended to be approachable by a Customer Validation Professional, you might need to enlist help from an internal technical resource and refer to our vocabulary and troubleshooting documentation .
Through the External Sources feature, Centercode can allow feedback from third-party sources to be added to your Centercode platform. External Source is designed to be flexible enough to receive data from a third-party system and map it into your feedback forms. Leveraging Webhooks from Centercode or third-party systems, data can be sent to your External Sources to essentially move feedback from one type to another. This enables the conversion of Bug Reports to Suggestions and vice-versa.
In this guide, you will:
- Create (or identify an existing) API Key in Centercode
- Configure an External Source to receive feedback in Centercode
- Create a POST Webhook Request to send feedback to be received by a different Feedback Type in Centercode
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)
1. Creating an API Key
From the Centercode side, 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 API endpoints are accessed and can be leveraged by multiple simultaneous API 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.
Preparing Centercode to Capture External Feedback
2. Configuring your External Feedback
External Feedback is located within your Feedback Type’s settings. To begin, you’ll need to navigate to the External Sources section of your desired Feedback type. Here, you’ll be configuring the data you want to be captured. We’ll start this example with Suggestions. Please repeat the below steps in as many Feedback Types as necessary.
From your Project homepage:
- Click Project Tools
- Click Feedback Types
- Hover over your desired Feedback Type (Suggestions) & click Modify
- Click External Sources
- Click Create an External Source
You’re now at the External Source creation screen to designate a way to receive external feedback to the specified feedback type. At this point, technical help may be necessary - please work with a developer (and/or Centercode).
From the External Sources creation page:
- Create an (internally-facing) Name
- Provide a simple Key to help identify this External Feedback Source (ex: “appcrashlog” - detailed below)
- Select the appropriate Workflow state for new feedback created via this source (typically “New”)
- Choosing No Selection here will mark the Status parameter as required - that field must be a supplied Parameter by the incoming data
- 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 incoming Parameters (detailed below)
- 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 Suggestions’ External Feedback Source!
- 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. This area is essential in lining up the upcoming Webhooks step, where you’ll be sending data to these Parameters
- Single Choice, Multiple Choice, and Rating Scale values passed to Centercode via parameter must match the selection options on the Feedback Form exactly.
- The Workflow section leverages the existing Workflow configured for your Feedback Type
- When External Feedback is created without an otherwise 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 Feedback should trigger existing Feedback Automation or Workflows (including External Destinations)
Preparing Centercode to Send Feedback Data
3. Creating Your Feedback Webhook Macro
Macros allow you to create a single instruction that includes a set of actions to complete a desired task. Webhooks send data from the original source, whether from a third-party app or within the Centercode platform itself, and the External Source converts it into the destination Feedback Type. In this example, we’re creating a Feedback Webhook Macro to send Bug Report data into Suggestions’ External Source.
From the Project Homepage:
- Click the Bug Reports
- 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, technical help may be necessary - please work with a developer (and/or Centercode)
- 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
The JSON Body field determines the data that will be sent from your Bug Reports to Suggestions. 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 it 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 (Click here), or on an automated schedule (Click here). In this example, we’ll stick with 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 other feedback type, you’ll want to review the Macro’s logs to troubleshoot issues. You’re offered with the individual Feedback tickets your Macro was applied and 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
Common Troubleshooting Scenario
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.