Catalyst Java SDK Integration in Third-Party Applications

You can integrate and use the Catalyst Java SDK methods in applications deployed outside the Catalyst environment. Say, a React app hosted on Vercel using a Flask backend (running outside Catalyst) can upload documents to Catalyst Cloud Scale Stratus or a data pipeline running on Amazon Web Services EC2 can push customer data into Catalyst Cloud Scale Data Store using Catalyst Cloud Scale ZCQL queries using the respective Java SDK operations.

These are just a few common use cases where external applications can securely interact with Catalyst components without being deployed within the Catalyst platform.

We have provided the code snippet to help you integrate the Catalyst Java SDK with external applications. However, before implementing the code in your application, please review the following prerequisites.

Prerequisites for the SDK Integration

To integrate the Catalyst Java SDK with your external application, ensure you have the following information:

• Project ID:

The unique identifier of your Catalyst project.

• ZAID (Zoho Account ID):

A unique portal identifier assigned by Catalyst to link your project with the Catalyst environment (development or production).

• Environment:

The target environment (development or production) of your Catalyst project.

• OAuth Credentials:

This is required to authenticate and authorize your external application via Catalyst’s self-client portal to access Catalyst components. You will need the following:

1. Client ID
2. Client Secret
3. Refresh Token

After you fetch these values , you can proceed with integrating the Java SDK into your application.

Now, let’s look at how to fetch each of these values and configure them in the code snippet.

Please ensure you follow the steps outlined below:

1. Create a project in the Catalyst Console : You can create a new Catalyst project in the console by using the steps mentioned in this help page.

2. Retrieve the Project ID: Once you have created your project, you will need to make a note of the Project ID. The Project ID is the unique ID of your project that will be created automatically during the project’s creation.

You can find it by clicking the Settings icon located in the top-right corner of the Catalyst console.

In the Settings screen, navigate to Project Settings and select General. You can view and make a note of the Project ID from this section, as shown in the screenshot below.

3. Retrieve the ZAID: You will need to include your project’s ZAID in the code snippet provided in this section. The ZAID is a unique portal identifier assigned by Catalyst to link your project with the required Catalyst environment (development or production). You can learn more about Catalyst environments from this help page.

To retrieve the ZAID, setting up the Catalyst CloudScale Authentication component is mandatory. However, using it for your application’s authentication flow is optional. Below are the steps to fetch the ZAID:

i. Navigate to the Catalyst CloudScale service in the console and under Security & Identity, select Authentication.

ii. You will need to set up Native Catalyst Authentication, where Catalyst manages the entire authentication process for you, eliminating the need for any additional coding or infrastructure management on your part.

iii. Click on Set Up.

iv. In the next step, select Hosted authentication type, which enables you to host your login element on dedicated pages of your application. You can configure and design the authentication from the console, and Catalyst will render it for your application and handle all the backend requirements.

v. You must enable the Public Signup option to display the signup feature in your login component, allowing new users to register and access your application.

vi. You can refer to the hosted authentication help page for a detailed step-by-step setup guide.

vii. In the confirmation screen, click Yes, proceed.

viii. You can enable any of the supported social login options listed below and retrieve the corresponding ZAID value from the selected provider. For detailed instructions on how to obtain the ZAID for a specific social login, refer to the steps outlined in this help page.

To know more about this hosted authentication type, you can refer to its dedicated help page.

4. Register a Self Client Application: You will need to obtain the Refresh Token, Client ID, and Client Secret to authenticate and authorize your application to access Catalyst resources on behalf of your application’s user.

For fetching the above required items, you must first register your application as a self-client in API console.

i. Login to the API console and click on Self-client.

ii. You must configure the scope of the self-client application based on the operations your application needs to perform in Catalyst. For more information on available scopes, refer to this help page.

iii. Provide the required scope, add an appropriate description, and click Create.

iv. The grant token will be generated. Please make sure to copy and store it securely, as this is a one-time process and the token cannot be retrieved from the console again.

For step-by-step guidance on generating the grant token, please refer to this help page.

v. Switch to the Client Secret tab and note down the client ID and the client secret details.

vi. You can generate the access and refresh token by using the request in this help page. You can also refresh the access token by using the steps listed in this page.

After you have noted all the values mentioned above, you can configure them in the code snippet as shown below and integrate Java SDK into your application. The SpringBoot code below demonstrates this with the example of fetching buckets from Catalyst CloudScale Stratus.

Code Snippet

    

        
copy
        

            

        
    
    

         package com.example.demoapp; 
import org.springframework.boot.CommandLineRunner; 
import org.springframework.boot.SpringApplication; 
import org.springframework.boot.autoconfigure.SpringBootApplication; 
import org.springframework.stereotype.Component; 
import java.util.List; 
import java.util.logging.Logger; 
import org.json.simple.JSONObject; 
import com.zc.common.ZCProject; 
import com.zc.common.ZCProjectConfig; 
import com.catalyst.config.ZCThreadLocal; 
import com.zc.api.APIConstants.ZCAuthType; 
import com.zc.api.APIConstants.ZCUserScope; 
import com.zc.auth.ZCAuth; 
import com.zc.component.USER_TYPE; 
import com.zc.component.object.ZCObject; 
import com.zc.component.object.ZCRowObject; 
import com.zc.component.object.ZCTable; 
@SpringBootApplication 
public class DemoappApplication { 
private static final Logger logger = 
Logger.getLogger(DemoappApplication.class.getName()); 
public static void main(String[] args) { 
SpringApplication.run(DemoappApplication.class, args); 
} 
@Component 
public static class DataProcessor implements CommandLineRunner { 
@Override 
public void run(String... args) { 
try { 
ZCThreadLocal.putValue("user_type", USER_TYPE.ADMIN); 
JSONObject oAuthParams = new JSONObject(); 
oAuthParams.put("client_id", CLIENT_ID); //Provide CLient ID value here
oAuthParams.put("client_secret", CLIENT_SECRET); //Provide CLient secret value here
oAuthParams.put("refresh_token", REFRESH_TOKEN); //Provide refresh token value here
oAuthParams.put("grant_type", "refresh_token");   
ZCAuth auth = ZCAuth.getInstance(oAuthParams); 
auth.setScope(ZCUserScope.ADMIN); 
System.out.println("Auth Object: " + auth); 
ZCProjectConfig config = ZCProjectConfig.newBuilder() 
.setProjectId(PROJECT_ID) //Provide Project ID value here
.setProjectKey(ZAID) //Provide ZAID value here
.setZcAuth(auth) 
.setProjectDomain("https://api.catalyst.zoho.com") 
.setEnvironment("Development") //set the value as either "Development" or "Production"
.build(); 
ZCProject project = ZCProject.initProject(config, ""); 
ZCStratus stratus = ZCStratus.getInstance(); 
List  buckets = stratus.listBuckets(); 
} 
catch (Exception e) { 
logger.severe("Error during data processing: " + 
e.getMessage()); 
            } 
        } 
    } 
}