diff --git a/source/fusiondirectory-orchestrator/development/orchDevPlugin.rst b/source/fusiondirectory-orchestrator/development/orchDevPlugin.rst index 72f793a565385e2778098f43d033ff9bf18c6d77..b7d7aa64acc6b1a615517a42ba24a286ec35dddb 100644 --- a/source/fusiondirectory-orchestrator/development/orchDevPlugin.rst +++ b/source/fusiondirectory-orchestrator/development/orchDevPlugin.rst @@ -1,71 +1,177 @@ -=================== -Orchestrator plugin -=================== - -This guide will help you get started with development within our GitLab environment. -It covers account creation, issue creation, project forking, and submitting a Merge Request (MR). - ----------------------------- -1. Orchestrator contribution ----------------------------- - -Please follow how to create an account, fork a project, create an MR and creating issues from FusionDirectory development section. -Exact same methodology will apply for your orchestrator plugin if you want it to be contributed within the main project. - -With that said, let's see how to create a plugin, a new orchestrator endpoints. - - ------------------- -2. Class structure ------------------- - -**Your class must implements the interface "EndPointInterface"** - -In order to interact with many defined methods, including LDAP interaction, we received a "gateway" object. - -class anOrchestratorPluginClass implements EndpointInterface -{ - - private TaskGateway $gateway; - - public function __construct (TaskGateway $gateway) - { - $this->gateway = $gateway; - } - - /** - * @return array - * Part of the interface of orchestrator plugin to treat GET method - */ - public function processEndPointGet (): array - { - } - - /** - * @param array|null $data - * @return array - */ - public function processEndPointPost (array $data = NULL): array - { - return []; - } - - /** - * @param array|NULL $data - * @return array - */ - public function processEndPointDelete (array $data = NULL): array - { - return []; - } - - /** - * @param array|NULL $data - * @return array - * @throws Exception - */ - public function processEndPointPatch (array $data = NULL): array - { - } - -} \ No newline at end of file +========================== +Creating an Orchestrator Plugin +========================== + +This guide explains how to create an Orchestrator Plugin, implementing potential "Strategy development pattern" using +interfaces implementation. + +------------------------------- +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), allowing structured API interactions. + +To create a new plugin, define a class that implements this interface and ensure it 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 serves as an interface to interact 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** is used to retrieve existing data, such as tasks or configurations, from the system. + +.. 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 + } + +**Explanation:** +- This method is responsible for fetching data when an API request is made with ``GET``. +- It can retrieve information from LDAP or other sources via the ``TaskGateway``. +- The returned data should be formatted as an **array**. + +---------------------------------- +3. Handling POST Requests +---------------------------------- + +The **POST method** is used to create new records in the system. + +.. code-block:: php + + /** + * Handles POST requests. + * + * This method is responsible for creating new records in the system. + * It is typically used when an administrator or an external service + * submits new data to be stored (e.g., adding a new task to LDAP). + * + * @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 []; + } + +**Explanation:** +- This method processes **new data submissions** (e.g., creating a new task). +- The input data is passed as an array, and it should be processed and stored accordingly. +- The return value should be an array indicating whether the operation was **successful or failed**. + +---------------------------------- +4. Handling DELETE Requests +---------------------------------- + +The **DELETE method** is used to remove existing records. + +.. code-block:: php + + /** + * Handles DELETE requests. + * + * This method removes existing records from the system. + * It is used when an administrator or system process + * wants to delete a task or configuration from the directory. + * + * @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 []; + } + +**Explanation:** +- This method allows deleting records, such as removing a scheduled task. +- The ``$data`` array should contain information about what needs to be deleted. +- The method should return an array confirming the **successful deletion**. + +---------------------------------- +5. Handling PATCH Requests +---------------------------------- + +The **PATCH method** is used to update specific fields of an existing record. + +.. 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 + } + +**Explanation:** +- This method is used when modifying specific attributes of an existing record. +- Unlike ``POST``, which creates new data, ``PATCH`` **updates existing values**. +- The method should ensure only relevant fields are updated without affecting unrelated data. + +------------------------------- +6. Understanding the Components +------------------------------- + +The plugin interacts with the system using the ``TaskGateway`` class, which provides a bridge to external services like LDAP. + +- **TaskGateway Integration**: + - The ``TaskGateway`` object allows retrieving and modifying data. + - It serves as an abstraction layer to interact with FusionDirectory’s tasks. + +- **HTTP Method Mappings**: + - ``processEndPointGet()`` → Handles GET requests to fetch existing records. + - ``processEndPointPost()`` → Handles POST requests to create new entries. + - ``processEndPointDelete()`` → Handles DELETE requests to remove entries. + - ``processEndPointPatch()`` → Handles PATCH requests to update existing records. + +------------------------------- +7. Summary +------------------------------- + +To create a new orchestrator plugin: + +1. **Define a class** that implements ``EndpointInterface``. +2. **Inject the TaskGateway** in the constructor to enable interaction with external data sources. +3. **Implement all required methods** to properly handle API requests. +4. **Use appropriate logic** within each method to interact with FusionDirectory (e.g., querying LDAP, managing tasks). + +By following this structure, you can integrate new functionality into FusionDirectory’s Orchestrator efficiently.