Show metadata of a document from Microsoft SharePoint

In the article Relating requirements to documents in Microsoft SharePoint Online I explained how to configure an interface between Relatics and SharePoint Online. The result is that end users can directly relate a requirement to a document in SharePoint, using a selection. Besides relating a document, end users often want to see more information about the document in Relatics than just the document name. For example, the author, current version or a hyperlink. This article explains how you can expand the interface to show in Relatics the metadata of a document from SharePoint Online.

Required prior knowledge

For this article, I assume that you have already configured a webservice in Relatics to request documents from SharePoint Online, as described here.

Configuring a webservice to receive the metadata of a document from SharePoint Online

A second RESTful webservice (for example: ‘Relatics – SharePoint – GetDocumentDetails’) is required to show the details of a specific document that was saved previously in Relatics using the webservice ‘Relatics – SharePoint – GetDocuments’:

01_relatics-sharepoint-details-attributes-and-replacers

You can include a URL in the RequestURI to request the metadata of a document for a specific project:

Example of RequestURI: Requesting the metadata of a document in SharePoint

[SubsiteUrl]/_api/Web/Lists(guid'[ListID]’)/Items([ItemNr])/FieldValuesAsText

The nice thing about the SharePoint API ‘FieldValuesAsText’ is that you will receive all the available metadata of a document in text, in a single list. This means that you don’t need to use operators to configure complex URLs and you are able to work directly with the data in Relatics.

I like to use RequestURI Replacers for this webservice. It is important to realise that the values for ‘ItemNr’ and ‘ListID’ will eventually be fetched from the document attributes. This is possible because the webservice ‘Relatics – SharePoint – GetDocuments’ has initially saved the values in the attributes ShortName and Remark for the ‘ItemNr’ and the ‘ListID’, respectively.

Processing the result from SharePoint Online in the Relatics webservice

To process the webservice result, the Relatics webservice can be configured as follows:

02_relatics-sharepoint-details-adapterfields

Under ‘XML Adapter Definition’ you can enter an Xpath Expression to interpret the webservice result of the SharePoint webservice:

Example of XPath Expression: XML Adapter Definition

//item/d/results/item

Next, under ‘XML Adapter Fields’, you can create all the fields from the webservice result that you want the end users to see.  Here’s a tip to select these fields: click on the ‘Preview’ icon in the top right corner of the screen, then view the ‘Preview XML’. In the example above I created a subset of the available metadata which seems relevant to the project. Of course, it’s up to you to select whatever metadata you wish to use.

It is advisable to select an XML Adapter Field in the ‘Identifying Field’ table. Even though this webservice does not store any data in Relatics, this setting ensures that the information will be grouped properly in the end application.

Configuring authentication for SharePoint Online in the Relatics webservice

For SharePoint online, switch the option ‘By Credentials’ to ‘Enabled’ on the ‘Authentication’ tab. The settings are the same as for the webservice ‘Relatics – SharePoint – GetDocuments’:

03_relatics-sharepoint-details-authentication

Relating the element from the information model in the Relatics webservice

In the ‘primarily retrieves one instance of’ table on the ‘Connections’ tab, you can select the element from the information model to be used for the interface with SharePoint Online:

04_relatics-sharepoint-details-connections

This setting ensures that it is clear, when configuring a query, that there is a webservice available. In the query browser, available webservices are shown underneath an element.

Configuring the query to display the document’s metadata

I have created a table with a query displaying the available metadata on the detail page of a document:

05_relatics-sharepoint-details-query

To make the webservice work, first the parameters need to be configured in the ‘Webservice’ table. The parameter ‘SubsiteUrl’ refers to the properties of the ‘Project’ element in the query. This construction is advisable when using multiple project workspaces in Relatics in combination with Synchronization. The parameter ‘ListID’ refers to the document attribute ‘Remark’. The parameter ‘ItemNr’ refers to the attribute ‘ShortName’. As indicated above, these are values that were previously saved for the document. This happens when the end user selects a document in Relatics using the webservice ‘Relatics – SharePoint – GetDocuments’.

The final result

When we first look in SharePoint Online, we see a selection of the available metadata:

06_relatics-sharepoint-details-sharepoint-properties

In Relatics, an end user can view the metadata of a document on the document’s details page:

07_relatics-sharepoint-details-end-result

This information is received live from SharePoint and displayed in Relatics using the webservice. Also, two links are available to view the document in SharePoint and to download the document. Obviously, this requires having the relevant user rights in SharePoint.

Downloads

Upload the RCS file below to your Relatics environment to view the examples contained in this article:

Note: For security reasons, the username and password of the webservice have been deleted. The webservice will therefore not work in the end application. The workspace is very handy for viewing the configuration settings.

About Kris de Waal

Relatics Portret-120

After graduating in Business Administration with a specialization in Business Information Management, Kris joined Relatics as a Business Information Consultant. He is eager to learn about new concepts, technologies, IT systems and apply the knowledge in his daily work. In addition, Kris loves to work on new ideas and innovations to get more out of Relatics.