Advanced Settings
Establishing a Connection
Connecting To SuiteCRM V4.1 API
You can connect to SuiteCRM data via the V4.1 API by simply setting the following connection properties:
- Schema: Set this to suitecrmv4.
- Url: Set this to the URL associated with the SuiteCRM application, for example http://suite.crm.com.
- User: Set this to the user associated with the SuiteCRM account.
- Password: Set this to the password associated with the SuiteCRM account.
Note that retrieving SuiteCRM metadata can be expensive. It is advised that you store the metadata locally as described in Caching Metadata.
Connecting To SuiteCRM V8 API
Before Connecting
Before you connect to SuiteCRM V8 API you will need to first configure it in your SuiteCRM instance. The API can be configured in SuiteCRM version 7.10+. To configure the API, please follow the steps written in the SuiteCRM JSON API docs, found here: https://docs.suitecrm.com/developer/api/developer-setup-guide/json-api/#_before_you_start_calling_endpoints .
The SuiteCRM V8 API uses OAuth2.0 as its main method of authentication using 2 types of grant type, password or client credentials. To authenticate to SuiteCRM V8 API, please do the following. Note that you have to be an admin to create credentials, create roles, assign roles to users etc.
Note: The OAuth flow is the same in a headless machine.
Register an Application
To obtain the OAuth client credentials, the consumer key, and consumer secret:
- Log in to your admin account.
- On profile dropdown select Admin > OAuth2 Clients and Tokens and click New Password Client or New Client Credentials Client.
- Enter a name and a secret.
- Click Save.
Assign Roles for API Access
Usually when authenticating with a client credentials grant type, you will have full access to the API. For authentication with password grant type, the user should have permissions for each module/table.
Users' access to certain resources can be set by configuring REST roles and assigning users to the specific REST roles.
To create a role:
- On the profile dropdown, select Admin > Role Management and click Create Role.
- Enter name and description and click Save. Then, you will be redirected to the role configuration menu where you can select permissions to any operation on any module.
- After you are done with setting up the permissions, you can click Save.
To assign a role to a user:
- On profile dropdown, select Admin > Role Management and click on the role you want to assign to a user.
- Scroll down to the bottom and click Select User.
- A user search window will appear.
- Select the users you want to assign the role to and click Select > Save.
Authenticating using Client Credentials Grant
After setting the following connection properties, you are ready to connect:
- Schema: Set this to the suitecrmv8.
- OAuthGrantType: Set this to CLIENT.
- OAuthClientId: Set this to the client key that you received.
- OAuthClientSecret: Set this to the client secret that you noted.
- InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.
- URL: The base URL of your SuiteCRM system. For example, https://suitecrmhost/.
Authenticating using Password Grant
After setting the following connection properties, you are ready to connect:
- Schema: Set this to the suitecrmv8.
- OAuthGrantType: Set this to PASSWORD.
- OAuthClientId: Set this to the client key that you received.
- OAuthClientSecret: Set this to the client secret that you noted.
- User: Set this to the username associated with the user.
- Password: Set this to the password associated with the user.
- InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.
- URL: The base URL of your SuiteCRM system. For example, https://suitecrmhost/.
Customizing the SSL Configuration
By default, the provider attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.
Connecting Through a Firewall or Proxy
HTTP Proxies
To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.
In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.
Other Proxies
Set the following properties:
- To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
- To tunnel the connection, set FirewallType to TUNNEL.
- To authenticate, specify FirewallUser and FirewallPassword.
- To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.
Troubleshooting the Connection
To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.
- Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
- Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.
- The certificate presented by the server cannot be validated: This error indicates that the provider cannot validate the server's certificate through the chain of trust. If you are using a self-signed certificate, there is only one certificate in the chain.
To resolve this error, you must verify yourself that the certificate can be trusted and specify to the provider that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.