uip is connectors builder activity hook

Syntax and options for creating, reading, and managing JavaScript pre/post-request hooks on a connector's activities.

uip is connectors builder activity hook manages JavaScript transformation hooks — the connector's escape hatch for request/response logic that a declarative field or parameter can't express. It's a nested sub-group under activity, split onto its own page because of the amount of runtime-context documentation a hook author needs. See Connectors builder for the shared concepts (connector-directory resolution, the typical authoring flow) that apply here too.

Hook files live under app/element/hooks/ in the connector directory. A hook can attach to a specific resource+method (a resource hook) or run for every request (a global hook, --global).

Synopsis

uip is connectors builder activity hook list [--connector-dir <path>]
uip is connectors builder activity hook get <filename> [--connector-dir <path>]
uip is connectors builder activity hook create --hook-type <preRequest|postRequest> [options...] [--connector-dir <path>]
uip is connectors builder activity hook delete <filename> [--connector-dir <path>]

uip is connectors builder activity hook list

List the JavaScript hook files under app/element/hooks/ and whether each is referenced in element.json.

Options

Long	Value	Description
--connector-dir <path>	path	Connector directory.

Example

uip is connectors builder activity hook list

Data shape (--output json)

{
  "Code": "HookList",
  "Data": {
    "ConnectorRoot": "/work/periodic-design-acme",
    "Hooks": [
      { "filename": "resource-account-GET-postRequest.js", "registered": true }
    ]
  }
}

A hook file that exists on disk but has registered: false is orphaned — its code runs for nothing until it's re-registered (re-run hook create against it, or wire it manually into element.json).

uip is connectors builder activity hook get

Read a single hook file's source and registration status.

Arguments

Name	Required	Purpose
<filename>	yes	Hook filename, e.g. resource-account-GET-postRequest.js or global-preRequest.js.

Options

Long	Value	Description
--connector-dir <path>	path	Connector directory.

Example

uip is connectors builder activity hook get resource-account-GET-postRequest.js

Data shape (--output json)

{
  "Code": "Hook",
  "Data": {
    "ConnectorRoot": "/work/periodic-design-acme",
    "Filename": "resource-account-GET-postRequest.js",
    "Registered": true,
    "Code": "done({ response_body });"
  }
}

uip is connectors builder activity hook create

Create a JavaScript hook file and — unless --no-auto-register — register its reference in element.json.

Options

Long	Value	Required	Description
--resource-name <name>	string	conditionally*	Resource the hook attaches to. Not needed with --global.
--method <method>	string	conditionally*	HTTP method of the resource. Not needed with --global.
--path <internalPath>	string	no	Resource internal path (the unique element.json resource path), to disambiguate when a list resource and a by-id resource share a method (e.g. /contacts/{id}) — vendor paths aren't unique, the internal path is.
--hook-type <type>	preRequest|postRequest	yes	Hook phase.
--custom-code <js>	string	no**	The hook body, inline. Mutually exclusive with --custom-code-file.
--custom-code-file <path>	path	no**	Path to a .js file whose contents become the hook body. Preferred over --custom-code.
--description <text>	string	no	Comment placed at the top of the file.
--context-params <list>	string	no	Override the contextParams string on the hook reference.
--no-auto-register	flag	no	Write the file but do not register it in element.json.
--global	flag	no	Register a connector-wide hook in the top-level hooks[] array, instead of attaching to one resource+method.
--connector-dir <path>	path	no	Connector directory.

* Commander can't express "required unless --global" declaratively — both options are plain (not requiredOption), and the underlying service enforces the resource-hook case at runtime, failing if --resource-name/--method are missing on a non-global hook.

** Passing both --custom-code and --custom-code-file is an error. You write the hook body yourself (or have an agent write it) — the CLI only places and registers the file; it does not generate hook logic.

Hook body context

A hook returns through done({...}), never a bare return, and must call done() on every code path. The CLI auto-binds exactly the variables your body references; override the set with --context-params (list multipart_hook_context_items explicitly if you use it).

preRequest — read-only:

request_method, request_headers, request_path, request_path_variables, request_parameters, request_body, request_body_map (curated request body as a map — read fields directly), request_body_raw, request_vendor_body_map, request_vendor_url, request_expression (CEQL where, as [{attribute,value,operator}]), request_previous_response, request_previous_response_headers, object_name, vendor_object_name, configuration (read-only in this phase).

preRequest — read/write (edit, then return only the keys you changed; a bare done() passes everything through unmodified):

request_vendor_method, request_vendor_headers, request_vendor_path, request_vendor_parameters, request_vendor_body (a string on read; string, list, or map on write), request_root_key, multipart_hook_context_items.

preRequest — done()-only keys: continue (false skips the vendor call but still runs postRequest), response_status_code / response_body / response_body_raw / response_error_message (short-circuit a response without calling the vendor at all).

postRequest — read-only:

response_iserror (true unless the HTTP status is 200–207), response_body_map, response_body_raw_map, every request_* variable as actually sent to the vendor, request_previous_response, request_previous_response_headers.

postRequest — read/write (edit and return the changed keys):

response_body (map), response_body_raw (string), response_headers, response_status_code, response_root_key, configuration (writable in this phase — see below), multipart_hook_context_items.

postRequest — done()-only keys: response_error_message (converts the call to an error; status comes from response_status_code, else 400), connection_identity (set the connection's display name), metadata_merge / merge_objects (object-discovery resources only).

Key rules:

• configuration is read-only in preRequest, read/write in postRequest. To persist a derived per-connection value (e.g. a base URL computed from a token), write it in a postRequest hook: done({ configuration: { 'base.url': url } }). Writing configuration in preRequest has no effect.
• A request_vendor_path that starts with http becomes the full request URL, bypassing the connector's configured base URL.
• Success is strictly HTTP 200–207. response_iserror is derived and read-only — returning a different value for it does nothing.

Engine: the hook runtime (Denali) supports modern JavaScript (?., ??, async/await) and require() for a fixed module set: axios (for secondary HTTP calls from inside a hook), crypto, url, querystring, util, buffer, zlib, lodash, jmespath, moment.

For guidance on when (and when not) to reach for a hook instead of a declarative field/param, the CLI points to the uipath-connector-builder skill's references/hooks.md — see uip skills.

Examples

# Post-request hook for a resource, from an agent-written JS file
uip is connectors builder activity hook create \
  --resource-name Account --method GET --hook-type postRequest \
  --custom-code-file ./account-postRequest.js

# Global pre-request hook
uip is connectors builder activity hook create \
  --hook-type preRequest --global --custom-code-file ./my-hook.js

Data shape (--output json)

{
  "Code": "HookCreated",
  "Data": {
    "ConnectorRoot": "/work/periodic-design-acme",
    "Filename": "resource-Account-GET-postRequest.js",
    "HookType": "postRequest",
    "Method": "GET",
    "ResourceName": "Account",
    "FilePath": "app/element/hooks/resource-Account-GET-postRequest.js",
    "HookReference": {},
    "RegisteredInElement": true
  }
}

For a global hook, Filename follows the global-<hookType>.js pattern (e.g. global-preRequest.js) and ResourceName/Method are absent.

uip is connectors builder activity hook delete

Delete a hook file and strip every reference to it from element.json.

Arguments

Name	Required	Purpose
<filename>	yes	Hook filename to delete.

Options

Long	Value	Description
--connector-dir <path>	path	Connector directory.

There is no dedicated "edit a hook" verb — delete and re-create, or edit the file on disk directly (a hook file is plain JavaScript, not a generated artifact).

Example

uip is connectors builder activity hook delete resource-account-GET-postRequest.js

Data shape (--output json)

{
  "Code": "HookRemoved",
  "Data": {
    "ConnectorRoot": "/work/periodic-design-acme",
    "Filename": "resource-account-GET-postRequest.js",
    "FileDeleted": true,
    "ReferenceRemoved": true
  }
}

Related

• Activity — the resource/field/method/param commands a hook attaches to.
• Connectors builder — concepts and the four tenant-lifecycle verbs.
• Auth — configure the connector's authentication scheme.
• Trigger & state — event triggers and low-level element-file edits.

See also

• Integration Service tool overview
• Global options
• Exit codes