Menu Items

Menu Items

Menu Items are used to describe content which can then be placed into a Menu. They are created and exist independently from the Menus which use them. Modifying an existing Menu Item will affect all Menus which reference it.

You can search, modify, create, and delete menu items from the Menu Items page inside your Admin Console. In general you will be able to customize the name and icon of menu items. Be aware that horizontal space inside the Portal Menu is limited, therefore names which are too long will be truncated with ellipses. You can also add searchable metadata to the items, known as tags. These are here to help you manage and organize your items.

System Menu Items

These are the standard menu items that come with DeskDirector. System menu items cannot be created or deleted, but you can customize their name and icon. These menu items are included in every Menu by default.

• Contact Support - This menu item will show the contact the option to either create a ticket or chat with a technician (if the user has Chat permissions enabled)
• Invoices - This will display the Invoices table. This will not display if any ConnectBooster Menu Item's are found in the Menu. This is only visible if user has Invoices permission.
• Learning - Represents the learning center. Once the new menu system has been enabled, top level learning items will instead appear inside the learning center. This is only visible is the Learning Center permissions are enabled for the contact/company.
• Notifications - This will display the notification center. This is only available if notifications are enabled.
• Quotes - With this enabled, the quotes table will be displayed to the contact. This menu item is only available if Quotes permission is set for the contact.
• Tickets - This menu item will show tickets that contacts have access to. By default, it will show tickets he own (open and closed). If "All Tickets" permissions are enabled, he will see the option see all Tickets. Checking this guide on how the ticket list page looks. If the contact is set as an approver, he will see the tickets for approval.

What if I want custom menu items other than the system menu items? Well, you can easily create custom menu items in DeskDirector.

Creating Menu Items

Creating menu items can be easily done via Portal > Menu Items > New Menu Item:

In the Create Menu Item page, you should be welcomed by several forms and checkboxes, the most basic of which is the Name and Icon for the menu item.

Please specify the display name of the menu item, then specify an icon to be used for it. You should be presented with a few options upon selecting the icon form.

Type of Menu Items

After specifying the menu name and icon, you should now choose the type of menu item you want to set up.

Extension Menu

This menu item will embed a static/dynamic website into the portal. You just need to specify the extension site's URL. Among the type of custom menu items listed here, this is the most powerful as this adds a lot of flexibility and functionality to the client portal with the endless possible extensions you can add.

Below the extension site URL form are sections for security and query parameters. Here's a separate guide to learn more about extension menu security and query parameters.

ConnectBooster Menu

This menu item will embed ConnectBooster (invoices and payments) inside the portal. You just need to specify the ConnectBooster site URL.

OneNote Notebook Menu

This menu item will embed a OneNote Notebook into the portal. You should be able to choose from a selection of existing OneNote Notebooks. If you have not created one yet, you can easily create OneNote Notebooks from the DeskDirector Portal.

BiggerBrains

The BiggerBrains menu item will allow your customers to view all the BiggerBrains courses for the given product. You can select which BiggerBrains product you want to show in the menu item.

Extension Menu Items

Sandbox Restrictions

When creating a new menu item and selecting Extension Menu, you should see an overwhelming number of checkboxes that refer to the extension menu item's security and query parameters.

Upon adding an external site as your extension menu, it will be fully sandboxed by default for security.

What is a sandbox?

Sandboxing applies extra restrictions to the content in the frame that you are embedding in your DeskDirector portal. You can read more about sandbox in iframes in this document from MDN web docs.

In simpler terms, a sandbox is meant to protect your DeskDirector users from triggering something from the external site you embedded that will compromise their experience. In DeskDirector, sandbox restrictions can be easily lifted at your discretion.

Lifting Restrictions via Security Templates

To save you the headache of having to research what each sandbox option does, you can easily lift the sandbox restrictions by using security templates.

• I own the site, I know what I'm doing: This template will basically lift all restrictions - no holds barred. This means you trust everything that this site will do when embedded into your portal.
• I know this site, I trust it: This template will allow majority of the restrictions, aside from allowing top navigations and allowing top navigation by user activation. If you wan then enabled, you can always tick them, or just select the first template.
• I found this site, avoid exploits: This template disables both restrictions from above, plus allowing pop-ups to escape. This means that pop-ups can't open new windows.
• I don't trust this site: This basically is opposite of the first template. All restrictions are in place for this option

Extension Menu Item Query Parameters

Query Parameters allow the portal to also pass through certain information inside the query parameters that can be reused by the embedded site. This can be very useful for different scenarios as this adds capability for more personalization to the content on the embedded site.

Example use case of query parameters:

• Use the parameter "Contact Name" to say a simple greeting in the embedded webpage
• Use the Contact Email parameter to check if the email address has been compromised (see https://haveibeenpwned.com/)
• Use the Company Name parameter and have the embedded page open a feed/stream of news that relates to the company.

A working example is discussed here - Dynamic content based on logged in user

The possibilities are endless in using the query parameters to present a more personalized experience for your users.

Dynamic Content for Logged in Users

Basic Setup

There are scenarios, where you want to display customized content for your customer or you have created an awesome internal website that you want to share inside DeskDirector portal, but you only want users who have logged to have access to it and not publicly open to the internet. Below you can see an example of how this can be achieved with Menu Items

This will make use of:

• Dynamic Menus (This is the core feature we're interested in here.)
• Access Tokens
• iFrame Sandboxes
• The DeskDirector API

1. Create a new Menu Item in the Admin Portal under Client Portal > Menu System > Menu Items
   We will use extension menu item for this case. You should enter following fields.
   • Name
   • Icon
   • Website URL
   • Select Access Token inside Query parameters
   • Enable Access Token

     

2. Create or open your preferred Menu Group under Client Portal > Menu System > Menu Groups. (This can either be under a new menu or under the default menu.)
3. Add the menu item you have just created into this collection.
4. Add in handling to consume the access token provided by DeskDirector. (You can see this below.)
   When portal accesses an external website, it will pass an access token in the headers.
   The access token can be extracted and used to query the DeskDirector server if needed (see below for an example on using this to query user info).

   const accessToken = 'get access token from query params';
   
   // Will return something that looks like this:
   // {
   //     "userName": "test@email.com",
   //     "entityId": 188
   // }
   const request = fetch('https://{sub-domain}.deskdirector.com/api/v2/user/client', {
       method: 'GET',
       headers: {
           Authentication: `DdAccessToken ${accessToken}`,
           Accept: 'application/json'
       }
   });
   
   const response = await request;
   const result = await response.json();
   console.log(result);

   You are not restricted with the above API. Pretty much 99% of portal API is allowed to be used with Access Token. With the code above, you can also verify the user. If your website is based on MVC (Model View Controller), then you can verify the user before web page has been returned. If user is unauthorized or incorrect, you can redirect them to different page!
   You can see more API endpoints via your swagger instance at https://{sub-domain}.deskdirector.com/swagger.
   More about API you can read DeskDirector API.

Additional: Access Token Life Cycle

Access token has limited life span. It only available for one hour. For back-end approach, you can authorize user everytime they access on the end point.

For front-end, we will introduce capability for iFramed page to talk to its parent. So, they can ask for more access-token when it is closed to expire.

Additional: iFrame Sandbox

You can read more about sandbox here. Basically, system exposes all the relevant options for iFrame sandbox. If the website is constructed by yourself, feel free to disable sandbox. Else please choose proper security with sandbox.

How the sandbox has been configured is your responsibility. If any information leaks because of incorrect sandbox configuration, then it's your responsibility to take the blame.

It is also true for access token. You can choose to pass access token to the external site, if they use it to retrieve sensitive information about logged in user, then it is also your responsibility on what has happened.

Example Extension Menu Item

1. Unlock host for your Site. To allow CORS, we need to add the extension site's host to DeskDirector. Navigate Advanced > Developer Corner in the Admin Portal and add host at bottom of Developer Corner page.

   

2. Under Client Portal > Menu System > Menu Items, create menu item for extension demo page
3. Setup New Menu Item:
   • Type: Extension Menu
   • Extension Site's URL: https://deskdirectorfiles.blob.core.windows.net/media-public/demo/access_token_demo/access_token.html
   • Enable Sandbox
   • Allow Same Origin
   • Allow Scripts
   • Under Query Parameters, Enable Access Token
4. Navigate to Client Portal > Menu System > Menu Groups then click New Menu.
5. Add new the Extension Demo Page into new menu group by clicking on the Add Menu Item button
6. Save
7. Allow test contact to use newly created menu group. Navigate to Client Portal > Contacts and select your desired contact
8. Under Custom Portal Menu, select the menu group you created earlier

Code and Explanation of Extension Pages

Extension demo page's source can be found here. At the moment, Allow Same Origin for iFrame's SandBox is still required. In the future, we want to make this extension page work even without Allow Same Origin permission.

To identify the user, DeskDirector introduced access_tokens. This means that menu items that are set as extension page and have access_token enabled, will have access_token passed in as query parameter. Which from the source code, we have code to extract it