feat(orchestrator): add support for selectors in SchemaUpdater (#1006)

Signed-off-by: Marek Libra <marek.libra@gmail.com>

Author: mareklibra

workspaces/orchestrator/.changeset/fresh-gorillas-know.md

@@ -0,0 +1,5 @@
+---
+'@red-hat-developer-hub/backstage-plugin-orchestrator-form-widgets': patch
+---
+
+Add support for selectors in SchemaUpdater. A complex response can be narrowed by the selector to produce the object structure as desired by the SchemaUpdater.

workspaces/orchestrator/docs/orchestratorFormWidgets.md

@@ -39,7 +39,7 @@ A headless widget used for fetching snippets of JSON schema and dynamically upda
 
 Thanks to this component, complex subparts of the form can be changed based on data entered in other fields by the user.
 
-Example of use in workflow's input data schema:
+### Example of the SchemaUpdater use in workflow's input data schema
 
 ```json
 {
@@ -67,6 +67,8 @@ Example of use in workflow's input data schema:
 }
 ```
 
+### Expected response for the SchemaUpdater
+
 The response of `fetch:url` endpoint is expected to be a JSON document conforming structure defined by the `SchemaChunksResponse` type.
 
 Considering the data-input schema structure above, the response can look like:
@@ -86,10 +88,15 @@ Considering the data-input schema structure above, the response can look like:
 }
 ```
 
-Please note: The response must be a single JSON object whose property names correspond to the identifiers defined in the data-input JSON Schema.
+Please note: The response must be
+
+- a single JSON object
+- whose property names correspond to the identifiers defined in the data-input JSON Schema
+- and values are valid replacements for the UI schema.
 
-A provided snipped can be of `"type": "object"` and so inject/replace fields for a complex data structure.
-Additional `SchemaUpdater` widgets can be instantiated this way as well.
+A provided snipped can be of `"type": "object"` and so inject/replace fields for a complex data structure, so the use is not limited to just a single string or numeric properties.
+
+**Additional `SchemaUpdater` widgets can be instantiated this way as well.**
 
 The `SchemaUpdater` widget scans for the identifiers, the top-level property names in the response, and replaces any matching ones with the corresponding values from the response.
 Identifiers that do not exist in the current schema are ignored.
@@ -100,14 +107,71 @@ You can instantiate multiple `SchemaUpdater` widgets simultaneously. It is up to
 
 It is highly recommended that endpoints are implemented as stateless and free from side effects, consistently returning the same response for identical input sets.
 
-### SchmeaUpdater widget ui:props
+### Using selector to narrow complex response in SchemaUpdater
+
+As stated above, the `SchemaUpdater` expects a single object of the desired structure as its input.
+
+If the response does not meet that condition, meaning it contains additional data or the structure is malformed, the `fetch:response:value` selector can be used to pick-up a single object in the desired format.
+
+Example complex HTTP response:
+
+```json
+{
+  "foo": "bar",
+  "prop1": {
+    "subprop": "a lot of complex but useless stuff"
+  },
+  "mydataroot": {
+    "mydata": {
+      "sendCertificatesAs": {
+        "type": "string",
+        "title": "Send certificates via",
+        "ui:widget": "ActiveText",
+        "ui:props": {
+          "ui:variant": "caption",
+          "ui:text": "This course does not provide certificate"
+        }
+      }
+    }
+  }
+}
+```
+
+For the schema:
+
+```json
+{
+  "properties": {
+    ...
+     "sendCertificatesAs": {
+      "type": "object",
+      "title": "This title will never be displayed. Will be managed by the 'mySchemaUpdaterForCertificates'.",
+      "ui:widget": "hidden"
+    },
+    "mySchemaUpdaterForCertificates": {
+      "type": "string",
+      "title": "This title will never be displayed.",
+      "ui:widget": "SchemaUpdater",
+      "ui:props": {
+        "fetch:url": "$${{backend.baseUrl}}/api/proxy/mytesthttpserver/certificatesschema",
+        "fetch:response:value": "mydataroot.mydata",
+        ...
+      }
+    },
+    ...
+  }
+}
+```
+
+### SchemaUpdater widget ui:props
 
 The widget supports following `ui:props`:
 
 - fetch:url
 - fetch:headers
 - fetch:method
 - fetch:body
+- fetch:response:value
 - fetch:retrigger
 
 [Check mode details](#content-of-uiprops)

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/utils/applySelector.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 import jsonata from 'jsonata';
-import { JsonObject } from '@backstage/types';
+import { JsonObject, JsonValue } from '@backstage/types';
+
+export function isJsonObject(value?: JsonValue): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 
 export const applySelectorArray = async (
   data: JsonObject,
@@ -28,7 +32,7 @@ export const applySelectorArray = async (
   }
 
   throw new Error(
-    `Unexpected result of "${selector}" selector, expected string[] type. Value "${value}"`,
+    `Unexpected result of "${selector}" selector, expected string[] type. Value "${JSON.stringify(value)}"`,
   );
 };
 
@@ -44,6 +48,22 @@ export const applySelectorString = async (
   }
 
   throw new Error(
-    `Unexpected result of "${selector}" selector, expected string type. Value "${value}"`,
+    `Unexpected result of "${selector}" selector, expected string type. Value "${JSON.stringify(value)}"`,
+  );
+};
+
+export const applySelectorObject = async (
+  data: JsonObject,
+  selector: string,
+): Promise<JsonObject> => {
+  const expression = jsonata(selector);
+  const value = await expression.evaluate(data);
+
+  if (isJsonObject(value)) {
+    return value;
+  }
+
+  throw new Error(
+    `Unexpected result of "${selector}" selector, expected object type. Value "${JSON.stringify(value)}"`,
   );
 };

workspaces/orchestrator/plugins/orchestrator-form-widgets/src/widgets/SchemaUpdater.tsx

@@ -27,6 +27,7 @@ import {
   useRetriggerEvaluate,
   useTemplateUnitEvaluator,
   useFetch,
+  applySelectorObject,
 } from '../utils';
 import { ErrorText } from './ErrorText';
 import { UiProps } from '../uiPropTypes';
@@ -47,6 +48,8 @@ export const SchemaUpdater: Widget<
     () => (props.options?.props ?? {}) as UiProps,
     [props.options?.props],
   );
+  const valueSelector = uiProps['fetch:response:value']?.toString();
+
   const [localError, setLocalError] = useState<string>();
 
   const retrigger = useRetriggerEvaluate(
@@ -68,27 +71,39 @@ export const SchemaUpdater: Widget<
       return;
     }
 
-    const typedData = data as unknown as SchemaChunksResponse;
+    const doItAsync = async () => {
+      let typedData: SchemaChunksResponse =
+        data as unknown as SchemaChunksResponse;
+      if (valueSelector) {
+        typedData = (await applySelectorObject(
+          data,
+          valueSelector,
+        )) as unknown as SchemaChunksResponse;
+      }
+
+      // validate received response before updating
+      Object.keys(typedData).forEach(key => {
+        if (!typedData[key]?.type) {
+          // eslint-disable-next-line no-console
+          console.error('JSON response malformed: ', typedData);
+          setLocalError(
+            `JSON response malformed for SchemaUpdater, missing "type" field for "${key}" key.`,
+          );
+        }
+      });
 
-    // validate received response before updating
-    Object.keys(typedData).forEach(key => {
-      if (!typedData[key]?.type) {
+      try {
+        updateSchema(typedData);
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error('Error when updating schema', props.id, err);
         setLocalError(
-          `JSON response malformed for SchemaUpdater, missing "type" field for "${key}" key.`,
+          `Failed to update schema update by the ${props.id} SchemaUpdater`,
         );
       }
-    });
-
-    try {
-      updateSchema(typedData);
-    } catch (err) {
-      // eslint-disable-next-line no-console
-      console.error('Error when updating schema', props.id, err);
-      setLocalError(
-        `Failed to update schema update by the ${props.id} SchemaUpdater`,
-      );
-    }
-  }, [data, props.id, updateSchema]);
+    };
+    doItAsync();
+  }, [data, props.id, updateSchema, valueSelector]);
 
   if (localError ?? error) {
     return <ErrorText text={localError ?? error ?? ''} id={id} />;