June 2022

TABLE OF CONTENTS

• Overview
• Scope
• Access / Bill of Materials
• Extracting the Install Package
• Create the Azure App Registration
• Request Access to Microsoft Teams Message Data
• Create the Yammer App Registration
• Deploy the Azure Resources
• Troubleshooting Azure Deployment Issues
• Deploy tyGraph Pages Resources
• Install the tyGraph Pages Engine
• tyGraph Pages Graph API Access
• Install the Pages Web Part
  • Add the Site Analytics Web Part to a page
  • Configure the Site Analytics Web Part
    • Configure Authentication
    • Configure Reports
    • Configuring the Data Source
    • Specifying which site to display reports
      • Configuring Caching
      • Configuring Additional Options
    • Configuring filters
    • Toggling between visualizations and data view
  • Saving your configuration
  • Configuring the Report Panel
  • Using the web part in Microsoft Teams
• Enable Access to tyGraph Resources
• Install and Run the tyGraph Harvester
  • Office 365 Configuration
  • Azure Tenant Configuration
  • Yammer Network Configuration
  • Cognitive Services Configuration
  • Configure Email Notifications
  • Deploy the Harvester Webjobs
  • Start the Initial Harvest
• Configure the Daily Harvest
• Connect the tyGraph Pages Report
• Option A: Connect tyGraph Reports using a VNet Gateway
• Option B: Connect tyGraph Reports using IP Whitelisting
• Troubleshooting Power BI Report Refreshes

Overview

This article is intended to give detailed instructions on how to deploy tyGraph, a reporting and Analytics tool for actionable insights on Office 365.

tyGraph pulls data from Office 365 using webjobs daily and stores the information in an Azure SQL Database. Canned PowerBI reports and Dashboards are used to pull data from the Azure SQL Databases for the actionable insights

Scope

The purpose of this article is to provide operational documentation for deploying tyGraph, a reporting and Analytics tool for actionable insights on Office 365, in the Azure environment.  The primary audience of the document are implementation engineers. It should be used to understand the practices and procedures to be adhered to for the application.

Access / Bill of Materials

• Azure:
  • Ability to create and consent to Azure App Registrations
  • Access to create resource groups and Azure resources (SQL Server, App Service, App Service Plan, Cognitive Services, VNet)
• Yammer:
  • Yammer Service Account (must be a Verified Admin, which is different from an Azure Global Admin)
• A current version of SQL Server Management Studio (SSMS)
• Power BI (Ideally Power BI Pro or a Power BI Premium Capacity)
• Admin access to Office 365
• Admin Access to Power BI

Extracting the Install Package

1. Download the deployment package from the link provided by the tyGraph team.
2. Right-click on the deployment package ZIP file and select "Properties". If there is an option to "Unblock" the file, select it and hit Apply. IMPORTANT: Proceeding with a blocked ZIP file will prevent the package from extracting properly and can cause the update to fail.
3. Extract the deployment package. It contains an ARM Template for Azure resource deployment, a .CER certificate file, the SharePoint packages for tyGraph Pages, a folder of Diagnostic Scripts, and the Admin Console for tyGraph installation and management.

Create the Azure App Registration

1. Log in to the Azure Portal with an Administrator account.
2. In the search box, type "App registration" or in the Azure Portal, select "All Services", then "App Registrations" in the "Other" category. 
3. Once in the App Registrations blade, click "New registration".
4. In the registration blade, give the App Registration a name. The remaining settings can be left as the defaults.
5. In the Overview panel of the new App, record the Application ID for use during configuration.
6. From the left-hand menu in your App Registration, select "Certificates and secrets".
7. Click the button for a "New client secret".
8. Click "Add" to create a new secret.
9. Record the secret value for use during configuration. Note: Make sure to copy the secret down immediately, as it will disappear once you leave the page.
10. Click the "Certificates" tab.
11. Click "Upload Certificate".
12. Click the browse button, and select the .CER file provided with your installation package.
13. The certificate will be installed on the App Registration.
14. On the left menu, click "API Permissions".
15. Click "Add a permission".
16. Select "Microsoft Graph".
17. Click "Application Permissions".
18. Find and select the appropriate permissions for the tyGraph products you will be using. (For a full explanation of tyGraph permissions, see the tyGraph Compliance Whitepaper).

    	tyGraph Enterprise	tyGraph Pulse	tyGraph for OneDrive	tyGraph for SharePoint	tyGraph for Teams	tyGraph for Yammer
    ChannelMessage.Read.All	X				X
    Directory.Read.All	X	X	X	X	X	X
    Files.Read.All	X			X	X
    Group.Read.All	X	X	X	X	X
    Reports.Read.All	X	X	X	X	X	X
    Sites.Read.All	X			X	X
    User.Read.All	X	X	X	X	X	X

    
19. Once you have selected all the necessary permissions for the tyGraph products you will be using, click the "Add permissions" button.
20. Click the "Add a permission" button again.
21. Scroll down and select the "Office 365 Management APIs" button.
22. Select "Application Permissions", check the ActivityFeed.Read box, and click "Add permissions". (The ActivityFeed.Read permission is required for all tyGraph products).
23. Click the "Add a permission" button again.
24. Scroll down and select the "SharePoint" button.
25. Select "Application Permissions", check the Sites.Read.All box, and click "Add permissions. (The Sites.Read.All permission is required if using tyGraph Enterprise, tyGraph Pulse, tyGraph for OneDrive, tyGraph for SharePoint, or tyGraph for Teams). 
26. You will see that the various permissions are listed with a status of "Not granted".
27. To grant consent to the permissions, click the "Grant admin consent" button.
28. Click "yes" to continue.
29. The list of permissions will change to a "Granted" status.

Request Access to Microsoft Teams Message Data

You can skip this section if you will not be using tyGraph for Teams.

1. Open the Microsoft Teams Protected API Access Form.
2. Fill out an email.
3. Enter the publisher information and the Application ID you recorded earlier.
4. You can skip step 5 (leave this blank).
5. Select "Reporting and analytics" for step 6.
6. Answer step 7 with "To perform analytics on Microsoft Teams data.", then select "It is obvious to any admin installing this app that it will make a copy of Microsoft Teams messages." for step 8.
7. Fill in your Azure Tenant ID (located in your Azure Active Directory’s Overview page) and indicate that you own the tenant:
8. Answer "Yes" for steps 11 & 12, then click "Submit".

Create the Yammer App Registration

You can skip this section if you will not be using tyGraph for Yammer.

1. Log in to Yammer using a Verified Admin service account.
2. Switch the UI to disable the "New Yammer" experience for now.
3. Navigate to the Yammer Client Applications UI.
4. Click "Register New App".
5. Fill out the form as follows:
   • Application Name: tyGraph (YOUR ORG NAME HERE)
   • Organization: tyGraph
   • Support e-mail:

      help@tygraph.com

   • Website:

      https://tygraph.com

   • Redirect URI:

      https://www.yammer.com

6. Record the Client ID and Client Secret from this page for use during configuration.
7. Open a new browser tab and navigate to the following URL (after replacing the appropriate section with the Client ID you have just recorded).

   https://www.yammer.com/dialog/oauth?redirect_uri=https://www.yammer.com&client_id=CLIENTID

8. Click the "Allow" button on the consent page that appears.
9. You will be redirected back to the Yammer home page. Your browser's URL bar will now have a "code" value. Copy this value down for use in the next steps.
10. Open a new browser tab and navigate to the following URL (after replacing the appropriate sections with the Yammer Client ID, Client Secret, and the Code value that was just retrieved).

    https://www.yammer.com/oauth2/access_token.json?client_id=CLIENTID&client_secret=CLIENTSECRET&code=CODE

11. The browser window will open a JSON file containing information about your Yammer network. Record the "network_id", "network_permalink", and "token" values for use in configuration.

Deploy the Azure Resources

1. Open the Azure Portal and click "Create a Resource".
2. Search for “template” and select “Template deployment (deploy using custom templates)”
3. Click "Create".
4. Click "Build your own template in the editor".
5. Click the "Load file" button.
6. Select the ARM Template file included in your tyGraph Deployment Package.
7. Click "Save".
8. Create or choose a Resource group to deploy your tyGraph resources into. Choose a SQL Server Name, a SQL Server Admin username, a SQL Server Password, and an App Service Name. You may also change the App Service Plan Name, the Sentiment Analysis Name, and the VNet Name if you want. Once you are done, click "Review + create".
   • Note: Your SQL Server Name must be globally unique, or the deployment will fail. It is recommended to use the format "tygraph-yourorgname-sql".
     
   • Note: The SQL Server Password must meet the minimum password strength requirements. It must include at least one lowercase character, one uppercase character, and one number, or the deployment will fail.
   • Note: Your App Service Name must be globally unique, or the deployment will fail. It is recommended to use the format "tygraph-yourorgname-app".
9. Once the screen shows that your deployment is complete, you can proceed.

Troubleshooting Azure Deployment Issues

If your Azure Deployment didn't have any errors, you can skip to the next section.

1. Sometimes you will see a notification that your ARM Template deployment has failed. Click the notification to view the failed deployment.
2. Click the Operation details to see why a given resource didn't deploy properly.
   • "Code": "NameAlreadyExists" - This means the SQL Server Name you entered is already in use. Try a different SQL Server Name.
   • "Message": "Website with given name..." - This means the App Service Name you entered is already in use. Try a different App Service Name.
   • "Code": "PasswordNotComplex" - This means your SQL Server password failed to meet SQL Server's password policies. Make sure to create a password with at least one lowercase letter, uppercase letter, and number.
3. To fix a failed deployment, click the Redeploy button in the Template Overview panel and refill your ARM Template parameters, then click "Purchase" again - this will update your current deployment without duplicating any resources.

Deploy tyGraph Pages Resources

You can skip this section if you will not be using tyGraph Pages.

1. Click the "Create" button in your tyGraph Resource group.
2. Search for "log analytics workspace" and select "Log Analytics Workspace".
3. Click "Create".
4. Give the Log Analytics Workspace a name and choose a region (ideally the same region as your other tyGraph Resources). Click "Review + create", then click "Create".
5. When the deployment is complete, click "Go to resource".
6. Use the search bar on the left side to search for "Usage and estimated costs" and select it.
7. Click the "Data Retention" button.
8. Adjust the slider to the desired level of retention, then click "OK". Note: Increasing data retention will result in additional Azure storage costs.
9. Return to your tyGraph Resource Group and click the "Create" button again.
10. Search for "application insights" and select "Application Insights".
11. Click "Create".
12. Give the Application Insights a name, select the same Region as your Log Analytics Workspace, and select your Log Analytics Workspace. Click "Review + create", then click "Create".
13. Once the deployment is complete, click "Go to resource".
14. Record the Instrumentation Key value for use in configuration.
15. Use the search bar on the left side to search for "api access" and click "API Access".
16. Record the Application ID value for use in configuration.
17. Click the "Create API key" button.
18. Give the API key a name, check the "Read telemetry" box, and click the "Generate key" button.
19. Record the key for use in configuration. Note: Make sure to copy the key down immediately, as it will disappear once you leave the page.
20. Return to your Application Insights and open the "Access Control (IAM)" panel.
21. Click the "Add role assignment" button.
22. Select the "Reader" role and click the "Next" button.
23. Click the "Select members" link.
24. Search for the AAD User Account that will be used to connect your tyGraph Pages Power BI report, and select it, then click the "Select" button.
25. Click the "Review + assign" button.
26. Click "Review + assign" again.
27. Complete the tyGraph Pages signup form, filling in any desired data obfuscation settings, and filling in the Instrumentation Key you recorded earlier.

Install the tyGraph Pages Engine

You can skip this section if you will not be using tyGraph Pages.

1. Go to the Microsoft 365 admin center.
2. Click "SharePoint".
3. Click "More features".
4. Under "Apps", click the "Open" button.
5. Click the link to go to the "classic experience".
6. Click the "Upload" button.
7. Click the "Browse" button.
8. Select the tyGraphPagesEngine.sppkg file included in your tyGraph Deployment package.
9. Click "OK".
10. Select "Make this solution available to all sites in the organization" and click the "Deploy" button. 
11. To check the deployment of the engine, visit a Modern SharePoint site page, right-click on the page, and click "View page source".
12. Search the page for "tyGraphPagesEngine" to confirm a successful installation.

tyGraph Pages Graph API Access

You can skip this section if you will not be using tyGraph Pages or if you don't need user-level filtering in your Pages report.

1. Go to the Microsoft 365 admin center.
2. Click "SharePoint".
    
3. Click "Advanced".
4. Click "API access".
5. Select the "Microsoft Graph" request for the "tyGraph Pages Engine".
6. Click the "Approve" button.
7. Click the "Approve" button.

Install the Pages Web Part

The tyGraph Pages Web Part is an optional component that can be installed alongside tyGraph Pages. You can skip this section if you will not be using the tyGraph Pages Web Part.

1. Go to the Microsoft 365 admin center.
2. Click "SharePoint".
    
3. Click "More features".
4. Under "Apps", click the "Open" button.
5. Click the link to go to the "classic experience".
6. Click the "Upload" button.
7. Click the "Browse" button.
8. Select the tyGraphPagesWebParts.sppkg file included in your tyGraph Deployment package.
9. Click "OK".
10. Select "Make this solution available to all sites in the organization" and click the "Deploy" button. 

Add the Site Analytics Web Part to a page

The tyGraph Pages Site Analytics web part provides reporting capabilities for any site, hub site, or for the tenant.

Security Consideration: a configured web part can view the analytics for any page in your tenant.  The web part only shows the current site / hub site by default.  However, any user with page edit permission can configure the web part to show analytics for the entire tenant.  We recommend placing the web part only on sites with limited access and ensure only desired users have edit permissions on the page.  As an alternative, you can view site and hub site analytics when using tenant-wide authentication.

Throttling Consideration: in order to avoid throttling by the Application Insights API, we do not recommend placing the web part on high traffic sites such as an Intranet home page.

Add the tyGraph Site Analytics web part to a page:

1. On the page you want to add the web part, click the "Edit" button.
2. Click the "plus (+)" sign where you would like to add the web part.
3. Search for "tyGraph" and select the tyGraph Site Analytics web part

Configure the Site Analytics Web Part

To display your reports, you must configure the Application Insights Id and API key.  The steps below configure authentication for the current page only.  If you want to configure authentication globally, you may configure tenant-wide authentication.  This will store the authentication information in the app catalog, and users can use the web part without having to configure it. NOTE: Tenant-wide authentication cannot be configured until the tyGraph Pages license has been enabled.

Configure Authentication

1. Edit the web part and set authentication:    
   1. Click the "pencil" icon to edit the web part
   2. 
   3. Scroll to Authentication and complete the "Application Id" and "API Key" fields with the values you recorded earlier.

Security Consideration: users who can edit the page with the web part can retrieve your API key.  In addition, users who are familiar with a browser developer console can view the API calls and retrieve your API key.  We recommend placing the web part only on sites with limited access.

Configure Reports

The Site Analytics web part comes with a standard preconfigured report layout or you can customize it to your needs.  The web part supports the following Report Layouts:

• Site Analytics - reports including page views, news, sites, and button clicks.
• Devices - reports containing browsers, operating systems, screen resolutions, and browser sizes
• Viva Connections - adoption reports for Viva Connections 
• Custom - pick any reports you want to include

 

Select "Custom" to choose your own reports.

You can choose from the following reports:

• Page Views - line chart showing total page views for the site / hub by day
• Unique Users - line chart showing unique users by day
• Top Pages  - bar chart of pages ordered by number of page views
• Top News - top news articles by number of page views
• Time on Page - chart showing average time on pages for the site / hub
• Button Activity (Preview) - filterable report which allows you to view button clicks such as Page Edit, Page Publish, or Page Like over time
• Browsers - pie chart showing browser utilization
• Operating Systems - pie chart showing operating system utilization
• Screen Resolutions - bar chart showing top screen resolutions
• Browser Sizes - bar chart showing top browser sizes
• Client Types - shows the client used to access the site such as a desktop browser, Teams Desktop, Teams Mobile, or SharePoint Mobile
• Sites - top sites by page views
• Button Clicks - top events associated with button clicks
• Top Links - provides a list of the top links clicked on in the site / hub
• Navigation - shows you which links in your site, hub site, or global navigation are getting 
• Viva Connections Daily Page Views - percentage of page views that used Viva Connections
• Viva Connections Summary - summary comparison of Viva Connections usages to SharePoint usage
• Viva Connections Users- comparison of Viva Connections users to total users

Configuring the Data Source

By default, the Site Analytics web part will show reports for the current site.  If the current site belongs to a SharePoint hub site, you can opt to show data for the hub site instead.

Specifying which site to display reports

You can choose from the following options for the site data source:

• This site
• All sites in the hub
• All sites in the tenant 

 

Note: "All sites in the hub" only show on sites connected to a SharePoint hub site.

 

By default, the web part will use the current site URL.  You can change the URL to any other site in the tenant.

Permissions note: if you specify an invalid URL, a URL from another tenant, or a site in which you do not have permission, you will receive an error.  All users of the web part, must have permission on the site in order to see the reports.

Configuring Caching

To avoid throttling issues, the web part caches report data for five minutes.  Caching can be adjusted by moving the slider.  You may also disable the cache by choosing a value of "0".

  

Configuring Additional Options

You can configure these additional options:

• Show demo data - toggle to view the report with demo data
• Disable site / hub toggle - removes the button to toggle between site and hub site analytics.  Choose this option if you don't want users to be able to toggle between these views.
• Disable report layout selector - removes the dropdown allowing you to switch between the Site Analytics and Devices report layouts
• Hide data refresh date - check this box to remove the refresh date from each report.
• Enable 365 day filter - adds the 365 day option on the day slicer

Configuring filters

You can configure the number of days to show in the report.  By default, the web part will show 45 days of history.  Users can view other reporting periods in the web part by using the day slicer in the web part. 

Toggling between visualizations and data view

All reports in the Site Analytics web part have the ability to default to a view with visualizations or table data.

 

Saving your configuration

Once you have completed your configuration, click the "Republish" button on the page to save your changes and publish the page.

Note, that the web parts display data in near-real time that has been collected by the tyGraph Pages engine.  If you just installed the engine, there may not be any data to display in the web parts when you first install them.

Configuring the Report Panel

The tyGraph Pages Report Panel provides page-level reports at the click of a button from any SharePoint page.  Read the configuration guide for additional steps.  When it's available, you can click the Page Report button at the top to open the Report Panel.

Using the web part in Microsoft Teams

You may opt to use the web part as a tab in a Microsoft Teams channel.  Follow these instructions to configure Microsoft Teams.

Enable Access to tyGraph Resources

1. Open your tyGraph Resource group in the Azure Portal and select the SQL Server.
2. Search for "network", then open the Networking panel.
3. Under "Firewall rules", click "Add your client IPv4 address (IP address)".
4. Click the menu button, then click "Edit". Change the "Rule name" to "Admin Config". Copy the Start IP address for the next steps, and click "OK".
5. Navigate back to your Resource group and click your tyGraph App Service.
6. Search for "networking" and open the Networking panel.
7. Click "Access restriction".
8. Click "Add rule".
9. Give the rule a name, a priority (ie. 300), and paste in the IP address you recorded above. Then click "Add rule".

Install and Run the tyGraph Harvester

Note: If you are installing multiple tyGraph harvesters, you will need to follow the steps in this section for each harvester, selecting a new Setup Key each time.

1. Open the Admin Console folder in your tyGraph Deployment package.
2. Locate the tyGraph365.AdminClientWinform Application file and run it (run as an administrator if possible).
3. Select "New tyGraph Installation".
4. Fill out the SQL Server Name (followed by .database.windows.net), the DBA username, the DBA password, and select your Setup Key from the dropdown. (If you are installing multiple harvesters, there will be multiple options for your Setup Key, and you will need to select a different Setup Key each time). Finally, click "Connect".
   • If you get an error message containing an IP address, your Admin Console is unable to reach the SQL Server. Review the steps for enabling access to make sure the IP has been added properly.
5. Scroll to the bottom of the Installation Details panel and click the "Complete Database Setup" button.

6. Office 365 Configuration

   The Admin Console will navigate to Configuration > Office 365. The required information can be found in the Azure Portal.
   • Tenant ID is the ID of your AAD tenant - found in the Overview or Properties panel of Azure Active Directory on the Azure Portal.
   • Tenant Name (your Azure Tenant Domain) is found in the Custom domain names panel of your Azure Active Directory. It is the domain that ends with '.onmicrosoft.com'.
   • Domain (your SharePoint Domain) is based on the tenant name entry. Remove the '.onmicrosoft.com' portion of the Tenant Name to get the Domain.
   • Teams Whitelisted can be switched to 'yes' if you have completed the form to request access to Microsoft Teams Message Data.
   • Teams Start Date can be left as 'All Time' for a default deployment.
   • Click the "Apply" button to save the configuration.

7. Azure Tenant Configuration

8. Fill out the App Registration section:    
   • App ID is the Azure App Registration Client ID that you recorded earlier.
   • App Secret  is the Azure App Registration Client Secret that you recorded earlier.
   • Click the "Test" button to ensure the App Registration is working properly.
   • Once you've tested the App Registration, click "Apply" to save the configuration.
9. Fill out the App Service section:    
   • Name is the name you gave to your tyGraph App Service.
   • URL can be found in the "Advanced Tools" panel. Click the "Go" link to open a new browser tab containing the App Service URL.  
     • If you receive an "Error 403 - Forbidden" message, your Admin Console is being blocked by the App Service. Review the steps for enabling access to make sure you have added your IP properly. 
   • Username and Password can be found by clicking the "Get publish profile" button on the Overview panel of your App Service. This will download a .PublishSettings file, which can be opened with any text editor. The Username and Password will be listed as "userName" and "userPWD" in the file. Note: The username includes the '$' symbol.
   • Proxy URL and Admin Proxy URL can be left blank in a standard deployment.
   • Click "Test" to make sure you can connect to the App Service.
     • If you receive a (403) Forbidden error, your Admin Console is being blocked by the App Service. Review the steps for enabling access to make sure you have added your IP properly.
   • Once you've tested the connection to the App Service, click "Apply" to save the configuration.

10. Yammer Network Configuration

    • You can skip these steps if you will not be using tyGraph for Yammer.
11. Fill in the Yammer App section:    
    • App ID is the Yammer App Client ID you recorded earlier.
    • App Secret is the Yammer App Secret you recorded earlier.
    • Click "Apply" to save the configuration.
12. Fill in the Canonical Network section:    
    • Network ID  is the "network_id" value you recorded earlier.
    • Permalink is the "permalink" value you recorded earlier.
    • Token is the "token" value you recorded earlier.
    • Click "Test" to make sure you can connect to your Yammer Network.
    • Once you've tested the connection, click "Apply" to save the configuration.
13. The External Network section can be left blank in a standard deployment.

14. Cognitive Services Configuration

    • You can skip these steps if you are not going to be using Sentiment Analysis to analyze Yammer or Teams messages
15. Fill in the Cognitive Services section:    
    • Open your Sentiment Analysis resource in the Azure Portal.
    • URL can be found in the "Keys and Endpoint" panel. Copy the "Endpoint" and append text/analytics/v2.0 to the end.
    • Key can be found on the same "Keys and Endpoint" panel. Copy one of the two available key values. 
    • Key Name is a human-readable name for your key, typically your organization name.
    • Yammer Enable should be set to "yes" if you want Sentiment Analysis for Yammer messages.
    • Yammer Start Date can be left as "All Time" for a standard deployment.
    • Teams Enable should be set to "yes" if you want Sentiment Analysis for Teams messages.
    • Teams Start Date can be left as "All Time" for a standard deployment.
    • Click "Test" to test the connection to Cognitive Services.
    • Once you have tested the connection, click "Apply" to save the configuration.

16. Configure Email Notifications

17. Fill in the Email Notifications section:    
    • From Address can be set to "tyGraph@unlimitedviz.com" in a standard deployment.
    • Recipients should include "tyProd@unlimitedviz.com", plus any other recipients you wish to receive error notifications. All recipients should be separated by commas.
    • tyGraph Relay should be set to "yes" in a standard deployment.
    • Click "Test" to send a test email notification.
    • Once you've verified that the email notifications are working, click "Apply" to save the configuration.
18. The SMTP section can be left blank in a standard deployment.
19. The Exchange section can be left blank in a standard deployment.
20. The Microsoft Graph section can be left blank in a standard deployment.

21. Deploy the Harvester Webjobs

22. Expand the "Manage Harvester" node and open the "Deploy Harvester" section. Change the Operation Group to "Multiple harvesters", then, click the "Deploy Harvester" button.
23. To verify the successful deployment, switch the bottom tab to "Event Log" and click the "Apply" button.
24. A successful deployment will include an "Operation completed" Event. (An unsuccessful deployment will instead include an "Operation error" Event).
25. Open the "Deploy Monitoring Service" section. Check the "Enable tyGraph heartbeat service" box, the "Enable email notifications" box, and click the "Deploy Monitor" button.
26. To verify the monitor deployment, click the "Apply" button in the bottom "Event Log" tab again.
27. There should now be a second "Operation completed" Event.

28. Start the Initial Harvest

29. Open the "Trigger or Revive Harvester" section. Click the "Trigger Harvester" button to start the first tyGraph data harvest.
30. You can follow the status of the harvest through the "Event Log" tab at the bottom of the Admin Console. Click the "Apply" button to refresh the view. Once the Description field shows "All operations completed" for the "primary" harvester, the harvest is done. If the log shows "Operation error", something has gone wrong, and you will need to contact the tyGraph Teams for support.

Configure the Daily Harvest

Note: If you are installing multiple tyGraph harvesters, you will need to follow the steps in this section for each harvester.

Follow these steps only after your initial tyGraph data harvest has completed.

1. If you have closed the Admin Console, reconnect it by entering your SQL connection details in the "Connect to tyGraph" section and clicking "Go". Otherwise, skip this step.
2. Open the "Manage Harvester" node of the Admin Console and select the "Set Operation Sequence" section.
3. Switch the "Data Collection Type" dropdown to "On going data collection" and click "Apply Sequence".
4. Open the “Schedule Harvester” node of the installer, then check the “Enable scheduling” box and click “Apply” (Optionally: change the UTC start time from midnight to some other time.)

Connect the tyGraph Pages Report

You can skip this section if you will not be using tyGraph Pages.

1. Sign in to Power BI using a Power BI Pro account and click the "Get Data" button in the bottom left.
2. Click the "Get" button in the Services box. 
3. Search for "tyGraph Pages" and select the tyGraph Pages Power BI App.
4. Click "Get It Now".
5. If you see the contact form below, enter your contact information, check the permission box, and click "Continue".
6. Click "Install".
7. Once the install process completes, click the menu icon for the newly created app.
8. Click "Edit".
9. Click "Yes, go to workspace".
10. Click the link to "Connect your data".
11. Fill in the parameters.
    • AppInsights Application ID is the Application ID you recorded earlier.
    • TimeZoneOffset sets the number of hours to offset from UTC time (ie. -5 for EST). The default value is 0, indicating UTC time.
    • Period (days) can be set as desired. Period (days) controls the number of days to retrieve data for the report. The recommended initial value is 60. Depending on data volume, this value can be increased.
    • Communication Sites Only can be set as desired. This is an optional parameter to scope the reports to Communication sites only when set to “True”. The default option is “False” and will retrieve all sites.
    • Site Collection URL(s) can be set as desired. This is an optional parameter to scope the reports to certain Site Collection(s) only. Multiple full URL's can be entered using a comma-delimited list. The default option is “All”, to retrieve all sites.
    • Hub URL(s) can be set as desired. This is an optional parameter to scope the reports to certain Hub(s) only. Multiple full URL's can be entered using a comma-delimited list. The default option is “All”, to retrieve all sites. 
    • Session Duration Cap (minutes) applies a cap on session duration. The default value is 30 minutes.
    • Page Visit Time Cap (minutes) apply a cap on page visit duration per session. The default value is 30 minutes.
      • Note: The following parameters are mutually inclusive: Communication Sites Only, Hub URL(s), and Site Collection URL(s).
12. Click "Next".
13. Set the Authentication method to "OAuth2", the privacy level as required by your organizational policies, and click "Sign in and connect".
14. Select the account you added to the Access Control (IAM) of your App Insights earlier.
15. The refresh will initiate automatically.
16. Click "Update app".
17. Click "Update app".
    
18. Click "Update". 
19. Click "Go to app".

Option A: Connect tyGraph Reports using a VNet Gateway

A VNet Gateway is the recommended method for connecting tyGraph Reports, as it provides the greatest stability and security. However, VNet Gateways require Power BI Premium. For another option, see Connect tyGraph Reports using IP Whitelisting.

1. Follow the Microsoft documentation to create a VNet Gateway using the VNet in your tyGraph Resource Group.
2. Sign in to Power BI using a Power BI Pro account and click the settings icon in the top right corner.
3. Click "Manage gateways".
4. Click the "Virtual network data gateways" tab, hover over the VNet gateway you created, and click the gear icon.
5. Move the slider under "Number of gateways" to the maximum (3), then click "Save".
6. Navigate to the "Data sources" tab, then click "New" in the top left.
7. Under "Gateway cluster name", select the VNet gateway you created earlier. Give your data source a name (recommended to be the same as the name of the database it will connect to). Set the Data source type to "SQL Server", then enter your SQL Server name and the database name. Set the Authentication Method to "Basic". The form will now ask for a Username and Password.
   
8. To retrieve your reporting credentials, start by opening your tyGraph Admin Console and navigating to "Manage Database" > "Setup Database" > "Installation Details".
9. Scroll down to the "Reports - Open" section, click the "v" button to view the Password, then copy the Login and Password. 
10. Return to Power BI and enter the credentials into the data gateway form, then hit "Create".
11. If you are setting up multiple tyGraph harvesters, repeat steps 6-10 for each.
12. Click the "Get data" button in the bottom left corner.
13. Click the "Get" button in the Services box.
14. Search for "tyGraph" and select the report you want to connect.
15. Click "Get It Now".
16. If prompted, enter your contact information, check the permission box, and click "Continue".
17. Click "Install".
18. Once the install process completes, click the menu icon for the newly created app.
19. Click "Edit".
20. Click "Yes, go to workspace".
21. Click the "Settings" button in the workspace menu bar.
22. Click the "Premium" tab.
23. Assign a "Premium per user" or "Premium per capacity" and click "Save".
24. Click the menu button for the Dataset (orange icon).
25. Click "Settings".
26. Expand the "Parameters" section.
27. Fill in the parameters for your report.
    • Schema (Yammer only) should be set to "open". 
    • Server should be the name of your SQL Server.
    • Database should be the name of your tyGraph database, and should match one of your VNet Gateway data sources. (If you have set up multiple harvesters, specific reports might map to specific harvesters, as indicated by the tyGraph team).
    • Detail Period (Months) (SharePoint only) should be set to 1.
    • Summary Period (Months) (SharePoint only) should be set to 6.
    • Site URL(s) (SharePoint only) should be set to "<N/A>".
    • Include subsites? (Yes/No) (SharePoint only) should be set to "No".
    • User Column Name (SharePoint only) should be set to "<N/A>".
    • User Column Value(s) (SharePoint only) should be set to "<N/A>".
    • All other parameters can be left as their default values.
28. Click the "Apply" button.
29. Refresh the page.
30. Expand the "Gateway connection" section.
31. Switch the Gateway connection option to "On".
32. Select your database from the mapping dropdown and click "Apply".
33. Open the "Scheduled Refresh" section.
34. Switch the Scheduled Refresh to "On".
35. Click the "Add another time" link.
36. Select a time of day to refresh your report and click "Apply".
37. Click the workspace on the left hand side.
38. Click the Refresh button on the Dataset (orange icon).
39. Repeat steps 12-38 for each report you will be using.

Option B: Connect tyGraph Reports using IP Whitelisting

1. Sign in to Power BI using a Power BI Pro account and click the "Get Data" button in the bottom left.
2. Click the "Get" button in the Services box.
3. Search for "tyGraph" and select the report you want to connect.
4. Click "Get It Now".
5. If prompted, enter your contact information, check the permission box, and click "Continue".
6. Click "Install".
7. Once the install process completes, click the menu icon for the newly created app.
8. Click "Edit".
9. Click "Yes, go to workspace".
    
10. Click the link to "Connect your data".
11. Fill in the parameters for your report.
    • Schema (Yammer only) should be set to "open".
    • Server should be the name of your SQL Server.
    • Database should be the name of your tyGraph database. (If you have set up multiple harvesters, specific reports might map to specific harvesters, as indicated by the tyGraph team).
    • Detail Period (Months) (SharePoint only) should be set to 1.
    • Summary Period (Months) (SharePoint only) should be set to 6.
    • Site URL(s) (SharePoint only) should be set to "<N/A>".
    • Include subsites? (Yes/No) (SharePoint only) should be set to "No".
    • User Column Name (SharePoint only) should be set to "<N/A>".
    • User Column Value(s) (SharePoint only) should be set to "<N/A>".
    • All other parameters can be left as their default values.
12. Once you have entered all the parameters, click "Next".
13. You will see a connection form.
14. To retrieve your reporting credentials, start by opening your tyGraph Admin Console and navigating to "Manage Database" > "Setup Database" > "Installation Details".
15. Scroll down to the "Reports - Open" section, click the "v" button to view the Password, then copy the Login and Password.
16. Back in Power BI, enter these credentials into the connection form, then click "Sign in and connect".
17. You will see an error that the Power BI service IP is blocked. Copy down this IP address.
18. Open your tyGraph Resource Group in the Azure Portal, then click on your SQL Server.
19. Use the search bar on the left side to search for "network", then open the "Networking" panel.
20. Add a rule for the Power BI Service IP you copied down, then click "OK"
21. Click "Save".
22. Return to Power BI, then click "Sign in and connect".
    • You might receive an error message containing a different Power BI Service IP. If so, repeat steps 15-19 until you have added all Power BI Service IPs for your region.
23. Once your report is connected, you will see that the "Connect your data" link is gone.
24. Click the menu icon for the Dataset (orange icon).
25. Click "Settings".
26. Expand the "Scheduled Refresh" section.
27. Click the "Add another time" link.
28. Select a time and click "Apply".
29. Repeat all of these steps for each report you will be using.

Troubleshooting Power BI Report Refreshes

1. Open Power BI and click "Workspaces" to open the workspaces tab.
2. Search for the workspace containing the report you want to troubleshoot and click on it.
3. Click the menu icon for the Dataset.
4. Click "Settings".
5. Click the "Refresh History" link.
6. Click the "Show" link for any Failed refreshes to get more details on the issue.
7. If the issue is simple, this should give you enough information to resolve it (for example, in this circumstance, the SQL Server is missing a Power BI service IP address, which should be added to the firewall). Otherwise, copy the details to add to a support ticket with the tyGraph team.