Overview of MobileFirst adapters

Adapters run on the server and connect to mobile apps.

Adapters are the server-side code of applications that are deployed on and serviced by MPF. Adapters connect to enterprise applications (otherwise referred to as back-end systems), deliver data to and from mobile applications, and perform any necessary server-side logic on this data.

With IBM MobileFirst Platform Foundation, create and configure adapters manually, or we can also automatically generate SAP Netweaver Gateway or SOAP adapters with the services discovery wizard.

Starting with MPF v6.3, changes were made to the XML definition and behavior of adapter timeout and concurrency.

Benefits of MobileFirst adapters

Adapters provide various benefits, as follows:

• Fast Development: Adapters are developed in JavaScript and XSL. Developers employ server-side JavaScript to code for integrating with back-end applications and processing data. Developers can also use XSL to transform hierarchical back-end data to JSON.

• Read-only and Transactional Capabilities: MobileFirst adapters support read-only and transactional access modes to back-end systems.

• Security: MobileFirst adapters use flexible authentication facilities to create connections with back-end systems. Adapters offer control over the identity of the user with whom the connection is made. The user can be a system user, or a user on whose behalf the transaction is made.

• Transparency: Data retrieved from back-end applications is exposed in a uniform manner, so that application developers can access data uniformly, regardless of its source, format, and protocol.

The adapter framework

The adapter framework mediates between the mobile apps and the back-end services. A typical flow is depicted in the following diagram. The app, the back-end application, and the JavaScript code and XSLT components in the MobileFirst Server are supplied by the adapter or app developer. The procedure and auto-conversions are part of MPF.

Figure 1. The adapter framework

1. An adapter exposes a set of services, called procedures. Mobile apps invoke procedures by issuing Ajax requests.

2. The procedure retrieves information from the back-end application.

3. The back-end application then returns data in some format.

   • If this format is JSON, the MobileFirst Server keeps the data intact.

   • If this format is not JSON, the MobileFirst Server automatically converts it to JSON. Alternatively, the developer can provide an XSL transformation to convert the data to JSON. In such a case, the MobileFirst Server first converts the data to XML (if it is not in XML already) that serves as input for the XSL transformation.

4. The JavaScript implementation of the procedure receives the JSON data, performs any additional processing, and returns it to the calling app.

   • Writing an adapter that pulls large amounts of data and transfers it to the client application is discouraged because the data must be processed twice: once at the adapter and once again at the client application.

   • HTTP POST requests are used for client-server communications between the MobileFirst application and the MobileFirst Server. Parameters must be supplied in a plain text or numeric format. To transfer images (or any other type of file data), they must be converted to base64 first.

Anatomy of adapters

MobileFirst adapters are developed using XML, JavaScript, and XSL. Each adapter must have the following elements:

• Exactly one XML file, describing the connectivity to the back-end system to which the adapter connects, and listing the procedures exposed by the adapter to other adapters and to applications.

• Exactly one JavaScript file, containing the implementation of the procedures declared in the XML file.

• Zero or more XSL files, each containing a transformation from the raw XML data retrieved by the adapter to JSON returned by adapter procedures.

The files are packaged in a compressed file with a .adapter suffix (such as myadapter.adapter).

The root element of the XML configuration files is <adapter>. The main subelements of the <adapter> element are as follows:

• <connectivity>: Defines the connection properties and load constraints of the back-end system. When the back-end requires user authentication, this element defines how the credentials are obtained from the user.

• <procedure>: Declares a procedure that is exposed by the adapter.

The structure of the <adapter> element is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<wl:adapter>
<description> 
<connectivity>
<connectionPolicy> 
<loadConstraints>
</connectivity>
<procedure /> <!-- One or more such elements -->
</wl:adapter>

The HTTP adapter

The MobileFirst HTTP adapter can be used to invoke RESTful services and SOAP-based services. It can also be used to perform HTML scraping.

Use the HTTP adapter to send GET, POST, PUT, and DELETE HTTP requests and retrieve data from the response body. Data in the response can arrive in XML, HTML, or JSON formats.

We can use SSL in an HTTP adapter with simple and mutual authentication to connect to back-end services. Configure the MobileFirst Server to use SSL in an HTTP adapter by implementing the following steps:

• Set the URL protocol of the HTTP adapter to https.

• Store SSL certificates in a keystore defined using JNDI environment entries. The keystore setup process is described in SSL certificate keystore setup.

• If we use SSL with mutual authentication, the following extra steps must also be implemented:

  • Generate our own private key for the HTTP adapter or use one provided by a trusted authority.

  • If we generated our own private key, export the public certificate of the generated private key and import it into the back-end truststore.

  • Save the private key of the keystore defined using JNDI environment entries.

  • Define an alias and password for the private key in the <connectionPolicy> element of the HTTP adapter XML file, adaptername.xml. The <sslCertificateAlias> and <sslCertificatePassword> subelements are described in The <connectionPolicy> element of the HTTP adapter.

Note however that SSL represents transport level security, which is independent of basic authentication. It is possible to do basic authentication either over HTTP or HTTPS.

The SQL adapter

Use the MobileFirst SQL adapter to execute parameterized SQL queries and stored procedures that retrieve or update data in the database.

The Cast Iron adapter

The MobileFirst Cast Iron adapter initiates orchestrations in Cast Iron to retrieve and return data to mobile clients.

Cast Iron accesses various enterprise data sources, such as databases, web services, and JMS, and provides validation, aggregation, and formatting capabilities.

The Cast Iron adapter supports two patterns of connectivity:

Outbound pattern.

The invocation of Cast Iron orchestrations from IBM MobileFirst Platform Foundation.

Inbound pattern.

Cast Iron sends notifications to devices through IBM MobileFirst Platform Foundation.

The Cast Iron adapter supports the invocation of a Cast Iron orchestration over HTTP only. Cast Iron Template Integration Projects (TIPs) are provided in Cast Iron as examples of this technique, and for you to use as a basis for our own orchestrations. See Cast Iron documentation.

Cast Iron uses the standard MobileFirst notification adapter and event sources to publish notification messages to be delivered to devices using one of the many notification providers.

For information about defining event sources, see the createEventSource method in the WL.Server class.

Cast Iron Template Integration Projects (TIPs) are provided in Cast Iron as examples of this technique, and for you to use as a basis for our own notification scenarios. See Cast Iron documentation.

To protect the notification adapter, use basic authentication.

The JMS adapter

The MobileFirst JMS adapter can be used to send and receive messages from a JMS-enabled messaging provider. It can be used to send and receive the headers and body of the messages.

Troubleshooting a Cast Iron adapter – connectivity issues

Symptom: The MobileFirst adapter cannot communicate with the Cast Iron server.

Causes:

• Cast Iron provides two network interfaces, one for administration and one for data. Ensure that you are using the correct host name or IP address of the Cast Iron data interface. We can find this information under the Network menu item in the Cast Iron administrative interface. This information is stored in the adapter-name.xml file for the adapter.

• The invocation fails with a message Failed to parse the payload from backend. This failure is typically caused by a mismatch between the data returned by the Cast Iron orchestration and the returnedContentType parameter in the adapter-name.js implementation. For example, the Cast Iron orchestration returns JSON but the adapter is configured to expect XML.

Parent topic: Develop the server side of a MobileFirst application