The Mini-Language concept in Open For Business is similar to the Gang of Four Interpreter pattern, or the Mark Grand Little Language pattern. This is also the central theme of the Building Parsers with Java book by Steven John Metsker which the OFBiz Rule Engine is based on. The idea is to create simple languages that simplify complex or frequently performed tasks.
In business software there are things that are done hundreds or thousands of times in a single application that a Mini-Language can simplify to the point of cutting implementation and maintenance times not by just 50%, but often as much as 70-90%. Yes, certain tasks will take only 10% of the effort and knowledge to perform. This makes it easier people not familiar with the software to manipulate existing or build new functionality.
Mini-Languages tend to have instructions that are more like method calls in a general purpose language. They are meant to solve a specific problem in a specific context, and are generally worthless or need to be modified for other contexts or problems.
Often this idea is implemented using a free form (BNF) or english-like syntax. In Open For Business the Mini-Languages are expressed as XML files to simplify the learning and manipulation of the syntax, in addition to making the Mini-Languages easier to write and extend.
The DTD for the simple-map-processor and simple-method XML files is in the distribution in ofbiz/core/docs/xmldefs/ofbiz/simple-methods.dtd or on the website at www.ofbiz.org/dtds/simple-methods.dtd. These are combined into a single DTD to make it easy to use inlined simple-map-processors inside a simple-method.
To specify the DOCTYPE for a simple-map-processors XML file use the following:
<!DOCTYPE simple-map-processors PUBLIC "-//OFBiz//DTD Simple Methods//EN" "http://www.ofbiz.org/dtds/simple-methods.dtd">
To specify the DOCTYPE for a simple-methods XML file use the following:
<!DOCTYPE simple-methods PUBLIC "-//OFBiz//DTD Simple Methods//EN" "http://www.ofbiz.org/dtds/simple-methods.dtd">
The only difference between the two DOCTYPE definitions is the root node to use from the DTD.
The Simple Map Processor Mini-Language performes two primary tasks: validation and conversion. It does this in a context of moving values from one Map to another. The input map will commonly contain Strings, but can contain other object types like Integer, Long, Float, Double, java.sql.Date, Time, and Timestamp.
NOTE: The reference information for the simple-map-processor has been moved to annotations in the simple-methods.xsd file.
<!DOCTYPE simple-map-processors PUBLIC "-//OFBiz//DTD Simple Methods//EN" "http://www.ofbiz.org/dtds/simple-methods.dtd">
<simple-map-processors>
<simple-map-processor name="update">
<make-in-string field="estimatedStartDate">
<in-field field="estimatedStartYear"><constant>-</constant>
<in-field field="estimatedStartMonth"><constant>-</constant>
<in-field field="estimatedStartDay"><constant>T</constant>
<in-field field="estimatedStartHour"><constant>:</constant>
<in-field field="estimatedStartMinute"><constant>:</constant>
<in-field field="estimatedStartSecond">
</make-in-string>
<process field="workEffortId"><copy replace="false"/></process>
<process field="scopeEnumId"><copy/></process>
<process field="currentStatusId"><copy/><not-empty><fail-message message="Status is missing."/></not-empty></process>
<process field="priority"><convert type="Long"><fail-message message="Priority is not a valid whole number."/></convert></process>
<process field="estimatedStartDate">
<compare-field operator="less" field="estimatedCompletionDate" type="Timestamp" format="yyyy-MM-dd'T'HH:mm:ss">
<fail-message message="Estimated Start date/time must be BEFORE End date/time."/></compare-field>
<convert type="Timestamp" format="yyyy-MM-dd'T'HH:mm:ss">
<fail-message message="Estimated Start Date is not a valid Date-Time."/></convert></process>
<process field="estimatedCompletionDate">
<convert type="Timestamp"><fail-message message="Estimated Completion Date is not a valid Date-Time."/></convert></process>
<process field="estimatedMilliSeconds">
<convert type="Double"><fail-message message="Estimated Milli-seconds is not a valid number."/></convert></process>
</simple-map-processor>
<simple-map-processor name="delete">
<process field="workEffortId"><copy/><not-empty><fail-message message="Work Effort ID is missing."/></not-empty></process>
</simple-map-processor>
</simple-map-processors>
The Simple Method Mini-Language is a simple way to implement an event that is invoked by the Control Servlet or a service that is invoked by the Service Engine. A Simple Method can be invoked through the static methods on the SimpleMethod class, or as an event through an entry in the controller configuration XML file like the following:
<event type="simple" path="org/ofbiz/commonapp/workeffort/workeffort/WorkEffortSimpleEvents.xml" invoke="update"/>
or as a service through an entry in a services.xml file like the following:
<service name="createPartyRole" engine="simple"
location="org/ofbiz/commonapp/party/party/PartyRoleServices.xml" invoke="createPartyRole" auth="true">
<description>Create a Party Role (add a Role to a Party)</description>
<attribute name="partyId" type="String" mode="IN" optional="true"/>
<attribute name="roleTypeId" type="String" mode="IN" optional="false"/>
</service>
The path or location for a Simple Method is the classpath and filename of the XML file.
In this Mini-Language you can invoke Simple Map Processors, Services and bsh scripts, perform entity related operations, and create messages to return to the caller. Specific operations can be enclosed in if blocks to execute conditionally and values or fields can be copied around in the maps, lists and method environment.
There are a number of tags which can be used to get and set attributes to/from a request or session object when called as an event or to set attributes in the result when called as a service. These operations are only applied when applicable. In other words if you include a env-to-request operation it will only be invoked when the simple-method is called as an event and a env-to-result operation will only be invoked when the simple-method is called as a service. Everything else is the same when called as an event or a service which makes it easy to write flexible logic that can be mounted/applied in various ways.
There are a number of objects that exist in the method environment when a simple-method starts or that are used as it executes to keep track of certain information. Some will exist when called as an event or a service, these are marked in the following list. Each name can be overridden using an attribute on the simple-method tag. The defaults are listed below (you can also find them in the DTD).
Here is a complete list of the attributes of the simple-method tag:
| Attribute Name | Reqd? | Default Value | Description |
| method-name | Y | N/A | A name (preferably a legal Java identifier) 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 | Y | N/A | A short description of the method for certain system error messages. |
| login-required | N | "true" | Is a logged in user (UserLogin object, or login.username and login.password Strings) required to run this method? "true" or "false". |
| use-transaction | N | "true" | Create a transaction if none exists for this thread? "true" or "false". |
| default-error-code | N | "error" | The default error return code. |
| default-success-code | N | "success" | The default success return code. |
| parameter-map-name | N | "parameters" | As event: copy of request parameters As service: incoming context |
| event-request-object-name | N | "request" | (as event only) |
| event-response-code-name | N | "_response_code_" | (as event only) |
| event-error-message-name | N | "_error_message_" | (as event only) |
| event-event-message-name | N | "_event_message_" | (as event only) |
| service-response-message-name | N | "responseMessage" | (as service only) |
| service-error-message-name | N | "errorMessage" | (as service only) |
| service-error-message-list-name | N | "errorMessageList" | (as service only) |
| service-success-message-name | N | "successMessage" | (as service only) |
| service-success-message-list-name | N | "successMessageList" | (as service only) |
| delegator-name | N | "delegator" | A GenericDelegator object to use in the method |
| security-name | N | "security" | A Security object to use in the method |
| dispatcher-name | N | "dispatcher" | A LocalDispatcher object to use in the method |
In strings and field names a special syntax is supported to flexibly access Map member, List elements and to insert environment values into string constants.
The ${} (dollar-sign-curly-brace) syntax can be used to insert an environment variable value in pretty much any string constant in a simple-method file. Not only can it be used to reference top-level envrionment variables, the syntax elements described below can be used to access values in sub-structures.
You can use the "." (dot) syntax to access Map
members. For example if you specify the attribute field-name="product.productName"
it will reference the productName member of the product
Map.
This would be the same as specifying map-name="product"
field-name="productName".
Note that this is, of course, more flexible than a field-name/map-name
combination because
the Map structure can be multiple levels deep. For example if you have
use the attribute
field-name="products.widget.productName" it will reference
the productName in
the widget Map which is in the products Map.
The "[]" (square-brace) syntax can be used to
access list elements.
For example you can specify the attribute field-name="products[0].productName"
and it will reference the productName of the first
(position zero) element in the products List. To make
this more useful you can pull a list index from the environment using
something like field-name="products[${currentIndex}].productName".
There are two extensions to the [] syntax that can be used when refering to an environment location that is the target of an operation. If you do not include a number between the square braces the value will be put at the end of the list. If you put a "+" (plus sign) in front of the number between the square braces (ie: [+2]) it will insert the value before that position in the list instead of replacing the value at that location. For example, specifying [+0] would insert the value at the beginning of the list.
In fact, you can use the ${} syntax to
substitute any string or other value at any location in a field-name or
other string constant. So, you could even reference
a Map member named in some other environment variable. For example you
could use field-name="products[${currentIndex}].${currentMember}"
to achieve this effect.
Okay, enough of the general stuff, here is a catalog and description of the available operations.
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 named out-map already exists. Resulting messages are added to the named 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 Name | Required? | Description |
| xml-resource | N | The full path and filename on the classpath of the XML file which contains an external map processor to execute. This is only required if an external map processor is desired. |
| processor-name | N | The name of the external map processor to execute in the specified xml-resource. This is only required if an external map processor is desired. |
| in-map-name | Y | The name of a map in the method environment to use as the input map. |
| out-map-name | Y | 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 already exists will be added to in place. |
| error-list-name | N | The name of a list in the method environment that the error messages will be added to. Will be created if it does not exist. Defaults to "error_list". |
| Sub-Element Name | How Many | Description |
| simple-map-processor | 0 or 1 | Uses the same definition as the simple-map-processor in the context of a simple-map-processors XML file. Allows for an inlined simple-map-processor. |
call-service
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.
| Attribute Name | Required? | Description |
| service-name | Y | |
| in-map-name | Y | |
| include-user-login | N | Defaults to "true". |
| error-code | N | Defaults to "error". |
| success-code | N | Defaults to "success". |
| Sub-Element Name | How Many | Description |
| error-prefix | 0 or 1 | |
| error-suffix | 0 or 1 | |
| success-prefix | 0 or 1 | |
| success-suffix | 0 or 1 | |
| message-prefix | 0 or 1 | |
| message-suffix | 0 or 1 | |
| default-message | 0 or 1 | |
| results-to-map | 0 to many | |
| result-to-field | 0 to many | |
| result-to-request | 0 to many | |
| result-to-session | 0 to many | |
| result-to-result | 0 to many |
call-service-asynch
Calls a service asynchronously and ignores the result, so no return messages are used; that doesn't mean no errors will result, but they would just be system errors like database failures, etc which all have system error messages.
| Attribute Name | Required? | Description |
| service-name | Y | |
| in-map-name | Y | |
| include-user-login | N | Defaults to "true". |
call-bsh
Runs an external bsh script from the classpath if 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 Name | Required? | Description |
| resource | N | |
| error-list-name | N | Defaults to "error_list". |
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 Name | Required? | Description |
| xml-resource | N | 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 | Y | 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. |
create-object
Creates an object of the given class and if the field-name is specified saves it in that field.
The string and field sub-elements are passed to the constructor method as arguments in the order they are specified. If the sub-elements do not match the constructor method arguments an error will be returned.
| Attribute Name | Required? | Description |
| class-name | Y | The name of the class to construct an object of. |
| field-name | N | The name of a field to put the new object in. If not specified the object will be created but ignored after that. |
| map-name | N | The name of the map the field will go in. If not specified the field will be put in the environment. |
| Sub-Element Name | How Many | Description |
| string | 0 to many | Used to specify an inline String argument to the constructor method. |
| field | 0 to many | Used to specify a field to be passed as an argument to the constructor method. The field can be in a map in the environment or if no map-name is specified then the field will come directly from the environment. |
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 an value is returned and if a field and optionally a map name are specified.
| Attribute Name | Required? | Description |
| obj-field-name | Y | The name of the field the object is in that has the method to be called. |
| obj-map-name | N | The name of the map the field of the object is in that has the method to be called. If this is not specified the environment will be used to find the field in. |
| method-name | Y | The name of the method to call on the given object. |
| ret-field-name | N | The name of the field to put the result in. If not specified any return value will be ignored. |
| ret-map-name | N | 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. |
| Sub-Element Name | How Many | Description |
| string | 0 to many | Used to specify an inline String argument to the method call. |
| field | 0 to many | Used to specify a field to be passed as an argument to the method call. The field can be in a map in the environment or if no map-name is specified then the field will come directly from the environment. |
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 an value is returned and if a field and optionally a map name are specified.
| Attribute Name | Required? | Description |
| class-name | Y | The name of the class to call the static method on. |
| method-name | Y | The name of the static method to call on the given class. |
| ret-field-name | N | The name of the field to put the result in. If not specified any return value will be ignored. |
| ret-map-name | N | 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. |
| Sub-Element Name | How Many | Description |
| string | 0 to many | Used to specify an inline String argument to the method call. |
| field | 0 to many | Used to specify a field to be passed as an argument to the method call. The field can be in a map in the environment or if no map-name is specified then the field will come directly from the environment. |
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 Name | Required? | Description |
| error-code | N | Defaults to "error". |
| error-list-name | N | The name of the list to in the method environment to check for error messages. Defaults to "error_list". |
| Sub-Element Name | How Many | Description |
| error-prefix | 0 or 1 | |
| error-suffix | 0 or 1 | |
| message-prefix | 0 or 1 | |
| message-suffix | 0 or 1 |
add-error
Adds an error message with to the given error list from either an inline message or a message from a properties file.
| Attribute Name | Required? | Description |
| error-list-name | N | The name of the list to in the method environment to check for error messages. Defaults to "error_list". |
| Sub-Element Name | How Many | Description |
| fail-message | 0 or 1 | Used to specify an inline message. Has one attribute called 'message'. |
| fail-property | 0 or 1 | Used to get the message from a properties file. Has two attributes: resource and property. |
return
Returns immediately from the simple-method with the given response code string.
| Attribute Name | Required? | Description |
| response-code | N | The string to return as a response code. Defaults to "success". |
field-to-request
The field-to-request tag copies a field from a map to the specified servlet request attribute.
The tag is only used when the simple-method is called as an event, it is ignored otherwise.
| Attribute Name | Required? | Description |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
| request-name | N | The name of the request attribute to use. Defaults to the field-name. |
field-to-session
The field-to-session tag copies a field from a map to the specified servlet session attribute.
The tag is only used when the simple-method is called as an event, it is ignored otherwise.
| Attribute Name | Required? | Description |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
| session-name | N | The name of the session attribute to use. Defaults to the field-name. |
request-to-field
The request-to-field tag copies an attribute from the servlet request to a field of a map in the method environment.
The tag is only used when the simple-method is called as an event, it is ignored otherwise (except the default value, if specified).
| Attribute Name | Required? | Description |
| map-name | N | The name of the map in the method environment. If not specified the field-name will be used to set the field in the method environment. |
| field-name | Y | The name (key) of the map field to use. |
| default | N | A default value to use if the request attribute is null or is a String and is empty. This will also be used when NOT running as an event. |
| request-name | N | The name of the request attribute to use. Defaults to the field-name. |
request-parameters-to-list
The request-parameters-to-list tag appends a request parameter values from the servlet request to the specified list.
The tag is only used when the simple-method is called as an event, it is ignored otherwise.
| Attribute Name | Required? | Description |
| request-name | Y | The name of the request parameter values to use. |
| list-name | N | The name of the list in the method environment that the request parameter values will be appended to. (default: request-name) |
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.
The tag is only used when the simple-method is called as an event, it is ignored otherwise (except the default value, if specified).
| Attribute Name | Required? | Description |
| map-name | N | The name of the map in the method environment. If not specified the field-name will be used to set the field in the method environment. |
| field-name | Y | The name (key) of the map field to use. |
| default | N | A default value to use if the session attribute is null or is a String and is empty. This will also be used when NOT running as an event. |
| session-name | N | The name of the session attribute to use. Defaults to the field-name. |
webapp-property-to-field
The webapp-property-to-field tag copies a property value from a properties file in a ServletContext resource to a field.
The tag is only used when the simple-method is called as an event, it is ignored otherwise (except the default value, if specified).
| Attribute Name | Required? | Description |
| resource | Y | The resource location of the properties file inside the webapp, and relative to the root of the webapp (can be inside a war file). An example of this is "/WEB-INF/myprops.properties". |
| property | Y | The property whose value will be put in the field. |
| default | N | A default value to use if the property value is null or empty. This will also be used when NOT running as an event. |
| map-name | N | The name of the map in the method environment. If not specified the field-name will be used to set the field in the method environment. |
| field-name | Y | The name (key) of the map field to use. |
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 Name | Required? | Description |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
| result-name | N | The name of the request attribute to use. Defaults to the field-name. |
map-to-map
The map-to-map tag copies all fields from one map to another map.
| Attribute Name | Required? | Description |
| map-name | Y | The name of the map in the method environment the fields will come from. |
| to-map-name | N | The name of the map in the method environment the fields will go to. If empty the fields will be copied to the environment. |
field-to-field
The field-to-field tag copies a field from a map to a field in another map.
| Attribute Name | Required? | Description |
| map-name | N | The name of the map in the method environment the field will come from. If this is null or empty it will default to the method environment itself. |
| field-name | Y | The name (key) of the map field to copy. |
| to-map-name | N | The name of the map in the method environment the field will go to. If empty will default to the map-name. Note that if no map-name was specified this will default to the method environment. So, you can copy from the environment to the environment or from the environment to a map, but to copy from a map to the environment you must use the field-to-env operation defined below. |
| to-field-name | N | The name (key) of the map field to put the original field in. If empty will default to the field-name. |
field-to-list
The field-to-list tag appends a field to the specified list.
| Attribute Name | Required? | Description |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
| list-name | Y | The name of the list in the method environment that the object will be appended to. |
env-to-field
The env-to-field tag copies a field from the method environment to a field in a map.
| Attribute Name | Required? | Description |
| env-name | Y | The name of the method environment field the object will come from. |
| map-name | N | The name of the map in the method environment the field will go to. If empty or not specified this will default to the method environment itself. |
| field-name | N | The name (key) of the map field to put the original field in. If empty will default to the env-name. |
field-to-env
The field-to-env tag copies a field from a map to a field in the method environment.
| Attribute Name | Required? | Description |
| field-name | Y | The name (key) of the map field to get the object from. |
| env-name | N | The name of the method environment field the object will be put in. If empty will default to the field-name. |
| map-name | N | The name of the map in the method environment the field will come from. If empty or not specified this will default to the method environment itself. |
string-to-field
The string-to-field tag puts the inlined string value in the specified field.
| Attribute Name | Required? | Description |
| string | Y | The string value to be put in the field. |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
| arg-list-name | N | The name (key) of a list to use for argument values for any place holders in the string. Formatting is done with the Java MessageFormat class. Place holders, for example, are denoted as follows: {0}, {1}, etc and can appear anywhere in the string. |
string-to-list
The string-to-list tag appends the inlined string value in the specified List.
| Attribute Name | Required? | Description |
| string | Y | The string value to append to the list. |
| list-name | Y | The name of the list in the method environment. |
| arg-list-name | N | The name (key) of a list to use for argument values for any place holders in the string. Formatting is done with the Java MessageFormat class. Place holders, for example, are denoted as follows: {0}, {1}, etc and can appear anywhere in the string. |
to-string
The to-string tag converts the Object in the specified field to a String, putting the string in the same field.
| Attribute Name | Required? | Description |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
clear-field
The clear-field tag clears/removes the specified field.
| Attribute Name | Required? | Description |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
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.
| Attribute Name | Required? | Description |
| entry-name | Y | The name of the method environment field that will contain each entry as we iterate through the list. |
| list-name | Y | The name of the method environment field that contains the list to iterate over. |
| Sub-Element Name | How Many | Description |
| Any Operation | 0 to many | Any simple-method operation can be nested under the iterate tag. |
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 Name | Required? | Description |
| entry-name | Y | The name of the method environment field that will contain the first entry in the list. |
| list-name | Y | The name of the method environment field that contains the list to get the first entry from. |
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.
| Attribute Name | Required? | Description |
| env-name | Y | The name of the method environment field the timestamp will be put in. |
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.
| Attribute Name | Required? | Description |
| env-name | Y | The name of the method environment field the date will be put in. |
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 Name | Required? | Description |
| sequence-name | Y | 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 | Y | The name of the method environment field the sequenced ID will be put in. |
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, etc.
| Attribute Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the UserLogin GenericValue object. |
find-by-primary-key
The find-by-primary-key tag uses the delegator to find an entity value by its primary key. The resulting GenericValue object will be placed in the method environment using the specified value-name.
| Attribute Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the GenericValue object. |
| entity-name | Y | The name of the entity to find an instance of. |
| map-name | Y | The name of a map in the method environment that will be used for the entity fields. |
| delegator-name | N | By default this operation is done using the delegator that is part of the simple-method calling context. This allows you to override the default delegator by naming an alternate delegator. |
| use-cache | N | 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. Must be "true" or "false", defaults to "false". |
find-by-and
The find-by-and tag uses the delegator to find entity values by anding the fields passed in the map. The resulting GenericValue objects will be placed in the method environment using the specified list-name.
| Attribute Name | Required? | Description |
| list-name | Y | The name of the method environment field that contains the list of GenericValue objects. |
| entity-name | Y | The name of the entity to find instances of. |
| map-name | Y | The name of a map in the method environment that will be used for the entity fields. |
| order-by-list-name | Y | The name of a list in the method environment that contains a list of strings specifying fields to order the results by. |
| delegator-name | N | By default this operation is done using the delegator that is part of the simple-method calling context. This allows you to override the default delegator by naming an alternate delegator. |
| use-cache | N | 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. Must be "true" or "false", defaults to "false". |
| use-iterator | N | Specifies whether or not to use the EntityListIterator when
doing the query. This is much more efficient for large data sets
because the results are read incrementaly instead of all at once. Note
that when using this the use-cache setting will be ignored. Also note
that an EntityListIterator must be closed when you are finished, but
this is done automatically by the iterate operation. Must
be "true" or "false", defaults to "false". |
filter-list-by-and
The filter-list-by-and tag filters the given list by the fields in the specified map.
| Attribute Name | Required? | Description |
| list-name | Y | The name of the method environment field that contains the list of GenericValue objects. |
| to-list-name | N | The name of the method environment field the filtered list will be put into. Defaults to the value of the list-name attribute (ie goes to the same place it came from, replacing the old list). |
| map-name | N | 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. |
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 Name | Required? | Description |
| list-name | Y | The name of the method environment field that contains the list of GenericValue objects. |
| to-list-name | N | The name of the method environment field the filtered list will be put into. Defaults to the value of the list-name attribute (ie goes to the same place it came from, replacing the old list). |
| valid-date-name | N | The name of a field in the method environment date to filter by. Defaults to now. |
| from-field-name | N | The name of the GenericValue field to use as the beginning effective date. Defaults to fromDate. |
| thru-field-name | N | The name of the GenericValue field to use as the ending effective date. Defaults to thruDate. |
| all-same | N | Specifies whether or not all GenericValue objects in the list are of the same entity. Defaults to true. |
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 Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the GenericValue object. |
| entity-name | Y | The name of the entity to construct an instance of. |
| map-name | N | The name of a map in the method environment that will be used for the entity fields. |
clone-value
The clone-value tag make 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 Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the GenericValue object. |
| new-value-name | Y | The name of the method environment field that will contain the new GenericValue object. |
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 Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the GenericValue object. |
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 Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the GenericValue object. |
remove-value
The remove-value tag removes the specified GenericValue object by removing 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 Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the GenericValue object. |
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 Name | Required? | Description |
| entity-name | Y | The name of the entity to remove instances of. |
| map-name | Y | The name of a map in the method environment that will be used for the entity fields. |
clear-cache-line
Uses the delegator to clear elements from the cache; intelligently looks at the map passed to see if it is a byPrimaryKey, and byAnd, or an all.
| Attribute Name | Required? | Description |
| entity-name | Y | The name of the entity to clear cache lines of. |
| map-name | Y | The name of a map in the method environment that will be used for the entity fields. If the fields in the map form the full primary key the entry will be removed from the byPrimaryKey cache. If the map exists but the fields do not include a full primary key the entry will be removed from the byAnd cache. If no map-name is specified the entry will be removed from the all cache. |
clear-entity-caches
This is a very simple tag that should be used sparingly because of the performance impact. It clears all lines from all Entity Engine caches. It has no attributes or sub-elements.
set-pk-fields
Looks for each PK field in the named map and if it exists there it will copy it into the named value object.
| Attribute Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the GenericValue object. |
| map-name | Y | The name of a map in the method environment that will be used for the entity fields. |
| set-if-null | N | Specifies whether or not to set fields that are null or empty. Defaults to true. |
set-nonpk-fields
Looks for each non-PK field in the named map and if it exists there it will copy it into the named value object.
| Attribute Name | Required? | Description |
| value-name | Y | The name of the method environment field that contains the GenericValue object. |
| map-name | Y | The name of a map in the method environment that will be used for the entity fields. |
| set-if-null | N | Specifies whether or not to set fields that are null or empty. Defaults to true. |
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 in that values in the list will be inserted if it does not exist or updated if it does exist.
| Attribute Name | Required? | Description |
| list-name | Y | The name of the method environment field that contains the list of GenericValue objects. |
remove-list
The remove-list tag uses the delegator to remove all entity values in the list. For each value in the list if it is a primary key just that entity instance will be removed, but if it is not a full primary key all entity instances will be removed from the datasource that match the constraint of the field map.
| Attribute Name | Required? | Description |
| list-name | Y | The name of the method environment field that contains the list of GenericValue objects. |
transaction-begin
The transaction-begin tag will begin a transaction if one is not already in place. If a transaction is begun the environment field named as the began-transaction-name will be set to true, otherwise it will be set to false.
Note that unless the simple-method is flagged to not use a transaction all simple-methods will be inside a transaction. The same is true for service calls through the Service Engine.
| Attribute Name | Required? | Description |
| began-transaction-name | N | The name of the method environment field that contains a Boolean specifying whether or not a transaction was begun in the current transaction demarcation. Defaults to "beganTransaction". |
transaction-commit
The transaction-commit tag will commit a transaction if a transaction was begun in the current demarcation context as represented by the environment field named as the began-transaction-name. If the Boolean in that field is false no commit will be done.
| Attribute Name | Required? | Description |
| began-transaction-name | N | The name of the method environment field that contains a Boolean specifying whether or not a transaction was begun in the current transaction demarcation. Defaults to "beganTransaction". |
transaction-rollback
The transaction-rollback tag will rollback a transaction if a transaction was begun in the current demarcation context as represented by the environment field named as the began-transaction-name. If the Boolean in that field is false a set rollback only will operation will be done instead of rollback which will force the transaction to rollback regardless of which method or object is responsible for beginning and ending the transaction.
| Attribute Name | Required? | Description |
| began-transaction-name | N | The name of the method environment field that contains a Boolean specifying whether or not a transaction was begun in the current transaction demarcation. Defaults to "beganTransaction". |
if
The if operation offers a flexible
way of specifying combinations
of conditions, alternate conditions, and operations to run on true
evaluation of the conditions or to
run otherwise.
The other if operations are meant for a
specific, simple condition when used outside of the condition
sub-element of this operation. The attributes of the other if
operations are the same when used
inside this operation. In this case they are empty tags and do not have
any sub-elements because the operations
to run are under the then or else tags.
| Sub-Element Name | How Many | Description |
| condition | 1 | A simple element with no attributes that contains the
condition that will be evaluated to determine which sub-operations to
execute. To combine the other if operations documented below the and,
or, xor, and not
elements
can be used. The and, or, and xor elements can contain as many general
if operations and modifier/combination elements (ie and, or, xor, and
not). |
| then | 1 | The then element is used to contain operations that will run if the condition evaluate to true. A then tag must be included, but can be empty. |
| else-if | 0 to many | The else-if element can be used to specify alternate
conditional execution blocks. Each else-if element must contain two
sub-elements: condition and then. These
operations are used the same as the condition and then elements
describes above. If the condition of the parent if element is evaluated
to false, each condition of the else-if sub-elements will be evaluated,
and the operations under the then element corresponding first condition
that evaluates to true will be run. |
| else | 0 or 1 | The else element can be used to contain operations that will
run if the condition evaluates to false, and if no else-if
sub-conditions evaluate to true. It can contain any simple-method
operation. The else tag must be placed as the last tag under the if tag. |
if-validate-method
The operations contained by the if-validate-method tag will only be executed if the validate method returns true. This tag can contain any of the simple-method operations, including the conditional/if operations.
| Attribute Name | Required? | Description |
| map-name | N | 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). |
| field-name | Y | The name of the map field that will be validated. |
| method | Y | 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 return a boolean. |
| class | N | The name of the class that contains the validation method. If not specified defaults to "org.ofbiz.base.util.UtilValidate". |
| Sub-Element Name | How Many | Description |
| Any Operation | 0 to many | Any simple-method operation can be nested under an if-* tag. |
| else | 0 or 1 | The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag. |
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 Name | Required? | Description |
| map-name | N | 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). |
| field-name | Y | The name of the map field that will be compared. |
| operator | Y | Specified the comparison operator must be one of the following: less, greater, less-equals, greater-equals, equals, not-equals, or contains. |
| value | Y | The value that the field will compared to. Must be a String, but can be converted to other types. |
| type | N | The data type to use for the comparison. Must be one of the following: String, Double, Float, Long, Integer, Date, Time, or Timestamp. If no type is specified the default will be String. |
| format | N | A format specifier to use when converting String objects to other data types, mainly Date, Time and Timestamp. |
| Sub-Element Name | How Many | Description |
| Any Operation | 0 to many | Any simple-method operation can be nested under an if-* tag. |
| else | 0 or 1 | The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag. |
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 Name | Required? | Description |
| map-name | N | 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). |
| field-name | Y | The name of the map field that will be compared. |
| operator | Y | Specified the comparison operator must be one of the following: less, greater, less-equals, greater-equals, equals, not-equals, or contains. |
| to-map-name | N | 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. |
| to-field-name | N | The name of the to-map field that the main field will be compared to. If left empty will default to the field-name. |
| type | N | The data type to use for the comparison. Must be one of the following: String, Double, Float, Long, Integer, Date, Time, or Timestamp. If no type is specified the default will be String. |
| format | N | A format specifier to use when converting String objects to other data types, mainly Date, Time and Timestamp. |
| Sub-Element Name | How Many | Description |
| Any Operation | 0 to many | Any simple-method operation can be nested under an if-* tag. |
| else | 0 or 1 | The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag. |
if-regexp
The operations contained by the if-regexp tag will only be executed if the value complies with the regular expression. This tag can contain any of the simple-method operations, including the conditional/if operations.
| Attribute Name | Required? | Description |
| map-name | N | 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). |
| field-name | Y | The name of the map field that will be compared. |
| expr | Y | A regular expression that the map value must comply with. |
| Sub-Element Name | How Many | Description |
| Any Operation | 0 to many | Any simple-method operation can be nested under an if-* tag. |
| else | 0 or 1 | The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag. |
if-empty
The operations contained by the if-empty tag will only be executed if the map field is empty. This tag can contain any of the simple-method operations, including the conditional/if operations.
| Attribute Name | Required? | Description |
| map-name | N | 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). |
| field-name | Y | The name of the map field that will be compared. |
| Sub-Element Name | How Many | Description |
| Any Operation | 0 to many | Any simple-method operation can be nested under an if-* tag. |
| else | 0 or 1 | The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag. |
if-not-empty
The operations contained by the if-not-empty tag will only be executed if the map field is not empty. This tag can contain any of the simple-method operations, including the conditional/if operations.
| Attribute Name | Required? | Description |
| map-name | N | 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). |
| field-name | Y | The name of the map field that will be compared. |
| Sub-Element Name | How Many | Description |
| Any Operation | 0 to many | Any simple-method operation can be nested under an if-* tag. |
| else | 0 or 1 | The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag. |
if-has-permission
The operations contained by the if-has-permission tag will only be executed if the user has the specified permission, and optionally the action. This tag can contain any of the simple-method operations, including the conditional/if operations.
| Attribute Name | Required? | Description |
| permission | Y | The name of the permission in the database. The user must belong to a security group that has this permission. |
| action | N | If an action is specified the user can have one of two permissions: the permission + "_ADMIN" or permission + action. Examples of actions include "_CREATE", "_VIEW", etc. |
| Sub-Element Name | How Many | Description |
| Any Operation | 0 to many | Any simple-method operation can be nested under an if-* tag. |
| else | 0 or 1 | The else tag can be used to contain operations that will run if the condition fails, or in other words if the operations under the if tag do not run. It can contain any simple-method operation. The else tag must be placed as the last tag under the if-* tag. |
check-permission
The check-permission tag checks to see if the current user has the specified permission. The the user does not have the specified permission or there is no user associated with the context then the failure message from fail-message or file-property will be added to the specified error list.
| Attribute Name | Required? | Description |
| permission | Y | The name of the permission in the database. The user must belong to a security group that has this permission. |
| action | N | If an action is specified the user can have one of two permissions: the permission + "_ADMIN" or permission + action. Examples of actions include "_CREATE", "_VIEW", etc. |
| error-list-name | N | The name of a list in the method environment that the error messages will be added to. Will be created if does not exist. Defaults to "error_list". |
| Sub-Element Name | How Many | Description |
| alt-permission | 0 to many | Allows you to specify alternate permissions, any of which
will satisfy this check permission. If the current userLogin does not
have any of these permissions the error will be added to the list. Has
two attributes: permission and action that
behave just as the corresponding attributes described above for the
check-permission element. |
| fail-message | one | An inline failure message. |
| fail-property | one | A failure message from a properties file. |
check-id
The check-id tag checks to see if the ID value in the given field is a valid ID string. Valid IDs can be any sequence of characters or digits but must not containt the following characters: space [ ], doublequote ["], single quote ['], ampersand [&], question mark [?], less-than sign [<], greater-than sign [>].
| Attribute Name | Required? | Description |
| field-name | Y | The name of the field that contains the ID value to check. |
| map-name | N | The name of the Map that contains the field. If not specified the environment will be used to find the field. |
| error-list-name | N | The name of a list in the method environment that the error messages will be added to. Will be created if does not exist. Defaults to "error_list". |
| Sub-Element Name | How Many | Description |
| fail-message | one | An inline failure message. |
| fail-property | one | A failure message from a properties file. |
property-to-field
The property-to-field tag puts the inlined string value in the specified field.
| Attribute Name | Required? | Description |
| resource | Y | The resource location of the properties file. |
| property | Y | The property whose value will be put in the field. |
| default | N | The default value to use if the specified property is empty. |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
log
The log tag logs a message used 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.
| Attribute Name | Required? | Description |
| level | Y | The logging/debug level to use. Must be one of the following: verbose | timing | info | important | warning | error | fatal | always. These are the standard OFBiz logging levels. |
| message | N | A shortcut for simple messages. If used along with field and/or string sub-elements the inline string in the message will come first. |
| Sub-Element Name | How Many | Description |
| field | 0 to many | Inserts the value of the field into the message where specified. |
| string | 0 to many | Inserts the value of the inline string into the message where specified. |
calculate
The calculate tag performs the specified calculation and puts the result in an object in the field of the specified map (see the calculate element attribute descriptions above). The type of the object can be specified with the type attribute, but 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.
Each calcop tag has three attributes: operator, map-name and field-name. Only the operator is required. 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.
Regardless of the operator the action is very
similar. It translates to a
formula like the following: (V1 [operator] V2 [operator] V3).
In other
words a final result is calculated by applying the operator to the
values in the
order they are specified. If a field-name (and optionally map-name) is
specifies
on the calcop tag that field will be used as the first value, otherwise
the
first nested calcop or number will be the first value.
The get operator is just an alias for add. It adds all of the values under it. Likewise the negative operator is almost an alias for subtract, with the exception that the first value is negated instead of left positive. For convenience the calculate tag itself acts like an add, in other words the calcops and numbers under it are all added together.
| Attribute Name | Required? | Description |
| map-name | N | 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 | Y | The name (key) of the map field to use. |
| type | N | The object type to put into this field. Can be: Double | Float | Long | Integer. The default is Double. |
| Sub-Element Name | How Many | Description |
| calcop | 0 to many | This tag is used to apply an operator in the calculation. It can have calcop and number tags nested under it, making it also act like a parenthesis. It has three attributes: operator, map-name, and field-name. These are described below. |
| number | 0 to many | This is used to put a numeric constant (a number) into the calculation. It has one attribute: value. This must be a properly formatted number or an error will result. |
Here is an example of an XML snippet that
performs the calculation
a=b+(((c+x+2)*-d)/e), or in Reverse Polish Notation
(a little
bit closer to the resulting XML, and the notation used in the Rule
Engine)
a=+(b,/(*(+(c,x,2),-d),e)). Here is the XML:
<calculate field-name="a">
<calcop operator="get" field-name="b"/>
<calcop operator="divide">
<calcop operator="multiply">
<calcop operator="add" field-name="c">
<calcop operator="get" field-name="x"/>
<number value="2"/>
</calcop>
<calcop operator="negative" field-name="d"/>
</calcop>
<calcop operator="get" field-name="e"/>
</calcop>
</calculate>
<!DOCTYPE simple-methods PUBLIC "-//OFBiz//DTD Simple Methods//EN" "http://www.ofbiz.org/dtds/simple-methods.dtd">
<simple-methods>
<simple-method method-name="createProduct" short-description="Create an Product">
<check-permission permission="CATALOG" action="_CREATE"><fail-message message="Security Error: to run createProduct you must have the CATALOG_CREATE or CATALOG_ADMIN permission"/></check-permission>
<check-id field-name="productId" map-name="parameters"/>
<check-errors/>
<make-value value-name="newEntity" entity-name="Product"/>
<set-nonpk-fields map-name="parameters" value-name="newEntity"/>
<set-pk-fields map-name="parameters" value-name="newEntity"/>
<now-timestamp-to-env env-name="nowTimestamp"/>
<env-to-field env-name="nowTimestamp" field-name="lastModifiedDate" map-name="newEntity"/>
<env-to-field env-name="nowTimestamp" field-name="createdDate" map-name="newEntity"/>
<field-to-field field-name="userLoginId" map-name="userLogin" to-field-name="lastModifiedByUserLogin" to-map-name="newEntity"/>
<field-to-field field-name="userLoginId" map-name="userLogin" to-field-name="createdByUserLogin" to-map-name="newEntity"/>
<create-value value-name="newEntity"/>
<!-- induce keywords if autoCreateKeywords is emtpy or Y-->
<if-empty field-name="autoCreateKeywords" map-name="newEntity">
<call-bsh><![CDATA[org.ofbiz.commonapp.product.product.KeywordSearch.induceKeywords(newEntity);]]></call-bsh>
<else>
<if-compare field-name="autoCreateKeywords" map-name="newEntity" operator="equals" value="Y">
<call-bsh><![CDATA[org.ofbiz.commonapp.product.product.KeywordSearch.induceKeywords(newEntity);]]></call-bsh>
</if-compare>
</else>
</if-empty>
</simple-method>
<simple-method event-name="create" short-description="Create Work Effort">
<call-map-processor xml-resource="org/ofbiz/commonapp/workeffort/workeffort/WorkEffortMapProcessors.xml"
processor-name="update" in-map-name="parameters" out-map-name="context"/>
<check-errors/>
<call-service service-name="createWorkEffort" in-map-name="context">
<default-message>Work Effort successfully created.</default-message>
<result-to-request result-name="workEffortId"/></service>
</simple-method>
<simple-method event-name="update" short-description="Update Work Effort">
<call-map-processor xml-resource="org/ofbiz/commonapp/workeffort/workeffort/WorkEffortMapProcessors.xml"
processor-name="update" in-map-name="parameters" out-map-name="context"/>
<check-errors/>
<call-service service-name="updateWorkEffort" in-map-name="context">
<default-message>Work Effort successfully updated.</default-message></service>
</simple-method>
</simple-methods>