Directory Feature Guide

0   Index

1   Home
2   Approve
3   Event Log
4   Users
5   Settings
   5.1   General
   5.2   Approval
   5.3   Attributes
   5.4   Branding
   5.5   Hyperbot
   5.6   Embed
5.7   Org Directory
6   Collections
7   PowerShell Hooks

 

1   Home

The Home page shows the number of pending changes, the current operational mode of Directory, as well as your organization’s current Active Directory completion summary. Each attribute category listed under ‘Current Summary’ will jump to the relevant section when clicked.

2   Approve

The Approval page is accessible to all Directory administrators and designated approvers. Pending changes are itemized, showing the user who submitted the change, the attribute to be updated, the previous value of the attribute, the proposed new value of the attribute, and the time of submission.

Approvers can approve or reject the changes by clicking the approve or reject button under the ‘Actions’ column. Pending changes can be filtered by clicking on the ‘By Attribute’ or ‘By User’ tabs.

If changes fail to apply, a notification is shown in the upper left hand corner, and failed instances can be shown or hidden.

3   Event Log

The Event Log page provides a view of each action processed through Directory. This includes all profile update submissions, approvals, and commits. Incremental scans, full scans, and administrative actions are also logged.

The filtering options allow for filtering of directory scans, and profile updates, by date range.

4   Users

The ‘Users’ page allows administrators to search for users in Active Directory and view their Directory profile pages, review email communication history, and see which Collection the user is in.

When a search term is entered, possible matches will be displayed below. Items can be expanded to quickly view user details:

Two actions can be taken from the 'Actions' column:

View User Profile - Takes you to a read-only version of the selected user's Directory profile page.

View User Emails - Shows a history of emails sent to the user. Emails can be opened and previewed. This provides an easy method of verifying user experience, and confirmation that the correct message templates are being used if branding/language is different across multiple collections.

5   Settings 

Selecting the ‘Settings’ option from the main menu will produce an additional set of menu options for configuring Directory administrative settings. Make sure to click ‘SAVE’ after modifying any settings to apply the changes.

5.1   General

Directory Mode – Allows you to change between modes of operation:

• Analysis – scans Active Directory only.
• Pilot – scans Active Directory and reaches out to designated Pilot users to collect information
• Run – scans Active Directory and reaches out to all users within the target domain or OU scope

Monthly Report - This toggle will send the Directory Administrators a monthly report with the latest directory health and Directory engagement statistics.

Daily Full Scan – The Daily Full Scan section allows for configuration of full analysis scans of your Active Directory environment. Real time scans are performed every 15 minutes. Full scans are scheduled once per day. Clicking on the full scan time allows you to change the daily scan time using the time picker.

Directory Details – The Directory Details will show different details depending on your implementation type.

Directory Details for Hybrid deployments will show:

• Domain Controller name
• Connection status and ‘Reconnect’ option
• The last successful heartbeat ping (sent every 5 minutes)
• Current Directory Agent version number and a ‘Get Latest’ option

If it is necessary to move the Directory Agent to a different host or re-register the current host machine, clicking the ‘Reconnect’ option will generate a new ten-digit registration code to enter to the Directory Agent installer when prompted.

Clicking ‘Get Latest’ will automatically download the latest version of the Directory Agent to ensure that the latest features and bug fixes are available.

Directory Details for Cloud-only deployments will show:

• The current Global Administrator account that is used to read/write from Azure Active Directory
• The email address of the current Directory Administrator

Directory Scope (Hybrid deployments only) -- Allows for customization of the Directory analysis scope. 

By default, Directory Scope settings are set to analyze the entire directory.

If the 'Specific Organizational Units' option is selected, Include/Exclude OU options, and diagram options become available.

An OU scope can be configured by clicking '- Exclude OUs' or '+ Include OUs'.

OUs can then be selected using the picker. 

To keep track of which OUs are included/excluded, clicking 'Diagram' will produce a map of the Active Directory OU structure. Included OUs are marked green, and excluded OUs, are marked red. Inclusion/exclusion definitions are accented with a ring. 

OUs can be excluded or included in Diagram Mode as well. Clicking on an OU will produce options to Exclude, Include, or Inherit:

Support Contact - This is the email address for the support point of contact for Directory related queries in your organization. The email will be visible at the bottom of the email communications sent out to users, as well as on the bottom of the profile update page.

Audit Scope Filter - Specifc Profile Attributes Filter used to customise fetched profiles for Azure Active Directory when an audit is ran.
During an audit, profiles that were previously outside the scope of the filter, are removed from cache. Filters are passed as-is to the GraphAPI query, the filter structure follows the OData rules.

Directory Administrators - Administrators are people who can log into Directory and review metrics, manage settings, and conduct approvals. Users added here do not need to have access to the directory being managed.

The initial user account used to implement Directory is the default initial administrator. Additional administrators can be added using the people picker. Each user added will receive an invitation once the '+ Add' button is clicked. Users can be removed from this list by clicking the red ‘trash’ icon.

Directory Editors - This user group allows users to edit other user's profiles. This is handy for users in the Human Resources team, that will update information for new employees. Additionally, some organizations have strict guidelines on specific attributes being updated. This allows a designated user to update this information without having to go into Active Directory or Azure Active Directory to update. Finally, there will still be an approval message that goes out to ensure the right governance is taking place for attributes requiring an approval.

To enable a user as an editor, navigate to the Settings tab and scroll down to the bottom. Under Directory Administrators, there is a section labelled Directory Editors. Select the "Add User" at the top right to add any user found in either AD or Azure AD instance.

Once this user is added, they will have the ability to access the user list tab from their profile page. The user can select their profile image at the top right and a dropdown will appear with the option to navigate to the user list tab. This is where the editor can navigate to update other user profiles.

By selecting the User List, the editor will then be presented with the screen below. Where they can search any user and load their profiles.

Lastly, any update that is made by an editor on another user's profile will reflect in the Admin Event Logs. That way, there is a record on who exactly made a change.

Note-Any user already listed as a Directory Administrator is by default, already an editor. They can navigate to the User Tab in the Admin Dashboard to update a user's profile.

 

5.2   Approval

 A list of attributes will be displayed on this page. By default, all attributes will require approval. Toggling the option for auto approve for a specific attribute will allow submitted changes to that attribute to bypass the approval process. This is useful for required employee information not verifiable by the employer such as personal mobile phone numbers.

Timing

The timing section determines when an approver will receive a notification that there are pending updates they require approvals.  These options include;

Immediately-Once an approval is submitted, a notification will be sent to the approver.

Daily-Once a day at a preset time a notification will be sent to the approver until the approval is approved or rejected.

Never- Approvers will not receive notifications. Instead, will need to navigate to the Admin Dashboard to check on pending approvals.

Approvers

Approvers receive notifications of pending approvals and can approve or reject changes. When approvers log in to the Directory web portal, they will be able to see the ‘Approve’ page in addition to the self-service Profile Update Page.

Approvers can be added using the people picker. Each user added will receive an invitation once the '+ Add' button is clicked. Users can be removed from this list by clicking the red ‘trash’ icon.

5.3   Attributes

The Attributes page is used to tailor the overall interaction between Directory and Active Directory user profile attributes. To adjust the location of either a Category or Attribute, select the option and drag it to the desired location.

Attributes

The Attributes feature lists all the attributes that Directory can analyze, sorted by their categories.

Custom attributes in extended AD schemas can be added by clicking the ‘+ Add Attribute’ link. The name of the custom attribute is required.

Note: Custom attributes can be deleted by clicking the ‘trash’ symbol, but core attributes will not have the option to do so. The default categories provided can be removed or renamed.

Clicking on the edit button for an attribute under the ‘Actions’ column allows for modification of Display Name, Hint Text, and Format.

The ‘Display Name’ is how the attribute will be labeled on the Directory Profile Update page.

‘Hint Text’ will provide end users with context and usage information for a given field on the Profile Update Page.

If 'Must Contain a Value' is toggled 'on', the field is required in the Profile Page. 

Form and Hyperbot Options include:

Hidden - Hides the attribute from view on the Profile Page

Read Only - Shows the attribute on the Profile Page, but restricts users from editing the field

Editable - Users can update the value on the Profile Page

Hyperbot and Editable - Users can update the value on the Profile Page, and will receive Hyperbot notifications if the value is missing or out of format

To apply or edit the format, select the 'Validation' tab at the top.

 

"Render As" Types (Validation Formats)

The "Render As" validation option displays a list of formats and allows for editing of default and custom formats.

Each attribute can have a different type of validation format applied, and can be configured to use one of the following render types:

• Autocomplete - a list of options that will provide selections as the field is filled
• Dropdown - a list of options to choose from
• Multiple Freetext - allows users to input multiple freetext items in a tag-like manner 
• Number Input - allows numbers only
• Text Input - allows alphanumeric text entry
• Long Text Input - multi-line text entry
• Toggle - a true or false toggle

 

Profile photos are also validated upon user submission. Clicking the edit button for Profile Picture in the ‘Formats’ section will bring up the validation options.

By default, profile photos will be evaluated for:

• Racy content – excessive amounts of skin
• Adult content – nudity of any kind
• No faces – pictures of animals, cartoon characters, or inanimate objects
• Multiple faces – photos containing more than one individual’s face

Toggling the switch to ‘allow’ any of these validation options will allow the corresponding photo types to be uploaded by users.

Cascading Drop-downs

Cascading drop-downs will provide additional functionality by allowing  organizations to utilize a series of dependent attributes in either drop-down or autocomplete format that can be tied together. This provides the end user with a seamless experience when updating a set of attributes that are dependent on each other.

To create a series of cascading attributes, navigate to the Settings tab, then select 'Attribute' tab. The first step to create a set of cascading drop-down attributes will be determine a parent attribute.  For this example, the goal will be to collect an office location address for a user who is part of a company with multiple office locations. As this is commonly broken up into separate attributes (Country, Street Address, City, State, Zip Code)

For this example, the parent value will be the Country attribute. Ensure the format for this attribute is either an autocomplete or drop-down. Next, populate each option that will be available for end users to choose from in the 'Options section show in the image below.

Once the parent value has been configured, the next step is to setup the sequence of attributes that are dependent from the parent attribute. To do this, navigate to the next attribute that needs to be populated by the end user. In this instance after Country, State would be the next value. Configuration of this attribute is shown in the image below.

After selecting the edit option on the State attribute, navigate to the validation tab. From there, ensure the 'Render As' option is either a drop-down or autocomplete format this format is required all attributes being used with the cascading drop-down feature. Select the ‘Options Cascade From’ and set this to the parent value (for this example, Country attribute). 

Once set, navigate through each parent value option in the drop-down list and populate each value with options available. The image above, illustrates all street addresses within the United States a user can select.  Once complete, save and move onto the next attribute that is planned in the sequence. Replicate this process for each attribute being used. Once completed, when the the end user navigates to their profile page they will be prompted with a wizard like the one shown below. Illustrating a series of values that need to be populated. Each attribute dependent on the attribute above it being populated first. The next image reflects what a populated example can look like. Note the lines on the right-hand side indicating how the attributes are connected. Additionally, as the end user starts to populate each field, the next field will be highlighted in red, indicating that is the next required field in the series to be populated.

 

 

Categories

The Categories feature allows for creation and management of categories that attributes are listed under on the Profile Update Page.

Clicking ‘+ Add Category’ allows for creation of new categories to add attributes to.

The label of the category can be customized and attributes can be added from a drop-down menu.

 

5.4   Branding

Profile Page

The Branding page allows for customization of the Profile Update Page. Header, header text, secondary, and accent colors can be customized with valid CSS color values. Additionally, a corporate logo can be uploaded to be displayed in the header.

The ‘Preview’ button opens a preview of the Profile Update Page with the customizations applied. 

The ‘Reset’ button can be used to reset custom branding values back to default values.

Email Communications

Email communications from Hyperbot can be branded with a company logo in the header of the email. 

5.5   Hyperbot

The Hyperbot settings page is used to configure Hyperbot, the Directory bot personality that reaches out to end-users to collect and confirm profile information.

Hyperbot can be toggled ‘On’ and ‘Off’ using the toggle switch. This can be considered a master switch for all channels of communication.

Contact Channels - Currently, there is one contact channel available for Hyperbot:

Email is the standard channel for Hyperbot communications. By default, Hyperbot will send emails as hyperbot@hyperfish.com

It is possible to configure Hyperbot emails to be sent from an internal Office 365 account. This can be configured by clicking the edit icon next to the Email channel switch:

 Select 'Send from existing email account' and click 'Sign In With Office 365':

Sign in with an Office 365 Global Administrator account, then search for and select the account you wish Hyperbot communications to be sent from:

Personality - The personality can be further customized to suit company culture by using the ‘Personality’ slider to adjust the tone of the interactions with users. This includes “Relaxed”, “Standard”, and “Formal” settings, with “Formal” being the most professional. 

Email Customization - The language contained within Hyperbot communications can be further customized by expanding the 'Email Templates' section beneath Hyperbot Personality settings:

Custom templates can be created for the following communications:

Profile Update Communications:

First Attempt - The first attempt to contact users to ask them to update missing, invalid, or out of date directory profile information.

Reminder - Subsequent attempts to contact users to ask them to update missing, invalid, or out of date directory profile information.

Update Rejected - A profile update has been rejected by the administrator or approver.

Profile Validation Communications:

First Attempt - The first attempt to contact users to ask them to review and confirm or update their profile information.

To customize a template, click the edit button of the communication you would like to update, and the template editor will be displayed:

 

Modify the subject, greeting, introduction, call to action, help text, button text, and signature lines as needed. Then, click the 'PREVIEW' button to see how the email will look, or click 'SAVE' to apply the changes. 

Tenacity - The Tenacity sliders allow for configuration of the frequency in which Hyperbot contacts end-users to collect profile information. The ‘Attempts’ slider configures the number of times users are contacted within the selected frequency.

 

Profile Validation - Profile validation helps to keep directory information fresh by reaching out to users periodically to update profile information.

The initial date and time can be set for Hyperbot to reach out to users. Subsequent validation frequency can be selected from the 'Repeats Every:' drop down. Frequency can range from 1 month to 12 months.

 

The validation email includes the user's current profile information and gives them either the option to Confirm the information, or to Update My Profile (which works the same as the regular profile update magic links). Upon clicking the 'Confirm' button, the user will be taken to a page letting them know that their profile information has been confirmed successfully.

Do Not Disturb - The ‘Do Not Disturb’ feature accepts email addresses of user accounts that should never be contacted by Hyperbot, e.g., users who wish to opt-out. 

5.6  Embed

The Embed section allows you to configure use of embeddable snippets. These are preconfigured code snippets that can be used to embed the web parts (corporate directory and org-chart) on webpages or intranets outside of a SharePoint site.

Authentication Tokens - These tokens are used to communicate from any of your generated code snippets, to the Directory backend, and thus serve the appropriate information back to the user.

To add a token, simply click '+ Add New Token'. This will prompt you for a name, and the purpose.

Existing tokens can be deleted via the button in the Actions column.

Generate Embeddable Snippet - Once a valid authentication token is generated, two buttons appear here to generate a snippet for the Directory, or the OrgChart.

Configure Directory snippet - Clicking on 'Directory' will bring up the below for configuration of the directory snippet.

Configure OrgChart snippet - Clicking on 'Org Chart' will bring up the below for configuration of the Org Chart snippet.

5.7 Org Directory

This section contains the configuration settings for the webparts that are available to users from the Profile update page.

Directory Settings - Configure the directory webpart that will be available from the profile update page for users.

Org Chart Settings - Configure the org chart webpart that will be available from the profile update page for users.

 

 

 6   Collections

With Directory Collections, different settings can be applied to specific audiences of users. In hybrid and environments, Collections are defined by either organizational unit (default), or attribute value (by request). In online environments, Collections can only be attribute-based. 

Collections settings can be accessed from the Collections tab in the navigation pane.

To create a collection, navigate to the 'Collections' page, and click '+Add Collection'.

Pick a name and the organizational units / attribute values that will make up the collection.

Settings can be copied over from an existing collection. 

Each Collection can have its own unique configurations (separate to the master settings) for:

• Approvers

• Required attributes

• Formatting rules

• Branding in Profile Pages and emails

 

Expanding a collection in the collections page will display the configuration summary for that collection.

The expanded view shows whether or not the collection inherits any configured settings from the master collection, as well as the included organizational unit(s). 

Additionally, quick links to the collection's Approval, Attributes, and Branding settings pages can be accessed.

When changing settings for a collection, the collection's name is shown at the top of the settings menu. The search functionality can be used to quickly switch to settings for another collection. 

When customizing attributes and formats, the 'Override Master Settings' toggle switch can be found at the item level in the edit modal dialogue:

 

7   PowerShell Hooks

Note: This feature applies to and hybrid Directory deployments only.

Optionally, PowerShell hooks can be configured to execute custom PowerShell scripts before (pre-update) or after (post-update) attribute commission. 

Two parameters are passed to the scripts:

• The AD property being updated
• The user object GUID

Some usage examples include instantly syncing profile pictures to Exchange Online or SharePoint Online user profiles, and updating SharePoint Online profile (Delve) properties (e.g., About Me, Skills, Past Projects, Schools).

To get started, an example script and implementation instructions can be found at the Hyperfish/scripts Git repository: https://github.com/Hyperfish/scripts/blob/master/PowerShellHooks/PostUpdateScript.ps1 

 

 

If you have any questions around Directory features and functionality, please feel free to reach out to Customer Support via email, Support@livetiles.nyc