The Open For Business Project

The Open For Business Project: Mini-Language Guide

Generated from simple-method.xsd with simple-method.xsl files


CallOperations

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
 Name of a properties file on the classpath.
error-list-name
N
 The name of the list in the method environment to check for error messages. Defaults to "error_list".

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.

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
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.
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.
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 to 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-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.
method-name
Y
 The name of the method to call on the given object.
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.
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.

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
 Name of the service to call.
in-map-name
N
 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 than you can just leave off the in-map name, although typically in a service tag you will see a service-name and the in-mapname passed in.
include-user-login
N
 Include-user-login 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. Defaults to "true".
break-on-error
N
 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 you can just set that to false. Defaults to "true".
error-code
N
 Defaults to "error".
success-code
N
 Defaults to "success".
require-new-transaction
N
 Defines if the simple-method requires a new transaction or not. Defaults to "false".
transaction-timeout
N
 Defines the time out for the transaction, in milliseconds. None by defaults.

Sub Element Name How Many Description
error-prefix 0 to 1
error-suffix 0 to 1
success-prefix 0 to 1
success-suffix 0 to 1
message-prefix 0 to 1
message-suffix 0 to 1
default-message 0 to 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
 Name of the service called asynchronously.
in-map-name
N
 The name of a map in the method environment to use as the input map.
include-user-login
N
 Defaults to "true".

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
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.
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.

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.

set-service-fields

 Take all the incoming files for this service, or all the incoming service attributes, and look for fields with the same name in the incoming map and copy those onto the outgoing map.

Attribute Name Required Description
service-name
Y
 Name of the service from which take all the incoming files, or all incoming attributes.
map-name
Y
 Incoming map to copy fields from.
to-map-name
Y
 Map to copy to fields to.


ControlOperations

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 in the method environment to check for error messages. Defaults to "error_list".

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 in the method environment to check for error messages. Defaults to "error_list".

Sub Element Name How Many Description
error-prefix 0 to 1
error-suffix 0 to 1
message-prefix 0 to 1
message-suffix 0 to 1

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 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.

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 Name Required Description
key-name
Y
 Name of the variable to put the key.
value-name
Y
 Name of the variable to put the value in.
map-name
Y
 Name of the map to use.

loop

 Loop, rather than iterating over some sort of a structure, will simply loop a certain number of times. The number of times to loop is specified in the count attribute, and it will put the current count in the field attribute, or in the variable named by the field attribute. So if you want to loop ten times you say count=ten, and field=count for example. First time through count will be zero; last time through count will be nine.

Attribute Name Required Description
count
Y
 Number of times to loop.
field
N
 Current count is put in the field attribute.

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".


EntityFindOperations

entity-and

 Does a find-by-and, returns a list of Generic values if any are found, otherwise returns 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 you can go forward.

Attribute Name Required Description
entity-name
Y
 Name of entity to search in.
list-name
Y
 Name of the list where to put results.
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".
filter-by-date
N
 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. Defaults to false.

Sub Element Name How Many Description
field-map 1 to many
select-field 0 to many Specify fields to select, otherwise all fields will be selected.
order-by 0 to many Defines fields to order list by.
limit-range 0 to 1
limit-view 0 to 1
use-iterator 0 to 1

entity-condition

 Like entity-and returns a list of Generic values if any are found, otherwise returns null. Uses any of condition-expression, condition-list and condition-object.

Attribute Name Required Description
entity-name
Y
 Name of entity to search in.
list-name
Y
 Name of the list where to put results.
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".
filter-by-date
N
 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. Defaults to false.
distinct
N
 Filter the results making sure that all of them are unique. Defaults to false.
delegator-name
N
 Name of a delegator to use. By default uses the delegator associated with that instance of the service engine.

Sub Element Name How Many Description
condition-expr 0 to 1
condition-list 0 to 1
condition-object 0 to 1
having-condition-list 0 to 1
select-field 0 to many Specify fields to select, otherwise all fields will be selected.
order-by 0 to many
limit-range 0 to 1
limit-view 0 to 1
use-iterator 0 to 1

entity-count

 The entity-count is very similar to the entity-condition. Specify the entity-name, optionally the delgator-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 have-in-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.

Attribute Name Required Description
entity-name
Y
 Name of entity to search in.
count-name
Y
 Name of the variable to put result of the count in.
delegator-name
N
 Name of a delegator to use. By default uses the delegator associated with that instance of the service engine.

Sub Element Name How Many Description
condition-expr 1 to 1
condition-list 1 to 1
condition-object 1 to 1
having-condition-list 0 to 1

entity-one

 Does a find-by-primarykey, always returns a single generic value object if it's found, otherwise returns null.

Attribute Name Required Description
entity-name
Y
 Name of the entity to look for.
value-name
Y
 Name of the variable to put entity in.
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".
auto-field-map
N
 Looks for all primary key field names in the current context as well as in the parameters map or not. Defaults to true.

Sub Element Name How Many Description
field-map 0 to many Specify where to find primary key fields if you set auto-field-map to false.
select-field 0 to many Specify fields to select, otherwise all fields will be selected.

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.

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
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.
list-name
Y
 The name of the method environment field that contains the list of GenericValue objects.
order-by-list-name
N
 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.
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".

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
map-name
Y
 The name of a map in the method environment that will be used for the entity fields.
value-name
Y
 The name of the method environment field that contains the GenericValue object.
entity-name
N
 The name of the entity to find an instance of.
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".
fields-to-select-list
N
 List containing name of fields to select, if empty defaults to all 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.

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. You start with the the value object, specify the name of the relationship. You can specify the name of a map that will restrain the query further, beyond the field mappings and their relationship. You can also specify how you want to order it. Use-cache true or false, list-name for the output.

Attribute Name Required Description
value-name
Y
 Name of a generic value sitting in the context from where you want to get a related generic value.
relation-name
Y
 Name of the relation to use to relate generic value in value-name to generic value in to-value.
list-name
Y
 Name of a list where to put the result in.
map-name
N
 Name of a map that will restrain the query further, beyond the field mappings and their relationship.
order-by-list-name
N
 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.
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".

get-related-one

 If you have a generic value object sitting in the context and you want to get a related entity following one of the type one relationships in the data model, then you can specify the name of the value here, the relation-name, the name of the relationship between the two entities, and the to-value where it should put the result, and you can tell it to use-cache or not, by default it doesn't.

Attribute Name Required Description
value-name
Y
 Name of a generic value sitting in the context from where you want to get a related-one generic value.
relation-name
Y
 Name of the one-relation to use to relate generic value in value-name to generic value in to-value.
to-value-name
Y
 Name of a generic value where to put the result.
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".

order-value-list

 Order-value-list does not actually do anything with the database. It takes an exiting list that has been returned and sorts it.

Attribute Name Required Description
list-name
Y
 Name of the list of generic value objects that we want to sort.
order-by-list-name
Y
 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
N
 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.


EntityListOperations

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.
do-cache-clear
N
 Clear the cache, 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.
do-cache-clear
N
 Clear the cache, defaults to true


EntityMiscOperations

entity-data

 Specify the location of an XML file that should be in the same format as any of the entity engine XML files, or the entity engine transformed XML files. And what this will do is either load or assert that file depending on the mode. If it finds the record but any of the fields are different, this is in the assert mode still, it will report any field that's different in a message on the error list. So that's basically what you can in essence assert, that a certain set of data exists in the database.

Attribute Name Required Description
location
Y
 Specify the location of an XML file to load in database or verify in assert mode.
delegator-name
N
 Overrides the delegator or default context by specifying a delegator-name.
timeout
N
 Override the timeout to start a new transaction and load the data with a longer timeout.
error-list-name
N
 The name of the list in the method environment to check for error messages. Defaults to "error_list".
mode
N
 "load" or "assert". Default to "load".

make-next-seq-id

 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 Name Required Description
value-name
Y
 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 of many different sets of sequences for the same entity is 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
Y
 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
N
 Since these are eventually strings we do numeric-padding so that the sort is consistent, By default we pad it with five positions.
increment-by
N
 Default to 1. If you want to leave some space in the sub-sequence you can use a greater increment.

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.
get-long-only
N
 Get a numerical long value and put it there, so it does not do that by default. By default getlong-only is false. If you want it to just get a long number then you can set that to true. That's in there for supporting lower level functionality, but that's not the typical pattern used in OFBiz as we do use strings for sequencing.
stagger-max
N
 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.


EntityTxOperations

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".


EntityValueOperations

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
N
 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.

Attribute Name Required Description

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.
do-cache-clear
N
 Clear the cache, 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.

refresh-value

 Refresh from database the value given in value-name.

Attribute Name Required Description
value-name
Y
 Name of the value to refresh from database.
do-cache-clear
N
 Clear the cache, defaults to true.

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.
do-cache-clear
N
 Clear the cache, defaults to true

remove-related

 Given a value name and a relationship name, follows the relationship and remove 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 you have a product-type entity and you 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 you're doing something like removing an order or removing a product, and you want to remove all related elements before removing the product to resolve foreign key issues. Usually the best practice for that, for removing a product for example, 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-relateds.

Attribute Name Required Description
value-name
Y
 Name of a generic value to remove all related records.
relation-name
Y
 Name of a relation to use to remove related records.
do-cache-clear
N
 Clear the cache, defaults to true

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.
do-cache-clear
N
 Clear the cache, 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
N
 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-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
N
 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-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.
do-cache-clear
N
 Clear the cache, defaults to true


EnvOperations

clear-field

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

Attribute Name Required Description
field-name
Y
 The name (key) of the map field to use.
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-to-list

 The field-to-list tag appends a field to the specified list.

Attribute Name Required Description
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.
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.

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.

list-to-list

 Copy a list to another list.

Attribute Name Required Description
list-name
Y
 Name of the list to copy from
to-list-name
Y
 Name of the list to copy to.

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.

order-map-list

 Sort a list : ordered by fields names given in order-by attribute.

Attribute Name Required Description
list-name
Y
 Name of the list ordered by fields names given in order-by attribute.

Sub Element Name How Many Description
order-by 1 to many

set

 Move a value from one field to another field. You 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. You 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 you 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 Name Required Description
field
Y
 Name of the field to copy value to.
from-field
N
 Name of the field to copy value from.
value
N
 Simple value to copy in field.
default-value
N
 Default value to copy in field if value evaluates to an empty string or the from field is null or empty.
type
N
 Type to convert to.
set-if-null
N
 Specifies whether or not to set fields that are null or empty. Defaults to true.
set-if-empty
N
 If the source value, either from a value or from a field, is empty, and empty-string an empty list or a null value. In this case it's set to true. If you don't want to set, if you want it to leave the target field alone when the source is empty, then you need to set this to false.

string-append

 NOTE: the prefix and suffix will only be used IFF the current string and the string to be appended are both not empty. So if the field does not exist then it will create a new field with this string value. If it does exist then it will append this string value to the end.

Attribute Name Required Description
field-name
Y
 The field that you want string-append to operate on. This is the target field where the value will be put, and this is the string to append to that field. So if the field does not exist then it will create a new field with this string value. If it does exist then it will append this string value to the end.
string
Y
 The string to append to the field named in field-name.
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.
arg-list-name
N
 arg-list-name is used to insert values from a list into the string using the object in the standard Java library that does this sort of string expresison with a { } brackets and a number, no dollar sign. This pattern of the arg-list-name with the prefix and suffix is something form the early days which is still supported, but the best thing to do here is just use the flexible string expander which is far more flexible and powerful. So you can have the prefix variables to expand and everything all mixed into one string.
prefix
N
 Used in conjunction with arg-list-name. String that will be prepended to the string,
suffix
N
 Used in conjunction with arg-list-name. String that will be appended to the string,

string-to-list

 Take a string literally that can also have a flexible string expander and such in it, and it will add it to a list. Note that you can have an arg-listname for using the standard Java style argument list where you have in the source string numbers inside of { } brackets that represent the number the index in the argument list to insert at that point.

Attribute Name Required Description
string
Y
 String to add to the list named in list-name.
list-name
Y
 List to add string to.
arg-list-name
N
 arg-list-name is used to insert values from a list into the string using the object in the standard Java library that does this sort of string expresison with a { } brackets and a number, no dollar sign. This pattern of the arg-list-name with the prefix and suffix is something form the early days which is still supported, but the best thing to do here is just use the flexible string expander which is far more flexible and powerful. So you can have the prefix variables to expand and everything all mixed into one string.
message-field-name
N
 To insert a message above a field (used in conjunction with @fieldErrors FTL macro)

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
field-name
Y
 The name (key) of the map field to use.
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.
format
N
 Format based on the type of the object (date,number, etc.).
numeric-padding
N
 Padding to use if a numeric object is used.


EventOperations

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
field-name
Y
 The name (key) of the map field to use.
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.
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
field-name
Y
 The name (key) of the map field to use.
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.
session-name
N
 The name of the session 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)

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
field-name
Y
 The name (key) of the map field to use.
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.
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.

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
field-name
Y
 The name (key) of the map field to use.
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.
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.
field-name
Y
 The name (key) of the field to use.
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.
session-name
N
 The name of the session attribute to use. Defaults to the field-name.


IfBasicOperations

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
field-name
Y
 The name of the map field that will be compared.
value
Y
 The value that the field will compared to. Must be a String, but can be converted to other types.
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).
format
N
 Format based on the type of the object (date,number, etc.).

Sub Element Name How Many Description
else 0 to 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
field-name
Y
 The name of the map field that will be compared.
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).
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.
format
N
 Format based on the type of the object (date,number, etc.).

Sub Element Name How Many Description
else 0 to 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
field-name
Y
 The name of the map field that will be compared.
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).

Sub Element Name How Many Description
else 0 to 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
else 0 to 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-instance-of

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

Attribute Name Required Description
field-name
Y
 The name of the map field that will be validated as being an instance of the named class.
class
Y
 The name of the class that named instance in field-name is supposed to belong.
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).

Sub Element Name How Many Description
else 0 to 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
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.
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).

Sub Element Name How Many Description
else 0 to 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-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 Name Required Description
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.
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).
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
else 0 to 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.


IfOtherOperations

assert

 Each condition under the assert element will be checked and if it fails an error will be added to the given error list. Note that while the definitions for the if-* operations are used, the tags should be empty because of the differing semantics. This is mainly used for testing, and for writing simple-methods that are meant to be used as part of a test suite. This is mostly useful for testing because the messages are targeted at a programmer, and not really at an end user.

Attribute Name Required Description
title
N
 Each assert operation have a title that can be used in the report for the testing. These can be used in the normal code.
error-list-name
N
 The name of the list in the method environment to check for error messages. Defaults to "error_list".

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".

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
accept-userlogin-party 0 to 1
alt-permission 0 to many
fail-message 1 to 1
fail-property 1 to 1

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. Note that while the definitions for the if-* operations are used, the tags should be empty because of the differing semantics.

Attribute Name Required Description

Sub Element Name How Many Description
condition 1 to 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 notelements 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 to 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 to 1 The else element can be used to contain operations that will run if the condition evaluates to false, and if no else-ifsub-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-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
field-name
Y
 The name of the map field that will be compared.
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).

Sub Element Name How Many Description
else 0 to 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.

while

 While loop operation, uses the same condition element as the if operation.

Attribute Name Required Description

Sub Element Name How Many Description
condition 1 to 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 notelements 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 to 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.


OtherOperations

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). The type of the object can be specified with the type attribute, 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 Name Required Description
field-name
Y
 The name (key) of the map (or env if map-name is empty) field to use.
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.
type
N
rounding-mode
N
 Rounding mode for BigDecimal calculation, primarily for divide operation.
decimal-scale
N
 Initial scale to use for the internal BigDecimal. Defaults to 2 for monetary calculations.
decimal-format
N

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.

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.

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.

property-to-field

 The property-to-field tag puts the inlined string value in the specified field.

Attribute Name Required Description
resource
Y
 Name of a properties file on the classpath.
property
Y
 The property whose value will be put in the field.
field-name
Y
 The name (key) of the map field to use.
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.
default
N
 The default value to use if the specified property is empty.
no-locale
N
 If sets to true don't use the default locale variable. Defaults to false.
arg-list-name
N

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.


ServiceOperations

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
field-name
Y
 The name (key) of the map field to use.
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.
result-name
N
 The name of the request attribute to use. Defaults to the field-name.