Configuration SDK

Overview

The Configuration SDK accelerates Socotra Enterprise Core config development, getting you up and running with industry-standard development tools following best practices for product creation, maintenance, and troubleshooting. The Configuration SDK exemplifies “convention over configuration”: instead of piecing together all the parts you need for a productive environment, you start with a system ready for use, with the option to pick and choose components or integrate with alternative tools if you want.

The SDK consists of a template to organize your configuration’s source code, along with a collection of Gradle tasks packaged as a Gradle plugin. Though these could be used in any Java development environment, including editors like VS Code with Java-specific extensions, we test against and recommend IntelliJ (Community Edition or better) for use with the Configuration SDK.

Do I really need an SDK to write and maintain configs?

Technically, no. Practically, yes.

Socotra Enterprise Core configuration could be done in any text editor, since you’re working with JSON and Java. However, going without our SDK and a compatible IDE is to deprive yourself of all the advantages that come with our fundamental data model and static typing, such as IDE-assisted code generation, inspection, and proactive plugin and configuration validity checks.

For example, suppose you’ve defined a new product with some underlying elements and data extensions in your JSON config, and now wish 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 you could write all code without typing assistance, it is far easier to have your IDE reference compiled classes for all Socotra and custom types, and gain all the advantages of type-checking and automatic code generation. We supply developer endpoints to support this process, where you 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 process, placing compiled classes from the target tenant or your in-progress config into a directory that your IDE can treat as a library.

Getting Started

Getting started with the Configuration SDK is simple:

Get the source control template
Update the Config SDK Gradle plugin to point at a target tenant
Use tasks as you build your config

The “target tenant” is crucial for plugin development: even if you never intend to deploy to the target tenant directly from your config development environment, the Gradle task set will leverage the tenant’s development endpoints for tasks like validating your config and refreshing your data model for reference by your plugin code.

Get the source control template

The template is available as a public GitHub repository. It includes the Gradle plugin as a dependency that is fetched from the repository’s Maven package index, using your GitHub username and a Personal Access Token (PAT) with the read:packages scope. Check to ensure that Gradle is using valid credentials if the Config SDK plugin fetch does not succeed.

Note

If you’d rather not set up credentials to fetch the plugin dependency from GitHub’s package index, you can download the JAR directly from the “Packages” section on the front page of the Config SDK Template repository. Just click on com.socotra.socotra-ec-config-developer and select the JAR from “Assets”.

Source template file structure

The template is intended to serve as the canonical source repository for your configuration. It closely resembles a typical Gradle project:

├── README.md
├── build
├── build.gradle.kts
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
├── socotra-config
│   ├── config.json
│   └── plugins
│       └── java
│           ├── DocDataSnapshotPlugin.java
│           ├── RatingPlugin.java
│           ├── UnderwritingPluginImpl.java
│           └── ValidationPluginImpl.java
└── src
    ├── main
    │   └── java
    │       └── com
    │           └── socotra
    │               └── deployment
    │                   └── customer
    │                       ├── DocDataSnapshotPlugin.java
    │                       ├── RatingPlugin.java
    │                       ├── UnderwritingPluginImpl.java
    │                       └── ValidationPluginImpl.java
    └── test
        └── java
            └── com
                └── socotra
                    └── deployment
                        └── customer
                            └── RatingPluginTest.java

Notable components:

socotra-config: the local configuration, containing JSON and plugin code organized for deployment. Can be created manually or will be automatically created when pulling config from a tenant using one of the Gradle tasks.
com.socotra.deployment.customer package in src/main/java and src/test/java: canonical plugin code for development and testing. Placement here enables your IDE’s Java code support. When ready for deployment, plugin code should be copied to appropriate locations in socotra-config, which contains the complete deployable config.
build: directory containing build artifacts, including compiled classes for the core Socotra data model and any custom types defined in your product configuration.

Update the config plugin to point at a target tenant

In the template’s build.gradle.kts file, you’ll see the following section:

`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")
}

You can set your environment variables with the requisite information, or write the string values directly. We recommend using environment variables if you are committing your configuration template to source. See the Authentication API reference to learn how to manage Auth (“Personal Access”) Tokens.

Use tasks as you build your config

The Gradle plugin enables two task groups: kernel-developer, and kernel-developer-aux (“auxiliary”). The auxiliary group contains smaller-scale tasks composing the larger tasks found in kernel-developer. You’ll tend to use the kernel-developer tasks the most, which are summarized below:

Task	Description
`cleanupSocotraFolders`	Deletes temporary artifacts produced by the other Gradle plugin tasks.
`createTenant`	Deploys config in your `socotra-config` directory to a brand-new tenant, writing the new tenant locator into the `socotra-config-developer` section in `build.gradle.kts`. Will fail if there is already a `tenantLocator.set` statement in `socotra-config-developer`.
`deployConfigToTenant`	Deploys config in your `socotra-config` directory to the tenant. Will fail if there are unsafe changes.
`overwriteConfigOnTenant`	Deploys config in your `socotra-config` directory, overwriting existing configuration.
`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`.

After you’ve configured the plugin to point to a target tenant, you can run tasks against it. For example, to work on modifications to a tenant’s config, you can execute downloadConfigAndPlugins.

Once you’ve run one of the data model tasks that places your compiled types in the build directory, you’ll be able to use your IDE’s code assistance facilities (auto-completion, type inspection, method generation, etc.) for plugin development.

../../_images/config-sdk-code-assistance.gif

Note

Whenever you download a data model, you may need to refresh your Gradle dependencies to ensure that all the latest type definitions are recognized by your IDE. You can do this from the Gradle sidebar in IntelliJ, or by running ./gradlew --refresh-dependencies in the terminal.

Bootstrapping

Effective use of the Configuration SDK requires a tenant. If you’re starting without a tenant, you’ll need to make an initial config deployment to create one (see “Create a Tenant” in the Configuration Deployments API reference). You can use the createTenant task in the Config SDK task set to deploy to a new tenant.