Eisen relateren aan documenten uit Microsoft SharePoint Online

Projecten gebruiken graag een Document Management System (DMS), zoals Microsoft SharePoint, om documenten te beheren. Vaak ontstaat in een project de behoefte om informatie uit Relatics te koppelen aan een document of documentversie uit het DMS. In dit artikel laat ik je zien hoe je een webservice-koppeling kunt maken tussen Relatics en Microsoft SharePoint Online. Je kunt zelf bepalen of je de koppeling configureert voor bijvoorbeeld een document of een documentversie. In dit artikel wordt uitgegaan van een document. Eindgebruikers kunnen op deze manier in Relatics direct een eis koppelen aan een document uit SharePoint en worden geholpen met een selectie, waarmee gezocht kan worden in de actuele set van documenten.

De Relatics webservice inrichten om een verzoek naar SharePoint Online te sturen

In een RESTful webservice (Receiving Client) kun je zelf je eigen webservice naar SharePoint Online configureren:

In de RequestURI kun je de URL voor de SharePoint site van je project vastleggen, die gebruik maakt van de API van SharePoint om documenten op te vragen. Hieronder zie je een voorbeeld die ik zelf graag toepas.

Voorbeeld RequestURI: Documenten uit SharePoint opvragen

[SubsiteUrl]/_api/Web/Lists(guid'[ListGuid]')/Items?$select=ID,GUID,Title,FileLeafRef,UniqueId&$filter

=substringof('[Search]',Title) or substringof('[Search]',FileLeafRef)&top=100&orderby=ID

In de URL zijn verschillende operators gebruikt die invloed hebben op het resultaat van de webservice. Op deze pagina vind je welke operators beschikbaar zijn. Het is een tip om de URL eerst in je webbrowser op te bouwen. Hierdoor krijg je snel resultaat en weet je zeker dat de URL goed werkt. Het is belangrijk om te beseffen dat je zelf volledig vrij bent in het opstellen van de URL en zelf bepaalt welke metadata van documenten relevant is voor het project.

Verder gebruik ik graag RequestURI Replacers. Dit is erg belangrijk, omdat je hiermee vanuit de eindapplicatie de webservice kan beïnvloeden. Zo wordt een zoekterm, ingevoerd door een eindgebruiker in de parameter van een selection, meegegeven via de RequestURI Replacer ‘Search’ in de operator ‘filter’.

Het resultaat uit SharePoint Online verwerken in de Relatics webservice

Op de tab ‘Details’ configureer je wat er met de ontvangen data uit de webservice gedaan moet worden:

Bij ‘XSL transformations (optional)’ heb ik een zelfgemaakt XSLT-bestand toegepast.

Voorbeeld XSLT-bestand: All-Documents-with-DerivedListID.xslt

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:fn="http://www.w3.org/2005/xpath-functions">

  <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>

  <!-- Select each node -->

   <xsl:template match="@*|node()">

     <!-- Create a copy of the current node -->

      <xsl:copy>

        <xsl:choose>

            <!-- Check if the current node is the node "entry" inside the node "feed" -->

              <xsl:when test="(name() = 'uri') and (parent::__metadata)">

                 <!-- Select the string that contains the ListID of SharePoint -->

                 <xsl:variable name="StringWithListID" select="current()"/>

                 <!-- Remove "SP.Data." before the String -->

                 <xsl:variable name="ListID" select='substring-after($StringWithListID,"Lists(guid&apos;")'/>

                 <!-- Remove "Item" from the String and save the result in the attribute "DerivedListID"-->

                 <xsl:attribute name="DerivedListID" select='substring-before($ListID,"&apos;)")'/>

              </xsl:when>

            </xsl:choose>

            <!-- Apply a template to the current element or to the current element's child nodes -->

            <xsl:apply-templates select="@*|node()"/>

        </xsl:copy>

    </xsl:template>

</xsl:stylesheet>

 

Het XSLT-bestand zorgt ervoor dat het ID van de SharePoint List als aparte node in de XML staat. In het originele resultaat van de webservice staat deze ListID namelijk in een gedeelte van een URL. Het is aan te raden om de ListID apart in het resultaat op te nemen. Deze wil je in Relatics bij een document opslaan, omdat je deze later nodig hebt voor andere webservices.

Merk overigens op dat ik hier praat over XML, terwijl het eigenlijk om een RESTful webservice gaat. Dit komt omdat Relatics achter de schermen het resultaat omzet van JSON naar XML. Dit is fijn, omdat je zo altijd op dezelfde manier data kan filteren.

Bij ‘XML Adapter Identifying Field’ kun je een Xpath Expression invullen om het webservice resultaat van de SharePoint webservice te interpreteren:

Voorbeeld XPath Expression: XML Adapter Definition

//item/d/results/item

Met bovenstaand voorbeeld zorg je ervoor dat uit het webservice resultaat alle nodes geselecteerd worden die een document uit SharePoint betreffen.

Bij 'XML Adapter Fields' kun je vervolgens de nodes uit het webservice resultaat aanmaken die je in Relatics wil gebruiken. Als je goed kijkt zie je dat een aantal velden in attributen opgeslagen worden. Dit is belangrijk om te doen, omdat deze informatie later nodig is voor het aanroepen van additionele webservices. Bijvoorbeeld, om alle details van 1 document uit SharePoint op te vragen.

Als 'XML Adapter Identifying Field' is het aan te raden om 'UniqueID' te gebruiken. Dit veld is essentieel. Hierdoor is in Relatics bekend welk document correspondeert met hetzelfde document in SharePoint.

De authenticatie voor SharePoint Online instellen in de Relatics webservice

Op de tab ‘Authentication’ moet je voor SharePoint Online de optie ‘By credentials’ op ‘Enabled’ zetten. Vervolgens kun je een Username en Password opgeven van een user die toegang heeft tot de de SharePoint site van het project.

Belangrijk is om bij ‘Domain’ te kiezen voor de waarde ‘SharePointOnline’. Dit zorgt ervoor dat het juiste authenticatiemechanisme gebruikt wordt. Verder raad ik je aan om geen persoonlijke user te gebruiken, maar een aparte user voor de koppeling tussen Relatics en SharePoint, die alleen leesrechten in SharePoint heeft.

Het element uit het informatiemodel instellen in de Relatics webservice

Op de tab ‘Connections’ kun je in de tabel ‘primarily retrieves a set of instances of’ het element uit het model selecteren, waarin instanties van het geselecteerde document vastgelegd worden. Uiteraard hangt het van je eigen informatiemodel af welk element hier het meest geschikt voor is. In dit geval is gekozen voor het type element ‘Document’.

Een selection voor de eindgebruiker configureren

Om de eindgebruiker te helpen bij het selecteren van een document is het aan te raden om een selection te maken. Voorbeeld:

Merk op dat de rootnode van de query het element ‘Project’ is. Daarnaast bevat het twee eigenschappen waarin URLs voor SharePoint worden vastgelegd. Deze constructie is ideaal wanneer je meerdere project workspaces hebt in combinatie met Synchronization. Op deze manier kun je per project workspace de te koppelen SharePoint site instellen.

Het eindresultaat

Laten we eerst kijken naar SharePoint Online. In onderstaande afbeelding kun je zien dat in het voorbeeldproject ‘The Connection’ twee documenten beschikbaar zijn:

Wanneer een eindgebruiker in Relatics een document wil relateren, bijvoorbeeld bij een eis, dan verschijnt er een selectie. In deze selectie kan de eindgebruiker een zoekwoord invoeren (bijv. ’doc’). Na het klikken op ‘Search’ verschijnt de actuele set van documenten uit SharePoint. Deze zijn live via de webservice opgevraagd.

07_relatics_sharepoint_webservice_result_relatics

Als een eindgebruiker een document selecteert, dan wordt in Relatics een instantie van het document aangemaakt, inclusief de relatie tussen de eis en het document. Het werkt echt heel intuïtief voor eindgebruikers om op deze manier een relatie te leggen tussen informatie uit Relatics en uit SharePoint Online.

Downloaden

Upload onderstaand rcs-bestand in je Relatics environment om de voorbeelden van dit artikel zelf te bekijken:

Opmerking: Uit veiligheid zijn de username en password van de webservices verwijderd. Hierdoor zal de webservice niet werken in de eindapplicatie. De workspace is zeer handig om de instellingen van de configuratie te bekijken.

Over Kris de Waal

Na het afronden van de studie Bedrijfskunde met een specialisatie in Business Information Management, werkt Kris bij Relatics als Business Information Consultant. Hij leert graag over nieuwe concepten, technologieën, IT-systemen en past deze kennis toe in zijn dagelijkse werk. Daarnaast werkt Kris graag aan nieuwe ideeën en innovaties om meer uit Relatics te halen.

Relatics Portret-120

Contact

Heeft u hulp nodig bij het toepassen van de genoemde technieken in uw eigen casus? Of heeft u vragen, opmerkingen of suggesties over dit artikel? Laat het ons dan weten via onderstaand formulier.