> For the complete documentation index, see [llms.txt](https://documentation.ocsinventory-ng.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ocsinventory-ng.org/administrator-docs/server-setup/configuration/advanced/automations.md).
# Automated actions
Automated actions are scripts stored in a specific location on the server’s file system.\
They are executed using **Django’s built-in management commands** according to a defined schedule.
Each automated action consists of:
* **a scheduler entry**, which defines its status and how often it runs
* **a script**, located in the designated directory and following the required naming and format conventions
* **a cron job (or similar system scheduler)** used to trigger execution of management commands at a scheduled interval
From **Configuration → General → Automated actions**, you can view each automated action’s **last execution date**, **status**, **recurrence interval**, and access its **execution history**.
Automated action overview
## Working principle
Automated actions are executed through a two-layer system:
1. **Scheduler layer**: a system-level scheduler (cron, systemd, etc.) periodically triggers the Django management command responsible for automation handling.
2. **Application layer**: when invoked, this command checks all configured automated actions and executes those whose recurrence conditions are met (hourly, daily, weekly, or monthly).
The scheduler does not directly run each action. It only launches the handler, which evaluates all actions and runs the eligible ones based on their configuration. If the scheduler runs less than once per hour, some actions may be delayed or skipped until the next execution.
## Default automated actions
* **Dynamic groups generation**: updates [Asset Groups](/user-docs/asset-management/asset-groups.md#dynamic-groups) by replaying the search they are associated with and adding/removing assets to the group.
* **Account info generation**: generates administrative data entries for assets. Can disabled if the administrative data generation is delegated to the agent.
* **Agent logs purge**: removes old agent logs according to the retention policy.
* **Legacy assets merge**: merges duplicated legacy asset entries.
* **Orphaned files purge**: removes unlinked or orphaned files.
* **Old packages purge**: deletes deployment packages according to the max age policy.
## Recurrence
Automated actions run on a fixed schedule if enabled. Four modes are available:
* **Hourly:** runs every hour.
* **Daily:** requires specifying the **hour** of execution.
* **Weekly:** requires specifying both the **day of the week** and the **hour**.
* **Monthly:** requires specifying the **day of the month** and the **hour**.
{% hint style="info" %}
The [system scheduler](#system-scheduler) defines how often the automated action scheduler itself runs. The recurrence you set in the interface (hourly, daily, etc.) is only evaluated when this job executes.
{% endhint %}
## Executing automated actions
### One-time run
Automated actions are executed using a dedicated Django management command.\
To launch the process manually from the OCS back-end directory:
```
python manage.py automation
```
To run a specific task immediately (bypassing its configured recurrence) use the `--force` flag. For example, to update dynamic groups and purge orphaned files:
```
python manage.py automation --force dynaGroups.DynaGroups,purgeFiles.PurgeFiles
```
{% hint style="info" %}
Task names must match exactly those displayed in the web console.
{% endhint %}
To adjust verbosity or log level for a manual execution, use the `--loglevel` option:
```
python manage.py automation --force dynaGroups.DynaGroups --loglevel DEBUG
```
### System scheduler
To run the automated action handler every hour using cron:
```
0 * * * * /usr/bin/python3 /opt/ocsinventory/manage.py automation
```
## Consulting the execution history
Execution history confirms when automated actions ran and whether they completed successfully.
You can access this history in two ways:
#### Global history
Lists **all** automated-action executions across the application.
* Navigate to **Configuration ➜ General ➜ Automated actions**.
* Click the **File** icon at the top of the table.\
This opens the aggregated log recorded by all active automated actions.
#### Per-action history
Shows the history for a **single** action.
* On the same page, locate the action you want
* Click the **File** icon in the **Actions** column
Both logs display execution date, time, status, and output for troubleshooting.
## Creating automated actions
Creating an automated action requires two components:
* A [scheduler entry](#scheduler-entry) which registers the automated action and defines its recurrence
* The [script](#automated-action-script) that will be executed
### Automated action script
#### **Location**
All automated action scripts are located under `automation/tasks/` from the root of the **OCS Inventory Server** back-end directory.\
New scripts must be placed in the same path to be detected.
#### **Inheritance**
All automated action scripts must inherit from the `AbstractTask` class defined in `abstractTask.py`.\
This requires implementing an `execute()` method.
The `example.py` script provides a reference for creating a new class with inheritance and implementing the `execute()` method. Other scripts can also be consulted as examples.
#### **Naming convention**
* Use **camelCase** for the filename (e.g., `purgePackages.py`)
* Use **PascalCase** for the class name inside the file
\
Both must remain consistent, since the **moduleName.ClassName** pair is used when registering the [scheduler entry](#scheduler-entry).
### Scheduler entry
To make your automated action executable, you must register it with a scheduler entry.\
The scheduler entry defines the action’s name, its recurrence, and whether it is active.
To create a scheduler entry:
{% stepper %}
{% step %}
Navigate to **Configuration** **→** **General** **→** **Automated** **actions**.
{% endstep %}
{% step %}
Click the **Add an automated action** button.
{% endstep %}
{% step %}
Fill the form.
* **Name:** must match the `moduleName.ClassName` format.
* **Description**
* **Active:** enable or disable execution.
* **Recurrence:** hourly, daily, weekly, or monthly.
* **Time-related fields**: appear depending on the recurrence.\
These allow you to specify the exact execution time (hour, day of the week, day of the month).
{% endstep %}
{% step %}
Click **Add**.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
The scheduler entry only **declares** the action and defines when it should run.\
Execution will only happen if your external [**system scheduler**](#system-scheduler) (cron, systemd timer, etc.) runs `python manage.py automation` frequently enough.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.ocsinventory-ng.org/administrator-docs/server-setup/configuration/advanced/automations.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
