Starten und Warten auf das Ende eines Prozesses
Grundlegend können Prozesse im Portal, im Studio oder im Code selbst gestartet werden. Letzteres ist vor allem sinnvoll, wenn man den Start eines Prozesses automatisieren möchte. Im folgenden Kapitel soll erläutert werden, wie ein Prozess direkt aus dem Code heraus (ohne ausführen im Portal) gestartet werden kann. Dazu wird der Process-Definitions-Client in .NET genutzt.
Voraussetzungen
- NuGet-Paket
AtlasEngine.Client(bereits im Kapitel Projekt erstellen installiert) - Eine Instanz der 5Minds-Engine
- Der genutzte Prozess deployed auf der Engine
Process-Definitions-Client
Um einen Prozess in .NET zu starten, wird eine Instanz des ProcessDefinitionsClients benötigt.
Das Instanziieren des Clients geschieht mithilfe der ClientFactory mittels der Methode CreateProcessDefinitionsClient().
Die Methode hat folgende Parameter
- Engine-
Uri
Die ClientFactory ist im NuGet-Paket AtlasEngine.Client enthalten.
Um einen Prozess auszuführen, wird eine 5Minds-Engine-Instanz benötigt.
In diesem Fall wird die Engine aus dem Template (http://engine:8000) verwendet. Das folgende Codebeispiel kann nun in die Datei Program.cs
geschrieben werden.
Es ist darauf zu achten, dass alle folgenden Beispiele oberhalb des
app.Run()Funktionsaufrufs zu implementieren sind.
var engineUri = new Uri("http://engine:8000");
var processDefinitionClient = ClientFactory.CreateProcessDefinitionsClient(engineUri);Starten eines Prozesses
Mit dem erstellten Client ist es nun möglich, Prozesse über die Methode StartProcessInstanceAsync() zu starten. Die ID des zu startenden
Prozesses muss dabei als Parameter übergeben werden.
Die Methode ist asynchron und erfordert daher ein await Statement beim Aufruf.
Es ist darauf zu achten, dass der Prozess vorher auf der Engine deployed werden muss.
var processModelId = "example";
var startResponse = await processDefinitionClient.StartProcessInstanceAsync(processModelId);Die zurückgegebene StartProcessInstanceResponse beinhaltet die ProcessInstanceId und ermöglicht dadurch
die Verfolgung und weitere Verwaltung des gestarteten Prozesses.
Die Datei Program.cs könnte dann mit den oben genannten Implementierungen so aussehen:
1using AtlasEngine;
2using AtlasEngine.ApiClient;
3
4using Template.ProcessCube.Project.Worker.Example;
5
6var builder = WebApplication.CreateBuilder(args);
7
8builder.Services.AddSpaYarp();
9
10// Add services to the container.
11builder.Host.UseExternalTaskWorkers();
12builder.Services.AddControllers();
13builder.Services.Configure<ApiClientSettings>(builder.Configuration.GetSection("AtlasEngine"));
14builder.Services.AddScoped<ExampleHandler>();
15
16// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
17builder.Services.AddEndpointsApiExplorer();
18builder.Services.AddSwaggerGen();
19
20var app = builder.Build();
21
22if (app.Environment.IsDevelopment())
23{
24 app.UseSwagger();
25 app.UseSwaggerUI();
26}
27// Configure the HTTP request pipeline.
28if (!app.Environment.IsDevelopment())
29{
30 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
31 app.UseHsts();
32}
33
34app.UseHttpsRedirection();
35
36app.UseCors(x => x
37 .AllowAnyOrigin()
38 .AllowAnyMethod()
39 .AllowAnyHeader());
40
41app.UseStaticFiles();
42app.UseRouting();
43
44app.MapControllerRoute(
45 name: "default",
46 pattern: "{controller}/{action=Index}/{id?}");
47
48app.UseSpaYarp();
49
50app.UseWebSockets();
51
52app.MapFallbackToFile("index.html");
53
54var engineUri = new Uri("http://engine:8000");
55var processDefinitionClient = ClientFactory.CreateProcessDefinitionsClient(engineUri);
56var processModelId = "ProzessId";
57var startResponse = await processDefinitionClient.StartProcessInstanceAsync(processModelId);
58
59app.Run();
601using AtlasEngine;
2using AtlasEngine.ApiClient;
3
4using Template.ProcessCube.Project.Worker.Example;
5
6var builder = WebApplication.CreateBuilder(args);
7
8builder.Services.AddSpaYarp();
9
10// Add services to the container.
11builder.Host.UseExternalTaskWorkers();
12builder.Services.AddControllers();
13builder.Services.Configure<ApiClientSettings>(builder.Configuration.GetSection("AtlasEngine"));
14builder.Services.AddScoped<ExampleHandler>();
15
16// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
17builder.Services.AddEndpointsApiExplorer();
18builder.Services.AddSwaggerGen();
19
20var app = builder.Build();
21
22if (app.Environment.IsDevelopment())
23{
24 app.UseSwagger();
25 app.UseSwaggerUI();
26}
27// Configure the HTTP request pipeline.
28if (!app.Environment.IsDevelopment())
29{
30 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
31 app.UseHsts();
32}
33
34app.UseHttpsRedirection();
35
36app.UseCors(x => x
37 .AllowAnyOrigin()
38 .AllowAnyMethod()
39 .AllowAnyHeader());
40
41app.UseStaticFiles();
42app.UseRouting();
43
44app.MapControllerRoute(
45 name: "default",
46 pattern: "{controller}/{action=Index}/{id?}");
47
48app.UseSpaYarp();
49
50app.UseWebSockets();
51
52app.MapFallbackToFile("index.html");
53
54var engineUri = new Uri("http://engine:8000");
55var processDefinitionClient = ClientFactory.CreateProcessDefinitionsClient(engineUri);
56var processModelId = "ProzessId";
57var startResponse = await processDefinitionClient.StartProcessInstanceAsync(processModelId);
58
59app.Run();
60Starten und gleichzeitiges Erwarten des Endes eines Prozesses
Über die Methode StartProcessInstanceAndAwaitEndEventAsync() kann ein Prozess gestartet und bis zu dessen Ende gewartet werden. Die Methode
nimmt dieselben Parameter wie die StartProcessInstanceAsync() Methode.
Es ist darauf zu achten, dass der Prozess vorher auf der Engine deployed werden muss
var processModelId = "example";
var endResponse = await processDefinitionClient.StartProcessInstanceAndAwaitEndEventAsync(processModelId);Anders als bei der StartProcessInstanceAsync() Methode, ist der Rückgabewert vom Typ StartProcessInstanceAndAwaitEndEventResponse,
welche neben der ProcessInstanceId noch eine EndEventId sowie eine TokenPayload beinhaltet.
Weitere Startparameter
Neben der ID des zu startenden Prozessmodells, können auch noch folgende optionale Parameter angegeben werden
string startEventId = "",
object initialToken = null,
string correlationId = "",
string callerId = "",
CancellationToken cancellationToken = default (CancellationToken)Erklärung zu den aufgeführten Parametern
startEventIddient dazu, den Prozess von einem bestimmten Start Event aus zu starten. Der Parameter ist Pflicht, wenn der Prozess mehrere Start Events besitzt.initialTokenkann verwendet werden, um den Prozess mit einer eigenen Payload zu starten.correlationIdbietet die Möglichkeit mehrere Prozessinstanzen fachlich zu gruppierencallerIdsollte genutzt werden, wenn der zu startende Prozess ein Sub-Prozess ist. Durch diese ID kann der Parent-Prozess angesprochen werden.cancellationTokenwird verwendet, um Prozesse abzubrechen.
Beispiel Start eines Prozesses mit optionalen Parametern
var processModelId = "UntypedStartEventTest";
var startEventId = "StartEvent";
var initialToken = new { Number = 1337, Text = "test", IsValid = true };
var correlationId = "e8eee364-d20f-4e17-b34d-d8bdc26d1bda";
var cancellationToken = new CancellationToken();
var startResponse = await processDefinitionClient.StartProcessInstanceAsync(processModelId, startEventId, initialToken, correlationId, null, cancellationToken);Prozess erwarten
Ein gestarteter, aber nicht abgeschlossener Prozess kann mittels des ProcessInstancesClient überprüft, erwartet oder beendet werden.
Eine Instanz des ProcessInstancesClient ist ebenfalls mithilfe der ClientFactory erstellbar. Dazu können wir eine ähnliche Implementierung zu der
bereits bekannte Implementierung von oben benutzen. Statt der CreateProcessDefinitionsClient() benutzen wir hier nun CreateProcessInstancesClient():
var engineUri = new Uri("http://engine:8000");
var processInstancesClient = ClientFactory.CreateProcessInstancesClient(engineUri);
var processDefinitionClient = ClientFactory.CreateProcessDefinitionsClient(engineUri);
var processModelId = "example";
var startResponse = await processDefinitionClient.StartProcessInstanceAsync(processModelId);Mithilfe der QueryAsync() Methode ist es möglich, nach bestimmten Prozessinstanzen zu suchen.
Es ist darauf zu achten, dass die Methode nach dem Start des Prozesses und vor dem Funktionsaufruf
app.Run()implementiert werden muss.
Der Rückgabewert ist eine IEnumerable vom Typ ProcessInstance.
Da in diesem Fall aber nur eine Prozessinstanz vorhanden ist, wird mit FirstOrDefault() direkt auf diesen zugegriffen.
Über die Methode FilterByProcessInstanceId() wird ein Filter erstellt, der mit Hilfe der ID aus startResponse.processInstanceId
nach der gestarteten Prozessinstanz sucht.
processInstancekannnullsein, wenn keine Prozessinstanz gefunden wurde.EndTokenkannnullsein, wenn die Prozessinstanz noch läuft.
var processInstance = (
await processInstancesClient.QueryAsync(
options => options.FilterByProcessInstanceId(startResponse.ProcessInstanceId)
)
).FirstOrDefault();Ergebnis Token auslesen
Ergebnis Token auslesen bei einem erwarteten Prozess
Wurde die zurückgegebene Prozessinstanz bereits beendet, kann das Ergebnis der Prozessinstanz abgefragt werden. Dafür muss eine Datei MyPayloadType.cs
im Projekt im Ordner apps/My.Cool.Project erstellt und mit folgendem Code implementiert werden:
namespace My.Cool.Projekt.MyPayloadType;
public class MyPayloadType
{
public int Number { get; set; }
public string? Text { get; set; }
public bool IsValid { get; set; }
}Anschließend kann in der Program.cs Datei über den namespace die MyPayloadType.cs Datei referenziert werden. Dazu fügen wir oben im Bereich der
anderen using Tags unsere Referenz hinzu.
using My.Cool.Project.MyPayloadType;Als nächstes können wir nun unterhalb der startResponse Initialisation auf die resultPayload zugreifen:
var processInstance = (
await processInstancesClient.QueryAsync(
options => options.FilterByProcessInstanceId(startResponse.ProcessInstanceId)
)
).FirstOrDefault();
var resultPayloadString = processInstance?.EndToken?.RawPayload;
var resultPayloadType = processInstance?.EndToken?.GetPayload<MyPayloadType>();Bei unserem aktuellen Example Prozess endet der Prozess erst nach Ausführung der User Task. Deswegen ist beim
Ausführen der Datei die resultPayload noch null, weil der Prozess noch nicht beendet wurde.
Ergebnis Token auslesen bei einem gestarteten und erwarteten beendeten Prozess
Wurde ein Prozess mittels StartProcessInstanceAndAwaitEndEventAsync() gestartet und erwartet beendet (wie hier
beschrieben), kann das Ergebnis Token durch EndToken.RawPayload
entweder direkt als string ausgelesen und manuell deserialisiert werden
oder mittels EndToken.GetPayload<TPayload>() direkt in den gewünschten Typen deserialisiert werden.
Beispiel:
var processModelId = "example";
var endResponse = await processDefinitionClient.StartProcessInstanceAndAwaitEndEventAsync(processModelId);
var resultPayloadString = endResponse?.TokenPayload?.RawPayload;
var resultPayloadType = endResponse?.TokenPayload?.GetPayload<MyPayloadType>();endResponse kann null sein, wenn kein Prozess-Model gefunden wurde. TokenPayload kann null sein, wenn kein
Ergebnis Token vorhanden ist. Verwendet man den Example Prozess, ist die resultPayload null, weil der Prozess noch
nicht zu Ende ist und auf einen User Task wartet.