Workers
Service tasks, send tasks, and connectors become external jobs. A worker activates a job, does the work, then completes or fails it.
Contract
- Send
X-Workflow-Worker-Protocol-Version: v1. The response carriesX-Workflow-Engine-Protocol-Version. GET /jobs/capabilitieslists the worker features this server supports.- Activate with
POST /jobs/activate. Complete, fail, and extend the lock at/jobs/{key}/complete,/fail, and/extend-lock. - Mutation calls send
Idempotency-Key, at most 128 characters. Complete, fail, and extend-lock each use a distinct key, even on the same job. A retry of the same operation reuses that key and replays the accepted result. The scope is the operation plus the job key. - If the work can outlast the lock, call
extend-lockbefore it expires. A lock-ownership error ends that activation. - gRPC
JobWorkerServicelistens on the command process atGRPC_ADDR, default:50051. The gateway does not publish it. Use HTTP/jobs/*unless you control the pod network.
With IAM_DEPLOYMENT_MODE=true the caller needs artificialflowclient. With false the API accepts the call with no token. Full SDKs that include a worker are Node.js, .NET, and Java. Worker-only clients are Python and Go. make worker-conformance is the wire check for /jobs/*.
Connectors
Set artificialflow:taskType on a service or send task. The modeler properties panel lists the official types. For the HTTP connector, put inputs on the task as artificialflow:property name and value pairs, or pass the same names when the process starts. At job creation the engine copies a known connector key into the instance context only when that key is not already set, so start variables win over the diagram.
| Job type | Inputs |
|---|---|
io.artificialflow.connector.http | url, method, headers, body, timeoutMs, failOnNon2xx |
io.artificialflow.connector.webhook | webhookUrl, payload, webhookToken |
io.artificialflow.connector.kafka | kafkaTopic, kafkaKey, kafkaValue |
io.artificialflow.connector.email | emailTo, emailSubject, emailBody |
io.artificialflow.connector.s3 | s3Bucket, s3Key, s3Body, contentType |
HTTP connector
Job type io.artificialflow.connector.http. The worker in connectors/http calls the URL and writes the response back onto the instance.
| Field | Required | Meaning |
|---|---|---|
url | yes | Absolute HTTP or HTTPS URL. |
method | no | Defaults to POST. |
headers | no | Object of string headers, or a JSON object string. Count and size are bounded. |
body | no | JSON-serializable body, or a JSON string. |
timeoutMs | no | Defaults to 10000. |
failOnNon2xx | no | Defaults to true. A non-2xx response fails the job. |
The completed job sets three variables:
httpStatus, the response status code.httpBody, the response body as a string, truncated.httpOk,truewhen the status is 2xx.
Outbound calls stay on an allowlist. HTTP_CONNECTOR_ALLOWED_HOSTS is a comma-separated host list and is required. HTTP_CONNECTOR_ALLOW_ANY_HOST defaults to false; set it to true only for a local evaluation. An empty allowlist without that switch fails at startup. Redirects are checked again, and the new host must still be allowed. When the instance does not set failOnNon2xx, HTTP_CONNECTOR_FAIL_ON_NON_2XX applies and defaults to true.
Pass ARTIFICIALFLOW_TOKEN when IAM is enabled. The token needs artificialflowclient.
export ARTIFICIALFLOW_BASE_URL=http://localhost:9100/api
export ARTIFICIALFLOW_TOKEN=...
export HTTP_CONNECTOR_ALLOWED_HOSTS=api.example.com
go run ./connectors/httpAllow any host only on a workstation:
HTTP_CONNECTOR_ALLOW_ANY_HOST=true go run ./connectors/httpBuild the connector image from the product repository:
docker build -f connectors/http/Dockerfile -t artificialflow-http-connector .The email, Kafka, webhook, and S3 connectors ship beside the HTTP connector. Each one is an external worker in connectors/. The webhook connector also re-checks redirect targets against its allowlist.
curl -fsS http://localhost:9100/api/jobs/capabilities \
-H "Authorization: Bearer $ARTIFICIALFLOW_TOKEN" \
-H "X-Workflow-Worker-Protocol-Version: v1"