Set up and use the Config SDK for tenant configuration

This article explains how to set up and use the Config SDK to configure tenants for the Socotra Insurance Suite.

Overview

Note: The Config SDK is intended for a technical audience comfortable with programming.

For users who aren’t comfortable with programming, we recommend using the Socotra web interface to make configuration changes. For more information, see: Create a tenant configuration file.

What is the Config SDK?

The Config SDK is a set of tools that are developed and maintained by Socotra for its developer community.

The Config SDK accelerates tenant configuration development for Socotra Insurance Suite by allowing you to develop from a usable base configuration. It also gives you the opportunity to integrate with third-party tools.

The Config SDK includes industry-standard development tools that assist you in product creation, maintenance, and troubleshooting.

The Config SDK has two primary components:

• A template to organize your configuration’s source code

• A collection of Gradle tasks (packaged as a Gradle plugin)

Advantages to using the Config SDK

There are several advantages to using the Config SDK and a compatible IDE, including:

• IDE-assisted code generation

• Inspection

• Proactive plugin and configuration validity checks

Using the Config SDK lets you interact more easily with the Socotra data model and static typing.

Advantage example: Streamlining data typing

Suppose you’ve defined a new insurance product with some underlying elements and data extensions in your JSON config. Now, you want to write a validation plugin.

The Java code for your plugin must refer to the types you’ve defined in your config, in addition to the core Socotra data types.

While it’s possible to write all of that code without typing assistance, it’s far easier to have an IDE that’s able to reference compiled classes for all of your defined data types and the core Socotra data types.

Advantage example: Generating Java classes

You can also use the Config SDK, along with Socotra API developer endpoints, to expedite the configuration process. With Socotra’s developer API endpoints, you can send a config to a tenant and receive compiled JAva classes corresponding to the types therein.

The SDK’s Gradle plugin task set streamlines this activity, placing compiled classes from the target tenant or your in-progress config into a directory that your IDE can treat as a library.

Once you’ve set up the Config SDK, you can write tenant config JSON and plugin code in your IDE, run Config SDK tasks to validate your data model, leverage the IDE’s code completion and generation features, and deploy the config to the tenant.

What will I learn?

By the end of this tutorial, you will know how to:

• Set up the Config SDK for rapid configuration development

• Use key Config SDK features to more easily create and maintain plugin code / tests.

What will I need?

You’ll need the following to follow this tutorial:

• A set of credentials to log into your business account.

  • To learn more, see: Log into Socotra.

• An Integrated Development Environment (IDE) (e.g. IntelliJ, Visual Studio Code, etc.)

  • You can use any IDE, but we recommend using IntelliJ (either Ultimate or the free Community Edition).

• JDK 17 (or higher)

  • Java 17 is the production execution environment for Socotra.

  • Plugin code should be written against the Java 17 standard.

• A tenant created in your business account.

  • The tenant allows the Config SDK ot use the tenant’s development API endpoints for critical tasks. It also serves as the target for configuration deployment from the SDK.

  • For more information, see: Create a tenant in Socotra

Steps

Part 1 - Create a Personal Access Token

The first step is to create a Personal Access Token in Socotra. The Personal Access Token allows the Config SDK to use your business account’s access to Socotra API endpoints.

1. Log into your Socotra business account. For more information, see: Log into Socotra.

   1. For more information, see: Log into Socotra.

2. Click the profile icon in the top-right corner of the screen.

3. Click Personal Access Tokens.

4. On the Personal Access Tokens page, click Create token.

5. In the Create token window, enter a token name of your choice.

   1. For the purposes of this guide, a token with “Full Access” permissions and tenant scope will suffice.

Note: If you’ve created a tenant but don’t see any options under “Add tenants”, navigate to the Tenants tab in your User Profile. Then, confirm that there is at least one tenant scope entry for your user. If the table is empty, create a “Full Access” entry.

Part 2 - Download and configure the Config SDK

Once you’ve created a Personal Access Token, the next step is to:

• Download the Config SDK

• Open it

• Link it to a tenant

We’ll cover how to do that in this section. Before we begin, however, let’s review the components of the Config SDK:

• A template (to serve as the canonical repository for your tenant code)

• A Gradle plugin (to run critical tasks and minimize the number of steps required to get started)

Now that we’ve reviewed that information, let’s continue to learn how to download and configure the Config SDK.

1. Download the latest Config SDK template from Socotra’s GitHub repository: https://github.com/socotra/config-sdk-template

2. Unzip the Config SDK archive.

3. Open the Config SDK directory in your IDE.

4. You should see the following directory structure (which also reflects a typical Gradle project):

The Config SDK plugin will be fetched from the repository’s Maven package index using your GitHub username and a GitHub personal access token (PAT) with the read:packages scope.

Note: If you encounter an error fetching the plugin, check to ensure that Gradle is using appropriate credentials when attempting to fetch the plugin package.

1. Open build.gradle.kts and inspect the socotra-developer section. To set up the Config SDK, you’ll need the following information:

   • The base Socotra API URL corresponding to your target tenant (e.g. https://api.socotra.com)

   • The target tenant locator

   • Your personal access token string

We recommend using environment variables to store these values, especially for any source-controlled development. The example below depicts retrieving environment variables and falling back to hard-coded values.

`socotra-developer` {
    apiUrl.set(System.getenv("SOCOTRA_KERNEL_API_URL") ?: "http://hardcoded-fallback-tenant-url")
    tenantLocator.set(System.getenv("SOCOTRA_KERNEL_TENANT_LOCATOR") ?: "hardcoded-fallback-tenant-locator")
    personalAccessToken.set(System.getenv("SOCOTRA_KERNEL_ACCESS_TOKEN") ?: "hardcoded-fallback-access-token")
}

Alternatively, it’s also possible (though not advised) to simply hard-code the values:

`socotra-developer` {
   apiUrl.set("https://api.socotra.com")
   tenantLocator.set("11d4ae42-971f-45cc-a287-40decd85eaa4")
   personalAccessToken.set("SOCP_01J2VBZSEAN80DEHSFPAF5Y1NY")
}

Part 3 - Fetch your tenant’s config

After setting credentials in the socotra-developer section of build.gradle.kts, you’re ready to execute the Config SDK’s Gradle plugin tasks.

1. Open the Gradle toolbar to reveal the task set under kernel-developer.

• cleanupSocotraFolders: Deletes temporary artifacts produced by the other Gradle plugin tasks.

• deployConfigToTenant: Deploys config in your socotra-config directory to the tenant.

• downloadConfigAndPlugins: Downloads the tenant’s config, along with plugin code and compiled class files for reference by plugins.

• downloadReferenceDataModel: Downloads compiled class files for reference by plugins.

• refreshReferenceDataModel: Places compiled classes corresponding to your local socotra-config definition for reference by plugin code.

• validateConfig: Validates the config in socotra-config.

1. Double-click downloadConfigAndPlugins (or run ./gradlew downloadConfigAndPlugins) in your IDE’s terminal.

   1. You should see a new socotra-config directory in your file tree.

   2. `socotra-config contains a local copy of your tenant’s configuration.

Part 4 - Update and validate the configuration

1. Open socotra-config/accounts/ConsumerAccount/config.json.

2. Add an optional “Notes” field with an invalid type, such as “binary”, and save it:

"data": {
    // ...,
    "Notes": {
        "displayName": "Notes",
        "type": "binary?"
    }
}

3. Run the validateConfig task. You should see an error like the following:

"Error in config bundle: accounts[ConsumerAccount].data[Notes]: type [Binary] is not defined"

4. Since validateConfig has brought an error to our attention, let’s fix it by changing it to a valid type:

"data": {
    // ...,
    "Notes": {
        "displayName": "Notes",
        "type": "string?"
    }
}

5. After saving, run validateConfig again.

   1. You should see the task complete successfully, indicating that the config is once again in a deployable state.

6. Deploy your updated config to the tenant by running deployConfigToTenant. You’ll need to confirm deployment by typing “DEPLOY” in the terminal prompt:

7. Then, ensure that your local Java classes are aligned with the latest state by running downloadReferenceDatamodel.

Part 5 - Write a plugin

Plugin development is where the Config SDK really shines since it allows you to write code with all the productivity-enhancing IDE facilities you would usually expect for Java projects.

In this step, we’ll write a simple validation plugin for the ConsumerAccount.

1. Click on the cycle icon in the Gradle sidebar (or run ./gradlew --refresh-dependencies) to ensure that your IDE has the most recent references to Socotra data types and your own custom data types in your configuration.

2. Open ValidationPluginImpl.java in the src/main/java/com/socotra/deployment/customer directory to begin writing your plugin.

   1. All plugins must belong to the com.socotra.deployment.customer namespace.

   2. You’ll always work on plugin code in the src/main directory, moving code into the socotra-config/plugins directory when you are ready for deployment.

3. You will see a stub validate method entry for ConsumerAccountRequest in ValidationPluginImpl.

4. In the method, you can test out the auto-complete features by typing consumerAccount.data().no in a new line in the method, which will cause the IDE to suggest available data element – notice how the IDE suggest the new “Notes” field that we added:

5. After writing any additional logic for “Consumer Account” validation in this plugin, you can move the plugin code to socotra-config/plugins and deploy.

   1. Future releases of the Config SDK will streamline this process and able to be automated.

Part 6 - Write tests

As is typical for Java projects, you can write tests in src/test, a parallel directory to src/main.

1. Make sure you have the following sample code deployed to your tenant:

package com.socotra.deployment.customer;


import com.socotra.coremodel.ValidationItem;


public class ValidationPluginImpl implements ValidationPlugin {
 @Override
 public ValidationItem validate(ConsumerAccountRequest request) {
   ConsumerAccount consumerAccount = request.account();


   if (consumerAccount.data().lastName().equalsIgnoreCase("Batman")) {
     return ValidationItem.builder()
         .addError("A fictional person cannot be insured")
         .build();
   }


   return ValidationItem.builder().build();
 }
}

2. Create a new Java file ValidationPluginTest in src/test/com/socotra/deployment/customer.

3. Create a new method called testConsumerValidationCatchesSpeciousClaimsToBeTheDarkKnight. In this method, we’ll create a mock ConsumerAccount and run tests against it.

Since the Config SDK template is organized like a typical Gradle project and makes a distinction between the ready-for-deployment configuration and the namespaced Java code, you are free to introduce any other Java libraries you find useful in facilitating development.

For testing, we’ll introduce the Mockito framework, and build a test that uses it. Update your build.gradle.kts dependencies list to add testImplementation("org.mockito:mockito-core:5.+"), and then refresh your Gradle dependencies. Then copy the following code into the test file:

package com.socotra.deployment.customer;


import org.junit.jupiter.api.Test;


import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;


public class ValidationPluginTest {
   @Test
   public void testConsumerValidationCatchesSpeciousClaimsToBeTheDarkKnight() {
       var consumerAccountRequest = mock(ValidationPlugin.ConsumerAccountRequest.class);
       var consumerAccount = mock(ConsumerAccount.class);
       var consumerAccountData = mock(ConsumerAccount.ConsumerAccountData.class);


       when(consumerAccountRequest.account()).thenReturn(consumerAccount);
       when(consumerAccount.data()).thenReturn(consumerAccountData);


       // Batman returns an error
       when(consumerAccountData.lastName()).thenReturn("Batman");
       var validationItem = (new ValidationPluginImpl().validate(consumerAccountRequest));
       assert(validationItem.errors().size() == 1);


       // Other names are acceptable
       when(consumerAccountData.lastName()).thenReturn("Smith");
       validationItem = (new ValidationPluginImpl().validate(consumerAccountRequest));
       assert(validationItem.errors().size() == 0);
   }
}

When you run unit tests from the Gradle sidebar or by executing ./gradlew test in the terminal, you’ll see the tests pass. You can change the validation error sizes or the strings in the test to verify that the tests are actually running.

Once you’re satisfied with your plugin code, you can move it to socotra-config so that it can be deployed.