Tutorials and How-Tos

Options for Obtaining SaaSGrid's Billing Information

2010-03-12T17:02:00Z

As can reasonably be expected, just about every customer has their own system and processes in place to handle bookkeeping and accounting activities. SaaSGrid conducts billing actions natively as a part of its subscription model, and naturally there is a desire to link this information to a customer's own accounting systems. This article provides an overview of the information that SaaSGrid's billing system captures, and presents a couple of options for how to retrieve this information so that customers can use and link this information in to their accounting processses.

Invoices in SaaSGrid

SaaSGrid's primary record of billing actions is an invoice. Invoices are generated for two discreet actions:

Adding or changing subscriptions
Processing a recurring payment for a group of subscriptions (1 or more subscriptions)

SaaSGrid already provides the ability to view invoices via the Provider Portal. A sample listing of invoices is shown in the following screenshot:

There are two ways to access the invoice listing using the Provider Portal:

Selecting a customer via the Customers section. This permits filtering per customer / application combination.
Accessing the invoices via the Billing section. This permits filtering by invoice status only (paid/unpaid).

There will be some enhancements to the invioces view coming in a future version of SaaSGrid, including:

The ability to view all of the invoices for a particular application
General searching and sorting capability
Exporting of data via the portal into industry standard formats

Now that SaaSGrid's default capabilities are known, we can explain how to build upon this to assist in automating interactions with other systems.

Programmatically Retrieving Invoice Information

By using the SaaSGrid Remote API, it is possible to interact with the Provider Portal's backing WCF service to get invoice information. The following information is intended to provide general advice as to how to do this. It assumes some familiarity with the Remote API and WCF. If you need additional assistance, contact SaaSGrid Support or post on the forums.

Configuring the Remote API:

Reference the appropriate DLL's that are included with the SDK to access the Remote API (Apprenda.Execution.CallContextStorage, Apprenda.Utils, SaaSGrid.API, SaaSGrid.API.Remote), and setup the appropriate configuration by pointing the RootCloudUri to your SaaSGrid instance. Also, set the ApplicationAlias to provider as shown in the following example.

...
<configSections>
<section name="saaSGridRemoting" type="System.Configuration.AppSettingsSection" />
...
</configSections>

<saaSGridRemoting>
<add key="RootCloudUri" value="http://${YourCloudUri}" />
<add key="ApplicationAlias" value="provider"/>
</saaSGridRemoting>
...

Before continuing, verify that you can log in and establish a SaaSGrid session.

Configuring the Service Client:

Next, you'll need to set up a service reference to the Provider Portal service. This is done by adding a standard WCF client endpoint to the configuration along with the necessary behavior so that the Remote API can use the client. The following example shows how to set up the client endpoint correctly.

...
<system.serviceModel>
<bindings>
    <wsHttpBinding>
      <binding name="DefaultHttp" messageEncoding="Text">
        <security mode="None"/>
      </binding>
    </wsHttpBinding>
</bindings>
<client>
    <endpoint address="http://${YourCloudUri}:12000/services/soap12/http/r/provider(v1)/ProviderPortalService/IProviderService"
      contract="Apprenda.SaaSGrid.Business.Clients.ProviderPortal.IProviderService"
      binding="wsHttpBinding"
      bindingConfiguration="DefaultHttp"
      behaviorConfiguration="RemoteClientBehavior" />
</client>
<behaviors>
    <endpointBehaviors>
      <behavior name="RemoteClientBehavior">
        <ApprendaInitRoutine/>
      </behavior>
    </endpointBehaviors>
</behaviors>
<extensions>
    <behaviorExtensions>
      <add name="ApprendaInitRoutine"
        type="Apprenda.SaaSGrid.API.Remote.ClientExtension, SaaSGrid.API.Remote, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
    </behaviorExtensions>
</extensions>
</system.serviceModel>
...

Calling the Service:

You can use the same proxies that we use to call our services. To do this, add references to the following DLL's, which can be found in your SaaSGrid distribution in the folder Binaries\Applications\00000000-0000-4000-0000-000000000001\316b32db-e812-40b8-9be0-9a4292bc95cc\base\Services\ProviderPortal:

SaaSGrid.Business.Clients
Castle.DynamicProxy
Iesi.Collections
SaaSGrid.Topology

The following code example shows how to create and use our proxy, and make a service call that gets the first 1000 invoices for a given application.

using Apprenda.SaaSGrid.Business.Clients.ProviderPortal;
using Apprenda.Utility;
...

public void ProcessInvoices()
{
using (IProviderService proxy = Factory<IProviderService>.GetInstance())
{
proxy.GetApplicationInvoices(appId, 1000, 1);
}
}

The application ID of the application to list invoices for can be found by looking up the information in the SaaSGrid Operation Center's Service Catalog section, as illustrated below.

A word of caution: this technique uses our Internal API, for which we do not publish official documentation. These APIs are subject to change without notice.

Responding to SaaSGrid's Invoice Events

Whereas programmatically accessing SaaSGrid as described above can be used to read invoice information, another approach is to use SaaSGrid Extension Points to respond to Invoicing events in SaaSGrid.

The following events can be intercepted:

Invoice Creation: called prior to SaaSGrid's logic, and allows for modification of the invoice prior to SaaSGrid's creation of it
Invoice Created: called after SaaSGrid has created the invoice
Invoice Payment Initiation: called before the payment request for the invoice is made
Invoice Payment Finished: called after the payment request for the invoice is made

By using these events, customers have great flexibility in responding to invoicing events. Furthermore, the usage of other extension points in conjunction with these extension points can open up additional possiblities.

For additional information regarding extension points, refer to the document "Extending SaaSGrid", which is included with your SaaSGrid distribution. It is a little bit more difficult to implement, manage, and deploy extensions so many customers opt to use the Remote API and "poll" for information as opposed to using SaaSGrid's event triggers. A SaaSGrid support representative can help you choose which mechanism is best for you.

Developing your SaaSGrid Service to work with a Silverlight Interface

2010-02-01T22:52:00Z

Web services play a central part of all SaaSGrid applications, including those that take advantage of SaaSGrid’s native Silverlight 3 Support. There are some things to be aware of when developing, and more importantly, configuring your services so that Silverlight can talk to them. This is because the WCF client stack in Silverlight 3 is somewhat limited compared to the more complete .NET WCF stack. This article will explain how to appropriately set up your WCF services so that your SaaSGrid-based Silverlight 3 proxies can contact your services.

There are three fundamental requirements to be aware of when configuring your WCF services:

Use the basicHttp binding instead of (or in addition to) the netTcp binding.
Enhance your service to serve the clientaccesspolicy.xml file to fulfill Silverlight 3 security requirements.
Attach SaaSGrid’s ContextEndpointBehaviorExtension to all of your service endpoints (except that which serves your clientaccesspolicy.xml).

Note that the first two requirements are not imposed by SaaSGrid. They are necessary to permit Silverlight to contact your WCF services. The final requirement adds SaaSGrid “awareness” to your service. Each of these requirements is described further below.

Use the basicHttp binding instead of (or in addition to) the netTcp binding.

Silverlight 3 simply does not support the netTcp binding. Therefore you should use the basicHttp binding so Silverlight can talk to your service when developing locally and using Silverlight. Note that SaaSGrid supports both the netTcp and basicHttp bindings (although netTcp is the default on SaaSGrid and encouraged for a variety of reasons).

When your service is ultimately deployed on SaaSGrid, the service will be deployed onto the cloud using both bindings, and SaaSGrid’s routing mechanism will forward requests made by your Silverlight application from the web server to the running instance. (For information on correctly configuring your Silverlight application to contact the service, refer to the “Silverlight” section of the Developing on SaaSGrid guide.)

The following is a sample configuration file of a service that uses the basicHttp binding, which will be enhanced as the additional requirements are covered in this document:

<system.serviceModel>

<endpoint address="http://localhost:4001/Service"

binding="basicHttpBinding"

bindingConfiguration="defaultBasicHttpBinding"

contract="Service.IService"/>

</service>

</services>

<basicHttpBinding>

<binding name="defaultBasicHttpBinding">

<security mode="None"/>

</binding>

</basicHttpBinding>

</bindings> . . .

Enhance your service to serve the clientaccesspolicy.xml file to fulfill Silverlight 3 security requirements.

Silverlight, before dispatching any service calls to a running service, will request the file called clientaccesspolicy.xml from the root of the service (e.g.: http://localhost:4001/clientaccesspolicy.xml). This is a requirement that Silverlight 3 plug-in imposes for security purposes and is not SaaSGrid specific. When developing locally you must enhance your service to serve this file. When the service is running on SaaSGrid, our routing system will automatically serve this file.

To enhance your service to fulfill this client request, create a new endpoint using the webHttp binding and create a new service contract containing a single operation that responds to the request for the clientaccesspolicy.xml file. This is best described with an example, building upon that in the previous step.

First, add the endpoint and behavior in the service configuration file:

<system.serviceModel>

<endpoint address="http://localhost:4001/Service"

binding="basicHttpBinding"

bindingConfiguration="defaultBasicHttpBinding"

contract="Service.IService"/>

<endpoint address="http://localhost:4001"

binding="webHttpBinding"

behaviorConfiguration="webHttpBehavior"

contract="Service.IClientAccessPolicy" />

</service>

</services>

</binding>

</basicHttpBinding>

</bindings>

<endpointBehaviors>

<behavior name="webHttpBehavior">

<webHttp />

</behavior>

</endpointBehaviors>

</behaviors> . . .

Then, add a new service contract with the operation that will respond to clientaccesspolicy.xml:

[ServiceContract]

public interface IClientAccessPolicy

{

[OperationContract, WebGet(UriTemplate = "/clientaccesspolicy.xml")]

Stream GetClientAccessPolicy();

}

Finally, implement this service contract.

public class Service : IService, IClientAccessPolicy

{

. . .

public Stream GetClientAccessPolicy()

{

const string result =

@"<?xml version=""1.0"" encoding=""utf-8""?>

<access-policy>

<cross-domain-access>

<policy>

<allow-from http-request-headers=""*"">

<domain uri=""*""/>

</allow-from>

<grant-to>

<resource path=""/""

include-subpaths=""true""/>

</grant-to>

</policy>

</cross-domain-access>

</access-policy>";

if (WebOperationContext.Current != null)

{

WebOperationContext.Current.OutgoingResponse.ContentType =

"application/xml";

}

return new MemoryStream(Encoding.UTF8.GetBytes(result));

}

After following these steps, the fundamental requirements for a Silverlight application to communicate with the WCF Service have been met. However, SaaSGrid requires some additional endpoint configuration, described below.

Attach SaaSGrid’s ContextEndpointBehaviorExtension to all of your service endpoints (except that which serves your clientaccesspolicy.xml).

SaaSGrid attaches contextual information when the client makes service calls, which the service later reads. This allows an otherwise stateless service to know which SaaSGrid-based user is making the service call so that SaaSGrid’s subscription and security model can be applied.

This is achieved by applying the ContextEndpointBehaviorExtension to all of the endpoints that respond to service calls. As expected, the endpoint handling the call to the clientaccesspolicy.xml file must be excluded as this call will not include the SaaSGrid contextual information.

Note that for non-Silverlight applications, this behavior can be configured at the service level, and the Visual Studio SDK Template applies the configuration this way. [Note that this will be changing over the next few weeks.]

Below is the abbreviated final markup of the service configuration to use the endpoint behavior:

<system.serviceModel>

<endpoint address="http://localhost:4001/Service"

binding="basicHttpBinding"

bindingConfiguration="defaultBasicHttpBinding"

behaviorConfiguration="ApprendaEndpointBehavior"

contract="Service.IService"/>

. . .

</service>

</services>

. . .

<behavior name="ApprendaEndpointBehavior">

<ContextBehavior />

</behavior>

. . .

</endpointBehaviors>

</behaviors>

<extensions>

<behaviorExtensions>

<add name="ContextBehavior"

type="Apprenda.SaaSGrid.API.Local.`

ContextEndpointBehaviorExtension, SaaSGrid.API.Local,`

Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

</behaviorExtensions>

</extensions>

</system.serviceModel>

Conclusion

Upon following these requirements, your service should now be equipped to work with both Silverlight and SaaSGrid. Our Taskr with Silverlight sample provides an implementation of the concepts presented in this posting. If you encounter any issues or have any questions, don’t hesitate to post in our developer forums.

How to Create a Custom Login Screen For Your SaaSGrid Application

2009-04-01T14:30:00Z

Because the SaaSGrid platform is multi-application/multi-vendor, yet single sign-on from the user’s standpoint, Apprenda has provided expected authentication mechanisms and appropriate user interfaces at the platform level. Users have the ability to login by entering their username and password, which grants them access to all of their subscriptions.

The Default Login Interface

By default, the authentication user interface is themed (via CSS) to match the style of the SaaSGrid portal user interfaces. This is the login screen for all applications that do not implement custom login styles as described in this document.

Custom Login Interfaces

Through a combination of CSS and an application setting in the SaaSGrid Provider Portal, ISVs may override the login screens for their particular application(s).

The SaaSGrid runtime routes requests for applications based on automatically generated application URLs – which are created at deploy time; therefore, each application deployed to a SaaSGrid cloud instance has its own ‘entry point’. If a user hits the ‘entry point’ for an application and the user is not already logged into to their SaaSGrid account, SaaSGrid will render the login screen, AND if the ISV for the application has specified a custom stylesheet for the application, it is applied as in the screens above.

Step 1: Create the Custom Stylesheet

The core styles to override in your custom stylesheet are:

body - Define a style for the body of the page, such as the background image/color, margins, etc.

body { your declarations here; }

div.section - The login controls are encapsulated in a div with the class 'section'. Override this CSS class declaration to change the container of the login controls.

div.section { your declarations here; }

.section .title - The login control container has an <h3> html tag that has the class 'title' applied to it. Override this declaration in your stylesheet to change the title of the container.

div.section h3.title { your declarations here; }

#footer - The copyright statement on the default login screen is encapsulated in a <div> html tag with the id 'footer'. Override this id to change the style of the footer element.

#footer { your declarations here; }

Most of the desired customizations for the authentication screens can be accomplished by simply providing overrides for these 4 style declarations.

Step 2: Upload & Host the Stylesheet

After you have created your stylesheet, upload it to a hosting location of your choice that is accessible to the internet. This may be a URL on your corporate website or another site altogether. SaaSGrid implements your custom stylesheet by writing a <link rel=”stylesheet” /> tag to the login page that points to the URL you will specify in step 3.

Step 3: Specifying the Stylesheet URL in Your Application Deployment Settings

Now that you have created and hosted your custom stylesheet, you will need to tell SaaSGrid that you want to override the login screen for your application. You can do this in the Deployment Settings configuration for you application in the SaaSGrid Provider Portal. On the Deployment Settings page you will see a section called ‘Login Page Stylesheet’ (see below) that allows you to enter the URL of your hosted stylesheet. Simply enter the URL and save your changes. From this point on, when a user accesses any version of your application via its application URL and needs to authenticate, the login page will apply your style overrides.

You're done!

API Changes

2008-10-03T20:46:00Z

Today we are publishing a new version of our API that will require code changes on our provider's part for the first time in the beta period. We understand that API revs are expensive and painful for developers and we will work very hard to make sure that we have as few as possible in the future.

We are introducing a new enum (MeterStatus) and a new class (MeterResult). Their usage is similar - they return a status of the requested meter change. Previously, when you changed a meter, you received a bool to indicate success or failure (for decrement) or a count (for GetCount). This meant that you couldn't return meaningful status to your users about a meter - you had no way to know if they had had access and the count was exhausted or if they did not have access. For example:

OLD API:

[code lang="csharp"] bool canDoIt = SubscriptionContext.Instance.DecrementBlock("DoIt"); if (canDoIt) { // Do It } [/code]

That doesn't give you information about whether or not the user had access to the meter, only that it could or couldn't decrement. The new version:

NEW API:

[code lang="csharp"] MeterStatus canDoIt = SubscriptionContext.Instance.DecrementBlock("DoIt"); if (MeterStatus.NotExhausted == canDoIt) { // Do It } [/code]

Likewise, methods that returned a value have been updated to also include status:

OLD API:
[code lang="csharp"] long howManyLeft = SubscriptionContext.Instance.GetBlockCount("DoIt"); if (10 < howManyLeft) { // Do It }[/code]

NEW API:

[code lang="csharp"]

MeterResult<long> doItResult = SubscriptionContext.Instance.GetBlockCount("DoIt");
if (10 < doItResult.Value) { // Do It } else if (MeterStatus.NotSubscribed == doItResult.Status) { // User doesn't have access! } else if (MeterStatus.NotExhausted == doItResult.Status) { // User has some but not enough }[/code]

How To Create Shared Lookup Tables

2008-09-10T11:25:00Z

This article was last updated on September 30, 2009.

One of the challenges of writing SaaS apps is making a multi-tenant database schema, especially if you have a pre-existing single tenant application that you want to move to SaaS. SaaSGrid makes this process much easier by changing your schema to be multi-tenant automatically.

Most of the time, SaaSGrid's automatic conversion of database tables to multi-tenant tables is exactly what you want. Sometimes there is data that should be shared among all of your tenants, such as a listing of countries and timezones. In this case, it probably does not make sense to maintain separate copies of this data for each tenant and it is desirable to conserve database space.

SaaSGrid Support and Considerations

SaaSGrid permits you to include a metadata file that permits application developers to designate tables as "shared tables." This is straight-forward to do and is described in the next section. Please be aware of all SaaSGrid considerations before utilizing this feature of SaaSGrid:

This is suited for the co-mingled data model only. In the isolated database data model, SaaSGrid simply deploys a copy of the database for every tenant, as there is no notion of "shared tables" in this data model. If you designate shared tables in the isolated database model, it is ignored. In this scenario, a separate non-SaaSGrid database must be created for shared data, and private cloud operators can enlist SaaSGrid to assist with managing the configuration of the database connection.
This is suited for read-only lookup data only. SaaSGrid is designed to allow all traditional database operations (e.g. select, insert, update, delete) in application code and process these queries in a way that affects only the data of the tenant that the user belongs to. Non-select operations that affect shared tables are not guaranteed to have consistent state between databases in isolated and between servers in commingled model. In the co-mingled data model, this is because there will be multiple copies of the shared data: one for every database server that backs your scaled-out application. Only the copy of shared data local to your tenant's data would be changed in the event of a insert, update, or delete operation.Isolated suffers from a similar issue, but the scope is now at the tenant database level. However, simultaneously changing data in all shared tables across all databases, servers and datamodels is possible and can be done through the patch process.

Indicating Shared Tables in your Application

Designating shared tables for your co-mingled application is done by including a metadata file in your application.

To do so, include a file called manifest.sql.xml in the persistence folder of your application archive.

Here is an example of such a file:

<manifest xmlns="http://schemas.saasgrid.com/PersistenceManifest">
   <tableOptions>
      <tableOption name="countries" option="AllTenants" />
      <tableOption name="timezones" option="AllTenants" />
   </tableOptions>
</manifest>

The name attribute indicates the name of your table. The option attribute set to the value AllTenants indicates that this table should be shared amongst tenants. You may share as many tables as you wish.

To insert data into your shared tables when the application is deployed, place the insert statements in the Application Provisioning script after your table's create statement.

Creating "Hello World" Part 3 of 3 - Modifying Your Local Environment

2008-04-11T20:48:00Z

Apprenda's VP of Engineering, Abraham Sultan, takes you through how to modify your local environment to simulate different execution contexts and see how the "Hello World" application reacts to the different use cases. This video is the last part of the 3 part demo; if you haven't yet, we recommend that you see Parts 1 and 2 before this one so you can better understand what's going on.

[camtasia:CreatingHelloWorld3of3:700:570]

Creating "Hello World" Part 2 of 3 - Using the API

2008-04-10T15:38:00Z

Apprenda's VP of Engineering, Abraham Sultan, takes you through how to enhance a WCF "Hello World" application to use the SaaSGrid API. This video is a continuation of Part 1 and in the video Abe goes over the different types of monetizable features that SaaSGrid supports and shows you how easy it is to enhance your application to take advantage of them.

[camtasia:CreatingHelloWorld2of3:700:570]

To learn how to configure your local execution environment check out Part 3!.

Creating "Hello World" Part 1 of 3 - Getting Started

2008-04-08T17:14:00Z

Apprenda's VP of Engineering, Abraham Sultan, takes you through your first steps as a SaaSGrid developer. Beginning with a fresh install of the SaaSGrid SDK, Abe fires up Visual Studio and creates a new SaaSGrid solution, outlining the structure of a simple service-oriented application that does what you'd expect from your first project... it says "Hello World!".

[camtasia:CreatingHelloWorld1of3:700:570]

Ready for more! check out Part 2.