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.
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 of 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.
Actions is the code executed in activities. You can read about them here.
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"
]
}
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 nameparameter
- 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
}
Conditions are the code responsible for logical branches in the processes. You can read about them here.
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"
]
}
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 methodExample of Response:
{
"success": true,
"data": true
}
The data
field contains the result of the condition execution: true or false.
Authorization Rules are the code responsible for Users' access to commands. You can read about them here.
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
Which of the callback servers is called to execute the method depends on the list of Authorization Rules returned.
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 methodExample of Response:
{
"success": true,
"data": false
}
If the access is granted, true
is written in the data
field; if no access, false
is returned.
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"]
}
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).schemeСode
- 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.
You can subscribe remote handlers for the two events: ProcessStatusChange
d 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.
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
}
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
}
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; }
}
Example of returning an error
{
"success": false,
"error": "error(exception) name",
"message": "error(exception) details"
}
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.