on WfXML-R.0.2.pdf
John Mettraux
this is my feedback about the document named "WfXML-R.0.2.pdf".
0.
* please downgrade me to commenter of the document, I'm not one of its authors.
Background : why the name WfXML for this document ? Link to WfXML ?
What's the link to the original WfXML specification.
Workflow Reference Model Diagram : where does this document stands in
thtat diagram ?
2.2
user authority : does that cover automated users ? roles ? principals ?
3.5
can an activity be shared by multiple processes ?
5.0
what is a service endpoint from a REST point of view ? Can there be no
endpoint ? Directly http://host:port/resource ?
5.1.3
I get the feeling that /wfcs/itemtypes/en_US/workflows and
/wfcs/itemtypes/ja_JP/workflows are two distinct resources... Aren't
they two distinct representations of the same resource ?
5.1.4
/wfcs/workflows/{id}/definitions/{id} : for me, this implies that a
workflow has many definitions. Not that a workflow has many versions
of a definition. How can the system distinguish {id} from {version} ?
5.2.1
How can you tell on which engine (your protocol implies that there are
potentially many) the process instance has to be created.
POST /wfcs/workflows/tweet_me/processes
...
<g:command>halt</g:command>
is not RESTful, "POST ... halt" should be DELETE...
Best regards,
--
John Mettraux -///- http://jmettraux.openwfe.org
Pat Cappelaere
Thank you so much for your time and early feedback on the document.
> * please downgrade me to commenter of the document, I'm not one of its
> authors.
As you wish (although a lot of "kisha" is in it and leverage from past
OpenWFE work).
> Background : why the name WfXML for this document ? Link to WfXML ?
> What's the link to the original WfXML specification.
We probably should expand on some background explanation. Wf-XML is the
original interoperability interface developed by Keith Swenson and other
WfMC members for workflow engine based on SOAP and ASAP / WS-Access. Most
of the information can be found here:
http://www.wfmc.org/standards/wfxml.htm
I originally wanted to use it as is but it did not fit the REST model.
However the model was worth preserving and all the legacy work that went
into it.
> Workflow Reference Model Diagram : where does this document stands in
> thtat diagram ?
The reference model is fairly important as it describes all the interfaces
that come in play. This is leveraged from the WfMC work:
http://www.wfmc.org/standards/referencemodel.htm
> 2.2
>
> user authority : does that cover automated users ? roles ? principals ?
Delegation of user authority to workflows is critical the web 2.0
application. I do not believe that this document needs to address user
authentication.
In the appendix, there is a best practice on how one implementation could go
about implementing Oauth 1.0 (and a simpler version of it for pre-approved
transactions). This provides a secure way to do transactions by adding a
signature in the http headers.
If the implementation uses OpenID, user authentication is done outside this
API so we do not need to do anything.
User access control is also implementation dependant. This API might only
need to specify what access is required when the workflow is created and
uploaded. This part needs to be added...I have not had the time to document
it yet. This would be part of the BPMN designer to workflow engine
interface for content management... Coming soon hopefully.
> 3.5
>
> can an activity be shared by multiple processes ?
Yes. A participant can perform many activities within one process.
Multiple processes will involve many participants performing many
activities.
> 5.0
>
> what is a service endpoint from a REST point of view ? Can there be no
> endpoint ? Directly http://host:port/resource ?
You could but this might not be recommended if you want that host to
eventually support many other services.
> 5.1.3
>
> I get the feeling that /wfcs/itemtypes/en_US/workflows and
> /wfcs/itemtypes/ja_JP/workflows are two distinct resources... Aren't
> they two distinct representations of the same resource ?
That is a good question.
This portion is really lifted from the Google API to query metadata
information.
http://www.google.com/base/api/demo/html/demo.html#metadata
Are you suggesting to use something else?
> 5.1.4
>
> /wfcs/workflows/{id}/definitions/{id} : for me, this implies that a
> workflow has many definitions. Not that a workflow has many versions
> of a definition. How can the system distinguish {id} from {version} ?
A workflow can have many definitions. I suppose that they would be
different versions as the workflow gets refined and new definitions get
refactored.
The end-user would always use the same workflow name or id.
A definition does not have a name so we could use the version as a name:
/wfcs/workflows/3/definitions/v_1
/wfcs/workflows/tweet_me/definitions/v_2_1
The version would have to be a string and not an id to avoid confusion.
I am not very satisfied with this but cannot think of something more
elegant. If you have any other suggestion, please let me know.
> 5.2.1
>
> How can you tell on which engine (your protocol implies that there are
> potentially many) the process instance has to be created.
Good question. Since "engine" is a resource. The door is open to a POST
that would create a new engine and a DELETE that would delete the old
engine. Do you think that needs to be supported?
> POST /wfcs/workflows/tweet_me/processes
> ...
> <g:command>halt</g:command>
>
> is not RESTful, "POST ... halt" should be DELETE...
May be we should use suspend|resume to avoid confusion.
Start and Stop are the other 2 commands used in the same breath. This is
not RESTful to implement them there but users may be accustomed to using
them there. Could go either way.
Thanks again.
Hopefully Keith will provide more info, background and other recommendations
to help us out.
This is a big deal and I really appreciate all the work you have already
done in that area as many others have. Everyone needs to be recognized in
that effort.
V/R,
Pat.
John Mettraux
On Jan 14, 2008 6:46 AM, Pat Cappelaere <cappe...@gmail.com> wrote:
>
> > * please downgrade me to commenter of the document, I'm not one of its
> > authors.
>
> As you wish (although a lot of "kisha" is in it and leverage from past
> OpenWFE work).
Yeah, I would love to finish my work on Kisha, by
designing/implementing it, I could get my ideas clear on all of this.
> > Workflow Reference Model Diagram : where does this document stands in
> > thtat diagram ?
>
> The reference model is fairly important as it describes all the interfaces
> that come in play. This is leveraged from the WfMC work:
> http://www.wfmc.org/standards/referencemodel.htm
It feels isolated there in the document, and nowhere else it is
further referenced.
> > 5.0
> >
> > what is a service endpoint from a REST point of view ? Can there be no
> > endpoint ? Directly http://host:port/resource ?
>
> You could but this might not be recommended if you want that host to
> eventually support many other services.
>
> > 5.1.3
> >
> > I get the feeling that /wfcs/itemtypes/en_US/workflows and
> > /wfcs/itemtypes/ja_JP/workflows are two distinct resources... Aren't
> > they two distinct representations of the same resource ?
>
> That is a good question.
> This portion is really lifted from the Google API to query metadata
> information.
> http://www.google.com/base/api/demo/html/demo.html#metadata
> Are you suggesting to use something else?
en_US and ja_JP feel like "flavour" of the representation.
/wfcs/itemtypes/workflows?lang=ja_JP is not that bad. Maybe there are
other better examples. My feeling was that the language was given
priority over the actual resource.
At this point of the document a simpler example (less prone to debate)
could help infuse the RESTful point of view.
> > 5.1.4
> >
> > /wfcs/workflows/{id}/definitions/{id} : for me, this implies that a
> > workflow has many definitions. Not that a workflow has many versions
> > of a definition. How can the system distinguish {id} from {version} ?
>
> A workflow can have many definitions. I suppose that they would be
> different versions as the workflow gets refined and new definitions get
> refactored.
> The end-user would always use the same workflow name or id.
> A definition does not have a name so we could use the version as a name:
>
> /wfcs/workflows/3/definitions/v_1
> /wfcs/workflows/tweet_me/definitions/v_2_1
>
> The version would have to be a string and not an id to avoid confusion.
> I am not very satisfied with this but cannot think of something more
> elegant. If you have any other suggestion, please let me know.
IMO, /wfcs/workflows/{process_definition_name}/{process_definition_revision}
is sufficient.
For you, is a workflow (a) a set of the same process definitions with
a different revision number ? Or (b) a set of process definitions
which grouped make for a complex workflow (then which is the top
definition ?) ?
Sorry for playing the lawyer, but you seem to be writing a
specification after all.
My extended opinion on that is that a true REST[ful] workflow system
should not care about doing content management, it should leverage the
'web' and simply GET its process definitions via a given URI. Just for
the record.
> > 5.2.1
> >
> > How can you tell on which engine (your protocol implies that there are
> > potentially many) the process instance has to be created.
>
> Good question. Since "engine" is a resource. The door is open to a POST
> that would create a new engine and a DELETE that would delete the old
> engine. Do you think that needs to be supported?
>
> > POST /wfcs/workflows/tweet_me/processes
> > ...
> > <g:command>halt</g:command>
> >
> > is not RESTful, "POST ... halt" should be DELETE...
>
> May be we should use suspend|resume to avoid confusion.
> Start and Stop are the other 2 commands used in the same breath. This is
> not RESTful to implement them there but users may be accustomed to using
> them there. Could go either way.
Paraphrasing the holy scriptures : "POST is for creating resources,
PUT is for modifying them". Instead of POSTing to a resource with a
command to modify its 'status', you should be PUTting to it by
indicating the new status you want it to reach.
Pat Cappelaere
>
> On Jan 14, 2008 6:46 AM, Pat Cappelaere <cappe...@gmail.com> wrote:
>>
>>> * please downgrade me to commenter of the document, I'm not one of its
>>> authors.
>>
>> As you wish (although a lot of "kisha" is in it and leverage from past
>> OpenWFE work).
>
> Yeah, I would love to finish my work on Kisha, by
> designing/implementing it, I could get my ideas clear on all of this.
The purpose of this document is to clarify the interface before implementing
it. I think that we are getting close. I would be really happy if you could
implement it :). I would like to build the consensus first based on many
years of experience rather than create something from scratch that cannot
get any support for interoperability.
>>> Workflow Reference Model Diagram : where does this document stands in
>>> thtat diagram ?
>>
>> The reference model is fairly important as it describes all the interfaces
>> that come in play. This is leveraged from the WfMC work:
>> http://www.wfmc.org/standards/referencemodel.htm
>
> It feels isolated there in the document, and nowhere else it is
> further referenced.
I agree that it needs to be further explained. I am hoping that Keith will
jump in and help. I am not a very good writer... Trying my best here!.
>>> 5.1.3
>>>
>>> I get the feeling that /wfcs/itemtypes/en_US/workflows and
>>> /wfcs/itemtypes/ja_JP/workflows are two distinct resources... Aren't
>>> they two distinct representations of the same resource ?
>>
>> That is a good question.
>> This portion is really lifted from the Google API to query metadata
>> information.
>> http://www.google.com/base/api/demo/html/demo.html#metadata
>> Are you suggesting to use something else?
>
> en_US and ja_JP feel like "flavour" of the representation.
> /wfcs/itemtypes/workflows?lang=ja_JP is not that bad. Maybe there are
> other better examples. My feeling was that the language was given
> priority over the actual resource.
>
> At this point of the document a simpler example (less prone to debate)
> could help infuse the RESTful point of view.
Another path I had previously taken was to use an extension to output the
metadata associated with a collection type such as:
/wfcs/workflows.metadata
/wfcs/definitions.metadata
/wfcs/processes.metadata
This is more intuitive and rails like in my opinion but this is not what
Google chose to do.... Hummmm!
I will keep looking around... Any other idea is welcome!
>>> 5.1.4
>>>
>>> /wfcs/workflows/{id}/definitions/{id} : for me, this implies that a
>>> workflow has many definitions. Not that a workflow has many versions
>>> of a definition. How can the system distinguish {id} from {version} ?
>>
>> A workflow can have many definitions. I suppose that they would be
>> different versions as the workflow gets refined and new definitions get
>> refactored.
>> The end-user would always use the same workflow name or id.
>> A definition does not have a name so we could use the version as a name:
>>
>> /wfcs/workflows/3/definitions/v_1
>> /wfcs/workflows/tweet_me/definitions/v_2_1
>>
>> The version would have to be a string and not an id to avoid confusion.
>> I am not very satisfied with this but cannot think of something more
>> elegant. If you have any other suggestion, please let me know.
>
> IMO, /wfcs/workflows/{process_definition_name}/{process_definition_revision}
> is sufficient.
>
> For you, is a workflow (a) a set of the same process definitions with
> a different revision number ? Or (b) a set of process definitions
> which grouped make for a complex workflow (then which is the top
> definition ?) ?
(a) A workflow is the handle that embodies the work to be done. It has an
id, a name, a designer author name... The designer creates the flow itself
in some GUI (BPMN 1.0 for example) and eventually uploads it to the workflow
engine for execution. End users can then execute that workflow using the
uploaded process definition. New and enhanced versions can then be uploaded
later as necessary (and transparently to the user unless user wants to go
back to older version)
> Sorry for playing the lawyer, but you seem to be writing a
> specification after all.
You make some good points. No need to apologize. This is indeed a
specification to clarify things. If it is not clear, we need to work on it.
> My extended opinion on that is that a true REST[ful] workflow system
> should not care about doing content management, it should leverage the
> 'web' and simply GET its process definitions via a given URI. Just for
> the record.
It needs a way to receive process definitions that could be created by an
external modeler. These services would publish their work to the engine.
The engine itself becomes GUI agnostic once we agree on the API (which is
one of the goals of the document). This will be defined in the POST
/wfcs/workflows/{name}/definitions
>>> 5.2.1
>>>
>>> How can you tell on which engine (your protocol implies that there are
>>> potentially many) the process instance has to be created.
>>
>> Good question. Since "engine" is a resource. The door is open to a POST
>> that would create a new engine and a DELETE that would delete the old
>> engine. Do you think that needs to be supported?
>>
>>> POST /wfcs/workflows/tweet_me/processes
>>> ...
>>> <g:command>halt</g:command>
>>>
>>> is not RESTful, "POST ... halt" should be DELETE...
>>
>> May be we should use suspend|resume to avoid confusion.
>> Start and Stop are the other 2 commands used in the same breath. This is
>> not RESTful to implement them there but users may be accustomed to using
>> them there. Could go either way.
>
> Paraphrasing the holy scriptures : "POST is for creating resources,
> PUT is for modifying them". Instead of POSTing to a resource with a
> command to modify its 'status', you should be PUTting to it by
> indicating the new status you want it to reach.
I agree. The initial creation would use a POST with the command attribute
set to "start".
To modify that attribute and the process behavior, one would need a PUT.
This is probably not well explained yet and I am taking notes of it... I
will move the command tag definition to that section.
Thanks again.
Pat.