THE OFBIZ SERVICE COOKBOOK
==========================

This document is a set of HOWTOs on using the ofbiz service system.
This includes tips on the SECA system.

* How to make a service into a web service:
  Add the tag export="true" to your service definition

* How to authenticate a web service call 
  Pass in login.username and login.password as parameters to your call 

* How to input a date such as 2005-29-12 instead of a full Timestamp

    <service definition>
      <attribute name="dateField" type="java.sql.Date" ...>
    </service>

* How to control number of times a failed service runs

   Use the max-retry="" tag in <service >

* Warning: Attribute types are case sensitive

  <!-- suppose we use "string" instead of "String"-->
  <attribute name="example" type="string" mode="IN" optional="false"/>  
  ... later on in the Java code ...
  String example = (String) context.get("example");  // result is null! You won't get a warning about this

* Warning: auto-attributes must have the include tag or they won't work

  This won't work correctly:
<auto-attributes mode="IN" entity-name="Content" optional="true"/>

  The fields wil show up as optional in the service reference, but ModelService may still consider them required.  You must specify the include
<auto-attributes mode="IN" include="nonpk" entity-name="Content" optional="true"/>

* How to set all input parameters of a service to a Map automatically

  Let's say you have a Map of key-value pairs, and you want to pass them quickly to a service.  The easiest
  way is to use the ModelService.makeValid method, pass in your Map, and get its result Map, then pass it to
  your service.  (In minilang, you can use <set-service-fields ..>)

* But how do I get a ModelService?

  DispatchContext has a .getModelService(String serviceName) method.

*  How to check for conditions SECAs

   This example from applications/party/servicedef/secas.xml shows:

    <!-- when an email communictaion event for a contact list is marked "IN PROGRESS", launch a background process to send them out -->
    <eca service="updateCommunicationEvent" event="commit">
        <condition field-name="statusId" operator="equals" value="COM_IN_PROGRESS"/>
        <condition field-name="communicationEventTypeId" operator="equals" value="EMAIL_COMMUNICATION"/>
        <condition field-name="contactListId" operator="is-not-empty"/>
        <action service="sendCommEventAsEmail" mode="async"/>
    </eca>
    <!-- if there is no contact list, then send it in the same thread and complete it -->
    <eca service="updateCommunicationEvent" event="commit">
        <condition field-name="statusId" operator="equals" value="COM_IN_PROGRESS"/>
        <condition field-name="communicationEventTypeId" operator="equals" value="EMAIL_COMMUNICATION"/>
        <condition field-name="contactListId" operator="is-empty"/>
        <action service="sendCommEventAsEmail" mode="sync"/>
    </eca>

   conditional workflow secas which causes sendComEventAsEmail to be sync when you try to send one email but async when you try to send to a whole list.  

*  What are the available operators?

   is-not-empty, is-empty, not-equals, equals, (check source for more) 

*  How to I return a service error from java?

   org.ofbiz.service.ServiceUtil.returnError("error message");

   Use the following if you want to pass a service error you just received from calling another service:
   org.ofbiz.service.ServiceUtil.returnError("error message", null, null, serviceResult);

*  What is the difference between an error and a failure?

   If you return a ServiceUtil.returnError(...), the service engine will set a transaction rollback and cause the whole chain of service calls to be rolled back,
   even if your service does not use transactions.

   To avoid this kind of behavior, you can use ServiceUtil.returnFailure(...) instead just to denote that your service was not a success, without necessarily
   triggering a chain of rollbacks.  This may be preferable if your service is only for computing or obtaining values. 

*  How to create and run a bsh service

  WE DO NOT NECESSARILY RECOMMEND IT, BUT YOU CAN DO IT LIKE THIS:

  In your servicedef, use the engine="bsh" attribute and invoke=""
  Specify the path to the bsh file using location="". This path is
  relative to the classpath named "script" in ofbiz-component.xml 
  
  <service name="bshService" engine="bsh" invoke="" 
    location="script/../bshService.bsh"/>

  The beanshell is given a context and dispatch context named "dctx" just
  like a normal service, hence you can start using them right away:

    /* bshService.bsh */
    delegator = dctx.getDelegator();
    dispatcher = dctx.getDispatcher();
    userLogin = context.get("userLogin");
    ...

  When you're done with the service or need to break out due to an error,
  define a variable called "result" and store the return Map in it, then
  call return;

    if (error) {
       result = ServiceUtil.returnError(errorMessage);
       return;
    }

    ... continue with script ...

    context = ServiceUtil.returnSuccess();
    context.put("returnData", returnData);
    // END OF FILE 

* Service engine configuration parameters from framework/service/config/serviceengine.xml:
    failed-retry-min: number of minutes before running a failed async service
 
*  Multi-service and transactions
   
   You can have a web form call the service engine multiple times by using the 
   
      <event type="service-multi" invoke="autoUpdateQuotePrice"/>

   This will cause the service to be called for multiple rows in your form, each one with _o_${i} appended to the end, and with the number of rows
   controlled by _rowCount parameter.

   By default, service-multi will wrap one big transaction around all the services, with a timeout set to _rowCount * transaction timeout of the service.

   If you do not want all the service calls to be wrapped in one transaction, use the global-transaction="false" parameter after the invoke="" (as of
   OFBIZ SVN r 472647/opentaps 0.9.3)