est Error Handling 02: Run a Child Flow

Error Handling using a Power Automate Child Flow

A few weeks back my colleague Chris Langridge gave some feedback on my ‘A Guide to Error Handling in Power Automate Flow‘ article and asked if I had intended for the error handling steps to be encapsulated within a ‘Child Flow’. I scratched my head and replied what a good idea!

So today I have created a second Cloud Flow with the imaginative name of ‘Test Error Handling 02‘ which calls a Child-Flow named ‘Error Handler‘. Both of which can be found within the updated ‘PoC Flow Error Handling‘ Power Platform Solution, which you can download from my Power-Platform GitHub repository.

Power Platform Solution: PoC Flow Error Handling

Why use a Child-Flow?

Imaging you have a number of Power Automate Flows that are critical to your organisation. In my previous article you would have to recreate the ‘Error Handler‘ scope in each Flow, below each critical step. This would take a lot of time and clicking (or copy and pasting*).

Creating a single ‘Child’ Flow means that you only have to create your message template once and then call it as many times as you require. It has the added advantage of reducing maintenance overheads; for example, if you needed to update the message body, then you only have to update one step (compared to multiple steps and flows).

*At the time of writing this article, using copy and paste within Power Automate Cloud Flows is still in preview and can be temperamental.

Creating the Error Handler Flow

The ‘Child‘ Flow; I started by creating a new Instant Flow within the ‘PoC Flow Error Handling‘ solution called ‘Error Handler‘.

Cloud Flow: Error Handler

I added three input parameters to the manual trigger:

NameTypeDescription
Flow Display NameTextworkflow()?[‘tags/flowDisplayName’]
Flow Instance URLTextconcat(‘https://’,parameters(‘Environment Region (sjlewis_EnvironmentRegion)’),’.flow.microsoft.com/manage/environments/’,workflow().tags.environmentName,’/flows/’,workflow().name,’/runs/’,workflow().run.name)
Scope NameTextPlease enter the name of the last Scope or Step

Note: Two of the descriptions are code snippets required by the Parent Flow(s) to generate the relevant values.

Instant Flow: Manually trigger a flow

Below the ‘Scope: Error Handling | Send Message’ step I have added a branch where I apply True or False to the MessageSent variable, using the ‘run after‘ configurations: ‘has failed’, ‘is skipped’ and ‘has timed out’ to see if the message was sent OK.

Cloud Flow: Branching with logic

I complete the workflow with a ‘Respond to PowerApp or flow’ step and return the following parameters to the ‘Parent‘ Flow:

NameTypeDescription
Message SentYes/NoMessageSent (variable)
Message SubjectTextOutput (Compose: Error Handing | Subject)
Message BodyTextOutput (Compose: Error Handing | Body)

Creating the ‘Parent’ Flow

I took a copy of the original ‘Test Error Handling‘ Flow, and after renaming ‘Test Error Handling 02‘, add it to the solution.

Cloud Flow: Run a Child Flow step

I then moved the ‘Terminate: Error Handing’ step out and below the ‘Scope: Error Handling‘ scope, before replacing it with the ‘Run a Child Flow: Error Handler‘ step. As with the ‘Scope: Error Handling’, the ‘Run a Child Flow: Error Handler’ step uses the following ‘run after‘ conditions: ‘has failed’, ‘is skipped’ and ‘has timed out’.

Cloud Flow: Conditional branching

The only other significant change was to move the ‘Condition: Throw Error‘ in to a Scope, which was to demonstrate how Scopes could be used within the context of error handling. The same could be done for the ‘Run a Child Flow: Error Handler‘ and ‘Terminate: Failed | Error Handler‘ steps to make them easier to copy and paste*.

Conclusion

I am a big fan of code reuse and considering Cloud Flows are just a visual representation of code it makes perfect sense, in my mind, to implement similar patterns and practices.

Using SharePoint REST API to GET List properties: ListItemEntityTypeFullName

While working with the REST API, I seem to forget how to quickly find the ListItemEntityTypeFullName property for a SharePoint List. Here is a quick reminder.

To GET the List properties, enter one of the following example URLs into your browser:

  • https://[TENANT].sharepoint.com/sites/[SITE]/_api/web/lists(‘00000000-0000-0000-0000-000000000000‘)
  • https://[TENANT].sharepoint.com/sites/[SITE]/_api/web/lists/getbytitle(‘[ListName]‘)

To GET on the ListItemEntityTypeFullName property, enter one of the following example URLs into your browser:

  • https://[TENANT].sharepoint.com/sites/[SITE]/_api/web/lists(‘00000000-0000-0000-0000-000000000000‘)?$select=ListItemEntityTypeFullName
  • https://[TENANT].sharepoint.com/sites/[SITE]/_api/web/lists/getbytitle(‘[ListName]‘)?$select=ListItemEntityTypeFullName

See Microsoft’s Working with lists and list items with REST article for more information,

Link within an email warning of an error opens the Flow instance

A Guide to Error Handling in Power Automate Flow

I would like to share how I am currently dealing with errors, within Cloud Flows, using a strategy of actively informing administrators and/or support staff that something has gone wrong.

We are going to start by creating a Power Platform Solution and adding environment variables, a single connection reference and Instant Cloud Flow.

By the end of this post, my intention for you, the reader, to be able to recreate the solution.

Power Automate Solution components
Power Automate Solution components

Building a PoC (proof of concept) Flow

Start by creating a new Power Platform Solution called “PoC Flow Error Handling”. With a few exceptions I almost always create a Power Platform Solution, which has plenty of advantages (out of the scope for this post).

Next, add the following environment variables, setting the default and/or current values to match your environment:

Display NameDescriptionDefault ValueCurrent Value
Email: IT AdminIT Admin team members who will manage and support this solution.it.admin@test.comdev.admin@test.com
Environment NameA label used to describe the environment e.g., DEV, UAT or leave blank for Production. DEV
Environment RegionGet this value from the Flow makers portal unitedkingdom
Environment Variables

Add a connection reference for Office 365 Outlook:

Display NameDescriptionConnectorConnection
PoC FEH: Office 365 OutlookOffice 365 Outlook connection reference.Office 365 Outlook connection reference.service.acc@test.com
Connection Reference

Add an Instant Cloud Flow to the solution called ‘Test Error Handling’.

Open the Cloud Flow and add a Yes|No (Boolean) parameter to the Trigger called ‘Throw Error’.

Directly under the Trigger, I add the following variables:

NameTypeValueNote
FlowInstanceURLString@{concat(‘https://’,parameters(‘Environment Region (sjlewis_EnvironmentRegion)’),’.flow.microsoft.com/manage/environments/’,workflow().tags.environmentName,’/flows/’,workflow().name,’/runs/’,workflow().run.name)}Contains the calculated Flow instance’s URL.
FlowInstanceNameStringTest Error HandlingContains the Flow instance’s name.
CauseErrorBoolean Used for demo purpose.
Power Automate Flow Variables
Power Automate Instant Flow trigger and variables
Power Automate Instant Flow trigger and variables

After variables add a “Condition” step, which is checks the ‘Throw Error’ value:

  • If TRUE then set the CauseError parameter to NULL
  • If FALSE then set the CauseError parameter to FALSE

Note: setting a Boolean variable to NULL will cause the Flow to error.

How to causing an error within a Microsoft Flow
If condition is true, then cause an error within the Microsoft Flow

After the condition, I add a branch and a step to each side:

  • The “Terminate: Succeeded” step implements the default “is useful” run after condition.
  • The “Scope: Error Handling” step implements the “has failed, is skipped, has timed out” run after conditions.
Error handling within a Power Automate Flow
Error handling within the Power Automate Flow

All the error handling “magic” happens within “Scope: Error Handling” step:

  1. The “Compose: Error Handing | Email Subject” step, builds the email subject and error title.
  2. The “Compose: Error Handing | Email Body” step, builds the email body and error message.
  3. The “Send an email (V2)” step sends the email to the email addresses set within the ” Email: IT Admin” environment variable, with the importance set to high.
  4. The “Terminate: Error Handing” step sets the instance of the flow as failed.
Error Handling Cloud Flow
Cloud Flow with error handling steps

Running the Flow

Either run the Flow by clicking on “Test” within the edit screen or clicking on “Run” within Flow’s the details page. Next, select the “Throw Error” toggle switch and then click on “Run Flow”. The Flow will fail as expected and send an email to the address set within the environment variable.

If you would like to test the successful branch, leave the “Throw Error” toggle switch unselected (false or off).

Running a Power Automate Intant Cloud Flow
Running the Power Automate Intant Cloud Flow
Email with the subject of "ERROR: 'Test Error Handling' Flow failed (DEV environment)"
Email subject “ERROR: ‘Test Error Handling’ Flow failed (DEV environment)”
Email Link Opens Flow Instance
Flow instance run history

Summary

I like this technique, because it informs the admin or support directly via an email, which is flagged as high priority, and includes a link directly to the failed instance. This reduces the possibility of an error being missed and saves time locating the cause.

The unmanaged Power Platform Solution can be downloaded from my Power-Platform GitHub repository.

Update

Thank you

Thank you to MacKenzie Bernard for the beer, much appreciated.

PowerShell script to hide or display form fields

Hide or show fields in New or Edit forms

SharePoint Customise Form Menu

Microsoft has made it easier to customise “modern” SharePoint Online Lists and Libraries Forms natively.

But what do you do if you need to managing list is “classic” Form or the edit for option is just not available?

One option is to write a PowerShell script, see example below which will hide or show fields within New or Edit Forms.

This code and other scripts can be accessed in GitHub.

For more information on customising Modern SharePoint Forms, see these Microsoft articles:

SPFx-People-Search

SharePoint/SPFx: Returning to Webpart Development Part #4 (with React Hooks)

Recently I was asked to develop a webpart for a modern SharePoint site. My first thoughts, where do I start; I haven’t done any webpart development for years? I would like to share my journey with you over the next few posts and hope my experience will help new and returning developers along the way.

In my previous post I covered:

In this post I will cover:

This article is different to its predecessors in the series, because I have published the SPFx-People-Search webpart solution to my GuiHub repository, I will be focusing on what I have found challenging about writing this webpart with React Hooks, SPFx and Microsoft Graph.

In the previous article I created the Project Folder Structure with stub files ready to add code. So now I can focus on creating the components such as the Service and User Interface. I deliberated on where to start, creating the Service layer or UI. Deciding to start with a service class called MSGraphService.ts and its corresponding interface.

Note: I have added a data JSON file, however I have more work to do before this can be used for testing in the local workbench.

Service Layer

The MSGraphService is based upon the Service Locator pattern which I took inspiration from an old colleague Vardhaman Deshpande who wrote this article. The MSGraphService files are located here:

Having decided on this pattern and how to implement it, the other challenges I had with the Microsoft Graph API included:

Microsoft Graph User Photo

What to do with the data returned by Microsoft Graph User Photo endpoint. With the lack of documentation, the Graph Explorer is great, but it still took a bit of work to figure out what to do with “Blob Strings” …

Microsoft Graph Explorer Me/User Photo
https://developer.microsoft.com/en-us/graph/graph-explorer?request=me%2Fphoto%2F%24value&method=GET&version=v1.0

See the getUserPhoto() function located within MSGraphService.ts

User Presence

What the different User Presence options are: User may display…? Again, the Graph Explorer was a great help, it went a long way to making up for the lack of documentation.

Microsoft Graph Explorer Me/User Presence
https://developer.microsoft.com/en-us/graph/graph-explorer?request=me%2Fpresence&method=GET&version=beta

See the getUserPresence() function located within MSGraphService.ts and the implementation within ResultCard.tsx

Configure the API permissions requests

This time I can praise the documentation by Microsoft: “To consume Microsoft Graph or any other third-party REST API, you need to explicitly declare the permission requirements from an OAuth perspective in the manifest of your solution.” For more information see https://docs.microsoft.com/en-us/sharepoint/dev/spfx/use-aad-tutorial#configure-the-api-permissions-requests

And my working example of the package-solution.json can be found here: https://github.com/sionjlewis/SPFx-People-Search/blob/main/config/package-solution.json

User Interface

To keep things simple, I kept the PeopleSearchWebPart.ts webparts “main/entry” class, created by the SPFx Yeoman scaffold, pretty much “as is”. Converting this class to React Hook seemed to be more hassle that it was worth.

Using React Hooks with the SPFx framework

So unlike all the React.JS Hook Documentation, I was unable to implement a basic function, but instead I found I needed to write something similar to the following:

export const PeopleSearch: React.FunctionComponent<IPeopleSearchProps> = (props) => { 
    … 
};

Writing the Hooks

Having organised the components into a Project Folder Structure, I started at the top:

  1. Added references and initiated object to PeopleSearchWebPart.ts and passed them on to PeopleSearch.tsx
  2. Updated the IPeopleSearchProps.tsx interface and added each of the “Wrapper” Hooks to the return statement
  3. Focusing on the ResultWrapper, I added the “useState” and “useEffect” Hooks to handle the getFilteredUsersExpanded() data, which I then “mapped” instances of the ResultCard.tsx
  4. Before focusing on details such as User Presence and User Photo, I output the “raw” User data to the user interface from the return statement. I used this technique to confirm that the service layer was connecting to and returning the data as expected

I continued on with this process of working until I “finished” the Results components and then moved onto the Footer and Search components.

You may have noticed that I have not started on the filter components as my strategy is to get something working as quickly as possible, with the following goals:

  • Enables demos and feedback loop to start earlier
  • Test the API(s) to confirm that they work as expected (or documented) and update our strategy if they don’t

Other Stuff

underscore.js vs Lodash

Back in my “JavaScript” days I was a big fan of underscore.js, so I tried it within this project, however I found the library too cumbersome to import and so I ended up replacing it with Lodash which seems to play better with TypeScript.

Conclusion

I am now a self-confessed fan of React Hooks and have really enjoyed the process of building this webpart. As with any new development technique or process, I will find better ways of doing things as I do more, but I like how clean the code looks and reckon the modularity will make the solution so much easier to support.

Siôn Lewis

28/11/2020

When attempting to debug a recently copied SPFx solution I kept seeing the following error displayed by my browser:

Cannot GET /temp/workbench.html

As per usual, I had entered the following command into the VSCode Terminal window:

gulp serve --nobrowser

Selected the Local workbench profile and clicked on Start Debugging, which attempted to opened the following URL with Google Chrome:

https://localhost:4321/temp/workbench.html

The solution to stop this “Cannot GET” error was to enter the following URL:

https://localhost:5432/workbench

This appears to reset the “service, cache or something” causing the error to go away.

Now I can debug as per normal again.

SharePoint/SPFx: Returning to Webpart Development Part #3 (with React Hooks)

Recently I was asked to develop a webpart for a modern SharePoint site. My first thoughts were; where do I start; I haven’t done any webpart development for years? I would like to share my journey with you over the next few posts and hope my experience will help new and returning developers along the way.

In my previous post I covered:

In this post I will cover:

Recommended Reading

The official React website has some fantastic documentation and to avoid duplicating what they have already published I would recommend reading the “Thinking in React” article before we move on. I found the section “Step 2: Building A Static Version In React” particularly useful to kick-off the build of this webpart.

Using React Hooks with the SPFx Framework

The first thing I did was to import the React module using following statement:

import React, { useState, useEffect } from 'react';

When I tried to build the project, I received the following error:

Module '"c:/.../SJLewis.SPFx.Webparts.People/node_modules/@types/react/index"' can only be default-imported using the 'allowSyntheticDefaultImports' flagts(1259)
index.d.ts(46, 1): This module is declared with using 'export =', and can only be used with a default import when using the  'allowSyntheticDefaultImports' flag.

Plus, the React and ReactDom import statements are underlined in red:

React and ReactDom import statement is underlined in red

What is allowSyntheticDefaultImports? It allows default imports from modules with no default export and it does not affect code emitted, it is just typechecking.

How to enable allowSyntheticDefaultImports

Open the tsconfig.json file and add the following code to the “compilerOptions” section:

"allowSyntheticDefaultImports": true

Your tsconfig.json file should look something like this:

allowSyntheticDefaultImports

And now TypeScript is happy…

React and ReactDom import statement are validated

Before moving on to the next step, let’s build the project and commit your changes to source control (just in case we break the project later).

Installing additional NPM packages

We don’t always know all of the packages we want to use upfront, however I like to add what I can upfront. For this example, I am going to add the following npm packages to my project. Enter the commands into the VS Code Terminal window:

And finish by doing some “housekeeping” and confirming that the project builds:

gulp clean
npm shrinkwrap
gulp build

Project Folder Structure

I like to start by creating a folder structure based upon the Components and Services listed within my wire-frame(s) and components list.

People Search Wire-Frame

Component List

Component NameData SourceExpected ResultsComponent Actions
Search Wrapper 
Search BoxGraph UsersZero to more itemsFilter
Search Clear Clear data & filters
Filter WrapperGraph UsersZero to more items
Filter Combo-boxGraph UsersZero to more itemsFilter
Filter Auto-suggestGraph UsersZero to more itemsFilter
Result WrapperGraph UsersZero to more items
Result CardGraph UserOne itemDisplay
Result User PhotoGraph User PhotoOne itemDisplay
Result User PresenceGraph User PresenceOne itemDisplay
Result User ContactGraph UserOne itemDisplay
Footer WrapperGraph UsersZero to more itemsDisplay

Component Folder Structures

Starting with components, add the following folders under this path:

“~\src\webparts\peopleSearch\components\”

  • filters
  • results
  • search

Next, add blank/empty .TSX files for each component:

~\src\webparts\peopleSearch\components\filters\

  • FilterWrapper.tsx
  • FilterComboBox.tsx
  • FilterAutoSuggest.tsx

~\src\webparts\peopleSearch\components\footer\

  • FooterWrapper.tsx

~\src\webparts\peopleSearch\components\results\

  • ResultWrapper.tsx
  • ResultCard.tsx
  • ResultUserPhoto.tsx
  • ResultUsrPresence.tsx      Not required / built into Persona (Office UI Fabric) control
  • ResultUserContact.tsx

~\src\webparts\peopleSearch\components\search\

  • SearchWrapper.tsx
  • SearchBox.tsx
  • SearchClear.tsx

Even thought these files are empty the project should build without any issues, I still like to build the project after every major change I make.

<em>gulp build</em>

Note: “~\” represents the project’s root folder.

Service, Models & Data Folder Structures

I am going to create the folder structure which will be used by the Service, Models & Data files. Start by adding the following folders under this path: “~\src\”

  • data
  • models
  • services

I have not planned exactly what will be created, but here is an overview as to what will go where:

  • The Data folder will contain .JSON files, these will contain mock data for testing the webpart using the local work bench
  • The Models folder will contain .TS files, which will describe the structure of the data respective of where it is stored or accesses from.
  • The Service folder will contain .TS files and classes that will represent the services and will retrieve data either from the mock or live data sources.

Next Steps

Now that I have my project structure laid out, I can focus on creating either the Data & Services or the Components & User Interface. Neither option is wrong, however, because I know more about the User Interface than the Services, that is where I will begin for my next post.

Tip: If you cannot decide on which order to build your webpart(s) take a look at the “Thinking in React” article, you may also find the section “Step 2: Building A Static Version In React” useful.

How to ‘Unblock’ PowerShell files

Frustrated by the warning message on Windows computers “This file came from another computer and might be blocked to help protect this computer“? The warning appears when you try to open a PowerShell file that has come from a 3rd party.

Check Security section

Right-click on a single file and choose Properties and look for the Security section at the bottom of the window:

“This file came from another computer and might be blocked to help protect this computer.”

You can check the box (in Windows 10) or click the Unblock button (in Windows 7/8) to unblock the file.

Unblock multiple files

If you have multiple files and are unable to select them all at once, you will need to manage each file separately to unblock them. If the files were supplied in a ZIP file, make sure you always unblock the ZIP file before extracting the files.

Unblock multiple files with PowerShell

If you have multiple files an alternative is to run the following PowerShell:

dir -Path [directory path] -Recurse | Unblock-File

Note: Don’t forget to replace [directory path].

Windows PowerShell ISE

Configuring SharePoint & Microsoft Teams PowerShell environment

Here is a list of steps that I usually complete when configuring a PC, so that I can run PowerShell script that connects to SharePoint Online and Microsoft Teams.

SharePoint Online Client Components SDK

The SharePoint Online Client Components SDK can be used to enable development with SharePoint Online. …[Microsoft] recommend using NuGet packages rather than installing CSOM assemblies to GAC. However, I find these DLLs useful when writing CSOM directly within my PowerShell scripts. 

Click here to select and download the relevant MSI file.

Open Windows PowerShell ISE as Administrator

To be able to complete the other steps that follow, we need to run the Windows PowerShell ISE as Administrator. If you would like to make this a more “permanent” action, follow these steps:

  • Search for Windows PowerShell ISE and Pin to the Start menu
  • Right click on the pinned tile and click on More and Open file location
  • Locate the Windows PowerShell ISE shortcut, right-click and select Properties 
  • Click Advanced… and select Run as administrator
  • Finish by clicking OK, Apply and OK 

From now on, when opening the Windows PowerShell ISE application from the Start menu, you will be prompted by: “Do you want this App to change your device.” Don’t forget to click Yes.

Note: If you do not open Windows PowerShell ISE with “Run as Administrator” you will not be able to set the Execution Policies. 

Check Your PowerShell Version 

The Microsoft Teams PowerShell Module has some known issues with PowerShell 7.
For the best experience, [Microsoft] recommend that you use PowerShell 5.1. If we are running anything newer than 5.x then you may need to down-grade… 

Run the following PowerShell code to check the PowerShell version

Get-Host | Select-Object Version; 

Execution Policies 

Generally, the execution policies on new machines are set to a level that will restrict the installation and running of our scripts. See the About Execution Policies article for information on how to manage them. Running the following PowerShell cmdlet to see what your current Execution Policy is set to:

Get-ExecutionPolicy;

I usually set my Execution Policy to Unrestricted, by running the following PowerShell cmdlet:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted; 

Install SharePoint Online Management Shell 

The SharePoint Online Management Shell is a tool that contains a Windows PowerShell Module to manage your SharePoint Online subscription in Office 365. 

I would recommend using the PowerShell cmdlet instead of the .MSI files, as the process for updating modules later are simpler. Click here for more information about the SharePoint Online Management Shell.

Run the following cmdlet, in administrative mode, to see if the SharePoint Online Management Shell has already been installed:

Get-Module -Name Microsoft.Online.SharePoint.PowerShell -ListAvailable | Select Name,Version;

Or run the following cmdlet, in administrative mode, to install the latest version of the SharePoint Online Management Shell:

Install-Module -Name Microsoft.Online.SharePoint.PowerShell;

Install PnP PowerShell Library

SharePoint Patterns and Practices (PnP) contains a library of PowerShell commands (PnP PowerShell) that allows you to perform complex provisioning and artifact management actions towards SharePoint. The commands use CSOM and can work against both SharePoint Online and SharePoint On-Premises (depending on the modules installed)

Click here for more information or run the following cmdlet to install the SharePoint Online PnP PowerShell library:

Install-Module SharePointPnPPowerShellOnline;

Install Microsoft Teams PowerShell

Microsoft Teams PowerShell is a set of cmdlets for managing Teams directly from the PowerShell command line.

Warning: There are known issues with PowerShell 7 and Teams PowerShell. For the best experience, we recommend that you use PowerShell 5.1.

Click here for more information or run the following cmdlet to install the Microsoft Teams library:

Install-Module MicrosoftTeams; 

Upgrading PowerShell Libraries

As a rule, I avoid using the Update-Module cmdlet as this results in having multiple versions of the same library installed. Instead, I like to use the Uninstall-Module cmdlet before then installing the latest version.

People-Search Wire Frame Page3

SharePoint/SPFx: Returning to Webpart Development Part #2

Recently I was asked to develop a webpart for a modern SharePoint site. My first thoughts were; where do I start, I haven’t done any webpart development for years? I would like to share my journey with you over the next few posts and hope my experience will help new and returning developers along the way.

In my previous post I covered:

In this post I will cover:

Avoiding Pitfalls Part #1

Let’s start by addressing the pitfalls I listed in my last post:

1. Distracted by someone else’s code

This one is easy; we are going create a new / blank project. If we need to refer to someone elses code for inspiration, then we will do this outside of our project.

2. Getting bogged down in detail

The React website has a great article on this called Thinking in React which I recommend reading. So, let’s practice what we preach….

3. Avoid the muddying of data and presentation code/layers

Well the plan we made to avoid the previous pitfall will also help with this too. If we are still confused it is because we need to do some more planning… 😊

4. Check the SPFx Project Generator Version

The tooling used to scaffold SPFx project is out of date. This should not be a problem if you have just configured a new brand environment/machine. If, however like me you are coming back to an existing environment/machine then I would recommend uninstalling everything SPFx related:

npm uninstall @microsoft/generator-sharepoint --global
npm uninstall yo --global
npm uninstall gulp --global

And finally, Node.js using the “Add or remove programmes…” to check the version and uninstall if required.

Once done, you can re-install the tools with confidence…

Solution Design (Avoiding Pitfalls Part #2)

Let’s start by creating a wire-frame, which essentially is a design without branding or colours. There are many great tools on the market for creating wire-frames, such as Balsamiq, Lucidchart or Microsoft Visio. However for this example, I am going to use Microsoft PowerPoint to demonstrate how easy it is to create an effective wire-frame. Click here to open my People-Search-Wire-Frame.pdf file.

Wire-Frames

Start by adding the components to the diagram, while thinking about how the end-user would interact with your webpart.

People Search Wire Frame Page 1

On the next diagram I have labelled each control, giving a brief description of each control and / or its behaviour. If you are a solo developer you may decide to skip this detail, however, I find the validation process useful.

People Search Wire Frame Page 2

The last page/diagram breaks the webpart down into components. I have done this by functionality, repeatability and in some cases, where the data will come from.

People Search Wire Frame Page 3

Data Sources

Now that I have a design I can start thinking about where the data is going to come from. In the past I may have used SharePoint Search with the User Profile Service, however today I am going to use the Microsoft Graph API, as “The Graph” combines multiple Microsoft 365 services into a single endpoint.

Tip: The Graph Explorer is a great place to start working Microsoft Graph, it has a number of sample queries to run against dummy data or better still sign in to your Microsoft 365 Tenant and test queries against your own data (see my next tip).

Tip: Sign-up to the Microsoft Developer Programme and get a Microsoft 365 developer subscription to develop your solutions independent of your production environment.

The table below lists the components I expect to build, obviously this may change if I find other complexities once the build is under way, plus:

  • The Data Source gives a rough idea as to where to find the data.
  • The Expected Results gives a rough idea of shape of the data.
  • The Component Action describes what the component will do with the data.
Component NameData SourceExpected ResultsComponent Actions
Search Wrapper
Search BoxGraph UsersZero to more itemsFilter
Search ClearClear data & filters
Filter WrapperGraph UsersZero to more items
Filter Combo-boxGraph UsersZero to more itemsFilter
Filter Auto-suggestGraph UsersZero to more itemsFilter
Result WrapperGraph UsersZero to more items
Result CardGraph UserOne itemDisplay
Result User PhotoGraph User PhotoOne itemDisplay
Result User PresenceGraph User PresenceOne itemDisplay
Result User ContactGraph UserOne itemDisplay
Footer WrapperGraph UsersZero to more itemsDisplay
Components List

Choosing a Framework

Just because you are developing a SPFx webpart does not mean you have to build it in React, there are other options, such as “No JavaScript framework” (i.e. hand-rolled or do it yourself) or Angular.

Sorry to disappoint, however I am going to stick with React – React Hooks possibly with useReducer.

Creating a SPFx Project

To help you reproduce my solution I have listed the steps below.

Creating a VS Code Workspace

I am a fan of Workspaces they enable you to save and share preferences including UK/NZ spellings…

  1. Create your project directory, for example:
    C:\…\Company.SPFx.Webparts.People
  2. Open Visual Studio and navigate to: File -> Open folder…
  3. Next locate and open your new directory
  4. Once opened navigate to: File -> Save Workspace As…
  5. Navigate up a folder, enter “Company.SPFx.Webparts.People.code-workspace” and click save

Scaffold the SPFx Project

Now we are ready to open the Terminal window with VS Code and run the Yeoman SharePoint generator.

  1. Open Terminal: [Ctrl]+[`]
  2. Enter the following commands:
yo @microsoft/sharepoint
  1. Next enter: MS-Graph People Search – Press enter
  2. Select: SharePoint Online only (latest) – press enter
  3. Use the current folder – press enter
  4. Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites? – Y
  5. Will the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant? N
  6. Select: WebPart – press enter
  7. What is your Web part name? People Search – press enter
  8. What is your Web part description? Search for people within your organisation using Microsoft Graph – press enter
  9. Select: React – press enter

Once the Yeoman command has completed, we can check the solution by running the following commands:

gulp clean
gulp build
npm shrinkwrap
gulp serve

Source Control

I am going to designate source control out of scope for this post, however what I would recommend committing your code (or backing it up) at this point, so that you have a place you can rollback to if it all goes wrong.

Next time

For my next post I will focus on building the structure of my webpart.