Holes in docs regarding integrating with SaaS service

[xd009642]

As a newcomer to the SaaS marketplace and trying to create a first marketplace offer there's a lot of friction in the docs (or lack of) which can make it hard to get running. Very little on the main MDN site I was encouraged to use points back to this project and it was only in later calls this was suggested. And only after watching some of the videos did it become clear what features this can provide. So in general it would be good if there was a more cohesive flow for newcomers to get familiar.

But now I'm past this initial hurdle my next thing which I'm not finding is actually integrating with my API service. The services the user will deploy and offer on the marketplace seem to never be mentioned in the saas accelerator tutorials which seems like a strange oversight. After all the purpose of this is to handle subscriptions to the APIs.

For example with billing/meters, is there an API route on the saas accelerator my service can call to register usage and verify the users token? Or should my application query the deployed database for this information? Where in the SaaS accelerator docs is this ever discussed (if ever because I'm genuinely lost)?

It feels this has a lot of potential to simplify azure marketplace offers but unlocking this potential is left as an exercise to the reader

[santhoshb-msft]

Hi @xd009642 Thank your above comments.

1. SaaS Accelerator solves some specific problems related to ISV publishing SaaS offers on Azure Marketplace. Our comprehensive learning library is available at https://aka.ms/masteringthemarketplace. I think it's a good idea we can point to these learnings from our Readme page. We will discuss on this internally.
2. SaaS Accelerator is a like a UI calling our client library APIs which in turn are calling Marketplace Metering APIs. Having another API on the SaaS accelerator layer to do metering could be a little overkill. We already have á meter usage page where you can report meters. Im unsure what you mean by verify the users token. But I recommend maybe following through our SaaS Accelerator training here.
3. We are more than happy to take specific feedback and implement as required.

[krifalk]

I agree with @xd009642 as I'm in the same step in the process. After reading and watching all the material and videos it's still a bit unclear how this is expected to work in combination with my SaaS solution (except for how the webhooks work). I fully understand how it could be used as a standalone solution to enable Marketplace and handle the process manually with enabling and billing the customer.

But the documentation could be clearer regarding if I'm supposed to integrate the validation of the offer/plan/tenant and metered billing with marketplace' API:s directly or thru the SaaS Accelerator which would be the natural way to do it since it's already has the functionality with scheduling and reporting. Just adding such an example scenario to the documentation would go a long way.

[xd009642]

@santhoshb-msft thanks for the quick response. I would say regarding the docs there's not enough prevalence to the accelerator on https://learn.microsoft.com/en-us/partner-center/marketplace/ either. Going on the repo it wasn't quite clear if the saas-accelerator would handle our issues with marketplace until I watched the mastering the marketplace videos (watched about 6 so far).

I think one thing about the resources of the saas accelerator is a lot of it seems more top level. And there's a lot of statements of "without writing any code". But watching the metering videos the outcome from them is thinking "okay so I do have to write the code for aggregation and sending the meter values". But even then there's some holes in how that should be done.

Within my own service I don't want to be aggregating the meter usage and sending rate limited to an hour because if the service goes down then I've potentially given a user API calls for free. So it should be persisted to a database. It would make sense that the same database that stores users subscription information and how much they've bought would also store how much they've used.

So with this in mind I went to Invoking metered billing with the SaaS Accelerator. And we see in the video the admin going into a subscription, using the breadcrumbs to go to "manage usage", manually entering a dimension and quantity and hitting "record usage" via a button. We also see in another video setting up some sort of cron job to send out the meters.

Now from this issue I've surmised that the SaaS accelerator doesn't aggregate and send, it provides a "dumber" UI to call the meter events. So I'm probably left writing a service to handle meter aggregation and submission, and I guess deploying another database because it would be unwise to just store that information in memory.

I do think a lot of confusion comes from the prevalence of statements like "you don't have to write any code when you use SaaS Accelerator" and the lack of any resources showing how your own service then interacts with this ecosystem. And too much information is scattered between learn.microsoft.com, github and the videos. It seems there's no one place you can access all the information.

Personally, I would prefer to not use the videos, the quality is very up-and-down [^1] and from the title I can't tell if a video is necessarily useful to me. At least with text I can read through it quicker and get an idea sooner on if this is what I need or if I should move on.

[^1]: In installing SaaS accelerator from the marketplace a privacy blur is put up to hide some secrets and not removed and the teacher navigates to the app registration view on azure behind the blur. Also, there's no guidance on the fact the database URL can clash with existing customers URLs leading me to have to tear it down and start again. Additionally, turning off comments on the videos means there's no way to try and raise these issues on a video or seek clarification. Should I be raising an issue on github or azure support linking the video? There's no means of feedback

[xd009642]

Just going over videos again to try and solidify my understanding. "SaaS Accelerator introduction" has this diagram

On one slide there is the text:

Provides the code to meet all technical prerequisites for your SaaS offers ... Flexible Billing: Advanced capabilities for custom billing and pricing models.

Also , the speaker makes reference to the ISV "emitting metered usage while the customer is actively using the product". So it seems clear to me where the confusion comes from in the functionality of the SaaS accelerator.

I notice in the mastering the saas accelerator course as well there's a note on the "Scheduling metered billing events" video link saying:

The technique to enable metered billing as per this video has been updated. The setting to enable the scheduler is no longer an application configuration setting, and is now a database setting. An updated video is in development.

This is the first place that links to this video that I've seen with this warning. These videos are linked to on other places on learn.microsoftonline.com with no such warning.

If for a moment we move beyond my current confusions from the documentation I'll just put forwards the flow I want to achieve assuming the accelerator does not handle the metered billing.

1. A user subscribes to my SaaS offer on the marketplace
2. They get some sort of token they can use to make requests to my API
3. I receive these API requests
4. I check the token and make sure the user is subscribed
5. I process the request
6. I update the meters sending their usage to somewhere (either accelerator, it's database or somewhere else it can be collated and updated on the hour)

The points 2. 4. 6. are the current sticking points. If you have links to any comprehensive documentation to guide me on these I would be grateful.

[santhoshb-msft]

@xd009642 - this is all great and please keep it coming.

1. We will try to pull more of this info back into our official docs

2. I agree SaaS accelerator might not cover every scenario ISV wants to cover and for any complex scenario's ISVs would/can fork and update as needed. but if we do see more and more requests, come through around a particular feature, we will be more than happy to add them in. like the "aggregation and sending meters". And yes for the most basic scenarios there is no need for ISVs to write code.

3. That is correct it provides a UI to manually enter meters or schedule job to report a qty in intervals.

4. We will definitely try and streamline the info as much as we can. @dstarr let review the comments here and see if we can update some of the docs.

5. I am glad that update message has been useful.

Now coming to the sticking points. 2 That is correct, when the customer comes to your landing page, they come with a token in the URL, so you can identify their SaaS subscription information by calling our Marketplace Apis. More info on this can be found here: The video here walkthrough the code about that token - https://microsoft.github.io/Mastering-the-Marketplace/saas/tech-topics/#building-a-simple-landing-page-in-net You can also read more about that resolving that token here - https://learn.microsoft.com/en-us/partner-center/marketplace/azure-ad-transactable-saas-landing-page#resolve-the-marketplace-purchase-identification-token They give you the basic understanding of how things work and it's the same the Accelerator implements it.

4. You check/resolve the token for the customer SaaS subscription information. And most likely it will be in the PendingFulfilment state, which means you as ISV need to provide them the service and activate that subscription. In the SaaS Accelerator, ISV can go to the admin portal and manually activate the customer SaaS subscription or you can configure (by updating the App config) for the customers to activate it directly from the landing page.

5. To do this, yes you need to report back to our metering API documented here. You can read more about it here: https://learn.microsoft.com/en-us/partner-center/marketplace/partner-center-portal/saas-metered-billing

I just want to emphasize that SaaS Accelerator will get ISVs up and running in very less time and address the most common needs. For any complex scenarios ISV can always fork and update as needed. I answered to best of what I understood above. Please feel free to let me know any follow ups.

Couple of other things.

1. For any documentation update, please pass the specific info/flow you would like to see and we will try and get that added
2. If you need more help understanding, I recommend raising a support request in the partner center portal.

I hope this will be helpful!

[santhoshb-msft]

I agree with @xd009642 as I'm in the same step in the process. After reading and watching all the material and videos it's still a bit unclear how this is expected to work in combination with my SaaS solution (except for how the webhooks work). I fully understand how it could be used as a standalone solution to enable Marketplace and handle the process manually with enabling and billing the customer.

But the documentation could be clearer regarding if I'm supposed to integrate the validation of the offer/plan/tenant and metered billing with marketplace' API:s directly or thru the SaaS Accelerator which would be the natural way to do it since it's already has the functionality with scheduling and reporting. Just adding such an example scenario to the documentation would go a long way.

Thank you for the feedback @krifalk @dstarr maybe we can discuss this and come back to @krifalk on how best we can add this example.

[xd009642]

@santhoshb-msft okay I'll look over those and report back. And just to try and understand a flow where we can use only the SaaS accelerator and not need to implement our own service if I'm understanding correctly we could use only SaaS accelerator for:

Billing that runs on fixed schedule ignoring usage i.e. "you pay X per month for unlimited access"

Can it also be used for charging a fixed amount per API call or does that come under the stuff with metering/aggregation which it doesn't implement.

[xd009642]

As a side note I found this via google https://github.com/microsoft/metered-billing-accelerator/tree/main I have never seen a link to this in any of the documentation. Additionally, the spread of things across the microsoft and azure orgs makes it very hard to find it intuitively. How many more microsoft orgs exist which may have useful gems for azure marketplace hidden in them?

[santhoshb-msft]

@santhoshb-msft okay I'll look over those and report back. And just to try and understand a flow where we can use only the SaaS accelerator and not need to implement our own service if I'm understanding correctly we could use only SaaS accelerator for:

Billing that runs on fixed schedule ignoring usage i.e. "you pay X per month for unlimited access"

Can it also be used for charging a fixed amount per API call or does that come under the stuff with metering/aggregation which it doesn't implement.

There are different pricing models which SaaS offers support, e.g flat rate for different billing terms (+ meter billing), per-user. For the flat rate and per user option you just have to activate the customer SaaS subscription. For metered billing, through SaaS Accelerator you can emit manually or setup a schedule to emit with x qty weekly, daily, monthly, yearly or one time.

As a side note I found this via google https://github.com/microsoft/metered-billing-accelerator/tree/main I have never seen a link to this in any of the documentation. Additionally, the spread of things across the microsoft and azure orgs makes it very hard to find it intuitively. How many more microsoft orgs exist which may have useful gems for azure marketplace hidden in them?

Glad you found it. Each have their own uses. You might find this page helpful -https://aka.ms/marketplacesamples

[santhoshb-msft]

Hi @xd009642 it was great connecting with you. As explained, the SaaS Accelerator meter reporting only supports with a set QTY reporting. From your feedback, I have created an item #659 to track this pending decision to implement or not. Closing this for now, please feel free to reopen or open new for on additional questions on SaaS accelerator. Everything else our Marketplace support should be able to help. Thanks again!