Integrations Troubleshooting
Common situations met while connecting other systems, with the likely cause and the recommended resolution. Sections follow the order of the Integrations guides.
Five Checks to Make First
Most Integrations questions are answered by one of these five checks.
- Does the license include Integrations? The Integrations menu appears in Configuration only when it does. License Details shows the service account allowance.
- Does the role have the API and Webhook permissions? They are in the System Configuration group of the role.
- Does Send work on the API? If the API fails on its own, a module or workflow that uses it will fail too.
- Is the response in the format the CRM requires?
A data array and a numeric
pagination.totalRecordsare needed for a list. - Is the token current? An expired token returns an authentication error, usually a 401.
Getting Started
| Symptom | Likely Cause | Resolution |
|---|---|---|
| There is no Integrations menu in Configuration. | The license does not include Integrations, or the role does not have the permissions. | Check License Details and the System Configuration group of the role. |
Service Accounts
| Symptom | Likely Cause | Resolution |
|---|---|---|
| A new service account cannot be created. | The license seat allowance for service accounts is used up, or zero. | Check the seat counter on the Service Accounts screen and remove an unused account. |
| The Generate Service Account button does nothing. | Client ID, Role or Groups has not been filled in. All three are required. | Complete the three fields and try again. |
| The service account secret has been lost. | The secret is shown only once, when the account is generated. | Open the account and use Regenerate Secret, then update the tools that use it. |
REST APIs
| Symptom | Likely Cause | Resolution |
|---|---|---|
| A request returns an authentication error. | The token is missing from the Authorization header, or has expired. | Request a new token from the token endpoint and send it as a Bearer token. |
BI and Database
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The BI tool cannot connect. | The host, port or database name is wrong, or the user name is not the Client ID. | Copy the values from the help section of the Create Service Account form. |
Collections
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The collection cannot be saved. | Collection Name or Base URL is empty, or a Bearer Token collection has no token. | Fill in the required fields. Use a collection script if the token is fetched by a login call. |
| The Select Collection dropdown on a module says Failed to fetch collections. | The integration service is not available for this installation. | Check that Integrations is included in the license, then reload the page. |
Collection Scripts
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The token is fetched on every call. | The script does not save the token with utils.updateCollectionAuth. | Save the token after the login call, and read it from utils.collection.authValues first. |
| The Available APIs list says No APIs available. | The collection has no saved APIs yet. | Create and save the login API, then open the Script Help panel again. |
Creating an API
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The URL does not include the base address. | A full address was pasted, or the path did not start with a slash. | Start the path with a slash so the base address is inserted. |
Variables
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The call fails with a missing value. | A variable has no input, no default value and no script value. | Supply the input, add a default value, or set it in a Pre Script. |
Scripts
| Symptom | Likely Cause | Resolution |
|---|---|---|
| A script error appears when the API runs. | The script returns the wrong thing, or reads a field that is not in the response. | Return the request or response object, and read fields with utils.getValue. |
Response Format
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The Get All API field shows a red message about the data array and totalRecords. | The saved response does not include a data array and a numeric pagination.totalRecords. | Reshape the response with a Post Script, click Send, and save the API. |
| The module loads but columns are empty. | The field names in the records do not match the module's field codes. | Rename the fields in the Post Script to match the field codes. |
External Modules
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The module shows no records, and a Primary Key Not Configured warning is shown. | No field has been marked as the primary key. | Open the Fields tab and mark one field as primary. |
| Agents cannot create or change records. | The Post API, Update API or Delete API slot is empty. | Assign the API if the action is wanted. Leave it empty for a lookup module. |
| Fetch Schema Response creates no fields. | The Get All API has not been saved with a response, or is not assigned to the module. | Save the API, click Send, save again, confirm the Get All API on the Module tab, then fetch again. |
| A script change does not show up in the module. | The change was not saved. Send and the module use the saved scripts. | Click Save on the API, then run Send and reload the module. |
LDAP
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The LDAP plugin shows that the server URL, domain or base DN is required. | These three fields are required when the plugin is turned on. | Fill in the LDAP Server URL, the AD Domain and the Base DN, then click Save Configuration. |
Workflows
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Execute API Request cannot find the API. | The collection was not chosen first, or the API was not saved. | Choose the collection, then the request. Save the API before using it. |
| The workflow waits and then fails. | The outside system is slow and the timeout was reached. | Check the outside system, and set a timeout that suits it. |
Webhooks
| Symptom | Likely Cause | Resolution |
|---|---|---|
| The Schema Editor shows No Schema Generated. | The JSON Input is empty or is not valid JSON. | Paste a valid sample payload. |
| The outside system cannot post to the webhook. | The address was copied with a different name, or the webhook was not created. | Copy the address again from the webhook and send it to the outside system. |
API Documentation
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Try it out returns an authorization error. | No token has been entered under Authorize. | Get a token and enter it under Authorize. |
Permissions
| Symptom | Likely Cause | Resolution |
|---|---|---|
| An administrator cannot open Webhook or Service Accounts. | The API or Webhook permission is switched off on the role. | Switch it on in the System Configuration group of the role. |