diff --git a/docs/Building_Diagrams/Extensions.md b/docs/Building_Diagrams/Extensions.md new file mode 100644 index 00000000..dfd65306 --- /dev/null +++ b/docs/Building_Diagrams/Extensions.md @@ -0,0 +1,99 @@ +# Extensions + +Extensions in SpiffArena provide a mechanism to augment the software with custom features and functionality. +By leveraging extensions, users can implement functions or features not present in the standard offering. +This powerful feature ensures adaptability to various business needs, from custom reports to specific user tools. + +Here are some of key aspects of using Extensions: +- Extensions are implemented within the process model repository. +- Once an extension is created, it can be made accessible via the top navigation bar. +- Extensions are universal. Once added, they will be visible to all users and are not user-specific. +- Configuration for an extensions can be found and modified in its `extension-uischema.json` file. + +![Extensions](images/Extensions_dashboard.png) + +## Getting Started with Extensions + +### Environment Variable Activation + +To utilize extensions, an environment variable must be set. +This variable activates the extensions feature in the SpiffWorkflow backend. +Here is the enviromental variable: + + SPIFFWORKFLOW_BACKEND_EXTENSIONS_API_ENABLED=true + +If SpiffWorkflow is being deployed using Docker Compose, add the environment variable under the selected section of your `docker-compose.yml` file as shown in screenshot: + +![Enviromental variable](images/Extensions2.png) + +### Creating an Extension +After enabling extensions from the backend, you can create extensions in the SpiffArena frontend. +To create your own custom extension, follow these steps: + +- Navigate to the process model repository where extensions are to be implemented. + +![Extension Process Group](images/Extension1.png) + +- Create the `extension-uischema.json` file. If you want to modify an existing extension, you can change the layout as well in existing models. + +![Extension](images/Extension_UI_schema.png) + +- To add a new extension with navigation, incorporate the navigation function within this JSON file. For instance, we are taking an example of aggregate metadata extension: + +``` json +{ + "navigation_items": [{ + "label": "Aggregate Metadata", + "route": "/aggregate-metadata" + } + ], + "routes": { + "/aggregate-metadata": { + "header": "Aggregate Metdata", + "api": "aggregate-metadata", + "form_schema_filename": "we-aggregate-schema.json", + "form_ui_schema_filename": "we-aggregate-uischema.json", + "markdown_instruction_filename": "we-aggregate-markdown.md", + "results_markdown_filename": "we-aggregate-results-markdown.md" + } + } +} + +``` +The provided JSON structure describes configuration for a data aggregation feature with user interface components including navigation. +Here's a breakdown of the key components: + +1. `navigation_items`: This is an array containing additional navigation items that should be added to the application. In this case, there's only one item: + - `"label"`: The label or display text for the navigation item is "Aggregate Metadata". + - `"route"`: The route or URL associated with the navigation item is "/aggregate-metadata". This indicates that clicking on this navigation item would take the user to this specific path. + +2. `routes`: This is an object that defines new routes within the application. In this case, there's only one route defined: + - `"/aggregate-metadata"`: This is the URL route that corresponds to the previously mentioned navigation item. The details for this route are: + - `"header"`: The header or title for the page associated with this route is "Aggregate Metadata". + - `"api"`: This refers to an API endpoint that is used to retrieve or manipulate aggregated metadata. + - `"form_schema_filename"`: The filename "we-aggregate-schema.json" points to a JSON schema that describes the structure of the data to be submitted through a form on the "Aggregate Metadata" page. + - `"form_ui_schema_filename"`: The filename "we-aggregate-uischema.json" points to a UI schema that specifies how the form elements on the page should be rendered and arranged. + - `"markdown_instruction_filename"`: The filename "we-aggregate-markdown.md" points to a Markdown file containing instructions or guidance for the user when interacting with the form on the "Aggregate Metadata" page. + - `"results_markdown_filename"`: The filename "we-aggregate-results-markdown.md" points to a Markdown file where the results of the aggregation process will be displayed or explained. + +This route has associated components such as a header, API endpoint, form schema, form UI schema, instructions in Markdown format, and a results display in Markdown format, all related to the process of aggregating metadata. +An entirely new feature application feature with frontend and backend components can therefore be implemented using an extension in this way. + +- Deploy your changes and ensure the environment variable is activated to see your extensions in the top navigation bar and start adding new features to SpiffArena. + +![Extension](images/Agregate_metadata.png) + +# Use Cases + +If your organization has specific needs not catered to by the standard SpiffArena features, you can use extensions to add those features. + +Here are some of the use cases already implemented by our users: +- Implementing a time tracking system. +- Creating custom reports tailored to your business metrics. +- Incorporating arbitrary content into custom pages using markdown. +- Creating and accessing tailor-made APIs. +- Rendering the output of these APIs using jinja templates and markdown. + +Extensions in SpiffArena offer a robust mechanism to tailor the software to unique business requirements. +When considering an extension, also consider whether the code would be more properly included in the core source code. +In the cases where an extension is appropriate, by following the instructions in this guide, organizations can expand the system's functionality to meet their unique needs. diff --git a/docs/Building_Diagrams/images/Agregate_metadata.png b/docs/Building_Diagrams/images/Agregate_metadata.png new file mode 100644 index 00000000..c98cc237 Binary files /dev/null and b/docs/Building_Diagrams/images/Agregate_metadata.png differ diff --git a/docs/Building_Diagrams/images/Env_variable_Screenshot.png b/docs/Building_Diagrams/images/Env_variable_Screenshot.png new file mode 100644 index 00000000..2cec5530 Binary files /dev/null and b/docs/Building_Diagrams/images/Env_variable_Screenshot.png differ diff --git a/docs/Building_Diagrams/images/Extension1.png b/docs/Building_Diagrams/images/Extension1.png new file mode 100644 index 00000000..1841cb90 Binary files /dev/null and b/docs/Building_Diagrams/images/Extension1.png differ diff --git a/docs/Building_Diagrams/images/Extension_UI_schema.png b/docs/Building_Diagrams/images/Extension_UI_schema.png new file mode 100644 index 00000000..e3bf57d1 Binary files /dev/null and b/docs/Building_Diagrams/images/Extension_UI_schema.png differ diff --git a/docs/Building_Diagrams/images/Extensions2.png b/docs/Building_Diagrams/images/Extensions2.png new file mode 100644 index 00000000..0af8f186 Binary files /dev/null and b/docs/Building_Diagrams/images/Extensions2.png differ diff --git a/docs/Building_Diagrams/images/Extensions_dashboard.png b/docs/Building_Diagrams/images/Extensions_dashboard.png new file mode 100644 index 00000000..3e435256 Binary files /dev/null and b/docs/Building_Diagrams/images/Extensions_dashboard.png differ diff --git a/docs/index.md b/docs/index.md index 4aedb273..a173e73f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,6 +21,7 @@ Building_Diagrams/Script_Tasks.md Building_Diagrams/sub-processes_and_call_activities.md Building_Diagrams/data_objects.md Building_Diagrams/dmn.md +Building_Diagrams/Extensions.md Building_Diagrams/pools_and_lanes.md ```