Git Integration

All IntelligenceHub start-up Git integration is configured using a JSON file. This file is specified using the environment variable HIGHBYTE_DEPLOYMENT_FILE or java property highbyte.deployment.file. When set, the IntelligenceHub will fetch configuration from one or more Git repositories during start-up. Any errors that occur during configuration are considered critical and will prevent the product from starting.

The deployment settings file can be configured to pull one or many JSON files from Git/Disk, layer the content together, and form a single Deployment settings file that an IntelligenceHub instance is configured with during start-up.

Any secrets stored in the configuration are encrypted/decrypted using the instance json encryption key stored in its certificate store.

Deployment Settings JSON file Schema

/**
 * Represents the configuration object for a deployment settings.
 */
{
    /**
    * The version of the configuration object, currently 0
    */
    version: 0,

    /**
     * Defines the Git repositories used during deployment. Fragments reference a repository by name using the repoName field.
     */
    repos?: {
        type: "git",                // The type of repository, currently only "git" is supported.
        name: string,               // The local name used in this file to link the fragment to this git configuration. The URI below contains the actual name of the repository
        uri: string,                // The URI of the repository.
        author: string,             // The author of the repository.
        email: string,              // The email address of the repository author.
        /**
         * Authentication scheme
         */
        auth: {
            type: "pass" | "none",  // The type of authentication, either "pass" (password) or "none".
            password?: string,      // The password for authentication.
            username?: string,      // The username for authentication.
        }
    }[],

    /**
     * An array of fragment configurations.
     */
    fragments: Fragment[]
}

Fragments describe files that can be imported and layered into a final configuration. These files can be HighByte configuration files, JSON Schema model definitions, UANodeSet model definitions, or any combination of the three. A fragment can reference files on disk or files in a configured Git repository. Fragments also support glob patterns for referencing one or more files. For more information, see Using Glob Patterns.

If the fragment points to HighByte configuration files, it should have the following shape:

{
    details: {
        type: "git" | "file",   // The type of fragment, either "git" or "file".
        patterns: string[],     // An array of glob patterns used to match files relative to rootPath.
        rootPath?: string,      // File only. The base directory used to resolve patterns. If patterns is empty, rootPath is treated as the full path to a single file.
        repoName?: string,      // Git only. The name of the repository associated with the fragment. This must match the name of a repo defined above.
        ref?: string,           // Git only. The reference (e.g., branch or tag) in the git repository.
    },
    type: "highbyte",
    keyPaths: string[]          // JSON Pointer-like string to select a sub-set of elements from the file.
}

If the fragment points to model configuration files, it should have the following shape:

{
    details: {
        type: "git" | "file",   // The type of fragment, either "git" or "file".
        deployFile: string,     // The path to the deployment file.
        repoName?: string,      // Git only. The name of the repository associated with the fragment. This must match the name of a repo defined above.
        ref?: string,           // Git only. The reference (e.g., branch or tag) in the git repository.
    },
    type: "model",
    format: "jsonschema" | "uanodeset"   // The model file format.
}

Using Glob Patterns

Glob patterns let you match multiple files using wildcards rather than listing each file path explicitly. The patterns array in a fragment accepts one or more patterns, and all matched files are included.

Wildcard Behavior
* Matches any characters within a single path segment
** Matches any number of path segments, including none
? Matches exactly one character within a single path segment
{a,b} Matches either a or b using brace alternation
[abc] Matches any one character listed in the brackets
[!abc] Matches any one character not listed in the brackets

Examples

Given the following directory structure:

config/
├── equipment_schema.json
├── material_schema.json
├── assembly/
│   ├── press_schema.json
│   ├── conveyor_schema.json
│   ├── robot_schema.json
│   └── welding/
│       ├── welder_schema.json
│       └── cells/
│           └── plc_schema.json
└── machining/
    └── operator_schema.json

Match all JSON files directly inside assembly/:

"patterns": ["assembly/*.json"]

Matches: assembly/press_schema.json, assembly/conveyor_schema.json, assembly/robot_schema.json

Match JSON files in both assembly/ and machining/ using brace alternation:

"patterns": ["{assembly,machining}/*.json"]

Matches: assembly/press_schema.json, assembly/conveyor_schema.json, assembly/robot_schema.json, machining/operator_schema.json

Match JSON files at all levels under assembly/welding/ using multiple patterns:

"patterns": ["assembly/welding/*.json", "assembly/welding/**/*.json"]

Matches: assembly/welding/welder_schema.json, assembly/welding/cells/plc_schema.json

Exclude files starting with a specific letter using a negated character class:

"patterns": ["assembly/[!r]*.json"]

Matches: assembly/press_schema.json, assembly/conveyor_schema.json. robot_schema.json is excluded because it starts with r.

Application CLI Commands

The application CLI can be used to encrypt passwords or PATs in the deployment settings file:

java -jar intelligencehub-runtime.jar encrypt </path/to/settings.json>

The source-controlled JSON deployment file defines all project and instance configuration used by an IntelligenceHub instance. This format is also used by the Git Backup features configured in Application Settings and can be exported using the application CLI:

java -jar intelligencehub-runtime.jar export [path]

Deployment File JSON High-Level Schema

/**
 * Describes the high-level elements of the deployment JSON file.
 */
{
    /**
     * Information about the instance that generated the deployment file.
     */
    productInfo: {
        company: string,
        product: string,
        version: string,
        build: string,         
        stage: string,
    },

    /**
     * Licensing information.
     */
    license: {
        signature: string,
        license: string,
    },

    /**
     * Project configuration.
     */
    project: {
        version: number,       
        connections: object[],
        conditions: object[],
        inputs: object[],
        outputs: object[],
        modeling: {
            models: object[],  
            instances: object[],
        },
        pipelines: object[],
        tags: object[],
        namespaces: object[],
        functions: object[],
    },

    /**
     * Network-related configuration.
     */
    network: {
        version: number,
        groups: object[],
        hubs: object[],
    },

    /**
     * Access control configuration.
     */
    accesscontrol: {
        version: number,
        roles: object[],
        user: object[],
        apiKeys: object[],
    },

    /**
     * System-level configuration.
     */
    system: {
        version: number,
        secrets: object[],
        variables: object[],
        certificates: object[],
        settings: object,
    },
}