uip is connectors builder init & connector

Syntax and options for scaffolding, editing, inspecting, and validating a local Integration Service connector — builder init, init preset apply, init header delete, inspect, and validate.

Part of the uip is connectors builder local-authoring toolchain. This page covers the two verbs that own a connector's on-disk shell:

• builder init — create a new connector, or edit fields on the one that resolves from the current directory. Also owns init preset apply (seed a base/pagination configuration bundle) and init header delete (remove a global request header).
• builder inspect / builder validate — read-only structure summary and CI-gradable pass/fail check set. These sit directly under builder, with no connector wrapper in the command path.

For scaffolding activities, auth, triggers, or low-level file edits, see the sibling pages.

Konzepte

• Create vs. edit dispatch — init decides its mode by whether a connector resolves from --connector-dir (or the current directory, scanning only the current directory itself — not subdirectories, unlike other builder commands' fallback resolution). No connector resolves → create (requires --name, scaffolds a fresh tree and seeds defaults). One resolves → edit (only the flags you pass change; everything else on disk is left as-is). If more than one connector directory would match, init fails with Code: "connectorAmbiguous" rather than guessing — pass --connector-dir explicitly.
• Why init won't scan subdirectories — every other builder command falls back to scanning immediate subdirectories when no connector resolves in the current directory (see Concepts on the parent page). init deliberately skips that fallback: scanning would risk resolving a sibling connector directory below cwd and silently editing or renaming it instead of creating a new one. Run init from inside the connector's own directory, or pass --connector-dir to edit one elsewhere.
• What init folds together — this single command replaces what used to be separate connector scaffold, metadata set, global set, and base/pagination config preset surfaces, so the other three authoring verbs (auth, activity, trigger) stay narrow. Long-tail element.json / metadata fields not exposed as flags here (displayOrder, extended, typeOauth, cloneable, tags, …) go through state patch on the Trigger & state page instead.
• Login requirement on create — creating a connector without --organization requires an active login, because the element key (design-{org}-{slug}) stamps the organization. This checks the actual login status, not just whether an org name happens to be cached locally — an expired or refresh-failed session fails the check even though uip login status itself would still report success. Pass --organization <slug> explicitly for offline or CI builds.
• Header create vs. delete asymmetry — adding or updating a global header is folded into init --header VendorName=value (repeatable). Removing one is the separate init header delete <vendor-name> — the one header operation state patch cannot do, because it can't address a single element.json parameters[] array item directly.

Zusammenfassung

uip is connectors builder init [--name <name>] [--connector-dir <path>] [options...]
uip is connectors builder init preset apply --kind <base|pagination> [--override <key=value>]... [--connector-dir <path>] [--force]
uip is connectors builder init header delete <vendor-name> [--connector-dir <path>]
uip is connectors builder inspect [--connector-dir <path>]
uip is connectors builder validate [--connector-dir <path>]

uip is connectors builder init

Create or configure a connector's shell on disk.

Hinweis:

Use this to bootstrap a brand-new connector (--name), or to set connector-level fields — name, description, categories, base URL, headers, lifecycle, tier — on one that already exists. To add resources/activities, use activity create on the Activity & hooks page. To configure authentication beyond the inline --auth sugar, use auth set on the Auth page. To edit a long-tail element.json field this command doesn't expose as a flag, use state patch.

Optionen

Long	Wert	Beschreibung
--name <name>	string	Display name, e.g. 'Acme Widgets'. Required when creating; the element key and default folder are derived from it.
--connector-dir <path>	Pfad	Connector directory. See Concepts above for resolution behavior specific to init.
--organization <name>	slug	Organization slug for the element key (design-{org}-{name}). Create mode only; defaults to your logged-in org.
--description <text>	string	One-line connector description.
--categories <csv>	csv	Comma-separated category list. Matching is case-insensitive; approved values are canonicalized to their approved spelling (e.g. crm → CRM). An unrecognized category fails fast here rather than later at validate.
--activity-color <hex>	hex	Hex color for the Studio activity UI.
--base-url <url>	url	Default base URL — sets the base.url configuration entry. A templated URL (https://{environment}/api) automatically seeds the backing interpolation config entry it needs.
--accept-type <value>	string	Accept header value.
--content-type <value>	string	Content-Type header value.
--header <kv>	VendorName=value	Global request header. Repeatable.
--lifecycle-stage <stage>	string	Lifecycle stage, e.g. GA, BETA.
--tier <tier>	string	Connector tier.
--auth <type>	string	Configure auth inline (create mode only): any auth set --auth-type value (oauth2, customApiKey, none, jwtOauth, firstPartyService, …). With oauth2, --authorization-url, --token-url, and --scope are required. Type-specific flags beyond the ones below need auth set.
--authorization-url <url>	url	OAuth2 login/consent URL. Required with --auth oauth2.
--token-url <url>	url	OAuth2 token endpoint. Required with --auth oauth2.
--token-refresh-url <url>	url	OAuth2 refresh endpoint. Defaults to --token-url.
--token-revoke-url <url>	url	OAuth2 token revoke endpoint.
--scope <scope>	string	OAuth2 space-delimited scope string. Required with --auth oauth2.
--api-key-param-name <name>	string	customApiKey — vendor header or query parameter name.
--api-key-location <where>	header | query	customApiKey — where the key is sent. Default header.
--api-key-prefix <prefix>	string	customApiKey — literal prefix.
--key-config-name <key>	string	customApiKey — internal config key. Default custom.api.key.
--key-config-display-name <name>	string	customApiKey — UI label. Default API Key.
--force	Markieren	Apply diffs on existing entries instead of erroring.

Beispiele

# Create a new connector (auth configured later)
uip is connectors builder init --name 'Acme Widgets'

# Create + OAuth2 + base URL in one call
uip is connectors builder init --name 'Acme Widgets' --base-url https://api.acme.com \
  --auth oauth2 --authorization-url https://acme.com/oauth/authorize \
  --token-url https://acme.com/oauth/token --scope 'read write'

# Edit an existing connector — only the passed flags change
uip is connectors builder init --description 'Acme Widgets connector' --categories crm,sales

Datenform (--output json)

{
  "Code": "ConnectorInitialized",
  "Data": {
    "Mode": "created",
    "ElementKey": "design-myorg-acmewidgets",
    "RepoName": "acme-widgets",
    "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets",
    "FilesCreated": ["app/element/element.json", "..."],
    "OrganizationName": "myorg",
    "OrganizationNameSource": "login",
    "HeadersSeeded": [],
    "BaseUrlSet": false,
    "MetadataChanges": [],
    "AuthConfigured": null
  }
}

Mode is "created" or "edited". Edit mode returns a narrower Data shape: Mode, ConnectorRoot, HeadersChanged, MetadataChanges, BaseUrlSet — there's no FilesCreated, OrganizationName, or AuthConfigured, since those only apply to a fresh scaffold.

uip is connectors builder init preset apply

Apply a canonical bundle of configuration entries: base (base URL plus select/nulls/instance keys) or pagination (the four pagination keys).

Hinweis:

Use this to seed the base or pagination configuration keys in one call. The event/polling bundle is a separate preset reached through trigger create --event-kind, not through this command. To add one bespoke configuration entry instead of a bundle, use state patch element.json/configuration/<key>.

Optionen

Long	Wert	Beschreibung
--kind <kind>	base | pagination	Required. Preset to apply.
--override <kv>	key=value	Per-entry defaultValue override. Repeatable.
--connector-dir <path>	Pfad	Connector directory.
--force	Markieren	Apply diffs on existing entries instead of erroring.

Beispiel

uip is connectors builder init preset apply --kind pagination

Datenform (--output json)

{
  "Code": "ConfigPresetApplied",
  "Data": {
    "Kind": "pagination",
    "Added": ["pagination.max"],
    "Updated": [],
    "Unchanged": [],
    "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets"
  }
}

uip is connectors builder init header delete

Remove a global request header by vendor name.

Hinweis:

Use this to remove a global header you no longer want sent. To add or update one, use init --header VendorName=value — there's no init header create; that operation lives on init itself.

Argumente

Name	Erforderlich	Zweck
<vendor-name>	ja	Vendor header name to remove.

Optionen

Long	Wert	Beschreibung
--connector-dir <path>	Pfad	Connector directory.

Beispiel

uip is connectors builder init header delete X-Tenant

Datenform (--output json)

{
  "Code": "GlobalHeaderRemoved",
  "Data": { "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets", "VendorName": "X-Tenant" }
}

uip is connectors builder inspect

Produce a read-only structured overview of a connector: auth types, configuration, resources (with standard-resource files and hooks), global hooks, events, and metadata.

Hinweis:

Use this to get a quick map of an existing connector before editing it, or to confirm which resources, hooks, and auth types are present. For pass/fail checks instead of a structure summary, use validate.

Optionen

Long	Wert	Beschreibung
--connector-dir <path>	Pfad	Connector directory.

Beispiel

uip is connectors builder inspect --connector-dir ./my-acme-connector

Datenform (--output json)

{
  "Code": "ConnectorInspected",
  "Data": {
    "ConnectorRoot": "/work/my-acme-connector",
    "ElementKey": "design-myorg-acmewidgets",
    "Name": "Acme Widgets",
    "Description": "Acme Widgets connector",
    "AuthTypes": ["oauth2"],
    "ConfigCount": 5,
    "ConfigKeys": ["base.url", "..."],
    "ResourceCount": 12,
    "ResourceSummary": {
      "/auth_validation": { "Methods": ["GET"], "Type": "standard", "StandardResourceFile": "auth_validation.json", "Hooks": [] }
    },
    "GlobalHooks": [],
    "HasEvents": false,
    "EventTypes": [],
    "Categories": ["CRM"],
    "LifecycleStage": "GA",
    "Metadata": { "...": "verbatim element-metadata.json content" }
  }
}

ResourceSummary is keyed by the resource's actual on-disk path (e.g. /auth_validation), and Metadata is the verbatim content of element-metadata.json. Both are exempt from the CLI's usual PascalCase key normalization — the raw keys are preserved exactly as they appear on disk, so a selector built from this output (e.g. /auth_validation, {sys_id}) matches the real file path instead of a mangled /authValidation / {sysId} variant.

uip is connectors builder validate

Run the full check set over a connector and emit a structured report. Exits non-zero when the connector is invalid, so CI can gate on it.

Hinweis:

Use this to gate a connector in CI before import or release, and to find errors, warnings, and suggestions across element.json, standard-resource files, hooks, and metadata. To browse a connector's structure instead of running checks, use inspect.

Optionen

Long	Wert	Beschreibung
--connector-dir <path>	Pfad	Connector directory.

Beispiele

uip is connectors builder validate

uip is connectors builder validate --connector-dir ./my-acme-connector

Datenform (--output json)

{
  "Code": "ConnectorValidation",
  "Data": {
    "ConnectorRoot": "/work/my-acme-connector",
    "ElementKey": "design-myorg-acmewidgets",
    "Valid": true,
    "Errors": [],
    "Warnings": [],
    "Info": ["Configuration entries: 5"],
    "Summary": "PASS: 0 error(s), 0 warning(s)"
  }
}

The report is emitted on both pass and fail — a failing report still returns Result: "Success" with Valid: false in Data (the command itself didn't error), but the process exits with a non-zero exit code so CI can gate on the outcome without parsing the body.

Zugehörig

• uip is connectors builder — concepts, and the tenant-lifecycle verbs (download/import/publish/publish-status).
• Auth — configure the connector's authentication scheme.
• Activity & hooks — define what the connector's activities do.
• Trigger & state — event triggers and low-level element-file edits.

Siehe auch

• Übersicht über das Integration Service-Tool
• Globale Optionen
• Exitcodes