Skip to main content

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.

  1. Does the license include Integrations? The Integrations menu appears in Configuration only when it does. License Details shows the service account allowance.
  2. Does the role have the API and Webhook permissions? They are in the System Configuration group of the role.
  3. Does Send work on the API? If the API fails on its own, a module or workflow that uses it will fail too.
  4. Is the response in the format the CRM requires? A data array and a numeric pagination.totalRecords are needed for a list.
  5. Is the token current? An expired token returns an authentication error, usually a 401.

Getting Started​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
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​

SymptomLikely CauseResolution
Try it out returns an authorization error.No token has been entered under Authorize.Get a token and enter it under Authorize.

Permissions​

SymptomLikely CauseResolution
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.