chore: suggest multilevel parameters

[DmitryAnansky]

This pull request proposes the introduction of additional options for defining parameters at different levels within the workflow specification.
According to current suggestion the only level that can have parameters defined is Step level.
This suggestion aims to provide more flexibility by allowing parameters definitions at the root and workflow levels as well.

The particular use-case can be found in the ExtendedParametersExample.workflow.yaml with JWT authentication token applied to all the Step API calls. This modification eliminates the need for duplicating parameters across individual steps, enhancing overall maintainability.

Same can be applied to Workflow level parameters.

workflowsSpec: 1.0.0
info:
  title: Public Zoo API
  version: '1.0'
sourceDescriptions:
  - name: animals
    type: openapi
    url: ./animals.yaml
parameters:
  - in: header
    name: Authorization
    value: Bearer someSecretToken
workflows:
  - workflowId: animal-workflow
    parameters:
      - in: cookie
        name: workflowLevelParamOne
        value: someValue
      - in: header
        name: workflowLevelParamTwo
        value: someValue
    steps:
      - stepId: post-step
        parameters:
          - in: cookie
            name: authentication
            value: SUPER_SECRET
        operationId: animals.postAnimal
      - stepId: get-step
        operationId: animals.getRandomAnimal

Please let me know what do you think about this idea,
Thanks.

[lornajane]

I had a bit of a dig through the slack channel history because I know I've seen this conversation before and to summarise: the expectation is that the same flows might be used with different parameters, so these would be supplied by the tool that uses the workflow rather than being coupled to the workflow.

So if you describe a flow where a user gets a list of items and edits the first one, you'd then execute the flow using parameters that are: a list, an empty list, an invalid user token, users with different access levels, etc.

My questions:

1. Is this a fair explanation of why the parameters are only set at step level (to get around the fact that it is harder to inject them to there)?
2. Is there a reason we wouldn't want to support them at other levels?
3. Does anyone have any concerns about us using x-parameters for this use case until we support parameters in more places?

[lornajane]

I'll also note that there's some connection with workflows[$id].inputs to think about if we support parameters at a per-workflow level (see https://github.com/OAI/sig-workflows/blob/main/versions/1.0.0.md#fixed-fields-3)

[frankkilcommins]

@lornajane - I'll try to answer below.

I had a bit of a dig through the slack channel history because I know I've seen this conversation before and to summarise: the expectation is that the same flows might be used with different parameters, so these would be supplied by the tool that uses the workflow rather than being coupled to the workflow.

I don't see a problem here, this would just be that the calling code would invoke the workflow with a different Inputs object instance

So if you describe a flow where a user gets a list of items and edits the first one, you'd then execute the flow using parameters that are: a list, an empty list, an invalid user token, users with different access levels, etc.

Here I would imagine that the workflow would have a defined Inputs object that takes an array of whatever and a string for the user token, then you run the workflow with different combinations of data for the Inputs object.

Example Inputs Object:

    Inputs:
      type: object
      properties:
        list: 
          type: array
          items:
            type: object
            properties:
              foo:
                type: string
              bar:
                type: integer
        token:
          type: string  

1. Is this a fair explanation of why the parameters are only set at step level (to get around the fact that it is harder to inject them to there)?

I believe the use case you laid out is possible by supplying the appropriate Input object values to the workflow (e.g. to run with different datasets). Theoretically, you could even pass in an Input object with counter property and a nested array containing all datasets and set up the workflow such that it loops through the data by defining an imaginative successCriteria to force iteration and setting the inputs data. Not sure such dark arts are warranted however.

2. Is there a reason we wouldn't want to support them at other levels?

One goal is to ensure that we can be very deterministic about what parameters on a step MUST be mappable to an API operation. Finding the scenario where 100% of the steps use a parameter might not be overly common. If indeed it's the case, defining the parameter with the components section and having a $ref to the parameter explicitly where it's applicable IMO is a verboseness we can live with for now.
If the very common situation that come to mind is an Authentication scenario, then I'd almost expect the Auth dance to be define in it's own independent workflow and referenced as the current workflow's first step.

3. Does anyone have any concerns about us using x-parameters for this use case until we support parameters in more places?

I'd like to dive deeper to understand what is the true use case / gap here that cannot be achieved using a combination of the reusable Inputs, reusable parameters, and chained workflows (see https://github.com/OAI/sig-workflows/blob/main/versions/1.0.0.md#components-object). Then we can determine if this is in/out of scope and a decision on your own extension can then be taken.

[RomanHotsiy]

I'd like to dive deeper to understand what is the true use case

One use case is to to provide an authorization header for all the steps in a whole workflows file.
Reusable parameters would require me to reference reusable parameter in every single step.

This is similar to how parameters are allowed on Operation object but also on the Path item object.

[frankkilcommins]

I'd like to dive deeper to understand what is the true use case

One use case is to to provide an authorization header for all the steps in a whole workflows file. Reusable parameters would require me to reference reusable parameter in every single step.

This is similar to how parameters are allowed on Operation object but also on the Path item object.

OK - I understand. Let me do some analysis so see what ratio of OAD's I can find that utilize params at the path item object level.

[frankkilcommins]

@RomanHotsiy @lornajane @DmitryAnansky I'm supportive of the proposal to have the ability to define parameters at the workflow level which will then be automatically applied to each step in the workflow should the need arise to have this behaviour.

I'd opt to hold off on the root level parameters to be used by all steps in all workflows for now until we have more feedback from the community on whether such a situation is very common.

[frankkilcommins]

Looks good. As suggested in last PR comment, let's limit to Workflow.parameters for now.
I'll submited a PR on your branch to adjust the Step.Parameters verbiage to align with the changes - See DmitryAnansky#1

[frankkilcommins]

@DmitryAnansky thanks for committing the changes. Could you merge DmitryAnansky#1 into your fork so that it's included in this PR?

[frankkilcommins]

I will create a separate PR to merge changes in DmitryAnansky#1 to the workflows main branch (issue #167 )