Actions on SharePoint location records

Article
04/07/2023

You can perform the actions described in this topic on Microsoft SharePoint location records.

Create, retrieve, update, and delete location records

Using the Dynamics 365 Customer Engagement Web Services messages on the SharePointSite and SharePointDocumentLocation entities, you can create, retrieve, update, and delete records. To perform these operations on the SharePointSite entity, you must have the System Administrator role in Dynamics 365 Customer Engagement (on-premises). For a list of supported messages, see SharePointSite Entity and SharePointDocumentLocation Entity.

Note

Performing these operations on SharePoint location records only manipulates the data in Dynamics 365 Customer Engagement (on-premises). It does not create, update, or delete the locations on the SharePoint server.

The SharepointSite.ValidationStatus attribute shows the validation status of the SharePoint site URL. The possible values for this attribute are defined in the sharepoint_validationstatus option set.

The SharepointSite.ValidationStatusErrorCode attribute shows the reason for the validation status of the SharePoint site URL. The possible values for this attribute are defined in the sharepoint_validationstatusreason option set.

The storage locations on SharePoint Server are hierarchical where the SharePoint site collection is the container that can contain multiple sites, and each site can contain multiple sites or document libraries. Each document library can contain multiple document folders. While creating location records in Dynamics 365 Customer Engagement (on-premises), specify the path or the URL of these locations on SharePoint Server.

Absolute URL of the SharePoint location records

This is the complete URL of a storage location on SharePoint. You can specify the absolute URL using the SharePointSite.AbsoluteURL or SharePointDocumentLocation.AbsoluteURL property.

To create a SharePointSite record by specifying the absolute URL:



// Instantiate a SharePoint site object.
// See the Entity Metadata topic in the SDK documentation to determine 
// which attributes must be set for each entity.
SharePointSite spSite = new SharePointSite
{
    Name = "Sample SharePoint Site",
    Description = "Sample SharePoint Site Location record",
    
    // TODO: Change this URL to a valid SharePoint URL.                        
    AbsoluteURL = "https://www.example.com",
};

// Create a SharePoint site record named Sample SharePoint Site.
_spSiteId = _serviceProxy.Create(spSite);

Similarly, to create a SharePoint document location record by specifying the absolute URL:

SharePointDocumentLocation spDocLoc = new SharePointDocumentLocation  
{  
    Name = "Sample SharePoint Document Location",  
    Description = "Sample SharePoint Document Location record",  
    AbsoluteUrl = "https://www.example.com/spdocloc"     
};  
_spDocLocId = _serviceProxy.Create(spDocLoc);

Absolute URLs are typically provided for the SharePoint site records because these are the container or parent objects under which you want to create other locations for storing and managing your documents.

Note

The SharePointDocumentLocation.LocationType attribute determines whether a SharePointDocumentLocation record points to a SharePoint folder (0) or to a OneNote file (1). When you create a SharePointDocumentLocation instance (record), the value of the SharePointDocumentLocation.LocationType attribute is set to 0 by default to indicate that it points to a SharePoint folder. For more information about the OneNote support, see Integrate Microsoft Dynamics 365 Customer Engagement (on-premises) with OneNote.

Relative URL of the SharePoint location records

This is the relative location of a location record with respect to its parent location record on the SharePoint server. When you specify a relative URL for a SharePoint location record, you must also specify the parent object under which it should be created. Dynamics 365 Customer Engagement (on-premises) internally uses the URL of the parent object to determine the absolute URL for the child object. For example, to create a record for a SharePoint document location under the SharePoint site created in the previous example, you must specify the following:



// Instantiate a SharePoint document location object.
// See the Entity Metadata topic in the SDK documentation to determine 
// which attributes must be set for each entity.
SharePointDocumentLocation spDocLoc = new SharePointDocumentLocation
{
    Name = "Sample SharePoint Document Location",
    Description = "Sample SharePoint Document Location record",
    
    // Set the Sample SharePoint Site created earlier as the parent site.
    ParentSiteOrLocation = new EntityReference(SharePointSite.EntityLogicalName, _spSiteId),
    RelativeUrl = "spdocloc",

    // Associate this document location instance with the Fourth Coffee
    // sample account record.
    RegardingObjectId = new EntityReference(Account.EntityLogicalName, _account1Id)
};

// Create a SharePoint document location record named Sample SharePoint Document Location.
_spDocLocId = _serviceProxy.Create(spDocLoc);

The absolute URL of the child object (document location in this example) is: “Parent_URL/Relative_URL”. So, in this example, the absolute URL of the document location is https://www.example.com/spdocloc.

Relative URLs are typically provided when you want to create a location record lower down the hierarchy or as a child record.

The benefit of using the relative URL is that if you decide to move to a different SharePoint server to store your documents, you just need to update the absolute URL of the parent object location record (probably a site collection or site record) in Dynamics 365 Customer Engagement (on-premises), and all the other records down the hierarchy will continue functioning as before because the absolute URLs (determined automatically by Dynamics 365 Customer Engagement (on-premises)) will not be broken. If you had used absolute URLs for these child location records, you would have to fix the URLs individually.

Set a site location record as default

You can set a SharePoint site location record as default so that all the document locations created using Dynamics 365 Customer Engagement (on-premises) will be automatically created under this site. To create a site location record as default, use the SharePointSite.IsDefault property, and set it to true. You can set a site location record as default while creating or updating a site location record.

Note

Automatic creation of document location records is possible only if the target site is a SharePoint 2010 or SharePoint 2013 server and Microsoft Dynamics CRM List Component for SharePoint Server is installed on the target SharePoint Site Collection. For more information about the Microsoft Dynamics CRM List Component, see Microsoft Dynamics 365 Customer Engagement (on-premises) list component for Microsoft SharePoint Server.

Associate a document location record with an entity record

You can associate a document location record with an entity record. When you do this, all the documents for the entity record are stored at this location on the SharePoint server. You can associate a SharePoint document location record with an entity using the SharePointDocumentLocation.RegardingObjectId property. The following sample shows how you can do this:



// Instantiate a SharePoint document location object.
// See the Entity Metadata topic in the SDK documentation to determine 
// which attributes must be set for each entity.
SharePointDocumentLocation spDocLoc = new SharePointDocumentLocation
{
    Name = "Sample SharePoint Document Location",
    Description = "Sample SharePoint Document Location record",
    
    // Set the Sample SharePoint Site created earlier as the parent site.
    ParentSiteOrLocation = new EntityReference(SharePointSite.EntityLogicalName, _spSiteId),
    RelativeUrl = "spdocloc",

    // Associate this document location instance with the Fourth Coffee
    // sample account record.
    RegardingObjectId = new EntityReference(Account.EntityLogicalName, _account1Id)
};

// Create a SharePoint document location record named Sample SharePoint Document Location.
_spDocLocId = _serviceProxy.Create(spDocLoc);

Retrieve absolute and site collection URLs for a location record

As explained earlier, SharePoint Server follows a hierarchical model to store records. If you want to retrieve the absolute (complete) URL of a location record in the hierarchy and the SiteCollection URL under which the location record is present, you can use the RetrieveAbsoluteAndSiteCollectionUrlRequest message to do so.

The RetrieveAbsoluteAndSiteCollectionUrlRequest message will work properly only if both are true:

The Microsoft Dynamics CRM List Component for SharePoint Server is installed on the SharePoint site collection on the target SharePoint 2010 or SharePoint 2013 server. For more information, see Microsoft Dynamics 365 Customer Engagement (on-premises) list component for Microsoft SharePoint Server.

The location record for the parent SharePoint site collection exists in Dynamics 365 Customer Engagement (on-premises), and the SharePointSite.IsGridPresent property was set to true while creating the parent location record.

Otherwise, you will get a blank value or an incorrect value for the SiteCollectionUrl property.

For more information, see RetrieveAbsoluteAndSiteCollectionUrlRequest.

The following sample shows how to use the RetrieveAbsoluteAndSiteCollectionUrl message:



// Retrieve the absolute URL and the Site Collection URL
// of the SharePoint document location record.
RetrieveAbsoluteAndSiteCollectionUrlRequest retrieveRequest = new RetrieveAbsoluteAndSiteCollectionUrlRequest
{
    Target = new EntityReference(SharePointDocumentLocation.EntityLogicalName, _spDocLocId)
};
RetrieveAbsoluteAndSiteCollectionUrlResponse retriveResponse = (RetrieveAbsoluteAndSiteCollectionUrlResponse)_serviceProxy.Execute(retrieveRequest);

Console.WriteLine("Absolute URL of document location record is '{0}'.", retriveResponse.AbsoluteUrl.ToString());
Console.WriteLine("Site Collection URL of document location record is '{0}'.", retriveResponse.SiteCollectionUrl.ToString());

Actions on SharePoint location records

Create, retrieve, update, and delete location records

Absolute URL of the SharePoint location records

Relative URL of the SharePoint location records

Set a site location record as default

Associate a document location record with an entity record

Retrieve absolute and site collection URLs for a location record

See Also

Feedback

Additional resources