Setting up the MobileFirst generic and application-specific adapters

The generic and application-specific adapters act as a gateway to facilitate the communication between the mobile application that runs on a device and the IBM® BPM server.

Before you begin

Before you proceed with the setup of the MobileFirst adapters, review the following requirements and ensure that they are met.

Use IBM MobileFirst Platform Foundation to develop a mobile application
Have general knowledge of IBM MobileFirst Platform Foundation and MobileFirst Studio
Ensure that MobileFirst Studio is installed in your Eclipse development environment
Have a general understanding of MobileFirst adapters and their configuration requirements
Decide whether to use an application-specific adapter. This decision is determined by the type of application to be developed and the required level of abstraction. A mobile application that interacts with one or more specific IBM BPM process applications can benefit from using the application-specific adapter. A good example might be an online banking mobile application that uses the bank's existing IBM BPM process application. Conversely, a mobile application that interacts with any arbitrary IBM BPM process application would likely not be a good candidate for using an application-specific adapter. For example, an application-specific adapter would not be of much benefit to a custom portal-like application that is developed for mobile platforms.

Procedure

Create a MobileFirst project in MobileFirst Studio.
Define a location for storing the adapters that are ready for the import.
1. In Eclipse, go to Windows > Preferences > MobileFirst > Templates and Components.
2. Specify a value for the Download Folder, into which you download the adapters that you obtained from the IBM BPM server.
Use the IBM Process Center application to download the generic adapter and store the .wlc file of the adapter in the download folder that you specified in the previous step.
1. To download the generic adapter, click the Download MobileFirst Adapter link on the Process Apps or Toolkits pages within the IBM Process Center application.
2. Depending on your browser configuration, the .wlc file might be downloaded directly to your Downloads directory or you might be prompted to save the file to a specified location. If the latter, download the file to the same adapter import location that you specified earlier in step 2 b. If the former, manually copy the file from the Downloads directory to the adapter import location.
After you complete this step, the IBM_BPM_MobileFirst_Adapter.wlc file is stored in the adapter import location that you defined earlier in step 2 b.
Optional: If necessary, use the Process Center application to generate and download the application-specific adapters for any specific process applications with which your mobile application interacts.
1. Select the process application by clicking its name in the main Process Apps page. The Snapshots page is displayed.
2. Decide which snapshot you want to use in your mobile application, then click the Export link to the right of that snapshot.
  Note:
  - There are subtle differences between an application-specific adapter that is generated for the current snapshot and an adapter that is generated for a specific, named snapshot. An adapter that is generated for the current snapshot continues to use whatever snapshot is current at any point in time. An adapter that is generated for a specific snapshot continues to use that specific snapshot even though other snapshots might be created. You must consider these differences and then determine which adapter you want to use. For example, you might want to use the current snapshot during the development of your mobile application, or you might want to use a specific snapshot when you prepare your application for production. The adapter can be regenerated for new snapshots when changes to the process application are made.
  - The application-specific adapter must be generated only for active snapshots. Therefore, when you generate an adapter for a specific snapshot, make sure that you activate the snapshot before you generate the adapter for it.
  - The application-specific adapter includes procedures that are related only to exposed BPDs. You must ensure that your BPDs are properly exposed and that the user who requests the code generation has the appropriate access to the exposed items before generating the application-specific adapter.
Import the generic adapter (and optionally the application-specific adapter or adapters) into your MobileFirst project.
1. Right-click the MobileFirst project, and select Add/Remove Application Components.
2. In the dialog, select the adapters to be imported and click OK.
Configure the generic adapter.
1. Edit your worklight.properties file to include the required properties. The generic adapter's XML source file, IBM_BPM.xml, contains a description of the required and optional properties:
  1. bpm.server.hostname: (Required) The name of the host computer on which the IBM BPM server is running
  2. bpm.server.port: (Required) The port number that is associated with the IBM BPM server
  3. bpm.server.protocol: (Required) The HTTP or HTTPS protocol that is used for the communication with the IBM BPM server
  4. bpm.server.context.root: (Optional) The context root that is associated with the REST API implementation on the IBM BPM server. The default value is rest/bpm/wle. You can edit this property only if you have modified the web application context root values within the IBM BPM server.
    Here is an example:
```
# BPM server properties
bpm.server.hostname=mybpmserver.mycompany.com
bpm.server.port=9080
bpm.server.protocol=http
```
2. Configure a security test and the authentication realm and login module to be used with the adapters. The generic and application-specific adapters are pre-configured to use a security test named BPMAdapter-securityTest. If you have an existing security test that you want to use instead, modify the IBM_BPM-impl.xml file to replace all the occurrences of BPMAdapter-securityTest with the name of your security test. If you want to define the BPMAdapter-securityTests, you can use the following example to do so.
  Note: The following instructions are examples of the required types of definitions. Specific choices for your MobileFirst project must be made as part of the overall security strategy for your mobile application. For more information, see the IBM MobileFirst Platform Foundation documentation.
  1. Within the authenticationConfig.xml file for your MobileFirst project, define a custom security test. You can use the following example to configure your custom security test within the authenticationConfig.xml file:
```
<securityTests>
                <customSecurityTest name="BPMAdapter-securityTest">
                   <test isInternalUserID="true" realm="BPMAuthRealm"/>
                </customSecurityTest>
            ...
            </securityTests>
```
  2. Also, the following examples shows you how to configure the authentication realm referenced earlier within the authenticationConfig.xml file.
    Note: The com.ibm.bpm.worklight.auth.BPMAuthenticator and com.ibm.bpm.worklight.auth.BPMLoginModule are provided here as examples, but are not included with the adapter export. You can use these examples as a reference when you start writing your own authenticator and login module classes. The examples are included in the MobileFirst project .zip file that is generated for the exported client-side human service.
```
<realms>
 <realm loginModule="BPMAuthLogin" name="BPMAuthRealm">
   <className>com.ibm.bpm.worklight.auth.BPMAuthenticator</className>
 </realm>
 ...
</realms>
```
  3. The authentication realm that you have already defined references a login module named BPMAuthLogin. Here is an example of how the login module can be configured in your authenticationConfig.xml file:
```
<loginModules>
                   <loginModule name="BPMAuthLogin">
                       <className>com.ibm.bpm.worklight.auth.BPMLoginModule</className>
                           <parameter name="server.protocol" value="${bpm.server.protocol}"/>
                           <parameter name="server.hostname" value="${bpm.server.hostname}"/> 
                           <parameter name="server.port" value="${bpm.server.port}"/>
                           <parameter name="server.context.root" value="${bpm.server.context.root}"/>
                   </loginModule> 
               ... 
               </loginModules>
```
Use the adapter procedures as required to complete the development of your mobile application.
Deploy your MobileFirst project.