Create Your First Extend App¶

This guide walks through the production workflow for creating an Extend connector and making it available as a node in Workspace.

Before you begin¶

You need:

Extend developer access
an organization where the connector can be installed
a governed Python runtime for the requested Python version
any required account or credential already configured in SchemAlign
connector source code that follows the Extend Production Guardrails

1. Decide what the connector does¶

Define the connector in one sentence.

Good examples:

Read directory entries over LDAP and publish a CSV stream.
Call a vendor API and write the response as JSON.
Transform an input file into a normalized CSV output.

Then choose the connector type:

Type	Use when
Source	The connector starts a stream by reading from an external system or generating an output file.
Compose	The connector prepares, reshapes, or enriches data inside the workflow.
Destination	The connector delivers a prepared stream or output to an external system.

2. Create the connector draft¶

In SchemAlign, open Admin > Extend and create a connector draft.

Use stable values:

Field	Description
Node key	Stable identifier for the connector. Use lowercase letters, numbers, and underscores, such as `active_directory_ldap_browser`.
Name	User-facing connector name.
Description	Short explanation of what the connector does.
Connector type	Source, compose, or destination.
Version	Draft version tag, such as `0.1.0`.
Entrypoint	Usually `connector:run`.
Python version	Governed Python version to run the connector.
Dependencies	One pinned package requirement per line.
Capabilities	Optional capability names that must be approved before an installed connector is enabled.

3. Add or replace connector source¶

The default source file should contain the configured entrypoint. For the common connector:run entrypoint, the source file is usually connector.py and includes:

def run(payload: dict | None = None) -> dict:
    payload = payload or {}
    config = payload.get("input_payload") or {}
    output_dir = Path(str(payload.get("output_dir") or "."))
    output_dir.mkdir(parents=True, exist_ok=True)
    return {"status": "ok"}

Keep connector code self-contained. Do not import SchemAlign internals.

4. Define the configuration schema¶

The configuration schema controls the fields shown in the node drawer when the connector is used in Workspace.

A simple schema looks like this:

{
  "type": "object",
  "additionalProperties": true,
  "required": ["account_id", "server_uri"],
  "properties": {
    "account_id": {
      "type": "string",
      "title": "Account",
      "description": "Account reference used to resolve credentials at runtime."
    },
    "server_uri": {
      "type": "string",
      "title": "Server URI / host"
    }
  }
}

Use account_id for credentials. Do not create password, token, or secret text fields in the schema.

5. Add safe test metadata¶

Test metadata should be safe to store and view. Use mock mode and synthetic values.

{
  "mode": "mock",
  "output_format": "csv",
  "publish_artifact": false,
  "publish_history": false
}

6. Validate the draft¶

Run validation before testing. Validation checks manifest shape, dependency declarations, governed runtime availability, source file paths, Python syntax, and entrypoint resolution.

Fix validation errors before publishing.

7. Build the dependency environment¶

Build the dependency environment for the draft version. SchemAlign uses the requested Python runtime and pinned requirements to create a dedicated runtime environment.

Do not make connector code install dependencies during a run.

8. Run a test¶

Run a connector test with safe input. If the connector needs credentials for live testing, use a configured account reference and a safe organization context.

Review:

status
stdout/stderr
returned JSON
output files
row counts or other output metadata

9. Publish the version¶

Publish only after validation and testing are clean. Publishing converts the draft into an immutable version and stores source, dependency, and package hashes.

Published versions are read-only. Create a new draft version for future changes.

10. Install to an organization¶

Install the published version to the target organization. If the connector requested capabilities, approve them before enabling the installation.

Once installed and enabled, the connector can appear in Workspace as an installed connector option for that organization.

11. Use it in Workspace¶

Open a pipeline in the organization where the connector is installed. Add the installed connector node, configure its schema-driven fields, connect it to downstream nodes, and run the pipeline.

For a full example, see Build an Active Directory LDAP Browser.