Jump to content

Publishing Seeq Notifications to Microsoft Teams with Webhooks


Patrick

Recommended Posts

  • Seeq Team

Update - To see a video of the below workflow in action, check out this Seeq Tips and Tricks video.

Webhooks are a convenient method to send event data from Seeq to “channel” productivity tools such as Microsoft Teams or Slack.  The following post describes how Seeq users can leverage Seeq Data Lab to send messages directly to MS Teams via Webhooks.

Pre-Requisites:
1)    Seeq Data Lab with Scheduled Notebooks enabled
            a. See Administration Panel -> Configuration and filter for “Features/DataLab/ScheduledNotebooks/Enabled”
2)    MS Teams Channel with a Webhook Connector

Assumptions:
1)    Summary of capsules generated in a defined time range (i.e., every 12 or 24 hours)
2)    Notifications are not near-real-time – script will run on a pre-defined schedule generally measured in hours, not minutes or seconds
3)    Events of interest are contained in an Asset Tree or Group with one or more Conditions

Step 1: Configure Webhook in MS Teams
To send Seeq capsules/events to MS Teams, a Webhook for the target channel needs to be created.  Detailed instructions on how to configure Webhooks in MS Teams can be found here:

https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook
 
For the purpose of this post, we will create a Webhook URL in our “Seeq Notifications” Team to alert on Temperature Excursions.  The alerts will be posted in the “Cooling Tower Temperature Monitoring” channel. Teams and Channel names can be configured to fit your need/operation, this is just an example for demonstration purposes:


image.png

image.png

image.png

MS Teams will generate a Webhook URL which we will use in our script in Step 4.

Step 2: Identify or Create an Asset Group or Asset Tree to define the Monitoring Scope

To scope the events of interest, we will use an Asset Tree that contains “High Temperature” conditions for a collection of Monitoring Assets.  While this is not a requirement for using Webhooks, it helps with scaling the Notification workflow.  It also allows us to combine multiple Conditions from different Assets into a single workflow.

To learn how create an Asset Tree, follow the “Asset Trees 1 – Introduction.ipynb” tutorial in the SPy Documentation folder contained in each new Seeq Datalab project. 
image.png  image.png

The script for the Monitoring Asset Tree used in this post is attached for reference:

Monitoring Asset Tree.ipynb

Alternatively, Asset Groups can be also used to create an asset structure directly in Workbench without using Python:

Once the Asset Group/Tree containing the monitoring Conditions is determined, create a Worksheet with a Treemap or Table overview for monitoring use:

image.png

Make note of the URL as it will be included in the Notification as a link to the monitoring overview whenever an event is detected.  For locally scoped Asset Groups or Trees, it will also inform the script where to look for Conditions.

 

Step 3: Install the “pymsteams” library in Seeq Datalab

The pymsteams library allows users to compose and post messages (or cards) to MS Teams.  The library can be installed from the pypi repository (pypi.org) using the “pip install” command.

1)    Open a Seeq Datalab Project
2)    Launch a Terminal session
image.png

3)    Install the pymsteams library by executing

pip install pymsteams

 

Additional documentation on pymsteams can be found here: https://pypi.org/project/pymsteams/ 

Step 4: Create or Update the Monitoring script
We are now ready configure a monitoring script that sends notifications to the Webhook configured in Step 1 using Conditions scoped to the Asset Tree in Step 2.

a)    Import the relevant libraries, including the newly installed pymsteams library

import pandas as pd
from datetime import datetime,timedelta
import pytz
import pymsteams

b)    Configure Input Parameters

#Refer to Microsoft Documentation on how to configure a Webhook for a MS Teams channel
webhook_url='YOUR WEBHOOK HERE'

#Specify the monitoring workbook - this is where the alert will link with the associated timeframe
monitoring_workbook_url='YOUR WORKBOOK HERE'

#Specify the asset tree and associated condition for which the webhook should be triggered
asset_tree='Compressor Monitoring'
monitoring_condition='High Temperature'

#Specify the lookback period and timezone to search for capsules
lookback_interval_hours=24
timezone=('US/Mountain')

c)    Search for Event Capsules

#Set time range to look for new conditions
delta=timedelta(hours=lookback_interval_hours)
end=datetime.now(tz=pytz.timezone(timezone))
start=end-delta
#Parse the workbook information
workbook_id=spy.utils.get_workbook_id_from_url(monitoring_workbook_url)
worksheet_id=spy.utils.get_worksheet_id_from_url(monitoring_workbook_url)
#This block is optional, it stores search results for the conditions once instead of searching each time the 
#script runs.  Saves time if the search result is not expected to change.  To reset, just delete the .pkl file.
pkl_file_name=asset_tree+'_'+monitoring_condition+'_'+workbook_id+'.pkl'

try:
    monitoring_conditions=pd.read_pickle(pkl_file_name)

except:
    monitoring_conditions=spy.search({'Name':monitoring_condition,
                                      'Type':'Condition',
                                      'Path':asset_tree},
                                     workbook=workbook_id,quiet=True)
    monitoring_conditions.to_pickle(pkl_file_name)
#Pull capsules present during the specified time range
events=spy.pull(monitoring_conditions,start=start,end=end,group_by=['Asset'],header='Asset',quiet=True)
number_of_events=len(events)
events

d)    Send Message to Webhook using the pymsteams library if a Capsule is detected in the time range

#If capsules are present, trigger the webhook to compile and send a card to MS Teams

if number_of_events != 0:
    events.sort_values(by='Condition',inplace=True)
    
    #Create url for specific notification time-frame using Seeq URL builder
    investigate_start=start.astimezone(pytz.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
    investigate_end=end.astimezone(pytz.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
    investigate_url=f"https://explore.seeq.com/workbook/builder?startFresh=false"\
        f"&workbookName={workbook_id}"\
        f"&worksheetName={worksheet_id}"\
        f"&displayStartTime={investigate_start}"\
        f"&displayEndTime={investigate_end}"\
        f"&expandedAsset={asset_tree}"
    
    #Create message information to be posted in channel
    assets=[]
    text=[]
    for event in events.itertuples():
        assets.append(event.Condition)
        
        #Capsule started before lookback window
        if pd.isnull(event[2]):
            if pd.isnull(event[3]) or event[4] == True:
                text.append(f'Event was already in progress at {start.strftime("%Y-%m-%d %H:%M:%S %Z")} and is in Progress')
            else:
                text.append(f'Event was already in progress at {start.strftime("%Y-%m-%d %H:%M:%S %Z")} and ended {event[3].strftime("%Y-%m-%d at %H:%M:%S %Z")}')
        
        #Capsule started during lookback window
        else:
            if pd.isnull(event[3]) or event[4] == True:
                text.append(f'Event started {event[2].strftime("%Y-%m-%d at %H:%M:%S %Z")} and is in Progress')
            else:
                text.append(f'Event started {event[2].strftime("%Y-%m-%d at %H:%M:%S %Z")} and ended {event[3].strftime("%Y-%m-%d at %H:%M:%S %Z")}')

    message='\n'.join(text)
    
    #Create MS Teams Card - see pymsteams documentation for details
    TeamsMessage = pymsteams.connectorcard(webhook_url)
    TeamsMessage.title(monitoring_condition+" Event Detected")
    TeamsMessage.text(monitoring_condition+' triggered in '+asset_tree+f' Asset Tree in the last {lookback_interval_hours} hours')

    TeamsMessageSection=pymsteams.cardsection()
    for i,value in enumerate(text):
        TeamsMessageSection.addFact(assets[i],value)

    TeamsMessage.addSection(TeamsMessageSection)
    TeamsMessage.addLinkButton('Investigate in Workbench',investigate_url)
    TeamsMessage.send()

Step 5: Test the Script

Execute the script ensuring at least one “High Temperature” capsule is present in the lookback duration.  The events dataframe in step 4. c) will list capsules that were detected.  If no capsules are present, adjust the lookback duration.

image.png

If at least one capsule is detected, a notification will automatically be posted in the channel for which the Webhook has been configured:

image.png

 

Step 6: Schedule Script to run on a specified Frequency

If the script operates as desired, configure a schedule for it to run automatically.  

#Optional - schedule the above script to run on a regular interval
spy.jobs.schedule(f'every day at 6am')

image.png

The script will run on the specified interval and post a summary of “High Temperature” capsules/events that occur during the lookback period directly to the MS Teams channel.

Refer to the spy.jobs.ipynb notebook in the “SPy Documentation” folder for additional information on scheduling options.

image.png

Attached is a copy of the full example script:

Seeq MS Teams Notification Webhook - Example Script.ipynb

Edited by Patrick
Added Tips and Tricks video link
  • Like 2
  • Thanks 2
Link to comment
Share on other sites

  • Patrick changed the title to Publishing Seeq Notifications to Microsoft Teams with Webhooks

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...