Frodo Library - v4.8.5
    Preparing search index...

    Type Alias ManagedObjectSchemaOps

    A managed-object type's schema is its resolved property/relationship definitions, readable in full via readManagedObjectSchema below — a read-only projection of the same underlying configuration IdmConfigOps.ts's readSubConfigEntity('managed', type) / importSubConfigEntity('managed', ...) read and write as a whole document. See ManagedObjectOps.ts's own header comment for how schema relates to managed-object records and configuration, the other two things this domain covers.

    Neither path is available on classic (AM-only) deployments at all — there is no IDM instance there, so neither the dedicated v2 API nor the generic config path below has anything to talk to. Both require a deployment that actually runs IDM (Cloud or ForgeOps); see assertIdmDeploymentForSchemaPropertyApi.

    There are two ways to mutate a type's schema on a deployment that does run IDM, and they are not interchangeable:

    1. readManagedObjectSchemaProperty / updateManagedObjectSchemaProperty / removeManagedObjectSchemaProperty below use IDM's dedicated v2 schema API, which is specifically for relationship-property definitions, one at a time, in place, with no whole-blob read-modify-write. This is a standard IDM REST API, introduced in IDM 7.5.0 (confirmed directly in IDM 7.5.0's own "New features" release notes, which link to this same endpoint) and present unchanged through IDM 8.1 — not Cloud-only, contrary to an earlier version of this comment, which wrongly assumed the API was Cloud-specific. Confirmed by directly comparing Ping's self-hosted PingIDM REST API reference (7.5 and 8.1) against the PingOne Advanced Identity Cloud REST API reference: identical endpoint (/openidm/schema/managed/{type}/ properties/{propertyName}), identical Accept-API-Version: resource=2.0 header, identical field shape (including reverseProperty), and no deployment restriction stated on either side. So this path specifically requires IDM 7.5+ (Cloud always qualifies; a ForgeOps deployment on an older IDM version would not, though Frodo has no way to detect that and doesn't attempt to — the deployment-type gate alone can't distinguish IDM versions within ForgeOps). See rockcarver/frodo-lib#388 for the original feature request (which itself doesn't claim Cloud-only either).
    2. For every other case — any non-relationship property, relationship properties on an IDM version that predates 7.5, and whole-type schema changes — use IdmConfigOps.ts's readSubConfigEntity('managed', type) / importSubConfigEntity('managed', ...) to read-modify-write the entire type definition (edit .schema.properties on the object you read before writing it back). This is the general-purpose path, available on any IDM version; #1 above is an optimization for one particular case on a sufficiently recent one, not the default.

    Neither path touches the underlying repository's index/persistence-layer definitions (e.g. DS's repo.ds on ForgeOps) — Frodo has no support for reading or writing repo.ds today, so adding a genuinely new custom relationship property on ForgeOps still requires a manual, Frodo-unassisted edit to that file outside either API above.

    type ManagedObjectSchemaOps = {
        createManagedObjectSchemaFlatProperty(
            type: string,
            propertyName: string,
            fields: ManagedObjectSchemaPropertyFields,
            subProperty?: string,
        ): Promise<Record<string, unknown>>;
        createManagedObjectSchemaRelationshipProperty(
            type: string,
            propertyName: string,
            fields: ManagedObjectSchemaRelationshipPropertyFields,
            reverse?: ManagedObjectSchemaRelationshipReverseFields,
        ): Promise<Record<string, unknown>>;
        createManagedObjectType(
            type: string,
            fields: ManagedObjectTypeFields,
        ): Promise<Record<string, unknown>>;
        readManagedObjectSchema(
            type: string,
            refreshCache?: boolean,
            options?: ManagedObjectSchemaOptions,
        ): Promise<ManagedObjectSchema>;
        readManagedObjectSchemaProperty(
            type: string,
            propertyName: string,
        ): Promise<ManagedObjectSchemaProperty>;
        readManagedObjectSchemaRelationshipPropertyOrNull(
            type: string,
            propertyName: string,
        ): Promise<Record<string, unknown>>;
        removeManagedObjectSchemaFlatProperty(
            type: string,
            propertyName: string,
            subProperty?: string,
        ): Promise<Record<string, unknown>>;
        removeManagedObjectSchemaProperty(
            type: string,
            propertyName: string,
        ): Promise<ManagedObjectSchemaProperty>;
        removeManagedObjectSchemaRelationshipProperty(
            type: string,
            propertyName: string,
            withReverse?: boolean,
        ): Promise<
            {
                current: Record<string, unknown>;
                reverse?: {
                    current: Record<string, unknown>;
                    propertyName: string;
                    type: string;
                };
            },
        >;
        removeManagedObjectType(type: string): Promise<void>;
        updateManagedObjectSchemaFlatProperty(
            type: string,
            propertyName: string,
            changedFields: Partial<ManagedObjectSchemaPropertyFields>,
            subProperty?: string,
        ): Promise<
            {
                current: Record<string, unknown>;
                propertyData: Record<string, unknown>;
            },
        >;
        updateManagedObjectSchemaProperty(
            type: string,
            propertyName: string,
            propertyData: ManagedObjectSchemaProperty,
        ): Promise<ManagedObjectSchemaProperty>;
        updateManagedObjectSchemaRelationshipProperty(
            type: string,
            propertyName: string,
            changedFields: Partial<ManagedObjectSchemaRelationshipPropertyFields>,
            withReverse?: boolean,
        ): Promise<
            {
                forward: Record<string, unknown>;
                reverse?: {
                    propertyData: Record<string, unknown>;
                    propertyName: string;
                    type: string;
                };
            },
        >;
        updateManagedObjectType(
            type: string,
            changedFields: Partial<ManagedObjectTypeFields>,
        ): Promise<
            { current: ManagedObjectTypeFields; proposed: ManagedObjectTypeFields },
        >;
    }
    Index

    Methods

    createManagedObjectSchemaFlatProperty createManagedObjectSchemaRelationshipProperty createManagedObjectType readManagedObjectSchema readManagedObjectSchemaProperty readManagedObjectSchemaRelationshipPropertyOrNull removeManagedObjectSchemaFlatProperty removeManagedObjectSchemaProperty removeManagedObjectSchemaRelationshipProperty removeManagedObjectType updateManagedObjectSchemaFlatProperty updateManagedObjectSchemaProperty updateManagedObjectSchemaRelationshipProperty updateManagedObjectType

    Methods

    • Create a flat (non-relationship) schema property on a managed object type -- or, with subProperty, nested inside an existing type: object property, as a dot-path relative to propertyName. Available on any deployment that runs IDM (Cloud and ForgeOps) -- unlike updateManagedObjectSchemaProperty, this goes through the generic readSubConfigEntity/importSubConfigEntity whole-type path, not the dedicated (relationship-only) v2 schema API, so it has no IDM 7.5+ requirement. Refuses (throws FrodoError) if the property already exists at that path -- use ManagedObjectSchemaOps.updateManagedObjectSchemaFlatProperty instead.

      Parameters

      • type: string

        managed object type, e.g. alpha_user or user

      • propertyName: string

        schema property name, e.g. custom_merchantId

      • fields: ManagedObjectSchemaPropertyFields

        the property's field values

      • OptionalsubProperty: string

        dot-path to nest the new property under an existing object property beneath propertyName, e.g. "address.street"

      Returns Promise<Record<string, unknown>>

      a promise that resolves to the written property definition

    • Create a new managed object type. Refuses (throws FrodoError) if a type with that name already exists -- use ManagedObjectSchemaOps.updateManagedObjectType instead. Seeds a minimal schema (just the _id property, a populated order array, and a default icon if fields.icon isn't given); custom properties/ relationships are added afterward via the flat-property/relationship- property paths, which already keep order/required in sync as they go.

      Parameters

      • type: string

        managed object type, e.g. alpha_widget

      • fields: ManagedObjectTypeFields

        the new type's field values (title required)

      Returns Promise<Record<string, unknown>>

      a promise that resolves to the written type schema

    • Read a single managed object relationship-property definition. Requires IDM 7.5+ (Cloud always qualifies) — uses IDM's dedicated v2 relationship-schema API to read one relationship-property definition without fetching the type's entire schema. For any non-relationship property, or on an IDM version that predates 7.5, use readSubConfigEntity('managed', type) and read the property off the returned schema.properties instead. Neither path is reachable on classic (AM-only, no IDM at all).

      Parameters

      • type: string

        managed object type, e.g. alpha_user or user

      • propertyName: string

        schema property name, e.g. custom_merchantId

      Returns Promise<ManagedObjectSchemaProperty>

      a promise that resolves to the property definition

    • Read a single relationship schema property, returning null (rather than throwing) if it doesn't exist. A confirmed 404 from the dedicated v2 API reliably means the property itself doesn't exist; any other failure propagates rather than being silently treated as "not found".

      Parameters

      • type: string

        managed object type, e.g. alpha_aiagentprivilege

      • propertyName: string

        relationship property name, e.g. agent

      Returns Promise<Record<string, unknown>>

      a promise that resolves to the property definition, or null if not found

    • Remove a flat (non-relationship) schema property from a managed object type -- or, with subProperty, a nested property reached via that dot-path. See ManagedObjectSchemaOps.createManagedObjectSchemaFlatProperty for the deployment/API-path notes. Refuses (throws FrodoError) if the property doesn't exist at that path.

      Parameters

      • type: string

        managed object type, e.g. alpha_user or user

      • propertyName: string

        schema property name, e.g. custom_merchantId

      • OptionalsubProperty: string

        dot-path to a nested property beneath propertyName, e.g. "address.street"

      Returns Promise<Record<string, unknown>>

      a promise that resolves to the removed property definition

    • Remove a relationship schema property, via IDM's dedicated v2 schema API. withReverse infers the reverse side from the forward property's own current definition and deletes it first, then the forward side. Deleting the reverse side of a bidirectionally-auto-created pair cascades and removes the forward side too, confirmed live -- a 404 on the forward-side delete immediately after a withReverse reverse-side delete means the desired end state (both sides gone) was already reached, and is treated as success, not surfaced as an error.

      Parameters

      • type: string

        managed object type, e.g. alpha_aiagentprivilege

      • propertyName: string

        relationship property name, e.g. agent

      • OptionalwithReverse: boolean

        true to also delete the inferred reverse side

      Returns Promise<
          {
              current: Record<string, unknown>;
              reverse?: {
                  current: Record<string, unknown>;
                  propertyName: string;
                  type: string;
              };
          },
      >

      a promise that resolves to the removed definition(s)

    • Remove a managed object type's entire definition (schema included). No separate existence pre-check -- the underlying config write already throws its own not-found error if the type is missing, so a second read here would be a redundant round trip.

      Parameters

      • type: string

        managed object type, e.g. alpha_widget

      Returns Promise<void>

      a promise that resolves when the type has been removed

    • Update an existing flat (non-relationship) schema property on a managed object type -- or, with subProperty, a nested property reached via that dot-path. Only the fields present in changedFields change; everything else keeps its current value. See ManagedObjectSchemaOps.createManagedObjectSchemaFlatProperty for the deployment/API-path notes. Refuses (throws FrodoError) if the property doesn't exist at that path -- use ManagedObjectSchemaOps.createManagedObjectSchemaFlatProperty instead.

      Parameters

      • type: string

        managed object type, e.g. alpha_user or user

      • propertyName: string

        schema property name, e.g. custom_merchantId

      • changedFields: Partial<ManagedObjectSchemaPropertyFields>

        only the field overrides to apply

      • OptionalsubProperty: string

        dot-path to a nested property beneath propertyName, e.g. "address.street"

      Returns Promise<
          {
              current: Record<string, unknown>;
              propertyData: Record<string, unknown>;
          },
      >

      a promise that resolves to the property's prior and newly-written definitions

    • Create or update a single managed object relationship-property definition, leaving the rest of the type's schema untouched. Requires IDM 7.5+ — see readManagedObjectSchemaProperty. For any non-relationship property, or on an IDM version that predates 7.5, use importSubConfigEntity('managed', ...) with the full updated type definition instead. Neither path is reachable on classic.

      Parameters

      • type: string

        managed object type, e.g. alpha_user or user

      • propertyName: string

        schema property name, e.g. custom_merchantId

      • propertyData: ManagedObjectSchemaProperty

        the property definition to write

      Returns Promise<ManagedObjectSchemaProperty>

      a promise that resolves to the written property definition

    • Update an existing relationship schema property, via IDM's dedicated v2 schema API. Refuses (throws FrodoError) if the property doesn't exist -- use ManagedObjectSchemaOps.createManagedObjectSchemaRelationshipProperty instead. Only the fields present in changedFields change; everything else keeps its current value. A configured reverse side's descriptor is always re-supplied (required by the v2 API on every write of a bidirectional property), regardless of withReverse; withReverse additionally applies changedFields' overrides to the reverse side itself and writes it as a second, separate call -- if that second call fails after the forward write already succeeded, the thrown error says so explicitly; there is no automatic rollback.

      Parameters

      • type: string

        managed object type, e.g. alpha_aiagentprivilege

      • propertyName: string

        relationship property name, e.g. agent

      • changedFields: Partial<ManagedObjectSchemaRelationshipPropertyFields>

        only the field overrides to apply

      • OptionalwithReverse: boolean

        true to also update the inferred reverse side

      Returns Promise<
          {
              forward: Record<string, unknown>;
              reverse?: {
                  propertyData: Record<string, unknown>;
                  propertyName: string;
                  type: string;
              };
          },
      >

      a promise that resolves to the written definition(s)

    Settings

    Member Visibility

    On This Page

    Methods