But this isn’t simply about new tools—it’s about sustained, structural changes in how teams work, how quickly stakeholders are involved, and how rapidly organizations can deliver value.

Each technological shift has seen team sizes shrink, feedback iterations with stakeholders shorten, and time-to-market accelerate.

At the center of this new delivery model is the Forward Deployed Engineer, uniquely positioned for projects where the business outcome is clear but the route is still being charted—or for companies that have defined a compelling digital vision but can’t operationalize it through traditional delivery methods

What is a Forward Deployed Engineer

The Forward Deployed Software Engineer (FDSE) model was pioneered by Palantir Technologies, renowned for solving complex, data-driven problems by embedding engineers on-site within client environments. Palantir demonstrated that for flexible, powerful platforms, “ease of use” is not enough—true value comes only when expert engineers tailor solutions to real-world, customer-specific contexts.

Other technology leaders quickly followed. ServiceNow employs FDSEs to deploy enterprise AI, Salesforce for its AgentForce platform, AMD to operationalize AI hardware, and OpenAI for production AI model integrations. As enterprise platforms, particularly in AI and data, become more powerful, the main obstacle becomes not technology, but its effective application within a customer’s unique operational landscape.

FDSEs meet this challenge head-on. Their role is:

• Full technical ownership: The FDSE becomes the top authority for every customer deployment, architecting and iterating with autonomy.

• Strategic enablement: Like a startup CTO, the FDSE drives results, adapts on the fly, and navigates ambiguity.

• Deep integration: These engineers become operational partners, understanding business processes firsthand and iterating solutions live for maximum impact.

In practice, the FDSE is an archetype for high-uncertainty transformation. With today’s OutSystems and low-code architectures, their skillset is more important and accessible than ever, especially for organizations unable to specify requirements or adapt to traditional agile models.

My Personal Perspective

When I stepped into the Low-Code world—specifically when I started developing with OutSystems in 2017 and became familiar with the OutSystems Delivery Process—I quickly realized that, to succeed as a service provider in Germany, an alternative delivery model was required.

While OutSystems, like most modern platforms, encourages agile practices and time-boxed iterations, the practicalities within the German market—particularly among the Mittelstand, our economic backbone comprised predominantly of privately and often family-owned businesses—are often different.

When building my team, I looked out for individuals with a wide technological perspective, quick-thinking abilities, and above all, the willingness and skill to work directly with business stakeholders. In essence, these were Forward Deployed Engineers before that label became widespread. At the time, I called this blended role “Solution Engineer.”

The reasoning was straightforward. For many Mittelstand companies, the concept of agile projects, sprints, or even time-boxed results is almost unknown.

The notion of investing in custom-developed software—as opposed to tailoring an existing standard product—is itself a profound paradigm shift. I recognized early on, that introducing these companies to a new way of working while also delivering their first applications would create unnecessary friction and potentially jeopardize project outcomes.

This insight confirmed for me the importance of a delivery model where technically capable, versatile engineers engage side-by-side with business users—breaking down barriers, minimizing the burden of change, and advancing digital innovation on the customer’s terms.

You could say that this was the Forward Deployed approach in practice—before the terminology existed.

From Linear to Modular: The Evolution of Software Delivery

Historically, organizations relied on the waterfall approach—large, specialized teams progressing through rigid phases, with feedback and business validation often arriving only at the end.

With agile, not only did cross-functional teams become the norm, but smaller teams worked in shorter timeboxes, providing more frequent opportunities for stakeholder input and business alignment.

Low-code took these trends even further, reducing the headcount needed for production-ready applications, compressing feedback cycles, and dramatically decreasing time-to-market with visual modeling and modular reuse.

The latest evolution—AI-assisted AppGen—amplifies these trends, enabling lean teams to generate and evolve working solutions through near real-time dialogue with stakeholders.

What Actually Gets Better as We Move Up the Stack

At each stage, four trends remain notably consistent:

• Team sizes decrease as processes and technology enhance collaboration and execution.

• Feedback loops with stakeholders shorten significantly, reducing cycles from months to weeks, days, or even hours.

• Time-to-market speeds up, allowing organizations to deliver measurable value and adapt more quickly.

• The cost-risk-benefit barrier is lowered, enabling consideration of digital solutions that were previously too risky to develop.

AppGen makes these benefits concrete—not by shifting development to business users, but by equipping skilled engineers to work hand-in-hand with the business. The OutSystems Forward Deployed Engineer can rapidly prototype, engage directly with stakeholders, and deliver incremental value—even when requirements remain ambiguous or unrefined—a perfect fit for organizations that have a strong vision but can’t translate it into classic delivery.

Why the OutSystems Forward Deployed Engineer Is a Capability-Driven Role

Modern delivery is about more than solving isolated problems; it’s about building reusable capabilities in the face of incomplete requirements or emerging specifications. This demands a role that can bridge vision and execution, even when “how” is unclear or agile methods are unsuitable.

With every evolution in delivery, the OutSystems Forward Deployed Engineer leverages:

• Smaller, more versatile teams for rapid collaboration.

• Shorter, more frequent feedback cycles for validation.

• Faster time-to-market as modular capabilities are assembled on the fly.

• The ability to deliver even when requirements are high-level or incomplete.

Beyond Experimental Projects: When Vision Outpaces Specification or Agile Isn’t Feasible

While experimental initiatives—where the outcome is clear but the implementation path is undefined—are a natural fit for OutSystems Forward Deployed Engineers, these are not the only contexts where this role thrives.

Many organizations can articulate a strategic digital vision (“we want a new customer portal” or “an integrated process experience”) but are unable to produce the detailed specifications required for classic or agile delivery. Others, because of their market, structure, or culture, may find agile frameworks, sprints, and backlogs difficult to sustain—yet the imperative to transform remains.

How Capabilities Are Developed and Delivered

The delivery workflow is optimized for speed and engagement:

• Lean, empowered teams—often a single OutSystems Forward Deployed Engineer with SMEs—collaborate from vision, not just requirements.

• Rapid, frequent feedback guarantees each iteration stays relevant.

• Time-to-market stays short as solutions iterate with business needs and discoveries.

Supporting the Model: The Lean Center of Excellence

A lean Center of Excellence supports reuse, governance, and rapid scaling—further reducing necessary team size and time-to-market. AI-guided discovery of assets makes each delivery faster and more robust over time.

The Organizational Payoff: Compounding Returns

Organizations progressing on this journey see profound changes: teams shrink, stakeholder feedback is immediate, and time-to-market accelerates dramatically. This model delivers even in high-change or ambiguous environments, creating a scalable and repeatable approach to capability-driven transformation.

Defining the OutSystems Forward Deployed Engineer

An OutSystems Forward Deployed Engineer:

• Thrives in ambiguity—able to operate from vision, not just requirements.

• Leads or participates in small, nimble teams within business operations.

• Delivers rapid, collaborative feedback cycles to refine solutions live.

• Translates business intent into reusable digital capabilities—even without classic requirements or agile discipline.

• Assumes end-to-end technical and business responsibility—often acting as principal driver of success.

Conclusion: Shorter, Faster, More Flexible Paths to Value

With an OutSystems Forward Deployed Engineer, organizations are no longer constrained by their ability to write detailed specifications or fit into traditional agile frameworks. Digital solutions—and business value—begin to flow thanks to smaller, multidisciplinary teams, rapid and continuous stakeholder feedback, and dramatically accelerated time-to-market. This model does not require clients to fully adopt or internalize new delivery methodologies overnight, nor does it demand an immediate cultural shift toward agile processes that may be unfamiliar or impractical.

Instead, the OutSystems Forward Deployed Engineer meets the business exactly where it is. By embedding with business stakeholders and iteratively developing solutions directly in their context, this role minimizes the friction and "change tax" that often derails digital transformation before it can start. Every iteration is an opportunity for learning, alignment, and tangible results—reducing operational risk and ensuring solutions are both technically robust and business-ready.

As transformative technologies like low-code, AI-assisted development, and modular digital capabilities become more prevalent, the OutSystems Forward Deployed Engineer stands out as a strategic enabler of continuous innovation. Whether an organization’s challenge is ambiguity in requirements, unfamiliarity with agile, or the simple need to move fast without heavy overhead, this role is the bridge from digital vision to working, scalable solutions.

Ultimately, value today flows not from documentation or theoretical roadmaps, but from the ability to turn intent into reality—side by side with the business, through smaller teams, shorter feedback loops, and a relentless focus on rapid, user-centered delivery. For organizations ready to accelerate and de-risk their digital journey, embedding an OutSystems Forward Deployed Engineer isn’t just a delivery tactic—it’s a competitive advantage.

OutSystems puts a lot of effort into making interoperability as easy as possible. As of now (Feb 2026), it's already possible to connect OutSystems 11 data (Entities) to ODC for both reading and writing, with more features on the way. Watch the Platform Interoperability on-demand webinar for an overview.

One of the still upcoming features is Identity Integration, which will let OutSystems 11 users sign in to ODC applications. Meanwhile, community members have already started asking on the forum about the easiest way to connect users with ODC.

That's why I created a component, essentially a Mini Identity Provider, for OutSystems 11. You can use it right away to connect your OutSystems 11 user base to ODC by adding a new Identity Provider in ODC Portal.

When You Should Care

This article and the Forge component are relevant to you if you're using the default username/password authentication method in the OutSystems 11 Users Provider. This includes any custom modifications you've made.

It doesn't apply if you're already using an external Identity Provider like Microsoft Entra, Auth0, or others.

If you are using OutSystems 11's default authentication and want your users to sign in to ODC with their O11 account, this article and component might be useful for you, even after OutSystems releases the official identity integration. OutSystems might not cover every possible edge case or your specific identity integration needs right away. In that case, you can use the component to tailor it to your needs and later transition smoothly to the official integration.

Besides all this, you may learn some implementation details about OAuth 2.0 Authorization Code flow, which can be valuable in many other situations.

Overview

The ODC Identity Bridge application consists of three modules:

• OpenIDBridge - This web module provides a sample Login (Authorize) screen with only a username and password.

  The direct URL of the Authorize screen is the URL returned by the ODC GetExternalLoginURL client action. The user is redirected to this URL to authenticate.

• OpenIDBridgeAPI - This service module is a core implementation of an OpenID Connect/OAuth 2.0 compatible Identity Provider. The module exposes REST operations for ODC to discover endpoints, like the Authorize endpoint and exchange tokens.

• OpenIDBridgeUtility - This code module provides only a single action, UrlDecode. You likely already have a similar utility action in your environment and may want to replace it.

Prerequisites

Before we dive further into the details, let's set up the necessary configurations to get ODC Identity Bridge up and running.

• Install ODC Identity Bridge from Forge.

• In O11 Service Center, we need to configure some Site Properties of the OpenIDBridgeAPI module.

• In the ODC Portal, we need to add an Identity Provider configuration.

Open the OpenIDBridgeAPI module in Service Center and click on the Site Properties tab. First, set a value for ClientId and ClientSecret. You can think of them as a service account's username and password that ODC uses to identify itself to the OpenID Bridge Identity Provider.

• ClientId - This can be any text string, such as "odc-dev-env" or just a UUID.

• ClientSecret - Enter a strong password here.

Leave the Site Properties tab open as we need to revisit it shortly. Open another tab and browse to your ODC Portal and click on Manage - Identity providers.

Click Add provider - OpenID Connect.

• Provider name - Choose a name for this identity provider, like OutSystems 11 Development.

• Discovery endpoint - Use the URL: https://<Your O11 environment domain name>/OpenIDBridgeAPI/rest/Oauth/Discovery. After clicking on Get Details, the additional configuration details will appear on the right.

• Client ID - Enter the Client ID you set in the Site Properties of the OpenIDBridgeAPI module in Service Center.

• Client secret (secret value) - Enter the Client secret you set in the Site Properties of the OpenIDBridgeAPI module in Service Center.

• PKCE - Select None.

• Organization user email verification - Select Trust all user emails as verified.

Under Claim mapping:

• Username - Set to preferred_username.

Leave all other settings as they are and click Save.

Next, click on Assign and link this Identity Provider configuration to applications in your development stage.

Finally, click on the Redirect URLs tab and expand Apps in Development. Copy the value of the Login URL.

In the O11 Service Center, go to the Site Properties of the OpenIDBridgeAPI module and paste the Login URL value into the RedirectUri property.

Authentication Flow

With ODC Identity Bridge installed and configured lets look on how the overall authentication flow works.

• An unauthenticated user tries to access an ODC application.

• A SecurityException is thrown and handled in Common - OnException.

• Your handler executes the GetExternalLoginURL client action to obtain the Authorize endpoint URL of the ODC Identity Bridge application in OutSystems 11.

• Your handler redirects the user to this URL to sign in with O11 user credentials.

• After signing in, the ODC Identity Bridge first redirects the user back to the RedirectURI of the ODC Identity Broker. This redirect includes an Authorization Code (code).

• The ODC Identity Broker uses this code to request an identity and access token from the Token endpoint of the ODC Identity Bridge application.

• It then decodes the Identity token, finds a user account or creates a new one, and authenticates the user.

• Finally, it redirects the user back to the application they requested.

You already know that having a user account in ODC doesn't automatically grant access to an application. The user needs additional role assignments. There are several ways to ensure a user has roles assigned when signing in to ODC.

• Pre-provision all user accounts from O11 to ODC using a Timer that creates or updates user accounts in ODC and assigns roles.

• Use ODC Group Mappings to apply application roles based on attributes of a user's Identity Token.

Please refer to the OutSystems Documentation Managing authorization and authentication for end-users - ODC Documentation for detailed instructions on adding external identity provider sign-in to applications.

ODC Identity Bridge

Let us look at some of the implementation details of the ODC Identity Bridge application. In Service Studio open the OpenIDBridgeAPI module.

Service Actions

ODC Identity Bridge exposes two service actions that are used in the sample Authorize screen in the OpenIDBridge web module.

Bridge_ValidateAuthorizationRequest

Validates the parameters that are sent by the ODC Identity Broker when redirecting a user to the Authorize endpoint (your Login screen in OutSystems 11). This action returns validation errors that are useful to troubleshoot the integration.

Bridge_AuthorizeUser

This service action is executed after a user submits its credentials in the Authorize screen of the OpenIDBridge web module.

• User_Login - Performs a username/password login using the User_Login action of the OutSystems 11 user provider.

• AuthCode - Generates a random authorization code.

• AuthorizationRequest_Create - Saves the authorization code along with the user identifier and additional authentication request details to the database.

• CallbackUri - Constructs the URL to which the browser must be redirected. This URL request includes the authorization code.

Discovery Endpoint

In Logic - Integrations - REST - Oauth inspect the exposed Discovery operation. This endpoint serves an OpenID Connect Discovery Document that looks like this

{
    "issuer": "https://<your environment>",
    "authorization_endpoint": "https://<your environment>/OpenIDBridge/Authorize",
    "token_endpoint": "https://<your environment>/OpenIDBridgeAPI/rest/Oauth/Token",
    "token_endpoint_auth_methods_supported": [
        "client_secret_post"
    ],
    "jwks_uri": "https://<your environment>/OpenIDBridgeAPI/rest/Oauth/Keys",
    .... more options
}

The action flow simply builds the values for the discovery document. The important ones are:

• authorization_endpoint - This is the full URL to your OutSystems 11 Login Page. This value must be changed if you roll your own Login screen.

• token_endpoint - This endpoint is used by the ODC Identity Broker to exchange an authorization code for ID and access tokens.

• jwks_uri - This endpoint provides the public key used by the ODC Identity Bridge to sign both ID and access tokens.

Token Endpoint

Next, examine the Token operation. This endpoint is used by the ODC Identity Broker to exchange an authorization code for ID and access tokens. After the user successfully signs in, the authorization code is sent to the RedirectURI of the configured Identity Provider in ODC Studio as part of the query string.

• ParseCodeExchangeForm - The Token endpoint uses a URL-encoded form, and this action converts the form content into a structured format.

• GetAuthorizationRequestByCode - Retrieves the authentication details saved during user login (Bridge_AuthorizeUser)

• CreateIdentityToken - Creates and signs a JWT Identity Token using the popular JWT component.

• CreateAccessToken - Even though ODC only uses the Identity token to authenticate a user, an access token must always be returned. This action creates and signs a JWT Access Token.

Keys

This operation serves the public key that matches the private key used to sign tokens from Data - Resources - Keys and returns it. See Roll Your Own Keys for details on how to exchange the signing key.

Adding Additional Claims

To use ODC's Group Mapping, you can add extra key-value pairs (claims) to the Identity Token. Modify the CreateIdentityToken and add additional claims to the LocalClaims local variable.

Roll Your Own Keys

ODC Identity Bridge has already included a public/private key pair to sign identity and access tokens, but you should replace the default with your own keys as soon as possible.

Run the following commands create a private and public key in PEM format.

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

Next, you need to convert the public key (public.pem) to a JSON Web Key (JWK). The simplest way is to use an online converter like https://pem2jwk.vercel.app/ and save the JSON result to a file named public.jwk.

You can use any converter, but ensure that the resulting JSON document follows this structure:

{
    "keys": [
        {
            "kty": "RSA",
            "n": "<n>",
            "e": "AQAB",
            "ext": true,
            "kid": "o11public",
            "alg": "RS256",
            "use": "sig"
        }
    ]
}

Finally, in Data - Resources - Keys, replace private.pem with your custom private key and the JWK conversion result with public.jwk.

Summary

By following this tutorial, you have successfully set up a working identity bridge between OutSystems 11 and OutSystems Developer Cloud.

You installed and configured ODC Identity Bridge in your O11 environment that exposes an OpenID Connect / OAuth 2.0 Identity Provider, and registered it in the ODC Portal. As a result, users from your existing OutSystems 11 user base can now sign in to ODC applications using their O11 credentials.

Thank you for reading. I hope you enjoyed it and that I've explained the important parts clearly. If not, please let me know 😊 Your feedback is greatly appreciated.

Follow me on LinkedIn to receive notifications whenever I publish something new.

However, in many situations, you want your application to interact with the Graph API on behalf of the logged-in user, allowing access only to the resources the user is allowed to use. Additionally, some Graph API resources are only accessible on behalf of a user. To access these, you need to perform an OpenID Authorization Code flow, where the user signs in to Entra using the browser to get an access token that represents the user's permissions.

In ODC, you can add Microsoft Entra as an Identity Provider, allowing users to sign in to your applications with their Entra account. You can set it up in just a few minutes by:

• Registering and configuring an application in your Microsoft Entra tenant.

• Configuring a new Identity Provider in the ODC Portal using your registration details.

• Enabling the Identity Provider in your applications as an additional or sole authentication method.

But unfortunately, ODC does not let you retrieve the original Microsoft Entra access token needed to access Graph API resources. Instead, ODC uses the identity token from Microsoft Entra to map (or create) a user in your ODC environment. The original identity and access tokens retrieved from Entra are not kept.

One option is to start another Authorization Code flow in your application to request an access token. However, this isn't a great user experience. The user already signs in with their Entra credentials and then has to authenticate again just for you to get the access token.

The other option, which is the focus of this article, is to implement an Entra ID proxy. This proxy acts as an Identity Provider for your applications, forwards requests to Microsoft Entra, and caches the tokens retrieved from Microsoft Entra for you to use.

Entry ID Proxy is available on OutSystems Forge for OutSystems Developer Cloud.

Entra ID Proxy Overview

Entra ID Proxy is an OutSystems application that needs to be set up as an Identity Provider in the ODC Portal. It provides three REST API Endpoints:

• openid-configuration - This retrieves the original OpenID discovery document from your registered Entra application and changes the authorize and token endpoint values to point to the Proxy instead of the Microsoft Entra endpoints.

• authorize - This proxies authorize requests and redirects the user's browser to the Microsoft Entra authorize endpoint.

• token - This endpoint not only proxies requests to the Entra token endpoint but also caches the identity and access tokens from Microsoft Entra after the authorization code exchange.

Let's take a high-level look at how the Entra ID Proxy interacts with an OutSystems application, the platform's Identity Management, and Microsoft Entra.

Prerequisites

After downloading the Entra ID Proxy application, you first need to register an application in your Entra tenant, as explained in the documentation: Add Microsoft Entra ID for use as an external identity provider - ODC Documentation.

Entra ID Application

Ensure you have assigned the following delegated permissions to your application registration:

• openid - This scope allows OutSystems to retrieve the identity token used to map or create a user.

• email - Enables the email and email_verified claim in the identity token.

• profile - Adds general profile information, such as the name, to the identity token.

• offline_access - This scope lets the proxy request a refresh token along with the identity and access token. The Proxy application needs this token to automatically refresh the access token after it expires, without requiring the user to log in again.

Additionally, add any extra Graph API permissions, such as Mail.Read and Mail.Send, for the resources you want to use. Your API permission screen should look like this:

From your Entra application you need the following informations copied for the next steps

• Application (client) Id

• Client Secret

• Directory (tenant) Id

• API / Permissions name of the additional delegated permissions you added

Entra ID Proxy Settings

Next, we will configure the Entra ID Proxy application settings. In the ODC Portal, select the Entra ID Proxy application and set up the following:

• EntraTenantId - Directory (tenant) Id of your registered Entra application

• EntraScope - Space-delimited Graph API Scopes (not openid, email, profile, and offline_access)

Identity Provider

Finally, we configure Entra ID Proxy as an Identity Provider.

For the Discovery endpoint, instead of using Microsoft Entra's discovery endpoint directly, you configure the Entra ID Proxy Discovery endpoint. The URL looks like this:

https://<FQN of your stage>/EntraIDProxy/rest/OAuth2/well-known/openid-configuration

• Client ID - Paste the Application (client) Id value from the Entra application registration.

• Client Secret - Paste the generated client secret value from the Entra application registration.

• Scope Mapping - The scopes openid, email, and profile are already configured by default. Add another entry: offline_access.

Leave all other values as they are and save the configuration. Then, assign the new Identity Provider to the stage and applications.

With all the prerequisites completed, you should now be able to sign in to applications using the newly configured Identity Provider.

Retrieving an Access Token

Entra ID Proxy provides two service actions that let you retrieve an access token:

• Entra_GetAccessTokenByUpn - This returns an access token for a given Universal Principal Name, typically the user's email address.

• Entra_GetAccessTokenByObjectId - This returns an access token for a given Object Identifier, which is the unique identifier of a user object in Entra.

Implementation

Both service actions call the server action GetAccessTokenByUpnOrObjectId.

This action performs the following steps:

• Attempts to retrieve the cache entry from the Token entry using either the Universal Principal Name or Object Identifier. If no entry exists, the action returns with IsSuccess = False.

• Deserializes the binary payload, which contains the access token and refresh token, of the found entry.

• Depending on whether the access token is still valid or has expired, it either returns the access token directly from the cache or tries to refresh the token before returning it.

Retrieving an Access Token in your Applications

In your application create a wrapper server action GetAccessToken that performs the following steps.

• Lookup the user record from the User entity filtered to GetUserId().

• Call the Entra_GetAccessTokenByUpn service action

• Return the success indicator IsSuccess and the access token

Remarks on the Token Store

The Token entity in Entra ID Proxy stores the following information

• Audience - Extracted from aud claim of the access token.

• Issuer - Extracted from the iss claim of the access token. This identifies your application registration.

• IssuedOn - Extracted from the iat claim and specifies when the access token was issued.

• ExpiresOn - Extracted from the exp claim and specifies when the access token expires. By default Entra access tokens expire after 1 hour.

• Subject - Extracted from the sub claim. Unique identifier of the user or principal in Entra. Typically the same value as ObjectId, but not guaranteed.

• ObjectId - Extracted from the oid claim. Unique Identifier of the user or principal in Entra. Use this instead of Subject.

• Payload - Access and Refresh token as binary data.

• ClientId - Application (client) Id for your application registration.

• ClientSecret - Client Secret of your application registration.

Summary

In this article, I'm introducing my OutSystems Forge component, Entra ID Proxy. Entra ID Proxy acts as an Identity Provider proxy in the OutSystems Developer Cloud and stores access tokens retrieved from Microsoft Entra after user authentication. These access tokens can be used to interact with the Microsoft Graph API with delegated permissions, allowing your application to interact with the Graph API on behalf of a user and their permissions. The access token can also be used to get more user information through the user info endpoint or the User resource in the Graph API.

Thank you for reading. I hope you enjoyed it and that I've explained the important parts clearly. If not, please let me know 😊 Your feedback is greatly appreciated.

Follow me on LinkedIn to receive notifications whenever I publish something new.

Let's consider the following scenario.

You are asked to implement a simple product discount. You need to create a discount scale that offers a discount based on membership status.

• Bronze status members receive 2%

• Silver status members receive 5%

• Gold status members receive 10%

Such a discount calculation can easily be implemented in ODC with an entity containing the discounts for each membership level. However, these discount calculations can change quickly over time, and changes could include:

• Discounts should not be applied if the product is already discounted.

• A discount should only be applied if the product's value exceeds a certain amount.

• A discount should only be applied if at least three items of the product are purchased.

• or a combination of the above……

Besides these permanent or semi-permanent changes, you might also encounter temporary changes, like additional discounts during a specific timeframe or even a complete change in the discount calculation if the company updates their membership program.

In short, implementing business rules directly within an application can become a burden and you may even risk losing money if you can't adapt to changes quickly enough. Externalizing business rules is the solution, as it allows you to define and modify business rules at runtime without changing server actions and redeploying the application.

Demo Application

This article features a demo application called "RulesEspresso Demo," available on ODC Forge.

• In the ODC Portal, navigate to Forge - All Assets.

• Search for "RulesEspresso Demo".

• Click on Install.

This demo relies on:

• RulesEspresso - This external logic library is the rules engine implementation you can use in your own applications.

RulesEspresso Introduction

RulesEspresso is a simple implementation of a business rules engine. At a glance it allows you to

• Provide a flat property JSON document containing data as the rules evaluation context.

• Include an optional JSON Schema for data validation.

• Define one or more rules using C# expressions to evaluate data conditions, returning either true or false.

• Optional result C# expressions for each rule to add calculated properties to the rules evaluation context if the rule expression evaluates to true.

Parameters

RulesEspresso external logic library contains a single action EvaluateRules with the following input parameters

dataObject

This parameter accepts a JSON document with key/value pairs that can be used in rule definitions. It serves as the context for a single run of EvaluateRules. To generate the dataObject input, you can:

• Create a structure with attributes.

• Use the structure as a local variable in a server action flow and assign values to it.

• Serialize the variable using the JSON Serialize action - with Serialize Default Values set to Yes!.

• Use the serialized result as the value for the dataObject input parameter.

ruleDefinitions

This parameter accepts a list of individual rules. Each rule consists of:

• RuleName - Any text. Each rule is evaluated separately, and you can use the rule name to identify it in the result of the Evaluate Rules action.

• EvaluationExpression - A boolean C# expression. This is where you specify a condition for the rule evaluation. Attributes of the dataObject are referred to by their names, and you can use C# methods within the conditions, such as DateTime.Now.

• ResultExpression - An optional C# expression that is evaluated if the EvaluationExpression is true. The ResultExpression can return a static or computed value, adding to the rules evaluation context, allowing you to use the value in subsequent rules.

• ResultPropertyName - Required if ResultExpression is set. This is the property name under which the result of ResultExpression should be added to the rules evaluation context.

jsonSchema

Takes an optional JSON schema to validate the dataObject. This validation is done only once, applying only to the input parameter and not to any ResultExpression values added during rules evaluation. The JSON schema is an excellent way to ensure that all necessary input parameters for rules evaluation are provided and have the correct values.

Example

Let us do an example. We want to pass the total value of a purchase busket, along with a membership status and calculate a discount based on that:

• Bronze status members receive 2%

• Silver status members receive 5%

• Gold status members receive 10%

Our dataObject parameter looks like this

{
  "totalValue": 7450.00,
  "memberStatus": "Silver"
}

The ruleDefinitions

Rule 1:

• RuleName: IsBronze

• EvaluationExpression: memberStatus == “Bronze”

• ResultExpression: totalValue * 2 / 100

• ResultPropertyName: discount

Rule 2:

• RuleName: IsSilver

• EvaluationExpression: memberStatus == “Silver”

• ResultExpression: totalValue * 5 / 100

• ResultPropertyName: discount

Rule 3:

• RuleName: IsGold

• EvaluationExpression: memberStatus == “Gold”

• ResultExpression: totalValue * 10 / 100

• ResultPropertyName: discount

These rules evaluate the value of memberStatus and calculate the discount.

Finally, we are adding a jsonSchema to ensure that memberStatus is either Bronze, Silver, or Gold, and that totalValue is greater than 0.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "totalValue": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "memberStatus": {
      "type": "string",
      "enum": ["Bronze", "Silver", "Gold"]
    }
  },
  "required": ["totalValue", "memberStatus"],
  "additionalProperties": false
}

You can try it out in the demo application and the Last Evaluation Result should look like this

Change the values and add some extra rule expressions.

Result

After evaluation, the results are returned in the ValidationResult output parameter:

• IsValid - This boolean value is true if all rules evaluated to true.

• Document - Contains the rules evaluation context JSON document, including all added result properties.

• RuleResults - An array of individual rule results. There is one entry for each rule evaluated, with the RuleName and a boolean IsValid property indicating whether the rule evaluated to true. You can use these individual entries to selectively take action within an action flow based on the result of a rule.

Summary

This article introduces the RulesEspresso external logic library for OutSystems Developer Cloud. RulesEspresso is a simple rules engine that lets you externalize business rules instead of hard-coding them into OutSystems applications. While it handles many use cases, for more complex scenarios, you might want to consider a Business Rules Management Solution. These solutions offer many extra features, including custom code integration and enterprise-level business rules evaluation, unlike RulesEspresso, which is designed for application-centric rules evaluation.

I hope you enjoyed it and would appreciate your feedback.

In some situations, you might need to build a form dynamically, along with its data model, or even let an end-user define a form and its elements while using the application. Assessments or surveys are good examples of such user-defined forms. Additionally, you could consider dynamically creating a form from an AI model operation result.

In this article, we explore how to implement my Runtime Forms component available on ODC Forge. The library allows you to dynamically describe and render a form. This approach is also called declarative forms, where you specify what the form should look like and how it should behave in a configuration (in this case, a structure), instead of placing individual input elements on the canvas like with static forms.

Demo Application

This article includes a demo application called "Runtime Forms Demo," available on ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "Runtime Forms Demo".

• Click on Install.

This demo depends on:

• Runtime Forms - This is the main library you can use and customize for your own applications. It offers a single widget to render a declarative form.

Runtime Forms Introduction

The library you downloaded from ODC Forge includes a single UI widget for rendering a declarative form. Think of it as a starting point that you can improve and customize for your own needs.

It supports the following features:

• Renders various input elements based on parameters (Fields) that describe them.

• Populates data (Data) into input elements from a JSON document.

• Validates the form on submission using HTML5 validation attributes.

• Sends form data as a JSON document upon submission (OnSubmit).

Supported Form Elements

The form elements you can use with the widget are limited to the following input types:

Text Inputs

• Text - A single-line text field. This is the default value for an input element.

• Textarea - A multi-line text field.

• Password - A single-line text field where the input is obscured to protect sensitive information.

• Email - A field specifically for entering one or more email addresses. Validation ensures that the text entered is a valid e-mail address.

• Search - A single-line text field for entering search queries. It may include a control to clear the entered text.

• Tel - A field for entering a telephone number. Unlike email, it doesn't enforce a specific syntax, but it may trigger a numeric keypad on mobile devices.

• Url - A field for entering a URL. The browser may provide validation to ensure the text is in a valid URL format.

Date and Time Inputs

• date - A control for entering a date (year, month, and day).

• time - A control for entering a time (hour and minute).

• datetime-local - A control for entering both a date and time, without time zone information.

• month - A control for entering a month and year.

• week - A control for entering a week and year.

Numeric Inputs

• number - A field for entering a number.

Selection Inputs

• radio - A radio button that allows the user to select only one option from a group of choices.

• checkbox - A checkbox that allows the user to enable or disable.

All input elements are displayed in the order specified by the Fields input parameter of the widget.

Field Configurations and Validations

Input field configurations and validations are divided into two parts: a common set of configuration elements that apply to all supported form elements, and type-specific settings that apply only to individual form element types.

Common

The following settings apply to all types:

• Name - The name attribute of the form element. This name also becomes the attribute name of the JSON data document you receive when you submit the form.

• Type - The input element's type attribute. The FieldType static entity provides the supported element types as described above.

• Label - If present, the widget adds an extra <label> tag for the form element.

• Text - If present, this text is displayed right above the form element. You can use it to add extra descriptions or guidance for the form element.

• Placeholder - If present, it sets the placeholder attribute of the form element.

• IsRequired - If set to True, it adds the required attribute to the form element, making user input necessary.

• IsDisabled - If set to True, it adds the disabled attribute to the form element. When the form is submitted, data from disabled elements is excluded.

• IsReadOnly - If set to True, it adds the readonly attribute to the form element. Data from readonly elements is included when the form is submitted.

• HasAutoFocus - Sets the autofocus attribute for the form element. Ensure that only one element has autofocus.

• TabIndex - Defaults to 0. When set, this configures the tab order of the element.

Type-specific

Type-specific settings are found in the Config object. Depending on the chosen input type, the following settings apply.

For text, textarea, password, email, search, tel and url the following settings apply:

• MinLength - Specifies the minimum number of characters the user must enter for the input to be considered valid.

• MaxLength - Specifies the maximum number of characters the user can enter into the input field.

• Pattern - Specifies a regular expression that the input field's value is checked against. It allows for complex validation rules.

• Autocomplete - Specifies whether a browser should automatically complete the input based on values the user has entered previously. Can be set to "on" or "off".

• Rows (only applicable to textarea) - The number of rows of the multi-line text input element.

For date, time, datetime-local, month and week:

• Min - Specifies the earliest date/time/month/week that can be selected.

• Max - Specifies the latest date/time/month/week that can be selected.

For number:

• Min - Specifies the minimum allowed value for the input.

• Max - Specifies the maximum allowed value for the input.

• Step - Specifies the legal number intervals (e.g., step="2" allows 0, 2, 4...). any allows any value.

For radio and checkbox:

• IsChecked - A boolean attribute that specifies if a checkbox or radio button should be selected by default when the page loads.

• Options (Radio only) - A list of Label/Value pairs for the radio options to select from.

Most of the settings above are related to validation, and the library uses the browser's built-in form validation. You can read more about this client-side form validation on MDN.

Applying and Submitting Data

The Data input parameter lets you add a JSON document as a string. The library attempts to apply the attribute values to the corresponding input elements based on the name.

Consider the following form:

• A text field named fullName

• A checkbox field named isMember

• A radio field shirtSize with the Label/Value pairs [Small - S], [Large - L], and [X-Large - XL]

The JSON document to apply all values would look like this:

{
  "fullName": "Stefan Weber",
  "isMember": true,
  "shirtSize": "XL"
}

Similarly, when you submit the form, you will receive an equivalent JSON document as the OnSubmit payload.

Library Limits

By the time of writing the Runtime Forms library does not support

• Validations for Radio buttons.

• Conditional visibility of form elements.

Demo Walkthrough

Let's take a closer look at how this works. In ODC Studio, open the Runtime Forms Demo application.

In the Logic tab, open the BuildSampleForm server action. This action is designed to create individual form elements using the FieldDefinition structure. It returns a list of FieldDefinition that serve as input parameters for the library's RuntimeForm widget.

Check the various configurations of the field elements.

In the Interface tab open the Run screen.

The GetFormDefinition data action executes the BuildSampleForm server action. The result of the data action is bound to the Fields input parameter of the RuntimeForm widget.

The local DataEntry variable is linked to the JSON Data textarea on the right side of the screen. When you click the Apply Data button (triggering the ApplyDataOnClick client action), the content of this variable is assigned to the DataSubmitted variable, which is bound to the Data input parameter of the widget.

When running the demo you will see the following screen.

• Hit the Apply Data button for applying the provided JSON data to the form.

• Leave the Company Mail Address empty and click the Submit button. Note the validation error message below the mail address.

• Enter a invalid value into the mail address field e.g. me@ and note the validation message.

• Fill in all required fields and click the Submit button. Note the JSON data in the Last Submitted JSON data area.

• Add and modify Field definitions in the BuildSampleForm server action.

Library Modifications

As mentioned above, you may need to adjust the library to fit your needs, such as adding custom client-side validations or additional form elements. Take a look at the RuntimeForms library, especially the following:

RuntimeForm widget

• ValidateForm client action - Validates all non-disabled field elements. If you want to customize or extend browser-based validation, this is where you can do it.

• PopulateFormData client action - Fills the individual field elements with the provided data.

• SubmitOnClick - Triggers the OnSubmit event with the form data as the payload.

RuntimeFormField

• ApplyFieldConfiguration client action - This action applies type-specific field attributes to the elements (e.g., required, minLength, etc.).

Summary

This article introduces the Runtime Forms library, available on ODC Forge, which enables dynamic form creation in OutSystems Developer Cloud applications. Unlike static forms, Runtime Forms allow developers or even end-users to define and render forms on-the-fly using a declarative approach. The component supports various input types and validations.

I hope you enjoyed it and would appreciate your feedback.

During synchronization, we gave permission to the ingested data records to the "everyone" group, allowing all organization users to search and view the data. In a real application, you will likely need to restrict who can search and view the ingested data. In this tutorial, we will explore how to manage access control lists for ingested data records to ensure that only authorized users have access.

Demo Application

This article series includes a demo application called "ODC with Graph Demo," available on ODC Forge. Be sure to download the version of the application that matches this article.

For this article, you need to install Version 0.2 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Graph Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.2.

Version 0.2 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily. In this tutorial however we use an action to retrieve the discovery document from Microsoft Entra only.

• Graph External Data Connections API - A connector library that integrates with Microsoft Graph API for external data connections.

• Graph Users API - A connector library that integrates with Microsoft Graph API users endpoint to retrieve user details.

What we build

In this part of the tutorial series, we will add specific access control list entries to ingested testimonials, allowing access only to designated users. This involves the following steps:

• Mapping User Accounts - Map OutSystems application users to Microsoft Entra users.

• Access Control List - Add access control list entries during data ingestion to Microsoft Graph.

Prerequisites

Before we begin, please reset the existing external data connection configurations in your Microsoft 365 tenant by following the cleanup steps and recreating the external data connection schema as described in part one of the series.

Entra Application Permissions

Our application registration we are using to ingest data requires one additional permission to retrieve Entra user details. In the Entra admin center, go to Applications - App Registrations and select the “Graph External Data Connection ODC” registration.

In the API permissions menu, click Add permission.

• Select Microsoft Graph and Application permission.

• Search for and select User.ReadBasic.All permission.

• Click Add permission.

This permission requires an administrator to grant admin consent.

• Click Grant admin consent <your domain> and confirm the dialog.

Before we try the demo application, let's explore Access Control List entries for external data in Microsoft Graph a bit more in depth.

Access Control List Entries

Access Control List entries in Microsoft Graph for external data specify who can access certain ingested data records and the level of access they have.

Entries are defined by a type attribute that identifies the identity you want to grant permissions to. The type can have one of the following values:

• user - Indicates that you want to grant permission to an individual Entra user account.

• group - Indicates that you want to grant permission to an individual Entra group.

• externalGroup - A non-Entra group that your application manages. We will discuss external groups shortly.

• everyone - A special type that indicates public access.

• application - Grants permission to a specific Entra application registration.

Next, a value must be provided that corresponds to the type you specified:

• user - The Entra user's object identifier.

• group - The Entra group's object identifier.

• externalGroup - The external group identifier.

• everyone - Must be set to “everyone”.

• application - The Application (client) ID of the Entra application registration.

Finally, the accessType attribute defines the level of permission:

• grant - Grants access to the record.

• deny - Denies access to the record. Deny Access Control List entries take precedence over grant entries.

A sample JSON representation of a single Access Control List entry that grants a specific Entra user access to a record looks like this.

{
  "accessType": "grant",
  "type": "user",
  "value": "381a61cf-7d4e-40a3-a225-83c5bc36fbf0"
}

A Graph ingested data record can have multiple Access Control List entries with different types.

Mapping User Accounts

Microsoft 365 users are authenticated through Microsoft Entra, and Entra does not automatically recognize OutSystems user accounts. Therefore, to manage authorizations, we need to identify which Entra user account matches an OutSystems user.

Even if OutSystems users log in through Entra, we, as of today, cannot directly access the login identification data within our application. The only information we have is the user data from the User entity. This means we have to use the user's email address to identify the corresponding Entra user.

There are two ways to do this. If the email address of an OutSystems user matches the Universal Principal Name (UPN) of the Entra user, we can easily get the Entra user details using the Graph_GetUser action from the Graph Users API connector library.

If the OutSystems user's email address does not match Entra's UPN, you can use the Graph_ListUsers action from the Graph Users API connector library. This allows you to filter for the user whose mail attribute matches the OutSystems user's email address. The filter would look like this

mail eq 'mail@domain.com'

Read more on OData filters in the Microsoft Documentation.

External Groups

External Groups represent group entities from systems outside of Microsoft Entra. These groups are used to reflect the access control structures of external data sources.

When developing an OutSystems application with record-level permissions (Entity records), it's better to manage permissions at the group or role level instead of individual user accounts. This makes permission management easier over time.

External Groups for Microsoft Graph External Data let you sync your application's group or role structures and use them in Access Control List entries for item permissions.

An external group is identified by a unique identifier that you need to specify when creating an external group in Microsoft Graph. This identifier can be any alphanumeric string without special characters. The external identifier is then used in all future member management operations.

The Graph External Data Connections API connector library offers the actions you need to create, update, and delete external groups, as well as add and remove group members.

Creating an External Group

With the Graph_CreateExternalGroup action you can create a new external group in Microsoft Graph by providing the following information.

• ExternalGroupId - The unique identifier of the external group. Can be any alphanumeric string without special characters.

• DisplayName - Optional display name

• Description - Optional description

Adding and Removing External Group Members

The actions Graph_CreateIdentity and Graph_DeleteIdentity let you add and likewise remove members from an external group. Members can be one of the following types

• user - A Microsoft Entra user account identified by its object identifier.

• group - A Microsoft Entra group identified by its object identifier.

• externalGroup - Another, already existing, external group that you want to nest.

Adding an External Group Item Access Control List Entry

Using an external group in an ACL is straight forward. The JSON representation of an external group ACL would look like this.

{
  "accessType": "grant",
  "type": "externalGroup",
  "value": "externalGroupIdentifier"
}

Now that we have covered the basics, let's explore the implementation of the demo application.

Demo Application Walkthrough

In this walkthrough, we will explore the key implementation details. Be sure to check the comments in the various server actions as well.

The demo application assigns Access Control List entries based only on user accounts, without using external groups. As a small challenge, try implementing a group permission structure in the demo application on your own.

In ODC Studio, open the ODC with Graph Demo application.

Saving a Testimonial

In the Logic tab, open the SaveTestimonial action under Server Actions - Actions. This action runs when a user creates or updates a testimonial on the Testimonial screen.

This action first performs a check if it is a new testimonial or an existing one and depending on the outcome executed either the Testimonial_Create or Testimonial_Update CRUD wrappers.

The AddPermission server action is executed when creating a new and is responsible for creating the initial record permission for the creator of the testimonial.

• GetUserDetails - Reads the current user's email from the User entity.

• GetEntraAccessToken - Retrieves an access token using the application credentials to access Microsoft Graph.

• Graph_GetUser - Queries Microsoft Graph using the user's email address to obtain Entra user details with the Universal Principal Name.

• TestimonialMember_Create - A CRUD wrapper to create a record in the TestimonialMember entity with the OutSystems User Identifier and the Entra user's object identifier.

Back in the SaveTestimonial action, whether creating or updating a testimonial, the IngestContent finally syncs the testimonial with Microsoft Graph.

Most of the action flow was already explained in part 1. The new addition is the GetTestimonialAccessList action, which retrieves the current permissions from the TestimonialMember entity and returns a list of ItemAccessControlList and assigned to the Graph_CreateOrUpdateItem request structure.

Modifying Permissions

You can modify testimonial permissions in the demo application for existing testimonials. In the Permissions tab of a testimonal you can add or remove OutSystems users.

Adding a new member with permissions to a testimonial triggers the AddTestimonialMember action under Server Actions - Actions. Removing a member triggers the RemoveTestimonialMember action.

Both actions first execute the AddPermission or DeletePermission actions, followed by the IngestContent action to update the record with the new ACL entries in Microsoft Graph.

This wraps up the demo application walkthrough. Try using the demo application with different user accounts to see the search results in Microsoft 365. As an extra challenge, try adding external group management to the application.

Notes and Recommendations

The demo application performs all actions synchronously, triggered from the frontend. In a real use case, you should offload data ingestion to Microsoft Graph to a workflow.

In addition, I recommend implementing a queue that stores an entry for each data item (testimonial) to create, update, and delete, and removes the entry from the queue once the data ingestion operation succeeds. This way, you minimize the risk of application data and graph data becoming inconsistent.

Summary

In this tutorial, we explored how to define Access Control List entries for ingested data items to limit access for specific user accounts. We also discussed how the Graph External Data Connections API and Graph Users API connector libraries can be used to manage external groups and their memberships.

I hope you enjoyed it and would appreciate your feedback.

However, the Graph API also lets us add our application data to the Graph, making it directly accessible to Microsoft 365 applications and services.

• Context IQ in Outlook Web - Allows users to find in-content suggestions from ingested application data while composing an email.

• Microsoft 365 apps - Allows application data to be discoverable from microsoft365.com under Quick Access and My Content.

• Microsoft 365 Copilot - Allows users to easily find, summarize, and learn important details about all content relevant to a user's natural language prompts, including ingested application data.

• Microsoft Search - Allows data to be searchable for users in Microsoft Search, including Office.com, Bing at Work, and SharePoint.

Each of the above integrations has specific requirements on how external data must be injected into the Graph to become available. A full description of the individual requirements is available here.

In this tutorial, we will learn how to add application data to Microsoft Graph for use with Microsoft Search. In future tutorials, we will cover the other integrations as well.

Demo Application

This article series includes a demo application called "ODC with Graph Demo," available on ODC Forge. Be sure to download the version of the application that matches this article.

For this article, you need to install Version 0.1 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Graph Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.1.

Version 0.1 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily. In this tutorial however we use an action to retrieve the discovery document from Microsoft Entra only.

• Graph External Data Connections API - A connector library that integrates with Microsoft Graph API for external data connections.

What we build

The demo application lets users create and manage simple customer testimonials. These testimonials will be available in Microsoft Search, enabling users to search and filter them.

The screenshot above shows a sample search result for a testimonial. Notice the selected Testimonials tab, known as a vertical, which makes it easy to filter search results to show only testimonials. The URL redirects the user to the demo application to view the full details of the testimonial.

To achieve this, we need to follow several steps:

• Register a connection and data schema - The connection serves as a container within the Graph API, storing content items (data). The schema defines the property names and data types of these content items.

• Customize M365 Search & Intelligence - We need to specify how search results for our content items are displayed in M365 search and set up a vertical for easy filtering of search results.

• Sync application data - Whenever a user adds, modifies, or deletes a testimonial in the demo application, we need to create, update, or delete the content item in Microsoft Graph.

Let's start with the prerequisites.

Prerequisites

Interacting with Microsoft Graph requires credentials from your Microsoft Entra tenant, with permissions to manage a data connection and content items.

Register Entra Application

In the Entra admin center, go to Applications - App Registrations and click on New registration.

• Name - Graph External Data Connection ODC

• Supported account types - Accounts in this organizational directory only

• Click Register

From the Overview page, copy the values for:

• Application (client) ID

• Directory (tenant) ID

Next, select the Certificates & secrets menu. In the Client secrets tab, click on New client secret.

• Description - Demo Application

• Expires - 90 days (3 months)

• Click Add

Copy the Value, which is the Client Secret. It will only be shown once.

Finally, we need to assign the permission to create and manage a Graph data connection.

In the API permissions menu, click Add permission.

• Select Microsoft Graph and Application permission.

• Search for and select ExternalConnection.ReadWrite.OwnedBy permission.

• Search for and select ExternalItem.ReadWrite.OwnedBy permission.

• Click Add permission.

• Remove the default User.Read permission.

This permission requires an administrator to grant admin consent.

• Click Grant admin consent <your domain> and confirm the dialog.

With your TenantId, ClientId, and ClientSecret, you can now set up the demo application's settings.

Demo Application Settings

In ODC Portal - Apps, choose the ODC with Graph Demo application.

In the configuration tab, enter the following values:

• EntraTenantId - Directory (tenant) ID.

• EntraClientID - Application (client) ID.

• EntraClientSecret - Secret value copied after creating a new secret.

Leave the fourth setting, ConnectionId, with its default value. We'll explore this one shortly.

Run the Demo Application

With the settings defined, you can now run the demo application (make sure to grant your user the ODCwithGraphDemo role first).

On the start screen, you will see an alert box notifying you that your Microsoft Graph tenant is not yet configured.

Click the Configure Data Connection button to register a data connection and a data schema. This process can take up to 15 minutes to complete. We will explore the details of connection and schema registration shortly. For now, we just want to be able to add some testimonials to the demo application.

Once the connection and data schema is ready you can add your first testimonal.

When you Save, the testimonial is stored in the Testimonial entity and then added to Microsoft Graph. Similarly, if you update or delete an existing testimonial, it is updated or deleted in Microsoft Graph.

After you create some testimonials, try searching for one of the company names or testimonial texts in Microsoft 365. You will notice that none of your testimonials appear yet. This is because, although we can already add data to Microsoft Graph, we still need to complete some final configuration steps in Microsoft 365 Search & Intelligence and enable our connection.

Microsoft 365 Search & intelligence Configuration

Microsoft 365 Search & Intelligence can be accessed through the Microsoft 365 admin center under Settings.

Here, we configure the vertical—the tab in the search bar that lets you filter testimonials only—how testimonials are displayed in the search results, and finally, we activate our connection.

Add a Vertical

A vertical is a tab on the search results page that shows results from a specific content source, like our injected testimonial data. It helps users to filter their search on a particular category of information, making the results more relevant. Some of the default verticals are

• All - shows results from all sources

• Files - shows documents and files

• People - shows user profiles

• Sites - shows Sharepoint sites

In Search & intelligence settings switch to the Customizations tab and select Verticals from the menu options.

• Click Add

• Name - Testimonials

• Click Next

• In the Select a content source screen select Connectors and then the configured Testimonials data source.

• Click Next

• Skip the Add a query screen by clicking Next

• Skip the Filters screen by clicking Next

• Review the vertical and click Add Vertical

Back in the Verticals list select the checkbox next to Testimonials and click the Enable button in the top menu.

Add a Result type

Result types are a customization feature that controls how search results are displayed based on specific conditions, such as the content source (like our injected testimonial data), but not limited to that. With a result type, you configure an Adaptive Card, a user interface widget that is bound to result data, which defines how a search result is shown to the user in Microsoft Search. It is a powerful way to enhance the user experience for your custom data.

In Search & intelligence settings switch to the Customizations tab and select Result types from the menu options.

• Click Add

• Name - Testimonial

• Click Next

• Content Source - Testimonials (the name of our External Data Connections container)

• Click Next

• Skip the Set rules for the result type screen by clicking Next.

• In the Design your layout screen paste the following Adaptive Card template to the text area.

{
    "type": "AdaptiveCard",
    "version": "1.3",
    "body": [
        {
            "type": "ColumnSet",
            "columns": [
                {
                    "type": "Column",
                    "width": "auto",
                    "items": [
                        {
                            "type": "Image",
                            "url": "https://res.cdn.office.net/midgard/versionless/defaultmrticon.png",
                            "horizontalAlignment": "center",
                            "size": "small"
                        }
                    ],
                    "horizontalAlignment": "center"
                },
                {
                    "type": "Column",
                    "width": "stretch",
                    "items": [
                        {
                            "type": "ColumnSet",
                            "columns": [
                                {
                                    "type": "Column",
                                    "width": "auto",
                                    "items": [
                                        {
                                            "type": "TextBlock",
                                            "text": "[${company}](${url})",
                                            "weight": "bolder",
                                            "size": "medium",
                                            "maxLines": 3,
                                            "color": "accent"
                                        }
                                    ],
                                    "spacing": "none"
                                }
                            ],
                            "spacing": "small"
                        },
                        {
                            "type": "TextBlock",
                            "text": "[${url}](${url})",
                            "spacing": "small",
                            "weight": "bolder",
                            "color": "dark"
                        },
                        {
                            "type": "Container",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "**${lastUpdatedByName}** modified {{DATE(${lastUpdatedOn})}}",
                                    "spacing": "small",
                                    "$when": "${lastUpdatedByName!='' && lastUpdatedOn!=''}"
                                },
                                {
                                    "type": "TextBlock",
                                    "text": "Modified on {{DATE(${lastUpdatedOn})}}",
                                    "spacing": "small",
                                    "$when": "${lastUpdatedByName=='' && lastUpdatedOn!=''}"
                                },
                                {
                                    "type": "TextBlock",
                                    "text": "Modified by __${lastUpdatedByName}__",
                                    "spacing": "small",
                                    "$when": "${lastUpdatedByName!='' && lastUpdatedOn==''}"
                                }
                            ],
                            "spacing": "small"
                        },
                        {
                            "type": "TextBlock",
                            "text": "${ResultSnippet}",
                            "maxLines": 2,
                            "wrap": true,
                            "spacing": "small"
                        }
                    ],
                    "spacing": "medium"
                }
            ]
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "$data": {
        "lastUpdatedOn": "2019-09-25T06:08:39Z,SHORT",
        "ResultSnippet": "Wonderful work. Very helpful.",
        "lastUpdatedByName": "Stefan Weber",
        "url": "https://without.systems",
        "company": "without.systems"
    }
}

Notice the ${property} elements in the Adaptive Card that connect individual properties of the defined data schema of a testimonial to the card. The ${ResultSnippet} is a special system property that links the inserted content value and also provides search highlighting.

• Click Next

• Review the Result type and click Add result type

Activate Connection

The final step is to activate our connection.

In the Search & Intelligence settings, switch to the Data Sources tab.

• Click on Include Connector Results in the Required Actions column of the Testimonials connection and confirm the dialog.

By the end of this step, you should be able to search for testimonials in Microsoft Search.

Lets walk through the demo implementation details.

Demo Application Walkthrough

In this walkthrough, we will explore the key implementation details. Be sure to check the comments in the various server actions as well.

In ODC Studio, open the ODC with Graph Demo application.

Data Connection and Schema Registration

In the Logic tab, open the RegisterGraphDataConnection action under Server Actions - Graph. This action was executed when you clicked the Configure Data Connection button on the demo application's start screen.

• GetEntraAccessToken - Retrieves an access token from Entra via OAuth client-credentials flow.

The demo application requests a new access token every time it interacts with Microsoft Graph. In a production environment, you would set up a token cache to request a new token only when the previous one has expired.

• Graph_CreateExternalConnection - This action is provided by the Graph External Data Connections API connector library and creates a new data connection with

  • id - the short name of the data connection

  • name - the display name of the data connection

  • description - additional description of the data connection.

• Graph_CreateOrUpdateConnectionSchema - This action registers a data schema for the data connection.

A data schema is a set of properties with its data type that represent the content item’s (testimonal) metadata. A single property definition in JSON looks like this.

{
  "name": "company",
  "type": "string",
  "isSearchable": true,
  "isRetrievable": true,
  "isQueryable": true,
  "labels": [
     "title"
  ],
  "aliases": []
}

Besides the property name, the definition specifies if you can search for the value (isSearchable), if the property can be used in KQL queries (isQueryable), or if the property can be used in result types (isRetrievable). Additionally, you can map properties to well-known labels of the Microsoft Search Index, like title in the example above. More information can be found in the documentation.

Ingest Content Item

In the Logic tab, open the IngestContent action under Server Actions - Graph. This action is triggered by the SaveTestimonial action after a testimonial is created or updated. It creates or updates the content item in Graph.

The Graph_CreateOrUpdateItem action at the bottom of the action flow expects a serialized JSON structure as Request parameter. The reason is that the object you have to pass to the Graph endpoint is dynamic based on the schema you defined.

Inspect the Item structure in Data - Structures - Content. The structure consists of the following parts

• Id - the Id is the unique identifier of the content item, the primary key value of our testimonal.

• Properties - Attributes that correspond to the schema we registered for the connection

• AccessControlList - Permissions that specify who can view/read the content item. ACLs are not covered in this tutorial though.

• Content - In our case the content object will hold the value of the testimonal text.

Lets break the server action flow down

• Testimonal_Get - This server action retrieves the full details of the requested testimonial.

• Id - We assign the testimonal identifier to the Id property of the Item structure.

• Properties - Assign the metadata values of the testimonials to the Item Properties objects.

• Content - Assign the text of the testimonial as content object of type text to the Item Content object.

• AccessControlListEntry - Access Control List that define who has access to the content item are not covered in this tutorial, but you must add at least one access control list entry. We take the easy route here and grant permission to everyone.

• SerializeItem - Serialize the Item structure and request parameter for the Graph_CreateOrUpdateItem action.

This concludes the demo application walkthrough. Explore the rest of the demo application and the configuration options in Microsoft 365 Search & intelligence. The final step is to cleanup everything.

Cleanup

Once you have finished exploring data ingestion to Microsoft Graph, you should perform the following cleanup steps in Microsoft 365 Search & Intelligence:

• Remove the Result type

• Remove the Vertical

• Delete the Data Connection

Notes and Recommendations

The demo application performs all actions synchronously, triggered from the frontend. In a real use case, you should offload data ingestion to Microsoft Graph to a workflow.

In addition, I recommend implementing a queue that stores an entry for each data item (testimonial) to create, update, and delete, and removes the entry from the queue once the data ingestion operation succeeds. This way, you minimize the risk of application data and graph data becoming inconsistent.

The Graph External Data Connections API library integrates with the endpoints to create a connection and its schema. However, since this is a one-time operation, you can also use Postman or a curl command instead of doing it in your application.

Be patient when changing Search & Intelligence settings like verticals or result types in the M365 admin center. In some cases, it may take several hours to see and use a new configuration due to caching.

Summary

In this tutorial, we built a simple integration with Microsoft Graph and ingested OutSystems application data into the Search index. Having a central way to search for both Microsoft 365 data and OutSystems application data is a great benefit for users who would otherwise have to switch between applications. Adding application data to Microsoft Search also provides additional benefits that I will explore in later tutorials.

I hope you enjoyed it and would appreciate your feedback.

If you try to copy and paste an auction link—either by copying the link from the browser or using the Copy component icon on a card—into a new Outlook message, you'll notice it doesn't work yet, meaning the URL won't unfurl. To extend our sample to support Microsoft Outlook messages as well, we need to do two additional steps:

• Add the Microsoft 365 channel configuration in our Azure AI Bot resource in the Azure Portal.

• Add a Search Command to our App Manifest.

• (Optionally) Implement the configured Search Command in our OutSystems Developer Cloud application.

Demo Application

This article series includes a demo application called "ODC with Loop Components Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.4 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Loop Components Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.4.

Version 0.4 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily. In this tutorial however we use an action to retrieve the discovery document from Microsoft Entra only.

• LiquidFluid - An external logic library that merges data with templates based on the Shopify Liquid Templating language.

• UriParser - An external logic library that parses a given URI/URL.

What we build

In this part, we extend our implementation to allow pasting auction links into Outlook messages, which are then expanded into Adaptive Card-based Loop components.

The good news is that we don't need to change our implementation. We only need to configure the Azure AI Bot resource in the Azure Portal and make one addition to our App Manifest by adding a Search Command. After that, our card will work just like it does in Teams, including card refreshes and, of course, the ability to place a bid.

Activate Microsoft 365 channel

This task is straightforward. Open the Azure Portal and select your Azure AI Bot Resource (if you followed the tutorial, its name should be BotId-<Application (client) ID>).

At the resource level, select Settings - Channels and under Available Channels, click the Microsoft 365 channel entry.

Click the Apply button to activate this channel.

Modify App Manifest

Activating the Microsoft 365 channel extends the support of our Azure AI Bot resource to Microsoft 365 applications.

However, when you try to paste an auction link into a new message, it still doesn't expand into an Adaptive Card. It took me a while to figure this out because the documentation isn't very clear, but for Microsoft Outlook to support link unfurling, your App Manifest must have at least one command configured.

In an App Manifest, you can configure two types of commands:

• Query - Allows a user to perform searches. Query implementations return search results from which the user can select.

• Action - Allows a user to perform any action, like creating a task in Microsoft To-Do directly from the conversation or message.

For link unfurling into an Adaptive Card, we only need to define one command in the App Manifest. However, we don't need to implement the command (though we will look at a sample implementation later in this tutorial).

Open your manifest.json and replace the empty commands array with the following:

{
  ...,
  "commands": [
    {
      "id": "searchAuction",
      "type": "query",
      "title": "Search Auction",
      "description": "Searches available auctions",
      "initialRun": false,
      "fetchTask": false,
      "context": ["compose", "commandBox"],
      "parameters": [
        {
          "name": "searchTerm",
          "title": "Search Term",
          "description": "Part of the auction title to search for",
          "inputType": "text"
        }
      ]
    }
  ],
  ...
}

This defines a query command called searchAuction that takes one input parameter, searchTerm, and is available in the Microsoft Outlook new message window and the Microsoft Teams command bar (context).

Additionally, increase the app manifest version property.

After making the changes, compress the manifest.json file along with the icons into a zip file. Then, re-upload the custom app to Microsoft Teams as described here.

Try it

Even without implementing the query command, the link unfurling of an auction should now work without any extra setup.

Open Microsoft Outlook and click on New - Mail in the ribbon menu. In the message compose window, click on Apps in the ribbon menu. Check that the app list includes the ODCwithLoop app.

Copy an auction link from the demo application and paste it into the message body. After pressing return, the link should successfully unfurl to our auction card, just like in Microsoft Teams.

With link unfurling working, we can now move on to implementing the query command in our application. This step is optional if link unfurling is the only feature you need. However, since we defined a query command, it's available in both the Outlook and Teams interfaces. It would create a poor user experience if someone tries it and finds that it doesn't return any results.

Search Auction Command

Our defined Search Auction command is available in both Microsoft Teams and Microsoft Outlook.

In Teams, you can find it in the conversation command bar by clicking on the + icon and searching for ODCwithLoop. After clicking on the app, you will see the following screen.

In Outlook, it is available in the compose message window. Click on Apps and select the ODCwithLoop app from the list.

Whenever you start typing our messaging endpoint receives a request of type invoke and a name of composeExtension/query. This request contains a value property that looks like this:

{
  ...,
  "value": {
    "commandId": "searchAuction",
    "parameters": [
      {
        "name": "searchTerm",
        "value": "pot"
      }
    ],
    "queryOptions": {
      "count": 25,
      "skip": 0
    }
  }
  ...
}

• commandId - the value defined for the command id in the app manifest.

• parameters - an array of parameter key/value pairs as defined in the app manifest.

• queryOptions - the default query options count (max items to return) and skip (skip number of records.

The response to a composeExtension/query must be a list of cards supported by the search widget. At the time of writing, the search widgets in both Teams and Outlook support:

• Hero Card - A card that usually has a large image, one or more buttons, and text.

• Thumbnail Card - A card that usually has a thumbnail image, one or more buttons, and text.

Both card types are only for displaying the search result list. The user can click on an entry to add the card to a Teams conversation or an Outlook message. To add the full card, we need to include some extra configuration and logic to retrieve the full card from the messaging endpoint once a user clicks on an entry.

Handling Search

When a user starts typing in the search widget, an activity request is sent to the messaging endpoint. This request is of type invoke and has the name composeExtension/query. It includes the searchTerm in the value object, along with other configurations (see the sample above).

Open ODC Studio and go to Logic - Integrations - REST - MessagingEndpoint, then open the Messages flow.

Inspect the third condition (query) of the Invoke switch.

• DeserializeQueryCommandActivity - Deserializes the request containing the value object that contains the searchTerm parameter.

• FilterSearchTerm - The searchTerm is part of the parameters array and we need to filter the list to get it.

MessagingSearchAuctionAction

This action performs a query on the Auction entity, constructs a payload structure and renders the search result template.

• SearchAuctions - Queries the Auction entity.

• GetDefaultDomain - Retrieves the domain name of the current ODC stage. This is needed to build the full URL to the auction.

• SearchAuctions.List and AppendAuction - Adds the search results to a local payload structure and constructs the auction URL.

• RenderAuctionCardListResponse - Renders the response using the payload data.

RenderAuctionCardListResponse uses the following Liquid template:

{
    "composeExtension": {
        "type": "result",
        "attachmentLayout": "list",
        "attachments": [
            {% for auction in auctions %}
            {
                "contentType": "application/vnd.microsoft.card.thumbnail",
                "content": {
                    "title": "{{auction.title}}",
                    "text": "{{auction.description}}"
                },
                "preview": {
                    "contentType": "application/vnd.microsoft.card.thumbnail",
                    "content": {
                        "title": "{{auction.title}}",
                        "text": "{{auction.description}}",
                        "tap": {
                            "type": "invoke",
                            "value": {
                                "url": "{{auction.webUrl}}"
                            }
                        }
                    }
                }
            }
            {% endfor %}
        ]
    }
}

For each auction in the payload structure, an attachment is created. The attachment includes the same thumbnail card content and preview, both needed for message extension responses, with one difference. The preview card has an extra object called tap. This object specifies what should happen when a user clicks on the card, such as when selecting an entry in the search widget. In our setup, it should invoke the messaging endpoint and send a parameter url, which contains the full URL to the auction.

This will send a request activity to our messaging endpoint with the type invoke and the name composeExtension/selectItem. We need to handle this next to return the full auction card.

Handle Item Selection

Back in the MessagingEndpoint - Messages flow, check the fourth Invoke switch condition. This condition handles the composeExtension/selectItem request.

• DeserializeSelectItemActivity - Deserializes the request into a structure that includes the url parameter of the selected entry.

• CreateFullCardForSelectedItem - Executes the MessagingQueryLinkAction server action, which we also use to respond to a link unfurling request.

With everything set up, you can now try it out. Use the search widget in either the Teams or Outlook app to look up an auction. Click on an entry to add the full card to the conversation or message.

I recommend debugging through the flows to check the different results.

Summary

In this tutorial, we set up our Azure AI Bot resource to work with Microsoft Outlook, in addition to Microsoft Teams, for our Adaptive Card-based Loop Component demo. We then updated our app manifest and added a search command, which is necessary for it to function in Microsoft Outlook. Finally, we implemented the search command, although it is optional if only link unfurling is needed. We learned that we need one logic to handle search requests and another to return a full card when a user clicks on a search result.

For now, this is the final tutorial in the ODC with Loop Components series. There are certainly more topics to explore, but this series should provide a good starting point. I hope you enjoyed working through it. Feedback is always appreciated.

Our implementation should allow the following:

• Users can bid on an item until the auction is closed from the web application.

• The card should show the highest bid.

• Closed auctions display a “Closed” badge next to the title and do not allow further bids.

Demo Application

This article series includes a demo application called "ODC with Loop Components Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.3 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Loop Components Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.3.

Version 0.3 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily. In this tutorial however we use an action to retrieve the discovery document from Microsoft Entra only.

• LiquidFluid - An external logic library that merges data with templates based on the Shopify Liquid Templating language.

• UriParser - An external logic library that parses a given URI/URL.

After updating the demo application in your environment, you can try it out right away because the App Manifest—the configuration file that added the app to Microsoft Teams—has not changed. Note that only new Loop components will refresh, while all previously added cards in a channel will stay the same.

Recap

Let's quickly recap what we covered in the last part of the series. We implemented a refresh pattern that keeps an Adaptive Card-based Loop Component up to date. This means a card triggers a Universal Action, which then returns an updated card.

We achived this by adding a refresh object to the Adaptive Card template

{
    ...,        
    "refresh": {
        "action": {
        "type": "Action.Execute",
        "title": "Refresh",
        "verb": "refreshAuctionCard",
        "data": {
            "url": "{{webUrl}}"
        }
        }
    },
    ....
}

The definition above sends an Activity of type Invoke to the messaging endpoint when executed. We observed that the action can be identified by the verb in our messaging endpoint implementation, and we can pass extra data using a data object.

The messaging endpoint processes the request and returns a complete Adaptive Card, wrapped in a status response template that looks like this:

{
    "statusCode": 200,
    "type": "application/vnd.microsoft.card.adaptive",
    "value": <Adaptive Card Content>
}

The changes we made in the previous step also laid the foundation for handling other actions besides the refresh action.

What we build

We are going to modify our implementation so that when a user pastes a running auction into a Teams channel, it will look like this.

A running auction should have a green "Active" badge next to the title. Below the description, the user should be able to enter an amount and place a bid.

After placing the bid, the card should immediately update to show the highest bid for the auction next to the description.

If an auction is closed from the web application, the card will render or update to look like this:

Closed auctions display a red badge “Closed” next to the title and the highest bid next to the description. Closed auction do not have an input field and “Place Bid” button.

In addition closed auction cards will not update anymore.

Let's now look at the changes needed to make this happen.

Entities

In ODC Studio, switch to Data - Entities - Database.

The Auction entity now has an additional attribute called IsActive, which shows whether an auction is running (true) or completed (false).

The Bid entity keeps track of all user bids for an auction. For this demo, it's quite simple, as we are only storing the amount.

Templates

Go to Data - Resources - Templates.

Download the AuctionCard template locally and inspect it with a text editor.

Declaring Variables

At the top of the template are some Liquid instructions to define additional variables based on data merged from the application.

{% if isActive %}
  {% assign status = "Active" %}
  {% assign statusStyle = "Good" %}
{% else %}
  {% assign status = "Closed" %}
  {% assign statusStyle = "Attention" %}
{% endif %}

{% if bid %}
  {% assign price = bid %}
  {% assign priceColor = "Good" %}
{% else %}
  {% assign priceColor = "Default" %}
{% endif %}

The first If statement sets the status and statusStyle variables based on the isActive boolean value from the application. These variables are used to show the badge next to the title.

The second If statement checks if there is a bid value, which exists only if there has been at least one bid. If there is a bid, it updates the price variable (part of the merged data) with the bid amount.

Conditional Rendering

Throughout the template, you will notice several If conditions that wrap parts of the template. For example, the refresh object should only be displayed if the auction is still running.

{% if isActive %}
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Refresh",
      "verb": "refreshAuctionCard",
      "data": {
        "url": "{{webUrl}}"
      }
    }
  },
{% endif %}

Inspect the entire template to identify which parts are displayed only when an auction is still active.

Form and Action

The most interesting part of the template is where we display the input field and the button for placing a bid.

{
  "type": "Container",
  "items": [
    {
      "type": "Input.Number",
      "placeholder": "Enter your bidding..",
      "id": "bid",
      "isRequired": true,
      "errorMessage": "Please enter an amount"
    }
  ]
}

The above part renders a Container with a single number input field (type of Input.Number).

It's important to note that the id of an input field becomes the attribute name when we submit the form using the Place Bid button.

"actions": [
    {
      "type": "Action.Execute",
      "id": "bidAction",
      "verb": "placeBidding",
      "title": "Place Bid",
      "data": {
        "url": "{{webUrl}}"
      }
    }
]

All card actions must be included in the actions array. Our template has one action of type Action.Execute. You'll notice that this is quite similar to the refresh action, and it is. Like the refresh action, it has a verb—which we use to identify the action taken in our messaging endpoint—and the same data object that passes the full URL to the auction item.

When a user enters an amount into the Input.Number field and clicks the “Place Bid” button, all input field data, along with the data defined at the action level, will be added to the data object sent to the messaging endpoint. In our case, the data object sent to the messaging endpoint will look like this.

"data": {
  "url": "https://<YOUR ODC STAGE>/ODCwithLoopComponentsDemo/AuctionDetail?AuctionId=12f521f9-5137-4489-be8c-9172673b710b",
  "bid": 650.00
}

Take your time to inspect the template and the RenderAuctionCard server action in Logic - Server Actions - Loop.

Deserialize Activity

In Logic - Server Actions - Util inspect DeserializeAdaptiveCardActionActivity and the InvokeAdaptiveCardActionActivity structure in Data - Structures - Messaging.

In addition to the Url data item, this structure includes an extra attribute called Bid, which deserializes the bid value sent to the messaging endpoint.

Messaging Endpoint

In Logic - Integrations - REST - MessagingEndpoint, open the Messages endpoint. In the previous part of the series, the second switch statement "Verb" had only one condition for the refresh action. We now add a second condition for the placeBidding verb defined in the AuctionCard template.

The MessagingAuctionBidAction server action processes the deserialized Activity and returns an updated card.

Bid Action

Switch to Logic - Server Actions - Messaging and review the MessagingAuctionBidAction server action.

You will note that this action is almost identical to the refresh action with the following exceptions

• Auction_AddBidding - Saves the received bid in the Bid entity.

• RenderAuctionCard - Displays the updated Auction card with the user's bid. (see note below)

Try

Paste an auction link from the demo application into a Microsoft Teams conversation. This will first display the auction card.

Next, change the auction price in the demo application.

In Microsoft Teams, click on a different conversation, then return to the conversation where you pasted the link. The card will update to show the new price you entered.

Place a bid and see if the card updates with the new value.

Close a bid in the web application and check if the card updates in the channel.

Summary

In this tutorial, we explored how to add form elements to an Adaptive Card-based Loop Component and submit form data to the messaging endpoint using a card action.

I hope you enjoyed it. Please leave a comment with your feedback or any questions you have.

In this tutorial, we explore how to refresh an Adaptive Card-based Loop component using a Universal Action for Adaptive Cards. Universal Actions are Adaptive Card actions that send an Activity of type “invoke” to the messaging endpoint with additional data and Refresh is a special type of a Universal Action.

Demo Application

This article series includes a demo application called "ODC with Loop Components Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.2 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Loop Components Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.2.

Version 0.2 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily. In this tutorial however we use an action to retrieve the discovery document from Microsoft Entra only.

• LiquidFluid - An external logic library that merges data with templates based on the Shopify Liquid Templating language.

• UriParser - An external logic library that parses a given URI/URL.

After updating the demo application in your environment, you can try it out right away because the App Manifest—the configuration file that added the app to Microsoft Teams—has not changed. Note that only new Loop components will refresh, while all previously added cards in a channel will stay the same.

Recap

In part one of the series, our messaging endpoint only responded to Activities of type "invoke" with the name "composeExtension/queryLink." To create this response, we used a single liquid template (based on the Shopify Liquid templating language) and merged it with auction data.

The response looked like this

{
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "attachments": [
      {
        "preview": <<Preview Adaptive Card>>
        "content": <<Full Adaptive Card>>
      }
    ]
  }
}

“preview” contains a simplified Adaptive Card (a thumbnail card), while “content” holds the full details of the Adaptive Card. Consider this response as a one-time message from your Messaging Endpoint to initially display an Adaptive Card in a channel.

"One-time" means we cannot reuse the same liquid template for future responses, such as refreshing a card (covered in this tutorial) or responding to user interactions (covered in the next tutorial). Future responses must include only the full Adaptive Card, which means just the “content” object from the response shown above.

In summary

• composeExtension/queryLink - Respond with a “composeExtension” object containing an attachment with a preview and full card.

• other - Respond with an Adaptive Card only.

To accomodate this we have to split our single liquid template into multiple templates. Let’s get started.

Templates

Open the ODC with Loop Components Demo application in ODC Studio and go to Data - Resources - Templates.

Note the various liquid templates in the folder, download them locally and inspect them with a text editor.

• AuctionCard - This template represents a full Adaptive Card for an auction.

• AuctionCardPreview - This is the preview version of the auction card.

• AuctionQueryLinkResponse - This template is used to create a composeExtension response for link unfurling requests. It combines the results of the AuctionCard and AuctionCardPreview templates.

• StatusValueResponse - This template is combined with the result of an Auction card and is used for follow-up responses of an auction card, such as when refreshing a card. It includes a "status code," a "type," and a "value”. In our case the value will always be an Adaptive Card.

Render AuctionCard and AuctionCardPreview

Go to Logic - Server Actions - Loop and check both RenderAuctionCard and RenderAuctionCardPreview. They are similar, but they use different templates and have a different input parameter structure.

First, the card payload data is serialized and then merged with the liquid template in Resources. Finally, the rendered template is returned.

Render QueryLinkResponse

Inspect the RenderQueryLinkResponse server action. This action creates the queryLink response by combining the results of RenderAuctionCard and RenderAuctionCardPreview into a liquid template.

• RenderAuctionPreviewCard - Returns the rendered preview card.

• RenderAuctionCard - Returns the full auction card.

• UnfurlPayload - Assigns both the preview and full card to a local structure instance of AuctionQueryLink.

• SerializeUnfurlPayload - Serializes the payload to a string (LiquidFluid only accepts JSON data as a string to merge with a template).

• RenderTemplate - Renders the AuctionQueryLinkResponse template.

Render StatusValueResponse

As mentioned above, subsequent responses for an existing card must only include the Adaptive Card. However, that card must be wrapped in a response structure that also returns a status code and type. The RenderStatusValueResponse server action wraps a rendered auction card in the required response structure.

The process here is straightforward, and you should already be familiar with it. Here is an example of what this action produces.

{
  "statusCode": 200,
  "type": "application/vnd.microsoft.card.adaptive",
  "value": {
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "type": "AdaptiveCard",
    "metadata": {
      "webUrl": "https://<<ODC Stage>>/ODCwithLoopComponentsDemo/AuctionDetail?AuctionId=9f890964-b33d-4817-8fa7-41171c8a0c3c"
    },
    "refresh": {
      "action": {
        "type": "Action.Execute",
        "title": "Refresh",
        "verb": "refreshAuctionCard",
        "data": {
          "url": "https://<<ODC Stage>>/ODCwithLoopComponentsDemo/AuctionDetail?AuctionId=9f890964-b33d-4817-8fa7-41171c8a0c3c"
        }
      }
    },
    "body": [
      {
        "type": "TextBlock",
        "size": "medium",
        "weight": "bolder",
        "text": "Mein bestes Produkt"
      },
      {
        "type": "ColumnSet",
        "columns": [
          {
            "type": "Column",
            "width": "stretch",
            "items": [
              {
                "type": "TextBlock",
                "text": "was ich jemands erste",
                "wrap": true
              }
            ],
            "verticalContentAlignment": "Center",
            "spacing": "Medium"
          },
          {
            "type": "Column",
            "width": "auto",
            "items": [
              {
                "type": "TextBlock",
                "text": "500.0",
                "wrap": true,
                "size": "ExtraLarge",
                "weight": "Bolder"
              }
            ]
          }
        ],
        "spacing": "None"
      }
    ]
  }
}

Refresh Action

Before we dive into how everything comes together at the messaging endpoint, let's quickly explore how a channel (like Microsoft Teams) knows that an Adaptive Card needs to be refreshed and how our messaging endpoint identifies which auction card should be updated.

Open the AuctionCard template in a text editor.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.6",
  "type": "AdaptiveCard",
  "metadata": {
    "webUrl": "{{webUrl}}"
  },
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Refresh",
      "verb": "refreshAuctionCard",
      "data": {
        "url": "{{webUrl}}"
      }
    }
  },
  "body": ....,
}

What's new is a “refresh” object that defines an action.

• type - This is always Action.Execute.

• title - Besides automatic card refreshes, Microsoft Teams and other channel applications show a three-dot menu next to the card to manually execute the action. The title you enter here becomes the menu option name.

• verb - This is any string that helps us identify which action is requested. At the messaging endpoint, we use this verb to recognize the refresh request.

• data - This is additional data sent to the messaging endpoint when the refresh action is requested. Here, we define a single item “url.” The handlebars {{ webUrl }} are replaced with the full URL of the Loop component (auction) when merging the template with data in the RenderAuctionCard server action.

Messaging Endpoint

In Logic - Integrations - REST - MassgingEndpoint open the Messages endpoint. In the last part the first switch statement had only one condition for the link unfurling (type of “invoke” and name of “composeExtension/queryLink”).

Adaptive Card-based actions, whether it's a refresh or any other defined action in the card, send an activity request of type "invoke" with a name of "adaptiveCard/action". This invocation is now handled in the second condition added to the switch statement.

Right after DeserializeAdaptiveCardActionActivity is called, which deserializes the request into a structure that provides access to two important pieces of information:

• verb - The action verb as defined in the Auction Adaptive Card. We use the verb to identify which action is requested.

• data - Additional data defined in the Auction Adaptive Card and passed to the messaging endpoint. Currently, only the Loop component URL is passed.

The next switch statement currently has a single condition that checks the verb and executes MessagingRefreshAuctionAction.

MessagingRefreshAuctionAction

This action generates the response that our messaging endpoint needs to send back to the channel. It includes an Adaptive Card for the auction, wrapped in a Status response structure.

• Auction_GetByUrl - This auction parses the given URL (sent via the invoke activity) for the auction identifier. Then it queries the Auction entity and returns the auction details.

• RenderAuctionCard - see above. Renders the Adaptive Card for the auction.

• RenderStatusValueResponse - see above. Wraps the auction card in a status response structure.

Try

Paste an auction link from the demo application into a Microsoft Teams conversation. This will first display the auction card.

Next, change the auction price in the demo application.

In Microsoft Teams, click on a different conversation, then return to the conversation where you pasted the link. The card will update to show the new price you entered.

Summary

In this tutorial, we explored how to keep Adaptive Card-based Loop components up to date in Microsoft Teams by adding a refresh action to a card and implementing a messaging endpoint action to return the most recent Adaptive Card for an auction.

The steps we implemented also lay the foundation for the next part of the tutorial, where we will add user interactions to the card.

I hope you enjoyed it. Please leave a comment with your feedback or any questions you have.

In this lab, I want to show that OutSystems Developer Cloud is more than capable of building agentic AI solutions. The initial effort might be higher than with a custom code AI framework, but on the other hand, you save on setting up a deployment pipeline. (….. and python 😎)

Demo Application

This lab includes a component on Forge called “Agentic AI Lab”.

Dependencies:

• AWSBedrockRuntime - External Logic Connector library for Amazon Bedrock.

• LiquidFluid - External Logic Utility library. This library is used to merge text templates with placeholders with data using the Shopify Liquid Templating language.

The Lab uses Amazon Bedrock models. You will need AWS credentials with access to the following models in the us-east-1 region.

• amazon.nova-micro-v1:0

• us.anthropic.claude-3-5-sonnet-20241022-v2:0 (cross region inference)

After installing the Lab into your ODC development environment, set the application settings for the AWS Access Key and AWS Secret Access Key.

Introduction

Let's begin by introducing some important terms and definitions related to agents and agent orchestration.

Model and Prompt

Let’ start with AI models and prompts. Sometimes, I notice misunderstandings about how AI models work, so let's clear a few things up.

• AI models are stateless, meaning they do not store anything. Everything you think the model needs as input must be included in the prompt, which is then sent to the model to produce a result.

• The prompt sent to the model is plain text. The API, such as the Chat Completion API from OpenAI, is an abstraction on top of the model that makes it easier to create a prompt with the necessary model-specific instruction tokens.

The OpenAI Chat Completion API has become a de facto standard in the market. Most major vendors offer an equivalent or similar API to interact with their models.

At a glance, the API allows you to easily build a prompt for the model with:

• System Prompt - A system prompt is a set of predefined instructions and guidelines given to an AI model to shape its responses and behavior. It defines the context, tone, and boundaries within which the AI operates.

• Message Conversation - An array of messages between a user and the model (assistant) that form a conversation history.

• Tools - (not applicable to all models) A tool definition includes a tool name, a description, and a JSON schema. The model examines the entire context to determine if a tool should be used based on the description. If necessary, tool parameters defined in the JSON schema are extracted from the context. Once all required tool parameters are extracted, the model returns a "Tool Use" result with the tool name and its extracted parameters. It is up to your application to execute the actual tool and add the results back to the Message Conversation.

• Configurations - Additional model settings. Here, you can usually specify the maximum number of tokens—words or parts of words—that the model should generate, and also how creative the output should be.

Agents

An AI agent is like a role in a company, with specific tasks and decision-making abilities, and access to tools for completing tasks or gathering information to make informed decisions. Employees in a role also bring their own knowledge and experience, which helps them handle tasks and interact with other employees and roles in the company.

When defining an AI agent, you consider the same questions as when defining a company role and its responsibilities (tasks). However, there is one difference: while company roles often cover a wide range of topics, AI agents are designed to focus on a specific topic and related tasks.

• Purpose - The purpose of the agent and a description of what it can do.

• Goals - A description of the goals and objectives the agent aims to achieve, along with a definition of the concrete results the agent produces.

• Instructions - Guidelines on how the agent should operate and interact with its environment (e.g., a user) to achieve its goals.

• Tools - A definition of the tools it must or can use to produce the results.

• Constraints - Additional safeguards and constraints that must be considered when the agent performs its tasks. (These exist for human roles too, though they might not always be written down).

From a technical perspective an agent would consist of

• Model - An AI model that powers the agent. The Purpose, Goals, Instructions, and Constraints serve as general guidelines for its behavior. The AI model you choose to power an agent can depend on several criteria, such as its ability to infer on a specific topic, the maximum context window, or its proficiency in a particular language.

• Tools - One or more tool definitions. Remember, a model cannot run a tool on its own. It can only decide if a tool should be used and identify the necessary input parameters from the context, leaving the actual tool execution to your application. A provided tool is simply a combination of a description and the required input parameter definitions. Tools supply on-demand data to the context.

• Knowledge - Additional information added to give the agent more context, helping it perform tasks better. This is like the extra knowledge and experience a human agent might have.

Agent Orchestration

Agent Orchestration involves managing and coordinating multiple AI agents to complete complex tasks and goals. An orchestrator is an agent designed to choose the best agents from a group to perform tasks. Different development frameworks for agentic AI solutions use various names for this agent, such as orchestrator, supervisor, or dispatcher. Besides selecting and activating agents, the orchestrator handles the overall context information and ensures that an agent receives the necessary context information when needed.

The main idea of agent orchestration with highly capable agents is that with minimal input data, the entire process can run independently. Agents collaborate to gather information, make decisions, and produce a result, such as placing an order with a vendor. However, fully automated orchestrations are not quite common right now. Instead, orchestrations linked to a chat conversation with a human in the loop are more typical.

1. A user sends a message to a chat, which is added to the orchestration context.

2. The orchestrator reviews the context and, if needed, selects an agent to handle the user's message. The orchestrator also provides the full context or parts of it to the agent.

3. The agent processes the message and produces a result, which could be the final outcome or a request for clarification or more information.

4. The orchestrator adds the agent's output to the overall context and displays it to the user in the chat.

5. Repeat from Step 1.

Why you should care

An orchestrated collection of AI agents with data and tools is excellent for automation and offers many advantages over using a single model and single agent.

• Automation - You can begin with an agentic human-in-the-loop orchestration and gradually move towards more automation by sending one agent's output directly to another agent. As your agents become more advanced, you'll need a human less often to check or manually adjust results.

• Model - You can choose the best model for your agent to perform its tasks from thousands of available foundational and fine-tuned models, including special-purpose models optimized for tasks like data extraction.

• Cost - Whether in your data center or in the cloud, using models incurs costs. By choosing smaller and therefore less expensive models for simpler tasks instead of relying on a single, large, and costly general-purpose model, you can significantly reduce your overall costs.

• Performance - Smaller models are typically faster at inferring than large models, resulting in better performance.

• Hallucination - Using focused agents with an orchestrator lets you carefully manage the context for a model's use, generally keeping the model's context smaller and reducing the risk of model hallucinations.

• Tool Overlap - Instead of defining many tools in a single model invocation, you attach tools to individual agents. This approach reduces the chance of the model choosing the wrong tool due to ambiguous tool descriptions.

Lab Outline

In this lab we a are building a human-in-the-loop agentic solution. We are going to implement two agents:

• Product Agent - This agent acts as a product manager in our company. In our implementation this agent is only responsible for creating new products in our company product catalog. Meaning that the agent will create a new product record in an entity of our application.

• LinkedIn Agent - This agent is a social media expert and drafts LinkedIn posts. In our implementation it is just an AI model with some instructions.

And, of course, an Orchestrator that evaluates which agent is best suited to handle a request from a conversation.

Agent and Orchestrator Implementation

Let's walk through the important steps to implement an agent and an orchestrator. Open the Agent AI Lab app in ODC Studio.

Agent

Both agents are defined in a static entity AgentSettings under Data - Entities - Database. Each agent record includes the following properties:

• Name - A short name that also serves as the record ID to identify the agent.

• Model - The Amazon Bedrock model the agent will use. Note that the Product Agent uses Amazon Nova Micro, a very small yet fast model, while the LinkedIn Agent uses the Anthropic Sonnets Claude model.

• Role - The agent's role title.

• Description - A description of the agent's capabilities.

• Goal - The outcome the agent aims to achieve.

• Instruction - Additional instructions for the agent.

Open the server action Agent_ProductManager in Logic - Server Actions - Agents. Unlike the LinkedIn agent, the Product Manager agent has an attached tool. Let's go through this one to explore the implementation details.

In general, the action flow of an agent consists of the following steps:

• Retrieve agent settings from the AgentSettings static entity

• Build the system prompt for the agent

• Add tool specification(s)

• Invoke the model

• Handle tool execution (if requested by the model)

• Return the response

Lets take a close look at RenderAgentSystemPrompt

RenderAgentSystemPrompt Action

This action uses the RenderTemplate action from the LiquidFluid external logic Forge component. The template, AgentPrompt, is located in Data - Resources - Agents. LiquidFluid allows you to merge JSON data with a text template that contains handlebars placeholders based on the Shopify Liquid Templating language.

The template for an agent looks like this:

You are an {{ role }}.  You will engange in an open-ended conversation, providing helpful and accurate information.

**Scope**

Your scope of providing assistance is limited to the following:

{{ description }}.

**Instructions**

{{ instructions }}

**Goal and expected result**
{{ goal }}

**Additional Instructions**

- Provide well-reasoned responses that directly address the users intent
- Provide additional explanations where appropiate
- Ask for clarification if parts of the question are ambigous.
- Ask for additional information if the context does not provide sufficient information
- Do assist in user questions or intents that are outside of the given scope. Decline such requests and respond respectfully.

• TemplateData - Here we assign parameters to a local structure variable that matches the handlebar placenholders in the template.

• SerializeTemplateData - Generates the stringified JSON document that is required for the LiquidFluid external logic.

• RenderTemplate - Merges the data with the agent template from Data - Resources - Agents

• Prompt - Assigned the rendered prompt to the output.

GetProductCreateToolSpec Action

Switch to the GetProductCreateToolSpec server action in Logic - Server Actions - Tools.

A tool specification consists of the following:

• Name - A tool descriptor that identifies a tool.

• Description - A detailed explanation of the tool and when it should be used.

• Schema - A JSON schema with required and optional input parameters.

Our Product Create Tool includes the following:

• Name - create_product

• Description - Creates a new product in the product catalog. This tool requires a user to specify a name, description, and price.

The parameter schema is loaded from Data - Resources - Tools and looks like this:

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Name of the product"
        },
        "description": {
            "type": "string",
            "description": "Short description of the product"
        },
        "price": {
            "type": "number",
            "description": "Price of the product."
        }
    },
    "required": ["name", "description", "price"]
}

The schema defines three required properties name, description and price.

Handle Model response

The most interesting part is handling the model response.

After running the Converse action, the model can respond with either a text message or a tool use request. The IF condition after the model call checks for this.

If it's a regular response, we simply return the text response generated by the model. This might happen if the user didn't provide enough information for the Product Create tool.

If it's a tool request (tool_use), we know it can only be the Product Create tool since we have only one tool attached. If you have multiple tools assigned, you would need to adjust the flow to identify which tool is requested and take the appropriate action.

• FilterCreateProduct - Here, we filter the list of messages from the Converse action for ToolUse.Name = "create_product".

• DeserializeToolInput - The FilterCreateProduct.FilteredList.Current.ToolUse.Input property contains the extracted and serialized tool parameters that we deserialize into a Product_Create structure.

• RunProductCreateTool - This action creates a new record in our Product entity and returns a response text.

Finally, we return the response text from the RunProductCreateTool to the orchestrator.

Take a moment to look at the LinkedIn agent too. You'll notice that this agent is much simpler because it doesn't have an attached tool.

Orchestrator

The Orchestrator is the "heart" of our implementation. It manages and stores the conversation history, decides which agent should handle a user's input, and calls the agent implementation.

Open the Orchestrator server action in Logic - Server Actions - Agents.

The Orchestrator takes the last user input message as a parameter and then performs the following steps:

• Message_Query - Retrieves the message history from the Message entity.

• ListAgents - Retrieves the agent settings from the AgentSettings static entity.

• AgentClassifier - Determines the most suitable agent to respond to the user's input message based on the message history. See details below.

• Run Agent - Executes one of the determined agents.

• SaveMessageTurn - Saves both the user input message and the model response to the Message entity.

Agent Classifier

The AgentClassifier server action in Logic - Server Actions - Agents is responsible for selecting one of our agents based on user input and the message context. You'll notice that its implementation resembles a typical agent implementation, and that's exactly what it is.

There are only two differences between the Agent Classifier and a regular agent: the prompt and the tool specification.

The system prompt for the classifier looks like this.

You are an agent dispatcher, an intelligent assistant who analyzes and evaluates requests and then forwards these requests to the most suitable agent. Your job is to understand a request, identify key entities and intentions and determine which of the available agents is best suited to handle a request.

**Important**: A request can also be a continuation of a previous request. The conversation history together with the short name of the last agent used is provided. If a request looks as if it is a continuation of a previous request, then use the same agent as before.

Analyze the request and determine exactly one of the following available agents.

**Available Agents**
Here is the list of available agents.

<agents>
  {% for agent in agents %}
  <agent>
    <shortName>{{ agent.shortName }}</shortName>
    <description>{{ agent.description }}</decription>
  </agent>
  {% endfor %}
</agents>

**Instructions for Agent classification**

- Agent Shortname: Choose the most appropiate agent shortname based on the nature of the request. For follow-up requests use the the same agent shortname as the previous interaction.
- Confidence: Indicate how confident you are in the classification on a scale from 0.0 (not confident) to 1.0 (very confident)
- If you are unable to select an agent put "none"

Handle variations in user input, including different phrasing, synonyms, and potential spelling errors. For short requests like "yes", "ok", "I want to know more", or numerical answers, treat them as follow-ups and maintain previous agent selection.

**Conversation History**
Here is the conversation history that you need to take into account before answering. The last message of a user has the highest relevance when determining an agent.

A message entry consists of a role and the message. The role can be “user” or “assistant”. “user” messages are requests from a user and ‘assistant’ messages are responses from an agent. Assistant messages have the agent shortname in brackets before the message.

<history>
  {% for message in history %}
  <message>
    <role>{{ message.role }}</role>
    <message>{{ message.text }}</message>
  </message>
  {% endfor %}
</history>

**Additional Instructions**

Skip any preamble and provide only the response in the specified format.

In short, this prompt provides the model with information about the available agents and the message history it should consider.

The real highlight is the attached tool specification, which looks like this:

• Name - analyze_prompt

• Description - Inspect a prompt and provide structured output

Schema

{
    "type": "object",
    "properties": {
        "userinput": {
            "type": "string",
            "description": "The original user input"
        },
        "selected_agent": {
            "type": "string",
            "description": "The short name of the selected agent"
        },
        "confidence": {
            "type": "number",
            "description": "The confidence level between 0.0 and 1.0"
        }
    },
    "required": ["userinput", "selected_agent", "confidence"]
}

Unlike the Product Create tool of the Product agent, this tool is always executed because the model can always derive the parameters from the given prompt. This allows us to deserialize the result every time into a ClassifierResult structure and use the SelectedAgent property to execute an agent.

Try and Debug

Now that we've explored the basics of orchestrator and agent implementation, I suggest you take some time to debug the implementation.

If something isn't working as expected, you may need to modify the prompts with additional instructions or constraints.

AI Agent Builder

Before we conclude the lab let us quickly discuss where AI Agent Builder fits in.

AI Agent Builder allows you to build a single agent with access to knowledge, data from entities and tools. It fits nicely into an orchestration like the one we just explored.You would just build the orchestration that handles the message context and the execute service agents from your AI Agent Builder agent implementation the same way as we did with our custom agents above.

Summary

This concludes our lab on Agentic AI with OutSystems Developer Cloud. In this lab, we explored the basics of building agent orchestration. It shows that ODC is a good alternative to existing agentic frameworks, although it currently doesn't offer as many features. However, you don't have to worry about custom coding or deploying a custom code agentic solution. OutSystems Developer Cloud, along with some Forge components, provides everything you need to build. The only limitation is that ODC cannot call agents in parallel, but in a human-in-the-loop scenario, this might not be necessary. ODC is rapidly adding new features, and I hope we will see parallel action calling in the platform soon.

Nevertheless, thoroughly evaluate your use-case scenarios before making a decision. The good thing is that you can always mix and match.

I hope you enjoyed it. Please leave a comment with your feedback.

• App Manifest - The App Manifest is a configuration file that defines our Microsoft 365 app. It specifically configures settings for link unfurling. The App Manifest is packaged with icon resources and then uploaded to Microsoft 365 through the Microsoft Teams app.

• Messaging Endpoint - An exposed REST API in ODC that receives link unfurling requests - via the Azure Bot resource -, processes them, and returns the Adaptive Card-based Loop Component.

Demo Application

This article series includes a demo application called "ODC with Loop Components Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.1 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Loop Components Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.1.

Version 0.1 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily. In this tutorial however we use an action to retrieve the discovery document from Microsoft Entra only.

• LiquidFluid - An external logic library that merges data with templates based on the Shopify Liquid Templating language.

• UriParser - An external logic library that parses a given URI/URL.

In the demo, you can create and edit auction entries with a title, description, and starting auction price. In Version 0.1, this is the only feature available, but we will expand it throughout the tutorial series.

After this tutorial, we want to be able to paste a link from an auction detail screen into a Teams conversation. This link should expand into an Adaptive Card-based Loop component that looks like this:

In later parts of the series, we will enable interaction with this card, allowing users to bid on the item.

Messaging Endpoint

The Building a Loop Component section in the series' introductory article mentiones that we need to create a Messaging Endpoint REST API to handle link unfurling. If you've read my ODC with Bots for Teams series, you might wonder why we aren't reusing what we built there and why this is a separate tutorial series.

In the ODC with Bots for Teams series, we developed a pattern for Conversational Bots that you can interact with in Microsoft Teams or other chat platforms like Alexa and Slack.

Conversational Bots are one feature that can be configured in an App Manifest and then uploaded to your Microsoft 365 environment.

Link unfurling, which transforms a link into an Adaptive Card-based Loop component, is another feature known as a Message Extension.

Conversational Bots and Message Extensions use the same core technology stack. This includes a Bot resource in Azure with an associated Entra application registration and an exposed REST API in ODC, which serves as the Messaging Endpoint handling requests from either a Conversational Bot channel or a Message Extension added to a Microsoft 365 app.

However, there is a fundamental difference in how Bots and Message Extensions send a response to a channel.

• Conversational Bots - Conversational Bots - the Bot handlers to be more precise - send a response to the channel via the Azure Bot Connector API.

• Message Extensions - For Message Extensions, the response is directly returned from the Messaging Endpoint REST API.

Conversational Bots

In ODC, we can use one Messaging Endpoint to manage requests from multiple Azure Bot resources and configured channels. The ODC with Bots for Teams series shows how to create this type of multi-bot handler using ODC events. The diagram below illustrates this pattern.

In this diagram, multiple Azure Bot resources use a single Messaging Endpoint REST API within a central ODC application. The Messaging Endpoint authorizes the Bot, stores the incoming activity in an entity, and then triggers an ODC event with details of the incoming activity.

Several other ODC applications can subscribe to this event, process the activity, and then respond to the channel using the Azure Bot Connector API.

Message Extensions

For Message Extensions, we can't use this decoupled pattern because the Messaging Endpoint must respond directly to the channel. Additionally, a single domain, such as your ODC development stage company-dev.outsystems.app, can only be managed by one - and only one - message extension, and there's no option to include a path. A message extension is defined in the App Manifest. Take a look at the following diagram:

This diagram shows a setup for handling link unfurling and Adaptive Card-based Loop Components.

A single Azure Bot resource with a configured messaging endpoint can manage link unfurling and Adaptive Card actions because the specific domains are listed in the App Manifest. You can create multiple Message Extension App Manifests for one bot resource.

The Messaging Endpoint that receives requests can be set up in a central ODC application with logic to differentiate between the relevant domains based on the domains and even path segments. It then uses service actions from other ODC applications to create or update an Adaptive Card or handle an Adaptive Card action.

While this approach isn't perfect, I used it because I couldn't find a better option.

Prerequisites

Enough with the theory. Let's start by preparing our environment.

Register Entra Application

A bot resource requires an Entra application registration.

In Azure Portal go to App Registrations and click on New registration.

• Name - Microsoft 365 Message Extension with ODC

• Supported account types - Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)

• Click Register

From the Overview page, copy the values of:

• Application (client) ID

We will need that value in the next step.

Create an Azure Bot

With our application registration complete, we can now create an Azure Bot resource. An Azure Bot resource is a middleware that connects Microsoft 365 apps (and others) with the Messaging Endpoint in ODC.

In Azure Marketplace search for Azure Bot and click Create - Azure Bot.

• Bot handle - BotId-<Application ID from Entra App Registration>

• Subscription - Select your subscription model

• Resource group - Choose a resource group where you want to place the bot resource

• Data residency - Global

• Pricing tier - Change plan to Free

• Type of App - Multi Tenant (corresponds to our Entra App Registration)

• Creation type - Use existing app registration

• App ID - Paste the Application ID from the Entra App Registration Overview page

• App tenant ID - Paste the Tenant ID from the Entra App Registration Overview page

• Click Review + Create, review the information the click Create

Wait until the deployment is complete, then click on Go to resource to continue.

Set Bot Profile

In the deployed Azure Bot resource, first go to the Settings - Bot profile menu and give your bot a meaningful display name and description. You can also upload a custom icon here.

Configure Messaging Endpoint

Next switch to the Settings - Configuration menu. The only settings we have to configure here is to provide the FQDN to our Messaging endpoint.

The messaging endpoint FQDN is the combination of your ODC stage base URL and the path you copied earlier from the Messaged endpoint of the demo application.

• Messaging endpoint - https://<ODC stage>.outsystems.app/ODCwithLoopComponentsDemo/rest/MessagingEndpoint/Messages

• Click Apply to save the changes.

Activate Teams Channel

Next, we need to activate Teams channel support in our Bot resource.

• Choose Microsoft Teams from the list of Available Channels in the Settings - Channels menu.

• Read the Terms of Service and Agree.

• In the Messaging tab, select Microsoft Teams Commercial (most common).

• Click Apply.

Summary

In the Prerequisites step, we created an Azure Bot resource with an associated Entra application registration. In the Bot configuration, we specified our Messaging Endpoint hosted in the ODC with Loop Components Demo application. Finally, we activated the Microsoft Teams channel.

As mentioned above, an Azure Bot resource in your Azure tenant acts as middleware. This middleware exchanges messages, called Activities, between configured channels and the messaging endpoint. It does not matter if you are building Conversational Bots or Message Extensions. These capabilities, or what your implementation actually does, are specified in the App Manifest.

Microsoft 365 App

The App Manifest document describes and configures the capabilities that this specific app—your implementation—can perform. In the ODC with Bots for Teams series, we covered the Conversational Bot capability, and in this tutorial, we configure a Message Extension capability for Link unfurling.

The App Manifest, along with additional resources like icons, needs to be uploaded to your Microsoft 365 tenant through either Microsoft Teams or the Microsoft Office Admin Portal. We will use Microsoft Teams and will "install" the app for a single user, a process known as sideloading.

Create App Manifest

The demo project includes a template for the manifest file, complete with icons. Download the template archive from Data - Resources in ODC Studio and extract it to a folder.

An app manifest file is a JSON document that follows the unified app manifest schema. Together with the manifest file you will also need two icons.

• Full color icon with a size of 192×192

• Outline icon with a size of 32×32

Open the manifest.json document from the extracted template in an editor of your choice.

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
    "version": "3.0.0",
    "manifestVersion": "1.19",
    "id": "<Entra Application (client) ID>",
    "name": {
      "short": "ODCwithLoop",
      "full": "ODCwithLoop Demo"
    },
    "developer": {
      "name": "without.systems",
      "websiteUrl": "https://without.systems",
      "privacyUrl": "https://without.systems/privacy",
      "termsOfUseUrl": "https://without.systems/termsofuse"
    },
    "description": {
      "short": "Shows how to build a Loop Component Adaptive Card",
      "full": "Create interaktive elements with Adaptive Cards and share it across Microsoft 365 apps."
    },
    "icons": {
      "outline": "outline.png",
      "color": "color.png"
    },
    "accentColor": "#FFFFFF",
    "showLoadingIndicator": true,
    "bots": [
        {
          "botId": "<Entra Application (client) ID>",
          "scopes": ["personal", "team", "groupChat"],
          "supportsFiles": false,
          "isNotificationOnly": false
        }
    ],
    "composeExtensions": [
      {
        "botId": "<Entra Application (client) ID>",
        "composeExtensionType": "botBased",
        "commands": [],
        "messageHandlers": [
          {
            "type": "link",
            "value": {
              "domains": [
                "<your ODC development stage domain e.g. company-dev.outsystems.app>"
              ],
              "supportsAnonymizedPayloads": false
            }
          }
        ]
      }
    ],
    "permissions": [
      "identity",
      "messageTeamMembers"
    ],
    "validDomains": [
      "<your ODC development stage domain e.g. company-dev.outsystems.app>"
    ]
  }

Modify the following values to match your environment

• id - Application (client) ID from your Entra Application registration

• bots.botId - Application (client) OD from your Entra Application registration

• composeExtensions.botId - Application (client) ID from your Entra Application registration

• composeExtensions.messageHandlers.value.domains - Add your ODC development stage domain name.

• validDomains - Add your ODC development stage domain name.

Save the document, then compress the manifest.json file and the two icon resources into a ZIP archive.

Allow Sideloading

By default users are not allowed to sideload custom apps into Microsoft Teams. This is defined in a Teams Setup Policy that is associated with your user account in the Microsoft Teams Admin center.

In the Microsoft Teams Admin center.

• Select Teams apps - Setup policies in the menu

• Click Add

• Name: OutSystems Bot Developer Setup Policy

• Description: Allows an OutSystems Bot developer to sideload Microsoft Teams apps

• Click Save

After we have created the policy, we must assign it to one or more users

• Select Users - Manage users in the menu

• Search your own user account and select it

• In the Policies tab click Edit

• Select the OutSystems Bot Developer Setup Policy in the Select App setup policy dropdown

• Click Apply

• 

Install App to Microsoft Teams

With our package prepared we can now install it to Microsoft Teams. Open your Microsoft Teams client and in the left icon menu click the Apps icon.

• On the bottom left click on Manage your apps

• In the apps list click the Upload an app button and select Upload a custom app

• Select the zip archive you created

• Check the details of the app, then click Add

With our app uploaded to Microsoft Teams, we can now proceed to try out the demo application.

Demo Application - First Try

Open the Demo application in your browser and create a new Auction. After saving, click on the entry of the created Auction again, which will take you back to the detail screen. Copy the full URL from the browser.

Open Microsoft Teams and start a chat conversation with another test account - or a collague you want to bother with your tests 😒.

Paste the URL into the message box, and after a short while, a Loop component should appear next to the pasted URL in the message box.

If it didn't work, check the following:

• Review your app manifest to ensure you added the correct domain for link unfurling.

• Add a breakpoint at the top of the Messages endpoint in the demo application, start the debugger, and check if a request is sent to your REST API.

• Verify the messaging endpoint URL in the Bot resource in Azure to ensure it matches the correct full endpoint URL.

• Check the botId value to ensure it matches your Entra Application (client) Id.

Before we dive into the implementation details, let's cover one more important part: Adaptive Cards.

Adaptive Cards

When you copy an auction link into a Teams message, it expands into a Loop component based on an Adaptive Card. These are basically JSON-based UI snippets that the host application displays. Host applications are mainly Microsoft 365 apps, but there is also a JavaScript-based SDK to display Adaptive Cards in any web application.

The template for the Adaptive Card JSON document for our Auction looks like this:

{
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.4",
    "type": "AdaptiveCard",
    "metadata": {
        "webUrl": "{{webUrl}}"
    },
    "body": [
        {
            "type": "TextBlock",
            "size": "medium",
            "weight": "bolder",
            "text": "{{title}}"
        },
        {
            "type": "ColumnSet",
            "columns": [
                {
                    "type": "Column",
                    "width": "stretch",
                    "items": [
                        {
                            "type": "TextBlock",
                            "text": "{{description}}",
                            "wrap": true
                        }
                    ],
                    "verticalContentAlignment": "Center",
                    "spacing": "Medium"
                },
                {
                    "type": "Column",
                    "width": "auto",
                    "items": [
                        {
                            "type": "TextBlock",
                            "text": "{{price}}",
                            "wrap": true,
                            "size": "ExtraLarge",
                            "weight": "Bolder"
                        }
                    ]
                }
            ],
            "spacing": "None"
        }
    ]
}

This card defines one Text Block containing the title of the auction followed by a table with two columns containing the description and the price.

Note the handlebar placeholders like {{title}} that will be replaced with values in our implementation as we will see in a bit.

The full reference documentation for Adaptive Cards along with samples can be found at Welcome - Adaptive Cards.

You can create Adaptive Cards either using a text editor or visually using the Adapative Card Designer.

Adaptive Cards in a Message Extension

To expand a link into an Adaptive Card, the Messaging Endpoint must return it in a specific format that looks like this:

{
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "attachments": [
      {
        "preview": {
          "content": {
            "title": "{{ title }}",
            "text": "{{ description }}"
          },
          "contentType": "application/vnd.microsoft.card.thumbnail"
        },
        "content": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "version": "1.4",
          "type": "AdaptiveCard",
          "metadata": {
            "webUrl": "{{webUrl}}"
          },
          "body": [
            {
              "type": "TextBlock",
              "size": "medium",
              "weight": "bolder",
              "text": "{{title}}"
            },
            {
              "type": "ColumnSet",
              "columns": [
                {
                  "type": "Column",
                  "width": "stretch",
                  "items": [
                    {
                      "type": "TextBlock",
                      "text": "{{description}}",
                      "wrap": true
                    }
                  ],
                  "verticalContentAlignment": "Center",
                  "spacing": "Medium"
                },
                {
                  "type": "Column",
                  "width": "auto",
                  "items": [
                    {
                      "type": "TextBlock",
                      "text": "{{price}}",
                      "wrap": true,
                      "size": "ExtraLarge",
                      "weight": "Bolder"
                    }
                  ]
                }
              ],
              "spacing": "None"
            }
          ]
        }
      }
    ]
  }
}

The Messaging Endpoint returns a result of composeExtension for a Link unfurling request, which includes an Attachment. This attachment has two important properties: preview and content. Both are needed for Link unfurling to work. The preview should contain a simplified version of the Adaptive Card, while the content should have the full version. In the example above, the preview only includes the auction title.

Implementation Walkthrough

Now, let's look at the different implementation details that will turn an auction link into a Loop component. The steps in this first tutorial are straightforward:

• Handle the queryLink request - Whenever a user pastes a link that matches the domain in the app manifest into a Teams message, the Teams channel sends a queryLink request to the configured Azure Bot resource, which then forwards the request to the Messaging endpoint.

• Unfurl - In our Messaging endpoint handler, we will process the request, look up the auction in the database, and finally return a response containing the Adaptive Card.

Open the ODC with Loop Components Demo application in ODC Studio.

Handle Request

Go to Logic - Integrations - REST - MessagingEndpoint and double click on the exposed Messages endpoint that handles inbound requests from the Azure Bot resource.

In a first step we have to determine the specific type of the activity sent to our Messaging Endpoint, because for now we only want to react on Link unfurling requests.

The DeserializeInboundMinimalActivity action deserializes the request's payload and gives us the following information:

• type - The type of activity, which is always invoke for Link unfurling.

• name - The name of the specific invocation, which is composeExtension/queryLink for a Link unfurling request.

The following switch statement currently has only one conditional path that is executed when type is invoke and name is composeExtension/queryLink. In all other cases we just end the action flow.

DeserializeInboundQueryLinkActivity converts the request into a structure that includes extra details such as the user who sent the request, the channel used, and more. The most important detail is the URL that was pasted, which is found in the Value attribute of the InvokeQueryLinkActivity structure.

The URL is then finally used to prepare a response in the UnfurlAuctionLink action.

Unfurl

The UnfurlAuctionLink performs several actions to create a response that can be sent back to the channel (Microsoft Teams).

• Parse - This external logic action extracts the URL from the Link unfurling request.

• ParseQueryString - Splits the query string from the URL into a list of name-value pairs.

• HasAuctionDetailPath - Checks if the URL is from an AuctionDetail screen by examining the segments of the parsed URL. If not, we simply exit.

• FilterAuctionId - Filters the query string name-value pairs for the AuctionId parameter.

• RenderAuctionLoop - Uses the URL and the identified AuctionId value to create the response (see below).

Render Auction Response

RenderAuctionLoop retrieves the Auction entity to obtain the record for the requested auction. It then uses this information to create a complete response for the Messaging Endpoint to send back to the channel.

Auction_Get - This action retrieves the record for the given AuctionId from the Auction entity.

The following actions are for merging a response template with data from the auction. The template (available under Data - Resources - AuctionUnfurl.json) contains handlebar placeholders that will be replaced by values using RenderTemplate from the LiquidFluid external logic library.

The template contains the following placeholders

• title - Title of the auction

• description - Full item description

• price - The auction start price

• webUrl - The full url referencing the auction in the demo application

This data structure is represented by a structure AuctionCard in Data - Structures - Auction.

First, we construct the Card payload by assigning values from Auction_Get to the structure properties. Next, we serialize the AuctionCard structure, and finally, we use the RenderTemplate action to merge the serialized data structure with the template.

The Messaging Endpoint then returns this rendered response to the channel, and the Adaptive Card-based Loop Component is displayed.

Missing Pieces

Try changing the auction you pasted earlier in the demo application. You will notice that the card does not update. Being "live" is a core feature of a Loop component, so we need to ensure that cards update when the data changes. We will address this in the next part of the tutorial series.

Another missing piece is that you can copy a Loop component between Microsoft Teams conversations, but not, for example, to a Microsoft Outlook message. We will cover this in a later part.

For now, congratulations! You have successfully turned an OutSystems application link into an Adaptive Card-based Loop component.

Summary

In this part of the ODC with Loop Components tutorial series, we set up the prerequisites for a Message Extension in Azure and implemented a Messaging Endpoint that responds to a link unfurling request from a Microsoft Teams channel with an Adaptive Card-based Loop component.

I hope you enjoyed it. Feel free to leave a comment with your questions and feedback.

Loop Components Overview

Loop components are a feature in Microsoft 365 that allow users to create live, actionable content that can be embedded and updated across various Microsoft 365 apps, such as Teams and Outlook. These components enable users to make real-time updates without switching contexts between different apps.

Their key characteristics are

• Live and Actionable - They allow users to interact with the content directly within the app, making updates and changes that are immediately reflected across all instances of the component.

• Cross-App Functionality - These components can be used across multiple Microsoft 365 apps, ensuring a seamless experience whether you're in Teams, Outlook, or another supported app.

• Contextual Updates - Users can make updates without leaving their current workflow, reducing the need for context switching and improving productivity.

Technically, Loop components are identified by a URL that, when pasted into a Microsoft 365 app, is transformed into an interactive element.

There are two types of Loop components you can use in Microsoft 365 apps.

Loop components created with Microsoft Loop

In Microsoft Loop, you can create a page in any of your workspaces and then share this page—a Loop component—in other Microsoft 365 apps. Simply copy the component using the Copy component button and paste it into another Microsoft 365 app.

Alternatively, Loop components using Microsoft Loop can also be created directly from various Microsoft 365 apps.

In Microsoft Teams, you can create and send a Loop component from the conversation action menu.

In Microsoft Outlook's message compose window, you can create a Loop component from the Ribbon menu.

Adaptive Card based Loop Components

The second type of Loop components is Adaptive Card-based Loop Components. While you can use Microsoft Loop components as provided by Microsoft, Adaptive Card-based Loop components are the ones that you can develop with OutSystems Developer Cloud, which is what we cover in this tutorial series.

Throughout this article and all the following tutorials, when I mention Loop components, we are referring to Adaptive Card-based Loop components.

Why you should care

As mentioned earlier, Loop components are live and actionable. "Live" means you can share and embed a single instance of a Loop component in multiple Teams conversations or Outlook messages, and it will always show the current state of the data linked to the adaptive card. In upcoming tutorials, we'll explore how this works technically. This means if that data changes, the Loop components will automatically update, so there's no need to send an updated version of it.

"Actionable" means a user can interact with a Loop component directly within a Teams conversation or Outlook message. This is beneficial because the user doesn't have to leave the current context, significantly reducing media-breaks between applications.

The combination of these features makes Loop components a great productivity booster. For example, consider the following scenario:

In your application, a user enters new product data that needs approval from someone in the Product Management role. You could send an Outlook message with a Loop component to all product management members. A product manager can then approve the new data directly in Outlook by clicking an Approve button in the Loop component. Once approved, all instances will update, and other product managers will immediately see that the data has already been approved by someone else. Additionally, the product manager who approved the data will see that they were the one who did it. There's no need to redirect users to an approval website anymore, and since the Loop component updates automatically, everyone will know whether an approval has already taken place or is still pending.

Building a Loop Component

Loop components are identified by a URL, such as a full URL to a screen with input parameters from your OutSystems application. Your implementation recognizes this URL and replaces it with an interactive element, known as an Adaptive Card. This process is called link unfurling and is a feature of Message Extensions for Microsoft 365. Developing the Message Extension is the most essential part of this series.

Building a Message Extension involves the following steps:

• Register a Bot and associated Entra application registration - In our Azure tenant, we need to create an Azure Bot resource along with an Entra application. The Azure Bot resource acts as the gateway between Microsoft 365 apps and our OutSystems Developer Cloud environment.

• Messaging Endpoint Implementation - This is an exposed REST API that processes requests from Microsoft 365 apps through the Azure Bot resource.

• Microsoft App Manifest - This is a configuration file that, along with other resources, needs to be published within your Microsoft 365 tenant. It contains configuration options like which URLs should be unfurled and more.

User Experience with Loop Components

From a user's perspective, using Loop components might look like this:

• A user copies the full URL from an OutSystems application into a Microsoft Teams conversation or Microsoft Outlook message.

• If the URL matches the configuration in your Microsoft App Manifest file, a link unfurling request is sent to the messaging endpoint of the configured Azure Bot resource.

• Your messaging endpoint processes the link unfurl request, determines the requested data, and responds with a Loop component based on an Adaptive Card.

• The Loop component is then displayed in the Microsoft 365 app.

The Loop component can include interactive elements with input fields and buttons. If the user clicks a button:

• The messaging endpoint is invoked again with a request specifying the card instance and the action.

• The messaging endpoint processes the request and, if needed, returns an updated Adaptive Card based Loop component to the app.

Summary

This concludes the introduction to Adaptive Card-based Loop Components with OutSystems Developer Cloud. Please take a moment to review the provided links, as they contain important additional information.

In the first tutorial, we will set up the prerequisites and unfurl an OutSystems application link for a simple adaptive card in Microsoft Teams - in later articles we will extend this to other Microsoft 365 apps. We will also handle data modifications and Loop component refreshes. This tutorial series includes a full demo application that you can use throughout the tutorials and as a starting point for your own implementation.

I hope you enjoyed the introduction. Feel free to leave a comment with your questions or feedback.

Authenticating a user within a Teams conversation is a significant topic. Besides the token exchange using Microsoft Entra, which is covered in this article, you can also authenticate a user with any OpenID Connect-compatible Identity Provider.

But when should you authenticate a user from within a conversation?

Explicitly asking a user to authenticate is not always necessary. You only need to require authentication when you need an access token to perform actions on behalf of the user (meaning with permissions associated with the user) on resources. Examples include:

• Interacting with the Microsoft Graph API, such as sending an email on behalf of a user. In this case, you need an access token issued by Microsoft Entra and permissions to send emails.

• Interacting with AWS Simple Storage Service. Here, you would authenticate a user with AWS Cognito to get an access token that you can exchange for AWS credentials via AWS STS.

You don't need to require user authentication just to know who the user is. The information sent as part of an Activity in the From and Recipient properties can be sufficient.

For more information on Bot Authentication, visit User authentication in the Azure AI Bot Service - Bot Service | Microsoft Learn.

So, without further delay, let's begin by preparing the prerequisites.

Demo Application

This article series includes a demo application called "ODC with Bots for Teams Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.5 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Bots for Teams Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.5.

Version 0.5 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily.

• Bot Framework Service API - A connector library for using Bot Connector API endpoints.

• LiquidFluid - An external logic library used to render handlebar templates based on the Shopify Liquid Templating syntax.

Microsoft Entra Application Registration

In Entra Application Registration, we will configure permissions, scope, and authorized clients, an additional client secret and a redirect URI.

Our demo bot needs to send an email on behalf of the logged-in user. To send emails, it requires the Mail.Send permission.

Additionally, we need to create a custom scope and add the Microsoft Teams client application as an authorized client. This ensures that only these trusted clients can request tokens from Entra on behalf of the user, which will be used in our bot to send an email.

We create a new client secret to be used by the Bot Framework token service to acquire the user token during authentication. You already have one secret configured to retrieve an access token for interacting with the Connector API. You could use the same secret, but creating a separate one makes the purpose of each client secret clearer.

Finally, we add a redirect URI to our application registration. This is where the authorization code will be sent after a user successfully signs in from Teams. The entire authentication process is managed by the Azure Bot Framework Service, specifically the Token Service, and the redirect URI will direct to that service.

In Azure Portal switch to the Entra application registration that is associated with your configured bot.

Grant Send Mail Permission

Under the Manage menu, select API permissions.

• Click Add a permission.

• In the Request API permissions sidebar, select Microsoft Graph.

• Choose Delegated Permissions (Permissions on behalf of a user).

• Type Mail.Send in the search box and check the box next to Mail.Send (Send mail as a user).

• Click Add permissions.

Repeat this step to add the following additional permissions

• openid

• email

• profile

Finally click on Grant admin consent for <your domain>.

Configure Scope

Under the Manage menu, select Expose an API.

• Click the Add link next to Application ID URI.

• For the value, enter api://<your Microsoft Tenant FQDN>/botid-<copied Application (client) ID>.

• Click Save.

In the Scopes defined by this API section, click on Add a scope.

• Scope name - access_as_user

• Who can consent - Admins and users

• Admin consent display name - Allow Teams to access the user profile and use the bot on behalf of the user

• Admin consent description - Allow Microsoft Teams to access the user profile and call the application's API on behalf of the user

• User consent display name - Allow Teams to access the user profile and use the bot on behalf of the user

• User consent description - Allow Microsoft Teams to access the user profile and call the application's API on behalf of the user

Add Authorized Client Applications

Still in the same menu.

In the Authorized client applications section, click on Add a client application.

Each Microsoft M365 application, such as Teams, Teams for Web, and Outlook, has a unique client ID. We are now allowing the Teams Desktop and Web applications to access our application API (ODC Exposed REST API) on behalf of the logged-in user. You can find a complete list of Microsoft First-Party apps with their identifiers here: Verify first-party Microsoft applications in sign-in reports | Microsoft Learn.

For the Microsoft Teams Desktop and Mobile applications:

• Client ID - 1fec8e78-bce4-4aaf-ab1b-5451cc387264

• Select the checkbox next to the scope you created earlier

• Click Add application

For the Microsoft Teams for Web application:

• Client ID - 5e3ce6c0-2b1f-4285-8d4b-75ee78787346

• Select the checkbox next to the scope you created earlier

• Click Add application

Add Client Secret

Under the Manage menu select Certificates & secrets

Select the Client secrets tab and click on New client secret

• Description - Bot User Authentication

• Expires - Recommended: 180 days (6 months)

• Click Add

Immediately after adding the new client secret, copy the Value and save it for later. It will only be displayed once.

Redirect URI

The final configuration step is to add a Redirect URI to the application registration.

Under the Manage menu select Authentication.

In the Platform configurations section click Add a platform

• Select Web

• Redirect URIs - https://token.botframework.com/.auth/web/redirect

• Click Configure

With our Entra application registration set up, we can now add some configuration details to our Azure Bot resource.

Azure Bot Resource

Under the Settings menu select Configuration

• Click Add OAuth Connection Settings

• Name: Default

• Service Provider: Azure Active Directory v2

• Client id: <Application (client) ID> from Entra application registration

• Client secret: <Client secret you created you in the previous step>

• Token Exchange URL: leave empty

• Tenant ID: common

• Scopes: Mail.Send openid email profile

• Click Save

After saving the connection, click on the newly created connection again. In the top right corner of the sidebar, click on Test connection. Complete the sign-in dialog and in the next dialog, you will receive the issued token. You can copy the value and inspect the token at jwt.io.

App Manifest

The configuration above lets us require users to authenticate through Azure Entra. With Microsoft Teams, we can use a "silent" token exchange feature that swaps a user's Teams access token for an access token issued for the application registration linked to our bot. To enable this "silent" exchange, we need to modify our Teams app manifest and add some extra properties.

{
  ...,
  "permissions": ["messageTeamMembers", "identity"],
  "validDomains": ["token.botframework.com"],
  "webApplicationInfo": {
    "id": "<Application (client) ID>",
    "resource": "api://<domain name>/BotId-<Application (client) ID>"
}

• permissions - identity: This permission allows the bot to access user identity information. It lets the bot get user details, which is important for personalized interactions and implementing SSO.

• validDomains: The domain token.botframework.com is included to let the bot use the Bot Framework OAuth flow for authentication. By specifying this domain, the bot can securely interact with the OAuth token service provided by the Bot Framework, which is necessary for handling user authentication and authorization.

• webApplicationInfo - id: This is the Application (client) ID of the bot registered in Microsoft Entra ID. It uniquely identifies the bot application and is used during the authentication process to request tokens.

• webApplicationInfo - resource: This is the Application ID URI that represents the bot's API. It specifies the intended audience for the authentication tokens.

After you modify the app manifest with the new values, package it, and reupload the Teams app to Microsoft Teams as described here.

With our prerequisites complete, we can now explore the implementation details. Open ODC Studio and the demo application.

Bot Handler

This version of the demo application includes a new handler called BotHandlerSimpleAuthentication, which is set up as the in-app event handler for the OnBotActivity event. In the Logic tab, open Bots - BotHandlerSimpleAuthentication.

Compared to our previous event handler we made the following additions.

TryGetUserToken

This action checks the TokenStore to see if there is already a valid, non-expired access token available for the sender of the message and returns it.

SendOAuthPrompt

Back in the main flow and if there is no non-expired access token available for the user our flow prepares an OAuthCard message and sends it to the user.

An OAuthCard is used to facilitate OAuth authentication. You will find the OAuthCard template under Data - Resources - Cards.

{
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.oauth",
            "content": {
                "connectionName": "{{connectionName}}",
                "tokenExchangeResource": {
                    "id": "{{activity}}"
                }
            }
        }
    ],
    "recipient": {
        "id": "{{recipient}}"
    }
}

RenderOAuthCard replaces the placeholder values with actual data. It uses the LiquidFluid external logic component to create the final card message.

• connectionName - The configured OAuth connection name in the Azure Bot resource (Default).

• activity - The Activity ID of the last activity that triggered the authentication flow. We will discuss why this value is important later. For now, remember that we use this ID to track the last message a user sent in the conversation.

• recipient - The ID of the recipient.

The rendered OAuthCard is then sent to the conversation just like any other message.

Summary

In our bot handler, we first try to get a valid access token for the user from the TokenStore entity. If the user doesn't have an access token, or if the access token has expired, we send an OAuthCard to the user in the Teams conversation to trigger a token exchange.

Messaging Endpoint

As soon as Microsoft Teams receives the OAuthCard message, it sends an Activity of type invoke to the bot's configured messaging endpoint. This Activity contains the user's Microsoft Teams client access token, which we need to exchange for a Bot application token using the Azure Bot Token API.

Open the Messages endpoint in Logic - Integrations - REST - MessagingEndpoint.

In the Messages endpoint we handle this special activity of type invoke and a name of signin/tokenExchange.

DeserializeInboundTokenExchange

This action deserializes the request in to a InvokeTokenExchange structure, a format the Azure Bot Token API expects to exchange a token.

TryExchangeUserToken

This action first gets an access token to interact with the Azure Bot Token API and then calls the ExchangeToken endpoint using our InvokeTokenExchange values. If successful, it saves the access token in the TokenStore entity for future use.

Original Message Playback

Now comes the tricky part. The user's original message hasn't been processed because our bot handler started an OAuth prompt flow, so the original message is essentially lost. Fortunately, all inbound activities are stored in the Activity entity.

When we created the OAuthCard, we added the original message's Activity Id to the card. This Id is sent back to us as part of the invoke - signin/tokenExchange activity.

{
  "name": "signin/tokenExchange",
  "type": "invoke",
  ...
  "value": {
    "id": "<Activity ID>",
    "token": "<Teams client token>",
    "connectionName": "Default"
  },
  ...
}

We now use this Activity ID to get the original message from the Activity entity (GetOriginActivity), deserialize the payload (DeserializeOriginActivity), and trigger an OnBotActivity with the values from the original activity.

This method replays the original message, and since we now have a valid access token, the bot handler will process the inbound message.

Summary

Our Messaging Endpoint manages the token exchange. It gets the Microsoft Teams client access token and swaps it for an access token for our registered Bot application using the Azure Bot Token Service API. Then, it retrieves the original user message from the Activity Store and triggers an OnBotActivity with the original message payload. This step is essential because the original message isn't processed if the user doesn't have a valid access token.

Send Mail via Graph API

Back in our bot handler (BotHandlerSimpleAuthentication) lets review the part when our action flow could successfully retrieve a users access token from the Token Store.

GetProfile

This action queries the Me endpoint of the Microsoft Graph API to retrieve the basic user profile using the user's access token. This step is needed to get the User Principal Name and the email address (in most cases, the UPN will be the same as the primary email address).

For this operation, the User.Read permission on the Bot application registration in Entra is required.

SendGraphEmail

This action sends a basic email using the Graph API. In our example, the email is sent from the user to themselves, but it's just for demonstration purposes.

For this operation, the Mail.Send permission on the Bot application registration in Entra is necessary.

Summary

To send an email, we use the cached user access token to first get the basic user profile, and then we send an email to that user via the Graph API. This shows how a Microsoft Teams client access token can be successfully exchanged for a bot-specific access token with granted permissions in the Entra application registration.

Bonus Excerise

After testing your bot implementation, you'll quickly notice some delay between sending a message and receiving a response from your bot. As an additional exercise, add a typing activity (an activity of type typing) to:

• The messaging endpoint before triggering the OnBotActivity event.

• The bot handler right after the condition that checks if the activity type is a message.

Sending a typing activity in a conversation improves the user experience by providing feedback.

The End of the ODC with Bots for Teams series

This is the final tutorial in my series on ODC with Bots for Microsoft Teams. As you can imagine, there is a lot more to the topic than what we covered in these tutorials, but I hope the series gives you a good start on your journey to turning OutSystems Developer Cloud into a full-fledged, multi-bot environment.

I hope you enjoyed this tutorial and the entire series. For questions and feedback, please leave a comment here.

However, we are still missing two important implementations. First, our messaging endpoint is publicly available without any authorization checks. Essentially, anything could mimic an inbound message, and our bot would react, which is not good.

Second, in some scenarios, we need a user's credentials, not just their ID, to perform actions on behalf of that user in a bot implementation. Currently, through a Teams channel, we get the identifier of a user logged into Teams, but to use Microsoft Graph API operations on behalf of that user, we need the user to explicitly authenticate to retrieve their access token for Graph API operations.

In this tutorial, we will protect our messaging endpoint to ensure that we only handle requests initiated by Azure AI Bot services. In the next tutorial, we will explore how to authenticate a user and retrieve an access token to act on behalf of a user with the Graph API.

Demo Application

This article series includes a demo application called "ODC with Bots for Teams Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.4 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Bots for Teams Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.4.

Version 0.4 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily.

• Bot Framework Service API - A connector library for using Bot Connector API endpoints.

Authenticating Requests to the Messaging Endpoint

Any request from a configured channel is routed through the Azure AI Bot Connector service, which adds a signed JSON Web Token to the Authorization header of each request. The entire authentication and authorization process is well documented here: Authenticate requests with the Bot Connector API - Bot Service | Microsoft Learn. It involves the following steps:

• Retrieve the token from the Authorization header.

• Parse the token header to identify which key was used to sign the token.

• Retrieve the public key for the identified key from the Bot Framework JSON Web Key Set URI.

• Validate the token.

In ODC, we manage all of this with a custom OnAuthentication handler on the exposed Messaging endpoint.

OnAuthentication Handler

In the demo application under Logic - Integrations - REST, note that our MessagingEndpoint REST API authentication setting is now configured with Custom, which includes the OnAuthentication handler. OnAuthentication runs before a request reaches the actual endpoint.

Double-click the OnAuthentication handler to review the implementation.

The OnAuthentication handler performs several actions, starting with retrieving the value of the Authorization request header using Request_GetHeader from the HTTP module. The value is formatted as Bearer <encoded JSON web token>. The JSON web token consists of three parts separated by dots. Each part is a base64 encoded JSON document.

• Header - Contains information about the token and how the signature was calculated.

• Payload - The token's payload with various key-value pairs, also known as claims.

• Signature - The signature of the payload.

ParseAuthorizationHeader Action

This action performs some String_Split operations. First, it splits by a single space to divide the Authorization header value into the word "Bearer" and the encoded JSON web token.

Next, it splits the encoded JSON web token by a single dot to separate the Header, Payload, and Signature parts.

Note the individual IF conditions that raise an exception if the Authorization header is empty or if the split actions do not produce the expected results.

ParseJwtHeader Action

This action converts the encoded Header of the token into a JwtHeader structure and returns it. The Header structure includes the Key Identifier of the public key that we need to use to verify the token's signature.

GetJwksKey Action

This action retrieves the public key from the Bot Framework Identity Provider's JSON Web Key Set endpoint. The Bot Framework Identity Provider issues the signed token, and its URL is https://login.botframework.com.

• First we retrieve the Discovery document from the Identity Provider that contains the URI of the JSON Web Key Set endpoint using GetDiscoveryDocument from the OAuthTokenExchange Forge component.

• Then we perform a GET request to the endpoint that returns the key sets using Request_SubmitGetRequest from the HTTP module and deserialize the response into a structure for easy filtering.

• We filter the list of retrieved keys to the key identifier retrieved from the token header using a ListFilter action.

• And finally we serialize the single key and return it.

ValidateToken Action

In ValidateToken, we use JWT_ReadToken from the Security module to check the signature with the retrieved public key.

If validation succeeds, the request is forwarded to the Messages endpoint for further processing.

Summary

At the end of this tutorial, we protected our messaging endpoint by validating the access token sent from the Azure AI Bot service. The great thing about this tutorial is that you can use this method whenever you need to validate a signed JSON web token.

Feel free to leave a comment with your questions or feedback.

An app manifest file connects your bot to the client application. It is a JSON document that describes your bot, its appearance, and behavior within Teams. App manifest files are used not only in Microsoft Teams but also in many other Microsoft 365 applications, providing a unified way to add external app resources to the Microsoft 365 environment.

Manifest documents and its referenced icon resources are packaged into a ZIP file and then deployed to Microsoft Teams clients either

• By sideloading into a single Teams client - This is what we will do in this tutorial. We will upload the Teams app to our local Microsoft Teams client.

• Distributing it within the organization - You can upload a Teams app to your organization, making it available for on-demand or policy-based installation internally.

• Distributing it via the Microsoft Teams Store - You can release your Teams bot/app to the official Microsoft Teams Store to make your solution publicly available. However, your app must meet the store guidelines.

Now, without further ado, let's begin by setting up the prerequisites.

Demo Application

This article series includes a demo application called "ODC with Bots for Teams Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.3 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Bots for Teams Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.3.

Version 0.3 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily.

• Bot Framework Service API - A connector library for using Bot Connector API endpoints.

Allow Sideloading

By default users are not allowed to upload custom apps into Microsoft Teams. This is defined in a Teams Setup Policy that is associated with your user account in the Microsoft Teams Admin center.

In the Microsoft Teams Admin center.

• Select Teams apps - Setup policies in the menu

• Click Add

• Name: OutSystems Bot Developer Setup Policy

• Description: Allows an OutSystems Bot developer to sideload Microsoft Teams apps

• Click Save

After we have created the policy, we must assign it to one or more users

• Select Users - Manage users in the menu

• Search your own user account and select it

• In the Policies tab click Edit

• Select the OutSystems Bot Developer Setup Policy in the Select App setup policy dropdown

• Click Apply

Activate Teams Channel

Next, we need to activate Teams channel support in our Bot resource.

• In the Azure Portal, select your Bot resource.

• Choose Microsoft Teams from the list of Available Channels in the Settings - Channels menu.

• Read the Terms of Service and Agree.

• In the Messaging tab, select Microsoft Teams Commercial (most common).

• Click Apply.

Create the App Manifest File

The demo project includes a template for the manifest file, complete with icons. Download the template archive from Data - Resources in ODC Studio and extract it to a folder.

An app manifest file is a JSON document that follows the unified app manifest schema. Together with the manifest file you will also need two icons.

• Full color icon with a size of 192×192

• Outline icon with a size of 32×32

Create a folder on your development machine

• Copy both icons to the folder

• Create a new file manifest.json

• Modify id with your bot’s application id from Entra App registration

• Modify botId with your bot’s application id from Entra App registration

• Check that the icon names match your uploaded icons.

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
  "version": "1.0.0",
  "manifestVersion": "1.19",
  "id": "<Application ID from app registration>",
  "name": {
    "short": "ODCwithTeams Bot",
    "full": "ODCwithTeams Demo Bot"
  },
  "developer": {
    "name": "without.systems",
    "websiteUrl": "https://without.systems",
    "privacyUrl": "https://without.systems/privacy",
    "termsOfUseUrl": "https://without.systems/termsofuse"
  },
  "description": {
    "short": "Shows how to build a bot",
    "full": "Full description of your app."
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "<Application ID from app registration>",
      "scopes": [
        "personal"
      ],
      "isNotificationOnly": false,
      "supportsCalling": false,
      "supportsVideo": false,
      "supportsFiles": false
    }
  ]
}

This is a basic app manifest file, which we will expand on in the upcoming articles of the series. You can find a complete description of the schema here: App Manifest Reference - Teams | Microsoft Learn.

After you have prepared your manifest file, select all the files in the folder (the manifest and icons) and compress them into a zip archive. The name of the zip archive doesn't matter.

Install App to Microsoft Teams

With our package prepared we can now install it to Microsoft Teams. Open your Microsoft Teams client and in the left icon menu click the Apps icon.

• On the bottom left click on Manage your apps

• In the apps list click the Upload an app button and select Upload a custom app

• Select the zip archive you created

• Check the details of the app, then click Add

After sucessful upload click the Open button to start a conversation with your bot.

Summary

In this tutorial, we added our Bot to Microsoft Teams. First, we enabled sideloading of Teams apps by creating a new setup policy in the Microsoft Teams Admin Center. Then, we created a manifest application package and uploaded it to a Microsoft Teams client.

Congratulations! This concludes this part of the series. In the next part, we will protect our messaging endpoint, as it is currently publicly available and does not perform any authorization checks.

Feel free to leave a comment with your questions or feedback. See you in the next part!

In this tutorial, we will walk through the steps to set up DeepSeek R1 on Amazon Bedrock as an Imported Model and use it in OutSystems Developer Cloud applications.

Alternatively, DeepSeek R1 is also available for marketplace deployment, which is more suitable for production use. Marketplace deployments are set up on SageMaker, offering more configuration options for scalability and security. However, deploying DeepSeek through the marketplace requires a service quota for p5 compute instances, which must be requested first. (It is actually a feature to prevent accidental high costs). That's why we use the Imported Models feature of Bedrock, which doesn't have this restriction but does come with some limitations. See the Important Notes section of this article. For a development and trial environment, it is good enough.

Amazon Bedrock Imported Models

Bedrock is an easy-to-use, fully managed AI service by AWS. It provides access to a wide range of AI models from Amazon Bedrock's model catalog through a unified API. In addition to these catalog models, Bedrock also allows the import of other models.

Imported models must follow specific predefined architectures to be supported by Bedrock. As of this writing, the supported model architectures include:

• Mistral

• Mixtral

• Llama 2, Llama 3, Llama 3.1, Llama 3.2, and Llama 3.3

• Flan

For a complete list of supported architectures, see Supported Architectures in the Amazon Bedrock documentation.

Fortunately, DeepSeek R1 is available as a distilled Llama model, which lets us import it into Amazon Bedrock. Distillation means that a teacher model (DeepSeek R1) transfers its "knowledge" to a student model (Llama 3.1). DeepSeek R1 and its distilled models are available on Huggingface for download.

For our walkthrough we will use deepseek-ai/DeepSeek-R1-Distill-Llama-8B.

Steps Outline

The steps are straightforward, but they may take some time because of the model's size.

• Upload the model to an S3 bucket

• Create a model import job in the Bedrock console

• Use the model in ODC

Prerequisites

Before we begin, ensure you meet all the necessary prerequisites.

Environment

• AWS Account - You need access to an AWS account with permissions for Amazon Bedrock and Amazon Simple Storage Service.

• Git - On your development workstation, you need the git command line tools and git lfs installed.

• AWS Credentials - Access Key and Secret Access Key for an IAM user with permissions to use custom models in Amazon Bedrock.

• S3 Bucket - An empty S3 bucket in the us-east-1 region (Bedrock only allows model imports from an S3 bucket).

• AWS CLI - Optional. Can be use as an alternative to upload model files to S3 instead of the console.

OutSystems Developer Cloud

To follow along, you will need to install two assets from Forge into your OutSystems Developer Cloud development stage.

• AWSBedrockRuntime - provides an action to execute the Amazon Bedrock InvokeModel API.

• AWS Bedrock Model Invocations - server actions to create a model-specific prompt for model invocation.

With all the prerequisites completed, let's start by uploading the model to an S3 bucket.

Upload Model to S3

Unfortunately, there isn't a direct way to copy a model from Huggingface into an S3 bucket, or at least I haven't found one. First, we download the model from Huggingface to our local computer, and then we upload it to S3.

Run the following command in a terminal window:

git clone --depth 1 https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Llama-8B

This command will clone the Huggingface repository into a folder named DeepSeek-R1-Distill-Llama-8B. Models are quite large, so the download may take some time.

After the download is complete, upload the entire folder to the S3 bucket you created. You can use either the AWS S3 console or the AWS command line interface if it is installed and set up.

aws s3 cp DeepSeek-R1-Distill-Llama-8B s3://<bucket>/ --recursive

Import Model to Amazon Bedrock

Next, switch to the AWS Bedrock console. Make sure to select the us-east-1 region. In the console's menu, select Imported models and click Import Model.

In the dialog:

• Model Details - Model name: DeepSeek-R1-Distill-Llama-8B.

• Import job name - Name: Import-DeepSeek-R1-Distill-Llama-8B.

• Model import settings - Model import source: Amazon S3 bucket.

• Model import settings - S3 location: Choose the DeepSeek-R1-Distill-Llama-8B folder you uploaded to your S3 bucket.

• Service access - Choose a method to authorize Bedrock: Create and use a new service role.

• Service access - Service role name: AWSBedrockModelImportRole. This role will have permission to access your S3 bucket, and you can reuse it later for other model imports to Bedrock.

Click Import Model to start the job. It will take several minutes to complete, and you can check the status in the Jobs tab.

After the job completes successfully, an entry will appear in the model tab. Click on the entry and copy the model ARN (Amazon Resource Name).

At this stage, you can also open the model in the Playground and interact with it. If you encounter a "Model not Ready" exception, please refer to the Important Notes section of this article.

You will need the model ARN, along with AWS credentials, to use the model from an OutSystems application.

Using the Model

Using the model in an ODC app is straightforward. The AWSBedrockRuntime Forge component wraps the official Amazon SDK for Bedrock and provides an action called InvokeModel for direct model use. This action requires the payload—the request—as binary data. Here's how to create a payload for the DeepSeek R1 model we just imported.

• Open the AWS Bedrock Model Invocations library in ODC Studio.

• Double-click the server action Deepseek_Llama_Invoke in Logic - Server Actions - Invocation.

Check the Request input parameter, which has an array of Messages with a Role and Content attribute. The Role can be either user or assistant, and the Content is any text. This structure somewhat follows the OpenAI API standard for conversational message prompts.

However, a model does not understand this structure directly. Instead, it uses specialized tokens to distinguish between a system prompt, a user message, or an assistant message. Therefore, the first step is to create a prompt string from this structure, which is done in the GenerateLlamaInvokePayload action.

GenerateLlamaInvokePayload performs the following steps

• Creates a StringBuilder objects

• If the request has a system prompt it appends

"<|begin_of_text|><|start_header_id|>system<|end_header_id|>" + NewLine() +
Request.System + "<|eot_id|>" + NewLine()

• Iterates over all Message items of the Messages array and appends

"<|start_header_id|>" + Request.Messages.Current.Role + "<|end_header_id|>" + NewLine() +
Request.Messages.Current.Content + "<|eot_id|>" + NewLine()

• Execute the StringBuilder_ToString action to get the complete prompt string.

• Assign global request parameters, such as MaximumLength, and the prompt string to a local variable.

• Serialize the local variable.

• Convert the serialized payload to binary data.

• Return the binary data payload.

In the Deepseek_Llama_Invoke action, this payload is used along with your AWS credentials to invoke the model.

Now it's up to you to build something on top of it.

Important Notes

Imported models in Amazon Bedrock are removed when they are not used for a couple of minutes and it takes up to 10 seconds depending on the model to cold start it. This causes additional latency and even my lead to a ModelNotReady exception. You can read more in the documentation.

Take some time to review Bedrock pricing for imported models.

Summary

In this tutorial, we imported a distilled DeepSeek R1 model into Amazon Bedrock. We also explored how to create a prompt string from a request structure in ODC to perform a direct model invocation.

I hope you enjoyed it. Feel free to leave a comment with your questions, or even better, tell us what you have built. We greatly appreciate any feedback.

In this tutorial, we will parse incoming messages and respond to them using the Bot Connector API.

Demo Application

This article series includes a demo application called "ODC with Bots for Teams Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.2 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Bots for Teams Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.2.

Version 0.2 depends on other Forge components:

• OAuthTokenExchange - An external logic library that helps retrieve access tokens easily.

• Bot Framework Service API - A connector library for using Bot Connector API endpoints.

Responding to Messages

In the introduction to this series, I explained the different types of activities a messaging endpoint can receive from a channel. The most important type is a message. The messaging endpoint receives this activity when someone sends a text message in a conversation where the bot is involved.

In this article, we will explore how to respond to a message activity.

We will use a pattern I came up with after several tries. I believe it provides the most flexible and adaptable way to build bots with OutSystems Developer Cloud. The main idea is that a single messaging endpoint—the one we already created—can be used for multiple connected Azure Bot resources. Additionally, multiple bots can be built as ODC applications to respond to incoming activities. At a glance this pattern involves the following steps

• Handle Inbound Request - Our messaging endpoint receives the entire activity payload as text. In this first step, we partially deserialize the request and store the whole payload in an entity record, along with some additional data, for later retrieval. Finally, we trigger an event with the activity details.

• Subscribe and Handle Event - Next, we handle the event. For simplicity in the demo, we handle the event directly in the demo application, but you can also create a separate application, subscribe to the event, and handle it there. Handling involves checking the activity type, retrieving the whole activity payload from the entity, deserializing the necessary parts, and then performing actions to respond to the activity.

• Authorize with Connector API - To send a message back to the conversation, we need to authorize with the Connector API. In our handler, we request an access token using our Entra application registration details.

• Build and Send Response - Finally, we create a response message and send it to the conversation through the Connector API.

Demo Application Settings

Before we go through the implementation details, let's configure the demo application's settings.

In the previous part of this series you created and configured Azure Bot resource and an attached Entra application registration. Make sure that you have copied Application (client) ID and the generated Client Secret from the application registration.

In ODC Portal - Apps, select "ODC with Bots for Teams Demo."

In the Configuration tab, set the following values:

• EntraClientId - Application (client) ID from the Entra application registration

• EntraClientSecret - Client Secret value from the Entra application registration

With our configuration set, we can now proceed with the implementation details.

Handle Inbound Activities

The exposed Messaging REST API endpoint receives activities from a channel. For more information on the different activity types, see the Introduction article. In the endpoint action flow, we perform the following steps:

• Deserialize part of the activity payload

• Create an entity record with basic activity details and the full payload

• Trigger an OnBotActivity event

Switch to ODC Studio and double-click the Messages endpoint in Logic - Integrations - REST - MessagingEndpoint.

• DeserializeInboundActivity - This server action converts the received text payload into a BasicActivity structure, which includes some parts of the full activity payload.

• Activity_Create - This server action creates a record in the Activity entity with details of the inbound activity and the full payload received as binary data. (Note the conversion from text to binary data)

• OnBotActivity - This event trigger uses property values from the deserialized activity payload as the event payload. The purpose of the event parameters is to provide a handler with enough information about an activity to determine if it should be handled.

Handle Event

Select the OnBotActivity event in Events - Events.

The demo application defines an in-app event handler called BotHandlerSimpleTextResponse (Logic - Bots). Using an event instead of handling everything directly within the Messaging endpoint allows you to build multiple bots within ODC. These bots can subscribe to this event and handle it based on conditional checks of the event parameters.

Bot Handler

Open the server action BotHandlerSimpleTextResponse in Logic - Bots.

• IsMessageType - This condition checks if the activity type is a message. If it isn't, the action flow ends because we only want to handle messages. At this point, you can add more checks, like verifying the BotId.

• Activity_Get - This action retrieves the full payload as text from the Activity entity.

• DeserializePayload - This action deserializes parts of the full payload. Here, we only deserialize the parts relevant for this bot handler to respond to the activity.

• OutboundMessagePayload - Here, we create a new activity of type message with text. Note the mandatory "From" assignment where we assign the Recipient object, which is our Bot.

• GetConnectorAPIAcccesToken - Before sending the activity to the Connector API, we need to acquire an access token, which this server action returns.

• Connector_SendToConversation - This uses an action from the Bot Framework Service API Forge component to send the response activity to the conversation.

Bot Framework Service API

Calls to the Connector API are made to a dynamic serviceUrl that depends on the channel that sent the activity. For example, the "Test in Web Chat" feature in the Azure Portal uses a serviceUrl of webchat.botframework.com, while activities from a Teams channel have a serviceUrl starting with smba.trafficmanager.net. The exact serviceUrl depends on the channel and sometimes the region of your bot, which is why the serviceUrl must always be deserialized from the inbound activity.

Activity Schema

The demo application includes the fixed elements of the Bot Activity Schema (Data - Structures - Schema) that you can use to build your own payloads.

Try it

Switch to the Azure Portal and select your Azure Bot resource. Go to the Settings - Test in Web Chat menu. Type anything in the chat window, and you should see the message:

Congratulations! You have successfully set up your ODC bot. 🎉

I recommend starting the demo application in debugging mode and setting some breakpoints to observe how the application processes the incoming message activity.

Summary

In part 3 of the ODC with Bots for Teams article series, we explored the steps needed to handle an inbound message activity using the Test in Web Chat feature of the Azure portal. We learned how to deserialize the inbound activity and manage it asynchronously with an in-app event handler.

In the next part of the series, we will activate the Microsoft Teams channel for our Bot resource and create a configuration package to add the bot to the Microsoft Teams client application.

Make sure you have read the Introduction to understand the different parts of this setup.

Demo Application

This article series includes a demo application called "ODC with Bots for Teams Demo," available on ODC Forge. Be sure to download the version of the application that matches each article in this series.

For this article, you need to install Version 0.1 from ODC Forge.

• In the ODC Portal, go to Forge - All Assets.

• Search for "ODC with Bots for Teams Demo".

• Click on the Asset (Do not click on Install on the tile!).

• Switch to the Version tab and click on Install next to Version 0.1.

Messaging Endpoint Application

A messaging endpoint receives various types of messages from communication channels, including user messages. In an OutSystems Developer Cloud, this is an exposed REST API endpoint that accepts POST requests and is later configured in an Azure Bot resource.

• Open the ODC with Bots for Teams Demo application and switch to the Logic tab.

• In Integrations - REST, select MessagingEndpoint.

The exposed REST API is configured with authentication set to None, and documentation is turned off.

• Click on the Messages endpoint

The Message endpoint is set up to accept POST requests and has one input parameter, Request, which is received in the Body as type Text.

• Copy the URL of the Messages endpoint. If you have not changed the demo app name it should be /ODCwithBotsforTeamsDemo/rest/MessagingEndpoint/Messages. We need that URL path later on, when we configure the Azure Bot resource.

For now, we will leave the Demo app and set up the rest in the Azure Portal.

Register Entra Application

A bot resource requires an Entra application registration, which we later use to get an access token to communicate with the Bot Connector API and respond to messages.

In Azure Portal go to App Registrations and click on New registration.

• Name - Microsoft Teams Conversational Bot with ODC

• Supported account types - Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)

• Click Register

From the Overview page, copy the values of:

• Application (client) ID

We will need these values later.

Add a Client Secret

Under the Manage menu select Certificates & secrets

Select the Client secrets tab and click on New client secret

• Description - ODC Conversational Bot sample

• Expires - Recommended: 180 days (6 months)

• Click Add

Immediately after adding the new client secret, copy the Value and save it for later, as it will only be displayed once. We won't use the Client Secret in this article, but it will be needed in future articles.

Add a Redirect URI

The final configuration step is to add a Redirect URI to the application registration.

Under the Manage menu select Authentication.

In the Platform configurations section click Add a platform

• Select Web

• Redirect URIs - https://token.botframework.com/.auth/web/redirect

• Click Configure

Create an Azure Bot

With our basic application registration complete, we can now create an Azure Bot resource that will connect one or more channels (like Microsoft Teams) with our ODC messaging endpoint.

In Azure Marketplace search for Azure Bot and click Create - Azure Bot.

• Bot handle - BotId-<Application ID from Entra App Registration>

• Subscription - Select your subscription model

• Resource group - Choose a resource group where you want to place the bot resource

• Data residency - Global

• Pricing tier - Change plan to Free

• Type of App - Multi Tenant (corresponds to our Entra App Registration)

• Creation type - Use existing app registration

• App ID - Paste the Application ID from the Entra App Registration Overview page

• App tenant ID - Paste the Tenant ID from the Entra App Registration Overview page

• Click Review + Create, review the information the click Create

Wait until the deployment is complete, then click on Go to resource to continue.

Set Bot Profile

In the deployed Azure Bot resource, first go to the Settings - Bot profile menu and give your bot a meaningful display name and description. You can also upload a custom icon here.

Configure Messaging Endpoint

Next switch to the Settings - Configuration menu. The only settings we have to configure here is to provide the FQDN to our Messaging endpoint.

The messaging endpoint FQDN is the combination of your ODC stage base URL and the path you copied earlier from the Messaged endpoint of the demo application.

• Messaging endpoint - https://<ODC stage>.outsystems.app/ODCwithBotsforTeamsDemo/rest/MessagingEndpoint/Messages

• Click Apply to save the changes.

Receive a Message from Web Chat

Switch to ODC Studio and double-click the Messages endpoint in Logic - Integrations - REST - MessagingEndpoint.

Right-click on the Start node and select Add Breakpoint from the menu to add a breakpoint.

In the Debugger tab, click Start debugging.

Leave the debugger and go back to your Azure Bot resource. Select the Settings - Test in Web Chat menu. You should immediately see ODC Studio flashing.

Check the Request input parameter, which contains a JSON document that should look like this:

{
  "type": "conversationUpdate",
  "id": "KJvkAp8O6y1",
  "timestamp": "2025-01-20T05:49:46.1194744Z",
  "serviceUrl": "https://webchat.botframework.com/",
  "channelId": "webchat",
  "from": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
  },
  "conversation": {
    "id": "xxxxxxxxxxxxxxx-eu"
  },
  "recipient": {
    "id": "BotId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "My Demo OutSystems Bot"
  },
  "membersAdded": [
    {
      "id": "BotId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "name": "My Demo OutSystems Bot"
    },
    {
      "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
    }
  ]
}

This first message indicates that both a bot and a user joined a conversation.

Resume the debugger to continue.

Next type a message in the Web Chat console and inspect the message again in the debugger.

You should receive a message like this

{
  "type": "message",
  "id": "175nbLQPt2A7LhdRnSZeYM-eu|0000000",
  "timestamp": "2025-01-20T05:55:16.1409929Z",
  "localTimestamp": "2025-01-20T06:55:18.613+01:00",
  "localTimezone": "Europe/Berlin",
  "serviceUrl": "https://webchat.botframework.com/",
  "channelId": "webchat",
  "from": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "name": ""
  },
  "conversation": {
    "id": "xxxxxxxxxxxxxxx-eu"
  },
  "recipient": {
    "id": "BotId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "My Demo OutSystems Bot"
  },
  "textFormat": "plain",
  "locale": "de",
  "text": "Hello",
  "attachments": [],
  "entities": [
    {
      "type": "ClientCapabilities",
      "requiresBotState": true,
      "supportsListening": true,
      "supportsTts": true
    }
  ],
  "channelData": {
    "clientActivityID": "xxxxxxxxxxxx"
  }
}

In this case I, identified by the from object, sent a text “Hello” to the bot identified by the recipient object.

The Test in Web Chat feature uses the Web Chat channel, which is activated by default. Later, you can disable these pre-activated channels once you are satisfied with your bot. However, for development purposes, you should keep it activated as it offers an easy way to test your implementation.

Summary

Congratulations! You have just completed the initial setup to receive messages from an Azure Bot resource. In this tutorial, we set up a new Azure Bot resource in your Azure Active Directory tenant. This resource sends messages received by a channel to a REST API endpoint in an OutSystems Developer Cloud application. In the next article, we will cover how to respond to incoming messages using the Bot Connector API.

Bots for Microsoft Teams offer many benefits. They can answer user questions and boost productivity by automating tasks directly within a conversation, among other things.

The Microsoft Bot for Teams ecosystem is extensive, and Microsoft provides several tools for developing bot solutions: the Bot Framework SDKs, the Teams Toolkit, Bot Composer, and the newest addition, Copilot Studio. Unfortunately, the documentation mainly assumes you are using one of the provided toolkits, and it takes some time to figure out how to create a bot—or multiple bots—with an alternative technology stack like ODC.

This is what I aim to cover in this article series because, in the end, all the above toolkits just use configurations and APIs you can leverage in ODC directly without needing to create custom code or adapt the Microsoft Bot Framework SDK for .NET.

So I hope you enjoy this journey on how to build Bots for Microsoft Teams with OutSystems Developer Cloud.

Why you should care

Nearly every organization is now working or at least experimenting with GenAI chatbots and AI agents. OutSystems has introduced its own AI Agent Builder, a user-friendly Forge component for creating conversational GenAI solutions. It also includes a UI widget library to design your own chatbot interface. This is ideal if you want to add an AI conversation feature to another ODC application, like a CRM you built. However, if you want to build a conversational AI experience that isn't directly linked to another application in ODC, it makes sense to integrate with an application users are familiar with. Since Microsoft Teams is the most popular messaging platform, it's a great choice.

Microsoft Teams is a great choice for providing users with a single point of contact to access multiple conversational AI solutions, like Bots. This applies not only to the AI Agent Builder but also in general.

Components of a custom Bot Environment

Although the documentation might seem overwhelming at first, setting up a bot environment for ODC is quite simple. Here are the core components:

• A configured Azure Bot resource for each bot you want to build, with an attached Microsoft Entra application registration.

• A single REST endpoint in ODC to receive conversation messages from channels like Microsoft Teams.

• Action flows in ODC to handle incoming messages and respond (with many structures for deserializing and serializing messages 😒).

• A Teams app publishing profile to add a Bot to a user's Teams client.

Without further ado, let's take a brief look at all of these components.

Azure Bot

Azure Bot is a resource you can set up from the Azure Marketplace in your tenant. Once configured, the Azure Bot resource acts as a gateway or router between one or more channels and a messaging endpoint.

Channels

Channels are integrations that allow your bot to interact with users on various communication platforms, such as Microsoft Teams, Facebook Messenger, Slack, Telegram, and many others.

Messaging Endpoint

The Messaging Endpoint is a specific URL that handles incoming HTTP requests from messaging channels. This is where the bot receives messages from users and processes them to create appropriate responses. For ODC, this is a single REST POST endpoint. A single messaging endpoint doesn't necessarily represent just one bot; it can be used for multiple different Azure Bot resources.

Bot Framework REST APIs

The Microsoft documentation for developing bots mainly focuses on using one of the official Bot Framework SDKs, such as the .NET Framework. These SDKs work with the Bot Framework REST APIs, which are Microsoft-managed APIs for sending messages (Connector API), receiving messages (Direct Line API), and managing user authentication (Token API) to and from a channel.

In OutSystems Developer Cloud applications, we need to use the Bot Framework REST APIs directly instead of the SDK. The Bot Framework offers the following REST APIs.

Connector API

Communication from a channel to a messaging endpoint is one-way. The messaging endpoint only receives requests and cannot directly reply to the channel. Instead, for a bot to send a message to a channel, it must use the Bot Framework Service Connector API. This API converts messages from the general Azure Bot message format to the specific format needed by each channel, ensuring messages are delivered correctly across different channels. For more details, see the Connector API OpenAPI specification.

Token API

In addition to the Connector API, the Bot Framework Service offers the Token API, which issues and manages access tokens to ensure secure and authenticated communication between a bot and a channel. A key feature of the Token API is that it simplifies the authentication process and token retrieval if your bot needs a user to sign in directly within a conversation. See the Token API OpenAPI specification for details.

Direct Line API

The Direct Line API is another API provided by the Bot Framework Service. It allows you to build your own client application to interact with a bot if none of the supported channels meet your needs. See the Direct Line API reference and the OpenAPI specification for details.

Bot Messages

Channels send requests to the Messaging Endpoint, and bots send requests to a channel using the Connector API. Request payloads are defined in the Azure AI Bot Activity Schema, which is a standardized JSON format used across all supported channels. Each request, called an Activity, is identified by a type attribute in the payload. Below is a list of all possible activities, along with simplified payload examples.

• message - Standard communication between bot and user. Includes the main content the bot wants to convey, such as text, attachments, or interactive cards.

{
  "type": "message",
  "text": "Hello! How can I assist you today?"
}

• conversationUpdate - Sent when a conversation's state changes. For example, when a user joins or leaves a chat, or when the conversation is created or deleted.

{
  "type": "conversationUpdate",
  "membersAdded": [
    {
      "id": "user1",
      "name": "User One"
    }
  ],
  "membersRemoved": [],
  "timestamp": "2025-01-10T07:10:00Z"
}

• contactRelationUpdate - Triggers when the bot's contact list changes. Includes adding or removing a user as a contact.

{
  "type": "contactRelationUpdate",
  "action": "add",
  "user": {
    "id": "user1",
    "name": "User One"
  }
}

• typing - Indicates that the bot or user is currently typing a response. Helps manage user expectations and improves interaction flow.

{
  "type": "typing"
}

• ping - A lightweight activity used to check connectivity between bot and endpoint. Ensures the bot is active and responsive.

{
  "type": "ping"
}

• event - Represents a named event sent from the bot or channel. Often used for channel-specific events or to trigger specific bot actions.

{
  "type": "event",
  "name": "customEventName",
  "value": {
    "key": "value"
  }
}

• endOfConversation - Indicates that the conversation has ended. Useful for closing sessions or indicating that no further interaction is expected.

{
  "type": "endOfConversation",
  "code": "completedSuccessfully",
  "text": "Thank you for chatting! Goodbye."
}

• handoff - Used to transfer the conversation to a human agent or another bot. It can include context and state information to facilitate the handover.

{
  "type": "handoff",
  "handoffMetadata": {
    "conversationId": "12345",
    "context": "Customer needs support from a human agent."
  }
}

• invoke - Represents a request to perform a specific operation. Commonly used for actions like triggering a dialog or processing specific input.

{
  "type": "invoke",
  "name": "triggerDialog",
  "value": {
    "dialogId": "greetingDialog"
  }
}

• installationUpdate - Sent when the bot is added or removed from a channel or a group. Helps the bot manage its presence and react to changes.

{
  "type": "installationUpdate",
  "action": "add",
  "timestamp": "2025-01-10T07:10:00Z"
}

Microsoft Teams Channel Integration

A channel is set up in the Azure Bot resource, but this alone is not enough to make a bot available in Microsoft Teams. To let users chat with a bot, it must be added as an app to Microsoft Teams.

An app for Microsoft Teams is a JSON document that follows the Microsoft App Manifest schema and includes configuration details about your bot. The manifest, along with the referenced app icon resources, is then compressed into a ZIP archive and published either as a custom app to a single Teams client (suitable for testing), to the organization's app catalog, or to the Teams Store.

If you aim to make your bot available to all Teams users by publishing it to the Teams Store, you must submit it to the Teams Store and ensure it meets all the necessary compliance and security requirements.

Other Channel Integrations

In this article series, we will focus only on Microsoft Teams. For information on how to integrate a bot with other supported channels, like Slack, please see Configure an Azure AI Bot Service bot to run on one or more channels - Bot Service | Microsoft Learn.

Conversation Scenario

Lets look at a simple conversation example scenario.

Mike has already a custom bot app OutSystems Bot published to his Teams client. In the Teams client he selects the OutSystems Bot App and Microsoft Teams display a conversation window with the Bot.

Mike enters “Hello” into the chat field and sends the message.

Message Receive

Our messaging endpoint will now receive two requests with two different type values

• conversationUpdate - This request indicates that Mike joined a conversation with the bot. The payload for this request looks like this.

{
  "type": "conversationUpdate",
  "membersAdded": [
    {
      "id": "29:xxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx",
      "aadObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    {
      "id": "28:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ],
  "id": "f:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "serviceUrl": "https://smba.trafficmanager.net/emea/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/",
  "from": {
    "id": "29:xxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx",
    "aadObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
  "recipient": {
    "id": "28:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "OutSystems Bot"
  },
  .... Additional payload data
}

Note the membersAdded array. The first item is the Id of the user Mike, the second one is the Id of the bot. Both have been added to the conversation.

• message - The second request of type message is the chat message Mike entered in the chat window. The payload looks like this.

{
  "text": "Hello",
  "textFormat": "plain",
  "type": "message",
  "id": "xxxxxxxxxxx",
  "serviceUrl": "https://smba.trafficmanager.net/emea/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/",
  "from": {
    "id": "29:xxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx",
    "name": "Mike",
    "aadObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "id": "a:xxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx"
  },
  "recipient": {
    "id": "28:xxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx",
    "name": "OutSystems Bot"
  },
  ... Additional payload data
}

Message Respond

Responding to an incoming message is straightforward. We can either send a response to the conversation itself or reply to an incoming activity (represented by the id attribute of the incoming message payload).

We choose to send a message directly to the conversation.

• First, we acquire an access token for interacting with the Connector API.

• We extract the serviceUrl, recipient.id (the Bot Id), from.id (Mike's Id), and conversation.id values from the "Hello" message sent by Mike.

• We make a request to

URL: https://<serviceUrl>/v3/conversations/<conversation.id>/activities
METHOD: POST
AUTHORIZATION: BEARER <Akquired Access Token>
JSON PAYLOAD:
{
  "type": "message",
  "from": {
    "id": "<recipient.id>" // Bot User Identifier
  },
  "recipient": {
    "id": "<from.id>" // Mikes user identifier
  },
  "text": "Welcome Mike, Iam happy to chat with you"
}

Summary

This concludes the introduction to Bots for Microsoft Teams with OutSystems Developer Cloud. Please take a moment to review the provided links, as they contain important additional information.

Setting up a basic environment for Microsoft Teams Bots with ODC is straightforward. It involves creating an Entra application registration and an Azure Bot resource in your Azure tenant, configuring the Bot resource to send messages to your exposed REST API endpoint, setting up one or more channels, and finally creating a publishing profile for a Teams app. We will cover how to perform these steps in the next part of the series.