Skip to content
ArtificialFlow

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 carries X-Workflow-Engine-Protocol-Version.
  • GET /jobs/capabilities lists 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-lock before it expires. A lock-ownership error ends that activation.
  • gRPC JobWorkerService listens on the command process at GRPC_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 typeInputs
io.artificialflow.connector.httpurl, method, headers, body, timeoutMs, failOnNon2xx
io.artificialflow.connector.webhookwebhookUrl, payload, webhookToken
io.artificialflow.connector.kafkakafkaTopic, kafkaKey, kafkaValue
io.artificialflow.connector.emailemailTo, emailSubject, emailBody
io.artificialflow.connector.s3s3Bucket, 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.

FieldRequiredMeaning
urlyesAbsolute HTTP or HTTPS URL.
methodnoDefaults to POST.
headersnoObject of string headers, or a JSON object string. Count and size are bounded.
bodynoJSON-serializable body, or a JSON string.
timeoutMsnoDefaults to 10000.
failOnNon2xxnoDefaults 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, true when 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/http

Allow any host only on a workstation:

HTTP_CONNECTOR_ALLOW_ANY_HOST=true go run ./connectors/http

Build 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"