@oneuptime/common 12.0.33 → 12.0.34

package/Types/CustomField/CustomFieldMappingCatalog.ts

@@ -0,0 +1,161 @@
+import CustomFieldMappingSourceResource from "./CustomFieldMappingSourceResource";
+
+/*
+ * WHICH RESOURCE PAIRS CAN MAP, in a form both the browser and the server can
+ * read.
+ *
+ * Custom field definitions live in nine sibling tables and the values they
+ * describe live in a `customFields` jsonb bag on nine different resources.
+ * Nothing in the codebase previously wrote down the pairing between the two,
+ * let alone which resource is reachable from which — that knowledge was
+ * spread across ~19 JSX call sites. A "map this field's value from a related
+ * resource" feature needs it in exactly three places at once (the settings
+ * picker, the create-time resolver and the propagation fan-out), so it is
+ * stated once, here, in Types where App's React-free tsc can import it.
+ *
+ * Keyed by the TARGET definition table name (`new AlertCustomField().tableName`)
+ * because that is what a settings page has in hand.
+ *
+ * A resource is listed only when the target genuinely has a relation to it AND
+ * the source itself carries custom fields. Today that is Monitor, reachable
+ * from Alert (one monitor), Incident and Scheduled Maintenance (many). The six
+ * definition tables with no reachable source are absent rather than mapped to
+ * an empty array, so `getCustomFieldMappingSources` returning nothing is the
+ * same answer for "unknown table" and "no sources" — which is what the UI
+ * wants either way.
+ */
+export interface CustomFieldMappingSourceInfo {
+  resource: CustomFieldMappingSourceResource;
+  /** How the source is named to an operator, e.g. "Monitor". */
+  title: string;
+  /** Definition table listing the fields available on the source. */
+  sourceDefinitionTableName: string;
+  /**
+   * True when the target can be attached to several sources at once (an
+   * incident spans many monitors). Drives the wording of the settings help
+   * text, because the resolution rule differs — see resolveMappedCustomFieldValue.
+   */
+  isManySources: boolean;
+  /**
+   * Property on the TARGET record that holds the relation: the FK column for a
+   * single source, the relation array for many.
+   */
+  targetRelationProperty: string;
+  /**
+   * Keys the relation can arrive under in a create or update payload, FK
+   * spelling FIRST. The dashboard posts `{ monitor: { _id } }` while server
+   * callers write `{ monitorId }`, and hooks run before TypeORM resolves one
+   * into the other — see Common/Server/Utils/Database/RelationIdUtil.ts.
+   */
+  relationDataKeys: Array<string>;
+}
+
+const MONITOR_SOURCE: (
+  isManySources: boolean,
+) => CustomFieldMappingSourceInfo = (
+  isManySources: boolean,
+): CustomFieldMappingSourceInfo => {
+  return {
+    resource: CustomFieldMappingSourceResource.Monitor,
+    title: "Monitor",
+    sourceDefinitionTableName: "MonitorCustomField",
+    isManySources: isManySources,
+    targetRelationProperty: isManySources ? "monitors" : "monitorId",
+    relationDataKeys: isManySources ? ["monitors"] : ["monitorId", "monitor"],
+  };
+};
+
+const CUSTOM_FIELD_MAPPING_CATALOG: Record<
+  string,
+  Array<CustomFieldMappingSourceInfo>
+> = {
+  AlertCustomField: [MONITOR_SOURCE(false)],
+  IncidentCustomField: [MONITOR_SOURCE(true)],
+  ScheduledMaintenanceCustomField: [MONITOR_SOURCE(true)],
+};
+
+export type GetCustomFieldMappingSourcesFunction = (
+  definitionTableName: string | undefined,
+) => Array<CustomFieldMappingSourceInfo>;
+
+export const getCustomFieldMappingSources: GetCustomFieldMappingSourcesFunction =
+  (
+    definitionTableName: string | undefined,
+  ): Array<CustomFieldMappingSourceInfo> => {
+    if (!definitionTableName) {
+      return [];
+    }
+
+    return CUSTOM_FIELD_MAPPING_CATALOG[definitionTableName] || [];
+  };
+
+export type GetCustomFieldMappingSourceFunction = (data: {
+  definitionTableName: string | undefined;
+  resource: CustomFieldMappingSourceResource | string | undefined;
+}) => CustomFieldMappingSourceInfo | undefined;
+
+export const getCustomFieldMappingSource: GetCustomFieldMappingSourceFunction =
+  (data: {
+    definitionTableName: string | undefined;
+    resource: CustomFieldMappingSourceResource | string | undefined;
+  }): CustomFieldMappingSourceInfo | undefined => {
+    if (!data.resource) {
+      return undefined;
+    }
+
+    return getCustomFieldMappingSources(data.definitionTableName).find(
+      (source: CustomFieldMappingSourceInfo) => {
+        return source.resource === data.resource;
+      },
+    );
+  };
+
+export type GetCustomFieldMappingRelationSelectFunction = (
+  source: CustomFieldMappingSourceInfo,
+) => Record<string, unknown>;
+
+/**
+ * The `select` clause that pulls a source relation off a target record. Shared
+ * so the server resolver and the resource's Custom Fields card ask for the
+ * same shape and read it back the same way.
+ */
+export const getCustomFieldMappingRelationSelect: GetCustomFieldMappingRelationSelectFunction =
+  (source: CustomFieldMappingSourceInfo): Record<string, unknown> => {
+    return {
+      [source.targetRelationProperty]: source.isManySources
+        ? { _id: true }
+        : true,
+    };
+  };
+
+export type HasCustomFieldMappingSourceFunction = (data: {
+  source: CustomFieldMappingSourceInfo;
+  record: Record<string, unknown> | null | undefined;
+}) => boolean;
+
+/**
+ * Is this record actually attached to something to inherit from?
+ *
+ * A large and ordinary class of records is not: SLO burn-rate alerts,
+ * security-event alerts, network-site rollup alerts and AI-declared incidents
+ * are all created with no monitor. A mapped field on one of those can never be
+ * filled in automatically, so it stays hand-editable rather than becoming a
+ * permanently blank box the operator is locked out of.
+ */
+export const hasCustomFieldMappingSource: HasCustomFieldMappingSourceFunction =
+  (data: {
+    source: CustomFieldMappingSourceInfo;
+    record: Record<string, unknown> | null | undefined;
+  }): boolean => {
+    const value: unknown = (data.record || {})[
+      data.source.targetRelationProperty
+    ];
+
+    if (data.source.isManySources) {
+      return Array.isArray(value) && value.length > 0;
+    }
+
+    return Boolean(value);
+  };
+
+export default CUSTOM_FIELD_MAPPING_CATALOG;

package/Types/CustomField/CustomFieldMappingSourceResource.ts

@@ -0,0 +1,19 @@
+/*
+ * Which related resource a custom field copies its value from.
+ *
+ * A member here is only meaningful for a TARGET resource that actually has a
+ * relation to it — an Alert has one Monitor, an Incident has many — so the
+ * per-target list of usable sources lives in the server-side registry
+ * (Common/Server/Utils/CustomField/CustomFieldMappingRegistry.ts) rather than
+ * in this enum. The enum is the wire/storage vocabulary shared by the model
+ * column, the settings form and the resolver.
+ *
+ * Values are persisted in the `mapFromResourceType` column of every
+ * `*CustomField` definition table, so a member's VALUE is load-bearing: it
+ * cannot be renamed without a data migration.
+ */
+enum CustomFieldMappingSourceResource {
+  Monitor = "Monitor",
+}
+
+export default CustomFieldMappingSourceResource;

package/Types/CustomField/CustomFieldValueMapping.ts

@@ -0,0 +1,288 @@
+import { JSONObject } from "../JSON";
+import CustomFieldType from "./CustomFieldType";
+import {
+  CustomFieldDropdownOption,
+  parseCustomFieldDropdownOptions,
+} from "./CustomFieldDropdownOption";
+
+/*
+ * The pure half of "custom field value mapping" (issue #3549): given the
+ * values a target's source records hold for one field, what — if anything —
+ * should be written onto the target?
+ *
+ * Everything here is deliberately free of database and React imports so the
+ * rules can be unit-tested directly and so both the server resolver and the
+ * settings form can share one definition of "compatible" and "empty".
+ *
+ * THE ONE INVARIANT WORTH STATING UP FRONT: mapping is never destructive. It
+ * writes a value that exists on a source, or it writes nothing at all. It has
+ * no code path that clears a key. That is what makes turning a mapping on
+ * safe on a project that has been filling the field in by hand for a year:
+ * the worst case is that some rows are not filled yet, never that a value is
+ * lost. The cost is that clearing the source does not clear the copies — said
+ * plainly in the settings help text rather than papered over.
+ */
+
+/*
+ * A single configured mapping, narrowed to what the resolver needs.
+ * `targetFieldName` and `sourceFieldName` are the definitions' `name` values,
+ * because the `customFields` bag is keyed by name (see the header comment on
+ * Common/UI/Components/ModelTable/CustomFieldColumns.tsx).
+ */
+export interface CustomFieldValueMapping {
+  targetFieldName: string;
+  sourceFieldName: string;
+  targetFieldType?: CustomFieldType | undefined;
+}
+
+export type IsCustomFieldValueEmptyFunction = (value: unknown) => boolean;
+
+/*
+ * The house definition of "this field holds nothing", lifted verbatim from
+ * InventoryEntityRegistry.hasCustomFieldValues so the two cannot drift.
+ *
+ * Note what is NOT empty: `false` and `0`. A Boolean custom field set to No
+ * stores a real `false` (BasicForm forces it when unset), and a Number field
+ * set to zero stores "0" — a falsy check would treat both as absent and, in a
+ * design that cleared absent values, would invert their meaning.
+ */
+export const isCustomFieldValueEmpty: IsCustomFieldValueEmptyFunction = (
+  value: unknown,
+): boolean => {
+  if (value === undefined || value === null || value === "") {
+    return true;
+  }
+
+  return Array.isArray(value) && value.length === 0;
+};
+
+/*
+ * Canonical form used to decide whether two source values are "the same
+ * answer". Arrays are order-insensitive because a MultiSelectDropdown holding
+ * ["a","b"] and ["b","a"] is one value, and treating them as two would make an
+ * incident's mapped field oscillate between syncs.
+ */
+type CanonicalizeFunction = (value: unknown) => string;
+
+const canonicalize: CanonicalizeFunction = (value: unknown): string => {
+  if (Array.isArray(value)) {
+    return JSON.stringify(
+      [...value]
+        .map((entry: unknown) => {
+          return String(entry);
+        })
+        .sort(),
+    );
+  }
+
+  return JSON.stringify(value ?? null);
+};
+
+export interface ResolvedCustomFieldValue {
+  /*
+   * False means "write nothing". It covers every one of: no source record,
+   * no source value, and sources that disagree. The caller must not turn a
+   * false into a delete.
+   */
+  hasValue: boolean;
+  value?: unknown;
+}
+
+export type ResolveMappedCustomFieldValueFunction = (data: {
+  /*
+   * One entry per source record, in whatever order the caller found them.
+   * Order must not affect the answer — the ManyToMany monitor relations carry
+   * no ORDER BY, so "the first monitor" is not a stable concept.
+   */
+  sourceValues: Array<unknown>;
+  targetFieldType?: CustomFieldType | undefined;
+}) => ResolvedCustomFieldValue;
+
+/*
+ * How several sources collapse into one value.
+ *
+ * - Nothing non-empty -> write nothing.
+ * - All non-empty sources agree -> that value.
+ * - They disagree, and the target is multi-select -> the sorted union, which
+ *   is the honest answer for a field that can hold several values and mirrors
+ *   what IncidentLabelRuleEngineService does with labels.
+ * - They disagree and the target holds one value -> write nothing. Picking a
+ *   winner would be arbitrary, and an arbitrary winner over an unordered
+ *   relation is a value that changes on its own.
+ */
+export const resolveMappedCustomFieldValue: ResolveMappedCustomFieldValueFunction =
+  (data: {
+    sourceValues: Array<unknown>;
+    targetFieldType?: CustomFieldType | undefined;
+  }): ResolvedCustomFieldValue => {
+    const presentValues: Array<unknown> = data.sourceValues.filter(
+      (value: unknown) => {
+        return !isCustomFieldValueEmpty(value);
+      },
+    );
+
+    if (presentValues.length === 0) {
+      return { hasValue: false };
+    }
+
+    const distinct: Map<string, unknown> = new Map<string, unknown>();
+
+    for (const value of presentValues) {
+      const key: string = canonicalize(value);
+
+      if (!distinct.has(key)) {
+        distinct.set(key, value);
+      }
+    }
+
+    if (distinct.size === 1) {
+      return { hasValue: true, value: presentValues[0] };
+    }
+
+    if (data.targetFieldType === CustomFieldType.MultiSelectDropdown) {
+      const union: Set<string> = new Set<string>();
+
+      for (const value of presentValues) {
+        if (Array.isArray(value)) {
+          for (const entry of value) {
+            union.add(String(entry));
+          }
+        } else {
+          union.add(String(value));
+        }
+      }
+
+      return { hasValue: true, value: [...union].sort() };
+    }
+
+    return { hasValue: false };
+  };
+
+export interface MergedCustomFields {
+  customFields: JSONObject;
+  /*
+   * False lets every caller skip the write entirely — which is what keeps a
+   * monitor edit from issuing an UPDATE against thousands of rows that
+   * already hold the right answer.
+   */
+  hasChanged: boolean;
+}
+
+export type MergeMappedCustomFieldValuesFunction = (data: {
+  existingCustomFields: JSONObject | undefined | null;
+  /* Keyed by the TARGET field name. Only keys present here are touched. */
+  resolvedValues: JSONObject;
+}) => MergedCustomFields;
+
+/*
+ * Fold resolved values into a bag, leaving every other key exactly as it was.
+ * Returned bag is always a new object: callers write it straight into a
+ * `customFields` column, and sharing the caller's object would let a later
+ * mutation change a row that was already persisted.
+ */
+export const mergeMappedCustomFieldValues: MergeMappedCustomFieldValuesFunction =
+  (data: {
+    existingCustomFields: JSONObject | undefined | null;
+    resolvedValues: JSONObject;
+  }): MergedCustomFields => {
+    const merged: JSONObject = {
+      ...((data.existingCustomFields as JSONObject) || {}),
+    };
+
+    let hasChanged: boolean = false;
+
+    for (const targetFieldName of Object.keys(data.resolvedValues)) {
+      const nextValue: unknown = data.resolvedValues[targetFieldName];
+
+      if (canonicalize(merged[targetFieldName]) === canonicalize(nextValue)) {
+        continue;
+      }
+
+      merged[targetFieldName] = nextValue as JSONObject[string];
+      hasChanged = true;
+    }
+
+    return { customFields: merged, hasChanged: hasChanged };
+  };
+
+export type GetCustomFieldMappingCompatibilityErrorFunction = (data: {
+  targetFieldType?: CustomFieldType | undefined;
+  sourceFieldType?: CustomFieldType | undefined;
+  targetDropdownOptions?: string | undefined;
+  sourceDropdownOptions?: string | undefined;
+  sourceFieldName: string;
+}) => string | null;
+
+/*
+ * Why both sides are checked, and why dropdown OPTIONS are checked too:
+ *
+ * Nothing on the server validates a custom field value against its
+ * definition, so a mapped value that is not one of the target's options is
+ * accepted, stored, rendered as an uncoloured badge, and — because the facet
+ * chip's option list is built from the TARGET definition — cannot be filtered
+ * for. Copying "AWS" out of a monitor dropdown into an alert dropdown offering
+ * only "Acme"/"Globex" produces exactly that. Catching it when the mapping is
+ * saved is the only moment a human is present to fix it.
+ *
+ * A field whose type is unset is rejected rather than assumed: the column is
+ * nullable, and `undefined === undefined` would otherwise let any two
+ * untyped fields map onto each other and any value flow between them.
+ */
+export const getCustomFieldMappingCompatibilityError: GetCustomFieldMappingCompatibilityErrorFunction =
+  (data: {
+    targetFieldType?: CustomFieldType | undefined;
+    sourceFieldType?: CustomFieldType | undefined;
+    targetDropdownOptions?: string | undefined;
+    sourceDropdownOptions?: string | undefined;
+    sourceFieldName: string;
+  }): string | null => {
+    if (!data.targetFieldType) {
+      return "Please choose a field type before mapping this field's value from another resource.";
+    }
+
+    if (!data.sourceFieldType) {
+      return `The source field "${data.sourceFieldName}" does not have a field type set. Set its field type before mapping from it.`;
+    }
+
+    if (data.targetFieldType !== data.sourceFieldType) {
+      return `This field is a ${data.targetFieldType} field, but "${data.sourceFieldName}" is a ${data.sourceFieldType} field. Map from a field of the same type.`;
+    }
+
+    const isDropdown: boolean =
+      data.targetFieldType === CustomFieldType.Dropdown ||
+      data.targetFieldType === CustomFieldType.MultiSelectDropdown;
+
+    if (!isDropdown) {
+      return null;
+    }
+
+    const targetOptions: Set<string> = new Set<string>(
+      parseCustomFieldDropdownOptions(data.targetDropdownOptions).map(
+        (option: CustomFieldDropdownOption) => {
+          return option.value;
+        },
+      ),
+    );
+
+    const missingOptions: Array<string> = parseCustomFieldDropdownOptions(
+      data.sourceDropdownOptions,
+    )
+      .map((option: CustomFieldDropdownOption) => {
+        return option.value;
+      })
+      .filter((value: string) => {
+        return !targetOptions.has(value);
+      });
+
+    if (missingOptions.length === 0) {
+      return null;
+    }
+
+    return `"${data.sourceFieldName}" can hold ${missingOptions
+      .map((option: string) => {
+        return `"${option}"`;
+      })
+      .join(
+        ", ",
+      )}, which this field does not offer. Add those options here, or map from a different field.`;
+  };

package/Types/Icon/IconProp.ts

@@ -74,6 +74,7 @@ enum IconProp {
   Slack = "Slack",
   Time = "Time",
   Terminal = "Terminal",
+  Keyboard = "Keyboard",
   Drag = "Drag",
   GripVertical = "GripVertical",
   Error = "Error",