Any guidance for tooling to decide which workflows to run from the document

[RomanHotsiy]

I understand this may be out of the context for the spec but it would be good to provide some guidance for tooling authors.

Currently our WIP tool accepts a path to the Workflow document and runs all workflows from it.

But we found some ambiguity reviewing one of the examples here: https://github.com/OAI/sig-workflows/blob/main/examples/1.0.0/oauth.workflow.yaml

This document describes 2 workflows: 'refresh-token-flowandauthorization-code-flow. But the first step of the 'refresh-token-flow executes the whole authorization-code-flow workflows.

We feel like the author intent here was to only run refresh-token-flow workflow from this file (kind of root or main workflows) while the authorization-code-flow feels like a "helper function".

(the obvious solution is to accept workflow id as an input for the tool but I hope there may be some better solution?)

Could you help us clarify it?

[kevinduffey]

So this is an example of 3 different authorization flows (there is a client credential one as well).

So at face value one may think that one of these flows is meant to be executed. In reality this is more of a workflow for reusability. It offers 3 different authorizations that an org may implement. Another workflow would then include this one, and use one (or two or all) of them in various other workflows.

So if your company only does token Base64 authorization, then you may only have one auth flow in a reusable workflow. Then use that in various other workflows so as to not duplicate that authorization flow. If your company only has a single workflow with ALL the flows in it (ideally you'd hope modularity would be a thing), then they could just put the auth flow they use there as well.

I have suggested in (#153) that we consider a workflow dependsOn property. This is a good example of where this type of file would be of use. If you have 10 workflows all relying on say token auth, and you break those up across 10 files, my suggestion is we have a dependsOn at the workflow level, not step level, that would then say "depend on the auth workflow (in the sourceDocs section)." This would basically say "the auth flow MUST run/success before THIS workflow can continue because it depends on some output from that workflow".

[frankkilcommins]

@RomanHotsiy having multiple workflows in a single document, or spreading across multiple documents it completely at the discretion of the author.

In this particular instance, there are 3 workflows describing independent use cases that can be executed leveraging the endpoints described within the referenced OpenAPI document. It just so happens that the one of the workflow's has a step that references an additional workflow. In this case the workflow referenced happens to be within the same document, but it could also be in a separate Workflows Document).

Aside - i'm not sure how valid the example is ... re executing an Authorization Code Flow as part of a Refresh Token Flow.

Leaving step references aside, each workflow is independent and there's no expectation that any tool interacting with a Workflow Document has to execute all workflows. I think this all completely depends on the context.

Example:

• A parser/linter would validate that all workflows are correct and conforming to the specification
• A documentation tool might render all workflows on a single UI page (or may create a tab or page per workflow)
• A testing tool might import all workflow, or present a dialog to a user to select all or some of the defined workflows. Similarly it may run and assert all workflows or run on-demand based on user input.
• etc.

In the future we will likely add a dependsOn property at workflow level, but this still will have no bearing on the fact that multiple independent workflow can coexist without any dependencies within a single Workflows Document.