application-integration-authoring

Files (6)

• SKILL.md
• cicd-promotion.md · references/
• integration-version-json.md · references/
• rest-api-cheatsheet.md · references/
• tasks-and-gotchas.md · references/
• triggers-and-execution.md · references/

SKILL.md (first lines)

# Application Integration Authoring

Google Cloud Application Integration workflows are authored, versioned, published, and executed programmatically through the REST API (`https://integrations.googleapis.com/v1/...`) or the discovery-based Google API Python client (`googleapiclient.discovery.build("integrations", "v1")`).

There is no `gcloud integrations` command group, no Google-managed MCP server for Application Integration, and no documented Terraform resource for integrations or versions. Use `gcloud` only for authentication, enabling APIs, and IAM bindings. Use Terraform only for region provisioning (`google_integrations_client`), authentication profiles (`google_integrations_auth_config`), and Integration Connectors (`google_integration_connectors_connection`).

For initial project setup, region provisioning, and IAM role definitions, use the `application-integration-basics` skill. For diagnosing failed or stuck runs, execution logs, and quota errors, use the `application-integration-troubleshooting` skill.

## Attribution

**MUST READ**: Before executing any `gcloud` command, REST API call, or Python
discovery-client call, you MUST read
[Usage Attribution](references/attribution.md). For commands executed directly
in the terminal (never in generated scripts, Terraform, ADK agents, or user
code), prefix `gcloud` with
`CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:application-integration-authoring)"`
and add `agent-skills/1.0 (skill:application-integration-authoring)` to the
`User-Agent` header of `curl` requests.

## Safety and Confirmation Rules

- **Read-only operations run freely**: `integrations.list`, `integrations:search`, `versions.list`, `versions.get`, `versions:download`, `authConfigs.list`, and `executions.list`.
- **Confirm before any state change or execution**: Before creating, uploading, patching, publishing, unpublishing, testing, executing, scheduling, or deleting an integration or version, or modifying IAM or auth configs, show the exact command and payload to the user and get explicit confirmation.
- **Host changes require approval.** Before installing packages (`pip install`) or changing global gcloud or credential state (`gcloud config set ...` such as `auth/impersonate_service_account`, `gcloud auth application-default login` / `set-quota-project`), show the exact command and wait for the user's approval.
- **Never store secrets in config variables**: Config variables (`CONFIG_*`) are stored and exported in plain text. Always use authentication profiles (`projects.locations.authConfigs`) or the Secret Manager access task for credentials.

## Prerequisites Checklist

1. **Install Google Cloud SDK**: Follow [Install the gcloud CLI](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt) if `gcloud` is not installed.
2. **Billing and project**: Ensure the Google Cloud project has an active billing account attached (required even when usage stays within the free tier), then set the target project (changes global gcloud state; get the user's approval first):
   ```bash
   gcloud config set project PROJECT_ID
   ```
3. **Enable required APIs**:
   ```bash
   gcloud services enable integrations.googleapis.com connectors.googleapis.com secretmanager.googleapis.com
   ```
4. **Provision the region**: Application Integration is regional: confirm the target region is supported on [Application Integration locations](https://docs.cloud.google.com/application-integration/docs/locations.md.txt) and use `us-central1` as a well-supported default when the user has no preference. The region is the `LOCATION` in every REST path; no `gcloud` default-region setting applies to Application Integration. The target `LOCATION` must be provisioned via the Cloud console or `POST .../clients:provision` before authoring integrations (see `application-integration-basics`).
5. **Authenticate**:
   - For `curl`: run `gcloud auth login` (changes host or credential state; get the user's approval first) and pass `-H "Authorization: Bearer $(gcloud auth print-access-token)"`.
   - For the Python client (install with `pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"`): run `gcloud auth application-default login` and `gcloud auth application-default set-quota-project PROJECT_ID` (or set `GOOGLE_APPLICATION_CREDENTIALS` for a service account) (changes host or credential state; get the user's approval first).
   - For service account impersonation: run `gcloud config set auth/impersonate_service_account SA_EMAIL` (requires `roles/iam.serviceAccountTokenCreator`) (changes host or credential state; get the user's approval first).
6. **Verify IAM roles**:
   - Create, upload, or edit drafts: `roles/integrations.integrationEditor` (covers `versions:upload`, which needs `integrations.integrationVersions.create`, and `versions:publish`)
   - Publish or unpublish: `roles/integrations.integrationDeployer` or `roles/integrations.integrationEditor` (`roles/integrations.integrationDeployer` alone can publish an existing version but cannot upload via `versions:upload`), plus `roles/integrations.serviceAgent` granted to the Application Integration service agent (`service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com`)
   - Invoke integrations: `roles/integrations.integrationInvoker`
   - Act as the run-as service account: integrations created on or after October 15, 2026 with any trigger other than an API or Private trigger (for example Schedule, Cloud Scheduler, Cloud Pub/Sub, Salesforce, or Connector Event; Private triggers are exempt like API triggers, so a sub-integration whose only trigger is Private can be published without `runAsServiceAccount`) cannot be tested or published unless `runAsServiceAccount` is set (and region governance requires it for all integrations); whenever `runAsServiceAccount` is set, the user publishing or testing the version needs `roles/iam.serviceAccountUser` on it (and at runtime, the invoking caller or trigger service account needs `roles/iam.serviceAccountUser` on it).

## Decision Flow

| Goal | Action | Endpoint / Method |
| :--- | :--- | :--- |
| Inspect existing integrations in a region | List integrations, then list versions | `GET .../integrations` then `GET .../versions` |
| Export an integration version to source control | Download version JSON | `GET .../versions/VERSION_ID:download?fileFormat=JSON` |
| Create an integration or add a new `DRAFT` version from JSON | Upload version JSON (creates the integration if it does not exist, or adds a new `DRAFT` version; still needs `:publish`) | `POST .../integrations/INTEGRATION_NAME/versions:upload` |
| Create a brand-new integration and fail on a name clash | Create first `DRAFT` version with `newIntegration=true` (returns `ALREADY_EXISTS` if `INTEGRATION_NAME` already exists) | `POST .../integrations/INTEGRATION_NAME/versions?newIntegration=true` |
| Edit an existing `DRAFT` version | Check `lockHolder`, then patch or upload | `PATCH .../versions/VERSION_ID?updateMask=...` |
| Edit an `ACTIVE` (published) integration | Upload or create a new `DRAFT` version | `POST .../integrations/INTEGRATION_NAME/versions:upload` |
| Externalize environment-specific URLs or IDs | Define `CONFIG_<NAME>` and supply at publish | `integrationConfigParameters` + `versions:publish` |
| Store API keys, OAuth credentials, or certs | Create an authentication profile | `POST .../authConfigs` |
| Test an integration before production | Publish to a non-production project and invoke `:execute` | `POST .../versions/VERSION_ID:publish` then `POST .../integrations/INTEGRATION_NAME:execute` |
| Deploy a `DRAFT` to serve live traffic | Publish version with `configParameters` | `POST .../versions/VERSION_ID:publish` |
| Invoke a published integration synchronously | Call `:execute` with `api_trigger/TRIGGER_NAME` | `POST .../integrations/INTEGRATION_NAME:execute` |
| Invoke a published integration asynchronously | Call `:schedule` with `scheduleTime` | `POST .../integrations/INTEGRATION_NAME:schedule` |
| Promote a version across projects (CI/CD) | Download JSON -> Upload to target -> Publish | `:download` -> `:upload` -> `:publish` |

See [references/rest-api-cheatsheet.md](references/rest-api-cheatsheet.md) for full request parameters, query filters, and IAM permissions for each method.

## Core Authoring Workflow

### 1. List Integrations and Download a Version

List integrations in `LOCATION` and list versions for a specific `INTEGRATION_NAME`:

```bash
TOKEN="$(gcloud auth print-access-token)"

# List integrations in the region
curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations?pageSize=50"

# List versions (ordered by most recently modified)
curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions?orderBy=last_modified_time%20desc"
```

Download a specific version (`VERSION_ID` is the UUID at the end of the version's `name` field) as portable JSON:

```bash
curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions/VERSION_ID:download?fileFormat=JSON" \
  | jq -r '.content' > integration-version.json
```

### 2. Understand the `IntegrationVersion` Structure

An `IntegrationVersion` JSON object contains four primary arrays and version-level settings:

- `triggerConfigs`: Entry points that start the workflow. Each entry requires a unique `triggerNumber`, plus `triggerType` (such as `API` or `PRIVATE_TRIGGER`), optional `triggerId` (auto-generated from `properties` if omitted; for API triggers: `api_trigger/TRIGGER_NAME`), and `startTasks` pointing to the first `taskId`.
- `taskConfigs`: Units of work. Each entry needs `task` (the task type, such as `EmailTask` in the public upload sample, or `FieldMappingTask` in a discovery enum description), a unique `taskId`, `parameters`, `nextTasks`, and optional `failurePolicy` or `errorCatcherId`.
- `integrationParameters`: Input, output, and transient variables (`key`, `dataType` such as `STRING_VALUE` or `JSON_VALUE`, `inputOutputType` of `IN`, `OUT`, `IN_OUT`, or `IN_OUT_TYPE_UNSPECIFIED`, and `defaultValue`).
- `integrationConfigParameters`: Environment-specific config variable definitions (`parameter` with key `` `CONFIG_<NAME>` `` and `parameter.defaultValue`; a top-level `value` in uploaded or created draft JSON is discarded, so per-environment values go in `configParameters` at publish).
- `runAsServiceAccount`: Dedicated user-managed service account email. When set and no authentication profile (`authConfig`) is configured on the task, it is used to generate the auth token for Connector (`Connectors`), REST (`Call REST Endpoint`), and Cloud Function tasks; an authentication profile configured on the task takes precedence over `runAsServiceAccount`.

Always use `triggerConfigs`, `taskConfigs`, and `integrationParameters`. Never use `triggerConfigsInternal`, `taskConfigsInternal`, or `integrationParametersInternal` because they are deprecated. See [references/integration-version-json.md](references/integration-version-json.md) for field schemas, `ValueType` shapes, and a minimal `IntegrationVersion` JSON template.

### 3. Create or Upload a `DRAFT` Version

Each integration allows up to 100 versions and 100 tasks, and `INTEGRATION_NAME` can be at most 64 characters. Calling `versions:upload` creates a new `DRAFT` version—creating the integration automatically if `INTEGRATION_NAME` does not exist yet, or adding the next `DRAFT` version if it already exists (for example, uploading onto version 5 creates version 6). The uploaded version is in `DRAFT` state and still requires `versions:publish` to serve traffic. Use `POST .../versions?newIntegration=true` (passing an `IntegrationVersion` JSON body) only when you explicitly want the call to fail with `ALREADY_EXISTS` if `INTEGRATION_NAME` already exists.

```bash
# Upload integration-version.json as a new DRAFT version
PAYLOAD="$(jq -n --rawfile content integration-version.json '{content: $content, fileFormat: "JSON"}')"

curl -sS --fail-with-body -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "${PAYLOAD}" \
  "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/INTEGRATION_NAME/versions:upload"

From google/skills, Apache-2.0.

More from google/skills