{"type":"doc","content":[{"type":"extension","attrs":{"layout":"full-width","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"markdown","parameters":{"macroParams":{"__bodyContent":{"value":"- [Search UI Integration](#search-ui-integration)\n - [Overview](#overview)\n - [Integrate Search UI](#integrate-search-ui)\n - [Prerequisites](#prerequisites)\n - [Usage](#usage)\n - [Bundle](#bundle)\n - [Configuration](#configuration)\n - [Access Token](#access-token)\n - [Web Components](#web-compononents)\n - [Integrate Search UI in SharePoint](#integrate-search-ui-in-sharepoint)\n - [Prerequisites](#prerequisites-1)\n - [Azure Resources](#azure-resources)\n - [Configuration](#configuration-1)\n - [Deployment](#deployment)\n - [Saga Server Configuration](#saga-server-configuration)\n\n## Overview\n\nThis documentation provides instructions on how to integrate Search UI components into 3rd party web applications.\n\nThere are 2 ways to integrate:\n\n1. Directly in web site using [Angular Custom Web Elements](#integrate-search-ui).\n2. In Sharepoint using [SPFX Web Parts](#integrate-search-ui-in-sharepoint).\n\n## Integrate Search UI\n\nSearch UI Integration Angular Elements contain custom web elements that enable integration of Search UI experience in 3rd party web applications.\n\nIt consists of 4 web components: search bar (ayfie-search-bar), search profiles (ayfie-search-profiles), search refiners (ayfie-search-refiners) and search-results (ayfie-search-results) which allows us to define search queries, search profile, refiners, and view results.\n\n### Prerequisites\n\n- Latest bundle from Ayfie downloaded and unzipped to any folder. [Contact Ayfie](https://www.ayfie.com/contact-ayfie) to get the bundle.\n- Dedicated server with Saga platform installed.\n- Dedicated server where your web application will be hosted.\n- Knowledge about web development.\n\n### Usage\n\n#### Bundle\n\nDownloaded bundle contains 2 files and 2 folders:\n\n- `assets` - Folder containing 3rd party libraries and localization files used by the web components\n- `media` - Folder containing definitions of fonts used by `styles.css` file.\n- `main.js` - File containing logic and definition of web components\n- `styles.css` - File containing styles used by the web components\n\n#### Scripts and styles\n\nIn order to use web components, one need to copy all the files from downloaded bundle into the server where web application will be hosted. Then `main.js` and `styles.css` files need to be loaded. It can be done using `script` and `link` tags in the `head` section of `index.html` file like this:\n\n```\n\n\n \n ...\n \n```\n\nBy default, components will attempt to load assets from the `./assets` path in their current location.\nThis behaviour can be changed by setting the `search-ui-elements-assets-url` value in browsers local storage to the URL of the `assets` folder.\n\n#### Access Token\n\nComponents do not provide with a way to retrieve Saga Access Token for the user so it has to be implemented by the developer. It is recomended to use Saga's authority service that utilizes keycloak and implement OAuth authentication with the PKCE. Examplary code on how it can be done can be found [here](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/3842146425/Ayfie+Saga+API+Integration).\n\n#### Web Compononents\n\nOne can simply use web components in `body` section like any other HTML tag.\n\n```\n\n \n \n \n \n\n```\n\n## Integrate Search UI in SharePoint\n\nSearch UI SPFX Web Parts contain SPFX Web Parts that enable integration of Search UI experience in Microsoft Sharepoint sites.\nIt consists of 4 web parts: search bar, search profiles, search refiners and search-results which allows us to define search queries, refiners, and view results.\n\n### Prerequisites\n\n- A Windows, Linux or Mac computer where web parts will be built and pushed to Azure with the following:\n - `node.js` (version >=18.17.1 <19) with `npm` installed. (Exact version is enforced by microsoft libraires).\n - Latest bundle from Ayfie downloaded and unzipped to any folder. [Contact Ayfie](https://www.ayfie.com/contact-ayfie) to get the bundle.\n- A Microsoft 365 organizational account with administrator permission where Sharepoint is running and has been registered.\n- An active Azure subscription (if you don't have one refer to this [documentation](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription) on how to create one).\n- Azure Resource Group. It is recomended to create new dedicated resource group for this plugin (refer to this [documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#create-resource-groups) on how to create one).\n\n### Azure Resources\n\nFollowing resources will have to be created in Azure:\n\n- Azure Entra ID App used to authenticate users\n\n- Navigate to https://aad.portal.azure.com/.\n- Go to `Applications > App registrations`.\n- Create single tenant Entra ID app registration.\n- Save `Client ID` and `Tenant ID` as it will be required later.\n- Go to created app in Azure.\n- In `Manage > Certificates & Secrets` create secret. Make sure to save the value as it will be needed later.\n- In `Manage > Token confguration` choose `Add optional claim`, Token type: `Access`, then in the list that appears check the boxes next to `email` and `upn`, then click `Add`.\n- In `Manage > Token confguration` choose `Add groups claim` check `All groups` then click `Save`.\n- In `Manage > Expose an API` add a scope with the name `user_impersonation`, make sure that `State` is set to `Enabled`.\n- In `Manage > API permissions` add a permissions: from `Microsoft APIs > Microsoft Graph > Delegated permissions` choose `email`, `openid`, `profile`, `offline_access`, from `APIs my organization uses > {created application name}` choose `user_impersonation`.\n- Grant admin consent to all of those permissions.\n- In `Manifest`\n - Find `groupMembershipClaims` property and set it to `\"All\"`.\n - Find `requestedAccessTokenVersion` property in `api` section and set it to `2`. If one can't find `api` section then this might mean this is older version of manifest, in that case find `accessTokenAcceptedVersion` and set it to `2`.\n- Go to `SharePoint Online Client Extensibility Web Application Principal` Entra Id App.\n- In `Manage > API permissions` add a `user_impersonation` permission from `APIs my organization uses > {created application name}`.\n- Grant admin consent to this permission.\n- In `Manage > Certificates & Secrets` make sure that client secret is present. If not go to Sharepoint Admin page > `Advanced > API access` and wait for page to load. Once page is loaded then secret in the `SharePoint Online Client Extensibility Web Application Principal` app should have been created.\n\n- Azure Storage Account\n - Navigate to https://portal.azure.com/.\n - Create Storage Account.\n - In the Resource group drop-down, select the resource group you've created for this purpose earlier (or create a new one).\n - Set `Primary service` to `Azure Blob Storage or Azure Data Lake Storage Gen 2`.\n - Set `Performance` to `Standard`.\n - Set `Redundancy` to `Locally-redudant storage (LRS)`\n - Go to `Advanded` tab.\n - Check `Allow enabling anonymous access on individual containers`.\n - After the deployment finishes, either click `Go to resource` or navigate to the created Storage Account manually.\n - Go to `Security + networking > Access keys` and save `Storage account name` and `key` value of one of the keys as it will be required later.\n - In `Storage browser > Blob containers` add container with `Anonymous access level` set to `Blob`.\n - Save the name of the blob container as it will be required later.\n - In `Security + networking > Front Door and CDN` create new endpoint.\n - Set `Service Type` to `Azure CDN`.\n - Set `Create new/use existing profile` to `Create new`. (this will create new `Front Door and CDN profiles` resource)\n - Set `Profile name` and `Endpoint name`.\n - Set `Origin host name` to `.blob.core.windows.net (Blob)`.\n - Set `Pricing tier` to `Standard Microsoft`.\n - Set `Query string caching behavior` to `Use Query String`.\n - Save the Endpoint host name as it will be required later.\n - Click `Create`\n - Once deployment finishes, press `Deployment details` and go to created Endpoint resource.\n - Go to `Settings > Rules engine`.\n - Press `Add rule`.\n - Fill the name.\n - Press `Add condition` and choose `Request Header`.\n - Set `Header name` to `Origin`.\n - Set `Operator` to `Equals`.\n - Next to `Header Value` press `Edit` and set `Value` to url of ones tenant sharepoint domain e.g. `https://ayfie.sharepoint.com`.\n - Press `Add action` and choose `Modify Response Header`.\n - Set `Action` to `Overwrite`.\n - Set `HTTP header name` to `Access-Control-Allow-Origin`.\n - Set `HTTP header value` to url of ones tenant sharepoint domain e.g. `https://ayfie.sharepoint.com`.\n - Press `Save`.\n\n### Configuration\n\n- Navigate to the folder where zip bundle was extracted to.\n- Open `./Search-UI-SPFX/.env.prod` file.\n - Set `SPFX_APP_NAME` to app name that will be displayed in apps in sharepoint app store. It will not be visible to end user.\n - Set `SPFX_SAGA_GATEWAY_HOSTNAME_URL` to the Saga Gateway Hostname URL (make sure it does not contain `/` at the end) e.g (`https://saga.hostname.com`).\n - Set `SPFX_ENTRA_ID_RESOURCE_ID` to the `Client ID` of created Entra ID application.\n - Set `SPFX_AZURE_STORAGE_CDN_HOSTNAME` to the hostname of the created Azure CDN endpoint.\n - Set `SPFX_AZURE_STORAGE_ACCOUNT` to the name of the storage account created for the integration.\n - Set `SPFX_AZURE_STORAGE_API_KEY` to the value of the access key for the storage account.\n - Set `SPFX_AZURE_STORAGE_CONTAINER` to the name of the blob container created for the integration.\n\n### Deployment\n\n- Navigate to the folder where zip bundle was extracted to.\n- Navigate to `./Search-UI-SPFX` folder.\n- Build web parts and upload assets to the azure storage using this commands:\n\n```\nnpm install\nnpm run ship:prod\n```\n\n- After command finishes there should be `search-ui-spfx.sppkg` file created in `./sharepoint/solution` folder\n- Navigate to `-admin.sharepoint.com`\n- Go to `More Features > Apps` and upload `./Search-UI-SPFX/sharepoint/solution/search-ui-spfx.sppkg` file.\n- Once upload finishes a popup should be displayed to Enable app. Additonally there should be information: `This app gets data from:`, it should point to the url `https:///`.\n- Check `Enable this app and add it to all sites` and press `Enable app`.\n- After this, when creating or editing pages in your SharePoint sites, `Locator Search Bar`, `Locator Search Results`, `Locator Search Profile` and `Locator Search Refiners` will be available in the Toolbox under the Web Parts panel.\n\n### Saga Server Configuration\n\n- Enter the server where Saga is installed.\n- If firewall is configured to restrict incoming traffic then firewall need to be opened to ones tenant SharePoint domain for incoming traffic.\n- Go to Saga installation directory.\n- Stop Saga if running:\n\n```\n.\\stop-saga.p1\n```\n\n- Start saga with `-Configuration` parameter:\n\n```\n.\\saga.p1 -Configuration\n```\n\n- Go to `Advanced`.\n - Set `Saga CORS Allowed Origins` to the host name of SharePoint domain without the `https://` prefix.\n- Go to `Advanced > Microsoft Entra Authentication`.\n - Set `Client ID` to `Client ID` of created Entra ID App.\n - Set `Client Secret` to `Client Secret` of created Entra ID App.\n - Set `Tenant ID` to `Tenant ID` of created Entra ID App.\n- Exit configuration menu.\n"}},"macroMetadata":{"macroId":{"value":"e79d66c7-af1e-45fd-972c-09967bf28ea4"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://d27i9fmzbobp10.cloudfront.net/markdown-mark.png"}}],"title":"Markdown"}}}}],"version":1}

Ayfie Saga Search UI Integration