Part 2: Create and connect to a Mobile Cloud Service mobile backend

Purpose

This tutorial walks you through the process of developing a Mobile Cloud Service (MCS) mobile backend where you can create, coordinate, and use MCS components. Specifically in this tutorial, you develop a mobile backend to support technicians and an application that allows them to work with customers to document specific appliance incidents.

To complete this tutorial, you will create a new MCS mobile backend, create an API definition to connect and access appliance incident data, including images, and then view the components from a MAF MCS Utility Application.

You must also download a zip file containing images and code that you will need while working on the tutorials. See next section or See “What Do You Need”

What Do You Need

Required Files	Download Files
This archive contains code and images you will need during the tutorial. The file should be saved and unzipped in a temporary directory located in the same hard drive partition as your JDeveloper/mywork directory.

Optional Requirements

To complete this tutorial you may, install and configure JDeveloper and either the Android SDK or Xcode 6 if you want to use iOS. These optional requirements allow you to test your MCS definitions from a MAF application. You may also test your definitions from outside MCS using Postman, if you do not want to install and configure the MAF MCS Utility.

If you are using an iOS environment, you can use the following tutorial to set up the development environment: Set Up and Configure an iOS Environment.

If you are using an Android environment, you can use the following tutorial: Set Up and Configure an Android Environment.

Product versions

This tutorial (v3.3) was developed against the following product versions:

- Oracle Public Cloud - Mobile Cloud Services - 16.3.3 (found in the About menu option)

- Oracle Mobile Application Framework - 2.3

- Oracle JDeveloper 12c (Studio Edition) - 12.2.1

- MAF MCS Utility - 2.2.1.0

- Chrome Postman - 4.3.5

In this section, you connect to your MCS instance and create, then examine, a mobile backend. A mobile backend is a logical grouping of custom APIs, users, storage collections, and other resources that are associated with one or more mobile apps.

One new thing for the UI in MCS 1.1 is an adaptive UI based on role. What this means is that it might be the case that some users will not see the same options other users see, depending on the assigned role for a user.

Used at development time to:

At deployment time, the mobile backend serves as a deployment unit with dependency management for all of the artifacts you need to support the set of mobile apps.

Like with all development efforts, save often, and save a lot.

1. Log in to your Mobile Cloud Service Home page and then, in the upper left of the page, click the burger icon to access the DEVELOPMENT menu.

   

   

2. In the DEVELOPMENT menu, click the Applications option to view the main applications page.

   Click the arrow in the upper left to dismiss the menu.

   

3. Click the Mobile Backends icon.

   

   Here, you can create, search, and view any mobile backend. On the left, you see any previously created mobile backend definitions. On the right, you see some high-level details for the selected mobile backend.

   On the upper left, click the New Mobile Backend button.

   

4. In the pop-up window, set the Name to FIF_Technician_xx (where xx is a unique value in the MCS instance - mine will be "3d"). You will be using this naming convention throughout this tutorial.

   Then, enter a description and click Create.

   

5. By default, the Settings page appears, where you can access the authentication and connection details required by your mobile applications.

   The identifiers you see here are used to authenticate your mobile application, connect your mobile application to its mobile backend, and access platform and custom APIs. These settings are also used by the mobile client SDK to construct REST headers for calls made to platform APIs. The Notifications API uses the application key to pair your mobile application with an individual user's mobile device, so that you can precisely target the sending of notifications from MCS.

   To get a better understanding of what a mobile backend may contain, let's examine one. All of the elements that we will look at here are covered in successive tutorials.

   

6. Click the Diagnostics icon on the left.

   Diagnostics enables you to easily find out what's going on with your connected mobile application by providing you with increasingly detailed levels of logging messages. Diagnostics presents request and error data in the Diagnostics page that is specific to a single mobile backend.

   

7. Click the Clients icon on the left.

   After you have a mobile backend defined, you can access from your mobile client.

   Here you add any mobile applications that you would want to recieve Push notifications.

   

8. Next, click the APIs icon on the left.

   After you have a mobile backend defined, you can access the API Catalog and select any custom APIs for your mobile backend to use.

   Or as the mobile developer, you might want to start creating your own set of REST APIs to provide building blocks for your applications.

   

9. Now, click the Storage icon.

   Within a mobile backend, collections can store the data from a mobile application. Similar to a table, a collection manages a group of various data objects, such as JSON payloads, text files, or images.

   

10. Click Users.

    Here is where you specify a user realm where you create and manage the mobile app users that are allowed to access the applications associated with the mobile backend.

    

11. Click Notifications.

    Here you configure notifications for both iOS applications (via Apple Push Notifications Service (APNS)) and Android applications (via Google Cloud Messaging (GCM)). If you set up notification configurations for both, you can initiate a single notification and have it delivered to both types of applications.

    

12. Finally, click App Policies.

    You can define and configure properties to be used to control and determine application policies.

    App policies are custom properties that you can define and adjust in a mobile backend and then reference from your apps through a simple REST call. Once you have defined an app policy, you can update its value anytime, even after you have published the mobile backend. This lets you make changes to the appearance and behavior of a deployed app without having to update the app itself.

    These values may be simple, like a string that appears in a welcome screen, or more complex, like things related to backend configuration—timeout values, location of certain files, and so on.

    

    In the next section, you add a custom API.

In this section, you add an API that allows your customers to report problems. This time you create the API from an existing RAML document and consume it in your mobile backend. A later tutorial covers creating an API from the ground up.

Save often, save a lot.

1. From the DEVELOPMENT menu, click the Applications menu option to return to the APPLICATIONS page. Then, click the APIs icon.

   

2. In the APIs page, click the New API button.

   

3. In the New API pop-up window, click the Upload a RAML document link.

   

4. In the Open window, navigate to the location where you unzipped the LabFiles and select the FIF_IncidentReport_3d.raml file.

   Then click Open.

   

5. In the New API pop-up window, the document loads and all the appropriate properties are populated. To ensure uniqueness, append "_xx" (where xx is your initials or another unique value) to the API Display Name and API Name properties.

   Also, change the API Name to incidentreport_xx (where xx is your unique values). Then add a short description and click Create.

   

6. A confirmation message that the API has been created is displayed and you are placed in the General tab.

   

7. To make it easy to run the API, allow for anonymous access.

   Click the Security tab, and set the Login Required slider to the Off position.

   Then click Save.

   

8. Let's take a quick look at what is created in MCS from the RAML document.

   Click the Endpoints tab and notice the three resources this API makes available.

   

9. Examine the methods in the /incidents resource.

   Click the Method link to the far right of the /incidents resource and you'll see two methods: GET and POST (click the GET or POST button in the upper left to see their details).

   

   

10. Click the Save button.

    

11. In the GET method, expand the Parameters node.

    Here are the three parameters, including name, type, and example values, which can be set when running the API. If more are required, then you can add them here.

    

12. Click the Save button.

    

13. Next, navigate to the mobile backend you created earlier and add the incident report API.

    Click the APPLICATIONS bread crumb and from the APPLICATIONS page, click the Mobile Backends icon.

    

14. In the Mobile Backends page, put the cursor in the Filter/Search box and type the unique characters (_xx) that you appended to your mobile backend when it was created.

    Then select the mobile backend and click the Open button.

    

15. Then, click the APIs icon on the left.

    

16. Click the Select APIs button.

    

17. Just like earlier, in the Filter/Search area, enter the two unique characters that you appended to the API name when it was created. Your API should be the only one in the list.

    Click the gray plus sign.

    

    ...to add the API to your mobile backend.

    

18. Navigate back to the APIs page by clicking the FIF_Technician_xx 1.0 link in the upper-left corner of the page.

    

    The FIF Incident Report API is now part of your mobile backend.

    

In this section, you test the endpoints and examine some diagnostics on the API. When you first created your mobile backend, the diagnostics page had no data. By testing the endpoints, you are able to see any example or real data that is returned. If there are any issues, then you can troubleshoot those problems before moving outside the MCS environment.

1. Inside the API tab of your mobile backend, select the FIF_IncidentReport_xx API to see all the endpoints.

   

2. Here you see all the available resources that this API has to offer.

   On the left, click the GET /incidents endpoint.

   

3. On the right, expand the Parameters node and for the contact parameter, enter lynn in the Test Console column. When using example data, the parameters do nothing and all the example records are returned. If the API had an implementation, then the parameter would restrict the returned records.

   

4. Scroll down and c lick the Test Endpoint button and examine the response. The response is displayed in a JSON format, and again if you used an API that had an implementation, you would see all the records for the contact named "Lynn". In our case since we are using example data, all the records are returned. You will see how the parameters work with an implementation later in the tutorial.

   

5. Navigate back to the mobile backend page by clicking the FIF_Technician_xx link in the upper-left corner.

   

6. Click the Diagnostics icon to see the overview. Here you can see the request counts and time.

   

7. Next, examine the requests and results for the API.

   Click the Requests tab and then the 2xx box to see any calls that returned HTTP 200, which represents a successful response. You should see one response for each time you tested the API.

   

8. Click the Timestamp to examine the message details. Notice the message includes the mobile backend name and API that was used.

   Click the X in the upper-right corner to close the pop-up window.

   

You have now created a mobile backend and API, then added the API to your backend and tested it. Next, you can run a mobile client to test your mobile backend.

If you are interested in testing your API from outside MCS, in this tutorial, you have two options: Postman or MAF MCS Utility Application. In this section you setup and configure an environment to test your MCS definitions. This step is optional and is only used to test the API from outside the MCS instance.

Use Postman

If you are not interested in using the MAF MCS Utility, you can still validate your definitions from outside MCS with Postman. Postman is an application that runs in a Chrome browser and allows you to connect and test APIs. It is a web client that gives you the ability to work with and monitor HTTP request and responses.

1. From a Chrome browser, download the application from www.getpostman.com.

   

2. Once you click on the Get the App button, the installer confirms your running from a Chrome browser and gives you the option to add the application.

   

3. After the install is complete, start Postman.

   

   On future occasions when you want to start Postman, you can find it in the Chrome App Launcher.

   

   

4. Next, to make Postman work with MCS, you need to set some environment variables in a JSON file. Once these have been set, you can import it into Postman and you'll be able to access your MCS instance.

   In Windows Explorer, navigate to the location where you unzipped the labfiles and open the Postman_MCS_1.json file in an editor.

   

5. Find the "environments": section. Here you need to change the two key values that allow Postman to access and work with your MBE. The name property is used to define a specific environment, it's keys and headers so it's easy to switch between them in Postman. In our case the environment name is MCS.

   

6. The first key you need to set is the Mobile Backend ID. This allows Postman to know which backend you are working with. In MCS, go into the Setting tab of your MBE and copy the Mobile Backend ID value.

   

   Then, back in the JSON file, paste it into the value property for the Mobile Backend Id key and save your work.

   

7. The second key you need to set for Authorization. This allows Postman to anonymously access and run your API. Again, in the MCS settings for your MBE, click the Show button to expose the Anonymous Key value.

   

   Copy the value.

   

   Then, back in the JSON file, paste it into the value property, following the word Basic, for the Authorization key and save your work.

   

8. Save your work

9. If you scroll down in the file, you'll see a headerPresets section. This defines two headers and sets the values to the keys you just modified. These header values are what gets passed into the API call. You do not need to do anything here, other than be aware of how the values and headers work in Postman.

   

10. Next, import the JSON file into Postman.

    Go back to Postman and in the upper right, click on the wrench icon.

    

    Then from the menu, select Settings.

    

11. In the Preferences screen, select the Data tab.

    Then at the bottom, click the Choose File button.

    

12. In the Open popup, find and select your Postman_MCS_1.json file. Then Open it.

    

    The file will import into Postman and when it completes, close the popup.

13. In the upper right, from the dropdown, select the MCS environment you just imported.

    

14. Finally, you need to add the header presets to the Header tab. This is quick and easy. Select the Headers tab. Then on the right, click the Preset button and select the MCS option.

    

    This will add the two headers defined in the JSON file to the Header tab.

    

    You are now ready to test your MCS definitions from Postman.

Use MAF MCS Utility Application

In this section, you install the MAF MCS Utility Application and configure it to use your Mobile Backend. This section is optional.

1. Navigate to the place where you unzipped the labfiles.zip and expand the /labfiles/ directory. Unzip the maf-mcs-utility-2.3.0.0.zip file to a directory of it's own. It needs to be unzipped in a directory path containing no spaces.

2. Then, open JDeveloper and click Open Application. In the Open Application window, navigate to the location where you unzipped the maf-mcs-utility-2.3.0.0.zip file and open the publicSample/mafmcsUtilitySample.jws file.

   

3. From the JDeveloper menu select Build -> Clean All.

   

4. Again in the JDeveloper menu, select Run -> Choose Active Run Configuration -> iOS Simulator if you are on an Mac OS X machine, or Android Emulator if you are on Windows.

   You can use this tutorial to setup and configure JDeveloper, Android SDK and Xcode (Setting Up Mobile Application Framework).

   

5. In the Application Resources pane, expand Descriptors -> ADF META-INF and open maf-application.xml.

   

6. In the editor window, click the Source tab.

   

   The utility uses maf-application.xml for default preference values. You can set preferences here or in the Overview tab.

   You will set several preferences in this file with values that you get from MCS.

7. In MCS, navigate to your mobile backend main page and click Open. (The screen shots have changed to a different set of initials, but you will search for the same mobile backend you created earlier).

   

8. Click Settings and copy the Base URL from the Environment Details section.

   

9. Back in the maf-application.xml file of JDeveloper, click the Overview tab and then select the Preferences tab.

   Next, click the Mobile Backend Base URL preference and then paste the value copied from MCS into the Default property.

   

10. Next. back in MCS, scroll down to the Authentication Keys section and in the HTTP Basic area, copy the Mobile Backend ID.

    Then, in JDeveloper, paste it into the Default property for Mobile Backend Id preference.

    

    

11. Back in MCS, in the HTTP Basic area, next to Anonymous Key, click Show and copy the Anonymous Key. In JDeveloper, paste it into the Default property for MBE Anonymous Key preference.

    
    
    

    

12. Next, if you were using Push notifications, you need an Application Key. However, in this tutorial you will not be using Push but the MAF MCS Utility Application requires a value. Select the Default property for both the MBE Application Key preference and enter a fake value. In this example, I've used "1234".

    

13. Save your work.

14. Right-click the View Controller project and select Run from the context menu.

    

    This launches the MAF MCS Utility Application in the simulator you selected earlier.

    If prompted, allow the MAF MCS Utility Sample to send you notifications.

    

15. In the MAF MCS Utility Application, click the Options icon (referred to as the hamburger icon) to see the options on the left. Click Start MAF MCS Utility Demo.

    

16. Log in to the MAF MCS Utility Application anonymously by selecting the Anonymous switch.

    

    You will see the following page when the anonymous login is successful.

    

    You are now ready to use the MAF MCS Utility Application to test your mobile backend. You will also use the tester to verify your work in later tutorials.