Implementing Workflows on App Engine with Fantasm

This post is another entry in our ongoing series of guest posts contributed by App Engine developers. Today we partner with Jason Collins and Shawn Rusaw of VendAsta Technologies who discuss their simplistic workflow management system for Python App Engine called Fantasm. Fantasm is very simple to start using but incredibly powerful. So powerful in fact, that they couldn't fit it into one blog post. So for more detail, see the Implementing Workflows on App Engine with Fantasm article in our documentation.

Most software systems of reasonable size need to implement workflows: a series of processing steps and decision points over an artifact, typically a document. You are likely using workflows even if you don't realize it; often processing is built up iteratively over time until you're left with a complex system with lots of subtleties. These systems can mysterious and difficult to manage or extend.

A formal workflow engine can offer help in these instances. It allows developers to break the steps and decision points into manageable and testable chunks, so that processing is predictable and measurable. Workflow engines can offer visibility into system operations and metrics around execution times and failure points. They provide retry mechanisms and allow tasks to be distributed among multiple computers.

We have developed Fantasm to be just such a workflow engine. Fantasm is a Python library that allows you to specify your tasks and steps between those tasks in a YAML configuration file. It uses a finite state machine model where the tasks are states and the steps are transitions. As a developer, you implement the code that executes inside of a state and are only responsible to return an event that is used to identify the appropriate transition to the next state. It is similar to the App Engine Pipeline API but is more simplistic and serves as a user-friendly introduction to the concept of workflows in App Engine apps.

Fantasm has become the central processing tool within our organization and we hope it can be of help to yours. For a more in-depth look at Fantasm (including examples!), please see the full Implementing Workflows on App Engine with Fantasm article in the App Engine documentation.

Posted by Wesley Chun, App Engine team

PayPal introduces PayPal X Platform Toolkit for Google App Engine

Hello App Engine Developers!
My name is Praveen Alavilli (@ppalavilli) and I work as a developer evangelist for PayPal's X Platform at PayPal.com. I want to take the opportunity to introduce you to our new open source toolkit for Google App Engine that provides an easy way to integrate your Java apps running on App Engine with the new PayPal's Adaptive Payments API. Currently this is a Java toolkit explicitly for App Engine Java, but a Python version will be coming out soon.

Background
The Adaptive Payments API provides a set of core services offered by the PayPal X Open Global Payments Platform to enable developers to embed payments into their applications, services, and platforms. The Adaptive Payments APIs offer several new payments functionality like Split Payments and Preapprovals, that enable developers to implement a variety of monetization models - freemium, subscriptions, pay-per-use, value-added-services, micro-transactions, e-commerce, etc. in their applications built and running on the App Engine. Whether you are building an application for Businesses to process back-end disbursements or payouts to affiliates, or building a social or gaming app for Facebook / Twitter / Open Social, or building a Desktop gadget for premium content, or building a Geolocation app that only helps users find places and people around where they are but even help in transacting them, or building a Web2.0 AJAX app that mashes up content and services, or several more use cases enabled by App Engine, now you can use the PayPal X toolkit to enable payments in them as it fits the needs.

Using the toolkit
Getting started with App Engine toolkit is easy. You can either checkout the source code from svn and import it into your Eclipse project or simply download the prebuilt jar file and include it in your application's class path (/WEB-INF/lib). Similar to other APIs that you might have used, you would need PayPal API Credentials to authenticate your API requests. With the toolkit you simply create an "APICredential" object from one of your application initialization methods (in most cases from your Servlet init() method) and load the API Credentials that you have obtained from the PayPal Sandbox. (Please refer to PayPal's Sandbox guide for more detailed information on how to obtain them).

// Obtain the credentials from your configs 
credentialObj = new APICredential();
credentialObj.setAPIUsername(getServletConfig()
    .getInitParameter("PPAPIUsername"));
credentialObj.setAPIPassword(getServletConfig()
    .getInitParameter("PPAPIPassword"));
credentialObj.setSignature(getServletConfig()
    .getInitParameter("PPAPISignature"));

// setup your AppID from X.com
credentialObj.setAppId(getServletConfig()
    .getInitParameter("PPAppID"));

// setup your Test Business account email 
// in most cases this would be associated with API Credentials
credentialObj.setAccountEmail(getServletConfig()
    .getInitParameter("PPAccountEmail"));

// add required error condition checks
//....

Once the APICredentialObj is initialized successfully, save it in the application's local context so you do not need to reinitialize it on every request.
At its core, the Adaptive Payments API provides 5 generic API methods: Pay, Pay Details, Preapproval, Preapproval Details, Cancel Preapproval, Refunds, and Convert Currency. The toolkit provides the base API Request classes required to make those API calls. To make it even simpler, the toolkit also provides a few functional API wrapper classes that not only abstracts the APIs in terms of the functionality exposed (SimplePay, ChainedPay, ParallelPay, CreateSimplePreapproval, CreatePreapprovalForPeriodicPayments, PreapprovedChainedPay, etc.) but also provides a few exceptions that helps in handling errors more easily than the generic API Responses.

A Simple example
To give you an example, let's say you are building a SaaS model application on App Engine that you charge your customers based on their usage. While on-boarding customers to use your app, you can use the Preapproval API to obtain authorization from your customers to charge them for the app/service based on their usage in the future. In this case you can simply use the 'CreateSimplePreapproval' to create and send a request as below:

try {

  // CreateSimplePreapproval request to setup a simple 
  // preapproval with no Payment Period Set
  CreateSimplePreapproval simplePreapproval = 
      new CreateSimplePreapproval();

  // set the API Credentials object (as given in the code above)
  simplePreapproval.setCredentialObj(credentialObj);

  // starting date in yyyy-MM-dd format
  simplePreapproval.setStartingDate("2010-06-25");

  // ending date in yyyy-MM-dd format 
  // in this case it's for an year from the starting date
  simplePreapproval.setEndingDate("2011-06-25");

  // set max total amount of all Payments
  simplePreapproval.setMaxTotalAmountOfAllPayments(52.00);

  // set max amount for each payment - let's say $1
  simplePreapproval.setMaxAmountPerPayment(1.00);

  // set max number of payments allowed - (52 weeks)
  simplePreapproval.setMaxNumberOfPayments(52);

  // set where to send the user in case of a cancellation
  simplePreapproval.setCancelUrl(req.getRequestURL() +
      "?action=preapproval&cancel=1");

  // set where to return the user after successful approval
  simplePreapproval.setReturnUrl(req.getRequestURL() + "?
    return=1&action=preapproval&preapprovalKey=${preapprovalKey}");

  /* Set other required fields */
  // ... //

  // set memo for user's transaction history
  simplePreapproval.setMemo("Preapproval for GAE Sample");

  // send the request
  PreapprovalResponse preapprovalResponse = 
      simplePreapproval.makeRequest();

  } catch (//...exceptions go here...//) {
  // handle exceptions as necessary

}

In this case, when the 'AuthorizationRequiredException' is thrown, your application would need to redirect the user to PayPal for authorizing the preapproval. The 'getAuthorizationUrl' method takes care of building the PayPal authorization url along with the Preapproval Key returned by the Preapproval API. Once the user authenticates and authorizes the preapproval request on PayPal.com, the user will be redirected back to your 'returnUrl' along with the preapprovalKey, which your application can verify by using the 'PreapprovalDetailsRequest' and store it in it's own app engine data store securely. From that point onwards, whenever the user needs to be charged for their usage of the application, the application can use one of the 'PreapprovedSimplePay' or 'PreapprovedParallelPay' or 'PreapprovedChainedPay' classes to make a payment on behalf of the user. Please refer to the sample apps to understand how to use the other classes provided by the toolkit to make Parallel,Chained or Simple Payments. For eg. the PicMartServlet.java in the PicMart sample app shows how you can make a parallel payment to two receivers at the same time.

Further examples
As mentioned earlier, if you are building a social game where users can buy digital goods (eg. micro-payments) and virtual currencies while playing a game, you can use the same Preapproval API to obtain authorization from them so you could charge their PayPal accounts as and when needed, without requiring them to re-enter their payment information or redirect to PayPal for authorizing the payments.
Other examples of using the toolkit can include:

• An application that lets merchants or enterprises pay their suppliers, or manage affiliate networks
• Applications to enable property owners to collect rental payments from tenants
• With a mult-merchant marketplace, a simple payroll app enables employee salary payments in multiple countries
• ...

As you can see, the toolkit's support of the Adaptive Payments APIs can easily enable all of these usecases.

Where to find more info
Please look at the sample code provided in the samples directory. The AdaptiveRequests.java class in AdaptiveSample and AdaptiveSampleFnAPI shows how to use the helper classes to send and receive requests. The PicMart sample app provides a simple example of how the Parallel Payment can be used in a Photo Printing app that let's users to buy prints of the pictures from Picasa Album of the photographer. This sample app uses the Picasa APIs to fetch the album and picture information from Picasa.

To learn more about the PayPal X Toolkit for App Engine, please visit: http://code.google.com/p/paypalx-gae-toolkit/ and to learn more about Adaptive Payments, please visit: https://www.x.com/community/ppx/adaptive_payments. You can find a lot of resources for developers like documentation, technical spec, sample apps, code, sdks, technical forums, technical support, etc.. on PayPal X Developer Network web site (https://www.x.com).
Posted by Praveen Alavilli (@ppalavilli), PayPal X Developer Network.

TweetDeck and Google App Engine: A Match Made in the Cloud

I'm Reza and work in London, UK for a startup called TweetDeck. Our vision is to develop the best tools to manage and filter real time information streams like Twitter, Facebook, LinkedIn and MySpace. We offer products like our TweetDeck desktop client built on Adobe AIR, and our iPhone application. We are happy to say that we use App Engine as key part in our backend.

We're a small startup, so early on we started to look for tools that would give us the biggest bang for our buck. Combined with the fact we love Python, we thought it might be worth taking a look at what Google App Engine had to offer. The first feature we started playing with was the mail sending facility.

It was easy! Sending mail was a single call-- no messing around. Combined with the fact that it was sent via tried-and-tested Google Mail servers, this meant that we had a simple mailing solution where we didn't have to deal with spam blacklists, mail retries or SPF records. We could really see App Engine being our sole email provider for transactional emails (new users and forgotten passwords), but also for newsletter-type mailing.

When we got started, our existing backend was hosted on Amazon EC2 and SimpleDB, and we knew that we needed a way for the two systems to communicate with each other. App Engine provides all the basic tools to define any sort of resources you want--but more importantly, it has the Python standard library. We implemented a small mail API, with authentication provided by an HMAC-SHA1 of the request information and a shared secret key. The API has been made extremely general: its JSON input format contains fields to send messages to blocks of email addresses that are either defined in the request itself, or which exist as a template in App Engine (templates are defined as strings in a Python module).

The whole setup currently works quite well. We're already extending our mailing system to use App Engine's task queues-- exposing a number of queues to break large mailing jobs into a series of subtasks, thus spreading mailing sending over a large period of time. We have plans to make an even tighter bridge between our EC2 systems and App Engine, which involves keeping our subscriber list entirely in App Engine, and adding and removing from that list as appropriate.

We also use App Engine for various other prototypes and smaller applications that are part of our product. We use it to serve our "TweetDeck Recommends" feed, and we've even developed small tools to apply TweetDeck fan badges on Twitter homepage backgrounds using the Imaging API! The lesson from us, of course, is that using something like App Engine doesn't have to mean everything runs on it. It's an extremely good platform for creating APIs or smaller parts of your application that do specific tasks, and do them well. Think of it as the UNIX metaphor applied to the Cloud.

We love that we've been able to grow the functionality that Tweetdeck provides by progressively using more of the cloud. App Engine provides the perfect platform to compose new services quickly, iterate on them in production, and scale with demand as Tweetdeck's install base grows. Thanks to App Engine and the cloud, there's nothing holding us back from tackling the needs of our user base.

Here is a video interview of Reza and the Tweetdeck team.

Guest Post by Reza Lotun @rlotun, TweetDeck