Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

This is deprecated, the new documentation is at Mini Language - minilang - simple-method - Reference.

 

In progress of being transferred to the Wiki.

Once transferred will need to confirm if this is deprecated and then archive.

Table of Contents

Table of Contents

...

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 NameRequired?Description
value-nameYThe name of the method environment field that contains the GenericValue object.
entity-nameYThe name of the entity to find an instance of.
map-nameYThe name of a map in the method environment that will be used for the entity fields.
delegator-nameNBy 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-cacheNSpecifies 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 NameRequired?Description
ist-nameYThe name of the method environment field that contains the list of GenericValue objects.
entity-nameYThe name of the entity to find instances of.
map-nameYThe name of a map in the method environment that will be used for the entity fields.
order-by-list-nameYThe name of a list in the method environment that contains a list of strings specifying fields to order the results by.
delegator-nameNBy 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-cacheNSpecifies 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-iteratorNSpecifies 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 NameRequired?Description
list-nameYThe name of the method environment field that contains the list of GenericValue objects.
to-list-nameNThe 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-nameNThe 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 NameRequired?Description
list-nameYThe name of the method environment field that contains the list of GenericValue objects.
to-list-nameNThe 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-nameNThe name of a field in the method environment date to filter by. Defaults to now.
from-field-nameNThe name of the GenericValue field to use as the beginning effective date. Defaults to fromDate.
thru-field-nameNThe name of the GenericValue field to use as the ending effective date. Defaults to thruDate.
all-sameNSpecifies whether or not all GenericValue objects in the list are of the same entity. Defaults to true.

Entity Engine Value Operations

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 NameRequired?Description
value-nameYThe name of the method environment field that contains the GenericValue object.
entity-nameYThe name of the entity to construct an instance of.
map-nameNThe 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 NameRequired?Description
value-nameYThe name of the method environment field that contains the GenericValue object.
new-value-nameYThe 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 NameRequired?Description
value-nameYThe 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 NameRequired?Description
value-nameYThe 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 NameRequired?Description
value-nameYThe 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 NameRequired?Description
entity-nameYThe name of the entity to remove instances of.
map-nameYThe 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 NameRequired?Description
entity-nameYThe name of the entity to clear cache lines of.
map-nameYThe 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 NameRequired?Description
value-nameYThe name of the method environment field that contains the GenericValue object.
map-nameYThe name of a map in the method environment that will be used for the entity fields.
set-if-nullNSpecifies 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 NameRequired?Description
value-nameYThe name of the method environment field that contains the GenericValue object.
map-nameYThe name of a map in the method environment that will be used for the entity fields.
set-if-nullNSpecifies whether or not to set fields that are null or empty. Defaults to true.

Entity Engine List Operations

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 NameRequired?Description
list-nameYThe 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 NameRequired?Description
list-nameYThe name of the method environment field that contains the list of GenericValue objects.

Entity Engine Transaction Operations

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 NameRequired?Description
began-transaction-nameNThe 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 NameRequired?Description
began-transaction-nameNThe 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 NameRequired?Description
began-transaction-nameNThe 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".

Conditional (If) Operations

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 NameHow ManyDescription
condition1A 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).
then1The 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-if0 to manyThe 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.
else0 or 1The 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 NameRequired?Description
map-nameNThe 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-nameYThe name of the map field that will be validated.
methodYThe 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.
classNThe name of the class that contains the validation method. If not specified defaults to "org.ofbiz.base.util.UtilValidate".
Sub-Element NameHow ManyDescription
Any Operation0 to manyAny simple-method operation can be nested under an if-* tag.
else0 or 1The 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 NameRequired?Description
map-nameNThe 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-nameYThe name of the map field that will be compared.
operatorYSpecified the comparison operator must be one of the following: less, greater, less-equals, greater-equals, equals, not-equals, or contains.
valueYThe value that the field will compared to. Must be a String, but can be converted to other types.
typeNThe 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.
formatNA format specifier to use when converting String objects to other data types, mainly Date, Time and Timestamp.
Sub-Element NameHow ManyDescription
Any Operation0 to manyAny simple-method operation can be nested under an if-* tag.
else0 or 1The 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 NameRequired?Description
map-nameNThe 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-nameYThe name of the map field that will be compared.
operatorYSpecified the comparison operator must be one of the following: less, greater, less-equals, greater-equals, equals, not-equals, or contains.
to-map-nameNThe 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-nameNThe name of the to-map field that the main field will be compared to. If left empty will default to the field-name.
typeNThe 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.
formatNA format specifier to use when converting String objects to other data types, mainly Date, Time and Timestam
Sub-Element NameHow ManyDescription
Any Operation0 to manyAny simple-method operation can be nested under an if-* tag.
else0 or 1The 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 NameRequired?Description
map-nameNThe 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-nameYThe name of the map field that will be compared.
exprYA regular expression that the map value must comply with.
Sub-Element NameHow ManyDescription
Any Operation0 to manyAny simple-method operation can be nested under an if-* tag.
else0 or 1The 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 NameRequired?Description
map-nameNThe 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-nameYThe name of the map field that will be compared.
Sub-Element NameHow ManyDescription
Any Operation0 to manyAny simple-method operation can be nested under an if-* tag.
else0 or 1The 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 NameRequired?Description
map-nameNThe 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-nameYThe name of the map field that will be compared.
Sub-Element NameHow ManyDescription
Any Operation0 to manyAny simple-method operation can be nested under an if-* tag.
else0 or 1The 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 NameRequired?Description
permissionYThe name of the permission in the database. The user must belong to a security group that has this permission.
actionNIf 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 NameHow ManyDescription
Any Operation0 to manyAny simple-method operation can be nested under an if-* tag.
else0 or 1The 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 NameRequired?Description
permissionYThe name of the permission in the database. The user must belong to a security group that has this permission.
actionNIf 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-nameNThe 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 NameHow ManyDescription
alt-permission0 to manyAllows 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-messageoneAn inline failure message.
fail-propertyoneA 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 NameRequired?Description
field-nameYThe name of the field that contains the ID value to check.
map-nameNThe name of the Map that contains the field. If not specified the environment will be used to find the field.
error-list-nameNThe 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 NameHow ManyDescription
fail-messageoneAn inline failure message.
fail-propertyoneA failure message from a properties file.

Other Operations

property-to-field

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

Attribute NameRequired?Description
resourceYThe resource location of the properties file.
propertyYThe property whose value will be put in the field.
defaultNThe default value to use if the specified property is empty.
map-nameNThe 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-nameYThe 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 NameRequired?Description
levelYThe 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.
messageNA 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 NameHow ManyDescription
field0 to manyInserts the value of the field into the message where specified.
string0 to manyInserts 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 NameRequired?Description
map-nameNThe 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-nameYThe name (key) of the map field to use.
typeNThe object type to put into this field. Can be: Double | Float | Long | Integer. The default is Double.
Sub-Element NameHow ManyDescription
calcop0 to manyThis 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.
number0 to manyThis 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>

Simple Methods Example

<!DOCTYPE simple-methods PUBLIC "-//OFBiz//DTD Simple Methods//EN" "http://ofbiz.apache.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>