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.
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’:
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
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:
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
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.
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:
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:
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:
In Relatics, an end user can view the metadata of a document on the document’s details page:
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.
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
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.
Do you need help in applying the techniques and tips in your own case? Or do you have questions, comments or suggestions about this article? If so, don’t hesitate to contact one of our consultants