Integrating Contentful with Microsoft Teams using Adaptive Cards

In today’s digital-first workplace, the integration of content management systems (CMSes) with content collaboration tools is becoming increasingly important. This post explores how organizations can enhance team collaboration by integrating Contentful with Microsoft Teams, utilizing Adaptive Cards to create visually appealing and interactive notifications. The integration ensures that teams are promptly updated with real-time content changes, fostering efficient workflows and engagement. 

Adaptive Cards are a critical tool in this integration, enhancing how information is communicated within Microsoft Teams. These cards provide a customizable and interactive format for displaying rich content and actionable elements directly within Teams. Unlike traditional notifications, Adaptive Cards can include images, buttons, and other interactive components that make the information more engaging and accessible.

For example, when a new article is published in Contentful, an Adaptive Card can be triggered as a notification in Microsoft Teams. This card could display the article’s title, a brief summary, and even an image, along with buttons for actions such as Read More or Share. This not only makes the notification more attractive but also more functional, allowing team members to interact with the content directly from the notification.

By using Adaptive Cards, organizations can create more than just notifications — they create experiences that foster engagement and interaction within Teams. This capability is crucial for maintaining the fluidity of communication and collaboration in a remote or hybrid work environment, ensuring that every team member stays informed and connected with the content that matters most to their work.

Example card templates in the designer

Understanding webhooks

Webhooks are automated messages sent from apps when an event occurs. They have a wide array of uses, particularly in content management systems like Contentful, where they can trigger notifications for events such as content updates, release creation, or entry deletion. This functionality is vital for teams that rely on timely information, ensuring that everyone is on the same page without manual intervention.  

Setting up a webhook in Contentful

First, log into your Contentful space. Go to the "Settings" menu and click on "Webhooks." This is where you can manage your existing webhooks or create a new one.

To create a new webhook, click on "Add webhook." Give your webhook a name that makes its purpose clear. Eventually, you will paste the Microsoft Teams webhook URL into the URL field as this is where the notifications will be sent.

For testing, you might want to use a tool like webhook.site. This web-based tool lets you see the payload being sent and ensures the webhook is working. Just remember, if you're using the free version, it might not be completely secure, so avoid sending any sensitive data during testing. You can also check out the payload in the webhook Activity Log inside the Contentful app to make sure everything is running smoothly.

Next, choose the specific actions in Contentful that will trigger this webhook, like content publishing or updates. Don’t forget to set the header to Content-Type: application/json to make sure the data is formatted correctly. You can either use the default payload or customize it to fit your needs.

For this example, the webhook will be listening for a single event, in this case, "entry, publish. This will fire any time an entry of any type is published, so it's more efficient to add a filter to only trigger this event for the Blog Post content type. It’s also constrained to the environment “master,” but can be set to non-master environments for testing without changing published content.

The payload is set to default during development, to allow you to see all of the fields being sent.  

After publishing a blog post article, you can see the HTTP request and response for this webhook event in webhook.site or the Activity Log tab in the UI. The request shows all of the JSON data that is posted to the target when sending the default payload.

The default payload for the publish event of an entry contains metadata, field data, and system data for the entry in Contentful. The system data contains fields such as publishedBy, contentType, and revision number, while the field data contains the values of the content in those fields.

These can then be customized and transformed into the specific JSON format that MS Teams uses for layout and functionality. But first you need to know what that JSON format needs to look like, and that's where the Adaptive Card Designer tool comes in.

Understanding Adaptive Cards and the Adaptive Card Designer

Adaptive Cards are rich, interactive card elements that can display a variety of content, including text, images, and buttons. They adapt seamlessly across different devices and platforms, making them an ideal choice for enhancing notifications in Microsoft Teams.

The Adaptive Card Designer is an online tool that simplifies the creation of these cards. With its visual drag-and-drop interface, users can design cards without writing any code. The tool also allows for real-time previews and testing with sample data, ensuring that the final product looks and functions as intended.  

This way, you can avoid the classic development loop of first tweaking the JSON transforms in the webhook tool, firing the webhook by publishing the blog post, and then viewing the rendered card inside of MS Teams. Then repeating this loop for all changes until the card looks and functions correctly.

Designing a simple Adaptive Card for a blog post

Designing an Adaptive Card for a blog post with the Adaptive Card Designer is straightforward and involves adding elements visually, like the blog post title, a subtitle, and an action link to the entry in Contentful. Here’s how you can create this simple yet effective card using the Adaptive Card Designer.

Start by navigating to the Adaptive Card Designer website. This online tool is where you'll create and customize your Adaptive Card. Once there, click the "new card" button. This will open a modal window with a variety of templates for different use cases. For this example, choose to start with an empty card. This provides a clean slate, allowing you to add only the necessary elements for your blog post card.

Begin by dragging a "Text Block" element from the toolbox on the left onto the canvas. This text block will serve as the title of your blog post. Customize the font size, weight, and color to match your desired style. Next, add an "Action.OpenUrl" element to include a link to the full blog post in Contentful. Set the button title to something like "View in Contentful" and configure the URL to point to the entry in Contentful.

For testing, you can use a placeholder URL such as https://app.contentful.com/spaces/<your-space-id>/environments/<your-environment-id>/entries/<your-entry-id>.

As you design your card, the canvas area will provide a real-time preview, allowing you to see how the card will appear in different environments like Microsoft Teams. This ensures that your card renders correctly across all platforms. In this example, it’s set to use Microsoft Teams as the host app and Dark as the theme to match the current team preferences.

Testing with sample data

Once the card design is complete, it’s crucial to test it with real data to ensure it functions and continues to look as expected. 

To test your Adaptive Card design with real data, open the Sample Data Editor in the Adaptive Card Designer. This feature allows you to input JSON data that mimics the content expected from Contentful webhooks, and then template the card JSON to use fields from the sample JSON instead of them being hard-coded. The templating technique between the Adaptive Card Designer tool and Contentful’s webhook payload customization aren’t exactly the same, but they are very similar.

By using the JSON format of the Contentful webhook output as your sample data, you can see how actual content from Contentful will populate the card elements, ensuring dynamic data integration.  

First, copy the JSON payload of a blog post webhook in Contentful.  The simplest way to do this is to use the Contentful Webhook Activity Log screen for the given webhook. You should see something like the JSON below, with content for each field of the entry, and a single locale being populated.

Copy

Copy this JSON content and paste it into the Sample Data Editor of the Adaptive Card Designer.  

Note: One known issue with using the Adaptive Card Designer templating tool is that it cannot resolve the field if the key in the JSON contains a - character, such as “en-US”. To get around this, perform a find and replace of “en-US” to “enUS” before pasting the JSON into the Sample Data Editor.

After pasting in the webhook JSON, you can modify the Card Payload to use values from the Sample Data Editor JSON data with their templating language. The logic is described in detail here. The preview of the card will now show it rendered with the actual values of the posted Contentful webhook content.

For designing a complex card with many data fields and actions, having the ability to rapidly prototype the card without needing to send a Teams message, is a huge time saver. Now you have the exact JSON format that you need to post to MS Teams to get the card design you want.

Integrating your Adaptive Card with Contentful webhooks

Now that your card design is ready, it’s time to get it working with Contentful. Start by pasting in the JSON from the Card Editor into the webhook as a custom payload. Then, it’s mostly a matter of changing to the templating to use the Contentful transform method of JSON Pointers but that effort largely entails replacing “.” with “/” and adding “/payload” to the beginning of the pointer string. More information for the JSON Pointer syntax.

Now, after triggering this webhook, you can see the transformed output in the activity log. 

Now that the design and formatting work is done, you can complete the webhook configuration by setting up an incoming webhook in Teams, to convert the posted webhook card JSON into a rendered card inside of a Teams channel. 

Once configured on the Teams side, you will receive a URL indicating where to post the messages. Add that URL to your webhook in Contentful as POST, and save the webhook. You should now see the rendered card inside of MS Teams whenever a blog post is published in Contentful. Clicking on the action button of the card should also take you to the entry in Contentful.  

Wrapping up

Using the Adaptive Card Designer streamlines the creation and testing of well-designed MS Teams cards.

Integrating Contentful with Microsoft Teams using Adaptive Cards keeps your teams informed of important content and workflow events in a timely manner. This integration not only enhances the functionality of notifications but also promotes better engagement and interaction within your team.

By leveraging these tools, you ensure that every team member stays connected and updated with the most relevant content, ultimately driving more efficient and cohesive collaboration.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.