Work ow engines for automated execution of process models are typically run as back end systems and provide APIs for connecting software components. These connecting components reside on a di erent level of abstraction, using business- instead of process-speci c concepts. To nd a remedy, work ow engine APIs are frequently mapped to business-speci c APIs speci cally developed for this purpose. Modelling a business-speci c interface for a work ow engine is a time consuming task. In order to reduce development e ort, this paper proposes a method to automatically generate domain-speci c REST APIs based on both, process models and complementing resource information with only small extra modelling e ort, thereby bridging the gap between process and data perspective. We furthermore present an architecture that can be used to implement the proposed method for any work ow engine which provides a REST API. The method promotes the continuous maintenance of process and resource information models. We introduce an initial prototype for the Camunda work ow engine, discuss limitations of the method and give an outlook for future work.
Work ow engines for automated execution of process models are typically run as back end systems and provide REST APIs for connecting software components. Using these APIs in a speci c business context comes with some challenges. Starting from a short description of business process management on the one side and resource-oriented architectures on the other side, this section explains these challenges and motivates our proposed approach for an automated generation of business-oriented APIs for work ow engines.
Many enterprises have adopted process management methodologies to improve
the e ciency, reliability, and maturity of their processes. The discipline of
business process management (BPM) deals with the whole life cycle of business
processes, comprising their initial conception / discovery, analysis, modelling,
execution, and monitoring [
WFMSs rely on BPMN models to control the process ow and to coordinate between process instances and their participants. Some examples of open source WFMSs are Camunda1, Activity2 and jBPM3 which have some features and components in common. They provide, for example, a process modeller to design executable process models and a process management interface, which is a graphical interface for end users to control and to take part in process execution. The core component of these WFMSs is a process engine that executes process instances on the basis of process models provided in form of XML les. In order to manage the data required within the process instances, WFMSs usually employ the concept of process variables [3{5] which can be read and manipulated to share information between process activities and with components lying outside the process.
Despite the existing GUI, process engines are often embedded as backend
services into existing applications or distributed scenarios. To couple an engine with
external components, it usually provides a Java API that can be used to
implement service tasks or control the ow of process instances. In addition to the
Java API, most engines o er a remote REST interface. Representational state
transfer (REST) is a widely adopted architectural style. Due to their simplicity,
REST APIs are used in many use cases such as communication between internal
services, communication with end-user devices or as an o ering for third
parties [
REST promotes properties such as scalability, loose coupling or intrinsic
interoperability of web services, which all are required under the conditions of
the World Wide Web. One central constraint that distinguishes REST from
other architectural styles is the uniform interface constraint. This constraint
1 https://camunda.com/
2 https://www.activiti.org/
3 https://www.jbpm.org/
among others requires that an individual resource is identi ed through a unique
identi er, which is used in requests. The representation of a resource, that is
returned to the client, is decoupled from the server's internal representation of
this resource. Furthermore, the client itself can modify a resource, if it holds
a representation of the resource and all attached metadata. Additionally, it is
required that every message contains all necessary information to be processed.
Lastly, the uniform interface constraint requires the use of hypermedia as the
engine of application state (HATEOAS). To implement HATEOAS, a server
enriches its response regarding one resource by adding links to other connected
resources and the methods applicable to them. This enables automatic discovery
of available resources for the client [
Since the REST APIs provided by WFMSs are ne grained, using them leads
to increased complexity and development e ort for consuming clients. Querying
or manipulating process data requires multiple API calls to access the needed
resource. Since the API relies on BPM terminology, developers have to be
familiar with both, BPM as well as business semantics and have to map concepts
of both worlds, which is a time consuming activity [
The following example scenario might illustrate this problem. Figure 1 shows a simple manual check of an application which might e.g. be carried out in some insurance company. Let's suppose a developer working on some front end for clerks who will later carry out the application check is using the REST API of a process engine to implement the respective functionality. To do so, he/she would need to implement all of the following steps. 1. fetch the process instance that handles the considered application 2. fetch the task "decide application" that belongs to the process instance 3. set process variables that represent the decision of the user 4. set the task's state to "complete" While a well designed REST API residing in the application domain would only require one step to update the state of a decision resource to realize this task, relying on the WFMS's REST API, the developer has to undergo several steps and has to match process concepts (e.g. task, process variable) with business concepts (e.g. decision).
To overcome this issue process engines are often used as an embedded library,
which is then wrapped by an API that re ects the application domain. This
approach moves the complexity of directly consuming the API of the engine
to the wrapping service that is using the engine. In this way, the development
e ort is not completely avoided but only shifted. Furthermore, REST and BPMN
have a di erent view on a system. While BPMN provides a process-centric view
of a system, REST provides a view that focuses on the resources and their
associations [
Looking at the challenges described above, automating the creation of a REST API for the process engine is an attractive approach. This work proposes a respective method that closes the gap between the di erent views and should reduce development e ort by automatically generating an API that re ects the business domain, and uses a WFMS as the back end. The API is generated by using a data model which describes the REST resources and their relations, together with a BPMN process model. In addition to the reduced e ort, the procedure promotes the continuous maintenance of data and process models.
The remainder of this paper is structured as follows. Section 2 gives an overview on related work. To further motivate our approach of an automated generation of business-centric APIs, we describe how it is embedded into an overall application development process. Details of the approach are explained in section 4 and the development of a rst prototype is presented in section 5. Finally, section 6 concludes this paper and gives an outlook on future work.
In [
In addition to the approaches in which API code is generated, there are also
some that generate an entire application. In [
Using the REST architectural style for business process applications has been
research subject of several projects. Various research questions were examined.
Pautasso proposes in [
Another question concerning BPMN and REST is how BPMN choreographies
can be realised with REST interfaces. [
The process model and a UML class diagram modelling the REST resources are created during the rst two activities of the work ow we introduced in section 3. Modelling the REST resources is described in more detail in section 4.1. The link between the models is created by connecting the process and tasks of the process model with the individual classes modelled in the class diagram. This connection is described in gure 3 as a composition between a process or some of the tasks and the classes. This connection closes the gap between resource semantics and process semantics. It indicates that the state of the process /task output is represented by the resource and can be manipulated by it. Further details about this connection can be found in section 4.2. Figure 3 also shows that the classes in the class diagram describe the resources and the corresponding URIs. The URIs are also important for the connection between process instances and individual resources. Section 4.3 and 4.4 describe how the URIs for resources are generated and how the mapping between a process instance and a resource is established. The relationship between task executions and resources is described in section 4.5. It also explains how the task execution state is used to determine the state of a resource.
Process Model
1 Process
executes
ProcessInstance id : String name : String businessKey : String references N
URI parentResources : List<String> parentIDs : List<String> resourceName : String resourceID : String 1 1 1 0..* 1
TaskExecution 0..* id : String name : String state: TaskExecutionState
Resource name : String data : Map child 1 parent 0..* Task executes 0..*
0..* H create/transform
UML Class Diagramm
1
Class J describe <<enumeration>> TaskExecutionState inactive active closed
As in other approaches dealing with the generation of APIs, UML class
diagrams are used for the modelling of REST resources. This suits our purpose,
as the attributes of the resources can be described as class properties.
Furthermore, associations can be used for the modelling of the URL hierarchy. Figure 4
shows a simple resource model for the application check process we have already
described in section 1. An application includes none to many documents and
a decision whether the application has been accepted and what the insurance
should cost. The decision also includes an approval. For simpli cation, the
resource model can only use directed associations here and must already represent
the URL tree. This simpli cation is chosen because this work only deals with
the linking of the resource-oriented view with the process view of a system. For
future versions of the tool which generates the interfaces we envision the use of
domain models as in [
To generate the interface, the business process for which the interface is generated must be linked to a resource. The idea behind this is that each business process processes or produces a resource. This concept is also re ected in common de nitions of the term business process, such as e.g formulated by Davenport: In de nitional terms, a process is simply a structured, measured set of activities designed to produce a speci ed output for a particular customer or market [17, p. 5].
The state of this output, be it a product or a service, can be described by the resource with which the process is annotated. This idea is also applicable to tasks. If a task is annotated with a resource, it means that this resource is being processed in this speci c process step. The resources associated with the tasks of the process can be sub-products and services required for the execution of the business process, or the process resource itself which is modi ed in the business process.
Technically, the linkage between process or task and a resource can be described by an annotation in the process model. The BPMN2.0 allows the extension of process models by extension elements. To create a link between a process element like a task and a resource of the class diagram, BPMN extension elements can be used. An extension element is an XML element that can be a child of a regular element of the BPMN speci cation to augment a process model with custom data. Listing 1 shows a BPMN user task named "evaluate application", which is linked to the resource named "evaluation" by such a BPMN extension element.
Listing 1. BPMN user task with extension elements <bpmn:userTask i d=" A c t i v i t y 0 4 b i 4 l p " name=" e v a l u a t e ,! a p p l i c a t i o n "> <b p m n : e x t e n s i o n E l e m e n t s>
<l i n k e d R e s o u r c e name=" e v a l u a t i o n " /> </ b p m n : e x t e n s i o n E l e m e n t s> <bpmn:incoming>Flow 1dzcmml</ bpmn:incoming> <b p m n : o u t g o i n g>Flow 0wx3he6</ b p m n : o u t g o i n g> </ bpmn:userTask>
As depicted in gure 3, a resource consists of a name and data de ned by the class diagram. In addition, a resource has a URI that identi es it. A URI is generated as follows. Typically, the URI represents the relationships between di erent resources by using subresources. Although this is not mandatory, it can contribute to the comprehensibility of the API for developers. Therefore, our tool can also interpret the subresource relationships represented by URIs.
product : String price: Integer applicant: Person 0..*
Document description : String type: String 1
accepted : Boolean premium: Double 0..1
approved :
Boolean The root resource of the API is always the resource which is linked to the process and is at the top of the modelled resource hierarchy. So, for our example, an "Application" resource modelled in gure 4 is identi ed by the URL /application/fapplicationIDg. The order of the child resources is then formed by the associations of the class diagram. To identify the decision associated with an application, the URL /application/fapplicationIDg/decision is used. The underlying resource "Approval" would then be identi ed with the URL /application/fapplicationIDg/decision/approval. In addition to the direction of an association, the multiplicity of an association is also important for URI creation. For 1-to-1 relations, routes can be formed without an identi er of a subresource, because the subresource is already identi ed by the parent resource. Therefore, no further identi er is needed for the path to the "Decision" resource. For 1-to-N relations, resources of the same class have to be distinguished. For this purpose, the path to the subresource, which can exist multiple times, must be equipped with an identi er for the respective subresource. To address a certain document resource the path /application/fapplicationIDg/document/fdocumentIDg would be used. The URI class in gure 3 summarizes which information is required to generate a URI. The parentResources attribute is used to display the associations of the resource model. In addition to the identi cation of a speci c resource, the parentIDs and resourceID attributes are also used to map resources to process instances. The mapping is explained in the following.
After explaining how resources are identi ed in the REST API, it is explained how a resource can be assigned to a process instance. The assignment of a resource to a task alone is not su cient, because in a typical application scenario several instances of a modelled business process are executed simultaneously. Therefore, a mapping from URI to process instance must be done to ensure that clients receive the data of the respective process instance. BPMN call activities start further process instances from a main process. These instances each have an ID of their own, so they cannot be assigned to a common parent process. A functionality that is o ered by many work ow engines is the use of a business key. This key can be passed on to child processes that were started by call activities and thus enables di erent process instances to be assigned to their parent process.
Alternatively, process variables can be used. Here, data required for process execution can be added to process instances as process variables. If a WFMS does not o er business keys but variables, the key can be implemented by a variable itself. In our approach the business key is used to assign the root resource, i.e. the resource that is also linked to the process, to all associated process instances. Thus the URL /application/fapplicationIDg for the application resource from gure 4 is equivalent to /application/fbusinessKeyg. This way of generating identi ers makes it easy to nd every process instance in which the application resource is processed. For subresources with a 1-to-1 relationship, the business key is also su cient as the only identi er. More di cult is the assignment of resources to tasks which have a 1-to-N relationship to their parents. As an initial simpli cation, we assume that 1-to-N relationships occur when the process execution loops through a subprocess several times. These subprocesses each have an ID of their own, which can be used as identi er for the resource that occurs multiple times. In this way, document resources from gure 4 are addressed with the URL /application/fbusinessKeyg/document/fprocessInstanceIDg. The simpli cation for ID creation of resources with 1-to-N relationship excludes some use cases. These will be explained in the outlook of this paper.
To implement HATEOAS it must be clear how the state of a resource is controlled. In our case the state of the resource should be determined by the business process. A method often suggested in the literature to model REST APIs are state machines. Linking activities to resources, delineates such a state machine. The BPMN2.0 speci cation also describes the life cycle of an activity as an automaton. For simpli cation, we restrict the state machine to the states Inactive, Active and Finished. These states can now be applied to the resource associated with the task. In our tool, a resource can only be changed if the respective activity is in the Active state. Read access is possible at any time. For the implementation of HATEOAS, a server response should contain links to parents and child resources, as well as the possible operations on the requested resource. These can be derived from the state of the annotated task. If a resource is linked to several activities, it can be processed if at least one annotated task is Active.
After showing how process models and resource models can be linked, this section presents a prototypical implementation. Therefore a generic modular architecture is introduced which can be implemented with di erent technologies. A goal of the architecture is that individual components can be replaced fast due to the generic core of the architecture. This allows changing the back end process engine as well as the HTTP library that receives the requests. Figure 5 visualizes the main components of the generic architecture.
RESTFacade
<<generate>> <<use>> <<interface>>
APIGenerator generate(processModel : ProcesModel, resourceModel : ResourceModel) : RESTFacade <<interface>>
ResourceController getResource( uri : URI ) : Resource updateResource( resource : Resource ) : Resource completeResource( resource : Resource ) : Resource deleteResource( uri : URI ) <<use>>
<<interface>>
ProcessEngineAdapter startProcessInstance( processDefinition : String, businessKey : String, variableName : String, variable : Map ) : String updateVariable( businessKey : String, variableName : String, variable : Map, processInstance : String, task : String ) isActive( businessKey : String, processInstance : String, task : String ) : boolean getVariable(variableName : String, businessKey : String, processInstance : String) : Map removeProcessInstance(businessKey : String, processInstance : String) completeTask(businessKey : String, processInstance : String, task : String) <<use>>
ProcessEngine HTTP requests are accepted by the RESTFacade. The RESTFacade converts the request data into the required data types and calls the corresponding methods of the ResourceController. The facade is generated by the APIGenerator. This should be done at runtime without generating code. This is possible because a generic data structure is used for the representation of the resource. The APIGenerator only has to generate HTTP endpoints for each resource from the model. The corresponding method call to the ResourceController is then the same for each resource, but with di erent parameters. These parameters are adapted by the generator for the respective resource. The ResourceController maps the resource logic described in the previous chapter. Here the conditions like the state of the tasks for a resource or the attributes sent with a resource are checked before a task is processed. Afterwards, the changes are passed on to the ProcessEngine using the methods o ered by the ProcessEngineAdapter. The ProcessEngine is abstracted by the ProcessEngineAdapter. This adapter makes the required calls to a ProcessEngine and must therefore be implemented individually for each engine. Calls to the ProcessEngine that are required could be for example: { start a new process instance { check whether a task is active { set a process variable { complete a task { read a process variable { stop a process instance
The architecture for the prototype was implemented in Java with the Camunda Process Engine. The Spring MVC web framework was used as HTTP library. To create HTTP routes dynamically for each resource, spring router functions where used4. This allows for a functional description of router behaviour at runtime, which is required to generate the resource URIs and create method calls to the Resource Controller that are adapted to each resource. The resource model is implemented as a graph by the Java graph library JGraphT5, which enables easy querying of children and parents of a resource. The resources are stored as vertices. The associations between resources are stored as edges of the graph. The edges also store the multiplicity of the association.
The Camunda Work ow Engine comes with its own modeling tool, which can be extended with custom forms. This was used in our implementation to add resources to a task or a process without having to make direct changes to the XML document. This ensures that the resource annotations are inserted at the right places in the document. The models in the Camunda WFMS are stored in BPMN2.0 compliant XML per default. Like BPMN, there is a standard data exchange format for describing models in UML. The XML Metadata Interchange standard speci ed by the OMG serves as an open format for UML models. Various modeling tools already o er export of models into this format. For the sample implementation of the REST API generator, a simple parser that can read UML class diagrams was developed. 4 https://docs.spring.io/spring/docs/current/spring-framework-reference/ web.html\#webmvc-fn 5 https://jgrapht.org/
This paper has presented a method to automatically generate domain-oriented REST APIs for business processes. We have made a proposal of how to connect process and resource models. We have described both, the linking of models, as well as the linking of REST resources and process instance by URIs at runtime. For this purpose, tasks are used as state machines for resources to control the possible operations on a resource. In addition, we have introduced an initial prototypical implementation of the presented approach. For the implementation a modular layered architecture has been used, which supports the interchangeability of process engines and HTTP libraries. The ResourceCotroller, once developped, does not have to be exchanged when changing libraries. Finally, we have explained how the tool can be used to create a user interface based on business processes using the generated API.
As already described in chapter 4, for the development of the prototype we assumed that a resource occurs multiple times in a process, if loops in the process allow a repetition of the associated task. However, it is possible that in a loop an existing resource is revised instead of a new one being created. It is also possible that when a task is repeated in a loop, the user has the choice of creating a new instance of a resource or editing an existing one. In order to execute these cases in the process, either conventions for modeling the process must be de ned or the models must be supplemented with additional annotations that describe the behavior of the resources more precisely.
Also, it must be further de ned how a change of the models a ects the runtime behavior of existing process instances. Some WFMS already o er strategies for the migration from an older process version to a newer one. Here it must be evaluated whether the tool for generating APIs is compatible with these strategies and whether these strategies are also applicable to changes in resource models. In this paper, the automatic implementation of interfaces has been presented for BPMN processes only. However, processes can also be modeled within other langauge, like e.g. CMMN. Although the symbols known from BPMN can be used to model CMMN models, a di erent automaton with di erent states and transitions is used to represent the life cycle of an activity. In short, it is possible that tasks do not necessarily have to be executed but are still available and can be aborted at any time. These characteristics, which are important for CMMN, should be taken into account when linking the state machine to the resource.
Since this work is the presentation of the basic concept and a prototype only,
further extensions for the developed tool are possible. In this paper, the API was
implemented for the development of front ends for user tasks. However, REST
APIs do not necessarily have to be used by front end applications. BPMN also
enables more than just modeling human interaction with the process. Message
events and receive tasks are further elements in the business process that require
an interface to WFMSs. Here, it is also interesting how the presented method
can be integrated into process choreographies. The work of Nikaj [
Furthermore, an evaluation of our tool is important. For this purpose, it can be examined in future work how the generated API a ects the client applications. In order to measure the impact on the client code, a case study can compare the client applications that use di erent interfaces. Surveys of the developers allow an evaluation of the developer experience for our tool. Software metrics such as coupling, cyclomatic complexity can be used for a quantitative comparison of the impact of the domain-oriented generated interfaces with the impact of the generic interfaces.