Sunday, 7 April 2019

Using MS Graph API and Adaptive Cards for Search/Render User Details with SPFx solutions

In this article, we will learn how to develop SPFx webparts for Office 365 SharePoint site and Microsoft Team, that leverages Microsoft Graph to search users and adaptive cards for rendering the user data effectively.

The sample used here uses the adaptive card, which has a very minimal UI. The sample used, shows how effectively UI could be changed by users. But complex custom UI could be built using the adaptive cards.

Adaptive Cards:

Let us use the adaptive card on our SPFx component for displaying user details. The following provides you the basic understanding.
  • Introduced recently, a new way for developers to render content in a consistent way, which is a open framework. 
  • It is providing options for developers, to design the UI for the specific component, using schema or visually.
  • Primarily targeted for BOT frameworks, Teams, Cortona, and windows notifications.
The following snapshot showing the UI built for our sample. This snapshot has 2 container sets for displaying 2 user details. In the schema mentioned later in the article, the single container is used, which could iterated using for loops for building containers for the required user set.

Adaptive Card Visual Interface for building component with UI
Adaptive Card Visual Interface for building component with UI

Building Solution

Create a spfx solution, by running the command "yo @microsoft/sharepoint"

Package.json File: The following packages needs to be installed, and the same has been referenced in package.json file.
  • adaptivecards - latest version
  • office-ui-fabric-react - 5.132.0
Note: You will face run-time issues, if right version set is not followed. Ensure, following points are considered. 
  • SPFx solution should have package references: 1.8.0
  • Type script referencing to 3.3 version, with right rush-stack-compiler packages mentioned on tsconfig.json and package.json files.
Alternatively, you follow the detailed explanation given here to manage conflicts.

React File: The react file for searching the user data based on the user input and rendering contains the following features/objects/methods.
  • Import necessary packages, like adaptive cards, Microsoft graph, and other interfaces.
  • The state requires 2 variables, 
    • one for holding the text to search for, and 
    • another to hold the search results.
  • The props will have the current user context information, to work with the Microsoft graph API.
  • Interfaces are used for setting user object. The parameters like display name, mail, principal name, and mobile phone parameters are declared here.
  • Text box has a function binding, for triggering for value changes. The function sets the state object, with the search text.
    • GetUsers method retrieve the user data using Microsoft graph API, msGraphClientFactory is used. 
    • MS graph client is called using the context variable. This variable is accessed using props object, that is being passed from the parent TS file.
    • There will be one or more user data. The collection variable is used to store the user collection, with the required parameters. The result collection is set into state object, for automatically rendering the search results with the help of life cycle method.
  • Life cycle method componentDidUpdate() is used for rendering the search results. 
    • This method is triggerd, whenever there is state object change. Remember, the state object is changed, whenever the search text is changed and the results are loaded.
    • This method uses the adaptive cards for rendering the data. Adaptive card requires necessary schema to be available before rendering the data.
      • themeData variable contains the static schema for displaying the single user data. The following code snippet typically shows, how the users data is rendered using the adaptive card.
      • The schema mentioned has the properties defined with the names {propertyName}. At the time of parsing, these values are set using the string replace methods. The following properties are set, 
        • Name
        • Mail
        • Mobile Phone
        • User Picture - Default outlook picture URL is used, with principal name property for dynamic user info.
    • Once the necessary schema is prepared, the data is displayed using adaptive card's parse and render methods.
The following code snippet shows the entire search / display user functionality.

The entire solution is available here for your reference.

The following snapshot shows the search user component, with user results. (For search text 'n', only two user data listed. This will dynamically expand/render based on the result count.)
SPFx component using MS Graph API and Adaptive Card for searching and rendering user details
SPFx component using MS Graph API and Adaptive Card for searching and rendering user details