Merge pull request #3409 from microsoft-search/develop

v4.10.0

Author: wobba

.github/workflows/publish.yml

@@ -18,10 +18,10 @@ jobs:
               with:
                   ref: develop
             # setup nodejs
-            - name: Use Node.js 14
+            - name: Use Node.js 16
               uses: actions/setup-node@v2
               with:
-                  node-version: 14
+                  node-version: 16
                   registry-url: "https://registry.npmjs.org"
             # cache node modules
             - name: Cache node modules

.github/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x]
+        node-version: [16.x]
 
     outputs: 
       majorMinorPatch: ${{ steps.setoutputs.outputs.majorMinorPatch }}

README.md

@@ -24,6 +24,15 @@ contact [[email protected]](mailto:[email protected]) with any additio
 
 ## "Sharing is Caring"
 
+## "PnP Modern Search Office Hours"
+If you are stuck on an issue or just need a peer review of your PnP Modern Search based idea, we have Office Hours.
+
+You can sign up for a 15 min timeslot and a member of the community will set up a Teams call, where you can show and tell about the issue.
+Office hours is every second Tuesday at mid afternoon UTC(0). 
+
+Sign up [here](https://aka.ms/pnp/modernsearchofficehours), and please note that not all requests might be granted if there are more requests than timeslots.
+
+
 ## Disclaimer
 
 **THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**

docs/assets/NoAccessError.png

@@ -189,7 +189,8 @@ Here are the list of all **reusable** web components you can use to customize yo
     data-secondary-text="Unknown"
     data-tertiary-text=""
     data-optional-text="514 928 0000"
-    data-persona-size="" >
+    data-persona-size=""
+    data-native-lpc=true >
 </pnp-persona>
 ```
 
@@ -201,6 +202,7 @@ Here are the list of all **reusable** web components you can use to customize yo
 |**data-tertiary-text**|The tertiary text to display (ex: work phone).
 |**data-optional-text**|The optional text to display.
 |**data-persona-size**|The size of the persona **item** to display (no only the picture). Valid values are <ul><li>tiny = 0</li><li>extraExtraSmall = 1</li><li>extraSmall = 2</li><li>small = 3</li><li>regular = 4</li><li>large = 5</li><li>extraLarge = 6</li></ul>
+|**data-native-lpc**|Enable SharePoint native Live Persona Card on hover.
 
 ## `<pnp-img>` 
 - **Description**: Display an image with support for fallback behavior.

docs/assets/installation-enable-app.png

@@ -1,20 +1,21 @@
 # Installation
 
-1. Download the latest SharePoint Framework packages **pnp-modern-search-parts.sppkg** from the [GitHub repository](https://github.com/microsoft-search/pnp-modern-search/releases).
-2. Add **pnp-modern-search-parts.sppkg** to the global tenant app catalog or a site collection app catalog. If you don't have an app catalog, follow this [procedure](https://docs.microsoft.com/en-us/sharepoint/use-app-catalog) to create one. 
+1. Download the latest SharePoint Framework packages **pnp-modern-search-parts-v4.sppkg** from the [GitHub repository](https://github.com/microsoft-search/pnp-modern-search/releases).
+2. Add **pnp-modern-search-parts-v4.sppkg** to the global tenant app catalog or a site collection app catalog. If you don't have an app catalog, follow this [procedure](https://docs.microsoft.com/en-us/sharepoint/use-app-catalog) to create one. 
 
-    !["App Catalog "](./assets/app_catalog.png){: .center}
+    !["App Catalog "](./assets/installation-enable-app.png){: .center}
 
     > * The packages are deployed in the general Office 365 CDN meaning **we don't host any code**.
 
-    > * For the **pnp-modern-search-parts.sppkg** package, you can choose to make the solution available in [all sites](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/tenant-scoped-deployment) or force to install an app to the site every time.
+    > * For the **pnp-modern-search-parts-v4.sppkg** package, you can choose to make the solution available in [all sites](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/tenant-scoped-deployment) or force to install an app to the site every time.
 
     > * The solution asks the following API permissions by default to enhance the experience. These permissions are **not mandatory**. If you don't accept them, you will simply have less available features.
 
     > * You can approve scopes from the API Access screen in the SharePoint Admin Center: https://<tenant>-admin.sharepoint.com/_layouts/15/online/AdminHome.aspx#/webApiPermissionManagement If you'd like more details on this step, please see the [Approving Scopes](#approving-scopes) section below.
 
     | Requested API permission | Used for |
     | -------------- | --------- |
+    | _Presence.Read.All_ | Read presence information of all users in your organization.
     | _User.Read_ | The Microsoft Graph Toolkit [persona card](https://docs.microsoft.com/en-us/graph/toolkit/components/person-card#microsoft-graph-permissions) in the people layout.  |
     | _People.Read_ | Same as above.
     | _Contacts.Read_ | Same as above.
@@ -27,9 +28,9 @@
     | _Bookmark.Read.All_ | Allow search for Bookmarks in Microsoft Search in your organization.
     | _Acronym.Read.All_ | Allow search for Acronyms in Microsoft Search in your organization.
     | _Chat.Read_ | Allow search for Teams messages.
-    | _ChannelMessage.Read.All_ | Same as above.
+    | _ChannelMessage.Read.All_ | Read user channel messages.
 
-3. Add the Web Parts to a SharePoint and start building!
+4. Add the Web Parts to a SharePoint and start building!
 
 !["Available Web Parts"](./assets/webparts.png){: .center}
 
@@ -44,3 +45,14 @@ You'll need to approve each request one at a time. If you have questions about w
 After you approve each request your view will be as shown in the screenshot below.
 
 !["App Catalog"](./assets/api-access-approved.jpg){: .center}
+
+
+## Note about Guest users
+
+By default guest users do not have access to the App Catalog. So if you are not using the CDN option, any SPFx web part from the App Catalog will show an error message for guest users:
+![No Access Error](./assets/NoAccessError.png){: .center}
+
+There are basicly two options to solve this issue,
+give guest users access to the App Catalog (read) or use the CDN option.
+
+see [this](https://laurakokkarinen.com/sharepoint-online-guest-user-troubles-and-how-to-get-past-them/) for more information.

docs/extensibility/web_components_list.md

@@ -0,0 +1,41 @@
+
+A common requirement for intranets is to show birthdays of employees. 
+And as the SharePoint User Profile Application has a property for birthdays, it is a natural choice to use search to show birthdays of employees.
+
+(as of writing this (2023), the Graph API does not have a property for birthdays, so we can't use the Graph API to get the information)
+
+
+
+The tricky part is that in the User profile application the birthday value is store is a rather usual datatype "date no year"
+
+![Birthday in the User Provisioning Service](../assets/../scenarios/assets/Setup-Results-web-part-to-show-birthdays/BirthdayUPA.png)
+
+
+In my tenant the SPS-Birthday property was mapped to RefinableDate00 and the actual value in the property is 2000-[the date]:
+
+![Managed Property value](../assets/Setup-Results-web-part-to-show-birthdays/refinabledate00.png)
+
+(use the magnificent [SP Editor tool](https://chrome.google.com/webstore/detail/sp-editor/ecblfcmjnbbgaojblcpmjoamegpbodhd) or [SP Search Query Tool](https://github.com/pnp/PnP-Tools/blob/master/Solutions/SharePoint.Search.QueryTool/README.md) to inspect the managed properties)
+
+
+
+So, the query had to be something like "those accounts where RefinableDate00 = 2000 + the value of today's date
+
+
+
+In KQL we have the token "today" that will give us today's date, but as far as I know, we can't get the components the date consist of, like Month and Day.
+
+Luckily, the PnP Modern search provides additional Tokens, see [Tokens](https://microsoft-search.github.io/pnp-modern-search/usage/search-results/tokens/)
+
+
+
+So the final query is:
+
+**RefinableDate00=2000-{CurrentMonth}-{CurrentDate}T00:00:00Z**
+
+
+
+( and of cause a criteria to exclude former employees, like SPS-HideFromAddressLists<>1) 
+
+![Birthday web part](../asserts/../scenarios/assets/Setup-Results-web-part-to-show-birthdays/birthdays.png)
+

docs/installation.md

@@ -0,0 +1,102 @@
+
+Getting PnP Modern Search to show work anniversaries should be easy enoght, right? Just add a couple of managed properties and a couple of web parts and you are done. Well, not quite.
+
+The problem is that date manipulation in KQL is hard at best and sometimes impossible. In order to find a work anniversary you must compare Today and the Hiredate managed property, but ONLY the day and month part.
+
+Calculating how many years the employee has been with the company is also required and it seems like there is no way to get that using KQL.
+
+![upa](../scenarios/assets/Setup-Results-web-part-to-show-work-anniversaries/upa.png)
+
+## Objective 
+
+We want to be able to display two options: 
+- Employees having a work anniversary today, and also how many years they have been with the company
+- Employees having a work anniversary within the next 7 days + number of years.
+
+## How to cheat
+In order to achieve the objectives, I had to get:
+- The account 
+- The hiredate, but with the year segment being the current year
+- The number of years the employee has been with company at the next anniversary
+
+![birthdayAndHiredateSynclist](..\assets\Setup-Results-web-part-to-show-work-anniversaries\BirthdayAndHiredateSyncList.png)
+
+Lets add birthdayThisYear while I was at it, in order to be able to show upcoming birthdays.
+
+
+The basic idea is that we want to change the hiredate from eg. 10/26/2005 to 10/26/2023 as that allows us to compare Today with this value 😀
+(RefinableDate12 is mapped to the HiredateThisYear property)
+
+Who is having a work anniversary today?
+
+  *RefinableDate12=Today*
+
+Anniversary within the next x days is also a piece of cake:
+
+ *RefinableDate12<{Today+7} AND RefinableDate12>{Today}*
+
+## Implementation
+Asking the intern to keep the list above in sync would be a cruel and unusual punishment, and hence actually forbidden in the USA, something to do with a constitution or something like that.
+
+The list should of course be synced with the source, in this case the User Profile Application, at least once each month. The reason I am not using Graph is that birthday is not in the schema.
+
+![mapping birthday and hiredate](../scenarios/assets/Setup-Results-web-part-to-show-work-anniversaries/mapping1.png)
+
+**Prereq: Map SPS-Birthday and SPS-Hiredate to RefinableDate00/01 or similar**
+
+Once data is showing up in those RefinableDate properties you should be ready to create the list.
+Grab the script here . It will create a few Site Columns and a Content type on the site collection of your choosing. The list is then created, and the Content type added to the list.
+The Add-UserDataToList function will query the UPA for accounts and write the data we need to the list.
+ 
+Hit the Reindex site in the site collections Search and Offline Availability section for the site columns to be picked up by search.
+
+Map the crawled properties to a couple of RefinableDates. If possible it is recommended to make this mapping on the tenant level as it ensures that you can use them in your entire tenant. 
+![mapping birthdaythisyear and hiredatethisyear](../scenarios/assets/Setup-Results-web-part-to-show-work-anniversaries/mapping2.png)
+Find the Content Type ID of the Content type created by the script.
+
+
+Add a Results web part, name it "Todays work anniversaries"
+
+Set the Query template to: 
+
+*Contenttypeid:0x01009290F0FA40E7CB42B55D6D96F897262B\* RefinableDate12=Today*
+
+*(replace 0x01009290F0FA40E7CB42B55D6D96F897262B with the value for the your content type)* 
+
+Add a Results web part, name it "Upcoming anniversaries (7 days)"
+
+Set the Query template to: 
+
+*Contenttypeid:0x01009290F0FA40E7CB42B55D6D96F897262B\* RefinableDate12<{Today+7} AND RefinableDate12>{Today}*
+
+*(replace 0x01009290F0FA40E7CB42B55D6D96F897262B with the value for your content type)* 
+
+
+
+Add the managed properties birthdayhiredateAccountOWSUSER, nextWorkAnniversaryInYearsOWSTNMBR, RefinableDate10, RefinableDate12 to the Selected Properties in both web parts.
+
+Enter Layout slots
+
+Change UserEmail to use the  birthdayhiredateAccountOWSUSER property
+
+Change Date from Created to RefinableDate12
+
+For both web parts you can select the People layout on "page 2" in the web part configuration.
+
+Set Secondary text to: 
+
+{{{Title}}} has been with us {{{nextWorkAnniversaryInYearsOWSTNMBR}}} years
+
+(remember to click Use Handlebars expression)
+
+Set Tertiary text to:
+
+{{getDate (slot item @root.slots.Date) "MMMM-D"}}
+
+(remember to click Use Handlebars expression)
+
+Set the sorting on the Upcoming Anniversaries to RefinableDate12 asc
+
+Run the Add-UserDataToList  function in a runbook or similar once a month and you should be done😊 Near the end of the year you might need to run is once per day.
+
+![final result](../scenarios/assets/Setup-Results-web-part-to-show-work-anniversaries/anniversaries.png)

docs/scenarios/Setup-Results-web-part-to-show-birthdays.md

@@ -48,10 +48,19 @@ With the Modern Search Web Parts you can create a simple and useful Department W
 ## [Use query rules for promoted links](Use-query-rules-for-promoted-links.md)
 With the Modern Search Web Parts you can show promoted links for important results. They will be configured with query rules in the SharePoint Search Admin Center. Promoted results will show users more informations and direct links about specific, predefined, terms they searching for.
 
-## [Use query string from URL for dynamic search](use-query-string-in-url.md)
 This scenario describes how to use query string as value in the URL from the current page. You can use URL query string parameters to build dynamic search pages.
 Use a library with metadata that you can use the query string parameter in the URL.
 
+
+
+## [Setup Results web part to show birthdays](Setup-Results-web-part-to-show-birthdays.md)
+A common request in any intranet is to show birthdays of employees. This scenario describes how to use stock SharePoint search to show birthdays of employees in the search results. 
+
+
+## [Setup Results web part to show work anniversaries](Setup-Results-web-part-to-show-work-anniversaries.md)
+
+Showing the work anniversaries of employees is a common request in any intranet. This scenario describes one way to achive this using a sleight of hand trick/cheating as the search index does not contains the information we need. 
+
 ---
 
 More to come!

docs/scenarios/Setup-Results-web-part-to-show-work-anniversaries.md

@@ -30,14 +30,16 @@ You can use the default configuration.
 There are two options available to use the Query String parameter from the URL. You only need one of the options.
 
 ### Option 1
+
 #### Configure Web Part Connections
 Activate the "use input query text" connection in the existing Results Web Part. Configure "Page environment" as source, "Query string" as page environment property, "Query parameters" as query string property. 
+
 You will miss the "Event" Query String from the URL on this time. Add your query string to the URL manually and your query string is available in the configuration. Use the query string "Event" in the queryParameters properties drop down in the Web Part configuration.
 
 As example:
-Full URL: https://[TENANT]/sites/[SITEURL]/SitePages/[PAGE].aspx?Event=Teams Nation&Mode=Edit
-Query String: Event=
-Value: Teams Nation
+* Full URL: `https://[TENANT]/sites/[SITEURL]/SitePages/[PAGE].aspx?Event=Teams Nation&Mode=Edit`
+* Query String: `Event=`
+* Value: `Teams Nation`
 
 ![configure query string parameter](assets/use-query-string-in-url/query-string-parameter.png)