# uip is connectors builder trigger & state

> Syntax and options for wiring polling/webhook triggers and for low-level structured read/write access to a connector's files with the Integration Service connector builder — trigger create, state query, and state patch.

Part of the [`uip is connectors builder`](./uip-is-connectors-builder.md) local-authoring toolchain. This page covers two unrelated but small command groups that share a page because of their size:

- **`builder trigger create`** — wire an existing activity as an event source (polling or webhook), so Studio can trigger a process when a vendor record is created, updated, or deleted.
- **`builder state query`/`patch`** — a generic, pointer-addressed read/write surface over a connector's on-disk files. This is the escape hatch for anything the higher-level commands (`init`, `auth`, `activity`) don't expose as a dedicated flag.

For connector directory resolution, the design-vs-published distinction, and the overall authoring flow, see [Concepts](./uip-is-connectors-builder.md#concepts) on the parent page. For the activities a trigger attaches to, see [Activity & hooks](./uip-is-connectors-builder-activity.md).

## Synopsis

```text
uip is connectors builder trigger create --resource-name <name> --updated-date-field <field> [options...]
uip is connectors builder state query <pointer> [--connector-dir <path>]
uip is connectors builder state patch <pointer> [--value <json> | --value-file <path>] [--op upsert|remove] [--connector-dir <path>]
```

## uip is connectors builder trigger create

Wire an existing activity/resource as a trigger source: seed the event config bundle (`--event-kind`), then configure polling metadata (`CREATED`/`UPDATED`/`DELETED`) — the standard-resource metadata, the poller config entry, and the connector's `hasEvents` flag.

`trigger` has a single verb. There is no `trigger list`/`get`/`delete` — remove or inspect a trigger through [`state patch`/`state query`](#uip-is-connectors-builder-state-query) against the resource's `element.json` entry instead.

:::note
Use this to turn an existing GET activity into a polling trigger source. The activity must already exist — this command hard-fails with `Code: "resourceNotFound"` if no standard-resource file exists yet for `--resource-name`; run [`activity create`](./uip-is-connectors-builder-activity.md) first.
:::

### Options

| Long | Value | Description |
|---|---|---|
| `--resource-name <name>` | string | **Required.** Existing activity/standard-resource to wire as a trigger. |
| `--updated-date-field <field>` | string | **Required.** Vendor field carrying the last-modified date, for example `LastModifiedDate`. |
| `--event-kind <kind>` | `polling` \| `webhook` \| `all` | Event config bundle to seed. Default `polling`. Validated client-side — an unrecognized value fails fast with `Code: "invalidEventKind"` rather than silently falling back. |
| `--override <kv>` | `key=value`, repeatable | Per-entry `defaultValue` override for the seeded event preset. |
| `--created-date-field <field>` | string | Vendor creation-date field. Defaults to `--updated-date-field`. |
| `--id-field <field>` | string | Primary key field. Defaults to `Id`. |
| `--date-format <mask>` | string | Date-format mask for updated timestamps. |
| `--created-date-format <mask>` | string | Date-format mask for created timestamps. Defaults to `--date-format`. |
| `--event-types <csv>` | comma-separated | Event types to enable. Defaults to `CREATED,UPDATED,DELETED`. |
| `--polling-url <url>` | url | Explicit polling URL. Auto-generated from the activity's GET path when omitted. |
| `--date-timezone <tz>` | string | Timezone for date comparisons. Defaults to GMT. |
| `--polling-resource-label <label>` | string | Label used in `elementMetadata.pollingResources`. |
| `--connector-dir <path>` | path | Connector directory. Same resolution order as [Concepts](./uip-is-connectors-builder.md#concepts). |

`--event-kind` folds what used to be a separate `config preset --kind event` step: it seeds the event config bundle (the poller config entry polling needs) before wiring the polling metadata, in one call.

### Example

```bash
uip is connectors builder trigger create --resource-name Account \
  --updated-date-field LastModifiedDate --id-field Id
```

### Data shape (--output json)

```json
{
  "Code": "TriggerCreated",
  "Data": {
    "ConnectorRoot": "/work/my-acme-connector",
    "ResourceName": "Account",
    "EventKind": "polling",
    "EventTypes": ["CREATED", "UPDATED", "DELETED"],
    "PollingUrl": "/accounts?where=LastModifiedDate>'<gmtDate>'",
    "PollerConfigKey": "polling.interval",
    "PollingConfig": { "...": "seeded poller config entry" }
  }
}
```

A `Warnings` array is added when the operation succeeds with caveats (for example, an auto-generated polling URL that may need manual review).

## uip is connectors builder state query

Read the slice of a connector addressed by a pointer. Read-only — returns the parsed value as-is (an object, array, or string).

:::note
Use this to inspect a connector's current shape before patching it — a single config entry, resource, standard-resource field, hook file, or metadata key. For a whole-connector structural rollup instead of one addressed slice, use [`inspect`](./uip-is-connectors-builder-init.md#uip-is-connectors-builder-inspect). To write or remove, use `state patch` below.
:::

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<pointer>` | yes | Pointer into the connector — see [Pointer grammar](#pointer-grammar) below. |

### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Connector directory. Same resolution order as [Concepts](./uip-is-connectors-builder.md#concepts). |

### Examples

```bash
uip is connectors builder state query element.json/configuration/base.url
```

```bash
# Path segments in a resource pointer are URL-encoded
uip is connectors builder state query element.json/resources/GET/%2Fcontacts
```

```bash
uip is connectors builder state query standard-resources/contacts/fields/email
```

### Data shape (--output json)

```json
{
  "Code": "StateQuery",
  "Data": {
    "pointer": "element.json/configuration/base.url",
    "value": { "key": "base.url", "type": "TEXTFIELD_128" }
  }
}
```

`Value`'s keys are kept exactly as they appear on disk (camelCase, not PascalCased like the rest of this CLI's output) — this is deliberate, so a `state query` result can be fed straight into `state patch --value` without any reshaping. See [Query → patch round-trip](#query-patch-round-trip) below. An array-level read that returns per-item stubs instead of full objects adds `"Summarized": true` and a `SummaryHint` field to the envelope — treat a summarized result as a list of names/keys to query individually, not the full records.

## uip is connectors builder state patch

Write (upsert) or remove the slice of a connector addressed by a pointer. `element.json` is the source of truth; linked standard-resource parameters auto-sync when a patch changes something they depend on.

:::note
Use this to set or replace a config entry, resource, parameter, standard-resource field, hook, or metadata key that none of the higher-level commands (`init`, `auth`, `activity`) expose as a dedicated flag — or to remove a single addressed item (`--op remove`). To read first, use `state query` above. This is not for bulk scaffolding or auth wiring — use the dedicated authoring commands for those.
:::

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<pointer>` | yes | Pointer into the connector — see [Pointer grammar](#pointer-grammar) below. |

### Options

| Long | Value | Description |
|---|---|---|
| `--value <json>` | inline JSON | Value to write. Mutually exclusive with `--value-file`. Omit for `--op remove`. |
| `--value-file <path>` | path | Read the JSON value to write from a file instead of inline. Mutually exclusive with `--value`. |
| `--op <op>` | `upsert` \| `remove` | Operation. Default `upsert`. |
| `--connector-dir <path>` | path | Connector directory. Same resolution order as [Concepts](./uip-is-connectors-builder.md#concepts). |

### Examples

```bash
uip is connectors builder state patch standard-resources/contacts/fields/email \
  --value '{"type":"string","vendorPath":"email"}'
```

```bash
uip is connectors builder state patch 'element.json/resources/GET/%2Fcontacts/parameters/0' --op remove
```

### Data shape (--output json)

```json
{
  "Code": "StatePatched",
  "Data": {
    "Pointer": "standard-resources/contacts/fields/email",
    "Op": "upsert",
    "Outcome": "Upserted field 'email' in contacts."
  }
}
```

A `Warnings` array is added when the patch succeeds with caveats, and an `AutoSynced` array lists any linked files or fields the patch updated as a side effect (for example, a standard-resource parameter kept in sync with a changed `element.json` resource definition). Both are omitted from `Data` when empty.

### Pointer grammar

Both `state query` and `state patch` address a connector through the same pointer grammar, also shown in each command's own `--help` output:

| Pointer | Addresses |
|---|---|
| `element.json/configuration` | Configuration summary. Filter with `?type=`. |
| `element.json/configuration/{key}` | One configuration entry. |
| `element.json/resources` | Resource summary. Filter with `?method=` / `?type=`. |
| `element.json/resources/{METHOD}/{path}` | One resource (`{path}` is URL-encoded). |
| `element.json/authentication` | The authentication block. |
| `element.json/hooks` \| `element.json/parameters` | Global hooks / parameters arrays. |
| `standard-resources` | List standard-resource names. |
| `standard-resources/{name}` | A whole standard-resource file. |
| `standard-resources/{name}/fields` | List field names. |
| `standard-resources/{name}/fields/{field}` | One field object. |
| `standard-resources/{name}/metadata[/{key}]` | Metadata object, or a single metadata key. |
| `hooks` | List hook files. |
| `hooks/{file}` | One hook JS file. |
| `element-metadata.json` | The `element-metadata.json` object. |
| any other repo-relative path | Raw-file fallback. Read-only; JSON is pretty-printed. |

### Query → patch round-trip

`state query`'s output is designed to be fed straight back into `state patch --value` unmodified: read a slice with `query`, edit the resulting JSON, then `patch` the same pointer with `--value` set to the edited JSON (or write it to a file and use `--value-file`). This only works because `Value`'s keys are preserved verbatim (camelCase, on-disk casing) rather than PascalCased like the rest of this CLI's JSON output — re-casing the keys before patching will not round-trip correctly.

## Related

- [Overview & tenant lifecycle](./uip-is-connectors-builder.md) — concepts shared across all builder pages, plus `download`/`import`/`publish`/`publish-status`.
- [Init & connector](./uip-is-connectors-builder-init.md) — scaffold a connector, and the `inspect` structural rollup.
- [Auth](./uip-is-connectors-builder-auth.md) — configure the connector's authentication scheme.
- [Activity & hooks](./uip-is-connectors-builder-activity.md) — the activities a trigger attaches to.

## See also

- [Integration Service tool overview](./uip-is.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)