Source

Target

Commits (89)
Showing with 554 additions and 140 deletions
+554 -140
# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.11"
# You can also specify other tool versions:
# nodejs: "20"
# rust: "1.70"
# golang: "1.20"
# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: source/conf.py
# You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
# builder: "dirhtml"
# Fail on all warnings to avoid broken references
# fail_on_warning: true
# Optionally build your docs in additional formats such as PDF and ePub
# formats:
# - pdf
# - epub
# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
install:
- requirements: source/requirements.txt
## %"FusionDirectory 1.3.1" - 2023-06-23
### Added
#### dev-manual
- dev-manual#1 adding release policies
- dev-manual#2 adding license
- dev-manual#4 Adding more documentation
- dev-manual#5 adding code of conduct
- dev-manual#6 adding an contributing section to the manual
- dev-manual#15 Add translate Fusiondirectory section
- dev-manual#19 Add schema number for sinaps config schema
- dev-manual#20 add schema number for supann extension
- dev-manual#21 reservation of a OID number for the schema of fusiondirectory-plugins-seafile and fusiondirectory-plugins-libreroaming
- dev-manual#30 Guidelines for better contributions
- dev-manual#31 code of conduct
- dev-manual#44 add the release workflow of our various software to the the manual
- dev-manual#45 new subsection in ldap schema "FusionDirectory attribute finder"
- dev-manual#49 add support / security / contact us like in the user manual
- dev-manual#51 add what is fusiondirectory / prerequisite /certified distribution
### Changed
#### dev-manual
- dev-manual#3 reorganising logically the documentation
- dev-manual#7 latest version of contributing.md
- dev-manual#18 move how_to_contribute page from the wiki to developper documentation
- dev-manual#17 move how_to_contribute page from the wiki to developper documentation
- dev-manual#25 rewrite the FusionDirectory Life Cycle page
- dev-manual#29 rewrite distribution and php support
- dev-manual#32 Update the contribute part of the Contributing to FusionDirectory
- dev-manual#37 change the old pictures showing fusiondirectory 1.0.8 in the manual
- dev-manual#47 correct the fusiondirectory cycle that is at 6 month when is should be 12 month
- dev-manual#48 move all fusiondirectory dev manual into a fusiondirectory subidrectory
### Removed
#### dev-manual
- dev-manual#50 remove centos 8 from te supported distribution
### Fixed
#### dev-manual
- dev-manual#13 Correct the exemple about php codesniffer
- dev-manual#9 Coding standard examples should match the coding standards
- dev-manual#10 The code sniffer command is wrong
- dev-manual#28 change the url in 1.3 for the webservice documentation
- dev-manual#52 replace freenode by libera
- dev-manual#66 clarify the php version supported for FusionDirectory 1.3.x
- dev-manual#67 update the certified distribution matrix
# fusiondirectory-docdev
FusionDirectory Development Documentation
# FusionDirectory Dev Manual
This is the FusionDirectory development documentation
This source is compiled to give the [FusionDirectory dev Manual][fusionDirectory-dev-manual]
## Get help
### Community support
There are a couple of ways you can try [to get help][get help].
### Professional support
Professional support is provided through of subscription.
* [FusionDirectory Subscription][subscription-fusiondirectory] : Global subscription for FusionDirectory
The subscription provides access to FusionDirectory's enterprise repository, tested and pre-packaged versions with patches between versions,
providing reliable software updates and security enhancements, as well as technical help and support.
Choose the plan that's right for you. Our subscriptions are flexible and scalable according to your needs
The subscription period is one year from the date of purchase and provides you with access to the extensive infrastructure of enterprise-class software and services.
### Best practice badge
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/351/badge)](https://bestpractices.coreinfrastructure.org/projects/351)
## Crowfunding
If you like us and want to send us a small contribution, you can use the following crowdfunding services
* [donate-liberapay]
* [donate-kofi]
* [donate-github]
## License
[FusionDirectory][FusionDirectory] is [GPL 2 License](COPYING).
[FusionDirectory]: https://www.fusiondirectory.org/
[fusionDirectory-dev-manual]: https://fusiondirectory-developer-documentation.readthedocs.io/en/dev/fusiondirectory/index.html
[get help]: https://fusiondirectory-user-manual.readthedocs.io/en/latest/support/index.html
[subscription-fusiondirectory]: https://www.fusiondirectory.org/en/iam-tool-service-subscriptions/
[register]: https://register.fusiondirectory.org
[donate-liberapay]: https://liberapay.com/fusiondirectory/donate
[donate-kofi]: https://ko-fi.com/fusiondirectory
[donate-github]: https://github.com/fusiondirectory
source/_static/images/fd_logo.png

22.6 KB | W: 0px | H: 0px

source/_static/images/fd_logo.png

22.3 KB | W: 0px | H: 0px

source/_static/images/fd_logo.png
source/_static/images/fd_logo.png
source/_static/images/fd_logo.png
source/_static/images/fd_logo.png
  • 2-up
  • Swipe
  • Onion skin
......@@ -51,17 +51,17 @@ master_doc = 'index'
# General information about the project.
project = u'FusionDirectory development'
copyright = u'2017, Benoit Mortier Côme Chilliet'
author = u'Benoit Mortier Côme Chilliet'
copyright = u'2017-2024 FusionDirectory'
author = u'Benoit Mortier Côme Chilliet Thibault Dockx Jonathan Swaelens Oana Eliza'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'1.4'
version = u'dev'
# The full version, including alpha/beta/rc tags.
release = u'1.4'
release = u'dev'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -262,7 +262,7 @@ latex_elements = {
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'FusionDirectorydevelopment.tex', u'FusionDirectory development Documentation',
u'Benoit Mortier Côme Chilliet', 'manual'),
u'Benoit Mortier Côme Chilliet Thibault Dockx Jonathan Swaelens', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
......
......@@ -5,9 +5,9 @@ Contact Us
We are also contactable on:
* Mailing list: `<https://lists.fusiondirectory.org/wws/lists>`__
* IRC: #fusiondirectory on irc.libera.chat `<irc://irc.libera.chat/fusiondirectory>`__
Follow Us
* On twitter: https://twitter.com/fusiondirectory
* On linkedin: https://www.linkedin.com/company/fusiondirectory
* on Mastodon: @fusiondirectory@pouet.chapril.org
Development Worflows
====================
We follow a specific workflow to label our tickets during their life cycle
.. toctree::
:maxdepth: 2
workflow-tickets.rst
New ticket opened
=================
First the label of the dolibarr project should be added to it.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The dolibarr label are made like this : **PJYYYY**-project number
We have some basic project number that should always be used by default if there is no customer project.
- FusionDirectory / Automated Testing / FusionDirectory demo :
**PJ1802-0188**
- Argonaut : **PJ1802-0190**
- Packaging Debian / Redhat / Centos / Ubuntu : **PJ1802-0189**
- Gitlab-ci changes : **PJ1802-0188**
- User-manual : **PJ2003-0342**
- Dev Manual : **PJ2003-0343**
.. warning::
if the label doesnt exist it need to be created at the group level
for exemple : `Group Label`_
Second the component where the bug/enhancement is to be made should be specified
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Example : fusiondirectory-core or plugin-xxx
.. warning::
It could be several component
Third if this is a customer under contract the level of support should be added also
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Example : basic, intermediate, expert, premium
Ticket as been treated
======================
you need to input you time into the ticket with **/spend** with a choice of xxmin, xxhours, xxdays
.. warning::
Very important as it allow to caculate the time spend on this feature or fix
if some code has been commited and need to be tested
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The **to be tested** label should be added
if some more info is needed to act on the report
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The **need info** label should be added, don’t hesitate to ping the
user reporting the bug with **@(useranme)** to ask him to check it out
If the change need to be cherry-picked in a -fixes version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The **fixes** label is added, when the cherry-pick as been merged we
remove the **fixes** and add the **fixes-merged** label
if the change need a change in packaging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The **packaging** label is added and a corresponding ticket is open
in the corresponding distribution projects
- `Debian Packaging`_
- `Centos Packaging`_
- `Ubuntu Packaging`_
- The packaging ticket are linked back with the code fix ticket
Ticket need to be closed
========================
- Remove the **to be tested** label, and add one of the changelog label
to specify what has been done.
- Added
- Changed
- Deprecated
- Fixed
- Removed
- Security
Those label are used to generate a changelog when we release a new
version of the software, and also used when we want to search in which
version something has been changed and what the type of change it was
.. _Debian Packaging : https://gitlab.fusiondirectory.org/debian
.. _Centos Packaging : https://gitlab.fusiondirectory.org/centos
.. _Ubuntu Packaging : https://gitlab.fusiondirectory.org/ubuntu
.. _Group Label : https://gitlab.fusiondirectory.org/groups/fusiondirectory/-/labels
Libraries
=========
Contents:
FusionDirectory Integrator
==========================
.. toctree::
:maxdepth: 2
......
FusionDirectory marketplace
FusionDirectory Marketplace
===========================
The FusionDirectory marketplace is the best way to find new plugins for FusionDirectory.
......@@ -12,4 +12,3 @@ If you are interested in helping other finding your plugins you will need to rea
:maxdepth: 2
yaml/index.rst
tags/index.rst
......@@ -3,3 +3,4 @@
:maxdepth: 2
yaml.rst
tags.rst
Authorized tags
===============
To be able to filter the plugin by usage, the marketplace can filter the plugins by tags.
The tags are also used to help the user understand in what categorie the plugin is.
Current tags
------------
The following tags are currently recognized by the marketplace
for users :
^^^^^^^^^^^
* card
* document
* entite
* etablissement
* group
* information
* notes
* pdf
* role
* user
for systems and services :
^^^^^^^^^^^^^^^^^^^^^^^^^^
* administration
* api
* automation
* component
* information
* inventory
* mobilephone
* notes
* phone
* printer
* server
* terminal
* workstation
for network and services :
^^^^^^^^^^^^^^^^^^^^^^^^^^
* api
* datacenter
* dcim
* mail
* netdisco
* network
* notes
* rack
* snmp
* zone
for reporting :
^^^^^^^^^^^^^^^
* api
* document
* information
* log
* pdf
* reporting
* template
......@@ -64,23 +64,25 @@ support
Syntax
^^^^^^
+---------------+----------------+--------------------------------------------------------------------+
| keyword | presence | description |
+===============+================+====================================================================+
| provider | mandatory | provider of support : "community" or name of the company |
+---------------+----------------+--------------------------------------------------------------------+
| homeUrl | mandatory | Link to the homepage of the plugin |
+---------------+----------------+--------------------------------------------------------------------+
| ticketUrl | recommended | Link to the ticket system of the plugin |
+---------------+----------------+--------------------------------------------------------------------+
| discussionUrl | recommended | Link to the discussion page of the plugin |
+---------------+----------------+--------------------------------------------------------------------+
| downloadUrl | mandatory | Link to the archive of the plugin |
+---------------+----------------+--------------------------------------------------------------------+
| schemaUrl | recommended | Link to the LDAP schema used by plugin |
+---------------+----------------+--------------------------------------------------------------------+
| contractUrl | none | Link to the company professionnal support page for FusionDirectory |
+---------------+----------------+--------------------------------------------------------------------+
+------------------+----------------+--------------------------------------------------------------------+
| keyword | presence | description |
+==================+================+====================================================================+
| provider | mandatory | provider of support : "community" or name of the company |
+------------------+----------------+--------------------------------------------------------------------+
| homeUrl | mandatory | Link to the homepage of the plugin |
+------------------+----------------+--------------------------------------------------------------------+
| ticketUrl | recommended | Link to the ticket system of the plugin |
+------------------+----------------+--------------------------------------------------------------------+
| discussionUrl | recommended | Link to the discussion page of the plugin |
+------------------+----------------+--------------------------------------------------------------------+
| documentationUrl | recommended | Link to the documentation page of the plugin |
+------------------+----------------+--------------------------------------------------------------------+
| downloadUrl | mandatory | Link to the archive of the plugin |
+------------------+----------------+--------------------------------------------------------------------+
| schemaUrl | recommended | Link to the LDAP schema used by plugin |
+------------------+----------------+--------------------------------------------------------------------+
| contractUrl | none | Link to the company professionnal support page for FusionDirectory |
+------------------+----------------+--------------------------------------------------------------------+
Example
^^^^^^^
......
========================
Development Orchestrator
========================
.. toctree::
:maxdepth: 2
orchDevPlugin.rst
===============================
Creating an Orchestrator Plugin
===============================
This guide explains how to create an Orchestrator Plugin by implementing the **Strategy & Factory Design Pattern** using a mandatory interface implementation.
------------------
0. Plugin Location
------------------
A folder named ``fusiondirectory-orchestrator/plugins`` has been created to store your classes.
At the time of writing, the orchestrator is primarily used for **task processing**.
Therefore, it makes sense to place your classes within the ``tasks`` directory inside ``plugins``, though this is not mandatory.
.. note::
Your plugin will be **automatically autoloaded**.
It will be used as an argument for the endpoint tasks: ``<orchestrator_url>/api/tasks/your_plugin_name``
-------------------------------
1. Implementing the Interface
-------------------------------
An Orchestrator Plugin **must implement** the ``EndpointInterface`` to define the required methods for handling API requests. Each method corresponds to an HTTP operation (**GET, POST, DELETE, PATCH**), ensuring structured API interactions.
To create a new plugin, define a class that implements this interface and includes the necessary methods:
.. code-block:: php
class anOrchestratorPluginClass implements EndpointInterface
{
private TaskGateway $gateway;
/**
* Constructor to initialize the plugin with a TaskGateway.
*
* @param TaskGateway $gateway The gateway instance for interacting with external data sources (e.g., LDAP).
*/
public function __construct(TaskGateway $gateway)
{
$this->gateway = $gateway;
}
}
The constructor takes a ``TaskGateway`` object, which acts as an interface for interacting with external services such as **LDAP**. This gateway will be used within the methods to fetch, update, and delete data.
----------------------------------
2. Handling GET Requests
----------------------------------
The **GET method** retrieves existing data, often from **LDAP**.
If additional processing is required, you are free to extend the logic by calling new methods within your tasks.
.. code-block:: php
/**
* Handles GET requests.
*
* This method retrieves data from the system.
* It is used when clients need to fetch existing records.
* For example, it can query LDAP to return a list of tasks or configurations.
*
* @return array The response data containing the requested information.
*/
public function processEndPointGet(): array
{
// Implement logic to fetch and return data
}
----------------------------------
3. Handling POST Requests
----------------------------------
The **POST method** is used to create new records.
.. code-block:: php
/**
* Handles POST requests.
*
* This method is responsible for creating new records based on your data logic.
* You might have developed a plugin with its own LDAP schema.
*
* @param array|null $data Input data to be processed and stored.
* @return array The response indicating success or failure.
*/
public function processEndPointPost(array $data = NULL): array
{
return [];
}
----------------------------------
4. Handling DELETE Requests
----------------------------------
The **DELETE method** removes existing records.
.. code-block:: php
/**
* Handles DELETE requests.
*
* This method removes existing records based on your data handling logic.
*
* @param array|null $data Information about what should be deleted.
* @return array The response confirming the deletion.
*/
public function processEndPointDelete(array $data = NULL): array
{
return [];
}
----------------------------------
5. Handling PATCH Requests
----------------------------------
The **PATCH method** updates specific fields of an existing record.
It can also be used to **trigger execution** of specific elements without necessarily updating data.
.. code-block:: php
/**
* Handles PATCH requests.
*
* This method updates existing records with new values.
* It is commonly used for modifying specific fields without replacing
* the entire data structure.
* For example, updating a task’s status or adjusting scheduling details.
*
* @param array|null $data Input data containing the fields to be updated.
* @return array The updated response data.
* @throws Exception If an error occurs during processing.
*/
public function processEndPointPatch(array $data = NULL): array
{
// Implement update logic here
}
.. note::
The **PATCH method** is **strongly recommended** in the official FusionDirectory Orchestrator client to execute task flows.
-------------------------------
6. Understanding the Components
-------------------------------
Your plugin interacts with key components such as ``TaskGateway``, which provides a bridge to **external services like LDAP**.
**Key Elements**
- **TaskGateway Integration**:
- Allows retrieving and modifying data.
- Acts as an abstraction layer for FusionDirectory’s tasks.
- **HTTP Method Mappings**:
- ``processEndPointGet()`` → Handles **GET** requests for fetching records.
- ``processEndPointPost()`` → Handles **POST** requests for creating entries.
- ``processEndPointDelete()`` → Handles **DELETE** requests for removing entries.
- ``processEndPointPatch()`` → Handles **PATCH** requests for updating records.
-------------------------------
7. Summary
-------------------------------
To create a new Orchestrator Plugin:
1. **Define a class** that implements ``EndpointInterface``.
2. **Inject the TaskGateway** in the constructor for interaction with external data sources.
3. **Implement all required methods** to handle API requests properly.
4. **Use appropriate logic** within each method to interact with FusionDirectory (e.g., querying LDAP, managing tasks).
By following this structure, you can efficiently integrate new functionality into FusionDirectory’s Orchestrator.
\ No newline at end of file
FusionDirectory Orchestrator
============================
.. toctree::
:maxdepth: 2
whatis/orchestrator.rst
requirements/mandatory.rst
development/index.rst
Mandatory Components
====================
FusionDirectory Orchestrator is a Web application that will need:
* A webserver;
* PHP;
* An ldap server;
* Fusion Directory 1.5 with configured tasks.
Web server
----------
FusionDirectory Orchestrator requires the following web server that supports PHP and URL Rewriting:
* `Apache 2 (or more recent) <http://httpd.apache.org>`_;
* `Nginx <http://nginx.org/>`_;
PHP
---
FusionDirectory Orchestrator 1.1 works with `PHP <https://www.php.net>`_ 7.4 and PHP 8.0.
Mandatory extensions
^^^^^^^^^^^^^^^^^^^^
Following PHP extensions are required for the app to work properly:
* ``curl``: to communicate with different types of servers and protocols
* ``filter``: to filters a variable with a specified filter;
* ``json``: to get support for JSON data format;
* ``mbstring``: to manage multi bytes characters;
* ``ldap``: to connect and query the ldap server;
* ``openssl``: secured communications and generation of secure tokens;
* ``session``: to get user sessions support;
* ``simplexml``;
* ``xml``.
LDAP server
-----------
FusionDirectory Orchestrator will use the LDAP server managed by your FusionDirectory.
Servers know to work are :
* `OpenLDAP`_
.. _OpenLDAP : https://www.openldap.org/
What is FusionDirectory Orchestrator ?
======================================
FusionDirectory Orchestrator is a RESTful web service using JWT authentication, designed to manage and execute tasks efficiently.
It supports multiple endpoints with plugin integration for custom processing or specialized tasks.
Tasks are defined within FusionDirectory, with a client available to query endpoints and manage workflows.
Common tasks include account lifecycle, notifications, reminders, mail automation, audit log management, and more.
Features
^^^^^^^^
- Tasks management.
- Tasks execution.
- Workflow management.
- JWT Authentication methods
Tasks management
^^^^^^^^^^^^^^^^
FusionDirectory Orchestrator REST API provides seamless management and retrieval of tasks created within FusionDirectory.
It offers a clear and concise view of the status of each task, including subtasks, allowing for detailed tracking and reporting.
With its extensible design, the Orchestrator supports specialized tasks such as mail automation, notifications, reminders,
account lifecycle management, and audit log processing, enabling tailored workflows to meet diverse needs
Tasks Execution
^^^^^^^^^^^^^^^^
One of the core functionalities of the **FusionDirectory Orchestrator** is the execution and processing of various tasks as defined within FusionDirectory.
- **Mail Tasks**:
When triggered, tasks of type "Mail" will automatically send the relevant emails if the scheduled conditions are met, ensuring timely communication.
- **Life Cycle Tasks**:
These tasks are responsible for updating specialized attributes, such as *supann* attributes, in accordance with defined lifecycle processes.
- **Notification Tasks**:
When attributes are modified, "Notification" tasks will send automated email alerts to keep users informed of changes.
- **Reminder Tasks**:
These tasks send reminders to users, potentially including links to extend or prolong their account, ensuring critical actions are not missed.
- **Audit Tasks**:
Tasks of this type allow for the management of audit logs, including the deletion of logs based on configurable retention policies, ensuring compliance and data management.
The **Orchestrator client** provides a user-friendly interface to activate and manage these tasks, allowing for seamless workflow execution and efficient task orchestration across the system.
JWT Authentication
^^^^^^^^^^^^^^^^^^^
To strengthen our authentication mechanism, we have adopted the **JWT (JSON Web Token)** methodology.
After a successful username/password authentication, the user receives two tokens:
- **Access Token**:
This token is used to authorize and perform operations on FusionDirectory Orchestrator endpoints.
- **Refresh Token**:
This token is used to obtain a new access token when the current one expires, ensuring seamless and secure access without requiring repeated login attempts.
This approach enhances security while simplifying the authentication process, enabling efficient and secure communication with the Orchestrator API.
\ No newline at end of file