How to publish to a Microsoft Teams channel using SAS

This post was kindly contributed by The SAS Dummy - go there to comment and to read the full post.

A few years ago I shared a method to publish content from SAS to a Slack channel. Since that time, our teams at SAS have gone “all in” on collaboration with Microsoft Office 365, including Microsoft Teams. Microsoft Teams is the Office suite’s answer to Slack, and it’s not a coincidence that it works in nearly the same way.

The lazy method: send e-mail to the channel

Before I cover the “deluxe” method for sending content to a Microsoft Teams channel, I want to make sure you know that there is a simple method that involves no coding, and no need for APIs. The message experience isn’t as nice, but it does the job. You can simply “send e-mail” to the channel. If you’re automating output from SAS, it’s a simple, well-documented process to send e-mail from a SAS program. (Here’s an example from me, using FILENAME EMAIL.)

When you send e-mail to a Microsoft Teams channel, the message notice includes the message subject line, sender, and the first bit of the message content. To see the entire message, you must click on the “View original e-mail” link in the notice. This “downloads” the message to your device so that you can open it with a local tool (such as your e-mail reader, Microsoft Outlook). My team uses this method to receive certain alerts from our communities.sas.com platform. Here’s an example:

To get the unique e-mail address for a channel, right-click on the channel name and select Get email address. Any message that you send to that e-mail address will be distributed to the team.

Getting started with a Microsoft Teams webhook

In order to provide a richer, more integrated experience with Microsoft Teams, you can publish content using a webhook. A webhook is a REST API endpoint that allows you to post messages and notifications with more control over the appearance and interactive options within the messages. In SAS, you can publish to a webhook by using PROC HTTP.

To get started, you need to add and configure a webhook for your Microsoft Teams channel:

Right-click on the channel name and select Connectors.
Microsoft Teams offers built-in connectors for many different applications. To find the connector for Incoming Webhook, use the search field to narrow the list. Then click Add to add the connector to the channel.
You must grant certain permissions to the connector to interact with your channel. In this case, you need to allow the webhook to send messages and notifications. Review the permissions and click Install.
On the Configuration page, assign a name to this connector and optionally customize the image. The image will be the avatar that’s used when the connector posts content to the channel. When you’ve completed these changes, select Create.

The connector generates a unique (and very long) URL that serves as the REST API endpoint. You can copy the URL from this field — you will need it later in your SAS program. You can always come back to these configuration settings to change the connector avatar or re-copy the URL.

At this point, it’s a good idea to test that you can publish a basic message from SAS. The “payload” for a Teams message is a JSON-formatted structure, and you can find examples in the Microsoft Teams reference doc. Here’s a SAS program that publishes the simplest message. Add your webhook URL and run the code to verify the connector is working for your channel.

filename resp temp;
options noquotelenmax;
proc http
  /* Substitute your webhook URL here */
  url="https://outlook.office.com/webhook/your-unique-webhook-address-it-is-very-long"
  method="POST"
  in=
  '{
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
      "type": "AdaptiveCard",
      "version": "1.0",
      "summary": "Test message from SAS",
      "text": "This message was sent by **SAS**!"
  }'
  out=resp;
run;

If successful, this step will post a simple message to your Teams channel:

Design a message card for Microsoft Teams

Now that we have the basic plumbing working, it’s time to add some bells and whistles. Microsoft Teams calls these notifications “message cards”, which are messages that can include interactive features such as images, data, action buttons, and more.

Designing a simple message

Microsoft Teams supports a large palette of building blocks (expressed in JSON) to create different card experiences. You can experiment with these cards in the MessageCard Playground that Microsoft hosts. The tool provides templates for several card varieties, and you can edit the JSON definitions to tweak and design your own.

For one of my use cases, I designed a simple card to show the status of our recommendation engine on SAS Support Communities. (Read this article for more information about how we built and monitor the recommendation engine.) The engine runs as a service and is accessed with its own API. I wanted a periodic “health check” to post to our internal team that would alert us to any problems. Here’s the JSON that I used in the MessageCard Playground to design it.

Much of the JSON is boilerplate for the message. I drew the green blocks to indicate the areas that need to be dynamic — that is, replaced with values from the real-time API call. Here’s what the card looks like when rendered in the Microsoft Teams channel.

Since my API call to the recommendation engine service creates a data set, I can run that data through PROC JSON to create the JSON segment I need:

/* reading the results from my API call to the engine */
libname results json fileref=resp;
 
/* Prep a simple name-value data set with the results */
data segment (keep=name value);
 set results.root;
 name="Score data updated (UTC)";
 value= astore_creation;
 output;
 name="Topics scored";
 value=left(num_topics);
 output;
 name="Number of users";
 value= left(num_users);
 output;
 name="Process time";
 value= process_time;
 output;
run;
 
/* use PROC JSON to create the segment */
filename segment temp;
proc json out=segment nosastags pretty;
 export segment;
run;

I shared a version of the complete program on GitHub. It should run as is — but you would need to supply your own webhook endpoint for a channel that you can publish to.

Design a message with actions

I also use Microsoft Teams to share updates about the SAS Software GitHub organization. In a previous article I discussed how I use GitHub APIs to gather data from the GitHub service. Each day, my program summarizes the recent activity from github.com/sassoftware and publishes a message card to the team. Here’s an example of a daily update:

This card is fancier than my first example. I added action buttons that can direct the team members to the internal reports for more details and to the GitHub site itself. I used the Microsoft Teams documentation and the MessageCard Playground to design the experience:

Messaging apps as part of a DevOps strategy

Like many organizations, we (SAS) invest a considerable amount of time and energy into gathering metrics and building reports about our operations. However, reports are useful only when the intended audience is tuned in and refers to them regularly. With a small additional step, you can use SAS to bring your most interesting data forward to your team — automatically.

Whether you use Microsoft Teams or Slack, automated alerting and updates are a great opportunity to keep your teams informed. Each of these tools offers fit-for-purpose connectors that can tie in with information from other popular operational systems (Salesforce, GitHub, Yammer, JIRA, and many more). For cases where a built-in connector is not available, the webhook approach allows you to easily create your own.

The post How to publish to a Microsoft Teams channel using SAS appeared first on The SAS Dummy.