6 min read

Defining a Service

We first need to define a service. Our first service will be named learningFirstService.

In the folder ${component:learning}, create a new folder called servicedef. In that folder, create a new file called services.xml and enter into it this:

Learning Component Services

location="org.ofbiz.learning.learning.LearningServices" invoke="learningFirstService">
Our First Service

In the file ${component:learning}ofbiz-component.xml, add after the last element this:

That tells our component learning to look for service definitions in the file ${component:learning}servicedefservices.xml.

It is important to note that all service definitions are loaded at startup; therefore any changes to any of the service definition files will require a restart!

Creating the Java Code for the Service

In the package org.ofbiz.learning.learning, create a new class called LearningServices with one static method learningFirstService:

package org.ofbiz.learning.learning;

import java.util.Map;

import org.ofbiz.service.DispatchContext;
import org.ofbiz.service.ServiceUtil;

public class LearningServices {

public static final String module = LearningServices.class.getName();

public static Map learningFirstService(DispatchContext dctx, Map context){

Map resultMap = ServiceUtil.returnSuccess("You have called on service
'learningFirstService' successfully!");
return resultMap;


Services must return a map. This map must contain at least one entry. This entry must have the key responseMessage (see org.ofbiz.service.ModelService.RESPONSE_MESSAGE), having a value of one of the following:

  • success or ModelService.RESPOND_SUCCESS
  • error or ModelService.RESPOND_ERROR
  • fail or ModelService.RESPOND_FAIL

By using ServiceUtil.returnSuccess() to construct the minimal return map, we do not need to bother adding the responseMessage key and value pair.

Another entry that is often used is that with the key successMessage (ModelService.SUCCESS_MESSAGE). By doing ServiceUtil.returnSuccess(“Some message”), we will get a return map with entry successMessage of value “Some message”. Again, ServiceUtil insulates us from having to learn the convention in key names.

Testing Our First Service

Stop OFBiz, recompile our learning component and restart OFBiz so that the modified ofbiz-component.xml and the new services.xml can be loaded.

In ${component:learning}widgetlearningLearningScreens.xml, insert a new Screen Widget:


In the file ${component:learning}widgetlearningLearningForms.xml, insert a new Form Widget:

Notice how the formTarget field is being set in the screen and used in the form. For now don’t worry about the Full Name label we are setting from the screen. Our service will eventually set that.

In the file ${webapp:learning}WEB-INFcontroller.xml, insert a new request map:

The control servlet currently has no way of knowing how to handle an event of type service, so in controller.xml we must add a new handler element immediately under the other elements:

We will cover service-multi services later. Finally add a new view map:


Fire to webapp learning an http OFBiz request TestFirstService, and see that we have successfully invoked our first service:

Apache OFBiz Service Engine: Part 1

Service Parameters

Just like Java methods, OFBiz services can have input and output parameters and just like Java methods, the parameter types must be declared.

Input Parameters (IN)

Our first service is defined with two parameters:

Any parameters sent to the service by the end-user as form parameters, but not in the services list of declared input parameters, will be dropped. Other parameters are converted to a Map by the framework and passed into our static method as the second parameter.

Add a new method handleInputParamaters to our LearningServices class.

public static Map handleParameters(DispatchContext dctx, Map context){

String firstName = (String)context.get("firstName");
String lastName = (String)context.get("lastName");
String planetId= (String)context.get("planetId");

String message = "firstName: " + firstName + "
message = message + "lastName: " + lastName + "
message = message + "planetId: " + planetId;

Map resultMap = ServiceUtil.returnSuccess(message);
return resultMap;

We can now make our service definition invoke this method instead of the learningFirstService method by opening our services.xml file and replacing:

  location="org.ofbiz.learning.learning.LearningServices" invoke="learningFirstService">


  location="org.ofbiz.learning.learning.LearningServices" invoke="handleParameters">

Once again shutdown, recompile, and restart OFBiz.

Enter for fields First Name, Last Name, and Planet Id values Some, Name, and Earth, respectively. Submit and notice that only the first two parameters went through to the service. Parameter planetId was dropped silently as it was not declared in the service definition.

Apache OFBiz Service Engine: Part 1

Modify the service learningFirstService in the file ${component:learning}servicedefservices.xml, and add below the second parameter a third one like this:

Restart OFBiz and submit the same values for the three form fields, and see all three parameters go through to the service.

Apache OFBiz Service Engine: Part 1



Subscribe to the weekly Packt Hub newsletter

* indicates required


Please enter your comment!
Please enter your name here