fix(servicenow): keep help_text in Get Catalog Item Variables

components/servicenow/actions/add-item-to-cart/add-item-to-cart.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-add-item-to-cart",
   name: "Add Item to Cart",
   description: "Add a ServiceNow catalog item to the current user's cart. Run **Search Catalog Items** to find the item `sys_id` and **Get Catalog Item Variables** to learn which variable names to supply. After adding items, use **View Cart**, then **Checkout Cart** or **Submit Cart Order** to submit. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_ServiceCatalogAPI.html)",
-  version: "0.0.5",
+  version: "0.0.6",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/check-order-status/check-order-status.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-check-order-status",
   name: "Check Order Status",
   description: "Retrieve the status of a ServiceNow catalog request (REQ) from the `sc_request` table, including request state, approval, and stage. Provide the request number returned by **Checkout Cart**, **Submit Cart Order**, or **Order Catalog Item**. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html)",
-  version: "0.0.5",
+  version: "0.0.6",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/checkout-order-guide/checkout-order-guide.mjs

@@ -8,7 +8,7 @@ export default {
   key: "servicenow-checkout-order-guide",
   name: "Checkout Order Guide",
   description: "Checkout a ServiceNow order guide using the items returned by **Submit Order Guide**. Pass those items as-is — this action maps `quantity` to `sysparm_quantity` and array `variables` (including nested `children`) to an object. Fill unanswered mandatory item variables in `items` first, and omit optional blank ones. If the order guide's Two step flag is on, this submits the order and returns the REQ number and `sys_id`. If the flag is off, items are added to the user's default cart and no REQ is returned — review with **View Cart**, then call **Submit Cart Order**. Use **Check Order Status** after a REQ exists. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_ServiceCatalogAPI.html)",
-  version: "0.0.2",
+  version: "0.0.3",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/create-table-record/create-table-record.mjs

@@ -5,13 +5,14 @@ export default {
   key: "servicenow-create-table-record",
   name: "Create Table Record",
   description: "Inserts one record in the specified table. [See the documentation](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/c_TableAPI.html#title_table-POST)",
-  version: "1.0.7",
+  version: "1.0.8",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: false,
   },
   type: "action",
+  ai: "optimized",
   props: {
     servicenow,
     table: {

components/servicenow/actions/find-users/find-users.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-find-users",
   name: "Find Users",
   description: "Search ServiceNow `sys_user` records to find a user's `sys_id` (used by props like the requested-for field on **Add Item to Cart**). Choose whether to match on name (partial) or email (exact). [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html)",
-  version: "0.0.5",
+  version: "0.0.6",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/get-catalog-item-variables/get-catalog-item-variables.mjs

@@ -4,8 +4,8 @@ import { describeCatalogVariables } from "../../common/utils.mjs";
 export default {
   key: "servicenow-get-catalog-item-variables",
   name: "Get Catalog Item Variables",
-  description: "Retrieve the ordered variables (form fields) for a ServiceNow catalog item or record producer, with where each field's valid values come from. Run **Search Catalog Items** first to obtain the item `sys_id`, then use the returned variable `name`s to build the `variables` payload for **Add Item to Cart**, **Order Catalog Item**, or **Submit Record Producer**. Supply a value for each variable whose `mandatory` is `true`; optional variables can be left out. Each choice-based variable has an `options` object: when `options.source` is `choices`, pick a `value` from the inline `choices` (lookup choices are already filtered by ServiceNow for the signed-in user); when it is `table`, run **Get Table Records** on `options.table` with `options.query` (if present) plus the user's search text and submit the record `sys_id`. `options.qualifier_unresolved: true` means the form filters this field with a script (`options.qualifier_script`) that cannot be evaluated here: do not reimplement the script with other queries or state which records it allows, tell the user the valid choices are decided by the form, and confirm the value they want; `options.depends_on` lists variables whose values change the valid options. Script defaults such as the current user are resolved into `value`, with the original script in `default_script`. When `default_unresolved` is `true`, `value` is empty: ask the user for the value instead of submitting `default_script`. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_ServiceCatalogAPI.html)",
-  version: "0.0.7",
+  description: "Retrieve the ordered variables (form fields) for a ServiceNow catalog item or record producer, with where each field's valid values come from. Run **Search Catalog Items** first to obtain the item `sys_id`, then use the returned variable `name`s to build the `variables` payload for **Add Item to Cart**, **Order Catalog Item**, or **Submit Record Producer**. Supply a value for each variable whose `mandatory` is `true`; optional variables can be left out. Each choice-based variable has an `options` object: when `options.source` is `choices`, pick a `value` from the inline `choices` (lookup choices are already filtered by ServiceNow for the signed-in user); when it is `table`, run **Get Table Records** on `options.table` with `options.query` (if present) plus the user's search text and submit the record `sys_id`. `options.qualifier_unresolved: true` means the form filters this field with a script (`options.qualifier_script`) that cannot be evaluated here: do not reimplement the script with other queries or state which records it allows, tell the user the valid choices are decided by the form, and confirm the value they want; `options.depends_on` lists variables whose values change the valid options. A non-empty `help_text` is the guidance ServiceNow shows under the field (it may contain HTML entities); show it to the user when asking for that value. Script defaults such as the current user are resolved into `value`, with the original script in `default_script`. When `default_unresolved` is `true`, `value` is empty: ask the user for the value instead of submitting `default_script`. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_ServiceCatalogAPI.html)",
+  version: "0.0.8",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/get-catalog-ui-policies/get-catalog-ui-policies.mjs

@@ -13,7 +13,7 @@ export default {
   key: "servicenow-get-catalog-ui-policies",
   name: "Get Catalog UI Policies",
   description: "Retrieve catalog UI policy actions for a ServiceNow catalog item from `catalog_ui_policy_action` (visibility, mandatory, and read-only rules). Each action includes its parent `catalog_ui_policy` record, including `catalog_conditions`. Run **Search Catalog Items** first to obtain the item `sys_id`. Use with **Get Catalog Item Variables** when building a form, then **Add Item to Cart** or **Checkout Order Guide**. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html)",
-  version: "0.0.2",
+  version: "0.0.3",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/get-incident/get-incident.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-get-incident",
   name: "Get Incident",
   description: "Retrieve a ServiceNow incident from the `incident` table by number. Use this after **Submit Record Producer** or **Create Table Record** when you need the incident state, priority, and assignment for a follow-up link. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html)",
-  version: "0.0.2",
+  version: "0.0.3",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/get-question-choices/get-question-choices.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-get-question-choices",
   name: "Get Question Choices",
   description: "Retrieve select-box choices for a ServiceNow catalog variable from the `question_choice` table, including inactive-filtered ordering. Prefer the inline `choices` from **Get Catalog Item Variables**: reading `question_choice` usually requires a catalog admin role, so most signed-in employees get a 403 here. Pass the variable `sys_id` (or `id`) from **Get Catalog Item Variables**. For table-backed reference variables, use **Get Table Records** on the variable's `options.table` instead. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html)",
-  version: "0.0.2",
+  version: "0.0.3",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/get-requested-items/get-requested-items.mjs

@@ -6,7 +6,7 @@ export default {
   key: "servicenow-get-requested-items",
   name: "Get Requested Items",
   description: "Retrieve requested items (RITMs) from the `sc_req_item` table for a catalog request. Provide the request number returned by **Checkout Cart**, **Submit Cart Order**, **Order Catalog Item**, or **Checkout Order Guide**. Use this after checkout to get RITM numbers and states for follow-up links. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html)",
-  version: "0.0.2",
+  version: "0.0.3",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/order-catalog-item/order-catalog-item.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-order-catalog-item",
   name: "Order Catalog Item",
   description: "Place a one-step Order Now request for a single ServiceNow catalog item, bypassing the cart. Run **Search Catalog Items** to find the item `sys_id` and **Get Catalog Item Variables** to learn which variable names to supply. Use **Check Order Status** afterward to track the resulting request. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_ServiceCatalogAPI.html)",
-  version: "0.0.5",
+  version: "0.0.6",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/search-configuration-items/search-configuration-items.mjs

@@ -6,7 +6,7 @@ export default {
   key: "servicenow-search-configuration-items",
   name: "Search Configuration Items",
   description: "Search ServiceNow CMDB configuration items in `cmdb_ci` by name. Use this for assigned-asset lookup after **Find Users** (pass that user's `sys_id` as **Assigned To**). Then read a specific CI with **Get Table Record By ID**. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html)",
-  version: "0.0.2",
+  version: "0.0.3",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/submit-order-guide/submit-order-guide.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-submit-order-guide",
   name: "Submit Order Guide",
   description: "Run the ServiceNow order-guide rule base and return the selected catalog items plus their variable schemas. Run **Search Catalog Items** to find the order-guide `sys_id` and **Get Catalog Item Variables** for guide-level field names. Pass the returned items to **Checkout Order Guide**. If checkout does not return a REQ, the guide's Two step flag is off: review with **View Cart**, then call **Submit Cart Order**. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_ServiceCatalogAPI.html)",
-  version: "0.0.2",
+  version: "0.0.3",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/submit-record-producer/submit-record-producer.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-submit-record-producer",
   name: "Submit Record Producer",
   description: "Submit a ServiceNow record producer to create the target record (e.g. an incident or RITM) from catalog variables. Run **Search Catalog Items** to find the record producer `sys_id` and **Get Catalog Item Variables** to learn which variable names to supply. [See the documentation](https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_ServiceCatalogAPI.html)",
-  version: "0.0.7",
+  version: "0.0.8",
   type: "action",
   ai: "optimized",
   annotations: {

components/servicenow/actions/update-table-record/update-table-record.mjs

@@ -5,7 +5,7 @@ export default {
   key: "servicenow-update-table-record",
   name: "Update Table Record",
   description: "Updates the specified record with the name-value pairs included in the request body. [See the documentation](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/c_TableAPI.html#title_table-PATCH)",
-  version: "1.0.8",
+  version: "1.0.9",
   annotations: {
     destructiveHint: true,
     openWorldHint: true,

components/servicenow/common/constants.mjs

@@ -38,6 +38,13 @@ const CATALOG_UI_POLICY_ACTION_TABLE = "catalog_ui_policy_action";
 const KNOWLEDGE_BASE_TABLE = "kb_knowledge_base";
 const MAX_LIMIT = 1000;
 
+// The field guidance ServiceNow shows under a catalog variable. Kept only when
+// set: most variables have none, and an empty string per field would undo the
+// trim in `describeCatalogVariables`.
+const DESCRIBED_TEXT_FIELDS = [
+  "help_text",
+];
+
 export default {
   DEFAULT_SEVERITY_OPTIONS,
   INCIDENT_SEVERITY_OPTIONS,
@@ -53,4 +60,5 @@ export default {
   CATALOG_UI_POLICY_ACTION_TABLE,
   KNOWLEDGE_BASE_TABLE,
   MAX_LIMIT,
+  DESCRIBED_TEXT_FIELDS,
 };

components/servicenow/common/utils.mjs

@@ -1,4 +1,5 @@
 import { ConfigurationError } from "@pipedream/platform";
+import constants from "./constants.mjs";
 
 export function parseObject(value) {
   if (!value) return undefined;
@@ -160,6 +161,14 @@ const DESCRIBED_VARIABLE_FIELDS = [
   "choices",
 ];
 
+/**
+ * Trim one catalog variable (and its children) to the fields an agent needs,
+ * and attach an `options` descriptor for choice-based types.
+ * @param {object} variable - A variable from the Service Catalog `/variables` response
+ * @param {object[]} scriptDefaults - Collects described reference variables whose
+ *   default is a `javascript:` script, for the caller to resolve
+ * @returns {object} The described variable
+ */
 function describeVariable(variable, scriptDefaults) {
   const type = Number(variable.type);
   const described = {};
@@ -168,6 +177,11 @@ function describeVariable(variable, scriptDefaults) {
       described[field] = variable[field];
     }
   }
+  for (const field of constants.DESCRIBED_TEXT_FIELDS) {
+    if (typeof variable[field] === "string" && variable[field].trim()) {
+      described[field] = variable[field];
+    }
+  }
 
   if (Array.isArray(variable.children)) {
     described.children = variable.children.map((child) =>
@@ -227,10 +241,11 @@ function describeVariable(variable, scriptDefaults) {
  * them in a Table API query, so they are flagged with `qualifier_unresolved`
  * rather than returned as `query`. Only the fields an agent needs to fill the
  * form are kept (`id`, `name`, `label`, `type`, `mandatory`, `value`,
- * `choices`, `children`, `options` and the default flags); form-rendering
- * metadata such as list collector `columns` is dropped. Reference variables
- * whose default is a `javascript:` script are returned in `scriptDefaults`,
- * with the referenced table in `options.table`, for the caller to resolve.
+ * `choices`, `children`, `options`, a non-empty `help_text` and the default
+ * flags); form-rendering metadata such as list collector `columns` is dropped.
+ * Reference variables whose default is a `javascript:` script are returned in
+ * `scriptDefaults`, with the referenced table in `options.table`, for the
+ * caller to resolve.
  */
 export function describeCatalogVariables(variables) {
   const scriptDefaults = [];

components/servicenow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/servicenow",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "Pipedream ServiceNow Components",
   "main": "servicenow.app.mjs",
   "keywords": [