---
title: "Service Tasks — Spiff Arena 0.1 documentation"
description: "A Service Task in SpiffWorkflow is an automated task type that interacts with external services or systems. Unlike manual tasks, which require user intervention, Service Tasks are configured to perform specific actions…"
source_url: https://spiff.works/docs/spiff-arena/reference/bpmn/service_tasks.html
---

☰ Menu

# Service Tasks[](#service-tasks "Link to this heading")

A **Service Task** in SpiffWorkflow is an automated task type that interacts with external services or systems. Unlike manual tasks, which require user intervention, Service Tasks are configured to perform specific actions automatically, such as retrieving or updating data, processing information, or calling external APIs.

These tasks are essential for integrating third-party services, streamlining data flows, and automating repetitive actions within a workflow.

## Use Cases for Service Tasks[](#use-cases-for-service-tasks "Link to this heading")

Service Tasks can be used in a wide variety of automation and integration scenarios, such as:

1. **Data Retrieval**: Pulling data from external APIs (e.g., employee information from an HR system).
2. **Data Update**: Sending data updates to external systems (e.g., updating inventory levels in a warehouse management system).
3. **Notifications and Alerts**: Integrating with notification services to automatically alert users when certain conditions are met.

## Setting Up a Service Task in SpiffWorkflow[](#setting-up-a-service-task-in-spiffworkflow "Link to this heading")

Service Tasks in SpiffWorkflow allow you to configure HTTP requests and other API calls directly within your workflow.

### Important Guidelines[](#important-guidelines "Link to this heading")

- **Python Expressions**: All fields in SpiffWorkflow interpret input as Python expressions. Wrap url in single quotes (`'...'`) unless passing them as variables.
- **Authentication**: For APIs requiring Basic Auth, use `basic_auth_username` and `basic_auth_password` parameters.
- **Parameter Syntax**: Headers, query parameters, and URLs require JSON-like syntax compatible with Python dictionaries.
- **Response Variables**: Use response variables to store data retrieved from service tasks. These variables can be referenced in later tasks for display or further processing.

### Retries for Transient Failures[](#retries-for-transient-failures "Link to this heading")

You can configure retries directly on a service task operator:

```
<spiffworkflow:retry retries="3" />
```

- `retries` is the maximum retry count.
- `backoff_base` is optional (default is `3`).
- Retry delay (in seconds) uses exponential backoff (`backoff_base^retry_number`, where `retry_number` starts at `1`). With default `backoff_base=3`: first retry after `3s`, second after `9s`, third after `27s`.
- Retry eligibility is determined automatically by Spiff Arena: transient failures (for example network issues, HTTP `5xx`, and `429`) can retry; most other `4xx` failures are treated as permanent and fail without retry.
- Retries also apply to long-running service tasks. If a connector returns `202 Accepted` and later reports a transient failure through the callback, Spiff Arena schedules the service task retry and calls the connector again when the retry is due.

Below, we’ll walk through detailed setup instructions for two examples to illustrate different configurations and use cases.

### Example 1: Fetching Mock Data from JSONPlaceholder API[](#example-1-fetching-mock-data-from-jsonplaceholder-api "Link to this heading")

This simpler example demonstrates how to retrieve user data from the JSONPlaceholder API, useful for testing or prototyping workflows.

#### Service Task Configuration[](#service-task-configuration "Link to this heading")

[![Service Task](../../_images/service_task_doc3.png)](../../_images/service_task_doc3.png)

- **Task Name**: `Get User Data`
- **Operator ID**: `http/GetRequestV2`

  - This is a placeholder API endpoint used to retrieve user data.
- **Response Variable**: `resp_get_user_data`

This example demonstrates a simple GET request. If you were creating data instead (e.g., using an HTTP POST), you could modify the configuration to use http/PostRequest and change the URL to point to a relevant endpoint.

**Parameters**:

- **URL**:
  **url**: `'https://jsonplaceholder.typicode.com/users/1'`

  - The URL is wrapped in single quotes to mark it as a string in Python.
- **Headers**:
  **headers**: `{"Accept": "application/json"}`

  - The `Accept` header specifies that the response should be in JSON format.

### Example 2: Retrieving Employee Information from BambooHR API[](#example-2-retrieving-employee-information-from-bamboohr-api "Link to this heading")

In this example, we’ll configure a Service Task that fetches employee details from the BambooHR API and displays this data in a subsequent manual task.

Below is workflow overview:

![Service Task](../../_images/service_task_doc1.png)

1. **Start Event**: Begins the workflow.
2. **Service Task**: Retrieves employee information from BambooHR.
3. **Manual Task**: Displays the retrieved employee data to the user.
4. **End Event**: Completes the workflow.

#### **Service Task Configuration**[](#id1 "Link to this heading")

[![Login Screen](../../_images/service_task_doc2.png)](../../_images/service_task_doc2.png)

- **Task Name**: `Get Employee Info`
- **Operator ID**: `http/GetRequestV2`

  - This operator is used for making HTTP GET requests to retrieve data from an external API.
- **Response Variable**: `bamboo_get_employee`

  - This variable stores the API response, allowing it to be used in subsequent tasks.

**Parameters**

1. **Basic Authentication**:

   - **basic\_auth\_password**: `"x"` (enclosed in quotes as its a python expression).
   - **basic\_auth\_username**: `"secret:BAMBOOHR_API_KEY"`

     - Replace `BAMBOOHR_API_KEY` with your actual API key. This format specifies the username for Basic Auth, using secure handling with `secret:` notation.
2. **Headers**:

   - **headers**: `{"Accept": "application/json"}`

     - Specifies that the response should be JSON formatted.
3. **Query Parameters**:

   - **params**: `{"fields": "firstName,lastName"}`

     - Defines specific fields (e.g., `firstName`, `lastName`) to retrieve from the API.

Note

⚠ This is specific to BambooHR’s API requirements. Other APIs may require different query parameters or none at all.

4. **URL**:

   - **url**: `'https://api.bamboohr.com/api/gateway.php/{your_company_subdomain}/v1/employees/directory'`

     - Replace `{your_company_subdomain}` with your BambooHR subdomain.