Service Flow Engine
This chapter describes the basic elements and patterns of diagrams created using the service flow engine.
1. Service Flow Diagram
AnyLink provides functionalities for linking and orchestrating various adapters and services via the service flow engine. AnyLink connects incoming and outgoing services via a service flow to handle additional tasks or create new values.
AnyLink service flows use Business Process Modeling Notation (BPMN), which is the standard used for modelling business processes. Diagrams in the BPMN format are stored in the Service Flow Description Language (SFDL) format, which is an XML document format.
1.1. Basic Elements of Service Flow Diagrams
The following is a description of the basic elements of service flow diagrams.
-
Service Flow
Called a process and consists of activities, events, and transitions.
-
Activity
Called a task, and represents the tasks to be executed when a flow reaches the applicable position in the service flow.
-
Transition
An arrow indicating the order of a flow between activities or events.
-
Event
A special activity that indicates events such as messages, errors, and timeouts. Events consist of start events which do not have incoming transitions, intermediate events which have both incoming and outgoing transitions, and end events which do not have outgoing transitions.
EventsBoundary events, which are a special form of intermediate events, are events that are positioned at the boundary of an activity or block, and if there is an event that occurs at the time a block or activity is activated, it will split off to the boundary event.
Boundary Event -
Gateway
A special activity type used for controlling flows. It consists of a split gateway which splits off a single transition flow to multiple transition flows, and a join gateway which joins multiple transition flows into a single transition flow.
Gateways
1.2. Service Flow Parallel Processing
AnyLink service flows are executed in the service flow engine of the runtime engine server.
Typically, an instance of a service flow defined by a message delivered by an inbound adapter is created. A message or timer information sent to a service flow is called a trigger in a service flow.
Typically, a service flow generated by a single trigger is executed with a single thread. However, an SFDL that defines service flows can be split off in parallel or joined.
The AnyLink service flow engine can also execute a single service flow instance simultaneously with multiple threads according to the service flow diagram type. As well, the AnyLink service flow engine is designed in a way so that when a service flow is created and the flow is processed, the usage of threads (which are system resources) is maximized and multiple threads are simultaneously processed.
The service call thread (thread 1) does not wait for a response after sending a request. The service response processing thread (thread 2) is created in an adapter when a response is received.
1.3. Diagram Graphs and Block Structure
An AnyLink service flow is based on a graph structure in which activities are connected with arrows. The graph structure has the advantage of being intuitive and flexible because it can express flows in the way a person thinks.
Each activity, transition (represented by arrows), and gateway (which represents splitting off and joining of various flows) efficiently represents the service flow of such graph structure.
When handling events and exceptions that occur in a particular area, it is efficient to group them together and express them. Typically, a grouping of a particular flow is called a block.
In programming languages like Java, the basic execution unit is a block or function that groups together multiple statements. Errors that are generated in a particular block or function can be handled by a single error processing logic. In an AnyLink flow, the grouping of activities is called a subprocess or a block.
Events such as errors or timeouts that occur during the execution of an activity or transaction in a block move according to the error event or timer event attached to the block boundary. Typically, a good process consists of a graph structure and a block structure. An AnyLink service flow partially supports the block structure based on the graph structure.
In an AnyLink service flow diagram, boundary events that are attached at the boundary between a block activity and another block activity are examples of implementing the flow of the block structure.
In addition to block activities, error handlers can be specified in service flows, which means errors generated when executing service flows can be handled. This can be thought of as a form of a block structure.
2. Basic Pattern
As shown in the previous AnyLink service flow diagram, flows are expressed by combining the graph structure and block structure based on the BPMN standard.
This section describes the commonly used service flow patterns.
2.1. Basic Flow Pattern
The following describes the basic flow patterns.
-
Sequential Execution
Sequential flows are the most basic flows, and an activity is executed after activities prior to it finish executing.
Sequential Execution -
Parallel Split
A single activity is split into multiple activities, and each of the split activities is executed independently of each other. Typically represented by the And Split gateway.
-
Synchronization
Threads executed in parallel are synchronized and combined into a single flow. Typically represented by the And Join gateway.
Parallel Split and Synchronization -
Exclusive Choice
A single execution path among multiple execution paths is selected. Typically represented by the XOR Split gateway.
-
Simple Merge
Only a single execution path among multiple execution paths is enabled for merging. Typically represented by the XOR Join gateway.
Exclusive Choice and Simple Merge
2.2. More Split and Merge Patterns
The following describes more split and merge patterns.
-
Multiple Choice
Selects several execution paths among multiple execution paths and executes in parallel. Typically represented by the OR Split gateway.
-
Synchronizing Merge
Joins while synchronizing multiple execution paths. Typically represented by the OR Join gateway.
Multiple Choice and Synchronizing Merge -
Multiple Merge
Joins multiple execution paths into a single path without synchronization. Goes through a single path multiple times if multiple paths are running.
Runs as follows if merged with an XOR Join gateway after an And Split gateway.
Join without Synchronization -
Discriminator
Without synchronizing multiple execution paths, only the first arriving flow goes through continuously. If multiple paths are running, then only the first arriving thread goes through a single path.
If Complex Join gateway’s flow condition is 1 when merging through a Complex Join gateway after an And Split gateway, the following occurs.
Discriminator -
N-out-of-M Join
Synchronizes until the specified number of execution paths is reached, and then flows as one. Only one flow goes through for paths after this gateway.
If joining through a Complex Join gateway after an And Split gateway, the number of flows that come into the Complex Join gateway is N.
-
Arbitrary Cycle
In AnyLink, repeat settings can be used for blocks. However, to repeat more freely, cycles can be set using a transition.
Arbitrary Cycle -
Implicit Termination
If all running service flows are finished, they are terminated implicitly. For reference, they can be terminated explicitly by using a terminate event.
Implicitly Terminating Service Flows -
Multiple Instances
Multiple activities are processed sequentially or in parallel with multiple instances. Multiple instances are created for each activity.
Multiple instances set the following.
Property Description Iteration Completion Condition
Specifies the Boolean condition that represents the completion condition or the number of instances.
Iteration Type
Two types exist: sequential and parallel. The sequential execution type is executed in the same method as a typical iteration statement, and the parallel execution type executes multiple instances at the same time. The parallel execution type is similar to the way multiple paths are executed through And Split.
Transition Method
There are four transition methods.
-
Transition occurs after all instances have been completed. Similar to the And Join method.
-
Transition occurs immediately if a single instance has been completed among multiple instances.
-
Transition occurs whenever each instance has been completed among multiple instances.
-
Transition occurs if a specified Boolean condition is met.
The following describes some key usage patterns related to multiple instances (MI).
-
MI without Synchronization
This is for a case where multiple instances of an activity are created without synchronization, and a transition occurs every time an instance is completed.
-
MI with a Prior Known Design Time Knowledge
This is for a case where the number of instances to be created for an activity to be executed in the MI method is known during design, and the instance count is designated as a constant in the iteration completion condition.
-
MI with a Prior Known Runtime Knowledge
This is for a case where the number of instances to be created for an activity to be executed in the MI method can be known during the activity execution, and the instance count is designated as a variable in the iteration completion condition.
-
MI without a Prior Runtime Knowledge
This is for a case where the number of instances to be created for an activity to be executed in the MI method cannot be known in advance even during execution. The iteration completion condition is specified by a Boolean condition.
-
-
Deferred Choice
Selects a single path among multiple paths like the XOR gateway, but determines the path according to an event that occurs first among the queued events in multiple paths. Typically represented by the XOREvent gateway.
Deferred Choice
3. Service Implementation Method and Service Flow Type
This section describes various service implementation methods and service flow types.
3.1. Proxy Service
A service model which integrates service endpoints so that existing or separately constructed services are serviced via AnyLink, and adds additional functions such as logging or security to existing services. For example, if an existing service is a web service, the WSDL of the service is imported to create a wrapper service.
A service flow is based on an incoming message event, outgoing service activity, and reply activity. Among them, activities for handling necessary logging and security are added.
3.2. Composite Service
A service model in which AnyLink creates new services by joining various services that exist already or are separately constructed.
A service flow is based on an incoming message event, multiple outgoing service activities, and a reply activity. Among them, necessary logging, security, message conversion, and other activities are inserted.
3.3. Service Implementation
AnyLink implements new services. The service logic is implemented mostly through user class activities, various adapter activities, and by splitting off.
A service flow is based on an incoming message event, a reply activity, and various adapter service activities and user class activities.
4. Service Flow Variable and Activity Parameter
The most basic form of an AnyLink service flow expresses a flow by connecting an activity and event with a transition. Here, the activity has parameters that correspond to input and output.
-
An input parameter is a variable that an activity uses to read. The variable is declared in a block activity that includes processes or activities.
-
An output parameter is a variable that an activity uses to write. The variable is declared in a block activity that includes processes or activities.
A service flow variable can be declared in a service flow (which is a process) or in a block activity that groups activities. The scope for process variables is all the activities, events, and transitions belonging to the process. The scope for block variables is all the activities, events, and transitions in the block activity.
5. Service Activity and Parameter
In an AnyLink service flow, calling another service is usually expressed as a call through an activity that represents the service. Services consist of message events, adapter outbound rules, and multi binding router rules of each service flow managed in the service flow engine.
The act of calling another service flow in a service flow is called a Service Flow Activity. An adapter outbound rule call is represented by each adapter’s activity (TCP, HTTP, Tmax, web service, etc.). As well, a multi binding activity is used for calling a multi binding router rule.
The characteristics of each service that calls service call activities may be different, but in the service flow perspective, they are operated the same as services called through a delivery channel. However, in the case of calling another service flow, the service flow engine internally calls itself, so it does not go through the delivery channel but is logically the same.
In an AnyLink service, request, response, and abnormal response messages are divided into input and output messages. A service activity is an activity that calls services, and can declare abnormal output parameters in addition to input and output parameters. In a typical service activity, an input parameter is sent as a service’s request message, and response and abnormal response messages are stored in output parameters and abnormal output parameters. If the input parameter and request message formats are different, data conversion can be specified by using the service activity’s request mapping. As well, if the response message and output message formats are different, data can be converted by using response mapping, and if the abnormal response message and the abnormal output message formats are different, data can be converted by using abnormal response mapping.
6. Mapping
Data conversion in an AnyLink service flow is done through mapping activities or service activities' request mapping, response mapping, and abnormal response mapping.
An AnyLink service flow can declare a process variable shared in a process. As well, a block activity can declare a block variable shared in a block.
Supported variables are String, Float, Integer, DateTime, and Boolean. In addition, message data types (which are structured data types) are supported. Message data types used in an AnyLink service flow are represented as a class that indicates data in the Java programming language. They can be thought of as classes in the form of value objects or data transfer objects in the Java programming language.
In an AnyLink service flow, variables are internally converted to Java classes, and mapping is generated in Java code that converts and passes data between Java objects to improve execution performance. The most basic form of mapping is linking each field of the source message and target message. Hence, the most basic form is to assign a specific field value in the source message to a specific field in the target message.
In addition to the field of a message, an expression can be used as the source. Expressions that can be used in an AnyLink service flow will be described separately later. A mapping activity of an AnyLink service flow is an activity that directs message conversion between these process variables or block variables. The source variable and target variable can be set, and the conversion rule between them can be specified using a diagram as follows.
There are request mapping (for request data needed when calling the start event of an adapter rule or other service flow), response mapping (for changing the format of the results value), and abnormal response mapping (when an abnormal response message is sent). The request mapping maps the input parameter of a service activity into the request message format of a service (adapter rule or another service rule) to be called. The response mapping maps the response message of a service into the output parameter of a service activity. Like the response mapping, the abnormal response mapping maps the abnormal response message of a service into the abnormal output parameter of a service activity. A reply activity can specify the response mapping or abnormal response mapping.
7. Service Flow Expression
Expressions are used to hierarchically represent a specific value of a data object (variable) in statements for representing conditional branches of service flows, calculating correlation values, representing multi binding router conditions, etc.
By considering the performance of frequently called expressions, the AnyLink service flow engine creates the expressions in Java code and then compiles and deploys them.
7.1. Structured Expression
The most basic format of an expression is "variable name"."field name". For example, if there is a variable named "child" and if a field named "name" is defined in this variable, then the source can be expressed as child.name. If used as a source, child.name is converted to the same type as child.getName() when converted to Java code. This kind of expressions that represent structure is called structured expressions.
In mapping’s each assignment operation, both the source and target can be specified as structured expressions. In the case of the source, various types of functions can be used in addition to structured expressions. Taking into consideration the characteristics of expressions generated as Java code, it is possible to use Java methods or operators in expressions of the mapping source. For example, if the name field of a variable named child is a string class in Java code, then the following expression can be used.
child.name.substring(3) + "_ChildName"
The above expression is converted in Java code as follows.
child.getName().substring(3) + "_ChildName"
7.2. Variable Expression
In the case of variable names, if there is no special notation, the beginning token of the structured expression is regarded as a variable name. Variables in a service flow are internally predefined and generated as code. It may be necessary to reference a service flow variable or a block variable during the execution of a service flow. The variables are represented by the "$" notation. For example, if a variable named dataField1 is declared, it can be used as follows.
$dataField1.content
As previously described, expressions are created in Java code. If the exact type of a variable or field is not known, then the Java code cannot be generated correctly. For variables defined in a service flow, their information is extracted from their definitions and then used to assume their actual data types in order to generate the Java code. The data type of a variable can be explicitly specified by using "<>". For example, if the exact data type of a variable named dataField1 is the com.tmax.anylink.ContentContainer class, then it can be expressed as in the following. AnyLink internally converts expressions into Java code and compiles them, so if an exact data type is unknown, then an error will occur during deployment. In the case a data type cannot be assumed in AnyLink, compile errors can be avoided by explicitly specifying the data type.
$dataField1<com.tmax.anylink.ContentContainer>.content
The above expression is converted into the following Java code.
((com.tmax.anylink.ContentContainer) _varCtx.getVariable("dataField1")).getContent()
7.3. Mapping Expression
Use mappings in mapping activities to convert input/output data in service activities or to change variable values in service flows. In mapping, the source data can be represented by a separate expression instead of the input value. The expression at this time is slightly different from expressions such as the conditional statements or the correlation value calculation statements described above. The basic form of the expression used in a mapping’s source is a structured expression. Hence, specify the field of the object value by using a period (.). In a hierarchical structure separated by a period (.), the first part of the mapping expression is the source or the target variable name. Unlike regular expressions, mapping expressions do not support variable names that begin with "$". Instead, the beginning of a structured expression is the variable name. For example, input1 in the below example is the variable name.
input1.person.name
If the field object used in the source is null, and the child field object is hierarchically specified (that is, input1.person.name is specified when the input1.getPerson() value is null), then the object is created as an empty object so that no error is generated. In addition, if the field of the mapping is an array, an asterisk (*) can be attached after the field name used in the target and the field name used in the source to represent an array mapping. Unlike regular expressions, functions are expressed in the form starting with "@" in a mapping expression.
@substring(input1.person.name, 0, 4)
The following are the functions that can be used in a mapping expression.
| Function | Description |
|---|---|
@arraySize(arg1) |
Returns the array size.
|
@date(arg1?) |
Returns the current date in the format indicated by the argument. (Default format: yyyy-MM-dd)
|
@time(arg1) |
Returns the current time in the format indicated by the argument.
|
@strlen(arg1) |
Returns the string length.
|
@trim(arg1) |
Returns a string with no white space characters before and after the string.
|
@substring(arg1, arg2, arg3?) |
Returns the substring of the string represented by the structured expression.
|
@concat(arg1, arg2?, arg3?, …) |
Returns a string that combines multiple strings together. Each argument is a structured expression that represents a string, char, or numeric value. |
@replace(arg1, arg2, arg3) |
Returns a string that replaces a part of the string with another string.
|
@dateformat(arg1, arg2, arg3) |
Converts a string represented by a specific date format to another date format.
|
@charAt(arg1, arg2) |
Returns a character at a specific position in a string.
|
@isNull(arg1) |
Returns whether the result value of the structured expression is null.
|
@numberformat(arg1, arg2) |
Converts the numeric value to a specific format.
|
@urlEncode(arg1) |
Returns a string URL-encoded with UTF8 charset.
|
@getNull() |
Returns the null object. |
@equals(arg1, arg2) |
Compares the equality of two objects.
|
@sequence(arg1, arg2, arg3) |
Acquires a sequence.
|
8. User Code and Handler
The AnyLink service flow provides a function in which users can write Java code to execute activities or execute additional code during error or at a specific point in time of the service flow and activity.
The following user code can be used in the service flow engine.
-
User Class Activity
Activity that executes the Java code written by the user.
The Java code written by the user must inherit the DefaultUserActivity class of the com.tmax.anylink.api.serviceflow package.
// Main method of the user activity void action(ActivityContext ctx) throws AnyLinkException;
-
Process Handler
Handler class that is called at the start and end of the service flow.
The Java code written by the user must inherit the DefaultProcessHandler class of the com.tmax.anylink.api.serviceflow package.
// Called at the beginning of the service flow. void started(ProcessContext ctx) throws AnyLinkException; // Called at the end of the service flow. void finished(ProcessContext ctx) throws AnyLinkException; // Only defined internally. Not actually called. void paused(ProcessContext ctx) throws AnyLinkException; // Only defined internally. Not actually called. void resumed(ProcessContext ctx) throws AnyLinkException;
-
Process Error Handler
Handler class that is called when an error that cannot be handled during service flow execution occurs.
The Java code written by the user must inherit the DefaultProcessErrorHandler class of the com.tmax.anylink.api.serviceflow package.
// Called when an error occurs during the execution of a service flow in which the error handler is defined. void handle(ProcessContext context, Throwable error) throws AnyLinkException;
-
Activity Handler
Handler class that is called at the start and end (due to normal termination, cancellation, or an error) of the activity.
The Java code written by the user must inherit the DefaultActivityHandler class of the com.tmax.anylink.api.serviceflow package.
// Called at the start of the activity in which the handler is defined. void started(ActivityContext ctx) throws AnyLinkException; // Called at the end of the activity in which the handler is defined. void finished(ActivityContext ctx) throws AnyLinkException; // Called at the end (due to cancellation) of the activity in which the handler is defined. void cancelled(ActivityContext ctx, String cause) throws AnyLinkException; // Called at the end (due to an error) of the activity in which the handler is defined. void errorOccurred(ActivityContext ctx, Throwable t) throws AnyLinkException;
-
Activity Error Handler
Handler class that is called when an error that cannot be handled during activity execution occurs.
The Java code written by the user must inherit the DefaultActivityErrorHandler class of the com.tmax.anylink.api.serviceflow package.
// Called when an error occurs while an activity defined in the error handler is executed. void handle(ActivityContext context, Throwable error) throws AnyLinkException;
-
Error Code Mapper
The service flow uses error code when generating or handling an error event. Hence, an error event written by the end event generates the specified error code’s error events, and the boundary error event is responsible for handling errors in the activity according to the error code. The error code mapper converts Java exception objects that are generated during the execution of an activity to error code. The error code mapper class can be specified in the service flow.
The Java code written by the user must inherit the DefaultErrorCodeMapper of the com.tmax.anylink.api.serviceflow package.
// Implement this method which identifies an exception and determines its corresponding error code. String getErrorCode(Throwable throwable);
-
Service Activity Handler
Handler class that is called before and after the call of the service.
The Java code written by the user must inherit the DefaultServiceActivityHandler class of the com.tmax.anylink.api.serviceflow package.
// Called just before the service call of the service activity in which the handler is defined. void beforeServiceCall(ActivityContext ctx, MessageContext mctx) throws AnyLinkException; // Called just after the service call of the service activity in which the handler is defined. void afterServiceCall(ActivityContext ctx, MessageContext mctx) throws AnyLinkException;
9. Correlation
A correlation refers to the association of independent objects. Correlation in AnyLink is used by adapters to find request messages and corresponding response messages. In AnyLink, a correlation does the following: when an event that represents a specific service is generated, an instance related to the event is found among the currently executed service flow instances, and the event is sent to the service flow instance. It associates a service flow instance with an event.
Typically, if an event generated in the service flow engine is a start event, it creates a new service flow instance. Events that use correlation are usually intermediate events where the service flow waits for an event to occur during execution, or boundary events.
In the service flow engine, a correlation event performs correlation between the service flow instance and service through the following two steps: the process of registering the expected correlation value, and a matching process for finding a matching correlation event instance when a corresponding service occurs.
When a service flow reaches an intermediate event using correlation through a transition, the AnyLink service flow engine internally calculates the value for correlation and registers it in the correlation information table.If a message is sent to the service flow engine via the AnyLink delivery channel, it is handled by the service flow engine in the following order.
-
If the service is a service that corresponds to the start message event of the service flow, a new service flow instance is created.
-
If the service is a service that corresponds to the message event that requires correlation, it attempts correlation matching. If a message event that matches the correlation value is found, then the message is sent to the service flow instance in which the event belongs to so that the flow instance transitions to the next step.
-
If correlation matching is not successful, it finds a message event waiting for the corresponding service without correlation, and delivers the service flow instance method in which the event belongs to so that the flow instance transitions to the next step.
-
If none of the message events waiting for the service are registered, then it is stored in the early arrived message map under the assumption that the message event has reached before the message event is registered in the service flow engine. The period of time to wait for a message arriving before the event registration is three seconds by default.
Correlation matching occurs in the AnyLink service flow engine when Service IDs (composed of a combination of the service flow ID and the corresponding message event ID) are the same and the calculated correlation value is the same as the correlation value registered by the service flow instance. For the correlation matching, intermediate events in the service flow can specify registration and matching expressions.
If you need correlation between different service flows or message events, you can use a multi-binding router. When the routing method of the multi-binding router is selected as the service flow correlation, correlation value matching can be performed between different services.