{"id":15588347,"url":"https://github.com/optimajet/workflowengineapi.net","last_synced_at":"2025-03-29T09:22:16.941Z","repository":{"id":255430539,"uuid":"841862974","full_name":"optimajet/WorkflowEngineApi.NET","owner":"optimajet","description":"Workflow Engine HTTP API","archived":false,"fork":false,"pushed_at":"2025-03-10T18:45:12.000Z","size":7511,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-10T19:41:52.104Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/optimajet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-13T07:37:22.000Z","updated_at":"2025-03-10T18:45:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"f31eb06f-031f-4c1c-9a57-7fcd890d2f64","html_url":"https://github.com/optimajet/WorkflowEngineApi.NET","commit_stats":{"total_commits":5,"total_committers":1,"mean_commits":5.0,"dds":0.0,"last_synced_commit":"f2091925873ac34903ffd5289e03811733e0c8a6"},"previous_names":["optimajet/workflowengineapi.net"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optimajet%2FWorkflowEngineApi.NET","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optimajet%2FWorkflowEngineApi.NET/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optimajet%2FWorkflowEngineApi.NET/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optimajet%2FWorkflowEngineApi.NET/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/optimajet","download_url":"https://codeload.github.com/optimajet/WorkflowEngineApi.NET/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246163017,"owners_count":20733536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T22:22:53.105Z","updated_at":"2025-03-29T09:22:16.905Z","avatar_url":"https://github.com/optimajet.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Workflow Engine API Sample\r\n\r\nThis repository contains a sample integration of the Workflow Engine API into an ASP.NET application. The Workflow\r\nEngine Web API is a library for the ASP.NET framework that allows you to integrate a ready-made API into your\r\napplication for managing data and processes within Workflow Engine instances. This module is easily integrable and\r\nhighly customizable, saving you from the routine development needed to integrate Workflow Engine into your web\r\necosystem.\r\n\r\n### Key Features\r\n\r\n1. **RESTful Data API**: Safely interact with the Workflow Engine database without risking internal process disruptions.\r\n2. **RPC API** *(Coming soon…)*: Remotely manage the Workflow Engine Runtime instance.\r\n3. **Permission-based Security**: Fine-tune access to each API endpoint and generate claims for your users.\r\n\r\nLearn more about Workflow Engine API on the [documentation website](https://workflowengine.io/documentation/web-api).\r\n\r\n## Get Started\r\n\r\n1. Install the [.NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0).\r\n2. Install [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4)\r\n   version 7 or higher.\r\n3. Install and run [Docker](https://www.docker.com/products/docker-desktop/).\r\n4. Clone the repository.\r\n\r\n    ```bash\r\n    git clone git@github.com:optimajet/WorkflowEngineApi.NET.git workflow-api-sample\r\n    ```\r\n\r\n5. Go to the solution directory:\r\n\r\n    ```bash\r\n    cd workflow-api-sample\r\n    ```\r\n\r\n6. Add your license key to the `./WorkflowApi/appsettings.json` file:\r\n\r\n    ```json\r\n    {\r\n      \"WorkflowApiCoreOptions\": {\r\n        \"LicenseKey\": \"your_license_key\"\r\n      }\r\n    }\r\n    ```\r\n\r\n7. Install the OpenAPI specification generator tool:\r\n\r\n    ```bash\r\n    dotnet tool install --global Swashbuckle.AspNetCore.Cli --version 6.6.2\r\n    ```\r\n\r\n8. Build the solution:\r\n\r\n    ```bash\r\n    dotnet build\r\n    ```\r\n\r\n9. Run integration tests:\r\n\r\n    ```bash\r\n    pwsh ./Scripts/Tests/run-tests.ps1 -Providers \"Mssql\"\r\n    ```\r\n\r\n10. Launch the WorkflowApi project:\r\n\r\n    ```bash\r\n    dotnet run --project ./WorkflowApi\r\n    ```\r\n\r\n11. Open the Swagger UI in your browser at [localhost:7169/swagger](https://localhost:7169/swagger/index.html).\r\n12. Send GET request to the auth controller with `name=admin\u0026password=admin` to get an API access token with all privileges:\r\n    - Using link: [localhost:7169/auth?name=admin\u0026password=admin](https://localhost:7169/auth?name=admin\u0026password=admin)\r\n    - Using curl:\r\n    \r\n        ```bash\r\n        curl -k -X GET \"https://localhost:7169/auth?name=admin\u0026password=admin\" -H \"Accept: text/plain\"\r\n        ```\r\n      \r\n    - Using Swagger UI:\r\n        1. Scroll to the `Auth` controller.\r\n        2. Click on the `GET /auth` endpoint.\r\n        3. Click on the `Try it out` button.\r\n        4. Enter `admin` in the `name` field.\r\n        5. Enter `admin` in the `password` field.\r\n        6. Click on the `Execute` button.\r\n        7. Copy the token from the response body.\r\n        8. Click on the `Authorize` button in the top right corner.\r\n        9. Paste the token into the `Value` field.\r\n        10. Click on the `Authorize` button.\r\n13. Try out the API endpoints using the Swagger UI, get runtimes for an example:\r\n    - Using curl:\r\n\r\n        ```bash\r\n        curl -k -X GET \"https://localhost:7169/workflow-api/data/runtimes\" -H \"Accept: application/json\" -H \"Authorization: Bearer PUT_YOUR_TOKEN_HERE\"\r\n        ```\r\n\r\n    - Using Swagger UI:\r\n        1. Scroll to the `Runtimes` controller.\r\n        2. Click on the `GET /workflow-api/data/runtimes` endpoint.\r\n        3. Click on the `Try it out` button.\r\n        4. Click on the `Execute` button.\r\n\r\n![How to use Swagger UI](./Images/how-to-use-swagger-ui.gif)\r\n\r\n## Solution Structure\r\n\r\nThe solution consists of three projects:\r\n\r\n- **WorkflowApi** — A sample web application that demonstrates how to use the `OptimaJet.Workflow.Api` library.\r\n- **WorkflowApi.Client** — A sample WorkflowApi client application generated using OpenAPI specification.\r\n- **WorkflowApi.Client.Tests** — An integration tests project based on WorkflowApi client that checks all API endpoints\r\n  work correctly.\r\n\r\n### Solution Building Pipeline\r\n\r\nWhen you run the build of the solution in the `Debug` configuration, an unusual build pipeline is used:\r\n\r\n1. Build WorkflowApi.\r\n2. After building WorkflowApi in debug configuration, the OpenAPI specification is generated by\r\n   the `Swashbuckle.AspNetCore.Cli` tool and placed in `./WorkflowApi/.swagger`.\r\n3. After specification generation, `./WorkflowApi/.swagger/swagger.yaml` is linted by executing\r\n   `./Scripts/lint-swagger.ps1` script.\r\n4. After the specification is linted, `WorkflowApi.Client` is generated by executing `./Scripts/build-client.ps1` and\r\n   placed in the `./.generated` folder.\r\n5. In the same script, the generated client is copied to the `./WorkflowApi.Client` project except for\r\n   the `WorkflowApi.Client.csproj` file.\r\n6. Build `WorkflowApi.Client`.\r\n7. Build `WorkflowApi.Client.Tests`.\r\n\r\n### Scripts\r\n\r\nScripts are stored in the `./Scripts` folder.\r\n\r\n- `build-client.ps1` - Generates the `WorkflowApi.Client` project using the OpenAPI specification\r\n  in `./WorkflowApi/.swagger`.\r\n- `lint-swagger.ps1` - Lints the OpenAPI specification generated at `/WorkflowApi/.swagger/swagger.yaml` using\r\n  the `dshanley/vacuum` Docker image.\r\n- `Tests/run-tests.ps1` - Runs integration tests for the `WorkflowApi.Client.Tests` project. Ensure Docker is installed\r\n  and running before executing. Has a `-Providers` parameter to specify the list of providers to test.\r\n- `Tests/create-containers.ps1` - Creates Docker containers for integration testing in the `WorkflowApi.Client.Tests`\r\n  project. Ensure Docker is installed and running before executing. Has a `-Providers` parameter to specify the list of\r\n  providers to test.\r\n- `Tests/remove-containers.ps1` - Removes containers created by the previous script. Ensure Docker is installed and\r\n  running before executing. Has a `-Providers` parameter to specify the list of providers to remove.\r\n- `Tests/containers.json` - Configuration for the created containers.\r\n\r\n## Details\r\n\r\nThis section dives into the elements of this project to understand the general principles of the Workflow API and its\r\nimplementation in this sample.\r\n\r\n### App Building and Configuration\r\n\r\nThe `AppBuilder` class is used to build the ASP.NET `WebApplication` instead of configuring it in the `Program` class.\r\nThis allows for easy integration testing, enabling another project to create multiple application hosts with predefined\r\nsettings and send requests to them.\r\n\r\nThe `Configuration` class contains part of the application settings, which can be overridden in `appsettings.json`.\r\nDuring service configuration, an instance of this class is serialized from the initial configuration and then added back\r\nto include default settings. This configuration approach allows easy use in integration testing and substitution if\r\nnecessary.\r\n\r\nThe application also adds several essential services, including controllers, authentication with authorization, Swagger\r\ngenerator, and DbContext. Each service has a `ConfigureX` method that takes an `options` object for configuration.\r\n\r\nAll possible Workflow API Data libraries are included in the application, and the provider is selected based on\r\nthe `Configuration.Provider` setting.\r\nThe provider's name chooses the connection string, with the default string\r\nused for the internal database of the Workflow API sample.\r\n\r\nFinally, the WorkflowAPI is connected. In the `ConfigureWorkflowApi` method, you can configure options, although\r\nWorkflow API Options also receive their initial settings from the configuration, allowing configuration\r\nin `appsettings.json`.\r\n\r\n### Security\r\n\r\nTo demonstrate the Workflow API Security component, this project includes authentication and authorization using JWT\r\nBearer, an authorization controller, and an in-memory SQLite database for storing user data.\r\n\r\nTo quickly get an API access token with all privileges, send a GET request to the auth controller with the\r\nusername `admin` and password `admin`.\r\n\r\nThe auth controller has a POST method allowing you to create a new user with any set of privileges. Privileges are\r\nspecified in dot format, such as `workflow-api.health`. You can learn more about privileges in\r\nthe [documentation](https://workflowengine.io/documentation/web-api/security) or use the convenient builder in\r\nthe `IWorkflowApiPermissions` service to get or validate a list of privileges.\r\n\r\nThe auth controller has a DELETE method to remove a user by their name.\r\nIt also has a GET method to get a user from the\r\ndatabase and create a list of claims for a JWT token based on their saved privileges.\r\nThis token is then generated\r\nbased on the JWT configuration and returned as a string.\r\n\r\n### Client Generation\r\n\r\nUsing the `openapitools/openapi-generator-cli` tool hosted in Docker, a C# client code for Workflow API is generated.\r\nThis client is generated based on the `swagger.yaml` API specification. The client is essentially boilerplate code for\r\nworking with API endpoints. It includes DTO classes for models, code for forming request objects, request settings,\r\nexception handling, creating an HTTP client, making requests, and data serialization and deserialization.\r\n\r\nThis tool can generate clients not only for C# but also for almost any popular language, such as TypeScript, Python, Go,\r\nJava, and many others. To generate your client, you can open the [online Swagger editor](https://editor.swagger.io/),\r\nupload the specification, and select `Generate Client → your language` from the menu. Alternatively, you can use the\r\nclient generation script in this repository and modify it to generate a client in an additional language.\r\n\r\n### Testing\r\n\r\nTo run automated testing, you need to install and run Docker, then execute the following command:\r\n\r\n```bash\r\npwsh ./Scripts/Tests/run-tests.ps1\r\n```\r\n\r\nThe tests are integration tests and use Docker databases, and start web application hosts in a separate thread,\r\nconfiguring them as needed for the tests. Each controller is tested in various use cases to ensure full coverage.\r\n\r\nThe tests also use an automatically generated client, so significant changes in the API specification will break the\r\napplication's build and help understand where backward compatibility is violated and where tests need to be modified.\r\n\r\n#### Providers\r\n\r\nBy default, testing is conducted for all data providers supported by Workflow Engine:\r\n\r\n- `Mongo`: MongoDB\r\n- `Mssql`: Microsoft SQL Server\r\n- `Mysql`: MySQL\r\n- `Postgres`: PostgreSQL\r\n- `Oracle`: Oracle\r\n- `Sqlite`: SQLite\r\n\r\nTo change the list of providers for testing, you need to pass the `-Providers` parameter to the script with a list of\r\nproviders separated by commas (without spaces in parameter value). For example:\r\n\r\n```bash\r\npwsh ./Scripts/Tests/run-tests.ps1 -Providers \"Mongo\",\"Mssql\",\"Mysql\",\"Postgres\",\"Oracle\",\"Sqlite\"\r\n```\r\n\r\nRunning tests for all providers can take a long time and require at least 24 GB of RAM. If you have less memory, you can\r\nrun tests for a specific provider or a subset of providers.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptimajet%2Fworkflowengineapi.net","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foptimajet%2Fworkflowengineapi.net","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptimajet%2Fworkflowengineapi.net/lists"}