Skip to content

Latest commit

 

History

History
275 lines (233 loc) · 9.1 KB

ui-config.json.md

File metadata and controls

275 lines (233 loc) · 9.1 KB
description
This page provides a comprehensive guide for developers on how to create and structure ui-config.json files used for auto-generating UIs for connectors.

ui-config.json

General Overview

  1. JSON Schema Standard:
    • The file follows the JSON Schema standard (type, properties, required, etc.).
    • Developers should ensure compatibility with standard JSON Schema parsers for validation purposes.
  2. Custom Fields:
    • helptext: A custom field providing detailed guidance that appears when a user focuses on a field.
    • uiIndex: Specifies the display order of fields in the UI.
  3. Flat Structure: Ensure all fields are at the top level. Nested objects are not allowed.
  4. Key Attributes:
    • description: Provides subtext for the input field.
    • helptext: Provides detailed guidance when the user focuses on the field.
    • format: Extended to include:
      • hidden: For fields with non-editable default values.
      • password: For sensitive inputs to hide entered text.
  5. Field Ordering: Use the uiIndex attribute to dictate the order of fields in the UI.

Core Sections in the ui-config.json

1. Metadata

  • title: Title displayed in the UI.
  • description: Brief summary of the connector setup.
  • helptext: General instructions for the user.
{
  "title": "Kafka Connector Setup Instructions",
  "description": "Configure Kafka Connector",
  "helptext": "Follow the below instructions to populate the required inputs needed for the connector correctly."
}

2. Properties

Each property represents a field in the UI. Define its type, validation rules, and additional UI hints.

Example Field: Kafka Brokers

{
  "title": "Kafka Brokers",
  "type": "string",
  "description": "Enter Kafka broker addresses in the format: broker1-hostname:port,broker2-hostname:port",
  "helptext": "<p><strong>Kafka Broker Address Format:</strong> Enter the broker addresses in the following format:<code>&lt;broker1-hostname&gt;:&lt;port&gt;,&lt;broker2-hostname&gt;:&lt;port&gt;</code></p><p><em>Example:</em> <code>broker1.example.com:9092,broker2.example.com:9092</code></p>",
  "uiIndex": 1
}

Field Attributes

  • type: Data type (e.g., string, enum).
  • description: Short subtext visible below the field.
  • helptext: Rich-text or HTML for focus-specific guidance.
  • pattern: Regex for input validation.
  • default: Default value, if any.
  • enum: Allowed values for dropdowns or similar fields.
  • format: Used for hidden or password to modify input behavior.

Example Fields

Below are sample configurations for common Kafka connector fields:

  1. Kafka Brokers (Required)
    • User inputs Kafka broker addresses.
    • Validation ensures correct format.
  2. Kafka Topic (Required)
    • Alphanumeric with dots, dashes, or underscores.
    • Clear helptext and example.
  3. Kafka Auto Offset Reset (Optional)
    • Dropdown with predefined values.
  4. Kafka Consumer Group ID (Required)
    • Alphanumeric name identifying the consumer group.
  5. Data Format (Hidden Default)
    • Predefined formats like json, csv, parquet.

Required Fields

Specify the list of fields mandatory for the configuration:

"required": [
  "source_kafka_broker_servers",
  "source_kafka_topic",
  "source_kafka_consumer_id",
  "source_kafka_auto_offset_reset",
  "source_data_format"
]

Best Practices

  1. Descriptive Text:
    • Ensure description and helptext are clear and concise.
    • Use examples where appropriate.
  2. UI Experience:
    • Use uiIndex for logical field order.
    • Leverage hidden for technical defaults and password for secure inputs.
  3. Validation:
    • Use pattern for format enforcement.
    • Provide feedback for invalid inputs.

Example JSON

Here’s a full example for a Kafka connector:

{
  "title": "Kafka Connector Setup Instructions",
  "description": "Configure Kafka Connector",
  "helptext": "Follow the instructions to configure the Kafka connector.",
  "type": "object",
  "properties": {
    "source_kafka_broker_servers": {
      "title": "Kafka Brokers",
      "type": "string",
      "description": "Enter Kafka broker addresses.",
      "helptext": "<p>Format: <code>broker1:port,broker2:port</code></p>",
      "uiIndex": 1
    },
    "source_kafka_topic": {
      "title": "Kafka Topic",
      "type": "string",
      "pattern": "^[a-zA-Z0-9\\\\._\\\\-]+$",
      "description": "Kafka topic name.",
      "helptext": "<p>Allowed characters: A-Z, 0-9, ., -, _</p>",
      "uiIndex": 2
    },
    "source_kafka_auto_offset_reset": {
      "title": "Kafka Auto Offset Reset",
      "type": "string",
      "enum": ["earliest", "latest", "none"],
      "default": "earliest",
      "description": "Auto offset reset.",
      "helptext": "Start reading from earliest, latest, or none.",
      "uiIndex": 3
    },
    "source_data_format": {
      "title": "Data Format",
      "type": "string",
      "enum": ["json", "csv"],
      "default": "json",
      "format": "hidden",
      "description": "Default format is JSON.",
      "uiIndex": 4
    }
  },
  "required": ["source_kafka_broker_servers", "source_kafka_topic"]
}

Structure for Multi-Tenant Configurations

A multi-tenant connector's ui-config.json organizes configurations under source-specific keys. Each key contains the UI configuration specific to that source, using the same schema as single-source connectors.

Example Structure

Using object store connectors ui-config.json file: 

{
  "aws-s3": {
    "title": "AWS S3 Connector Setup",
    "description": "Configure AWS S3 for the connector",
    "helptext": "Enter details specific to AWS S3, such as bucket name and region.",
    "type": "object",
    "properties": {
      "s3_bucket": {
        "title": "S3 Bucket Name",
        "type": "string",
        "description": "Enter the name of the S3 bucket.",
        "helptext": "Specify the bucket name exactly as it appears in your AWS S3 console.",
        "uiIndex": 1
      },
      "s3_region": {
        "title": "S3 Region",
        "type": "string",
        "description": "Enter the AWS region of the S3 bucket.",
        "helptext": "Example: us-west-2",
        "uiIndex": 2
      },
      "s3_access_key": {
        "title": "Access Key",
        "type": "string",
        "description": "Enter your AWS Access Key ID.",
        "helptext": "This key is used to authenticate access to AWS S3.",
        "format": "password",
        "uiIndex": 3
      },
      "s3_secret_key": {
        "title": "Secret Key",
        "type": "string",
        "description": "Enter your AWS Secret Access Key.",
        "helptext": "This key is used to authenticate access to AWS S3.",
        "format": "password",
        "uiIndex": 4
      }
    },
    "required": ["s3_bucket", "s3_region", "s3_access_key", "s3_secret_key"]
  },
  "azure-blob": {
    "title": "Azure Blob Storage Setup",
    "description": "Configure Azure Blob Storage for the connector",
    "helptext": "Enter details specific to Azure Blob Storage, such as container name and connection string.",
    "type": "object",
    "properties": {
      "blob_container": {
        "title": "Container Name",
        "type": "string",
        "description": "Enter the Azure Blob container name.",
        "helptext": "Specify the container name exactly as it appears in your Azure Storage account.",
        "uiIndex": 1
      },
      "blob_connection_string": {
        "title": "Connection String",
        "type": "string",
        "description": "Enter your Azure Blob connection string.",
        "helptext": "Retrieve this from your Azure Portal under the storage account settings.",
        "format": "password",
        "uiIndex": 2
      }
    },
    "required": ["blob_container", "blob_connection_string"]
  }
}

Guidelines for Multi-Tenant Connectors

  1. Source-Specific Keys:
    • Use keys like to represent each source. For ex: an object store connector pulling data from multiple storage types can use the keys aws-s3, azure-blob, or gcp-storage
    • Each key encapsulates the configuration for that specific source type.
  2. Consistent Schema:
    • The structure within each key follows the same JSON Schema standard as single-source connectors.
    • This ensures consistent validation and UI generation.
  3. UI Differentiation:
    • Fields, help text, and validation can vary by source to accommodate source-specific requirements.
  4. Dynamic Selection:
    • The UI can dynamically display the relevant configuration based on the source type selected by the user.

Best Practices for Multi-Tenant Configurations

  1. Clearly Defined Source Keys:
    • Use meaningful and consistent source identifiers (e.g., aws-s3, azure-blob).
  2. Modular Design:
    • Treat each source configuration as an independent module for easy updates and reusability.
  3. Dynamic UI:
    • Leverage UI logic to dynamically display fields based on the selected source_type.
  4. Validation:
    • Ensure each source configuration has clear validation rules and required fields.