Added workflow response object to workflow creation call #409

PatStLouis · 2024-08-06T19:33:30Z

Addresses #393

Replace workflowId in request/response and returned a workflow object.

Replace workflowId in request/response and returned a workflow object.

exchanges.yml

dlongley · 2024-08-06T20:01:24Z

exchanges.yml

-        workflowId:
-          type: string
-          description: The URL that uniquely identifies the created workflow.
+        workflowData:


Hmm, I think just the workflow config should be returned here and it looks like this is something a little different with some additional metadata is here. Certainly an implementation could do more, but I think we should only say that the workflow config is returned (i.e,. the same thing you'd get if you did a GET on the workflow ID).

Suggested change

workflowData:

config:

This is a copy of what is returned by the GET workflowId as you are suggesting with the addition of the workflowId itself under the 'id' property as mentioned in the original issue.

Oh, I see we have a couple of mistakes in what's in the spec now then. There should be no workflowData property when creating a workflow, rather, the properties here:

vc-api/exchanges.yml

Lines 190 to 222 in 5efdafd

properties:

steps:

type: object

description: One or more steps required to complete an exchange on the workflow. Passing the steps object is REQUIRED.

properties:

stepName:

type: object

description: The name of the step.

properties:

step:

$ref: "#/components/schemas/WorkflowStep"

initialStep:

type: string

description: The step from the above set that the exchange starts on. Passing intialStep is REQUIRED.

controller:

type: string

description: The controller of the instance. Passing controller is OPTIONAL.

authorization:

type: string

description: Authorization scheme information (e.g., OAuth2 configuration). Passing authorization is OPTIONAL.

credentialTemplates:

type: array

description: One or more VC templates for issuance. Passing credentialTemplates is OPTIONAL.

items:

type: object

properties:

type:

type: string

template:

type: string

id:

type: string

description: The ID that will be used for the created workflow. Passing an ID is OPTIONAL.

Should just be the main top-level properties in the payload, this is the "config" for the workflow.

I also see that the GET workflowId section is inconsistent and adds that extra stepInformation bit -- which we should remove (collapse it down so its nested properties are moved up a level so it matches what should be in the above payload for creating the workflow).

dlongley · 2024-08-06T20:02:14Z

exchanges.yml

+              type: object
+              description: Information about the steps required for the workflow. Returning stepInformation is REQUIRED.
+              properties:
+                exchanges:


I think this could be a potentially huge number of exchanges for a very popular workflow -- and it isn't part of the config, so we shouldn't do this as a requirement, though some implementation might return this kind of data if that is desirable/not problematic.

dlongley · 2024-08-06T20:03:05Z

exchanges.yml

+            stepInformation:
+              type: object
+              description: Information about the steps required for the workflow. Returning stepInformation is REQUIRED.
+              properties:
+                exchanges:
+                  type: array
+                  description: The identifiers of the current exchanges associated with the workflow instance.
+                  items:
+                    type: string
+                steps:
+                  type: object
+                  description: One or more steps required to complete an exchange on the workflow.
+                  properties:
+                    stepName:
+                      type: object
+                      description: The name of the step.
+                      properties:
+                        step:
+                          $ref: "#/components/schemas/WorkflowStep"
+                initialStep:
+                  type: string
+                  description: The step from the above set that the exchange starts on.


I think the stepInformation bit should be collapsed to what's in the config, i.e., I think steps and initialStep are nested here when they shouldn't be. See also note on "current exchanges".

This is a copy of the config of an existing workflow returned by the get workflowId route, could you provide an example of what the config should look like if this is not it?

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

PatStLouis

Happy to make the required changes if I can get some examples provided.

exchanges.yml

PatStLouis · 2024-08-08T02:00:08Z

exchanges.yml

+            stepInformation:
+              type: object
+              description: Information about the steps required for the workflow. Returning stepInformation is REQUIRED.
+              properties:
+                exchanges:
+                  type: array
+                  description: The identifiers of the current exchanges associated with the workflow instance.
+                  items:
+                    type: string
+                steps:
+                  type: object
+                  description: One or more steps required to complete an exchange on the workflow.
+                  properties:
+                    stepName:
+                      type: object
+                      description: The name of the step.
+                      properties:
+                        step:
+                          $ref: "#/components/schemas/WorkflowStep"
+                initialStep:
+                  type: string
+                  description: The step from the above set that the exchange starts on.


This is a copy of the config of an existing workflow returned by the get workflowId route, could you provide an example of what the config should look like if this is not it?

msporny · 2024-08-13T19:16:15Z

exchanges.yml

+            id:
+              type: string
+              description: The URL that uniquely identifies the created workflow.
+            stepInformation:


From the call: Delete stepInformation

msporny · 2024-08-13T19:16:44Z

exchanges.yml

+                steps:
+                  type: object
+                  description: One or more steps required to complete an exchange on the workflow.
+                  properties:
+                    stepName:
+                      type: object
+                      description: The name of the step.
+                      properties:
+                        step:
+                          $ref: "#/components/schemas/WorkflowStep"
+                initialStep:
+                  type: string
+                  description: The step from the above set that the exchange starts on.


Move steps and initialStep up/left one level.

msporny · 2024-08-13T19:18:24Z

exchanges.yml

    CreateWorkflowResponse:
      type: object
      additionalProperties: false
-      description: Object containing information about a created workflow.
+      description: Response containing the created workflowData Object.


Change workflowData -> config.

Same changes with workflowX -> X (in general).

dlongley · 2024-08-20T18:58:11Z

exchanges.yml

@@ -183,7 +183,7 @@ components:
      additionalProperties: false
      description: Object containing information for creating a workflow.
      properties:
-        workflowData:
+        config:


When creating a workflow, the config is the payload, it is not nested under config. I think we should have a WorkflowConfig object that can be referenced and used here as the direct payload and in other places where a config property is used to express it along with other side-by-side properties (like in the response / potentially other places) this object type can just be referenced -- rather than duplicating its rather long schema description.

dlongley · 2024-08-20T18:58:57Z

exchanges.yml

@@ -217,49 +217,81 @@ components:
                    type: string
                  template:
                      type: string
-            workflowId:
+            id:


id can be optional within the WorkflowConfig object when creating a workflow, indicating either a preferred id (which some servers may honor, others may reject).

dlongley · 2024-08-20T19:01:01Z

exchanges.yml

+            exchanges:
+              type: array
+              description: The identifiers of the current exchanges associated with the workflow instance.
+              items:
+                type: string


I don't expect this (exchanges) to ever be part of a WorkflowConfig -- and it may be very large in size anyway.

dlongley · 2024-08-20T19:01:19Z

exchanges.yml

    GetWorkflowResponse:
      type: object
      additionalProperties: false
      description: Object containing information about a workflow.
      properties:
-        workflowData:
+        config:


I expect this endpoint to return the WorkflowConfig directly as the response payload here.

msporny · 2024-08-20T19:13:56Z

This PR was merged presuming that a WorkflowConfig object will be created to remove duplication of that object.

Added workflow response object to exchanges.yml

3db50f9

Replace workflowId in request/response and returned a workflow object.

PatStLouis requested review from msporny, mavarley and mkhraisha as code owners August 6, 2024 19:33

PatStLouis requested a review from dlongley August 6, 2024 19:33

TallTed suggested changes Aug 6, 2024

View reviewed changes

exchanges.yml Outdated Show resolved Hide resolved

dlongley reviewed Aug 6, 2024

View reviewed changes

Update exchanges.yml

a670049

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

PatStLouis commented Aug 8, 2024

View reviewed changes

Update exchanges.yml

5efdafd

msporny reviewed Aug 13, 2024

View reviewed changes

PatStLouis added 2 commits August 20, 2024 14:38

Remove stepInformation property from workflow config

3f91229

Replace occurences of workflowData with config

9ee8ff9

dlongley reviewed Aug 20, 2024

View reviewed changes

msporny merged commit c12c194 into w3c-ccg:main Aug 20, 2024
1 check passed

PatStLouis mentioned this pull request Aug 20, 2024

Create WorkflowConfig object to re-use across API calls #413

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added workflow response object to workflow creation call #409

Added workflow response object to workflow creation call #409

PatStLouis commented Aug 6, 2024

dlongley Aug 6, 2024

PatStLouis Aug 8, 2024

dlongley Aug 8, 2024

dlongley Aug 6, 2024

dlongley Aug 6, 2024 •

edited

Loading

PatStLouis Aug 8, 2024

PatStLouis left a comment

PatStLouis Aug 8, 2024

msporny Aug 13, 2024

msporny Aug 13, 2024

msporny Aug 13, 2024

dlongley Aug 20, 2024

dlongley Aug 20, 2024

dlongley Aug 20, 2024

dlongley Aug 20, 2024

msporny commented Aug 20, 2024

	properties:
	steps:
	type: object
	description: One or more steps required to complete an exchange on the workflow. Passing the steps object is REQUIRED.
	properties:
	stepName:
	type: object
	description: The name of the step.
	properties:
	step:
	$ref: "#/components/schemas/WorkflowStep"
	initialStep:
	type: string
	description: The step from the above set that the exchange starts on. Passing intialStep is REQUIRED.
	controller:
	type: string
	description: The controller of the instance. Passing controller is OPTIONAL.
	authorization:
	type: string
	description: Authorization scheme information (e.g., OAuth2 configuration). Passing authorization is OPTIONAL.
	credentialTemplates:
	type: array
	description: One or more VC templates for issuance. Passing credentialTemplates is OPTIONAL.
	items:
	type: object
	properties:
	type:
	type: string
	template:
	type: string
	id:
	type: string
	description: The ID that will be used for the created workflow. Passing an ID is OPTIONAL.

Added workflow response object to workflow creation call #409

Added workflow response object to workflow creation call #409

Conversation

PatStLouis commented Aug 6, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dlongley Aug 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PatStLouis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

msporny commented Aug 20, 2024

dlongley Aug 6, 2024 •

edited

Loading