Retrieve metadata by name or MetadataId

Dynamics CRM 2016
 

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Your applications can adapt to configuration changes by querying the metadata. When you know one of the key properties of a metadata item, you can retrieve metadata definitions using the Web API.

System_CAPS_noteNote

This capability was added with December 2016 update for Dynamics 365 (online and on-premises).

All retrievable metadata items have a MetadataId primary key that can be used to retrieve individual items. For those types of metadata which have a defined alternate key, you can retrieve them by name.

Retrieving items by name is generally easier because you probably already have some reference to the metadata item name in your code. The following table lists the alternate key properties for retrieving metadata items by name

Metadata item

Alternate Key

Example

Entity

LogicalName

GET /api/data/v8.2/EntityDefinitions(LogicalName='account')

Attribute

LogicalName

GET /api/data/v8.2/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='emailaddress1')

Relationship

SchemaName

GET /api/data/v8.2/RelationshipDefinitions(SchemaName='Account_Tasks')

Global Option Set

Name

GET /api/data/v8.2/GlobalOptionSetDefinitions(Name='metric_goaltype')

A common item of metadata that people want to retrieve are the options configured for a particular attribute. The following example shows how to retrieve the OptionSet and GlobalOptionSet properties of a PicklistAttributeMetadata EntityType.

System_CAPS_noteNote

Expanding both the OptionSet and GlobalOptionSet single-valued navigation properties of PicklistAttributeMetadata EntityType allows you to get the option definition whether the attribute is configured to use global optionsets or the 'local' optionset within the entity. If it is a 'local' optionset, the GlobalOptionSet property will be null as shown below.

If the attribute used a global optionset, the GlobalOptionSet property would contain the defined options and the OptionSet property would be null.

Request

GET [Organization URI]/api/data/v8.2/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='accountcategorycode')/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet($select=Options),GlobalOptionSet($select=Options) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions('account')/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet,GlobalOptionSet,OptionSet(Options),GlobalOptionSet(Options))/$entity",
    "LogicalName": "accountcategorycode",
    "MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad",
    "OptionSet@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions('account')/Attributes(118771ca-6fb9-4f60-8fd4-99b6124b63ad)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet(Options)/$entity",
    "OptionSet": {
        "Options": [{
            "Value": 1,
            "Label": {
                "LocalizedLabels": [{
                    "Label": "Preferred Customer",
                    "LanguageCode": 1033,
                    "IsManaged": true,
                    "MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
                    "HasChanged": null
                }],
                "UserLocalizedLabel": {
                    "Label": "Preferred Customer",
                    "LanguageCode": 1033,
                    "IsManaged": true,
                    "MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
                    "HasChanged": null
                }
            },
            "Description": {
                "LocalizedLabels": [

                ],
                "UserLocalizedLabel": null
            },
            "Color": null,
            "IsManaged": true,
            "MetadataId": null,
            "HasChanged": null
        }, {
            "Value": 2,
            "Label": {
                "LocalizedLabels": [{
                    "Label": "Standard",
                    "LanguageCode": 1033,
                    "IsManaged": true,
                    "MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
                    "HasChanged": null
                }],
                "UserLocalizedLabel": {
                    "Label": "Standard",
                    "LanguageCode": 1033,
                    "IsManaged": true,
                    "MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
                    "HasChanged": null
                }
            },
            "Description": {
                "LocalizedLabels": [

                ],
                "UserLocalizedLabel": null
            },
            "Color": null,
            "IsManaged": true,
            "MetadataId": null,
            "HasChanged": null
        }],
        "MetadataId": "b994cdd8-5ce9-4ab9-bdd3-8888ebdb0407"
    },
    "GlobalOptionSet": null
}

Because the MetadataId is the primary key for metadata items, retrieving individual items follows the same pattern used to retrieve business data entities.

Metadata item

Example

Entity

GET /api/data/v8.2/EntityDefinitions(<Entity MetadataId>)

Attribute

GET /api/data/v8.2/EntityDefinitions(<Entity MetadataId>)/Attributes(<Attribute MetadataId>)

Relationship

GET /api/data/v8.2/RelationshipDefinitions(<Relationship MetadataId>)

Global Option Set

GET /api/data/v8.2/GlobalOptionSetDefinitions(<OptionSet MetadataId>)

To achieve the same result as shown in Example: Retrieve metadata items by name, you will need to perform a series of query operations to get the MetadataId by filtering by the entity LogicalName and then by the attribute LogicalName.

Request
GET [Organization URI]/api/data/v8.2/EntityDefinitions?$filter=LogicalName%20eq%20'account'&$select=MetadataId HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions(MetadataId)","value":[
    {
      "MetadataId":"70816501-edb9-4740-a16c-6a5efbc05d84"
    }
  ]
}
Request
GET [Organization URI]/api/data/v8.2/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes?$filter=LogicalName%20eq%20'accountcategorycode'&$select=MetadataId HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(MetadataId)","value":[
    {
        "@odata.type": "#Microsoft.Dynamics.CRM.PicklistAttributeMetadata",
        "MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad"
    }
    ]
}
Request
GET [Organization URI]/api/data/v8.2/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(118771ca-6fb9-4f60-8fd4-99b6124b63ad)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet($select=Options),GlobalOptionSet($select=Options) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet,GlobalOptionSet,OptionSet(Options),GlobalOptionSet(Options))/$entity",
    "LogicalName": "accountcategorycode",
    "MetadataId": "118771ca-6fb9-4f60-8fd4-99b6124b63ad",
    "OptionSet@odata.context": "[Organization URI]/api/data/v8.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(118771ca-6fb9-4f60-8fd4-99b6124b63ad)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet(Options)/$entity",
    "OptionSet": {
        "Options": [{
            "Value": 1,
            "Label": {
                "LocalizedLabels": [{
                    "Label": "Preferred Customer",
                    "LanguageCode": 1033,
                    "IsManaged": true,
                    "MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
                    "HasChanged": null
                }],
                "UserLocalizedLabel": {
                    "Label": "Preferred Customer",
                    "LanguageCode": 1033,
                    "IsManaged": true,
                    "MetadataId": "0bd8a218-2341-db11-898a-0007e9e17ebd",
                    "HasChanged": null
                }
            },
            "Description": {
                "LocalizedLabels": [

                ],
                "UserLocalizedLabel": null
            },
            "Color": null,
            "IsManaged": true,
            "MetadataId": null,
            "HasChanged": null
        }, {
            "Value": 2,
            "Label": {
                "LocalizedLabels": [{
                    "Label": "Standard",
                    "LanguageCode": 1033,
                    "IsManaged": true,
                    "MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
                    "HasChanged": null
                }],
                "UserLocalizedLabel": {
                    "Label": "Standard",
                    "LanguageCode": 1033,
                    "IsManaged": true,
                    "MetadataId": "0dd8a218-2341-db11-898a-0007e9e17ebd",
                    "HasChanged": null
                }
            },
            "Description": {
                "LocalizedLabels": [

                ],
                "UserLocalizedLabel": null
            },
            "Color": null,
            "IsManaged": true,
            "MetadataId": null,
            "HasChanged": null
        }],
        "MetadataId": "b994cdd8-5ce9-4ab9-bdd3-8888ebdb0407"
    },
    "GlobalOptionSet": null
}

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Community Additions

Show: