External Source integration specific use case: Create Centercode feedback from your mobile app, cloud system, etc.
The External Sources integration allows for Projects within your Centercode implementation to receive data from outside systems to create actionable feedback tickets. This integration utilizes your existing Workflow settings to dictate how your feedback should be triaged. Incoming feedback can also be tied to current testers within your Project or you can select a default submitter, which allows for anonymizing feedback that isn’t associated with your current testers.
Note that while Centercode’s integration features are intended to be approachable by Project Managers, you’ll require the help from an internal technical resource with administrator access in your outside system. They must be able to control the outside system’s API integration tools, such as HTTP Post request configurations. Technical documentation can be found here.
Can Centercode help connect our outside system to our Centercode implementation?
If you’d like the direct assistance with your integration, you can submit a Centercode Success Service and an Integrations & API Consultant will work directly with you and your technical resource to create, test, and troubleshoot your integration.
How do I use the External Sources 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. 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.
In this guide, you will:
- Create (or identify an existing) API Key in Centercode
- Configure an External Source to receive feedback in Centercode
- Identify data to be captured from your third-party system and sent to 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)
- Knowledge of your third-party system or an internal technical resource for that system
1. Create 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
External Sources configuration 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 from your outside system. We’ll start this example with Issues.
From your Project homepage:
- Click Project Tools
- Click 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, technical help may be necessary - please work with an internal technical resource.
From the External Sources creation page:
- Create an (internally-facing) Name
- Provide a simple Key to help identify this External Source (ex: “appcrashlog” - 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.
Notes
- 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. Prepare your outside system to send data to your External Source API endpoint
After completing the above instructions, you’ll need to configure your outside system.
- Identify the data you want captured from your users.
- Configure your outside system to send HTTP Post webhooks containing JSON data (detailed below).
- Consider conditions and automation in which your HTTP Post webhooks will be sent from your outside system to your External Source API endpoint to generate feedback tickets.
Configuring your HTTP Post webhook and formatting JSON
Your outside system will send HTTP Post webhooks with JSON data to populate each individual piece of feedback created through the External Source integration. The screenshot below simulates an outside system via Postman, an API testing tool. It’s required to understand how to work with JSON and the the concept of key-value pairs.
The fields on the left side of the screenshot (e.g. “submitter” and “summary”) are the Parameters or Keys you’re matching to the External Source’s Parameters. The fields on the right are the values (e.g. “jim@centercode.com”, “Crashing on load!”) are the values that will be mapped to populate feedback tickets.
Common Troubleshooting Scenario
When sending HTTP Post webhooks from your outside system to your Centercode External Sources API endpoint, you may encounter 400 status codes that indicate failure. The most common causes are due to invalid API endpoints (endpoints change if keys are adjusted) and invalid submitters.
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:
https://<YourCentercodeURL>/api/v1/projects/<YourProjectKey>/feedbackTypes/<YourExternalSourcesConfigurationName>/<feedbackID>/fileElements/<YourElementParameterName>apiKey=<YourAPIKey>
Common Troubleshooting Scenario
The following return response indicates that your API endpoint is invalid.
{
"status": 404,
"description": "The requested resource could not be found."
}
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.