Job Executor -- Steps API

Steps are the building blocks of a job. Each step represents a single action in an automation workflow -- sending an email, querying a database, calling an API, and so on. Steps are executed sequentially in the order defined by the job.

Base URL: http://localhost:9000

Prefix: /step

Endpoints

Method	Path	Description	Authority
POST	/step/upsert	Create or update steps (batch)	JobExecutor:Step:upsert
GET	/step/\{id\}	Get step by ID	JobExecutor:Step:read
GET	/step/all	Get all steps	--
GET	/step/job/\{jobId\}	Get all steps for a job	JobExecutor:Step:read
DELETE	/step	Delete steps by IDs (batch)	JobExecutor:Step:delete
POST	/step/search	Search steps with filters	--
GET	/step/\{path\}/exists	Check if a step path exists	--
POST	/step/\{stepId\}/pin	Pin/unpin step output	--

---

POST /step/upsert

Create or update one or more steps. Accepts an array, allowing batch upsert of all steps in a job in a single call.

If a step has an actionType of schedule and category of trigger, the endpoint also creates or updates the corresponding Temporal schedule.

Request body:

[
  {
    "jobId": "job-abc-123",
    "name": "Query Sales Data",
    "order": 1,
    "actionType": "database-query",
    "category": "database",
    "description": "Execute SQL query against the data warehouse.",
    "enabled": true,
    "config": {
      "connectionId": "conn-dw-001",
      "query": "SELECT region, product, SUM(revenue) FROM sales WHERE month = :month GROUP BY region, product",
      "parameters": {
        "month": "{{reportMonth}}"
      }
    }
  },
  {
    "jobId": "job-abc-123",
    "name": "Send Email",
    "order": 2,
    "actionType": "send-email",
    "category": "communication",
    "description": "Email the results to finance.",
    "enabled": true,
    "config": {
      "connectionId": "conn-email-001",
      "to": ["finance@example.com"],
      "subject": "Monthly Sales Report - {{reportMonth}}",
      "body": "Please find the sales report attached.",
      "attachPreviousStepOutput": true
    }
  }
]

Response:

{
  "status": "success",
  "message": "Steps upserted successfully",
  "data": [
    {
      "id": "step-001",
      "jobId": "job-abc-123",
      "name": "Query Sales Data",
      "order": 1,
      "actionType": "database-query",
      "category": "database",
      "enabled": true
    },
    {
      "id": "step-002",
      "jobId": "job-abc-123",
      "name": "Send Email",
      "order": 2,
      "actionType": "send-email",
      "category": "communication",
      "enabled": true
    }
  ]
}

---

GET /step/{id}

Get a single step by its unique ID.

Example:

curl http://localhost:9000/step/step-001

Response:

{
  "status": "success",
  "message": "Step fetched successfully",
  "data": {
    "id": "step-001",
    "jobId": "job-abc-123",
    "name": "Query Sales Data",
    "order": 1,
    "actionType": "database-query",
    "category": "database",
    "description": "Execute SQL query against the data warehouse.",
    "enabled": true,
    "config": {
      "connectionId": "conn-dw-001",
      "query": "SELECT region, product, SUM(revenue) FROM sales WHERE month = :month GROUP BY region, product"
    }
  }
}

---

GET /step/job/{jobId}

Get all steps belonging to a specific job, ordered by their order field.

Example:

curl http://localhost:9000/step/job/job-abc-123

Response:

{
  "status": "success",
  "message": "Steps for job fetched successfully",
  "data": [
    {
      "id": "step-001",
      "jobId": "job-abc-123",
      "name": "Query Sales Data",
      "order": 1,
      "actionType": "database-query",
      "category": "database"
    },
    {
      "id": "step-002",
      "jobId": "job-abc-123",
      "name": "Send Email",
      "order": 2,
      "actionType": "send-email",
      "category": "communication"
    }
  ]
}

---

DELETE /step

Delete one or more steps by their IDs. Accepts a JSON array of step IDs in the request body.

Request body:

["step-001", "step-002"]

Response: 204 No Content

If the request body is empty or null, the endpoint returns 400 Bad Request.

---

POST /step/search

Search steps with pagination, sorting, and column-level filtering. Uses the same FilterRequest structure as the Jobs search endpoint.

Request body:

{
  "page": 0,
  "size": 20,
  "sortBy": "order",
  "sortOrder": "asc",
  "searchText": "email",
  "filters": {
    "category": {
      "operator": "and",
      "constraints": [
        { "value": "communication", "matchMode": "equals" }
      ]
    },
    "actionType": {
      "operator": "and",
      "constraints": [
        { "value": "send-email", "matchMode": "equals" }
      ]
    }
  }
}

Response:

{
  "status": "Success",
  "message": "Steps fetched successfully",
  "data": [
    {
      "id": "step-002",
      "jobId": "job-abc-123",
      "name": "Send Email",
      "actionType": "send-email",
      "category": "communication"
    }
  ],
  "meta": {
    "totalElements": 1,
    "page": 0,
    "size": 20
  }
}

---

POST /step/{stepId}/pin

Pin or unpin a step's output data. When pinned, the step uses the pinned data instead of executing normally. This is useful for testing downstream steps without re-executing expensive upstream steps.

Request body:

{
  "pinnedData": {
    "rowCount": 1547,
    "columns": ["region", "product", "revenue"]
  },
  "pinEnabled": true
}

Response:

{
  "status": "success",
  "message": "Step pinned",
  "data": {
    "id": "step-001",
    "jobId": "job-abc-123",
    "name": "Query Sales Data",
    "pinEnabled": true,
    "pinnedData": {
      "rowCount": 1547,
      "columns": ["region", "product", "revenue"]
    }
  }
}

To unpin, send the same request with "pinEnabled": false.

---

Step Fields Reference

Field	Type	Description
id	string	Unique step identifier. Auto-generated on creation.
jobId	string	The parent job ID.
name	string	Human-readable step name.
order	integer	Execution order within the job (1-based).
actionType	string	The action the step performs (e.g., send-email, database-query, api-call, ssh-command). Maps to a plugin.
category	string	Step category (e.g., communication, database, api, protocol, utility, trigger).
description	string	Human-readable description.
enabled	boolean	Whether the step is active. Disabled steps are skipped during execution.
config	object	Step-specific configuration. Schema depends on the actionType.
pinEnabled	boolean	Whether the step output is pinned.
pinnedData	object	The pinned output data, used when pinEnabled is true.

Common Action Types

actionType	Category	Plugin	Description
send-email	communication	plugin-email	Send email via SMTP
database-query	database	plugin-database	Execute SQL query
api-call	api	plugin-api	Make HTTP API request
ssh-command	protocol	plugin-ssh	Execute remote SSH command
sftp-transfer	protocol	plugin-sftp	Transfer files via SFTP
s3-operation	cloud	plugin-aws-s3	AWS S3 operations
slack-message	communication	plugin-slack	Send Slack message
schedule	trigger	--	Cron-based schedule trigger