Entwickler Tutorial (Legacy)
Starten und Warten auf das Ende eines Prozesses

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

  1. 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.

Program.cs
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.

Program.cs
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:

Program.cs
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(); 60
Program.cs
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(); 60

Starten 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

Program.cs
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

Program.cs
string startEventId = "",
object initialToken = null,
string correlationId = "",
string callerId = "",
CancellationToken cancellationToken = default (CancellationToken)

Erklärung zu den aufgeführten Parametern

  • startEventId dient dazu, den Prozess von einem bestimmten Start Event aus zu starten. Der Parameter ist Pflicht, wenn der Prozess mehrere Start Events besitzt.
  • initialToken kann verwendet werden, um den Prozess mit einer eigenen Payload zu starten.
  • correlationId bietet die Möglichkeit mehrere Prozessinstanzen fachlich zu gruppieren
  • callerId sollte genutzt werden, wenn der zu startende Prozess ein Sub-Prozess ist. Durch diese ID kann der Parent-Prozess angesprochen werden.
  • cancellationToken wird verwendet, um Prozesse abzubrechen.

Beispiel Start eines Prozesses mit optionalen Parametern

Program.cs
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():

Program.cs
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.

processInstance kann null sein, wenn keine Prozessinstanz gefunden wurde. EndToken kann null sein, wenn die Prozessinstanz noch läuft.

Program.cs
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:

MyPayloadType.cs
namespace My.Cool.Projekt.MyPayloadType;
 
public class MyPayloadType
{
    public int Number { get; set; }
    public string? Text { get; set; }
    public bool IsValid { get; set; }
}
⚠️
Neue Dateien müssen in der docker-compose.yaml gemounted werden.

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.

Program.cs
using My.Cool.Project.MyPayloadType;

Als nächstes können wir nun unterhalb der startResponse Initialisation auf die resultPayload zugreifen:

Program.cs
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:

Program.cs
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.

Downloads

Prozesse