Enhance the metadata definition for the extension activities of Assemble flow

In current implementation, the activity's metadata looks like that

/config/activity/metadata/sendMail = {
   "attributes" : [
      {"name":"subject"},
      {"name":"address"},
      {"name":"view", "required":false},
      {"name":"cc", "required":false},
      {"name":"bcc", "required":false}
   ],
   "inputOccurrence" : 1,
   "withoutOutput" : true
}

The description of the metadata is in the following document

Create extension activity

There are one major issues of current metadata description is the metadata doesn't support input with name well. The tooling cannot leverage such information to create the widget and validate the inputs.

E.g. we can extend the sendMail activity, it have one required input named "body" for content, and one optional input for the "attachment" as following

    <sendMail name="sendMail_0" 
                address="${inputForm_0.client[0]}" 
                subject="The proposal of your request.">
        <input name="body" value="Here's the final proposal.s" />
        <input name="attachment" value="${getAttachedFile_0}"/>
    </sendMail>

But we could use as-is metadata to validate the flow markup and give tooling enough information to generate the widget for that.

After the discussion with team. The draft proposal is, we can define the input similar to attributes in metadata. E.g.

/config/activity/metadata/sendMail = {
   "attributes" : [
      {"name":"subject"},
      {"name":"address"},
      {"name":"view", "required":false},
      {"name":"cc", "required":false},
      {"name":"bcc", "required":false}
   ],
   "inputs" : [
      {"name":"body", "required":false},
      {"name":"attachment", "required":false }
   ],
   "output" : null
}

If we can support the multiple attachments in the sendMail activity. We will use

/config/activity/metadata/sendMail = {
   "attributes" : [
      {"name":"subject"},
      {"name":"address"},
      {"name":"view", "required":false},
      {"name":"cc", "required":false},
      {"name":"bcc", "required":false}
   ],
   "inputs" : [
      {"name":"body", "required":false},
      {"name":"attachment", "occurrence":"*" }
   ],
   "output" : null
}

It can support the above requirement well for both validation and tooling support, And we can provide the backward compatibility for the original metadata description, thus the activities with old metadata description will not be impacted.

Specification of the metadata

/config/activity/metadata/<activityName>= {
   "attributes" : [
      {
            "name": <name>, 
            "required": <boolean value>?, 
            "defaultValue": <value>? 
       } *
   ],
   "inputs" : [
      {
             "name":<name>, 
             "occurrence": <occurrence>?
      } *
   ],
   "output": null?
}

Name	Description	Required	Note
activityType	The type of the custom activity.	Yes
attributes	Describe the attributes that the activity supports. You can specify the name, and whether the attribute is required. By default the value is true. If it is an optional attribute, you need to set the value to false or "false". When the value is not specified in flow definition, the defaultValue is will be used.	Yes
inputs	Describe the input that the activity supports. You can specify the name and whether the input is required, and the "occurrence" for repeatable inputs. More details for the value of "occurrence" are listed below	No
inputOccurrence	The old format for input description. It will specify the the minimum and maximum numbers of inputs that are allowed.	No	Deprecated
output	If it is null, this activity will have no output	No
withoutOutput	Specifies if the activity have output. If the value is true, it can not have output. Otherwise, it can have output.	No	Deprecated

Note:

• 1. The occurrence value could be

1..* 
    It can accept at least one input.
0..1 
    It can accept, at most, one input.
3
    It can accept three inputs.
0
    No input is allowed.

• 2. If you want the input name could be any string, you can use "*" as wild card in the input definition

GC conventions

Path	Type	Description	Read/Write	Enhancement
/event/attribtues	Map<String, String>	The map of attributes	Read only	No
/evnet/attributes#name	String	The value of certain attribute	Read only	No
/event/inputs	List<Object>	The map of inputs	Read only	No
/event/inputNames	List<String>	The name of inputs	Read only	Yes
/event/contentTypes	List<String>	The name of inputs	Read only	Yes
/event/inputMap	Map<String, Object>	The map of inputs	Read only	No
/event/inputMap#name	Object	The value of certain input	Read only	No
/event/contentTypeMap	Map<String, String>	The map of content-type	Read only	Yes
/event/contentTypeMap#name	String	The content-type of certain input	Read only	Yes
/event/result	Object	The path to put the result	Write only	No
/event/resultContentType	String	The path to put the content-type of result	Write only	No

Migration Guide

The enhancement provide good backward compatibility. For the most cases, the implementation of extension activities or the existing flow won't be impacted.

You can continue use the old format for the metadata creation, but it is not recommended. In the flow definition, if the name of Activity input is missing, that input will be treated as same as the input defined in the first activity. E.g. The following two flow snippets are equality.

    <sendMail name="sendMail_0" 
              address="${inputForm_0.client[0]}" 
              subject="The proposal of your request.">
        <input value="Here's the final proposal." />
    </sendMail>

    <sendMail name="sendMail_0" 
              address="${inputForm_0.client[0]}" 
              subject="The proposal of your request.">
        <input name="body" value="Here's the final proposal." />
    </sendMail>

The following built-in activities will be updated

• <sendMail> : If you want to send the attachment in the email, you must specify the input with name "attachement" * <XSLT> : If you want to specify the variables used in the XSLT transformation context, you need to specify the input with name "variables "

Further Discussion: Extension activity with sample data Support

(Not in M1: It is for discussion only)

The optional information of data type and sample data could be used by tooling to simplify the data selection and validation. We can add the sample data support into the metadata of Activity.

/config/activity/metadata/<activityName>= {
  "attributes" : [
      {
            "name": <name>, 
            "required": <boolean value>?, 
            "defaultValue": <value>? 
       } *
   ],
   "inputs" : [
      {
             "name":<name>, 
             "occurrence": <occurrence>?, 
             "type": <list of accepted data type>
      } *
   ],
   "output": { 
            "type": <data type of result >?, 
             "sample":<sample value>?, 
             "sampleFile":<file path>?
   }?
}

NOTE:

• The "type" for input defines the list of accepted data type separated with comma
• The "type" for output defines the data type of the activity result
• "sample", "sampleFile" of output will provide the sample data to facilitate the tooling for better data selection.
• If the sample value should be consistent with its "type", e.g. the sample value in "json" should be the map or array.

The supported data types

• "json", "xml", "feed", "form" or the content-type like "application/json", "text/xml"
• string, number, boolean (Simple data type supported in JSON)
• * : Any data type for flexibility

Change Logs

• First draft 07/10
• Update per Dave's suggestion 07/14
• Update with sample data support 07/18

-- yili - 10 Jul 2008