Using Atomic Services

Atomic Services that have been created and saved by developers may be used by any user of the platform. There are several ways in which the VPH-Share cloud platform enables use of Atomic Services:

  • By asking a specific service to be instantiated using the so-called Generic Invoker
  • By authoring a Taverna workflow which makes use of the VPH-Share AS plugin to automatically instantiate the required services
  • By writing your own software which communicates with the Cloud Facade interface of the Atmosphere platform and makes use of its API to instantiate and invoke services

In this guide we will focus on the Generic Invoker as a tool provided directly by the VPH-Share platform and targeted for end users rather than application developers. A description of the Cloud Facade API can be found here. If you intend to use a workflow system (e.g. Taverna) to interface with the VPH-Share cloud platform you should consult the documentation supplied by that system.

The Generic Invoker

The Generic Invoker is a facility provided as part of the VPH-Share Master Interface and enabling you to use specific Atomic Services using a straightforward GUI, without worrying about the technicalities of service instantiation and invocation. Technically, the Generic Invoker is part of the Cloud manager portlet and can be accessed by logging into the Master Interface and selecting Applications in the menu. Please refer to the service developer manual to learn how to access the Master Interface and open the Cloud Management portlet (the steps involved in this process are identical whether you are a service developer or end user). Once you have logged in, select the Applications tab (which should be active by default) and click . This will bring up a list of the available Atomic Services:

List of Atomic Services available for instantiation in the Generic Invoker

Clicking Start next to the name of the selected service will instruct Atmosphere to prepare that service for user interaction. The contents of the window will change to reflect the fact that a service is being spawned, as shown in the following example:

Generic Invoker booting an Atomic Service Instance

 Booting delay: Depending on the configuration of the Atomic Service, Atmosphere may decide to grant you access to an existing instance of the service (if one is available) or to launch a brand new instance for your personal use. In the latter case the booting process may take several minutes as the service payload must be uploaded to one of the available cloud hosts and then booted.

You will be informed by the Master Interface when your service becomes available, as shown in the following screenshot:

Atomic Service Instance running in the Generic Invoker

At this point you may click the blue Show/hide details button to learn about the possible ways in which you may interact with your Atomic Service Instance. The Cloud Management portlet will display a suitable dialog listing the interfaces provided by the instance:

Atomic Service Instance access methods

In this case the sample service provides access through SSH (for administrative purposes) as well as an HTTP redirection upon which a Web Application endpoint has been configured. Clicking on the displayed link will take you directly to the web application, enabling you to start using the service - in this case the ViroLab Drug Ranking System:

The ViroLab Drug Ranking System accessed through the Generic Invoker

 Delayed activation of service payload: The cloud infrastructure reports the service as running as soon as the operating system has booted up; in practice, however, the Atomic Service payload (i.e. the actual application) may take a bit more time to reach a state in which it is ready to accept user requests. This is why Atmosphere monitors all HTTP endpoints that are exposed by the instance (including Web Services, RESTful services and web applications) and displays a suitable message next to each endpoint telling you when the application has actually begun responding. Wait for the indicator to display ok before attempting to click on an endpoint link.

If the service provides a non-Web interface - for example a remote desktop - you will need a client appropriate for the type of interface in use (e.g. VNC/NoMachine). Some services only provide programmatic access via APIs such as SOAP or REST, in which case the service is intended to serve as a backend for other services. While it may still be useful to instantiate such services in the Generic Invoker, no end-user interface will be available. In any case, the Show/hide details button will provide you with details on how to access any interface endpoint provided by your instance.

 Reduce, reuse, recycle! Service instances are persistent - they continue to operate even if you log out of the Master Interface and will be there when you log back in. However, any running service consumes hardware resources as well as financial resources. Given the finite capacity of the underlying cloud platform (not to mention the Project's wallets) we highly recommend that you shut down any Atomic Service Instances you no longer need. Atmosphere will display the current charge incurred by each service; note that services which require larger virtual machines (more CPUs, more RAM etc.) cost more money to operate.

Security considerations when accessing Atomic Services

Ensuring secure access to service features is at the discretion of their developers - services may be offered in public access mode, or may be protected against unauthorized access by security features, either those offered by the VPH-Share project or those instituted by developers specifically for the purposes of securing a given service. It should be noted that VPH-Share institutes a common security scheme where any HTTP endpoint exposed by an Atomic Service may be secured by the so-called Security Proxy. This is a component which resides on the same machine that the service instance operates on, intercepts calls to that instance and makes a decision on whether to allow or disallow them based on the contents of a security policy (which is itself defined by the service developer). If a service is protected by a Security Proxy, either of these actions must be taken:

  • When accessing the service programmatically, the user must pass the correct security credentials in the HTTP request header. This is done via the basic_auth security mechanism, with the username being an arbitrary string and the password containing the so-called authentication ticket - a string which is issued by the Master Interface and contains encrypted information regarding the current session.
  • When accessing web application endpoints, the user may be prompted to provide a username and password pair. In this case the username may remain empty (or take the form of an arbitrary string), while the password needs to be the current authentication ticket (same as above).

To retrieve your current authentication ticket, click on the Profile link in the left-hand panel of the Master Interface menu. You will see a summary of your personal data, along with a button which copies the current authentication ticket to your clipboard for easier access:

User profile panel

 Session tickets: Please note that authentication tickets are only valid for the duration of the current session and are set to expire in 24 hours. If you wish to access your services after this time you will need to log back into the Master Interface and obtain a new ticket.

Other modes of accessing Atomic Services

If you are developing a tool or application which would like to make use of VPH-Share Atomic Services, you can interface with the API of the Cloud Facade component which serves as a programmatic entry point to the functionality of Atmosphere. The Cloud Facade can instantiate services on your behalf, add them to your workflows, modify their parameters and perform all other actions which are normally offered through the Master Interface.

Read on to learn about the APIs offered by the Cloud Facade.