This repository contains a sample integration of the Workflow Engine API into an ASP.NET application. The Workflow Engine Web API is a library for the ASP.NET framework that allows you to integrate a ready-made API into your application for managing data and processes within Workflow Engine Runtime instances. This module is easily integrable and highly customizable, saving you from the routine development needed to integrate Workflow Engine into your web ecosystem.

1. RESTful Data API: Safely interact with the Workflow Engine database without risking internal process disruptions.
2. RPC API: Remotely manage the Workflow Engine Runtime instances in single- or multi- tenant modes.
3. Permission-based Security: Fine-tune access to each API operation and generate claims for your users.

Learn more about Workflow Engine API on the documentation website.

1. Install the .NET 8 SDK.

2. Install PowerShell version 7 or higher.

3. Install and run Docker.

4. Clone the repository.

   git clone [email protected]:optimajet/WorkflowEngineApi.NET.git workflow-api-sample

5. Go to the solution directory:

   cd workflow-api-sample

6. Add your license key to the ./WorkflowApi/appsettings.json file:

   {
     "WorkflowApiCoreOptions": {
       "LicenseKey": "your_license_key"
     }
   }

7. Install the OpenAPI specification generator tool:

   dotnet tool install --global Swashbuckle.AspNetCore.Cli --version 6.6.2

8. Build the solution:

   dotnet build

9. Run integration tests:

   pwsh ./Scripts/Tests/run-tests.ps1 -Providers "Mssql"

10. Launch the WorkflowApi project:

    dotnet run --project ./WorkflowApi

11. Open the Swagger UI in your browser at localhost:7169/swagger.

12. Send GET request to the auth controller with name=admin&password=admin to get an API access token with all privileges:

    • Using link: localhost:7169/auth?name=admin&password=admin

    • Using curl:

      curl -k -X GET "https://localhost:7169/auth?name=admin&password=admin" -H "Accept: text/plain"

    • Using Swagger UI:

      1. Scroll to the Auth controller.
      2. Click on the GET /auth endpoint.
      3. Click on the Try it out button.
      4. Enter admin in the name field.
      5. Enter admin in the password field.
      6. Click on the Execute button.
      7. Copy the token from the response body.
      8. Click on the Authorize button in the top right corner.
      9. Paste the token into the Value field.
      10. Click on the Authorize button.

13. Try out the API endpoints using the Swagger UI, get runtimes for an example:

    • Using curl:

      curl -k -X GET "https://localhost:7169/workflow-api/data/runtimes" -H "Accept: application/json" -H "Authorization: Bearer PUT_YOUR_TOKEN_HERE"

    • Using Swagger UI:

      1. Scroll to the Runtimes controller.
      2. Click on the GET /workflow-api/data/runtimes endpoint.
      3. Click on the Try it out button.
      4. Click on the Execute button.

The solution consists of three projects:

• WorkflowApi — A sample web application that demonstrates how to use the OptimaJet.Workflow.Api library.
• WorkflowApi.Client — A sample WorkflowApi client application generated using OpenAPI specification.
• WorkflowApi.Client.Tests — An integration tests infrastructure project based on WorkflowApi client.
• WorkflowApi.Client.Data.Tests — An integration tests project for testing Data operations using WorkflowApi client.
• WorkflowApi.Client.Rpc.Tests — An integration tests project for testing RPC operations using WorkflowApi client.

When you run the build of the solution in the Debug configuration, an unusual build pipeline is used:

1. Build WorkflowApi.
2. After building WorkflowApi in debug configuration, the OpenAPI specification is generated by the Swashbuckle.AspNetCore.Cli tool and placed in ./WorkflowApi/.swagger.
3. After specification generation, ./WorkflowApi/.swagger/swagger.yaml is linted by executing ./Scripts/lint-swagger.ps1 script.
4. After the specification is linted, WorkflowApi.Client is generated by executing ./Scripts/build-client.ps1 and placed in the ./.generated folder.
5. In the same script, the generated client is copied to the ./WorkflowApi.Client project except for the WorkflowApi.Client.csproj file.
6. Build WorkflowApi.Client.
7. Build all tests projects.

Scripts are stored in the ./Scripts folder.

• build-client.ps1 - Generates the WorkflowApi.Client project using the OpenAPI specification in ./WorkflowApi/.swagger.
• lint-swagger.ps1 - Lints the OpenAPI specification generated at /WorkflowApi/.swagger/swagger.yaml using the dshanley/vacuum Docker image.
• Tests/run-tests.ps1 - Runs integration tests for the WorkflowApi.Client.Tests project. Ensure Docker is installed and running before executing. Has a -Providers parameter to specify the list of providers to test.
• Tests/create-containers.ps1 - Creates Docker containers for integration testing in the WorkflowApi.Client.Tests project. Ensure Docker is installed and running before executing. Has a -Providers parameter to specify the list of providers to test.
• Tests/remove-containers.ps1 - Removes containers created by the previous script. Ensure Docker is installed and running before executing. Has a -Providers parameter to specify the list of providers to remove.
• Tests/containers.json - Configuration for the created containers.

This section dives into the elements of this project to understand the general principles of the Workflow API and its implementation in this sample.

The AppBuilder class is used to build the ASP.NET WebApplication instead of configuring it in the Program class. This allows for easy integration testing, enabling another project to create multiple application hosts with predefined settings and send requests to them.

The Configuration class contains part of the application settings, which can be overridden in appsettings.json. During service configuration, an instance of this class is serialized from the initial configuration and then added back to include default settings. This configuration approach allows easy use in integration testing and substitution if necessary.

The application also adds several essential services, including controllers, authentication with authorization, Swagger generator, and DbContext. Each service has a ConfigureX method that takes an options object for configuration.

All possible Workflow API Data libraries are included in the application, and the provider is selected based on the Configuration.Provider setting. The provider's name chooses the connection string, with the default string used for the internal database of the Workflow API sample.

Finally, the WorkflowAPI is connected. In the ConfigureWorkflowApi method, you can configure options, although Workflow API Options also receive their initial settings from the configuration, allowing configuration in appsettings.json.

To demonstrate the Workflow API Security component, this project includes authentication and authorization using JWT Bearer, an authorization controller, and an in-memory SQLite database for storing user data.

To quickly get an API access token with all privileges, send a GET request to the auth controller with the username admin and password admin.

The auth controller has a POST method allowing you to create a new user with any set of privileges. Privileges are specified in dot format, such as workflow-api.readiness. You can learn more about privileges in the documentation or use the convenient builder in the IWorkflowApiPermissions service to get or validate a list of privileges.

The auth controller has a DELETE method to remove a user by their name. It also has a GET method to get a user from the database and create a list of claims for a JWT token based on their saved privileges. This token is then generated based on the JWT configuration and returned as a string.

Using the openapitools/openapi-generator-cli tool hosted in Docker, a C# client code for Workflow API is generated. This client is generated based on the swagger.yaml API specification. The client is essentially boilerplate code for working with API operations. It includes DTO classes for models, code for forming request objects, request settings, exception handling, creating an HTTP client, making requests, and data serialization and deserialization.

This tool can generate clients not only for C# but also for almost any popular language, such as TypeScript, Python, Go, Java, and many others. To generate your client, you can open the online Swagger editor, upload the specification, and select Generate Client → your language from the menu. Alternatively, you can use the client generation script in this repository and modify it to generate a client in an additional language.

To run automated testing, you need to install and run Docker, then execute the following command:

pwsh ./Scripts/Tests/run-tests.ps1

The tests are integration tests and use Docker databases, and start web application hosts in a separate thread, configuring them as needed for the tests. Each controller is tested in various use cases to ensure full coverage.

The tests also use an automatically generated client, so significant changes in the API specification will break the application's build and help understand where backward compatibility is violated and where tests need to be modified.

By default, testing is conducted for all data providers supported by Workflow Engine:

• Mongo: MongoDB
• Mssql: Microsoft SQL Server
• Mysql: MySQL
• Postgres: PostgreSQL
• Oracle: Oracle
• Sqlite: SQLite

To change the list of providers for testing, you need to pass the -Providers parameter to the script with a list of providers separated by commas (without spaces in parameter value). For example:

pwsh ./Scripts/Tests/run-tests.ps1 -Providers "Mongo","Mssql","Mysql","Postgres","Oracle","Sqlite"

Running tests for all providers can take a long time and require at least 24 GB of RAM. If you have less memory, you can run tests for a specific provider or a subset of providers.