How to create web services in Ephesoft?

Here is my first blog on this website explaining how to create new web services in Ephesoft. As you probably know, Ephesoft already provides a set of web services that you can integrate in your own organization. So, my goal was to identify how complex it is to create new web services. First, let's focus on re-creating the web service getBatchInstanceList. This WS displays all batch instances in a specific status. All steps are not clearly explained but you can find the Maven project published on GitHub here.

Create a controller

The first thing to do is to create a Java controller like that:

@Controller
public class BatchInstanceController {

	/**
	 * Initializing batchClassService {@link BatchClassService}.
	 */
	@Autowired
	private BatchClassService batchClassService;

	/**
	 * Initializing batchInstanceService {@link BatchInstanceService}.
	 */
	@Autowired
	private BatchInstanceService batchInstanceService;
}

For the web services that we are going to create, we'll need two services exposed by Ephesoft: the batch class service and the batch instance service. They will be automatically assigned during the startup of Tomcat. Next, we need to create our method to handle our new web service. We'll need one parameter in the URL to get the status requested by the user, that will be mapped to a function parameter in Java.

@RequestMapping(method=RequestMethod.GET, value="/bataon/batchInstance/status/{status}")
@ResponseBody
public BatchInstanceList getBIByStatus(@PathVariable String status) throws DCMAException {
	LicenseAspect.aspectOf().secureWebService();
	List orders = new ArrayList();
	orders.add(new Order(BatchInstanceProperty.ID, true));
		
	List batchInstances = batchInstanceService.getBatchInstByStatus(BatchInstanceStatus.valueOf(status));
	BatchInstanceList list = new BatchInstanceList();
	list.init(batchInstances);
	return list;
}

This method doesn't need too many explanations :). We are using Spring annotations to declare the method as an exposed webservice. Our service will be usable by the GET method and following the URL pattern. First, we are checking the license and, next, we are using the batch instance service to get the result. However, we are not using default bean provided by Ephesoft because we want to return different information than the web service getBatchInstanceList.

Beans

We created two beans to handle the result: BatchInstanceList and BatchInstance. We are going to explain very quickly the BatchInstance bean. This one will be initialized by a BatchInstance object provided by Ephesoft. We identified as relevant information for a batch instance: the identifier, the achieved percentage (this information will be very interesting at the end of this blog post), the status, the reviewer, the validator, the batch class name and the batch class description. So, we just created this simple java class:

package com.bataon.ephesoft.rest.bean;

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "batchInstance")
public class BatchInstance {

	private String id;
	private float achievedPercentage;
	private String status;
	private String reviewer;
	private String validator;
	private String batchClassName;
	private String batchClassDescription;

	public BatchInstance(com.ephesoft.dcma.da.domain.BatchInstance batchInstance) {
		if (batchInstance != null) {
			this.id = batchInstance.getBatchInstanceID().toString();
			this.status = batchInstance.getStatus().toString();
			this.reviewer = batchInstance.getReviewUserName();
			this.validator = batchInstance.getValidationUserName();
			this.batchClassName = batchInstance.getBatchClass().getName();
			this.batchClassDescription = batchInstance.getBatchClass().getDescription();

			int nbOfModules = batchInstance.getBatchClass().getBatchClassModules().size();
			int nbOfExecutedModules = 0;
			if (batchInstance.getExecutedModules() != null)
				nbOfExecutedModules = batchInstance.getExecutedModules().split(";").length;
			
			this.achievedPercentage = (float) nbOfExecutedModules / nbOfModules;
		}
	}
	...
}

Next, you need to create a context file copying this file: https://github.com/bchevallereau/ephesoft-extension/blob/master/ephesoft...
And that's it, package your customization as a JAR file and put in the lib folder of the Tomcat instance used by Ephesoft. Next, you just have to call this web service (http:///dcma/rest/bataon/batchInstance/status/READY_FOR_VALIDATION) from your browser and you'll get something like that:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batchInstances>
	<count>1</count>
	<items>
		<batchInstance>
			<achievedPercentage>0.875</achievedPercentage>
			<batchClassDescription>HR Documents</batchClassDescription>
			<batchClassName>HRDocs</batchClassName>
			<id>BI4</id>
			<reviewer>ephesoft</reviewer>
			<status>READY_FOR_VALIDATION</status>
			<validator>ephesoft</validator>
		</batchInstance>
	</items>
</batchInstances>

New webservice

Now, we know how to create a webservice. The goal of this section is to create a webservice to get all 'active' batch instances, that means batch instances with the status RUNNING, READY, LOCKED, NEW, READY_FOR_REVIEW, READY_FOR_VALIDATION and ERROR. To do that, we are just going to create a new method in our controller:

@RequestMapping(method=RequestMethod.GET, value="/bataon/batchInstance/status/active")
@ResponseBody
public BatchInstanceList getActiveBI() throws DCMAException {
	LicenseAspect.aspectOf().secureWebService();
	List orders = new ArrayList();
	orders.add(new Order(BatchInstanceProperty.ID, true));
		
	List statusList = new ArrayList();
	statusList.add(BatchInstanceStatus.ERROR);
	statusList.add(BatchInstanceStatus.NEW);
	statusList.add(BatchInstanceStatus.READY);
	statusList.add(BatchInstanceStatus.READY_FOR_REVIEW);
	statusList.add(BatchInstanceStatus.READY_FOR_VALIDATION);
	statusList.add(BatchInstanceStatus.RUNNING);
		
	List batchInstances = batchInstanceService.getBatchInstanceByStatusList(statusList);
	BatchInstanceList list = new BatchInstanceList();
	list.init(batchInstances);
	return list;
}

That way, we get exactly the same result as describe above calling the URL: http://dcma/rest/bataon/batchInstance/status/active.

Alfresco & Share

But why create a web service like that? There are different ways to keep the user informed about pending batch instances... But, let's assume that Alfresco is the tool used intensively by all users... Why not create a dashlet to display 'active' batch instances in Ephesoft. So, we created a Java backed webscript that manages the authentication on Ephesoft and returns the result in JSON. Also, we created an auto-refresh dashlet that requests Alfresco to get all active batch instances. Directly from the Share user interface, you can open Ephesoft on the right batch instance when they are ready.
I'm not going to explain how to create a webscript or a dashlet in this blog. These topics are already covered by a lot of documentation. However, you can get the code that I developed on GitHub. Here is a quick (and accelerated) video of what you can get using this extension:


So, again, all customization developed in this blog post are available on GitHub. Feel free to comment or send me an email if you need clarification. I hope that this blog post will interest and should be the first of a long serie... So, keep posted!

Add new comment