Document budgets

content/.pages

@@ -7,6 +7,7 @@ nav:
 - processes
 - models
 - secrets
+- budgets
 - training
 - How to: howto
 - deployment

content/budgets/index.md

+---
+title: Budgets
+---
+
+!!! info
+
+    This feature is only available for Enterprise Edition customers.
+
+**Budgets** allow to keep track of and limit the execution costs of [processes](../processes/index.md) when they run [workers with costs](../workers/advanced.md#costs).
+
+A budget can be associated to one or more [projects](../project/index.md), and a project can only be linked to one budget.
+
+A budget has [access rights](../users/rights/index.md#budget-access) distinct from those of projects, allowing for more precise management of user rights, for example by allowing a user to contribute to a project without being able to run workers with costs, or to manage a budget without having access to the documents in the associated projects.
+
+## Budget entries
+
+Within a budget, **budget entries** represent changes in the funds available on the budget, with a description and optionally an associated user or process.
+
+Typically, instance administrators will add budget entries for their user account with positive values through the [administration interface](../deployment/administration.md#administration-interface) to add funds to the budget, and budget entries will be automatically created with negative values when executing a process.
+
+Budget entries can have values ranging from `-999,999,999.999` to `999,999,999.999`. All monetary values are represented in euros (€), but they could be interpreted in any other currency as Arkindex does not directly handle any financial information.
+
+## Browsing budgets
+
+In the top-right user menu, the **Budgets** action shows a list of all budgets that the user has access to. Clicking on any of those budgets will show their details page, including the currently available funds computed from all budget entries, the full list of budget entries, and the budget's memberships.
+
+It is also possible to view the budget associated to a project from the [project information](../project/index.md#web-interface) page, under the **Details** tab.
+
+From the status view of a process, the **Budget entries** action of the **Actions** menu offers a list of all the budget entries associated with this specific process, along with the total execution cost for this process.
+
+## Administration
+
+Other than viewing them and [managing their memberships](../users/rights/index.md#budget-access), most operations on budgets are only possible through the [administration interface](../deployment/administration.md#administration-interface). This includes:
+
+* creating a new budget;
+* editing an existing budget;
+* deleting a budget;
+* assigning a budget to a project;
+* creating budget entries.
+
+### Creating budget entries for processes
+
+The `arkindex update_budgets` administrator creates new budget entries for all processes that use workers with costs and have had any activity since the last time they had any budget entry created for them. System administrators need to arrange for this command to be run regularly to create new budget entries automatically.
+
+### Restricting process execution
+
+Instance administrators can enable the [`process_enforce_budgets` setting](../deployment/configuration.md#process_enforce_budgets) to require funds to be available to run processes that use [workers with costs](../workers/advanced.md#costs). When attempting to start a process, retry a process, or restart a task, an error will occur when:
+
+* there is no budget on the project associated with the process;
+* there is a budget, but you do not have the access rights to consume funds from this budget;
+* there is a budget, but it does not have any funds available.
+
+This option will apply for the whole instance, on any budget, project or worker.

content/processes/advanced.md

@@ -111,4 +111,14 @@ If you **Retry** the process (the "retry" action is available both from the proc
 Two additional actions are available from the Worker activities monitoring page:
 
 - The **Select all failed elements** button adds all the elements in an `error` state to [your selection](../howto/run-process/index.md#from-a-selection);
-- The **Create process** button create a new blank process from all the elements in an `error` state, which you can then [configure and run](../howto/run-process/index.md#configure-workers).
\ No newline at end of file
+- The **Create process** button create a new blank process from all the elements in an `error` state, which you can then [configure and run](../howto/run-process/index.md#configure-workers).
+
+### Execution costs
+
+!!! info
+
+    This feature is only available for Enterprise Edition customers.
+
+When a process includes [workers with costs](../workers/advanced.md#costs), their [budget entries](../budgets/index.md#budget-entries) and total execution cost can be viewed through the **Budget entries** action in the **Actions** menu of the process status view.
+
+If instance administrators [have enabled it](../budgets/index.md#restricting-process-execution), starting a process, retrying a process or restarting a task may cause an error when that involves running a worker with costs and there are no funds available to run it.

content/users/rights/index.md

@@ -195,3 +195,14 @@ If you have admin rights on the model, you can delete its versions and manage it
 | Stop a running dataset process        | ❌        | ❌     | ❌           | ✅     |
 | Retry a failed dataset process        | ❌        | ❌     | ❌           | ✅     |
 
+### Budget access
+
+Users can view the [budgets](../../budgets/index.md) that they have access to from the **Budgets** action in the top right user menu. After selecting a budget in the list, the memberships linked to that budget can be managed under the **Members** section.
+
+#### Budget permission table
+
+| action                      | no right | guest | contributor | admin |
+| --------------------------- | -------- | ----- | ----------- | ----- |
+| View a budget               | ❌        | ✅     | ✅           | ✅     |
+| Consume funds from a budget | ❌        | ❌     | ✅           | ✅     |
+| Manage members              | ❌        | ❌     | ❌           | ✅     |

content/workers/advanced.md

@@ -158,6 +158,8 @@ All costs are expressed in euros, have a precision of up to three decimal places
 
 When any of these costs is set to any value above zero, all costs will be displayed when viewing the details of a worker, and a `€` icon will be shown next to the worker name.
 
+In [Arkindex Enterprise Edition](../overview/license.md) only, new entries will be created in a [budget](../budgets/index.md) when running a process that contains any task using a worker with costs.
+
 ## Secrets
 
 Some workers may require the use of **Secrets**, like for example an authentication token to interact with an external API. See the dedicated [secrets documentation](../secrets/index.md).