diff --git a/source/fusiondirectory-orchestrator/development/index.rst b/source/fusiondirectory-orchestrator/development/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..ef1fcf45ecd24fc80cc437cd924bd9fc0b3ea6b0 --- /dev/null +++ b/source/fusiondirectory-orchestrator/development/index.rst @@ -0,0 +1,8 @@ +======================== +Development Orchestrator +======================== + +.. toctree:: + :maxdepth: 2 + + orchDevPlugin.rst diff --git a/source/fusiondirectory-orchestrator/development/orchDevPlugin.rst b/source/fusiondirectory-orchestrator/development/orchDevPlugin.rst new file mode 100644 index 0000000000000000000000000000000000000000..a5ad17d8b7b38e08a1dface00375938a88c4e3a3 --- /dev/null +++ b/source/fusiondirectory-orchestrator/development/orchDevPlugin.rst @@ -0,0 +1,176 @@ +=============================== +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 diff --git a/source/fusiondirectory-orchestrator/index.rst b/source/fusiondirectory-orchestrator/index.rst index 4596c59432ed7ae9279fc8b315555601b6a6761c..110fd9ef47c19b5dd78c7d5bab86cd6d9b4efc55 100644 --- a/source/fusiondirectory-orchestrator/index.rst +++ b/source/fusiondirectory-orchestrator/index.rst @@ -6,3 +6,4 @@ FusionDirectory Orchestrator whatis/orchestrator.rst requirements/mandatory.rst + development/index.rst