Installation and Configuration
Zoho Connector
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2023.
All rights reserved. All hardware and software names used are brand names and/or trademarks of their respective manufacturers.
These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes, or any other protected rights. The dissemination, publication, or reproduction hereof is prohibited.
For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.
Introduction
Using the Zoho Connector, tickets in Zoho can be indexed with their metadata and content.
Configuring Zoho
Generating Credentials
First, the credentials for the connector must be generated in Zoho.
Navigate to https://api-console.zoho.com/. If you have not yet created a "Self Client", create it by clicking on "Add Client" and then "Self Client".
When you click on the created Self Client, in the "Client Secret" tab you will find the Client ID and Client Secret that are required for the Connector.
In addition, a refresh token must be generated. To do this, go to the "Generate Code" tab in the Self Client. Insert the following in the "Scope" field:
SDPOnDemand.requests.READ,SDPOnDemand.general.READ,SDPOnDemand.setup.READ
Add a short description in the "Scope Description" field. Before you click on "Create", it is best to prepare the next request to fetch the refresh token, because the generated code is only valid for a maximum of 10 minutes.
You have to execute the following request with curl or Postman:
curl --location --request POST '<AccountsServerUrl>/oauth/v2/token' \
--form 'code="<GeneratedCode>"' \
--form 'grant_type="authorization_code"' \
--form 'client_id="<ClientId>"' \
--form 'client_secret="<ClientSecret>"' \
--form 'redirect_uri="https://www.zoho.com"'
Attention: Depending on the Postman version, this curl command may not be imported correctly. Make sure that the values of the parameters in Postman are not quoted with double quotes:
All entries in angle brackets need to be replaced with the respective parameters:
- AccountsServerUrl: The accounts server URL, based on your data center. You can find it here: https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/data-centers.html
- GeneratedCode: The code generated once you click the "Create" button.
- ClientId: The Client ID in the "Client Secret" tab in the Self Client.
- ClientSecret: The client secret in the "Client Secret" tab in the Self Client.
If you execute the request successfully, you will receive a response with a refresh token - this is needed for the configuration of the connector.
Configuring Mindbreeze
Open Mindbreeze Management Center in the browser to start the configuration.
Configuring the Index
In the Indices tab, add a new index using the +Add Index button. Select the desired Index Node and Client Service and specify the Zoho data source in the Data Source field. Then confirm your entries with the Apply button.
Configuring the Data Source
Now configure the data source.
Legend:
- Properties marked with *: mandatory field, these must be configured explicitly
- Properties not specially marked: optional fields
- Fields marked with (Advanced Settings) are only displayed if the "Advanced Settings" view is enabled in the configuration. This is only necessary in special use cases.
Connection Settings
Zoho URL* | The URL of your Zoho instance. If you have multiple Zoho instances, you must specify the URL to the exact instance. For example, if the homepage of your instance is https://mycompany.myzoho.com/app/myinstance/ui/ssp/pages/home, the Zoho URL must be https://mycompany.myzoho.com/app/myinstance. |
OAuth Credential* | A credential containing the Access Token URL, Client ID and Client Secret generated in the Generate Credentials step. The Access Token URL again depends on your Data Center. The format is <AccountsServerUrl>/oauth/v2/token. You can find your Accounts Server URL here: https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/data-centers.html |
Refresh Token* | A password credential containing the refresh token generated in the Generating Credentials step. |
Page Size | Number of objects that are fetched with one request from the Zoho API. The maximum value is 100. |
Log All Requests | If this option is enabled, all requests against Zoho will be written to the logfile "request-log.csv" as long as the login is successful. |
Permissions (Advanced Settings)
Own Site Requests Accessible | If this option is enabled, all requesters can find all requests created in their site in the Mindbreeze Search. | ||||
Static ACL | Static access rules which are set on all indexed documents.
|
Configuring the Principal Resolution Service
The Zoho connector also requires a Principal Resolution Service to resolve permissions.
To create this, scroll down to the Services section in the Indices tab and add a new service using the +Add Service button. For this service, select Zoho Principal Resolution Service in the Service dropdown.
Connection Settings
The connection settings here are identical to the connector as described in this section.
Cache, Health Check, Parent Cache, Service & Consumer Services Settings
These config options are described here in the Caching Principal Resolution Service documentation.
REST API zum Testen
- To test the caching principal resolution service, you can use the Principal Resolution Service REST API.
Appendix
Principal Names
If departments, locations or all requesters/technicians are to be specified with the "Static ACL" setting, these must be resolved via the Principal Resolution Service. For this it is necessary to use the exact correct names for the principals.
Use Case | Principal Name |
All requesters | zho_all_requesters |
All technicians | zho_all_technicians |
All requesters of a specific site | zho_site_<siteId>_requesters |
All technicians of a specific site | zho_site_<siteId>_technicians |
All requesters of a specific department | zho_department_<departmentId>_requesters |
All technicians of a specific department | zho_department_<departmentId>_technicians |
Finding the Site Ids
To find out the id of a site you need to go to "Setup" in Zoho (gear on the top right), then under “Instance Configurations” -> “Sites” you can view all sites. By right clicking on a site -> “Inspect Element” you can then see the id of the site:
Finding the Department Ids
To find out the id of a department you need to go to "Setup" in Zoho (gear on the top right), then under “Instance Configurations” -> “Departments” you can view all departments per site. In the dropdown list on the top right, select the site where your department is. By right clicking on a department -> “Inspect Element” you can then see the id of the department:
