Proposed Change List of Assemble Specification for M2

Use consistent sytanx to define attributes of activities

*Feedbacks from the community*

1. Confusion for writing activity attributes

Bug 1308: "It took me ages to spot that when using the GET Activity. I needed to surround the target URL with single quotes. I couldn't find it documented anywhere, and it seems wrong that the simplest case of just referring to a URL needs such an uncommon syntax of single quotes. A url should be entered as a url not 'url'."

As Jonathan said, the confusion is from the "uncommon syntax of single quotes". The single quote is used to distinguish a literal string from other parts in the expression, but this is uncommon. Let us look one more post from Yoav who has been confused by the same thing. Post from Yoav Obviously, he thought "<sendMail name="mailParams" address="my@email.address" subject="any subject">" is the right one, as Jonathan thought, but according to the spec, it should be <sendMail name="mailParams" address="'my@email.address'" subject="any subject">

Both Jonathan and Yoav are confused by the uncommon quote around literals, which is different from people's default assumption. We ourselves often made this mistake too. This should be fixed so that people could write attributes of activities in a way they are used to.

Another relevant problem is the inconsistency of the way to specify the attributes' value. Please look at below sample:

   <sendMail address="'maoxs@cn.ibm.com'" subject="test" ...>

2. Support usage of variables in the attributes of custom activities

Post for using variable in the "subject" of sendMail activity This post requests "changable" content of the subject through use of variable in the content template. It means the content template of the subject is a string containing variables.

Post for changing sender of sendMail activity Same feedback as above, but it requests changable value for "sender" attribute.

This is a continued confusion in community that what attribute of a custom activity is changable, what is not. In other words, what attributes of an activity is 'literal string', which are not changable during runtime, while what attributes of an activity are changable during runtime, i.e. it could refer and use variables.

The custom activity, sendMail is one most frequently used sample, but it defines its attribte 'address' are changable while 'subject' and 'sender' are not. This sample activity implies that the flow programmer should explicitly knows which attributes are changable, which are not. This is a burden to them.

It means we need one consistent way for the programmers to write attributes of activities, including built-in and custom activity. This approach should avoid the confusion in the community discussed in "1. Confusion for writing activity attributes" too.

*Proposed change*

Generally there are below situations for attributes:

1. literal string, not changable during runtime
2. string template, part of it is changable during runtime
3. value expression, it will be evaluated at runtime

Could we have one consistent way, which people are used to, for people to write them?

We propose to introduce the JSP Expression Language style syntax in the default expression language which could meet this:

1. for literal string, you just write it diretly, e.g. "<sendMail address="maoxs@cn.ibm.com" subject="test" ...>"
2. for string template, you embed ${expression} within an attribute's value. e.g. <GET target="http://host:port/stockquote?symbol=${symbol}" ...>
3. value expression, just use ${expression}, e.g.

    <assign name="test">
       <copy to="email" from="${recv.user[0]}"/>
    </assign>

One good thing about JSP Expression Language style syntax is its popularity in Java community. And the default expression language of flow is Groovy, GString provide the native support for EL style syntax.

Further, the ${expression} could be used in other situations which requests an value expression, i.e. links (data, control and error), and some activities which requests value expression like the looping condition of "while" activity, a Boolean value expression.

Here, let us have a look at more details about the syntax and execution semantics of "${expression}". In the flow definition, the expression is always written between the delimiters ${ and }. And the expression will be evaluated only when certain activity is ready to execute. The result of expression evaluation replaces the expression and its delimiters in the template text.

1. In attribute value

<Activity name="NCName" attributeName="attributeValue" ...>

The value of attribute could be a) Text only

<activity attr="sometext"/>

<activity attr="${expression}"/>

c) With one or more expressions separated or surrounded by text:

<activity attr="some${expr1}text${expr2}"/>

2. Within "value" attribute of inputs of actvivities

<input name="NCName"? value="inputValue"? content-type="yes|no"?>complex value?</input>

<input value="hello world"/>

<input value="${recv.user[0]}"/>

<input value="Please go here to approve an order: ${request.flow.uri}/../approval.gt?${FLOW_ID}"/>

<input>Please go here to approve an order: ${request.flow.uri}/../approval.gt?${FLOW_ID}</input>

<assign name="test">
   <copy to="email" from="${recv.user[0]}"/>
</assign>

<while name="while" condition="flag == true">

<control source="approval1" transitionCondition="approval1.approve[0]=='yes'"/>

<for-each name="..." itemName="..."? >
   input 
   control*
   <activity>+
</for-each>

<replyPOST name="addReply">   
     <control source="addRcv"/>
     <input value="addRcv_Output.num[0].toDouble() + addRcv_Output.num[1].toDouble()"/>
</replyPOST>

<replyPOST name="addReply">   
     <control source="addRcv"/>
     <input value="${addRcv.num[0].toDouble() + addRcv.num[1].toDouble()}"/>
</replyPOST>

<process name="echoProcess">
  <receivePOST name="echoRcv"/>
  <replyPOST name="echoReply">
    <input value="echoRcv"/>
  </replyPOST>
</process>

<process name="echoProcess">
  <receivePOST name="echoRcv"/>
  <replyPOST name="echoReply">
    <input value="${echoRcv}"/>
  </replyPOST>
</process>

  
  <replyGET name="errorReply">      
        <input value="invokeAdder" error="yes"/>
  </replyGET> 

  <replyGET name="errorReply">      
        <input value="${invokeAdder_Exception}"/>
  </replyGET>