bulk_dml
Destructive
Insert, update, upsert, delete, or hard-delete large Salesforce record sets via Bulk API 2.0 ingest jobs. Use this instead of sobject_dml when processing more than ~200 records. Pass records/recordIds to upload inline, or omit them to open a job so the user can upload a CSV from an in-chat control or a simple upload page (the file never goes through the chat). The tool waits up to 90 seconds; if the job is still running it returns a jobId you can pass back to wait or abort.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| abort | No | When true, abort the ingest job identified by `jobId`. Requires `jobId`. | |
| jobId | No | Existing ingest job ID or Cirra CSV upload handle (`bih_…`). Pass this to wait for a previously submitted job or to abort it. When set, `records` are ignored. If the handle is still waiting for a CSV, the response repeats the upload URL instead of creating a Salesforce job. | |
| records | No | Records to ingest. For update the records must include `Id`. For upsert they must include the external ID field. For delete/hardDelete you may pass records with `Id` instead of `recordIds`. Omit `records` and `recordIds` (with `operation` + `sObject`) to open a job so the user can upload a CSV from chat or a browser page (bypasses the LLM). | |
| sObject | No | API name of the sObject. Required to start a new job. | |
| sf_user | No | (optional) Salesforce username to identify the connection to use. Omit this to use the current default connection. | |
| pageSize | No | (optional) Maximum number of records to return per page when the response requires pagination, including the first page. If omitted, the first page is a short preview and later pages use an automatically calculated size. | |
| operation | No | Ingest operation. Required to start a new job. Always ask for explicit user approval before executing, and do not proceed without it. hardDelete permanently removes records (they skip the Recycle Bin) and requires the Bulk API Hard Delete permission. | |
| recordIds | No | Record IDs for delete or hardDelete. Takes precedence over `records` for those operations. | |
| cirra_ai_team | No | (optional) Cirra team ID or name that owns the Salesforce connection to use for this call. Must be provided together with 'sf_user'. Use it to run against a specific team's connection without changing your default team — e.g. to keep separate chats on Salesforce orgs in different teams. Omit it when this call carries the context_handle from cirra_ai_init, which names the team for the conversation. A user with more than one place to work (several teams, or a team and a personal account) must pass either the context_handle or 'cirra_ai_team' + 'sf_user'. | |
| context_handle | No | (recommended) The conversation context handle returned by cirra_ai_init in this conversation. Pass the exact context_handle value from the most recent cirra_ai_init result so this call runs against the team and Salesforce connection selected for this conversation. A user with more than one place to work (several Cirra AI teams, or a team and a personal account) must pass either this handle or 'cirra_ai_team' + 'sf_user'; a call with neither is refused. | |
| externalIdField | No | External ID field API name. Required for upsert, ignored otherwise. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ui | No | What the in-chat control should render. `csv_upload` is the only kind that needs a file picker. | |
| jobId | No | ||
| state | No | ||
| message | Yes | ||
| results | No | ||
| sObject | No | ||
| success | Yes | ||
| warning | No | ||
| timedOut | No | ||
| csvUpload | No | ||
| errorCode | No | ||
| operation | No | ||
| errorCount | No | ||
| resultCount | No | ||
| artifactType | No | ||
| instructions | No | ||
| requestCount | No | ||
| skippedCount | No | ||
| successCount | No | ||
| schemaVersion | No | ||
| salesforceJobId | No | ||
| artifactCategory | No | ||
| awaitingCsvUpload | No |