TCG Office Connector

The GroundWork TCG Office connector lets you use the API that Microsoft™ exposes to the Internet for monitoring any Microsoft 365™ accounts to which you have access. The metrics you gather are defined in a json file and are not configurable with the user interface, but are all generally useful. In some cases you may want to modify the json file to customize the items you monitor. 


All you need to use this connector is an Internet connection from your GroundWork Monitor server and the Tenant ID, Client ID and Client Secret for the account you want to monitor. You can't set up multiple Office connections on the same GroundWork Server, however.  

The tenant used must have the following permissions:

O365 Services StatusServiceHealth.Read
OneDrive UsageFiles.Read.All
Mailbox monitoringMail.ReadBasic.All
List licenses in useOrganization.Read.All
Sharepoint MonitoringSites.Read.All

Setting Up TCG

The easiest way to run the TCG instance that handles the connection to Microsoft 365 is to run it as a container under docker-compose on a GroundWork server. Of course, TCG is just a Go program and it's possible to deploy it differently, so it's up to you. Here's how to set it up as a container:

  1. Edit the docker-compose.override.yml file in the gw8 directory of your GroundWork server. In the services: section, add:

        image: groundworkdevelopment/tcg:${TAG}     
        entrypoint: ["/app/", "office-connector"]
          - tcg-var:/tcg
  2. At the bottom of the file, under the volumes: section, make sure that volumes: is uncommented, and tcg-var: is listed as a volume, for example: 


    Pay close attention to the indenting as you are editing a YAML file and it is sensitive to order and to white space. 

  3. Restart your GroundWork server: 

    docker-compose down
    docker-compose up -d

Setting Up the Connector

  1. Sign in to your GroundWork server as an administrative user.

  2. Go to Configuration > Connectors.

  3. Click the Add icon and select the Office connector from the menu.

  4. Enter the following information:
    • Connector Name: Provide a unique name
    • TCG Host Address: Enter, unless you have changed where TCG is running with a custom configuration
    • Tenant ID: Provide your Microsoft 365 Tenant ID
    • Client ID: Provide your Microsoft 365 Client ID
    • Client Secret: Provide your Microsoft 365 client secret
    • Interval: Set a polling Interval, Timeout and Retries as desired

      Microsoft may impose throttle limits on the API. While your polling interval can be set as fast as 1 minute, this may start failing if throttled. We recommend 30 minutes as an interval unless you really need it to be less, and not to go below 5 mins. 

  5. Click Create.
  6. After a few moments, you will see a new host group called Microsoft Apps appear in Status. This will contain two hosts and several services representing the state of your Microsoft 365 services. 
  7. Drilling down onto any services in a Warning or Critical state will give you a message about the issues detected. For example, in the image above, the Exchange Online and Microsoft 365 Suite services are up, but experiencing issues that affect some users. 

  8. In addition, unread email, license consumption and storage limits are monitored. While it is not possible to set the thresholds a priori, you can override them in the Status Summary. The default thresholds are:

    MetricDefault ThresholdDescription
    Onedrive.totalnoneOne Drive Total Disk Space
    Onedrive.remainingnoneOne Drive Remaining Disk Space
    Onedrive.freeWarning 15%, Critical 5% One Drive Percent Remaining Disk Space
    Sharepoint.totalWarning 10, Critical 100Share Point Total Disk Space Per Drive
    Sharepoint.remainingnoneShare Point Disk Space Remaining Per Drive
    Subscriptions.prepaidnoneSubscriptions Prepaid Count
    Subscriptions.consumednoneSubscriptions Consumed Count
    Unread.emailsWarning 5, Critical 10Microsoft Office Unread Emails

    To adjust, browse to the service you want to adjust in Status, click More Actions and select Edit Thresholds. Your choice will override the defaults. 

Related Resources