How can my external system (ex: app) send data to create tickets in Centercode?
This article applies to Team and Legacy editions.
What are External Sources?
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 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 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 first 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.
Common use cases for External Sources
- Allow mobile apps to send data on behalf of their users (including files and crash logs)
- Allow an online form to send feedback for collection and management within Centercode
Prerequisite criteria
- Enhanced Integrations enabled
- Community-level API Key (click here)
- Project Manager access
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.
Configure your External Source
The External Sources tool 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 from your outside system.
From your Project homepage:
- Click Management
- Hover over Project configuration
- Click Feedback types
- Hover over your desired feedback type and click Modify
- 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 Source creation page:
- Create an (internally-facing) Name
- Provide a simple Key to help identify this External Source
- Select the appropriate Workflow for new feedback created via this source (typically “New”)
- Picking No selection here will mark the Status parameter as required
- 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
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.
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. 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.
{
"status": 404,
"description": "The requested resource could not be found."
}
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.
- Single Choice, Multiple Choice, and Rating Scale values passed to Centercode must match the selection options on the Feedback Form 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.
- 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.