> ## Documentation Index
> Fetch the complete documentation index at: https://doc.qbilon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Tasks

> Understand custom tasks and their role in Qbilon automations.

## Preface

This document introduces you to Qbilon's automation engine and how to create your own tasks for it. If you’re dealing with complex IT landscapes and want to automate documentation and data flows, this is definitely for you. Qbilon helps you centralize, analyze, and automate everything about your IT assets, making your life easier and your processes smarter.

## Automation Engine

The automation engine is Qbilon's core functionality – a powerful feature designed to automate and orchestrate tasks across IT landscapes. It's purpose is to automatically carry out tasks that load, consolidate or synchronize asset data from and to 3rd-party systems.

`Automations` allow to define sequences of tasks ("workflows") that run automatically based on individual configuration. These tasks can include importing data from various sources, merging and cleaning up assets, triggering notifications, and exporting results among others.

The engine is open and highly customizable, enabling users to plug in own custom tasks to fit specific needs. This makes it very easy to extend the platform’s capabilities.

## Creating Custom Tasks

Qbilon makes it straightforward to add custom tasks to `Automations`.

### Preconditions

* Access to the Qbilon instance (with admin rights),
* a script or application (e.g., in Python, Bash, JavaScript, or another language) that performs the specific logic and
* a running Docker instance.

### Basic Automation

The first step is to write the custom logic, such as a script that fetches data from a special API, processes it, and returns the results. Next, the script can be registered as a custom task in Qbilon so that it becomes part of the automation, just like any standard task.

### Use Case Examples

* **Automated User Import:** Writing a Python script that collects user data from an HR system and imports it into Qbilon. Can be set up as a custom task and executed by Qbilon on schedule—no more manual updates!
* **Slack Notifications:** Receiving notifications when an automation completes can be achieved by creating a custom task that sends a message to a Slack channel whenever a data import finishes.
* **AI integration**: Qbilon can integrate AI into automations when the necessary API keys are made available by the AI provider. This enables an AI to create merging or linking configurations.

### Tutorials as Jump Start

We have prepared several small step-by-step tutorials (see [Creating Custom Tasks](https://doc.qbilon.io/12-customizing-qbilon/custom-tasks/creating-custom-tasks.md)) on how custom tasks can be created with Qbilon.

### Best Practices – No Secrets in Code

* During testing, this command can be used in Linux systems:
  ```text theme={null}
  MY_VAR=1234 MY_OTHER_VAR=production node app.mjs
  ```
* In PowerShell, the "env" variables have to be defined beforehand:
  ```powershell theme={null}
  $env:PORT = "3000"
  ```
* Qbilon provides the environment variable through a configuration parameter for custom tasks at runtime.

## Defaults and Limitations

**RAM/CPU Limits**
As a general rule, it is best to use no more than 2 GiB of RAM for tasks and avoid overstressing the CPU, as this may result in task being terminated in the cluster. Currently, it is not possible to increase the maximum RAM or CPU for each task.

**Image Sizes**
As a best practice, it is recommended to keep the image sizes used for custom tasks in Qbilon as small as possible. For instance, most of our tasks do not exceed the 300 MB limit. This can be achieved by using minimal base images, such as [Alpine images](https://hub.docker.com/_/alpine). The larger the image, the longer it takes Qbilon to spin it up as a task in an automation.

**Maximum runtime duration**
By default, a task will be terminated after 2 hours at the latest. It is not currently possible to change this.

### Environment Variables

By default, Qbilon will provide each task with the following environment variables:

| **Environment Variable** | **Description** | **Example Value** |
| - | - | - |
| `QB_TASK_ID` | Data-source ID provided to the task. Use its value unchanged for data-source-scoped API calls, and URL-encode it when inserting it into a path segment. | `14` |
| `QB_HOST` | Base URL of the Qbilon backend, without an endpoint path. Use this same base URL for the data API and the backend logging API. | [`https://yourcompany.gwc.qbilon.net`](https://yourcompany.gwc.qbilon.net/) or [`http://host.docker.internal:8181`](http://host.docker.internal:8181/) for local deployments |
| `QB_WORKFLOW_ID` | The unique ID (not the human readable identifier) of the automation your task is running in, which is used to access data sent to [Webhook Trigger](https://doc.qbilon.io/05-automations-workflows/webhooks.md) | `5` |

### Authentication

Authentication is provided in the file `/tmp/task-authentication` . Here's an example for retrieving and using a token:

```powershell theme={null}
# Read the token mounted inside the task container.
TOKEN="$(cat /tmp/task-authentication)"
curl --request POST "${QB_HOST%/}/apiv1/data" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"types":[{"names":["Azure Virtual Machine"],"attributeNames":["ID","Name"]}]}'
```

## Cheat Sheet

This is a short list of commonly used commands and scripts that may be helpful when creating custom tasks.

### Building/Publishing a Docker Image

To build and publish a Docker image, a Docker file that describes the build is needed. Then, in the same directory, the following command can be executed:

```bash theme={null}
IMAGE="YOUR_DOCKERHUB_USERNAME/qb-hello-qbilon:v1"
docker login
docker build --platform=linux/amd64 --tag "$IMAGE" .
docker push "$IMAGE"
```

## Troubleshooting

### Blank Spaces in Environment Variable Key

An error message similar to the following will be displayed if the "Key" of the environment variable contains blanks:

![Custom Tasks: Blank Spaces in Environment Variable Key](https://mintcdn.com/qbilon-docs/aJQhbcvq7mtvhV0w/.gitbook/assets/0b360e9a-43a1-4e77-adab-73d4f6d49b2a-image.png?fit=max\&auto=format\&n=aJQhbcvq7mtvhV0w\&q=85\&s=b41c15287ea344e4c4e7f0ec394f535b)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.