Http request plugin or message broker plugin

[rizalalfarizi123]

So i just want to utilize only imixs rest api and i want to ask is there any plugin that support http call after some process or subscribe to some message broker like kafka or google pubsub that we can use in model?

[rsoika]

Hi @rizalalfarizi123,
thanks for your interest in Imixs-Workflow and the Rest API. I understand that you want to run Imixs-Workflow engine as a Rest Service only and interact with the engine via the Rest API. This is fine and a simple, robust and lightweight solution.

And yes, you can integrate Plugins or Adapters into your workflow to let the workflow engine itself call external micro services via Rest API.
As Imixs-Workflow is build on top of Jakarta EE this is super simple. You can inject you entity classes and build a Client with the ClientBuilder API. See also here or here.
So your plugin code can be very simple as you do not need additional libraries. But it is not possible to provide this as a generic module because each rest-api is different and you need the corresponding client code - which of course can be generated form an Open-API documentation automatically.

So your plugin code would look something like this:

public class MyPlugin implements Plugin {

	public void init(WorkflowContext actx) throws Exception {
	}

	public ItemCollection run(ItemCollection workitem, ItemCollection event) throws Exception {
		try {
			Client client = ClientBuilder.newClient();
			WebTarget myResource = client.target("http://example.com/webapi/read");
			String response = myResource.request(MediaType.TEXT_PLAIN).get(String.class);
			// you business logic goes here....
		} catch (Exception e) {
			// signal exception....
			throw new PluginExeption(e);
		}
		// signal success 
		return workitem;
	}

	public void close(boolean rollbackTransaction) throws Exception {
		// close resources 		
	}
}

The other point is your question about a message broker. You can find an implementation for Apache Kafka here. This is a kind of generic adapter to connect Imixs Workflow with a Kafka Queue.

In both cases - whether rest client or message broker - communication can be bidirectional. Imix-Workflow can fetch data from an external service in order to supplement its own process instance with this data (e.g. address of a customer based on the existing customer number) or send data to a service itself (e.g. the release for an order from a workflow)

In all cases you can configure the communication via your BPMN model. For example you can place the service endpoint or request type as configuration data into your BPMN Event. This could be similar like in the SplitAndJoinPlugin that provides a configuration layer to be defined in the Event-Workflow-Result.

Let me know if this answers your question.

[rizalalfarizi123]

thank you for your clear answer @rsoika, so we need to implement it our self right. but is there any plan to provide http caller plugin that integrate with open bpmn, so we can just input http request parameters inside open bpmn modeler? something like camunda modeler

[rsoika]

Do you have a link to the camunda feature you are talking about here? A http caller plugin is not so complicated but how would you expect to configure this? And how would you extract data from a response body?

[rizalalfarizi123]

something like this, it is from camunda quick start: connector tutorial, so it will be a task that can make a request and will map response body into variable that we can use in the next process

[rsoika]

ok - understand.

Look, this is how your plugin code looks in Imixs - there is no need for a special connector - you can use Jax-rs native:

public class RestConnectorPlugin extends AbstractPlugin {
	private static final Logger logger = Logger.getLogger(RestConnectorPlugin.class.getName());

	@Inject
	private WorkflowService workflowService;

	@Override
	public ItemCollection run(ItemCollection workitem, ItemCollection event)
			throws PluginException {
		logger.info("...connecting rest api...");
		// read configuration from event
		List<ItemCollection> apiDefinitions = workflowService.evalWorkflowResultXML(event, "api-connector",
				"GET", workitem, false);
		if (apiDefinitions != null) {
			for (ItemCollection apiDefinition : apiDefinitions) {
				String endpoint = apiDefinition.getItemValueString("endpoint");
				String item = apiDefinition.getItemValueString("item");
				// Create a JAX-RS client
				Client client = ClientBuilder.newClient();
				WebTarget target = client.target(endpoint);
				Response response = target.request().get();
				if (response.getStatus() == 200) {
					// Parse the JSON response
					String jsonResponse = response.readEntity(String.class);
					JsonReader jsonReader = Json.createReader(new StringReader(jsonResponse));
					JsonObject jsonObject = jsonReader.readObject();
					String itemValue = jsonObject.getString(item);
					// Update workitem
					workitem.setItemValue(item, itemValue);
					jsonReader.close();
				} else {
					throw new PluginException(RestConnectorPlugin.class.getSimpleName(), "API-ERROR",
							"Failed to fetch data: " + response.getStatus());
				}
				response.close();
				client.close();
			}
		}
		return workitem;
	}
}

And this example allows you to configure the plugin by your BPMN Event:

You can copy the code from here.

Typically you will often have a more complicated Rest API. So the important part is the part with parsing the json result. I do not think that a generic plugin will help much here as you data will be more complex. For example you may want to joint data values or change the values somehow.
This is why a custom plugin gives you more freedom to do so. And the code is quite simple.

The nice thing is, that you have in this example also a configuration layer. You can put the following example config into your workflow result in the modeller:

    <api-connector name="GET">
        <endpoint>https://catfact.ninja/fact/</endpoint>
        <item>length</item>
    </api-connector>

And you can easily extend the configuration to your own needs.

I hope this helps you to get startet.

[rsoika]

Yes you can take a look at the Imixs Process-Manager. This project provides you withe a Web Application bundled with the Imixs-Workflow Engine. You can start it out of the box with Docker and you can use this project as a template for your own Business Application.

Or your can take a look at Imixs-Microservice. This project bundles the Imixs-Workflow Engine as a Microsservice. It is full featured and also bundled as a Docker Container. You can use this as a side-car-service in a Microservice Architecture.

[rizalalfarizi123]

okay, and why can we only implement our custom logic in event notation (using signal adapter) instead of just task notation?, with imixs workflow if I want to model tasks (e.g. getting customer credit score) we also need event notation to implements getCustomerCreditScore logic, right?

[rsoika]

Yes you are right and what you are thinking about is what we call a task-orientated processing concept. You are thinking about a concept where the task is the place to put in the code and business logic. Such concepts are used by Activiti and Camunda. Such a engine does nothing else than executing one task after another until the process terminates with an end event.

In Imixs Workflow we have an event-orientated processing engine. The difference is that in this concept the task defines a persistent unique state in the process flow. The workflow engine reacts on events. If no event is fired the process status will not change.

You can see this in the wording. The task describes a fact like 'We received a new Invoice' or 'The invoice is ready for Approval'.
But the task does not define what will happen. But if someone or something triggers the event 'Add Items' the workflow Engine will update the workitem status according to the process flow. So the action is the event like 'I add new items' or 'I approve the invoice'.

And from the coding perspective the code is not executed in a Task. In an event-orientated workflow engine this it different. If you want to add items you first need to fetch the process instance (workitem) from the persistence layer (data store). Now you can add data like items to the workitem and finally you call the event 'Add Items' to signal that now all is ready for the next step. The Workflow Engine coordinates this transition.

So from the coding it looks like this:

// fetch the workitem from the data base
workitem=workflowService.load(id);
// change or add the payload 
workitem.setItemValue("my item", "some data");
// process the workitem
workflowEngine.process(workitem.event(100));

Keep in mind that business logic should never take place in code, but should always be modeled in the BPMN model!

The actual code (e.g. reading data from an external database) is the same. Whether it is executed in a task or an event.

[rizalalfarizi123]

thank you for your clear explanation @rsoika , i tried imixs-process-manager app and then i uploaded and changed ticket model version to ticket-model-1.0.1 but when i try to start create ticket, why it's still using ticket-model-1.0.0 model and when i delete the previos version, the new workflow model worked. I see in doUploadModel method it called saveModel and from documentation saveModel = Saves a BPMNModel into a Document and adds the model into the ModelManager. should the service change the model on runtime?

[rsoika]

Hi @rizalalfarizi123 , Yes you are absolutely right and this is a bug in Version 6.1.0-SNAPSHOT. I just realized this and fixed it in Issue #876
I already pushed a new Docker image and updated the latest snapshot release. This should now work for you.

Thanks for finding this issue! 👍