Callback API

General information

Callback API allows hosting your code of Actions, Conditions or Rules on third-party servers. Many Callback servers can be connected to the Workflow Server; thus, it is possible to connect the Workflow Server to a microservice architecture. Callback servers are connected in the admin panel on the Callback API page.

1. Settings for a callback server. Any number of such servers can be connected.
2. The basic part of the URL to send requests to the callback server. You can leave it blank, but then, the full url must be specified for each method.
3. The part of the URL responsible for calling a certain method. The final URL is formed as baseUrl/methodUrl. The available methods are described further.
4. For each request, you can add an authorization token.
5. The button for the test request.
6. The response to the test request will be displayed in this field.
7. The button for adding a new callback server.
8. To apply the settings, be sure to save all of them.

You can see an example of settings in our demo stand. The source code of the callback server the demo stand is connected to can be viewed here. This server is written in Javascript (node.js), it is quite simple. Now let us consider all the methods that can be implemented in the callback server. You do not need to implement all APIs on your callback servers, you can implement some of them if necessary.

Methods of Actions Execution

Actions is the code executed in activities. You can read about them here.

Getting a list of actions

Returns a list of actions that can be executed on the callback server. When the Workflow Server should execute an Action with a certain name, it calls the action execution method on the server that has returned this name in response to the request for the list of actions. The Workflow Server executes this request as GET; the request contains a single schemeCode parameter that contains the code of the scheme where this Action is executed. The request result is cached.

Example of Response:

{
  "success": true,
  "data": [
    "Action1",
    "Action2",
    "Action3"
  ]
}

Action execution

Request to execute the action. Which of the callback servers is called to execute this method, depends on the list of actions returned. The Workflow Server executes this request as POST, with the following parameters:

• processInstance - an instance with the process information. An example of such an instance is given below.
• name - a string, the action name.
• parameter - a string, the action parameter that can be set in the process scheme designer.
• token - a string - the access token to the method.

Example of Response:

{
  "success": true,
  "data": {
    "processParameter1": "someString",
    "processParameter2": 42,
    "processParameter3": {
      "objProp1": "someString",
      "objProp2": 42
    }
  }
}

In the data field, you can return the new process parameters in the form of an object, whose properties are named the same as the process parameters. In C# you can use Dictionary<string,object>, serialized to JSON. If you do not want to change the process parameters, then you can return null in this field.

{
  "success": true,
  "data": null
}

Methods of Conditions Execution

Conditions are the code responsible for logical branches in the processes. You can read about them here.

Getting a list of conditions

Returns a list of conditions that can be executed on the callback server. When the Workflow Server should execute a Condition with a certain name, it calls the condition execution method on the server that has returned this name in response to the request for the list of conditions. The Workflow Server executes this request as GET; the request contains a single schemeCode parameter that contains the code of the scheme where this Condition is executed. The request result is cached.

Example of Response:

{
  "success": true,
  "data": [
    "Condition1",
    "Condition2",
    "Condition3"
  ]
}

Condition execution

Request to execute the condition. Which of the callback servers is called to execute this method, depends on the list of conditions returned. The Workflow Server executes this request as POST, with the following parameters:

• processInstance - an instance with the process information. An example of such an instance is given below.
• name - a string, the condition name.
• parameter - a string, the condition parameter that can be set in the process scheme designer.
• token - a string - the access token to the method.

Example of Response:

{
  "success": true,
  "data": true
}

The data field contains the result of the condition execution: true or false.

Methods of Authorization Rules Execution

Authorization Rules are the code responsible for Users' access to commands. You can read about them here.

Getting rules

Returns a list of Authorization Rules that can be executed on the callback server. When the Workflow Server should execute an Authorization Rule with a certain name, it calls the Authorization Rule execution method on the server that has returned this name in response to the request for the list of Authorization Rules. The Workflow Server executes this request as GET; the request contains a single schemeCode parameter that contains the code of the scheme where this Authorization Rules is executed. The request result is cached.

Example of Response:

{
  "success": true,
  "data": [
    "CheckRole"
  ]
}

Each of Authorization Rules consists of the two functions

• Check - check if the User has the access to the command.
• Get identities - get the list of all Users who have the access. How these functions work is described in detail here.

Which of the callback servers is called to execute the method depends on the list of Authorization Rules returned.

Checking the rule

Check if the User has the access to the command. The Workflow Server executes this request as POST, with the following parameters:

• identityId - the User ID to check the access.
• processInstance - an instance with the process information. An example of such an instance is given below.
• name - a string, the Authorization Rule name.
• parameter - a string, the Authorization Rule parameter that can be set in the process scheme designer.
• token - a string - the access token to the method.

Example of Response:

{
  "success": true,
  "data": false
}

If the access is granted, true is written in the data field; if no access, false is returned.

Getting identities

Returns the list of all Users who have the access.

The Workflow Server executes this request as POST, with the following parameters:

• processInstance - an instance with the process information. An example of such an instance is given below.
• name - a string, the Authorization Rule name.
• parameter - a string, the Authorization Rule parameter that can be set in the process scheme designer.
• token - a string - the access token to the method.

Example of Response:

{
  "success": true,
  "data": [
    "userId1",
    "userId2",
    "userId3"
  ]
}

Methods of Remote Scheme Generation

Workflow Engine supports scheme generation. If you include this method, then, to initialize a new scheme, the Workflow Server calls it on all of the connected servers with the settings containing the address of this method. The first response that returns XML with the new scheme will be used as the new process scheme. The Workflow Server executes this request as POST, with the following parameters:

• parameters - a JSON object with the parameters for scheme generation (used quite rarely).
• schemeCode - the scheme code.
• schemeId - the scheme ID (used quite rarely).
• scheme - XML with the initial scheme saved in the scheme designer.
• token - a string - the access token to the method.

The method should return XML with the new scheme.

Event Handlers of Workflow Engine

You can subscribe remote handlers for the two events: ProcessStatusChanged and ProcessActivityChanged. When and how these events are called is described here. It should be noted that these handlers are called exclusively as notifications and the Workflow Server does not wait for this event to complete.

Process status changed

The ProcessStatusChanged event is called only after switching to the statuses of Idled and Finalized. It is not called for subprocesses. The Workflow Server executes this request as POST, with the following parameters:

• processInstance - an instance with the process information. An example of such an instance is given below.
• processId - the process ID.
• schemeCode - the scheme code.
• oldStatus - the old status of the process.
• newStatus - the new status of the process.
• token - a string - the access token to the method.

Example of Response:

{
  "success": true
}

Process activity changed

The ProcessActivityChanged event. The Workflow Server executes this request as POST, with the following parameters:

• processInstance - an instance with the process information. An example of such an instance is given below.
• processId - the process ID.
• schemeCode - the scheme code.
• transitionalProcessWasCompleted - true, if the transitional process is complete, i.e. the process was stopped.
• token - a string - the access token to the method.

Example of Response:

{
  "success": true
}

ProcessInstance object

The processInstance object has many fields. Here is an example of its implementation in C#:

  public class WorkflowServerProcessHistoryItem
    {
        public Guid Id { get; set; }
        public Guid ProcessId { get; set; }
        public string IdentityId { get; set; }
        public string AllowedToEmployeeNames { get; set; }
        public DateTime? TransitionTime { get; set; }
        public long Order { get; set; }
        public string InitialState { get; set; }
        public string DestinationState { get; set; }
        public string Command { get; set; }
    }

    public class TransitionItem
    {
        public Guid ProcessId { get; set; }
        public string ActorIdentityId{ get; set; }
        public string ExecutorIdentityId { get; set; }
        public string FromActivityName { get; set; }
        public string FromStateName { get; set; }
        public bool IsFinalised { get; set; }
        public string ToActivityName{ get; set; }
        public string ToStateName { get; set; }
        public string TransitionClassifier { get; set; }
        public DateTime TransitionTime { get; set; }
        public string TriggerName { get; set; }
    }

    public class ProcessInstance
    {
        public Guid Id  { get; set; }
        public string StateName { get; set; }
        public string ActivityName { get; set; }
        public Guid? SchemeId { get; set; }
        public string SchemeCode { get; set; }
        public string PreviousState { get; set; }
        public string PreviousStateForDirect { get; set; }
        public string PreviousStateForReverse { get; set; }
        public string PreviousActivity { get; set; }
        public string PreviousActivityForDirect { get; set; }
        public string PreviousActivityForReverse { get; set; }
        public Guid? ParentProcessId { get; set; }
        public Guid? RootProcessId { get; set; }
        public bool IsDeterminingParametersChanged { get; set; }
        public byte InstanceStatus { get; set; }
        public bool IsSubProcess { get; set; }
        public string TenantId { get; set; }

        public List<TransitionItem> Transitions { get; set; }
        public List<WorkflowServerProcessHistoryItem> History { get; set; }
        public Dictionary<string, object> ProcessParameters { get; set; }
        public List<Guid> SubProcessIds { get; set; }
    }

Returning Error from Callback Server

Example of returning an error:

{
  "success": false,
  "error": "error(exception) name",
  "message": "error(exception) details"
}

Cache Configuration

The Workflow Server caches the lists of Actions, Conditions and Rules returned by Callback Servers. Moreover, the Workflow Server remembers which of the Callback Servers executes a certain method. The cache time is set by the CallBackCacheTimeout setting in the configuration file:

{
    "CallBackCacheTimeout": 300000, // 5 min
}

The value is specified in milliseconds. The absence of this setting disables caching.