Merge pull request #23799 from abpframework/elsa-pro-document

Add documentation for Elsa Pro module

docs/en/docs-nav.json

@@ -2443,6 +2443,10 @@
           "text": "Docs",
           "path": "modules/docs.md"
         },
+        {
+          "text": "Elsa (Pro)",
+          "path": "modules/elsa-pro.md"
+        },
         {
           "text": "Feature Management",
           "path": "modules/feature-management.md"
@@ -2655,6 +2659,10 @@
         {
           "text": "Easy CRM",
           "path": "samples/easy-crm.md"
+        },
+        {
+          "text": "ElsaWorkflows",
+          "path": "samples/elsa-workflows-demo.md"
         }
       ]
     },

docs/en/modules/elsa-pro.md

@@ -0,0 +1,134 @@
+# Elsa Module (Pro)
+
+> You must have an ABP Team or a higher license to use this module.
+
+This module integrates [Elsa Workflows](https://docs.elsaworkflows.io/) into ABP Framework applications and is designed to make it easy for developers to use Elsa's capabilities within their ABP-based projects. For creating, managing, and customizing workflows themselves, please refer to [the official Elsa documentation](https://docs.elsaworkflows.io/).
+
+## How to install
+
+The Elsa module is not installed in [the startup templates](../solution-templates/layered-web-application) by default and must be installed manually. There are two ways of installing a module into your application and each one of these approaches is explained in the next sections.
+
+### Using ABP CLI
+
+ABP CLI allows adding a module to a solution using the ```add-module``` command. You can check its [documentation](../cli#add-module) for more information. So, the Elsa module can be added using the following command:
+
+```bash
+abp add-module Volo.Elsa
+```
+
+### Manual Installation
+
+If you modified your solution structure, adding the module using ABP CLI might not work for you. In such cases, you can add the Elsa module into your solution manually.
+
+In order to do that, add packages listed below to the matching project in your solution. For example, `Volo.Abp.Elsa.Application` package to your **{ProjectName}.Application.csproj** as shown below:
+
+```xml
+<PackageReference Include="Volo.Abp.Elsa.Application" Version="x.x.x" />
+```
+
+After adding the package references, open the module class of the project (e.g.: `{ProjectName}ApplicationModule`) and add the code below to the `DependsOn` attribute:
+
+```csharp
+[DependsOn(
+  //...
+  typeof(AbpElsaApplicationModule)
+)]
+```
+
+> If you are using Blazor Web App, you need to add the `Volo.Elsa.Admin.Blazor.WebAssembly` package to the **{ProjectName}.Blazor.Client.csproj** project and add the `Volo.Elsa.Admin.Blazor.Server` package to the **{ProjectName}.Blazor.csproj** project.
+
+## The Elsa Module
+
+The Elsa Workflows has its own database provider, and also has a Tenant/Role/User system. They are under active development, so the ABP Elsa module is not yet fully integrated. Below is the current status of each module in the ABP's Elsa Module:
+
+- `AbpElsaAspNetCoreModule(Volo.Elsa.Abp.AspNetCore)` module is used to integrate Elsa authentication.
+- `AbpElsaIdentityModule(Volo.Elsa.Abp.Identity)` module is used to integrate ABP Identity authentication.
+- `AbpElsaApplicationModule(Volo.Elsa.Abp.Application)` and `AbpElsaApplicationContractsModule(Volo.Elsa.Abp.Application.Contracts)` modules are used to define the Elsa permissions.
+
+The rest of the projects/modules are basically empty and will be implemented in the future based on the Elsa features:
+
+- `AbpElsaDomainModule(Volo.Elsa.Abp.Domain)`
+- `AbpElsaEntityFrameworkCoreModule(Volo.Elsa.Abp.EntityFrameworkCore)`
+- `AbpElsaHttpApiModule(Volo.Elsa.Abp.HttpApi)`
+- `AbpElsaHttpApiClientModule(Volo.Elsa.Abp.HttpApi.Client)`
+- `AbpElsaBlazorModule(Volo.Elsa.Abp.Blazor)`
+- `AbpElsaBlazorServerModule(Volo.Elsa.Abp.Blazor.Server)`
+- `AbpElsaBlazorWebAssemblyModule(Volo.Elsa.Abp.Blazor.WebAssembly)`
+- `AbpElsaWebModule(Volo.Elsa.Abp.Web)`
+
+### Elsa Module Permissions
+
+The Elsa Workflow API endpoints check permissions. Also, it has a `*` wildcard permission to allow all permissions.
+
+The ABP Elsa module defines all permissions that are used in the Elsa workflow. You can use ABP Permission Management module to manage the permissions.
+
+`AbpElsaAspNetCoreModule(Volo.Elsa.Abp.AspNetCore)` module will check and add these permissions to the current user's claims:
+
+![Elsa Permissions](../images/elsa-permissions.png)
+
+You can also grant parts of the permissions to a role or user. It will add the `permissions` claims to the current user's `Cookies` or `Token`. Elsa Server will read the claims and allow or deny access:
+
+![Elsa Part Permissions](../images/elsa-part-permissions.png)
+
+### Elsa Studio
+
+Elsa Studio is an **independent** web application that allows you to design, manage, and execute workflows. It is built using **Blazor Server/WebAssembly**.
+
+Elsa Studio requires authentication and there are two ways to authenticate Elsa Studio:
+
+* Password Flow Authentication
+* Code Flow Authentication
+
+#### Elsa Studio - Password Flow Authentication
+
+The `AbpElsaIdentityModule(Volo.Elsa.Abp.Identity)` module is used to integrate with [ABP Identity module](./identity-pro.md) to check Elsa Studio *username* and *password* against ABP Identity. 
+
+You need to replace `UseIdentity` with `UseAbpIdentity` when configuring Elsa in your Elsa server project as follows:
+
+```csharp
+context.Services
+    .AddElsa(elsa => elsa
+        .UseAbpIdentity(identity =>
+        {
+            identity.TokenOptions = options => options.SigningKey = "large-signing-key-for-signing-JWT-tokens";
+        });
+    );
+```
+
+After that, you can add the below code to use `Identity` as the login method in your Elsa Studio client project:
+
+```csharp
+builder.Services.AddLoginModule().UseElsaIdentity();
+```
+
+Then, you can log in to the Elsa Studio application with the default credentials (`admin` as the username, and `1q2w3E*` as the password):
+
+![elsa-login](../images/elsa-password-login.png)
+
+Once, you logged in to the application, you can start defining workflows, manage them and see their execution instances and more:
+
+![elsa-main](../images/elsa-main-page.png)
+
+#### Elsa Studio - Code Flow Authentication
+
+ABP applications use [OpenIddict](./openiddict-pro.md) for authentication. So, you can use the [Authorization Code Flow](https://oauth.net/2/grant-types/authorization-code/) to authenticate Elsa Studio.
+
+To do that, you can add the code block below to your Elsa Studio client project:
+
+```csharp
+builder.Services.AddLoginModule().UseOpenIdConnect(connectConfiguration =>
+{
+    var authority = configuration["AuthServer:Authority"]!.TrimEnd('/'); // Your Server URL
+    connectConfiguration.AuthEndpoint = $"{authority}/connect/authorize";
+    connectConfiguration.TokenEndpoint = $"{authority}/connect/token";
+    connectConfiguration.EndSessionEndpoint = $"{authority}/connect/endsession";
+    connectConfiguration.ClientId = configuration["AuthServer:ClientId"]!;
+    connectConfiguration.Scopes = ["openid", "profile", "email", "phone", "roles", "offline_access", "ElsaDemoAppServer"];
+});
+```
+
+After that, Elsa Studio will redirect to your ABP application's login page, then redirect back to Elsa Studio after the successful login.
+
+### Elsa Workflows - Sample Workflow Demo
+
+ABP provides a complete demo application that shows how to use the Elsa module in your ABP application. You can download the demo application and see the integration points, if you stuck at any point. Please see the [Elsa Workflows - Sample Workflow Demo](../samples/elsa-workflows.md) page for more information.

docs/en/samples/elsa-workflows-demo.md

@@ -0,0 +1,73 @@
+# Elsa Workflows - Sample Workflow Demo
+
+The `ElsaDemoApp` is a sample application that demonstrates how to use the [Elsa](https://github.com/elsa-workflows/elsa-core) module in an ABP application. The demo application consists of four projects:
+
+- `ElsaDemoApp.Server` is an ABP application with Identity and Elsa modules. It is used as the authentication server and Elsa workflow server.
+- `ElsaDemoApp.Studio.WASM` is a Blazor WebAssembly application with Elsa Studio. It is used as the Elsa Studio client application.
+- `ElsaDemoApp.Ordering` and `ElsaDemoApp.Payment` are two microservices that can be used to test the Elsa workflows in distributed systems.
+
+![Elsa Module Structure](../images/elsa-module-structure.png)
+
+> **This sample workflow demonstrates how to integrate ABP with Elsa Workflows.** For more detailed information about Elsa itself, please refer to the official [Elsa documentation](https://docs.elsaworkflows.io/) and related guides.
+
+## Download
+
+> **Note:** The `ElsaDemoApp` sample application is only for the **ABP customers**. Therefore, you need to have a commercial license to be able to download the source code.
+
+* You can download the complete source-code from [https://abp.io/api/download/samples/elsaworkflow](https://abp.io/Account/Login?returnUrl=/api/download/samples/elsaworkflow)
+
+## Running the Demo Application
+
+The `ElsaDemoApp.Server` has a pre-defined Elsa workflow that creates an order and processes the payment using Elsa workflows, and uses ABP distributed event bus to coordinate the workflow.
+
+Here is the complete workflow in code:
+
+```cs
+public class OrderWorkflow : WorkflowBase
+{
+    public const string Name = "OrderWorkflow";
+
+    protected override void Build(IWorkflowBuilder builder)
+    {
+        builder.WithDefinitionId(Name);
+        builder.Root = new Sequence
+        {
+            Activities =
+            {
+                // Will publish NewOrderEto event to the Ordering microservice,  Ordering microservice will create the order and publish OrderPlaced event
+                new CreateOrderActivity(),
+
+                // Wait for the OrderPlaced event, This event is triggered by the Ordering microservice, and Elsa will make workflow continue to the next activity
+                new OrderPlacedEvent(),
+
+                // This activity will publish RequestPaymentEto event to the Payment microservice, Payment microservice will process the payment and publish PaymentCompleted event
+                new RequestPaymentActivity(),
+
+                //  Wait for the PaymentCompleted event, This event is triggered by the Payment microservice, and Elsa will make workflow continue to the next activity
+                new PaymentCompletedEvent(),
+
+                // This activity will send an email to the customer indicating that the payment is completed
+                new PaymentCompletedActivity()
+            }
+        };
+    }
+}
+```
+
+> The demo application uses SQL Server LocalDB as the database provider, Redis as the caching server and RabbitMQ for the message broker. Please make sure you have them installed and running on your machine and then follow the instructions below to run the application.
+
+You can apply the following steps to run the demo application:
+
+1. Run `ElsaDemoApp.Server` project to migrate the database(`dotnet run --migrate-database`) and start the server.
+2. Run `ElsaDemoApp.Studio.WASM` project to start the Elsa Studio client application.
+3. Run `ElsaDemoApp.Ordering` project to start the Ordering microservice.
+4. Run `ElsaDemoApp.Payment` project to start the Payment microservice.
+
+After running all the applications, you can log in to the `ElsaDemoApp.Server` application (with the default credentials) and navigate to the `https://localhost:5001/Ordering` page to create an order:
+
+![Create Order](../images/elsa-create-order.png)
+
+After that, you can navigate to the `ElsaDemoApp.Studio.WASM` application and see the workflow instance created, running, and completed:
+
+![Workflow Instances](../images/elsa-workflow-instances.png)
+