HTTP

The HTTP task is used to make calls to remote services exposed over HTTP/HTTPS. It supports various HTTP methods, headers, body content, and other configurations needed for interacting with APIs or remote services.

The HTTP task evaluates the parameters provided, constructs the HTTP request accordingly, and sends it to the specified URI. It handles the response by extracting useful information, such as the status code, headers, and body content, which can be used in subsequent tasks within the workflow.

Task parameters

Configure these parameters for the HTTP task.

Parameter	Description	Required/ Optional
inputParameters.uri	The URI for the service. It can be a partial value when using vipAddress or it can be the server address.	Required.
inputParameters.method	The HTTP method. Supported methods: GET HEAD POST PUT PATCH DELETE OPTIONS TRACE	Required.
inputParameters.accept	The accept header required by the server. The default value is application/json. Supported types: application/java-archive application/EDI-X12 application/EDIFACT application/javascript application/octet-stream application/ogg application/pdf application/xhtml+xml application/x-shockwave-flash application/json application/ld+json application/xml application/zip application/x-www-form-urlencoded audio/mpeg audio/x-ms-wma audio/vnd.rn-realaudio audio/x-wav image/gif image/jpeg image/png image/tiff image/vnd.microsoft.icon image/x-icon image/vnd.djvu image/svg+xml Any other headers can be passed as a dynamic variable.	Optional.
inputParameters.contentType	The content type for the server. The default value is application/json. Supported types: application/java-archive application/EDI-X12 application/EDIFACT application/javascript application/octet-stream application/ogg application/pdf application/xhtml+xml application/x-shockwave-flash application/json application/ld+json application/xml application/zip application/x-www-form-urlencoded audio/mpeg audio/x-ms-wma audio/vnd.rn-realaudio audio/x-wav image/gif image/jpeg image/png image/tiff image/vnd.microsoft.icon image/x-icon image/vnd.djvu image/svg+xml It can be passed as a dynamic variable.	Optional.
inputParameters.hedgingConfig.maxAttempts	The maximum number of parallel requests to send. The system will use the response from the first successful attempt, helping reduce tail latencies in remote services. Note: Hedging makes parallel requests, so use it only for idempotent services.	Optional.
inputParameters.headers	A map of additional HTTP headers to be sent along with the request. Supported types: Accept-Language Authorization Cache Control Content-MD5 From If-Match If-Modified-Since If-None-Match Max-Forwards Pragma If-Range If-Unmodified-Since Proxy-Authorization Range Warning x-api-key Accept-Charset Accept-Encoding Accept-Control-Request-Headers Accept-Control-Request-Method Content-Transfer-Encoding Expect Transfer-Encoding Trailer	Optional.
inputParameters.body	The request body for POST, PUT, or PATCH methods. Can be text or parameters such as string, number, boolean, null, or object/array.	Required for POST, PUT, or PATCH.
inputParameters.encode	Determines whether the URI needs encoding. When set to true, the Conductor will automatically encode the query parameters before sending the HTTP request. Set this to false if the URI is already encoded. The default value is true.	Optional.

The following are generic configuration parameters that can be applied to the task and are not specific to the HTTP task.

Caching parameters

You can cache the task outputs using the following parameters. Refer to Caching Task Outputs for a full guide.

Parameter	Description	Required/ Optional
cacheConfig.ttlInSecond	The time to live in seconds, which is the duration for the output to be cached.	Required if using cacheConfig.
cacheConfig.key	The cache key is a unique identifier for the cached output and must be constructed exclusively from the task’s input parameters. It can be a string concatenation that contains the task’s input keys, such as ${uri}-${method} or re_${uri}_${method}.	Required if using cacheConfig.

Schema parameters

You can enforce input/output validation for the task using the following parameters. Refer to Schema Validation for a full guide.

Parameter	Description	Required/ Optional
taskDefinition.enforceSchema	Whether to enforce schema validation for task inputs/outputs. Set to true to enable validation.	Optional.
taskDefinition.inputSchema	The name and type of the input schema to be associated with the task.	Required if enforceSchema is set to true.
taskDefinition.outputSchema	The name and type of the output schema to be associated with the task.	Required if enforceSchema is set to true.

Other generic parameters

Here are other parameters for configuring the task behavior.

Parameter	Description	Required/ Optional
optional	Whether the task is optional. If set totrue, any task failure is ignored, and the workflow continues with the task status updated to COMPLETED_WITH_ERRORS. However, the task must reach a terminal state. If the task remains incomplete, the workflow waits until it reaches a terminal state before proceeding.	Optional.
asyncComplete	Whether the task is completed asynchronously. The default value is false. false—Task status is set to COMPLETED upon successful execution. true—Task status is kept as IN_PROGRESS until an external event marks it as complete.	Optional.

Task configuration

This is the task configuration for an HTTP task.

{
     "name": "http",
     "taskReferenceName": "http_ref",
     "type": "HTTP",
     "inputParameters": {
       "uri": "https://orkes-api-tester.orkesconductor.com/api",
       "method": "GET",
       "accept": "application/json",
       "contentType": "application/json",
       "encode": true,
       "hedgingConfig": {
         "maxAttempts": 4
       },
       "headers": {
         "header-1": "${workflow.input.header-1}"
       }
     }
}

Task output

The HTTP task will return the following parameters.

Parameter	Description
response	A JSON object representing the response, if present.
headers	An object containing the metadata about the response.
statusCode	The HTTP status code indicating success or failure of the request.
reasonPhrase	The reason phrase associated with the HTTP status code.
body	The response body containing the data returned by the API.

Adding an HTTP task in UI

An HTTP task can be configured manually through the UI or automatically populated using registered service definitions.

Using registered services

Prerequisites

Register the remote service in Orkes Conductor.

To add an HTTP task using registered services:

1. In your workflow, select the (+) icon and add an HTTP task.
2. Select Populate from remote services.
3. In Service, select the registered HTTP service.
4. In Host, select the required host for the service.
5. In Service method, select the required endpoint.
6. Select Populate.
7. (Optional) In Hedging Config > Maximum attempts, enter a value for parallel hedged requests to reduce latency.

This method automatically fills in the HTTP task parameters based on the selected service. It is recommended if you have already registered your HTTP services in Orkes Conductor.

Manually configuring an HTTP tasks

To add an HTTP task:

1. In your workflow, select the (+) icon and add an HTTP task.
2. Choose the HTTP method for sending requests from the Method drop-down.
3. In URL, add the URI to be called by the HTTP task.
4. In Accept, select the accept header as required by the server.
5. In Content-Type, select the content type for the server.
6. (Optional) Enable or disable Encode to specify if the URI needs to be encoded.
7. (Optional) In Hedging Config > Maximum attempts, enter a value for parallel hedged requests to reduce latency.
8. (Optional) In Additional headers, add any additional HTTP headers to be sent along with the request.
9. In Body, add the request body when using PUT, POST, or PATCH method.
10. (Optional) Set Async complete to true if the task is to be completed asynchronously.

Examples

Here are some examples for using the HTTP task.

Sending an HTTP POST request

This example creates a workflow that sends an HTTP POST request to a public test API and returns the created resource in the task output.

To create a workflow:

1. Go to Definitions > Workflow, from the left navigation menu on your Conductor cluster.
2. Select + Define workflow.
3. In the Code tab, paste the following workflow definition:

{
  "name": "http_post_end_to_end_example",
  "description": "Sends an HTTP POST request and returns the response body",
  "version": 1,
  "tasks": [
    {
      "name": "http",
      "taskReferenceName": "post_request",
      "type": "HTTP",
      "inputParameters": {
        "uri": "https://jsonplaceholder.typicode.com/posts",
        "method": "POST",
        "accept": "application/json",
        "contentType": "application/json",
        "headers": {
          "x-source": "orkes-conductor"
        },
        "body": {
          "title": "Sample post created by Conductor",
          "body": "This payload was sent by an HTTP task.",
          "userId": 1
        }
      }
    }
  ],
  "outputParameters": {
    "createdPost": "${post_request.output.response.body}",
    "statusCode": "${post_request.output.statusCode}"
  },
  "schemaVersion": 2
}

4. Select Save > Confirm.
5. Select Execute to run the workflow.

This takes you to the workflow execution page, where you can inspect the task output and workflow output.

Use asyncComplete to complete an HTTP task asynchronously

The asyncComplete parameter allows an HTTP task to be completed asynchronously. When enabled, the task remains in progress until an external signal marks it as completed.

This example shows how to pause a workflow after an HTTP task starts and resume it later using asynchronous completion.

In this example, you’ll build a workflow that:

• Executes an HTTP request
• Pauses execution using asyncComplete
• Resumes only when an external signal marks the task as completed

To create a workflow:

1. Go to Definitions > Workflow, from the left navigation menu on your Conductor cluster.
2. Select + Define workflow.
3. In the Code tab, paste the following workflow definition:

{
 "name": "async_complete_example",
 "description": "Edit or extend this sample workflow. Set the workflow name to get started",
 "version": 1,
 "tasks": [
   {
     "name": "http_task_85tf2",
     "taskReferenceName": "http_task_85tf2_ref",
     "inputParameters": {
         "uri": "https://orkes-api-tester.orkesconductor.com/api",
         "method": "GET",
         "connectionTimeOut": 3000,
         "readTimeOut": "3000",
         "accept": "application/json",
         "contentType": "application/json"
     },
     "type": "HTTP",
     "asyncComplete": true
   }
 ],
 "schemaVersion": 2
}

4. Save the workflow.
5. Select Execute to run the workflow.

Upon execution, the HTTP task remains “In Progress” instead of completing immediately, allowing for asynchronous completion. The task can be completed using various methods:

Method 1: Complete the task using API

1. From the workflow execution page, copy the workflow ID and task reference name.

2. Use this workflowId along with the taskRefName to complete the task using the Update Task Status in a Workflow API.

POST /api/tasks/{workflowId}/{taskRefName}/{status}

Example Request

curl -X 'POST' \
  'https://developer.orkescloud.com/api/tasks/0cc5dd20-e49d-11f0-a0ca-c60c4ebc4813/http_task_85tf2_ref/COMPLETED' \
  -H 'accept: text/plain' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Response

0cc73cb9-e49d-11f0-a0ca-c60c4ebc4813

This API call marks the task as completed, allowing the workflow to finish its execution.

Method 2: Complete the task using API Conductor UI

Alternatively, you can complete the task manually using Conductor UI.

1. Open the workflow execution.
2. Select the HTTP task.
3. Update the status to COMPLETED.

These methods allow you to asynchronously complete your workflow, which is beneficial when pausing the workflow for external interventions.

Orchestrating long-running APIs

Explore the full tutorial on orchestrating long-running APIs.