Calling Dataverse Web API functions

Single source of truth

To find all

• entities, their attributes (columns) and relationships,
• complex and enum types and
• functions

available in your Dataverse environment, you may call the following endpoint:

https://org0.api.crm17.dynamics.com/api/data/v9.2/$metadata?annotations=true

It will return xml document full of wisdom =)
You may find this endpoint in my Postman Beyond Microsoft Graph collection here: Single Source of Truth

Calling Dataverse functions

Let's assume we need to access documents attached to a Dataverse record. SharePoint integration is configured for this entity, so all the files are saved in a SharePoint site.
What we need to do now, is to find the location of all attached documents.

RetrieveAbsoluteAndSiteCollectionUrl

This can be accomplished using the RetrieveAbsoluteAndSiteCollectionUrl function.

After calling the metadata endpoint, I have access to the documentation for this function:

//...
<ComplexType Name="RetrieveAbsoluteAndSiteCollectionUrlResponse">
   <Property Name="AbsoluteUrl" Type="Edm.String" Unicode="false" />  
   <Property Name="SiteCollectionUrl" Type="Edm.String" Unicode="false" />
</ComplexType>
//...
<Function Name="RetrieveAbsoluteAndSiteCollectionUrl" IsBound="true">
   <Parameter Name="entity" Type="mscrm.sharepointsite" Nullable="false" />
   <ReturnType Type="mscrm.RetrieveAbsoluteAndSiteCollectionUrlResponse" Nullable="false" />
</Function>
<Function Name="RetrieveAbsoluteAndSiteCollectionUrl" IsBound="true">
   <Parameter Name="entity" Type="mscrm.sharepointdocumentlocation" Nullable="false" />
   <ReturnType Type="mscrm.RetrieveAbsoluteAndSiteCollectionUrlResponse" Nullable="false" />
</Function>

Neat! 🚀

Note the IsBound="true" parameter and the fact that the <Function Name="RetrieveAbsoluteAndSiteCollectionUrl" is displayed twice. Bound functions can have multiple definitions when bound to different types.

This means that I can call the RetrieveAbsoluteAndSiteCollectionUrl with a reference to either sharepointsite or sharepointdocumentlocation.

Sharepoint Document Locations

Information about locations configured for the entity, or created for a record, can be obtained using sharepointdocumentlocations endpoint (line-breaks added for readability only):

https://org0.api.crm17.dynamics.com/api/data/v9.2/sharepointdocumentlocations?
 $select=
  sitecollectionid,
  _regardingobjectid_value,
  relativeurl,
  name,
  sharepointdocumentlocationid
 &$filter=
  _regardingobjectid_value eq '7399f668-90fc-4cf3-babb-75fa0c108486'

which returns the following reponse:

{
    "@odata.context": "https://orgbb429a1a.api.crm17.dynamics.com/api/data/v9.2/$metadata#sharepointdocumentlocations(sitecollectionid,_regardingobjectid_value,relativeurl,name,sharepointdocumentlocationid)",
    "value": [
        {
            "@odata.etag": "W/\"8333355\"",
            "sitecollectionid": "fec93c89-fd02-ef11-9f89-6045bd2c4a3e",
            "_regardingobjectid_value": "7399f668-90fc-4cf3-babb-75fa0c108486",
            "relativeurl": "AAA_7399F66890FC4CF3BABB75FA0C108486",
            "name": "Documents on External Cloud Service Site 1",
            "sharepointdocumentlocationid": "42c244ad-a375-ef11-ac20-002248c9a7cb"
        }
    ]
}

Calling RetrieveAbsoluteAndSiteCollectionUrl (I)

I will now call the RetrieveAbsoluteAndSiteCollectionUrl function with the sharepointdocumentlocation parameter, using the sharepointdocumentlocationid value returned in the previous step (line-breaks added for readability only):

https://org0.api.crm17.dynamics.com/api/data/v9.2/
 sharepointdocumentlocations(42c244ad-a375-ef11-ac20-002248c9a7cb)
/Microsoft.Dynamics.CRM.RetrieveAbsoluteAndSiteCollectionUrl()

Important: When an function is bound, it will have a reference to a specific item within the service namespace. To use the function, you must use the fully qualified name including the Microsoft.Dynamics.CRM namespace.

It returns the following response:

{
    "@odata.context": "https://org0.api.crm17.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RetrieveAbsoluteAndSiteCollectionUrlResponse",
    "AbsoluteUrl": "https://contoso.sharepoint.com/sites/powerplatform/ENTITY_NAME/AAA_7399F66890FC4CF3BABB75FA0C108486",
    "SiteCollectionUrl": "https://contoso.sharepoint.com/sites/powerplatform"
}

Calling RetrieveAbsoluteAndSiteCollectionUrl (II)

And what would happen if I used the sitecollection parameter?

https://org0.api.crm17.dynamics.com/api/data/v9.2/
 sharepointsites(fec93c89-fd02-ef11-9f89-6045bd2c4a3e)
/Microsoft.Dynamics.CRM.RetrieveAbsoluteAndSiteCollectionUrl()

Same same, but different. In this case I only see the references to the SPO site configured in SharePoint integration settings for the entity, but of course there's no folder

{
    "@odata.context": "https://org0.api.crm17.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RetrieveAbsoluteAndSiteCollectionUrlResponse",
    "AbsoluteUrl": "https://contoso.sharepoint.com/sites/powerplatform",
    "SiteCollectionUrl": "https://contoso.sharepoint.com/sites/powerplatform"
}

I already added these two calls to the Power Platform Environment folder in the Beyond Microsoft Graph collection.
Check it out to see them in action =)

Additional references

• Use the Microsoft Dataverse Web API
• Use OData to query data

Comments

[Euan]

Hi, I wanted to jump in and say your posts are fantastic and I’m super grateful for the effort you put into them! 🙏

[Kinga]

Thank you @euankennedy for your comment. You have no idea how much I appreciate it, that you found time and energy to write it.
I know that it’s often difficult to stop what we are doing and give a like or write comment. These posts often help us to move forward with our work and as soon as we find answers, we … move on.
So yeah, it means a lot ❤️