How to embed Cards into SharePoint

Digital Assistant can be embedded in SharePoint Online websites, in the form of a client-side web part. Follow the instructions below to install the Digital Assistant web part on your SharePoint tenant, connect your Digital Assistant to SharePoint and configure the web part.

You will need to complete the installation process with a user account that has sufficient privileges.

1. Install the web part

An App Catalog administrator must install the web part into the App Catalog for your tenant. Ensure you are logged into your SharePoint site with an account with sufficient privileges.

Full documentation on installing web parts is available on the Microsoft website.

The Digital Assistant web part is available here. Download the latest version of the file adenin-digital-assistant.sppkg to a location on your computer.

To install the web part into the App Catalog:

1. Navigate to your App Catalog site. To do so:

   • Go to the More features page of the new SharePoint admin center and sign in with an account that has admin permissions for your organization
   • Under Apps, select Open
   • Select App Catalog

   If you don't have an existing App Catalog site, follow the instructions here to create one.

2. Select the tile labeled Distribute apps for SharePoint

3. Select Upload, then upload the downloaded file adenin-digital-assistant.sppkg.

4. When prompted, select Deploy.

When deploying the web part, you can choose to deploy the web part to all sites. Enabling this means the web part will be immediately visible in the web part picker in both classic and modern pages across all sites.

If this option is enabled, proceed to 2. Configure SSO.

If this option is not enabled, you will need to deploy the web part to your site. To do so:

1. On the App Catalog site, click Settings and then click Add an app.
2. Select adenin Digital Assistant, then select Trust It when prompted.
3. On the site where you want to deploy the web part, click Settings and then click Add an app.
4. Select From Your Organization from the left navigation.
5. Select adenin Digital Assistant to add it to your site.

The web part will now be available for use on your site.

2. Configure SSO

The Digital Assistant web part uses Single Sign On to automatically log users into their personal Assistant. To enable this functionality, a user with administrator privileges must approve the adenin Digital Assistant SSO AD application.

Ensure you are logged into your SharePoint site with an account with sufficient privileges, then navigate to this link to add the application to your organization.

You will be prompted to accept the permissions request. Select Accept to continue. When successfully authorized, the web part will be accessible to all users.

3. Enable the SharePoint Online Add-in channel in Digital Assistant

To connect the web part to your Digital Assistant, you will need to enable the SharePoint Online Add-in Channel in the Digital Assistant administration view.

Navigate to the Channels page in the Digital Assistant administration view. Ensure you are logged into a Digital Assistant tenant adminstrator account.

Click the toggle switch next to SharePoint Online Add-in to switch the Channel on. A modal will open to prompt you to configure the Channel.

In the section labelled Whitelist domains that may embed Digital Assistant, you can enter a comma-separated list of domains that can embed Digital Assistant.

You must enter the URLs of any SharePoint tenants you have deployed the web part to, as Digital Assistant will not be able to display content in the web part otherwise.

Click Save once you have entered all URLs into the box.

Next, copy the API URL to your clipboard or make a note of it somewhere. You will need it in the next step.

Finally, click Enable to enable the integration.

The Channel should now show as being On. If you need to make any changes to the whitelisted domains or access the API URL, select Manage to view the settings modal.

4. Configure the web part

To use the Digital Assistant web part, begin by inserting the web part in a page using the web part picker.

In the page editor view, the current web part configuration is displayed. If the web part has not yet been configured, you will be prompted to do so. In the normal page view, you will see your Assistant embedded according to the display mode you select.

To configure the web part, click on the Configure button, or alternatively the pencil icon to the left of the web part. The configuration pane will open on the right of the screen.

The configuration options are detailled below.

Assistant API URL: identifies your Digital Assistant instance to the web part.

Enter the URL provided in step 2 of the Enable SharePoint Online Add-in modal you accessed during 3. Enable the SharePoint Online Add-in channel in Digital Assistant.

Display mode: The Digital Assistant web part supports multiple display modes, which enables you to embed Cards in different formats on SharePoint pages.

Available display modes include:

Board: Shows the currently logged in user's board, including all of their pinned Cards.

Card: Shows a single Assistant Card, identified by the Card's ID.

Search results: Shows Digital Assistant Cards alongside search results on custom search pages.

The Search Results Card works together with the PnP Modern Search web parts to show relevant Cards from connected apps in Search Results. Click here to learn how to create a custom search page using the Search Results Card.

After configuring the web part, switch back to read mode by saving the page as a draft or publishing your changes. Digital Assistant Cards will now be visible on the page, depending on your configuration settings.