The Imixs Workflow project provides a REST API to access all resources concerning a process management system. This Interface was designed to access the Imixs Workflow from any external client. It provides methods to create, update and read workitems
In various projects there is a requirement to integrate external master data which is not part of the process management system. An example there for is the customer or address data located in a remote system.
To access such external data from the workflow application in a general and easy way we think about a generic kind of micro-service-architecture to be used to access any external data.
Imixs Micro-Service-Architecture
The Imixs Micro-Service-Architecture is an idea to provide a concept to access any remote data based on a RESTfull service architecture. The idea is to split the problem into a generic data-value object and a generic API to access these objects. Both concepts should be based on RESTfull Services
A data object can be treated as a generic value-object like the imixs workflow business-data. This object can store any kind of data. See the following JSON example:
{"item":[
{"name":"$uniqueid","value":{"@type":"xs:string","$":"141cb98aecc-18544f1b"}},
{"name":"$modelversion","value":{"@type":"xs:string","$":"bestandspflege-de-0.0.2"}},
{"name":"$processid","value":{"@type":"xs:int","$":"2000"}},
{"name":"namcreator","value":{"@type":"xs:string","$":"admin"}},
{"name":"$isauthor","value":{"@type":"xs:boolean","$":"true"}},
{"name":"_subject","value":{"@type":"xs:string","$":"JUnit Test-6476"}},
{"name":"txtworkflowstatus","value":{"@type":"xs:string","$":"Vorlauf"}},
{"name":"txtworkflowresultmessage","value":{"@type":"xs:string","$":""}}
]}
As this concept is still part of the Imixs Workflow project this formats are described in the Imixs project:
To identify a external master data the standard attribute ‘$uniqueid’ can be used which should contain the primary key of the object. In addition the following default attributes can be provided. This attributes define a kind of minimum set to describe the data object:
| Core Properties | Type | read/ write |
Description |
|---|---|---|---|
| $Created | Date | no | Date of creation |
| $Modified | Date | no | Date of last modification |
| $uniqueId | String | no | The unique ID of this data |
| $uniqueIdRef | String | yes | A reference to a connected workItem |
| txtname | String | no | A short name of the data used for lookups |
| txtdescription | String | no | A long description of the data |
The REST API
REST is an architectural style that can be used to guide the construction of web services in a more easy kind as a service which uses the SOAP specification. REST is based on URIs. An URI is a unique resource identifier. In REST an URI represents a resource and is used to get or modify a resource. In the meaning of this micro-service-architecture the URIs represent master data provided by a remote system. Each kind of master data source should be identified by a unique resource name, e.g.:
- /customer/xxxxx-xxxxx
- /car/xxxxx-xxxxx
- /part/xxxxx-xxxxx
The last part of the URI identifies a data object by its primary key ($uniqueid) to create, update or delete. These crud operations are mapped to the corresponding http method:
- POST/PUT – creates or updates a data object
- GET – reads a data object
- DELETE – removes the data object
Posting a data object means to update the object. The method should accept any set or subset of attributes. This means if a POST request sends only a few attributes only these attributes should be updated.
Access data collections
To get a collection of data object the main URI can be used together with the GET method , e.g.
GET: /customer/
To restrict, filter or sort the collection the following query params should be provided:
- /customer?count=10 – returns 10 elements
- /customer?start=10 – returns elements from position 10
- /customer?txtname=xxx – returns elements matching the attribute ‘txtname=xxx’
- /customer?sort=1 – defines the sortorder of the returned collection (0=creation date descending ,1=creation date ascending ,2=modified date descending ,3=modified date ascending)
This is just a draft version of a concept to provide a generic interface to external data from a remote system.