Apache OFBiz Development: The Beginner's Tutorial

Apache OFBiz Development: The Beginner's Tutorial

By : Jonathon Wong, Rupert Howell

Buy this Book

Apache OFBiz Development: The Beginner's Tutorial

By: Jonathon Wong, Rupert Howell

Buy this Book

Overview of this book

<p>Apache OFBiz (Open For Business) is versatile open-source enterprise automation software that powers many small and medium sized businesses around the world. It incorporates a number of mature applications such as ERP, e-Commerce, MRP and CRM.<br /><br />Built around an MVC framework with common logic, data model and process components, Ofbiz allows existing and bespoke applications to be added through a component-based architecture. Ofbiz includes a mature suite of enterprise applications that integrate and automate a company's many business needs.<br /> <br />This easy-to-read book will quickly enable newcomers to get hands-on with OFBiz. It provides an overview of the main modules and employs illustrated examples that show readers how to build exemplary business applications rapidly. Covering the main aspects of the Model-View-Controller framework, the reader will gain a working knowledge of Widgets, Entities, and The Service Engine. The authors also describe how to tweak OFBiz, and offer valuable performance and development tips. By navigating through the flow of OFBiz and providing insight into the thousands of examples that already exist in the core code they have made this book a must-have for anyone looking to get started with OFBiz.</p>

Apache OFBiz Development

Credits

About the Authors

About the Reviewers

Preface

Free Chapter

Getting Started with OFBiz

Getting the OFBiz Code

Downloading and Installing SVN

Installing the Java Development Kit (JDK)

Downloading OFBiz Ready to Launch

Setting Up an Eclipse Project

Using Derby—the OFBiz Stock Database

Running OFBiz

Switching Off OFBiz

Our First Tour of OFBiz

Summary

Working with OFBiz

Adding Our First Field

Resetting Our Play Area Quickly

The Structure of OFBiz in General

The Model-View-Controller Architectural Pattern

Summary

Screen Widgets

Equipping Our Webapp with a Screen Widget View Handler

Using the Screen Widget View Handler

Files and Locations

Creating Our First Screen Widget

The Anatomy of the <section> Element

Nested Sections for Nested Conditions

Organizing a Large Screen into Smaller Screens

Screen Widget's Integration with FreeMarker

Cleaning Up in the "party" Component

Commenting Changes to the Core Code

Screen Widgets as Templates

Summary

Form Widgets

Files and Locations

Creating Our First Form Widget

Form Processing via Request Event

Java Events

Submitting and Processing Our First Form

The "list" Type Form Widget

The "multi" Type Form Widget

Alternative Targets in Two-Target Forms

Row-Level Actions

Summary

Other View Element Types in Screen Widgets

Menu Widgets

FreeMarker

Bringing it All Together

Summary

The Controller

How OFBiz Hears Our Requests—The Control Servlet

Programming a Control Servlet

Summary

Entities, View Entities, and Extended Entities

Accessing the Entities and View Entities

Setting-Up Our Playground

GenericValue Objects

Creating a Database Record

Updating Database Records

Deleting Database Records

Retrieving Database Records

Using the Entity Engine Cache

Dynamic View Entities

Paginating Using the EntityListIterator

Functions and Dynamic View Entities

Summary

The Events

Java Events

Working with the Database

Summary

The Service Engine

Defining a Service

Creating the Java Code for the Service

Testing Our First Service

Service Parameters

The DispatchContext

Service Security and Access Control

Calling Services from Java Code

Implementing Interfaces

Synchronous and Asynchronous Services.

Using the Job Scheduler

Quickly Running a Service

Naming a Service and the Service Reference

Event Condition Actions (ECA)

Summary

Permissions and the Service Engine

Simple Permissions

Two-Part Permissions and Special "_ADMIN" Permissions

Role Checks

Combining Multiple Checks

Nested Checks

Complex Permissions

Summary

Minilang

What is Minilang?

Defining a Simple Service

Simple Events

Validating and Converting Fields

Checking Security in Minilang

Invoking from Minilang

Minilang in Screen Widgets

Summary

Tying Up the Loose Ends

The OFBiz Look and Feel

Using FreeMarker

OFBiz Utilities

Outputting Different Formats

Summary

Tips and Techniques

Debugging Techniques

Debugging Java Code

Managing a Project Using Subversion

Apache HTTP Server and OFBiz using mod_proxy_ajp

Development Tips

Summary

Simple Method User's Guide

Customer Reviews

5 star

4 star

3 star

2 star

1 star

Appendix A. Simple Method User's Guide

The Simple Methods user guide specifies some of the most commonly used elements and attributes. Although more are available to use, they have been omitted from this guide as they are either deprecated, or simply not used. The complete XML schema from which this guide has been derived can be found at ${ofbizInstallFolder} /framework/minilang/dtd/simple-methods.xsd.

<simple-methods>

Opening tag of Simple Methods files.

<simple-method>

This is the opening tag for the Simple Method. The Simple Method can be called in either an event context from the Control Servlet (or another event), a service context through the Service Engine, or through any other component that has access to a service dispatcher.

Attribute Information:

`method-name="..."`	Required
The name as preferably a legal Java method name for this method. This name must be unique for the XML file it is in, as it will be used to reference this method externally.
`short-description="..."`	Required
A short description briefly describing the function of the method.
`Login-required="true\|false"`	(Optional—Defaults to `true`)
Checks if a user (UserLogin object, or `login.username` and `login.password` Strings) is required to be logged to run this method.
`Use-transaction="true\|false"`	(Optional—Defaults to `true`)
Determines whether the framework should create a transaction if none exists for the thread.

Usage

<simple-method method-name="createPostalAddressBoundary" short-description="Create Postal Address Boundary">
...
</simple-method>

Call Operations

We are able to call and process the results of static Java methods, BeanShell script and even invoke other services from our Simple Methods. These operations are available when the static method is called as an event or a service.

<call-map-processor>

The <call-map-processor> tag invokes a simple map processor from an existing Map, creating a new Map or adding to an existing one if the name out-Map already exists. Resulting messages are added to the name List, and a new List is created if a List with the given name does not yet exist. Note that all Lists and Maps exist in the same context and must have unique names. An inline simple-map-processor can be used by putting a simple-map-processor tag under the call-map-processor tag. If both, an external and an inline map-processor are specified, the external one will be called first, allowing the inline one to override its behavior.

Attribute Information

`xml-resource="..."`	Required only if external map processor is desired
The full path and filename on the classpath of the XML file which contains an external map processor to execute.
`processor-name="..."`	Required only if external map processor is desired
The name of the external map processor to execute in the specified xml-resource.
`in-map-name="..."`	Required
The name of a map in the method environment to use as the input map.
`out-map-name="..."`	Required
The name of a map in the method environment to use as the output map. Will be created if it does not exist already. If it already exists, it will be added to in place.

Usage

<call-map-processor xml-resource="org/ofbiz/accounting/payment/PaymentMapProcs.xml" processor-name="deletePaymentMethod" in-map-name="parameters" out-map-name="context"/>

<call-service> / <call-service-asynch>

The <call-service> tag invokes a service through the Service Engine. If the specified error code is returned from the service, the event is aborted and the transaction in the current thread is rolled back. Otherwise, the remaining operations are invoked.

The <result-to-request> and <result-to-session> elements will be ignored when called in a service context. So, they are only used when called in an event context.

The <call-service-asynch> tag calls a service asynchronously and ignores the result, so no return messages are used. This doesn't mean no errors will result, but they would just be system errors like database failures, and so on, which all have system error messages.

Attribute Information

`service-name="..."`	Required
Name of the service to call.
`in-map-name="..."`	Required
Optional name of a map in the method environment to use as the input map. If you're not going to pass any parameters to the service then you can just leave off the `in-map` name, although typically in a service tag you will see a service-name and the `in-map` name passed in.
`include-user-login="true\|false"`	Optional—defaults to `true`
by default, will include the user login so if there is a user login for the current simple-method it will pass that in to the service. If you don't want it to pass that in, you can just set this to `false`.
`break-on-error="true\|false"`	Optional—defaults to true. `<call-service>` only
If there's an error in the service, by default it will stop the current simple-method and return an error message that came from the service it called. If you don't want it to when there's an error, it can just be set to `false`.

Usage

<call-service service-name="updateCreditCard" in-map-name="uccMap" break-on-error="false"/>

<set-service-fields>

Looks at all of the incoming service attributes as specified in the service definition, looks for fields with the same name in the incoming map and copies those onto the outgoing map.

Attribute Information

`service-name="..."`	Required
Name of the service from which to take all incoming attributes.
`map-name="..."`	Required
Incoming map to copy fields from.
`To-map-name="..."`	Required
Map to copy fields to.

Usage

<set-service-fields service-name="updateCreditCard" map-name="creditCard" to-map-name="uccMap"/>

Handling the Results of Service Calls

The following operations are designed to handle the results, or OUT parameters from a synchronously called service.

<results-to-map>

The <results-to-map> tag takes all of the results of the service, the outgoing maps from the service and puts them in a map of the given map-name.

Attribute Details

`map-name="..."`	Required
Name of the map where results will be put in.

Usage

<call-service service-name="calculateAcctgTransTrialBalance" in-map-name="trialBalanceCallMap">
<results-to-map map-name="trialBalanceResultMap"/>
</call-service>

<result-to-field>

Specify the name of the field in the result and then the name of the field in the context you want to put it in, and optionally the name in the map. If no field-name is specified then the result-name will be used for the field-name, that's the name of the variable that will be created in the current context for the value of that result.

Attribute Details

`result-name="..."`	Required
Name of the result. May be used for the field-name. If you don't specify a field-name, this is the name of the variable that will be created in the current context for the value of that result.
`field-name="..."`	Optional
Optional field name.
`map-name="..."`	Optional
Optional map name.

Usage

<call-service service-name="createAgreement" in-map-name="createAgreementInMap">
<result-to-field result-name="agreementId" field-name="agreementIdTo"/>
</call-service>

<result-to-request>

The <result-to-request> tag is event specific. It takes the result with the given name and puts it in a request attribute with the given name here. The request-name is optional. If this is left it off then it will put it in an attribute with the name of the result-name.

Attribute Details

`result-name="..."`	Required
Name of the result. May be used for the request attribute name. If you don't specify a `request-name`, that's the name of the request attribute that will be created for the value of that result.
`request-name="..."`	Optional
Optional request name.

Usage

<call-service service-name="updateCreditCard" in-map-name="context">
<result-to-request result-name="paymentMethodId" request-name="paymentMethodId"/>
</call-service>

<result-to-result>

Service specific (when the Simple Method is being called as a service). It will take the result of the service you're calling with the call-service operation and it will put it in with the result of the current service. So result-name is the name of the result in the service that was called using the <call-service> tag.

These attributes are somewhat confusing: result-name is the name of the field in the result of this service call that the value comes from; service-result-name is the name of the field in the result of this simple-method called as a service where the value goes to; in other words from result-name and to

Attribute Details

`result-name="..."`	Required
Name of the field in the result of this service call that the value comes from.
`service-result-name="..."`	Optional
Name of the field in the result of this simple-method called as a service where the value goes to.

Usage

<call-service service-name="createPhysicalInventory" in-map-name="createPhysicalInventoryMap">
<result-to-field result-name="physicalInventoryId" field-name="physicalInventoryId" map-name="parameters"/>
<result-to-result result-name="physicalInventoryId" service-result-name="physicalInventoryId"/>
</call-service>

<call-bsh>

Runs an external bsh script from the classpath if the resource is specified and then runs the inlined bsh script if any is specified. The bsh context is the current simple-method environment including maps, lists and special objects whose names are defined in the simple-method attributes.

The current env cannot be modified, but if a Map is returned by the bsh block the entries in the map will be put into the current env.

Error messages go on the error list and are handled with the <check-errors> tag.

Attribute Details

`resource="..."`	Optional
Name of a properties file on the classpath.
`error-list-name="..."`	Optional—defaults to `error_list`
The name of the list in the method environment to check for error messages.

Usage

<call-bsh><!
[CDATA[
String password = (String) userLoginContext.get("currentPassword");
String confirmPassword = (String) userLoginContext.get("currentPasswordVerify");
String passwordHint = (String) userLoginContext.get("passwordHint");
org.ofbiz.common.login.LoginServices.checkNewPassword(newUserLogin, null, password, confirmPassword, passwordHint, error_list, true, locale);
]]></call-bsh>

<call-simple-method>

The <call-simple-method> tag calls another simple-method in the same context as the current one. In other words the called simple-method will have the same environment as the calling simple-method, including all environment fields, and either the event or service objects that the calling simple-method was called with.

Attribute Details

`xml-resource="..."`	Optional
The full path and filename on the classpath of the XML file which contains an external simple-method to execute. This is only required if a simple-method in a different file is desired.
`method-name="..."`	Required
The name of the simple-method to execute in the specified xml-resource, or in the current XML file if no xml-resource is specified.

Usage

<call-simple-method method-name="inlineCheckContactListMechType"/>

<call-object-method>

Calls a method on an existing object that exists in a field in the environment or in a map in the environment. The string and field sub-elements are passed to the method as arguments in the order they are specified. If the sub-elements do not match the method arguments, an error will be returned. The return value will be put in the named field if a value is returned and if a field and (optionally) Map name are specified.

Attribute Details

`obj-field-name="..."`	Required
The name of the field the object is in that has the method to be called.
`obj-map-name="..."`	Required
The nameof the map the field of the object is in, that has the method to be called. If this is not specified, the field will be taken from the environment.
`Method-name="..."`	Required
The name of the method to call on the given object.
`ret-field-name="..."`	Optional
The name of the field to put the result in. If not specified, any return value will be ignored.
`ret-map-name="..."`	Optional
The name of the map the field of the return value is in. If not specified, but the field name is, then the environment will be used to find the field in.

Usage

<call-object-method obj-field-name="USERNAME" obj-map-name="parameters" method-name="toLowerCase" ret-field-name="USERNAME" ret-map-name="parameters"/>

<call-class-method>

Calls a static method on a class. The string and field sub-elements are passed to the method as arguments in the order they are specified. If the sub-elements do not match the method arguments, an error will be returned. The return value will be put in the named field if a value is returned and if a field and optionally a Map name are specified.

Attribute Details

`Class-name="..."`	Required
The name of the class to call the static method on.
`method-name="..."`	Required
The name of the static method to call on the given class.
`ret-field-name="..."`	Optional
The name of the field to put the result in. If not specified, any return value will be ignored.
`ret-map-name="..."`	Optional
The name of the map the field of the returned value is in. If not specified, but the field name is, then the environment will be used to find the field in.

Usage

<call-class-method class-name="org.ofbiz.product.product.KeywordSearch" method-name="induceKeywords">
<field field-name="productInstance" type="org.ofbiz.entity.GenericValue"/>
</call-class-method>

Service Operations

The following operations are service specific, that is, they are only applicable when the Simple Method is called as a service.

<field-to-result>

The <field-to-result> tag copies a field from a Map to the specified service result field.

The tag is only used when the simple-method is called as a service, it is ignored otherwise.

Attribute Details

`Field-name="..."`	Required
The name (key) of the map field to use.
`map-name="..."`	Optional
The name of the map in the method environment. If not specified the field-name will be used to get the field from the method environment.
`result-name="..."`	Optional
The name of the request attribute to use. Defaults to the `field-name`.

Usage

<field-to-result field-name="agreementId" result-name="agreementId"/>

Event Operations

The following operations are event specific, that is, they are only applicable when the Simple Method is called as an event.

<session-to-field>

The <session-to-field> tag copies an attribute from the servlet session to a field of a map in the method environment.

Attribute Details

`Field-name="..."`	Required
The name (key) of the map field to use.

Usage

<session-to-field field-name="visit"/>

Environment Operations

The following environment operations deal with moving values from one field to another.

<set>

Moves a value from one field to another field. We can also take a value, just a string constant or a string that is made up of a mixture of constant and flexible string expansion variables using the ${} syntax, that will be put in the field. We can also specify a default value in the case that the value evaluates to an empty string, or the from field is null or empty. Then the default-value will be used. Again we can use the flexible string expander here, the ${} syntax and such. It can also do a type conversion. So going from whatever type the source data is in, which would be a string value or whatever the variable type is for a from field, it can convert that to any of these types before setting it in the target field.

Attribute Details

`Field="..."`	Required
Name of the field to copy value to.
`From-field="..."`	Optional
Name of the field to copy value from.
`Value="..."`	Optional
Simple value to copy in field.
`default-value="..."`	Optional
Default value to copy in field, if the value evaluates to an empty string or the from field is null or empty.
`Type="..."`	Optional
Type to convert to, can be: PlainString, String, BigDecimal, Double, Float, List, Long, Integer, Date, Time, Timestamp, Boolean, Object.
`set-if-null="true\|false"`	Optional—defaults to `true`
Specifies whether or not to set fields that are null or empty.
`set-if-empty="true\|false"`	Optional—defaults to `true`
If the source value, either from a value or from a field is empty, an empty-string, an empty list or a null value. In this case it's set to true. If you don't want to set it, if you want it to leave the target field alone when the source is empty, then you need to set this to false.

Usage

<set from-field="productStoreId" field="newEntity.productStoreId"/>

<clear-field>

The <clear-field> tag clears/removes the specified field.

Attribute Details

`map-name="..."`	Optional
The name of the map in the method environment. If not specified the field-name will be used to get the field from the method environment.
`Field-name="..."`	Required
The name (key) of the map field to use.

Usage

<clear-field field-name="variantProduct"/>

<first-from-list>

The <first-from-list> tag will get the first entry from the given list and put it in the environment field with the given entry-name.

Attribute Details

`Entry-name="..."`	Required
The name of the method environment field that will contain the first entry in the list.
`List-name="..."`	Required
The name of the method environment field that contains the list to get the first entry from.

Usage

<first-from-list entry-name="statusItem" list-name="contentStatus"/>

Miscellaneous Entity Operations

The following miscellaneous operations deal with obtaining primary or sequenced keys.

<sequenced-id-to-env>

The <sequenced-id-to-env> tag gets a sequenced ID from the Entity Engine (through the delegator) and puts it in the specified method environment field. The object will be a java.lang.Long, but can of course be converted to a String.

Attribute Details

`Sequence-name="..."`	Required
The name of the sequence to pass to the delegator. The same name must always be used for sequenced IDs that will be used for a certain entity field otherwise non-unique keys may result.
`env-name="..."`	Required
The name of the method environment field the sequenced ID will be put in.
`stagger-max="..."`	Optional
By default this is one. But if you want to have sequenced IDs that are staggered, instead of consecutive, then you can set this to something like twenty. And then it will do a random staggering for each sequenced id. Instead of picking the next value all the time it will pick something between the next value and twenty away from the next value, if stagger-max is set to twenty. So that can be used to make the sequenced Ids more difficult to guess.

Usage

<sequenced-id-to-env sequence-name="OrderHeader" env-name="orderId"/>

<make-next-seq-id>

Whereas <sequenced-id-to-env> is the primary key sequencer, <make-next-seq-id> is the secondary key sequencer. So this would be something like an orderId for example, where we're sequencing an orderId automatically. And this would be something like an orderItemSequenceId, where we have a sub-sequence that varies for order item records related back to an orderHeader. So all of them will have the same orderId.

Attribute Details

`value-name="..."`	Required
Specify the name of the entity for a `sequenced-id-to-env` preparing the `primarySequencedId`. The name of the entity is typically what we use for the sequenced name, but you can use anything you want, if you want to have different sets of sequences. The risk of course (in having many different sets of sequences for the same entity) is that unless you somehow prefix or suffix the value, you could have a key conflict. So we just use the entity name for these primary sequences.
`seq-field-name="..."`	Required
The field that will have the sub-sequenced value. We use the `seqId` suffix on the field names in the OFBiz data model to denote that that field is a secondary sequenced ID and should therefore be maintained for this sort of operation.
`numeric-padding="..."`	Optional—defaults to `5`
Since these are eventually strings we do numeric-padding so that the sort is consistent. By default we pad it with five positions. For example `00001`.
`increment-by="..."`	Optional—defaults to `1`
If you want to leave some space in the sub-sequence you can use a greater increment.

Usage

<make-next-seq-id value-name="newOrderItem" seq-field-name="orderItemSeqId"/>

Entity Find Operations

Entity Find Operations deal with retrieving data from the database.

<entity-one>

Performs a find by primary key lookup, returning a single GenericValue object if it's found, otherwise it returns null. This operation replaces the deprecated <find-by-primary-key> operation.

Attribute Details

`entity-name="..."`	Required
Name of the entity to look for.
`value-name="..."`	Required
Name of the variable to put the GenericValue in.
`use-cache="true\|false"`	Optional—defaults to `false`
Specifies whether or not the delegator's cache should be searched before going to the database. This results in much faster retrieval times, but can return stale data that is not the most current in the database.
`auto-field-map="true\|false"`	Optional—defaults to `true`
Specifies whether to look for all primary key field names in the current context as well as in the parameters map or not.

Usage

<entity-one entity-name="OrderHeader" value-name="orderHeader" auto-field-map="true"/>

<entity-and>

Performs a find-by-and lookup, returning a list of GenericValues if any are found, otherwise returning null. Uses name/value pairs, that will be used for the query and will all be "anded" together. The result-set-type by default is scroll which is flexible so we can go forward. This operation replaces the deprecated <find-by-and> operation and uses the <field-map> sub-element to pass in lookup criteria.

Attribute Details

`entity-name="..."`	Required
Name of the entity to look for.
`list-name="..."`	Required
Name of the variable to put the `GenericValue` in.
`use-cache="true\|false"`	Optional—defaults to `false`
Specifies whether or not the delegator's cache should be searched before going to the database. This results in much faster retrieval times, but can return stale data that is not the most current in the database.
`filter-by-date="true\|false"`	Optional—defaults to `false`
Look for from date and through date fields in the list of results coming back, and filters by the current date and time if set to true.

Usage

<entity-and entity-name="ProductFacility" list-name="products">
<field-map env-name="parameters.facilityId" field-name="facilityId"/>
</entity-and>

<entity-condition>

Like <entity-and> returns a list of GenericValues if any are found, otherwise returns null.

Uses any of <condition-expression>, <condition-list> and <condition-object> sub-elements to specify the lookup criteria.

Attribute Details

`entity-name="..."`	Required
Name of the entity to look for.
`list-name="..."`	Required
Name of the variable to put the `GenericValue` in.
`use-cache="true\|false"`	Optional defaults to `false`
Specifies whether or not the delegator's cache should be searched before going to the database. This results in much faster retrieval times, but can return stale data that is not the most current in the database.
`filter-by-date="true\|false"`	Optional defaults to `false`
Look for from date and through date fields in the list of results coming back and filters by the current date and time if set to true.

Sub-Elements

The following sub-elements are used by the entity-condition operation to specify WHERE conditions, HAVING conditions, fields to select and fields to order by.

<condition-list>

A <condition-list> is a list of conditions that are combined with either and or or. The default is and. We can have condition-lists under condition-list, for building fairly complex condition trees, and we may also drop in condition-objects at any point.

Usage

<condition-list combine="and">
<condition-expr field-name="partyId" operator="equals" env-name="parameters.partyId"/>
<condition-expr field-name="roleTypeId" operator="equals" env-name="parameters.roleTypeId"/>
</condition-list>

The <condition-expr> tag basically combines a field, a SQL operator and a variable or a value. The variable is actually a field in the context : env-name. There are some options when to ignore the condition, namely if the env-name or value is empty or null.

<having-condition-list>

Similar to condition-list but relates to SQL grouping : having-condition runs after the grouping.

<select-fields>

Name of the field to select.

Usage

<select-field field-name="partyId"/>

<order-by>

Defines fields to order list by.

Usage

<order-by field-name="-changeDate"/>

<entity-condition> complete example:

<entity-condition entity-name="OrderHeaderAndRoleSummary" list-name="orderInfoList">
<condition-list combine="and">
<condition-expr field-name="partyId" operator="equals" env-name="parameters.partyId"/>
<condition-expr field-name="roleTypeId" operator="equals" env-name="parameters.roleTypeId"/>
<condition-expr field-name="orderTypeId" operator="equals" env-name="parameters.orderTypeId"/>
<condition-expr field-name="statusId" operator="equals"
env-name="parameters.statusId"/>
<condition-expr field-name="orderDate" operator="greater-equals" env-name="parameters.fromDate" ignore-if-null="true"/>
<condition-expr field-name="orderDate" operator="less-equals" env-name="parameters.thruDate" ignore-if-null="true"/>
</condition-list>
<select-field field-name="partyId"/>
<select-field field-name="roleTypeId"/>
<select-field field-name="totalGrandAmount"/>
<select-field field-name="totalSubRemainingAmount"/>
<select-field field-name="totalOrders"/>
<order-by field-name="partyId"/>
</entity-condition>

<entity-count>

The <entity-count> tag is very similar to the <entity-condition>. Specify the entity-name, optionally the delegator-name if you want to override that, and then the name of the variable to put the count in. You can do the same condition-expr (condition expression) or condition-list which can have condition-expr and other condition-lists underneath it for a tree of conditions that can be arbitrarily complex. You can also use the having-condition-list, this is the same as on the entity-condition. What this will do basically is, rather than doing a query and getting the results back, it will just count the results and put that number in the context in the variable named by the count-name.

Usage

<entity-count entity-name="ReturnAdjustment"
count-name="returnCount">
<condition-expr field-name="orderAdjustmentId" operator="equals" env-name="orderAdjustment.orderAdjustmentId"/>
</entity-count>

<get-related-one>

If we have a GenericValue object sitting in the context and we want to get a related entity following one of the type one relationships in the data model, then we can specify the name of the value here, relation-name, which is the name of the relationship between the two entities, and the to-value where it should put the result.

Attribute Details

`value-name="..."`	Required
Name of a generic value sitting in the context from where you want to get a related-one generic value.
`relation-name="..."`	Required
Name of the one-relation to use to relate a generic value in value-name, to a generic value in to-value.
`to-value-name="..."`	Required
Name of a GenericValue where to put the result.
`use-cache="true\|false"`	Optional—defaults to false
Specifies whether or not the delegator's cache should be searched before going to the database. This results in much faster retrieval times, but can return stale data that is not the most current in the database.

Usage

<get-related-one value-name="orderHeader" relation-name="ProductStore" to-value-name="productStore" use-cache="true"/>

<get-related>

<get-related> is just like <get-related-one>, except that instead of getting a single value back to put in the to-value, it gets a full List back. We start with the value object, and specify the name of the relationship. We can specify the name of a map that will restrain the query further, beyond the field mappings and their relationship.

We can also specify how you want to order it.

Attribute Details

`value-name="..."`	Required
Name of a `GenericValue` sitting in the context from where we want to get related `GenericValues`.
`relation-name="..."`	Required
Name of the one-relation to use to relate `GenericValue` in value-name to `GenericValue` in `to-value`.
`list-name="..."`	Required
Name of a list to put the result in.
`map-name="..."`	Optional
Name of a map that will restrain the query further, beyond the field mappings and their relationship.
`order-by-list-name="..."`	Optional
This will be a list sitting in the context that has string entries in it for each field that we want it to order by. Each field in the list, or each entry in the list, will just be a string with a field name. It can be preceded by a plus or a minus to specify an ascending or descending sort. The default is ascending sort, so we just put a minus in front of the field-name if we want it to be descending.
`use-cache="true\|false"`	Optional—defaults to false
Specifies whether or not the delegator's cache should be searched before going to the database. This results in much faster retrieval times, but can return stale data that is not the most current in the database.

Usage

<get-related value-name="order" relation-name="OrderItem" list-name="orderItems"/>

<order-value-list>

The <order-value-list> operation does not actually do anything with the database. It takes an existing List that has been returned and sorts it.

Attribute Details

`list-name="..."`	Required
Name of the list of generic value objects that we want to sort.
`order-by-list-name="..."`	Required
This will be a list sitting in the context that has string entries in it for each field that you want it to order by. Each field in the list, or each entry in the list, will just be a string with a field name. It can be preceded by a plus or a minus to specify an ascending or descending sort for that. The default is ascending sort, so you just put a minus in front of the field-name if you want it to be descending.
`to-list-name="..."`	Optional
Name of the output list. If it is empty, as it is optional, it will simply use the list-name. In other words it will take the ordered list and put it over top of the resource list.

Usage

<order-value-list list-name="facilityLocationList" order-by-list-name="facilityLocsOrdLst"/>

<filter-list-by-and>

The <filter-list-by-and> tag filters the given list by the fields in the specified map.

Attribute Details

`list-name="..."`	Required
The name of the method environment field that contains the list of GenericValue objects.
`to-list-name="..."`	Optional
The name of the method environment field the filtered list will be put into. Defaults to the value of the `list-name` attribute (For example, it goes to the same place it came from, replacing the old `List).`
`map-name="..."`	Optional
The name of a `Map` in the method environment that will be used for the entity fields. If no `Map` is used this will just make a copy of the `List`.

Usage

<filter-list-by-and map-name="itemFilterMap" list-name="orderReadyToPickInfo.orderItemShipGrpInvResList" to-list-name="perItemResList"/>

<filter-list-by-date>

The <filter-list-by-date> tag filters the given list by the valid date using the from and thru dates in each value object.

Attribute Details

`list-name="..."`	Required
The name of the method environment field that contains the list of GenericValue objects.
`to-list-name="..."`	Optional
The name of the method environment field the filtered list will be put into. Defaults to the value of the list-name attribute (For example, it goes to the same place it came from, replacing the old list).
`valid-date-name="..."`	Optional
The name of a field in the method environment date to filter by. Defaults to now.
`from-field-name="..."`	Optional—defaults to "fromDate".
The name of the GenericValue field to use as the beginning effective date.
`thru-field-name="..."`	Optional—defaults to "thruDate".
The name of the GenericValue field to use as the beginning effective date.
`all-same="true\|false"`	Optional—defaults to `true`
Specifies whether or not all GenericValue objects in the list are of the same entity.

Usage

<filter-list-by-date list-name="emailAddressesAll" from-field-name="fromDate" to-list-name="emailAddresses"/>

Entity Value Operations

These operations deal with persisting, updating and removing values to and from the database.

<make-value>

The make-value tag uses the delegator to construct an entity value. The resulting value will not necessarily exist in the database, but will simply be assembled using the entity-name and fields map. The resulting GenericValue object will be placed in the method environment using the specified value-name.

Attribute Details

`value-name="..."`	Required
The name of the method environment field that contains the GenericValue object.
`entity-name="..."`	Required
The name of the entity to construct an instance of.
`map-name="..."`	Required
The name of a map in the method environment that will be used for the entity fields.

Usage

<make-value value-name="newEntity" entity-name="OrderHeader"/>

<clone-value>

The <clone-value> tag makes a copy of the value in the method environment field specified by value-name. The resulting GenericValue object will be placed in the method environment using the specified new-value-name.

Attribute Details

`value-name="..."`	Required
The name of the method environment field that contains the `GenericValue` object.
`new-value-name="..."`	Required
The name of the method environment field that will contain the new `GenericValue` object.

Usage

<clone-value value-name="partyContactMech" new-value-name="newPartyContactMech"/>

<create-value>

The <create-value> tag persists the specified GenericValue object by creating a new instance of the entity in the datasource.

An error will result if an instance of the entity exists in the datasource with the same primary key.

Attribute Details

`value-name="..."`	Required
The name of the method environment field that contains the GenericValue object.
`do-cache-clear="true\|false"`	Optional defaults to true
Clears the cache.

Usage

<create-value value-name="newEntity"/>

<store-value>

The <store-value> tag persists the specified GenericValue object by updating the instance of the entity in the datasource. An error will result if an instance of the entity does not exist in the datasource with the same primary key.

Attribute Details

`value-name="..."`	Required
The name of the method environment field that contains the GenericValue object.
`do-cache-clear="true\|false"`	Optional—defaults to `true`
Clears the cache.

Usage

<store-value value-name="orderHeader"/>

<refresh-value>

Forces a value to refresh from the database.

Attribute Details

`value-name="..."`	Required
The name of the method environment field that contains the GenericValue object.
`do-cache-clear="true\|false"`	Optional—defaults to `true`
Clears the cache.

Usage

<refresh-value value-name="newEntity"/>

<remove-value>

The remove-value tag removes the specified GenericValue object by removing the instance of the entity in the datasource.

Attribute Details

`value-name="..."`	Required
The name of the method environment field that contains the GenericValue object.
`do-cache-clear="true\|false"`	Optional—defaults to `true`
Clears the cache.

Usage

<remove-value value-name="someEntity"/>

<remove-related>

Given a value name and a relationship name, this operation follows the relationship and removes all related records, whether they be a type one or type many relationship.

For a type one relationship it will remove a single record if it exists, and for a type many relationship it will remove all the records that are related to it.

This of course can be dangerous. For example if we have a product-type entity and we do a remove-related with a certain product type value object here, and the relation name product here, it will remove all products of that type. This is of more value when we are doing something like removing an order or removing a product, and we want to remove all related elements before removing the product to resolve foreign key issues. Usually the best practice for that, is to do a remove-related on certain types of information related to the product, and then try to remove the product but not remove all related tables.

In many cases, if the product has been ordered for example, then you do not want to remove the product, and so you can do all these remove-related(s).

Attribute Details

`value-name="..."`	Required
The name of the method environment field that contains the GenericValue object.
`relation-name="..."`	Required
Name of a relation to use to remove related records.
`do-cache-clear="true\|false"`	Optional—defaults to `true`
Clears the cache.

Usage

<remove-related value-name="content" relation-name="ContentRole"/>

<remove-by-and>

The <remove-by-and> tag uses the delegator to remove entity values from the datasource and is constrained by "anding" the fields passed in the Map. Make sure the Map contains something, or all values will be removed.

Attribute Details

`entity-name="..."`	Required
The name of the entity to remove instances of.
`map-name="..."`	Required
The name of a map in the method environment that will be used for the entity fields.
`do-cache-clear="true\|false"`	Optional defaults to true
Clears the cache.

Usage

<remove-by-and entity-name="ProductPrice" map-name="productFindContext"/>

<set-pk-fields> / <set-nonpk-fields>

Looks for each primary key / non primary key field in the named map and if it exists there, it will copy it into the named value object.

Attribute Details

`value-name="..."`	Required
The name of the method environment field that contains the `GenericValue` object.
`map-name="..."`	Required
The name of a map in the method environment that will be used for the entity fields.
`set-if-null="true\|false"`	Optional—defaults to `true`
Specifies whether or not to set fields that are null or empty.

Usage

<set-nonpk-fields map-name="parameters" value-name="newEntity"/>
<set-pk-fields map-name="parameters" value-name="newEntity"/>

<store-list>

The <store-list> tag uses the delegator to store all entity values in the list. This is different than storing a single value using the <store-value> operation in that values in the List will be inserted if they do not exist, or updated if they do.

Attribute Details

`list-name="..."`	Required
The name of the method environment field that contains the list of GenericValue objects.
`do-cache-clear="true\|false"`	Optional—defaults to `true`
Clears the cache.

Usage

<store-list list-name="returnItems"/>

Control Operations

Control operations allow us to iterate through Lists and Maps, add and check errors, and return from the Simple Method.

<iterate>

The operations contained by the iterate tag will be executed for each of the entries in the List, and will make the current entry available in the method environment by the entry-name specified. This tag can contain any of the simple-method operations, including the conditional/if operations. Any simple-method operation can be nested under the iterate tag.

Attribute Details

`Entry-name="..."`	Required
The name of the method environment field that will contain each entry as we iterate through the list.
`list-name="..."`	Required
The name of the method environment field that contains the list to iterate over.

Usage

<iterate list-name="orderItems" entry-name="orderItem">
...
</iterate>

<iterate-map>

The operations contained by the iterate-map tag will be executed for each of the entries in the map. It will run all of the operations underneath the iterate-map-element for each of the entries in the given map, setting the key for that entry and the key-name variable, and the value for that entry and the value-name variable. This tag can contain any of the simple-method operations, including the conditional/if operations. Any simple-method operation can be nested under the iterate-map tag.

Attribute Details

`Key-name="..."`	Required
Name of the variable to put the key in.
`Value-name="..."`	Required
Name of the variable to put the value in.
`Map-name="..."`	Required
Name of the map to use.

Usage

<iterate-map map-name="inventoryItemQuantities" key-name="inventoryItemId" value-name="quantityNeeded">
...
</iterate-map>

<check-errors>

The message lists from invoking are not checked until the <check-errors> tag is used.

The named List is checked and if it contains any messages they are put in the servlet request object, and the specified error code is returned to the control servlet.

Attribute Details

`Error-code="..."`	Optional—defaults to `error`
Defaults to error.
`Error-list-name="..."`	Optional—defaults to `error_list`
The name of the list in the method environment to check for error messages.

Usage

<check-errors/>

<add-error>

Adds an error message to the given error list from either an inline message or a message from a properties file using the sub elements <fail-message> or <fail-property>.

Attribute Details

`Error-list-name="..."`	Optional—defaults to `error_list`
The name of the list in the method environment to add the error message to.

Usage

<add-error>
<fail-property resource="PartyUiLabels" property="PartyPermissionErrorForThisParty"/>
</add-error>

<return>

Returns immediately from the simple-method with the given response code string.

Attribute Details

`response-code="..."`	Optional—defaults to `success`
The string to return as a response code.

Usage

<return/>

If Conditions

These operations allow us to control the flow through the Simple Method depending on simple if tests.

<if-validate-method>

The operations contained by the <if-validate-method> tag will only be executed if the validate method returns true. <if-validate-method> calls a static Java method that takes a String and returns a boolean. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Details

`Field-name="..."`	Required
The name of the map field that will be validated.
`method="..."`	Required
The name of the method that will be called to validate the field. It must be a static method that takes a single `String` parameter and returns a `boolean`.
`Map-name="..."`	Optional
The name of the method environment field that contains the map that the field to be validated will come from. If not specified the `field-name` will be treated as a method environment field name (an env-name).

Usage

<if-validate-method field-name="${answerFieldName}" method="isCreditCard">
... success operations ....
<else>
... failure operations ...
</else>
</if-validate-method>

<if-instance-of>

Checks if the field is an instance of the name class.

Attribute Details

`field-name="..."`	Required
The name of the map field that will be validated as being an instance of the named class.
`class="..."`	Required
The name of the class that the named instance in field-name is supposed to belong.

Usage

<if-instance-of field-name="parameters.categories" class="java.util.List">
... success operations ....
<else>
if conditions<if-instance-of>, usage... failure operations ...
</else>
</if-instance-of>

<if-compare>

The operations contained by the <if-compare> tag will only be executed if the comparison returns true. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Details

`field-name="..."`	Required
The name of the map field that will be compared.
`value="..."`	Required
The value that the field will be compared to. Must be a String, but can be converted to other types.
`map-name="..."`	Optional
The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an env-name).

Usage

<if-compare field-name="product.productTypeId" operator="not-equals" value="DIGITAL_GOOD"/>
... success operations ....
<else>
... failure operations ...
</else>
</if-compare>

<if-compare-field>

The operations contained by the <if-compare-field> tag will only be executed if the comparison returns true. This tag can contain any of the simple-method operations, including the conditional/if operations.

Attribute Details

`field-name="..."`	Required
The name of the map field that will be compared.
`map-name="..."`	Optional
The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an env-name).
`to-field-name="..."`	Optional
The name of the to-map field that the main field will be compared to. If left empty, will default to the field-name.
`to-map-name="..."`	Optional
The name of the method environment field that contains the map that the field to be compared will come from. If left empty will default to the method environment. It does not default to the map-name because that would make it impossible to compare a map field to an environment field.

Usage

<if-compare-field field-name="inventoryFacilityId" map-name="store" operator="not-equals" to-field-name="oldFacilityId">
... success operations ....
<else>
... failure operations ...
</else>
</if-compare-field>

<if-empty> / <if-not-empty>

The operations contained by the <if-empty> / <if-not-empty> tag will only be executed if the map field is empty / not empty. These tags can contain any of the simple-method operations, including the conditional/if operations.

Attribute Details

`field-name="..."`	Required
The name of the map field that will be compared.
`map-name="..."`	Optional
The name of the method environment field that contains the map that the field to be validated will come from. If not specified the field-name will be treated as a method environment field name (an `env-name`).

Usage

<if-empty field-name="parameters.roleTypeId">
if conditions<if-not-empty>, usage... success operations ....
<else>
if conditions<if-empty>, usage... failure operations ...
</else>
</if-empty>

Conditions:

Nested conditions are acceptable in Minilang. Consider the following example:

<if>
<condition><not><if-empty field-name="parameters.groupName"/> </not></condition>
<then>
<entity-one entity-name="PartyGroup" value-name="partyGroup"/>
<if>
<condition><if-compare-field field-name="partyGroup.groupName" operator="not-equals" to-field-name="parameters.groupName"/> </condition>
<then>
<set-nonpk-fields value-name="partyNameHistory" map-name="partyGroup"/>
<create-value value-name="partyNameHistory"/>
</then>
</if>
</then>
</if>

Other Operations

These operations allow us to add Debug messages, calculate values or obtain the Timestamp value for this instant.

<log>

The <log> tag logs a message used by the OFBiz Debug class, which uses Log4J to log to the console, a file, or some other location. The message is a concatenation of the message attribute and then all of the field and string sub-element values in the order they are specified. Possible levels, which relate to the logging levels set in debug.properties are: verbose, timing, info, important, warning, error, fatal, always.

Usage

<log level="info" message="Contact mech created with id ${newValue.contactMechId}"/>

<now-timestamp-to-env>

The <now-timestamp-to-env> tag creates a java.sql.Timestamp object with the current date and time in it and puts it in a field in the method environment.

Usage

<now-timestamp-to-env env-name="nowTimestamp"/>

<now-date-to-env>

The <now-date-to-env> tag creates a java.sql.Date object with the current date in it and puts it in a field in the method environment.

Usage

<now-date-to-env env-name="nowDate"/>

<set-current-user-login>

The <set-current-user-login> tag sets the UserLogin GenericValue object to be used for authentication for the rest of the method. This is mostly used for calling services, and so on.

Usage

<set-current-user-login value-name="createdUserLogin"/>

<calculate>

The <calculate> tag performs the specified calculation and puts the result in an object in the field of the specified Map.

The type of the object can be specified with the type attribute, this defaults to Double. The calculate tag can contain <calcop> and <number> tags, and the <calcop> tag can also contain these two tags to enable nested calculations. The operator specifies the operation to perform on the given field and nested calcops and numbers. It must be one of the following: get | add | subtract | multiply | divide | negative.

Attribute Details

`field-name="..."`	Required
The name (key) of the `Map` (or `env` if `map-name` is empty) field to use.
`map-name="..."`	Optional
The name of the map in the method environment. If not specified the `field-name` will be used to get the field from the method environment.
`type="..."`	Optional—defaults to `Double`
Specifies the type of the object. Can be `String` \| `Double` \| `Float` \| `Long\| Integer`.
`rounding-mode="..."`	Optional—defaults to `Double`
Rounding mode for `BigDecimal` calculation, primarily for divide operation.
`rounding-mode="..."`	Optional—defaults to `Double`
Rounding mode for `BigDecimal` calculation, primarily for divide operation. Can be `Ceiling` \| `Floor` \| `Up` \| `Down` \| `HalfUp` \| `HalfDown` \| `HalfEven` \| `Unnecessary`.
`decimal-scale="..."`	Optional—defaults to `2`
Initial scale to use for the internal `BigDecimal`. Defaults to `2` for monetary calculations.

Usage

<set field="productCost" value="0" type="Double" />
<calculate field-name="productCost" type="Double" decimal-scale="6">
<calcop field-name="laborCost.cost" operator="add">
<calcop field-name="materialsCost.cost" operator="get"/>
<calcop field-name="routeCost.cost" operator="get"/>
<calcop field-name="otherCost.cost" operator="get"/>
</calcop>
</calculate>

Apache OFBiz Development: The Beginner's Tutorial

By : Jonathon Wong, Rupert Howell

Apache OFBiz Development: The Beginner's Tutorial

By: Jonathon Wong, Rupert Howell

Overview of this book

Related Content you might be interested in

Current Title:

Apache OFBiz Development: The Beginner's Tutorial

Appendix A. Simple Method User's Guide

<simple-methods>

<simple-method>

Attribute Information:

Usage

Call Operations

<call-map-processor>

Attribute Information

Usage

<call-service> / <call-service-asynch>

Attribute Information

Usage

<set-service-fields>

Attribute Information

Usage

Handling the Results of Service Calls

<results-to-map>

Attribute Details

Usage

<result-to-field>

Attribute Details

Usage

<result-to-request>

Attribute Details

Usage

<result-to-result>

Attribute Details

Usage

<call-bsh>

Attribute Details

Usage

<call-simple-method>

Attribute Details

Usage

<call-object-method>

Attribute Details

Usage

<call-class-method>

Attribute Details

Usage

Service Operations

<field-to-result>

Attribute Details

Usage

Event Operations

<session-to-field>

Attribute Details

Usage

Environment Operations

<set>

Attribute Details

Usage

<clear-field>

Attribute Details

Usage

<first-from-list>

Attribute Details

Usage

Miscellaneous Entity Operations

<sequenced-id-to-env>

Attribute Details

Usage

<make-next-seq-id>

Attribute Details

Usage

Entity Find Operations

<entity-one>

Attribute Details

Usage

<entity-and>

Attribute Details

Usage