Workflow API

General information

Workflow API serves to interact with process instances and some other auxiliary operations of Workflow Server (for example, working with users, stopping timers in a server instance, etc.). The comprehensive Workflow API documentation is included in the server admin.

This page contains a list of all Workflow API methods available, forms for test requests, all parameters description and code examples that can be copied and pasted directly into your application.

1. The name and description of the chosen API method.
2. The URL format to be used.
3. The button for opening / closing a form with the method parameters.
4. The button for testing and sending a request with the filled-in parameters to the server.
5. The button for managing the created instances.
6. The result of the request execution.
7. All method parameters.
8. In this window, the generated code which can be copied and pasted into your program to call the Workflow API method. Besides, it can be in two languages: javascript and C#.

Token Access Using OpenIddict

Starting from Workflow Server 9.0.0, OpenIddict is used exclusively for authentication. To obtain an accessToken, configure OpenId Connect following this guide.

First, let us describe the process of obtaining an access token manually. This is essential to understand the method, but, as a rule, it is recommended to use ready-made libraries.

1. Register your Client Credentials

You can register your Client Credentials using the config.json file:

{
  ...
  "DisableOpenIddictServer": false,
  "OpenIddictServerSettings": {
    ...
    "ClientCredentials": [
      {
        "ClientId": "workflowapi",
        "ClientSecret": "e3e3506c-1a2e-4e35-b6c6-2ecced416e07"
      }
    ]
  }, 
  ...
}

Alternatively, you can register them programmatically in Program.cs using WorkflowServerRuntime.RegisterOpenIdConnectClientCredentials method:

using OpenIddict.Abstractions;
using OpenIddict.Client;
using OptimaJet.WorkflowServer.OpenIddict;
...
(bool success, IWebHost host) = initializer.BuildWebHost(workflowServer =>
{
    //Register your own Action and Rule providers
    //workflowServer.RegisterActionProvider(new ActionProvider());
    //workflowServer.RegisterRuleProvider(new RuleProvider());

    //Register your own CodeAutocompleter
    //workflowServer.RegisterCodeAutocompleters(new CodeProvider());

    //Register your own Identity Providers:
    workflowServer.RegisterOpenIdConnectProviders(authBuilder =>
    {
        ...
    });

    // Register your own Client Credentials
    workflowServer.RegisterOpenIdConnectClientCredentials(new ClientCredential("workflowapi",
        "e3e3506c-1a2e-4e35-b6c6-2ecced416e07"));

    //register additional assemblies
    WorkflowRuntime.CodeActionsRegisterAssembly(typeof(System.Net.Http.HttpClient).Assembly);
});

info

When entering the same ClientId, priority is given to the RegisterOpenIdConnectClientCredentials method.

2. Discover the OpenIddict Endpoints

Open the following URL in your browser: https://localhost:8077/.well-known/openid-configuration.
You'll receive a JSON document describing all available endpoints of the OpenIddict server. In particular, note the following field:

"token_endpoint": "https://localhost:8077/connect/token"

This is the endpoint used to obtain access tokens.

3. Request an Access Token

To get an access token for the Workflow API, send a POST request to the token_endpoint. The request body must contain the parameters client_id, client_secret and grant_type, encoded as application/x-www-form-urlencoded.
Example Request:

POST /connect/token HTTP/1.1
Host: localhost:8077
Content-Type: application/x-www-form-urlencoded
Content-Length: 194

client_id=workflowapi
client_secret=e3e3506c-1a2e-4e35-b6c6-2ecced416e07
grant_type=client_credentials

The server will return a JSON response containing the access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

4. Use the Access Token with Workflow API

Include the obtained access_token in the Authorization header for every API request.
Example Request:

POST /workflowapi/createinstance/f54104f0-5de2-ea7b-e3be-47c9199a3967 HTTP/1.1
Host: localhost:8077
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkRDQTJFMTI2Nzg4QkY2RjZFQjU3MDY4NjAwQzc3RENDMzlFRkNGRTRSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IjNLTGhKbmlMOXZiclZ3YUdBTWQ5ekRudnotUSJ9.eyJuYmYiOjE2MDY5ODgyMDUsImV4cCI6MTYwNjk5MTgwNSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDc3IiwiYXVkIjoiV29ya2Zsb3dBcGkiLCJjbGllbnRfaWQiOiJ3b3JrZmxvd2FwaSIsImp0aSI6IjYwQzE3NTZBRkU4REFDQTY4M0Y0QzVDNkU4RDMwRkE3IiwiaWF0IjoxNjA2OTg4MjA1LCJzY29wZSI6WyJXb3JrZmxvd0FwaSJdfQ.auuTeD3hEBl40ZEXK58oSIGyHihuTMTxsFf_qAOeScsw4bcYz7YFVNWQqUPgx7Cno541wKMz70oOwO01M2Es31u9lN87y-jCJCn721vbGQeOXqXAlqztGUB5cJiTerOgVK_Fp4IMpm7TFQdzDKN42k3TPIX4IjOVBnc3bINXCtDnr5iteaLYcvwYI1vU-WyYqjfW4KCcEqwCjUA3F6eUYVMuXIsejD6DTI-7hwLqTP1Hopdtmq5x6W38kBcg1I-LrqPhLpg2-tj0xE7CcqttDWSC0G3wEjO04rflDkA0R58iDOgIuMhcPPZGaT8pAwhA5E0pkEjvIHKBV0aaeJ9pug
Content-Length: 37

{
    "schemeCode" : "TestScheme"
}