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

> The Digital Assistant web part is also available in the SharePoint store. To learn how to add apps from the SharePoint store, read the guide on the Microsoft website.

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:

    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.

SharePoint 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.

Digital Assistant web part editor view

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.

Digital Assistant web part configuration pane

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.

Digital Assistant Board in SharePoint page
Board display mode

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

Digital Assistant Card in SharePoint page

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

Digital Assistant Card in SharePoint search results

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.

### Configuring the Card display mode

Cards are identified by their Card ID. To embed a specific Card into SharePoint, you will first need to identify it's ID.

To do so, first navigate to the Cards page in the Digital Assistant administration view.

TBC

You can additionally select a Card Style. This changes the appearance of the Card. Styles available are borderless (none) or a Card-like appearance (Card).

Advanced settings

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.