typescript, metadata, Xrm => need a real, non-Xrm metadata cache layer

v9.0 of dynamics Xrm provided some metadata support e.g. Xrm.Utility.getEntitySetName. It is useful given a singlular entity name to provide the plural name e.g. contact => contacts.

But this is has not been enough for my applications and besides, I like to run tests on non-browser related components or use non-browser applications to support my dynamics applications.

With this type of requirement, we needa real metadata class that can provide a diverse set of metadata for any application.

I tend to use a modified version of CRMWebAPI to help with this. You can find some of the content I describe below in my dynamics-client-ui project.

Metadata? What do we need?

I typically need:

• Connection Roles and Categories lookup by name and value.
• Plural names as dsecribe above.
• OptionSet labels and values for a given lcsid.
• Object type codes.
• A list of all activity entity types.
• ...the list is nearly endless...
• Metadata on attributes
• Metadata on relationships especially 1:M

To support this we can create a metadata class in typescript (usable in javascript) to support metadata capture. It needs to provde caching of course to be efficient.

To do this is actually quite easy. The only real question is how you structure the cache. Generally, a simple cache structure with put/get would be sufficient but below we create some specialized data structures. The below works in both node environments for testing (and can be mocked) as well as browser environments.

The class below will require typescript and some type of module management/bundler. It's not complete but it's a skeleton to show how to create a Metadata class...and its not complete but an early draft.

import {DEBUG} from "BuildSettings"
import { CRMWebAPI, QueryOptions } from "./CRMWebAPI"
import * as R from "ramda"

interface LabelValue {
    Label: string
    Value: number
}

/** From OptionSet. */
interface Option extends LabelValue {
    Description?: string
}

export interface EntityDefinition {
    MetadataId: string
    SchemaName: string
    LogicalName: string
    PrimaryIdAttribute: string
    LogicalCollectionName: string
}

export interface OneToManyRelationship {
    MetadataId: string
    
    ReferencedAttribute: string
    ReferencedEntity: string,
    ReferencedEntityNavigationPropertyName: string
    
    ReferencingAttribute: string
    ReferencingEntity: string
    ReferencingEntityNavigationPropertyName: string
    RelationshipType: string
    
    SchemaName: string
    IsManaged: boolean
    IsHierarchical: boolean
}

export interface Attribute {
    MetadataId: string
    LogicalName: string
}


/** [entity name].[attribute name] => attribute metadata definition. */
let entityToAttribute = {}

/** singular entity name to entity object */
const entityNameToDefinition: Map<string, EntityDefinition> = new Map()
const entityDefinitions: Array<EntityDefinition> = []

/** entity logical name to array of relationships */
const entityNameToOneToMany: Map<string, Array<OneToManyRelationship>> = new Map()

export interface ObjectTypeCodePair {
    LogicalName: string
    ObjectTypeCode: number
}

let objectTypeCodes: Array<ObjectTypeCodePair> = []
const objectTypeCodesByCode: Map<number, ObjectTypeCodePair> = new Map()
const objectTypeCodesByName: Map<string, ObjectTypeCodePair> = new Map()

/** all connection role categories */
export interface ConnectionRoleCategory {
    Label: string
    Value: number
}

let connectionRoleCategories: Array<ConnectionRoleCategory> = []
const connectionRoleCategoriesByName: Map<string, ConnectionRoleCategory> = new Map()
const connectionRoleCategoriesByValue: Map<number, ConnectionRoleCategory> = new Map()

/** Set of all connection roles. */
export interface ConnectionRole {
    connectionroleid: string
    name: string
    category: number
    ["category@OData.Community.Display.V1.FormattedValue"]: string
    description: string
    statecode: number
    statuscode: number
}

let connectionRoles: Array<ConnectionRole> = []
const connectionRolesById: Map<string, ConnectionRole> = new Map()
const connectionRolesByName: Map<string, ConnectionRole> = new Map()

/**
 * Metadata API. Fetched metadata is shared among all instances of this class at the moment.
 */
export class Metadata {
    constructor(dynclient: CRMWebAPI, lcsid: number = 1033) {
        this.dynclient = dynclient
        this.lcsId = lcsid
    }

    private lcsId: number
    private dynclient: CRMWebAPI

    /** Get all attributes for a logical entity name or return [] */
    getAttributes = async (entityName) => {
        const entry = entityToAttribute[entityName]
        if (entry) { return entry.values() }
        try {
            const m = await this.getMetadata(entityName)
            // Navigate to attributes
            const attrs = await this.dynclient.Get<any>("EntityDefinitions", m!.MetadataId, {
                Select: ["LogicalName"],
                Expand: [{ Property: "Attributes" }]
            }).
                then((r: any) => r.Attributes)
            if (attrs && attrs.length > 0) {
                // place in cache, by logical name!
                const mergeMe = attrs.reduce((accum, a) => {
                    accum[a.LogicalName] = a
                    return accum
                }, {})
                entityToAttribute = R.mergeDeepRight(entityToAttribute, {
                    [entityName]: mergeMe
                })
                return attrs
            }
        } catch (e) {
            console.log(`Error obtaining entity attributes for ${entityName}`, e)
        }
        // no attributes returned? probably an error somewhere
        return []
    }

    /** Find a specific entity-attribute metadata. Return null if not found. */
    lookupAttribute = async (entityName, attributeName) => {
        await this.getAttributes(entityName)
        // we should have the data now if it exists
        const entity = entityToAttribute[entityName]
        if (entity) {
            const attribute = entity[attributeName]
            if (attribute) return attribute
        }
        return null
    }

    /** Returns all entity {LogicalName, ObjectTypeCode} pairs. */
    getObjectTypeCodes = async () => {
        if (objectTypeCodes.length > 0) return objectTypeCodes
        const qopts = {
            Select: ["LogicalName", "ObjectTypeCode"]
        }
        const r = await this.dynclient.GetList<ObjectTypeCodePair>("EntityDefinitions", qopts)
        objectTypeCodes = r.List
        objectTypeCodes.forEach(c => objectTypeCodesByCode.set(c.ObjectTypeCode, c))
        objectTypeCodes.forEach(c => objectTypeCodesByName.set(c.LogicalName, c))
        return objectTypeCodes
    }

    /** Given a numerical code, return the (LogicalName, ObjectTypeCode) pair. */
    lookupObjectTypeCodeByCode = async (code: number) => {
        await this.getObjectTypeCodes()
        return objectTypeCodesByCode.get(code)
    }

    /** Given a name, return the (LogicalName, ObjectTypeCode) pair. */
    lookupObjectTypeCodeByName = async (name: string) => {
        await this.getObjectTypeCodes()
        return objectTypeCodesByName.get(name)
    }

    /** Pass in the entity singular logical name. Returns null if not found. */
    getMetadata = async (entityName: string): Promise<EntityDefinition|null> => {
        const cacheCheck = entityNameToDefinition.get(entityName)
        if (cacheCheck) return cacheCheck

        const qopts = {
            Filter: `LogicalName eq '${entityName}'`
        }

        // We can do this with a EntityDefinitions(LogicalName='..name...') but CRMWebAPI
        // does not have that.
        return this.dynclient.GetList<EntityDefinition>("EntityDefinitions", qopts).
            then(r => {
                if (!r.List) return null
                // add to cache
                const edef: EntityDefinition = r.List[0]
                entityDefinitions.push(edef)
                entityNameToDefinition[entityName] = edef
                return edef
            })
    }

    /** Get the entity set name given the entity logical name e.g. contact => contacts. */
    getEntitySetName = async (logicalName: string) => {
        return this.getMetadata(logicalName).
            then(md => {
                if (md) return md.LogicalCollectionName
                return null
            })
    }

    /** Get the schema name given the entity logical name. */
    getSchemaName = async (logicalName: string) => {
        return this.getMetadata(logicalName).
            then(md => {
                if (md) return md.SchemaName
                return null
            })
    }

    /** Return all connection roles. */
    getConnectionRoles = async () => {
        if (connectionRoles.length > 0) return connectionRoles
        const qopts = {
            FormattedValues: true,
            Filter: "statecode eq 0"
        }
        const r = await this.dynclient.GetList<ConnectionRole>("connectionroles", qopts).then(r => r.List)
        connectionRoles = r
        connectionRoles.forEach(cr => connectionRolesById.set(cr.connectionroleid, cr))
        connectionRoles.forEach(cr => connectionRolesByName.set(cr.name, cr))
        return r
    }

    // Use public, handles this binding automatically... */
    /** Return an array of connection roles for a given connection category name. */
    public async getConnectionRolesForCategoryNamed(categoryName: string) {
        const roles = await this.getConnectionRoles()
        const cat = await this.getConnectionRoleCategoryByName(categoryName)
        return roles.filter(cr => cr!.category === cat!.Value)
    }

    /** Return a connection role by its id. */
    getConnectionRoleById = async (id: string) => {
        await this.getConnectionRoles()
        return connectionRolesById.get(id)
    }

    /** Return a connection role by its name. */
    getConnectionRoleByName = async (name: string) => {
        await this.getConnectionRoles()
        return connectionRolesByName.get(name)
    }

    /** Return an array of all of these. */
    getConnectionRoleCategories = async () => {
        if (connectionRoleCategories.length > 0)
            return connectionRoleCategories

        const r = await this.dynclient.GetOptionSetUserLabels("connectionrole_category")
        connectionRoleCategories = connectionRoleCategories.concat(r)
        connectionRoleCategories.forEach(crc => connectionRoleCategoriesByName.set(crc.Label, crc))
        connectionRoleCategories.forEach(crc => connectionRoleCategoriesByValue.set(crc.Value, crc))
        return r
    }

    /** Return a connecton role category by value (Category = OptionSet). */
    getConnectionRoleCategoryByValue = async (value: number) => {
        await this.getConnectionRoleCategories()
        return connectionRoleCategoriesByValue.get(value)
    }

    /* Return a connection role category its name. */
    getConnectionRoleCategoryByName = async (name: string) => {
        await this.getConnectionRoleCategories()
        return connectionRoleCategoriesByName.get(name)
    }

    /** 
     * Get Option pairs back, Label and Value or an empty list..
     * Hackey implementation. Only looks at Attribute.OptionSet not Attribute.GlobalOptionSet.
     * Not cached yet!!!
     */
    public async getOptionSet(entityLogicalName: string,
                              attributeLogicalName: string): Promise<Array<Option>>
    {
        const emeta = await this.getMetadata(entityLogicalName)
        const ameta = await this.lookupAttribute(entityLogicalName, attributeLogicalName)
        if(!emeta) return []
        const qopts: QueryOptions = {
            Select: ["Options"],
            Path:[{
                Property: `Attributes(${ameta.MetadataId})`,
                Type: "Microsoft.Dynamics.CRM.PicklistAttributeMetadata"
            },
                  {
                      Property: "OptionSet"
                  }]
        }
        const attr: any = await this.dynclient.Get("EntityDefinitions", emeta.MetadataId, qopts)
        const pairs = attr.Options.map(opt => ({
            Label: opt.Label.LocalizedLabels[0].Label,
            Value: opt.Value
        }))
        //console.log("attr", attr, pairs)
        return pairs
    }

    /** 
     * Return all activity types. How do we filter on non-published kinds? 
     * This may return a surprising number of activities that are used only 
     * in a specialized context so you may need to filter them.
     */
    public async getAllActivityTypes() {
        const qopts: QueryOptions = {
            Select:["LogicalName", "ObjectTypeCode","Description", "DisplayName",
            "IconSmallName", "IconLargeName", "IconMediumName"],
            Filter: "IsActivity eq true"
        }
        const l = await this.dynclient.GetList("EntityDefinitions", qopts).then(r => {
            return r.List.map((entry:any) => ({
                ...entry,
                Description: entry.Description.LocalizedLabels[0].Label,
                DisplayName: entry.DisplayName.LocalizedLabels[0].Label
            }))
        })
        return l
    }

    
    /** Retur the primary PK logical attribute name for a given entity. */
    public async getPk(entityLogicalName: string): Promise<string|null> {
        return this.getMetadata(entityLogicalName).
                    then(md => {
                        if (md) return md.PrimaryIdAttribute
                        return null
                    })        
    }

    /** Relationships. Returns empty array if not found. */
    public async getOneToManyRelationships(entityLogicalName: string): Promise<Array<OneToManyRelationship>> {
        const rels = entityNameToOneToMany.get(entityLogicalName)
        if(rels) return rels
        
        const m = await this.getMetadata(entityLogicalName)
        if(!m) return []
        return this.dynclient.Get<any>(
            "EntityDefinitions", m!.MetadataId,
            {
                Select: ["LogicalName"],
                Expand: [{Property: "OneToManyRelationships"}]
            }).
              then((r:any) => {
                  entityNameToOneToMany.set(entityLogicalName, r.OneToManyRelationships)
                  return r.OneToManyRelationships
              })
    }

    /** Get a 1:M relationship to a specific name. Could be multiple, so choose wisely. */
    public async getOneToManyRelationshipsTo(entityLogicalName: string, toEntityLogicalName: string) {
        const rels = await this.getOneToManyRelationships(entityLogicalName)
        return rels.filter(r => r.ReferencingEntityNavigationPropertyName === toEntityLogicalName)
    }

    /** Should be only one. null if not found. */
    public async getOneToManyRelationshipBySchemaName(entityLogicalName: string, schemaName: string) {
        const rels = await this.getOneToManyRelationships(entityLogicalName)
        const x = rels.filter(r => r.SchemaName === schemaName)
        if(x.length === 1) return x[0]
        return null
    }
                                                 

    
}

export default Metadata

Setting regardingobjectid in the new v9.0+ api

In the pre-9.0 API, you could pull a few tricks to set the regardingid value in a new activity that you opened with openEntityForm.

The API has changed somewhat in 9.0+. The new API uses Xrm.Navigation.openForm with the arguments specified as an object:

const parameters = {}
nav.openForm({entityName: "contact", id: <guid or skip id attribute for a new one>, 
                openInNewWindow: false, useQuickCreateForm: true, 
                width: 1000, height: 1000}, parameters) 

The tricky part was always setting the regarding attribute. Now you can rather easily by doing:

const parameters = {
  regardingobjectid: JSON.stringfy({id: regardingObjectIdGUID, name: "name of regarding object",
    entityType: "contact"})
}  

The entityName should be the regarding entity's logical name. The id should not have braces ({}).

If you need to support both APIs and use webpack, use DefinePlugin to set a "CLIENT" variable to switch between the formats.