Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation around workflowId in success and failure actions is ambigous #245

Open
TristanSpeakEasy opened this issue Aug 29, 2024 · 0 comments
Labels
bug Something isn't working documentation Improvements or additions to documentation

Comments

@TristanSpeakEasy
Copy link

Following on from discussion in the open-api slack community here: https://open-api.slack.com/archives/C022K8VD7AP/p1724762008594319

I had the below issue:

Just trying to understand exactly how to validate a workflowId in a "Success Action". Here it states:
The workflowId referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the type field value is "goto". If multiple arazzo type sourceDescriptions are defined, then the workflowId MUST be specified using a runtime expression (e.g., $sourceDescriptions..) to avoid ambiguity or potential clashes. This field is mutually exclusive to stepId.
The thing I am struggling to understand is:
If there are "multiple" arazzo type sourceDescriptions defined (and I assume multiple means more than 1 defined in sourceDescriptions) then the workflowId "MUST" be a runtime expression.
If the workflowId is in the current document I should use a runtime expression to reference it? Or should I be adding the current document as an item in sourceDescriptions and referencing it via $sourceDescriptions..
If there is only one arazzo document in sourceDescription I can still reference a workflowId in the current document just using an id and not a runtime expression? This to me seems like it makes the "multiple" qualifications of the above statement a bit arbitrary? Should it say "any" instead of "multiple"? So if you need to reference workflowId in that single document it should be via $sourceDescriptions..
Basically I am trying to understand:
What is "multiple" defined as
Should I be listing the current document in sourceDescriptions
Does it have to be "MUST" even with other arazzo type documents in sourceDescriptions? couldn't you dictate that if its isn't a runtime expression then it refers to the current document? Otherwise resolve the runtime expression?

@frankkilcommins followed up with this clarification:

the use of the word "multiple" here is a bit clumsy/ambiguous. Can you register an issue for us to revise that wording? Dropping "multiple" or replacement with "any" are options to clarify.
The intention:
referencing a workflow within the current Arazzo Description can happen solely using the workflowId as the identifier MUST be unique across all workflows described in the Arazzo Description
referencing a workflow described within an Arazzo Description listed as a sourceDescription MUST be specified using a runtime expression
Could you register an issue for us to clarify this within the spec?
Your questions:
What is "multiple" defined as
As discussed above, the use of "multiple" causes confusion in this situation
Should I be listing the current document in sourceDescriptions
No
Does it have to be "MUST" even with other arazzo type documents in sourceDescriptions? couldn't you dictate that if its isn't a runtime expression then it refers to the current document? Otherwise resolve the runtime expression?
As mentioned above, to reference workflows within the current Arazzo Description, you can leverage the workflowId directly.

@frankkilcommins frankkilcommins added documentation Improvements or additions to documentation bug Something isn't working labels Aug 29, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants