Adaptive Card sessions from #bbdevdays

Ben Lambert

I had a chance watch the adaptive card sessions from last week's #bbdevdays conference - great jobs @Dan Snyder and @Shelby Lewis!! I love seeing how you were able to use my blog posts to create flows that build your adaptive cards and then respond to the card actions (i.e., the Submit button)! Thanks for the shout-out, and I was glad to have been helpful!

Dan - in your session, you expanded the Send an HTTP request action in your flow and showed including a few request headers. Specifically, you included a Bb-Api-Subscription-Key header (with your API key) and an Authorization header (with a literal value of 'Implicit'). Neither of those headers are needed - that's the key point of the Send an HTTP request action (and all of Blackbaud's Power Platform connectors) - you don't need to have a SKY developer account. In fact, the official connectors will ignore both of those headers if they are included. So you can remove both of those headers from your actions in the flow. Actually, you may want to consider regenerating your sensitive SKY API subscription key (or rotating to use your secondary key) since it was visible in the recording.

@Alex Wong - you asked a question toward the end of Dan's session about whether Blackbaud would consider expanding the types of adaptive card actions supported. That is definitely something that is possible, but it'd be great if you could articulate/describe the scenario you'd like to support. As mentioned in the documentation, Action.Webrequest is just a custom action type that we defined within the Adaptive Card Host SPA…it handles sending the card details to the specified URL and handling any response that comes back (ex: showing a toast message). I'd always envisioned supporting additional types of “post-action” logic (like, “Refresh the current page”, “Navigate to URL”, etc., but never had a chance to formally define that implementation. That could mean just beefing up the types of post-action things supported by Action.Webrequest, but that could also be implemented as completely new types of card actions (ex: Action.DoSomethingCool) within the Adaptive Card Host SPA. So, if you can articulate your scenario/need to Blackbaud, it's possible that @Ben Wong ‘s amazing team (near and dear to my heart) may be able to come up with an elegant implementation that models your scenario.

Again, great job on the presentations Dan and Shelby!

Heather McLean

@Ben Lambert - thank you for your responses and for laying all of the groundwork that made these project possible! Isn't it inspiring to see these developers flourish!

Alex Wong

@Ben Lambert
Action from the Adaptive card is quite limited (from what I tried).

It is only able to “submit” the request with the data entered on the form and receive back the “response” and show it as a “toast message”.

It would have been better to be able to receive the response back and the adaptive card is able to “do something” with it. For example, display the response in the adaptive card somewhere (like a request status text area). If the submission was to “create” a record (gift or constituent), the response may be a “constituent record id” or “gift record id”, which being able to display that as a “link” to directly go to the record would be great too.

It may be too much to do with Adaptive Card, but if we use “high code”, I am able to use Glen's AIO tile to build a form (HTML CSS JavaScript), do AJAX submission, get back JSON data, process the JSON data, and depending on success or fail, “remove” the form, and display the response (nicely formatted in HTML CSS), and a new request form (subsequent form) to do additional functionality with a new submission, this can all be done in 1 flow with various condition action in the flow to drive down different path.

Ben Lambert

@Alex Wong (and Blackbaud team)

Another feature to consider in the Adaptive Card Host SPA that would support Alex’s scenario and many others…support returning another adaptive card from a webrequest. So for example, inspect the MIME type of the webrequest response (or look at the root element in the JSON) and if it is an adaptive card, then replace the original card with the new card. that would allow building a response card that can be as complex or as simple as needed to convey the response message. Would be a fun Friday afternoon feature to implement…?

Alex Wong

@Ben Lambert
lol on Fun Friday reference… I remember IBM used to have this “fun friday” concept, but everyone is always too booked up to really do “fun friday”

Kevin Hamling

@Ben Lambert
I am a CRM developer with a good amount of experience with Infinity/SDK, but I am just getting into Sky APIs, Sky Add-Ins, and Power Platform. I've seen the links for Adaptive Card Sky Add-Ins for FE/RE NXT and they seem straightforward. My question is should I be able to follow those in order to create the Adaptive Card Sky Add-In for CRM? I am running into an issue when I try to use the “Validate a user identity token” when creating any Power Automate flow for our Staging environment. I get an error, “The user identity token was missing or invalid, or the token has expired, or was issued to a different application or environment”. I have registered our Blackbaud hosted Staging environment (SP34, on BBID) as a Sky Application in my Developer account in order to get the Application ID. Maybe I did something wrong here with the URL, which I entered as "https://crm<siteid>s.sky.blackbaud.com/<siteid>s/webui/webshellpage.aspx?databasename=<dbname>. This is the link that takes me directly to our Staging instance of CRM. The RE example seemed straightforward, but I cannot get it to work in CRM. I'm not sure if I'm on the right track or not. I have been able to create a Power Automate flow, get the URL and embed it as a Custom Component in a Constituent tab using CRM's design mode and am able to get that to work, but if I try to create a Power Automate flow using the Sky Add-Ins connector, I cannot get past the “Validate a user identity token” action. Thank you for any help and direction you can provide.

Ben Lambert

Hi @Kevin Hamling,

Sadly, I'm no longer employed by Blackbaud so my knowledge is limited to the state of things as of March 2023. At the time, I don't believe the Blackbaud CRM (Infinity) webshell was capable of acting as a "SKY Add-in Host" (even using the "custom component" section type). At one point, I had explored leveraging the Page Host SPA with Blackbaud CRM. This technically works, since the Page Host SPA (built and deployed by Blackbaud) acts as the Add-in Host, but there were some challenges getting the right omnibar experience (if I remember, you can specify &svcid=bbcrm, but you won't see all the menu items since webshell uses a custom omnibar implementation). I built an adaptive card (using Power Automate) that uses the Send an HTTP Request (in the Add-ins connector) to send a request to the BBCRM SKY APIs to fetch data to be rendered in the card.

I don't know if anything has changed in the past few months, but I know the team was very interested in seeing what options were available to bridge between the (old) webshell UI and the (new) SKYUX UI. Perhaps someone from the team may have more thoughts (tagging @Ben Wong, @Paul Gibson, and @Heather McLean in case they can respond).

While we wait a Blackbaud to respond, perhaps you can elaborate more on what you'd ultimately like to accomplish (ex: add a custom section to CRM page <xyz> that shows an adaptive card). Any detail you can provide will help the team think through potential solutions.

Glen Hutson

@Kevin Hamling:

@Ben Lambert
I am a CRM developer with a good amount of experience with Infinity/SDK, but I am just getting into Sky APIs, Sky Add-Ins, and Power Platform. I've seen the links for Adaptive Card Sky Add-Ins for FE/RE NXT and they seem straightforward. My question is should I be able to follow those in order to create the Adaptive Card Sky Add-In for CRM? I am running into an issue when I try to use the “Validate a user identity token” when creating any Power Automate flow for our Staging environment. I get an error, “The user identity token was missing or invalid, or the token has expired, or was issued to a different application or environment”. I have registered our Blackbaud hosted Staging environment (SP34, on BBID) as a Sky Application in my Developer account in order to get the Application ID. Maybe I did something wrong here with the URL, which I entered as "https://crm<siteid>s.sky.blackbaud.com/<siteid>s/webui/webshellpage.aspx?databasename=<dbname>. This is the link that takes me directly to our Staging instance of CRM. The RE example seemed straightforward, but I cannot get it to work in CRM. I'm not sure if I'm on the right track or not. I have been able to create a Power Automate flow, get the URL and embed it as a Custom Component in a Constituent tab using CRM's design mode and am able to get that to work, but if I try to create a Power Automate flow using the Sky Add-Ins connector, I cannot get past the “Validate a user identity token” action. Thank you for any help and direction you can provide.

Hi Kevin, one thing you mentioned: “ I have been able to create a Power Automate flow, get the URL and embed it as a Custom Component in a Constituent tab using CRM's design mode and am able to get that to work” is a quasi-equivalent to a SKY Add-In in RENXT. Two different ways of approaching embedding external content within the system. That being said, if you're in our Cloud Operations and your environment is linked to BBID, you can take advantage of the Page Host SPA that Ben had mentioned. This does have a couple of advantages such as having more “screen-estate” for embedded Power Bi reports, etc. That can utilize the Validate a user identity token functionality.

Kevin Hamling

@Ben Lambert
Ok, I did not realize you were not with Blackbaud any longer, but I thank you for responding. I'm not really sure at this point what I want to accomplish with the Sky Add-Ins connector and Power Automate. I am just starting to get my hands on it and see what I can do. I guess a most simple question is should I be able to register a Blackbaud hosted Staging environment as a Sky Application in my Sky developer account and use the Sky Add-Ins connector to successfuly utilize the “validate a user identity token” action and then use the HTTP request from the connector to call the Sky APIs?

Kevin Hamling

@Glen Hutson
Hi Glen. Thank you. We are hosted by Blackbaud and our Staging environment is on BBID, but I cannot get past the “Validate a user identity token” step when using the Sky Add-Ins connector with Power Automate. If I understand correctly, it seems like that should work when using the Application ID of the app I registered using our Staging CRM link. I'm not sure what I'm missing or maybe I am not understanding. As mentioned, I am just beginning to play around with this. I was excited to be able to embed a Custom Component using the URL of another flow, so just digging into other capabilities.

Glen Hutson

@Kevin Hamling:

@Glen Hutson
Hi Glen. Thank you. We are hosted by Blackbaud and our Staging environment is on BBID, but I cannot get past the “Validate a user identity token” step when using the Sky Add-Ins connector with Power Automate. If I understand correctly, it seems like that should work when using the Application ID of the app I registered using our Staging CRM link. I'm not sure what I'm missing or maybe I am not understanding. As mentioned, I am just beginning to play around with this. I was excited to be able to embed a Custom Component using the URL of another flow, so just digging into other capabilities.

The “Validate a user identity token” will only work for you in combination with the Page add-in (not embedded directly in CRM). Anything that you're embedding directly into CRM as a custom component won't get the correct information it needs. So, for right now, embedding the output of a flow would be the route to go when embedding directly within CRM. Using the Adaptive Card SPA will only work on the Page Add-in, not when trying to embed directly in CRM.

Kevin Hamling

@Glen Hutson
Apologies for the back and forth. I am not being very clear. Let me try to restate. I was able to embed a Custom Component using the URL of a power automate flow. It was actually your Weather (All In One) post that helped me be able to do that. What I am now trying to do is something completely separate just as a learning exercise, trying to use the “Create an Adaptive Card Sky Add-In template”. I registered my Staging link as a Sky Application, put my Application ID in the Validate token action, followed the instructions for adding the Add-In as a Tile to my application (screenshot) while url-encoding the CardServiceURL. I think I expected it to show up as a Constituent Tile in CRM.

Glen Hutson

@Kevin Hamling:

@Glen Hutson
Apologies for the back and forth. I am not being very clear. Let me try to restate. I was able to embed a Custom Component using the URL of a power automate flow. It was actually your Weather (All In One) post that helped me be able to do that. What I am now trying to do is something completely separate just as a learning exercise, trying to use the “Create and Adaptive Card Sky Add-In template”. I registered my Staging link as a Sky Application, put my Application ID in the Validate token action, followed the instructions for adding the Add-In as a Tile to my application (screenshot) while url-encoding the CardServiceURL. I think I expected it to show up as a Constituent Tile in CRM.

Hi Kevin, great to see that you were able to take advantage of the AIO option. Currently, that (or perhaps a Power App) is the only way to get the output of a flow embedded into CRM. Neither the Adaptive Cards nor the Validate a user identity token currently work directly on CRM pages. The only place they currently work in a CRM environment is on the Page Add-ins that Ben reference earlier (not constituent page tiles). During our Product Update Briefing last April, it was mentioned that the native SKY Add-in functionality that will allow for Adaptive Cards and the Validate a user identity token is on the roadmap. However, I don't have any details on how close that is.

Ben Lambert

@Kevin Hamling

The problem is that the CRM webshell isn't (currently) a SKY Add-in "host" so it won't be able to produce a user identity token to send to your flow to validate (along with any "context" object).

But for the sake of discussion, let me elaborate on how you might use the Page Host SPA in case you want to try it out. I'm working from memory here, and potentially stale knowledge as of March, so keep that in mind.

The Page Host SPA *is* an add-in "host" - it is not part of the CRM webshell UI, it's a separate single-page-application (SPA). It provides a browser-friendly way to access your add-in as if it's just another page in the system (meaning, a "page" in the browser...not a "page spec" in the Infinity catalog system). The Page Host SPA is just a shim that includes the onnibar for navigation continuity.

So you can build a flow as you've done (triggered by an HTTP request) and paste the ID of your SKY application when validating the user identity token (btw, your SKY application ID isn't sensitive so no need to obfuscate it). In your flow trigger, you can also define additional context values you expect to use within the flow, and you can use the Send an HTTP request action in the SKY Add-ins connector to call the CRM SKY APIs and do whatever interesting logic you need to build an adaptive card. When you save your flow, Power Automate will give you the URL that can be used to trigger it.

You can then register an add-in for the "Page" extension point, which just means you can then access your add-in using Page Host SPA URL convention described in the docs (assuming your SKY application has been "connected" to your Blackbaud environment by your admin via the Marketplace -> Manage tab (this is what tells the system "this app has been approved for use within the environment"). The URL to specify when registering your Page add-in isn't your flow trigger URL...it's the Adaptive Card Host SPA URL (the Adaptive Card Host SPA is an add-in "client"):

https://app.blackbaud.com/addin-adaptivecard-host/tile?cardServiceUrl=YOUR_ENCODED_FLOW_TRIGGER_URL

Note that I'm using the /tile route. I know that may not be intuitive since you want a full-page experience, not a tile experience. It works, but means you might also need to provide a sufficiently large value for the `height` query parameter (since this route is normally intended for tile add-ins where the height is constrained).

So to summarize, you can:
1. Build your flow in Power Automate and save it to get the trigger URL
2. Use an online encoder to URL-encode your flow's trigger URL
3. In the SKY Developer portal, define an add-in for the "Page" extension point, and provide the Adaptive Card Host SPA URL for your add-in's URL. This URL accepts your flow's trigger URL as a query parameter.
4. Access the new "page" via the Page Host SPA URL convention in your browser. Make sure you include &svcid=bbcrm (currently undocumented) as well as &envid=YOUR_ENVIRONMENT_ID, and any context values as query string parameters (as described in the Page Host SPA docs) like &context_SystemRecordId=SOMEGUID.

At runtime, the page (being rendered by the Page Host SPA) will obtain a user identity token and pass it (along with any context query params you've included) to the Adaptive Card Host SPA, which will in turn send them to your flow. You should see a page with omnibar (but no menu items) showing your adaptive card.

The key point here is that all of this happens outside of the Infinity Webshell (until Blackbaud provides a formal support for SKY Add-ins within CRM).

Hope this helps!

Kevin Hamling

@Ben Lambert, @Glen Hutson

Thank you both for your help. I am understanding more now. I hope to not take up much more of your time. I think I am close to having my adaptive card show using the Page Host SPA.

I was on the right track based on the steps Ben provided, but I had missed a couple of things. I believe I have now followed all of the steps correctly. When I go to the Page Host SPA url, I see an omnibar with the 3 bars (dropdown menu) on the left and my user logo on the right; however, my adaptive card is not displaying. I just show a blank page. I am just using the “hello world” adaptive card from the walkthrough examples. I don't see that my adaptive card Power Automate flow was activated (not sure if I should, but I would think so). I am going to try to figure out what I'm missing, but wanted to follow up with the status and see if I might be missing something obvious. Again, thank you both.

Ben Lambert

@Kevin Hamling Following up, were you able to get this working? A few things to check:

• Make sure your SKY application is connected to your Blackbaud environment (via the Marketplace → Manage page)
• Make sure your Page add-in has an appropriate “Name” (this is what the Page Host SPA will use to find the URL to use for the embedded iframe that will render your add-in)
• Make sure you've properly encoded your flow's URL when you specify it as the cardServiceUrl parameter when defining your Page add-in.
  

When you access the Page Host SPA, it checks to see if your app (as specified in the route of the URL) is connected to your Blackbaud environment, and that your app has an add-in with the Name that you specified (also in the route of the URL).

If you open your browser's debugger, do you see any error messages?