Sei sulla pagina 1di 129

(https://www.oracle.

com/corporate/features

/mobile-cloud-service.html)

Develop a Mobile Cloud Service mobile


backend and custom API

Before You Begin

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, custom API and connector to support technicians and an application that allows them to
work with customers to document specific appliance incidents.

The use case for the tutorial is a fictional repair company. The company is in the contract maintenance
business, providing fast, reliable repair services which are critical to building solid customer relationships
that ensure ongoing business after the initial contract sale. FixItFast Inc (FiF), a mid-sized supplier of
maintenance services for large household appliances, understands this challenge. FiF provides extended
warranty contracts for appliances sold by department stores.

To complete this tutorial, you will create a new MCS mobile backend, create an API definition to connect
and access appliance incident data, and then optionally view the components from a MAF MCS Utility
Application or Postman . These two tools allow you to test your MCS components from outside MCS,
depending on if you want to see the results inside a MAF application or from a web application.

What Do You Need

You must also download a zip file containing images and code that you will need while working on the
tutorials. Unzip the file to a directory that works for you. Unzip the file to a directory that works for you.
Make sure there are no spaces in the directory path as it will cause problems when deploying. In this
tutorial, the file has been unzipped in the root of the "C:\" drive.

Required Files Download Files

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

Optional Requirements

1 of 129
if you want to use iOS. These optional requirements allow you to test your MCS definitions from a MAF
application or from Postman (you can download it from www.getpostman.com).

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. (http://docs.oracle.com/cd/E53569_01/tutorials
/tut_jdev_maf_setup/tut_jdev_maf_setup.html)

If you are using an Android environment, you can use the following tutorial: Set Up and Configure an
Android Environment (http://docs.oracle.com/cd/E53569_01/tutorials/tut_jdev_maf_setup
/tut_jdev_maf_setup_2.html).

Product versions

This tutorial (v4.5) was developed against the following product versions:

- Oracle Public Cloud - Mobile Cloud Services - 16.4.5

- Oracle Mobile Application Framework - 2.3.3

- Oracle JDeveloper 12c (Studio Edition) - 12.2.1.0.0

- MAF MCS Utility - 2.3.0.0

- Chrome Postman - 4.9.2

Step 1: Create a mobile backend to support a


technician application

In this section, you connect to your MCS instance and create, then examine, a mobile backend.

1. Log in to your Mobile Cloud Service Home page and then click the three lined (burger) icon on the far
left to open the DEVELOPMENT menu.

Then name of the menu will depend on the name used when creating the mobile instance. In my case
the development menu is named PMENABLEMENT1645, your name will differ. For this tutorial, the
menu name will be referred to as DEVELOPMENT.

2 of 129
Click the Applications option and then close the menu by clicking the left arrow.

3 of 129
2. In the Applications page, click the MOBILE BACKENDS icon.

3. In the Mobile Backends page, 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

4 of 129
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 and custom 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, take time yourself to look at the
various options. All of the elements that we will look at here are covered in successive tutorials.

5 of 129
6. When you are ready to move on, 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.

6 of 129
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 receive Push notifications.

8. Now, 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 defining your own set of REST APIs to provide
building blocks for your applications.

7 of 129
9. When you are ready, click the Storage icon to work with collections.

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

8 of 129
Here is where you may create and associate users that are allowed to access the applications
associated with the mobile backend.

11. Next, click Notifications.

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

9 of 129
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 configurationtimeout values, location of certain files, and so on.

In the next section, you add a custom API.

Setup an environment to access your MBE from outside MCS


(optional)
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 interested in validating your definitions from outside MCS, then you can use Postman. Postman

10 of 129
will work fine.

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

2. If you click Chrome, then you'll be taken to a place where you can launch the app. Click on the
LAUNCH APP button, the installer confirms your running from a Chrome browser and gives you the
option to add the application.

11 of 129
3. After the install is complete, start Postman.

On future occasions when you want to start Postman, the Bookmark Bar has the same icon. If you
install the Chrome App Launcher, you can find it there.

12 of 129
4. Next, to make it easier for Postman to 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 lab files 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.

13 of 129
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.

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

15 of 129
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.

16 of 129
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 section 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.

17 of 129
10. Next, import the JSON file into Postman.

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

Then from the menu, select Settings.

18 of 129
11. In the SETTINGS 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.

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

13. In the upper right, from the drop down, 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.

20 of 129
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 the MAF MCS Utility Application


In this section, you install the MAF MCS Utility Application. To complete this step, you will need access to
a production version of JDeveloper. The next section involves testing MCS using a Mobile Application
Framework application, requiring the use of JDeveloper. If you're not familiar with JDeveloper or don't
have it installed, this section is optional.

1. Start JDeveloper and click on the File - Open menu options.

21 of 129
2. 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. Remember, It needs to be unzipped
in a directory path containing no spaces.

Then, 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.

When the jws file is opened, you'll be prompted to migrate the application. Click OK.

When the migration has completed, you'll also be prompted. Click OK again.

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

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

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

23 of 129
6. In the editor window, click the Overview tab and then the Preferences tab.

24 of 129
The utility uses maf-application.xml for default preference values. You can also set these values
directly in the file by clicking the Source tab, but we'll use the Overview.

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.

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

25 of 129
9. Back in JDeveloper, select the Mobile Backend Base URL preference and set the Default value to
the value of Base URL that you copied in the previous step.

10. Back in MCS, copy the Mobile Backend ID.

26 of 129
Then in JDeveloper, select the Mobile Backend ID preference and paste it into the Default property.

11. Back in MCS, next to Anonymous Key, click Show and copy the Anonymous Key.

27 of 129
Then like before, in JDeveloper, click the MBE Anonymous Key preference and paste the value into
the Default property.

12. The last preference you need to specify is for the Application Key. If you were using Push notifications,
then you would need to create Client IDs based on the application platform.

28 of 129
For this example, I have used "1234".

13. Save your work. If you are running an Android emulator and it is not started, start it now.

If you are running an Android emulator and want better performance, complete the first 7 instructions in
Step 6 from this JDeveloper/MAF tutorial (http://docs.oracle.com/cd/E53569_01/tutorials
/tut_jdev_maf_app/tut_jdev_maf_app.html), to build and set a keystore value.

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

29 of 129
This launches the MAF MCS Utility Application in the simulator you selected earlier. If prompted, allow
notifications.

The screen shots in the tutorial are from an iOS version of the utility. The Android version looks
different but behaves the same.

30 of 129
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.

31 of 129
16. Log in to the MAF MCS Utility Application anonymously by selecting the Anonymous switch and
clicking the Login link.

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

33 of 129
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.

Step 2: Create an API for reporting appliance


incidents and add it to your mobile backend

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.

1. Click the APPLICATIONS breadcrumb to return to the Applications page.

34 of 129
Then, click the APIs icon.

2. In the APIS page, click the New API button and then, select API from the drop down.

35 of 129
3. For the next couple of steps create an API from an existing RAML document.

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

If you are interested in viewing the RAML file on it's own, open the FIF_IncidentReport.raml with an
editor application, like Notepad or Textpad.

36 of 129
4. In the Open window, navigate to the location where you unzipped the LabFiles and select the
FIF_IncidentReport.raml file. If you have not downloaded the zip file already, use this link
(files/labfiles.zip). (files/labfiles.zip)

Then click Open.

37 of 129
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.

Set the API Name to incidentreport_xx and then add a short description and then click Create.

38 of 129
view general information about the API.

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 disabled position.

Then click Save.

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

Click the Endpoints tab and notice the single resource this API makes available, incidents.

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 (to see the second method click the GET in the upper left corner).

40 of 129
10. 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.

41 of 129
In the Responses tab you can see any example data that can be used for testing the API.

You will see this data later during testing. For now, remember there are two incident reports with ids
100 and 101.

42 of 129
11. Next, navigate to the mobile backend you created earlier and add the incident report API.

Click the APPLICATIONS breadcrumb.

43 of 129
Then click the MOBILE BACKENDS icon.

12. 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.

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

44 of 129
14. Next, click the Select APIs button.

15. 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 plus sign.

45 of 129
...to add the API to your mobile backend.

16. 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.

46 of 129
You've now created an API and included it in a Mobile Backend.

Step 3: Add an endpoint to the API to return incident


records filtered using a parameter

In this part of the tutorial, you add a new, nested endpoint and GET method to return records by incident
id.

1. Go back to the APPLICATIONS and navigate to the APIs. Find your FIF_IncidentReport_xx API, and
then Open it.

2. Select the Endpoints tab, and then click the gray plus sign (Add Nested Resource) next to the
incidents resource.

3. In the new resource path, enter {id} following the /incidents/.

Save your work.

47 of 129
4. Set the Display Name property to Id and then you can add a method to the resource. Click the Add
Method button to see the methods that you can add.

Select the GET method because it will be used to retrieve incidents.

5. Click the Responses tab and then click the Add Response button. Here is where you may add what
should be seen with successful and unsuccessful returns.

48 of 129
6. Click the Add Response button and by default a 200 - OK is created for you. Add a description you
would want users to see, like OK.

Then to add some sample data, click the Add Media Type button.

7. In the Example tab, add some sample data to return when the API is called.

49 of 129
Then, copy and paste the following code into the example area:

{
"id": 20934,
"title": "Lynn's Leaking Water Heater",
"contact": {
"name": "Lynn Adams",
"street": "45 O'Connor Street",
"city": "Ottawa",
"postalcode": "a1a1a1",
"username": "johnbeta"
},
"status" : "New",
"driveTime" : 30,
"priority" : "high",
"notes" : "My notes",
"createdon": "2014-01-20 23:15:03 EDT",
"imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-
49f7-9bd2-88966c45668f?user=lynn1014"
}

8. Scroll up to the top of the page and click the Save button. You should see a confirmation message.

50 of 129
9. Next, add a response if no record is found. Scroll back down to the GET method and in the Response
tab click the Add Response button again.

10. For the Response, select 404 - Not Found and enter a description.

Then save your work.

11. When completed, the method and two responses should look like the image below.

51 of 129
12. Save all your work

Step 4: Test the Incident Report API from 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 aren't able to find
out if the endpoints can return requests from the mobile applications, but you can see how MCS tracks
requests, enabling you to quickly troubleshoot problems.

1. Inside your API, navigate to the Endpoints and click the Test button.

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

On the left, click the GET /incidents endpoint.

3. In the expanded Parameters node you could set parameter values to restrict the returned records.
However, if you are using example data, then only that data is returned and the parameters are not
used.

You may include query parameters in the URL to restrict the records that are returned. Add them to the
URL by including a "?", followed by the parameter name and then the parameter value. Depending on
the source of the data, you will see different results. Right now, only sample data is available. So, we'll
see that. If you had data retrieved from a web service or database, then the parameter values would be
used.

Parameters will not be used when only sample data is returned. We will show you how they can
be used, but since we are only using sample data, they will not have any influence right now.

53 of 129
the URI:

?contact=lynn

4. Expand the Authentication node and set the Mobile Backend to your FIF_Technican_xx backend and
the version should be 1.0. The Authentication Method should be set to Default. If you do not see this
value, then check the Security settings.

A MBE can use HTTP Basic or OAuth for authentication. If your MBE employs security, then you would
specify the authentication method here.

5. Click the Test Endpoint button and examine the response. The response is displayed in a JSON
format, and you can see the two records you entered as sample data.

54 of 129
6. Click the burger icon at the top left to invoke the menu.

In your DEVELOPMENT menu, expand the Applications node and select the Mobile Backends option.
Find and navigate to your FIF_Technician_xx Mobile Backend.

55 of 129
7. After you open in, click the Diagnostics icon to see the overview.

8. 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.

56 of 129
9. Click the first record in the timestamp to examine the message details. Notice the message includes
the mobile backend name and API that was used.

In the lower right corner, click the link next to the Request.

10. Here you see the logs for the request including what API was called and any messages.

57 of 129
Test the API from outside MCS (optional)
In this part of the tutorial, you may test the IncidentReport API by using either Postman or the MAF MCS
Utility Application. You've already logged in as an anonymous user. Now you run the API to see some
example data returned. To complete this step, you will need to have Postman installed or have access to a
production version of JDeveloper. If you're not familiar with JDeveloper or don't have it installed, this
section is optional.

Use Postman
If you are not interested in using the MAF MCS Utility, you can still validate your definitions from outside
MCS with Postman.

1. If not already started, start Postman. You can find it in the Chrome App Launcher, either on your
desktop or in your tool tray.

2. In the upper right of the app, ensure the MCS environment is selected.

58 of 129
3. Notice the gray GET label. To the right is where you'll enter the URI used by MCS.

4. In MCS, navigate to the APIs and find your FIF_IncidentReport_xx.

Then click the Test button to view the URI.

59 of 129
5. In MCS, copy the URL from the GET /incidents.

Then, paste it into Postman, next to the GET.

60 of 129
6. In Postman, click the Send button.

Postman will connect to your MCS instance, find your API and run it in the context of your MBE. Any
response can be viewed in the Body and in our case the two sample records are returned.

61 of 129
The next section shows how you can connect and test your MCS API from a MAF application.

Use the MAF MCS Utility Application


This is an optional part of the tutorial, if you want to test the MCS definitions from an external MAF
application.

1. In the MAF MCS Utility Application, navigate to the Home page as shown in the following image.

Then, click the MCS Custom API option.

62 of 129
2. Here you can read about how the utility accesses APIs.

Click the Sample tab to enter an API to run.

63 of 129
You must set two properties to run the API: URI and HTTP Method.

64 of 129
3. First set the URI. You can find the value for this field in MCS.

Back in MCS, open your FIF_IncidentReport_xx API in the API Designer.

Then click the Test button.

4. Here you can access all the endpoints that you can use. Each endpoint has a unique URL that you can
use when you test the API. The first two methods were created from the RAML document, the third you
created by hand.

65 of 129
On the left, click the POST method to see it's URL.

Click on the third method to see it's URL.

66 of 129
Look at the GET/incidents endpoint. The URI that you need to use in the tester consists of everything
that follows the port number.

In the example, the URI is:

/mobile/custom/incidentreport_1d/incidents

6. Go back to the MAF MCS Utility Application, and in the CUSTOM API TESTER FORM section, enter
that value in the URI property.

Unfortunately neither the iOS Simulator or Android Emulator support copy and paste, so you will need
to type the value.

7. By default, the HTTP Method is set to the first method in the list, GET. You test the GET method first.

67 of 129
them to the URL by including a "?", followed by the parameter name and then the parameter value.
Depending on the source of the data, you will see different results. Right now, only sample data is
available. So, we'll see that. If you had data retrieved from a web service or database, then the
parameter values would be used.

Parameters will not be used when only sample data is returned. We will show you how they can
be used, but since we are only using sample data, they will not have any influence right now.

To return only incidents where the contact is lynn, you would append the following query parameter to
the URI:

?contact=lynn

DO NOT add this parameter at this time.

8. At the bottom of the form, click Invoke Custom API to run the API and test the endpoint using the URI
that you specified.

68 of 129
9. The API is accessed, and you should see records returned in the response at the bottom of the page. If
you were accessing data from a database, the parameter values would be used to filter records. In our
case the two records of example data are returned.

These records come from the API's example data, just like they did in the API tester page within the
MCS UI.

69 of 129
Step 5: Connect to a SOAP web service

In this part of the tutorial, you create an MCS connector to support gathering data from a Right Now SOAP
service. For this tutorial, the sample SOAP service that you will use are deployed to an Oracle Java Cloud
Service, but of course the service might be deployed anywhere.

1. Log on to your MCS instance and click the burger icon.

Then, in your DEVELOPMENT menu, click the Applications option.

70 of 129
2. Close the menu and in the APPLICATIONS page, click the CONNECTORS icon.

71 of 129
3. From the drop down, select the SOAP option.

4. In the New SOAP Connection API dialog, enter the following values:

API Display Name: SoapRightNow_xx (where xx is your initials or unique value)

API Name: SoapRightNow_xx (should be populated based on the value entered for the Display
Name)

WSDL URL: http://129.150.73.18:7001/McsBetaSoapApp-MockRightNowService-context-


root/IncidentServicePort?WSDL

Short Description: Exposes All Operations for the Incident Report.

Then click Create.

72 of 129
5. In the Configuration SOAP API wizard, click Save.

6. Click the greater than sign in the upper right to navigate to the Ports train stop.

73 of 129
7. Click the greater than sign to navigate to the Security settings.

8. By default there are no policies selected in the Security Configuration. For our purposes, do not add
any policies.

74 of 129
9. In the Test page, scroll down to see all the resource methods that the service makes available. Each
method is prefixed by a POST to execute them.

SOAP APIs, when sending over HTTP, can use only the POST verb, and the exact action depends on
the SOAP method that is being called. REST, being an architectural style and not a standard, and
makes full use of all the available verbs. GET includes the request in the query string. SOAP requests
(XML messages) are usually too complex and verbose to be included in the query string, so almost
every implementation (for example JAX-WS) supports only POST.

10. Let's test a couple of the methods. First create a new incident in the database with the POST method.

Scroll down to the POST CreateIncident method.

75 of 129
Expand the Authentication node and set the Mobile Backend to the one you created
( FIF_Technician_xx ) and specify the version ( 1.0 ).

Then click Test Endpoint.

11. The response status should show 200, and the body should contain an incident ID. Write it down (mine
is 567).

76 of 129
12. Now that we can create a record using the connector and service, let's read the record using the
GetIncidentById operation.

Scroll back up to the POST GetIncidentById method and expand it.

In the Body, set the IncidentId to be the value you just created (mine was 567).

Expand the Authentication node and set the Mobile Backend to the one you created
( FIF_Technician_xx ) and specify the version ( 1.0 ).

Then click Test Endpoint.

77 of 129
13. Again, you should see a response status of 200. If you look in the body, you should see the incident ID
that you created and the username that you used.

78 of 129
Step 6: Implement and test the API with JavaScript
Node.js

In this section, you implement an incident reporting API by downloading a JavaScript scaffold that contains
stub implementations for your endpoints, adding code to the stub implementations to access the
SoapRightNow connector, and then uploading your changes to MCS.

1. You should be logged in, if not, log on to your MCS instance and click the hamburger icon to show your
DEVELOPMENT menu.

Then click the Applications menu option

2. Exit the menu and in the APPLICATIONS page, click the APIs icon.

79 of 129
3. Find the FIF_IncidentReport_xx API and open it.

4. On the left, click the Implementations icon and then click the JavaScript Scaffold button to download
the skeleton code.

The JavaScript scaffold contains stub implementations for your endpoints. It is generated from the
RAML that is associated with the API.

80 of 129
5. The scaffold comes in the form of a zip file that contains the following files. Download and unzip the file.

- incidentreport_xx.js: JavaScript skeleton code that contains stub implementations to match the
RAML resource methods.

- package.json: The standard package.json file. The name, version, and main sections are mandatory.
The 'apis' and 'connectors' sections hold a list of dependencies.

- ReadMe.md: Descriptions of the incidentreport.js and package.json files.

- samples.txt: Some custom code examples.

Take a look at the JavaScript and JSON files. In this lesson, you edit, repackage, and upload these
files to MCS.

Open the incidentreport_xx.js file in an editor.

81 of 129
6. In the incidentreport_xx.js file, notice that the JavaScript functions match the MCS API definition. The
screen shot shows the three methods and your file will also contain code to support the example
values. In later steps you will replace the example code with code to reference the APIs made available
using the connector. In 16.3.3 and later, you will also see the sample data imported from the RAML
document along with any other example data you add.

In the Code:

In MCS (this is just a list of the endpoints so you can see how they match what is included in the
scaffold file):

In the next few steps of the tutorial, you enable your custom code to access a SOAP service by using
the SoapRightNow connector that you created earlier. The connector will allow the API to access real
data from the RightNow service.

7. First set the API to use the SoapRightNow connector. From the zip file that you worked on earlier, find
the package.json file and open it in an editor. Make sure to save the file.

82 of 129
In the connectors area, add an entry that matches the name and version of the connector that you
created in MCS (remember to use your two character suffix). For example:

"/mobile/connector/SoapRightNow_xx":"1.0"

In the Code:

In MCS:

8. Next, access the SoapRightNow connector from your JavaScript. In all cases replace the code to
support the 'example' values with the code found in the below steps to access the connector APIs.

From the zip file, open the incidentreport_xx.js file in an editor. Edit the POST method to include code
to access the service.

Replace the code in the body of the service.post('/mobile/custom/incidentreport_xx/incidents',


function(req,res) stub implementation with the following code. Also remember to replace _xx in the
SoapRightNow_xx with your unique characters. The code can be found in the labfiles/code
/IncidentPOST.txt file.

83 of 129
function (success) {

res.send(success.statusCode, success.result);

},

function (failure) {

res.send(500, failure.error);

);

9. Next, replace the code to the GET method to use the SoapRightNow connector.

In the incidentreport_xx.js file, find the service.get('/mobile/custom/incidentreport_xx/incidents


/:id', function (req,res) method and replace the body with the following code. This code performs
functions that are similar to the code that you added to the POST method. The code can be found in
the labfiles/code/IncidentGETbyID.txt file.

Replace _xx in SoapRightNow_xx with your unique characters.

req.oracleMobile.connectors.SoapRightNow_xx.post('GetIncidentById', {Body:
{GetIncidentById: {'IncidentId': req.params.id}}}, {inType: "json"}).then(

function (success) {

var responsePayload = JSON.parse(success.result);

if (responsePayload.Body.GetIncidentByIdResponse == null) {

res.send(404, 'The requested resource could not be found but may be


available again in the future');

84 of 129
},

function (failure) {

res.send(500, failure.error);

);

10. Save your work.

11. Create a zip file with a parent directory containing, the package.json, incidentreport_xx.js,
ReadMe.md, and samples.txt files.

12. In MCS, navigate back to your FIF_IncidentReport_xx API and click the Implementations icon.

85 of 129
13. Scroll down and click Upload an implementation archive.

Find and select your zip file. Then click Open.

14. Dismiss the message, and click the Test button.

86 of 129
15. In the Endpoints page, navigate to POST/incidents and expand the Parameters node.

Populate the request body by clicking the Use Example button.

Set the UserName to patti (or use whatever name you want to use).

Expand the Authentication node and set the following values:

Mobile Backend: FIF_Technician_xx


Version: 1.0

If a username and password are asked for, go back to the Security tab and reset the anonymous user
to ON

87 of 129
16. Then, click the Test Endpoint button and wait for a response.

You should see a new incident id returned (the incident id in the example is 568). Remember your
incident id.

88 of 129
17. Next, use the GET method to return the incident that you just created.

In the Endpoints page, navigate to GET /incidents/{id}.

Expand the Parameters node and set the id to the IncidentId value that was returned in the previous
step.

Then set the authorization to the same values that you used when you tested the POST method.

Click the Test Endpoint button and examine the results.

89 of 129
18. You should see the incident record that was created when you tested the POST method. Confirm that
the incident uses the username that you specified earlier. The username in the example is "patti".

90 of 129
Test the implemented API from outside MCS (optional)
If you are interested in testing your API from outside MCS, in this tutorial, you have two options: Postman
or MAF MCS Utility Application. 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.

1. If not already started, start Postman. You can find it in the Chrome App Launcher, either on your
desktop or in your tool tray.

2. In the upper right of the app, your MCS environment should be showing and you should see the two
headers.

3. Notice the gray GET label. To the right is where you'll enter the URI used by MCS.

91 of 129
4. In MCS, navigate to the APIs and find your FIF_IncidentReport_xx.

Then click the Test button to view the URI.

5. In MCS, copy the URL from the GET /incidents{id}.

92 of 129
Then, paste it into Postman, next to the GET and replace the {id} with the incident id you created
earlier. In my case it was 568.

6. In Postman, click the Send button.

Postman will connect to your MCS instance, find your API and run it in the context of your MBE using
the incident id as a parameter. Any response can be viewed in the Body and in our case the newly
created record using incident 568 is returned.

93 of 129
The next section shows how you can connect and test your MCS API from a MAF application.

Use the MAF MCS Utility Application


In this section of the tutorial, you can test you MCS APIs from outside MCS, using the MAF MCS Utility
application. This section is optional and does require setting up and deploying the application from
JDeveloper. If you are not interested in testing from the MAF application, then continue on to the next
section.

1. Go back to the MAF MCS Utility Application and navigate to the Home page, as shown in the
following image.

Then, click the MCS Custom API option.

94 of 129
2. In this page click the Sample tab and here is where you can run any API methods.

You must set two properties to run the API: URI and HTTP Method.

95 of 129
3. First set the URI. You can find the value for this field by looking at the API endpoints in MCS.

Back in MCS, open the FIF_IncidentReport_xx API in the API Designer.

Then click the Test button.

4. Here you see all the methods that you can use. Each method has a unique URL that you can use when
you test the API.

96 of 129
5. First, lets test a method to find the incident record you created earlier in the MCS Utility. As part of the
URI, you can specify the incident id value as part of the path.

In MCS find the GET/incident/{id} endpoint.

Locate the URI (everything that follows the port number). For example:

/mobile/custom/incidentreport_1d/incidents/{id}

6. Go back to the MAF MCS Utility Application, and in the CUSTOM API TESTER FORM section, enter
the value in the URI field.

7. Before you run the API, you need to set the Id.

97 of 129
8. Then, make sure the GET method is selected and then at the bottom of the form, click Invoke Custom
API to run the API.

The response should include only one record, the incident with an Id of 938 and the username you
user earlier.

98 of 129
Step 7: Introduction to Analytics

Mobile program managers are responsible for the success of an organization's overall mobile strategy.
They want to know how many people are using their mobile applications, and how people are using them.
To achieve that, mobile program managers can use the analytics features in Oracle Mobile Cloud Service
to track standard metrics (such as registered and active users, number of transactions, and so on). They
can also create custom events to track business analytics and understand how users use the application.

MCS comes with a host of built-in metrics, including metrics about API calls, API call response time, new
users, active users, session count, and session duration. You can also track custom events. For example,
imagine that your application uses the Analytics API to post an event each time a mobile application user
creates a new incident report. The event could capture properties about the incident, such as the
appliance type, make, model, and model year. You could then generate graphs and tables based on those
events and filter the data in any number of ways, such as how many incident reports were filed for water

99 of 129
View system events
System events are automatically generated when mobile application users access the application. System
events track API calls, sessions, and user details. To enable system event tracking, the mobile application
developer simply calls the Analytics API to start a session, and the system events are tracked
automatically. The developer does not need to write any custom code.

To make the analytics data more interesting for this tutorial, the classroom environment has been
populated with realistic data to reflect a multi-user environment.

1. From your DEVELOPMENT menu, click the Analytics option.

2. Close the menu and notice the default view is the dashboard. Here you see active users by location,
charted on a map of the world.

100 of 129
3. To filter the data by mobile backend, select FIF_Technician. Note that this is not the mobile backend
that you created. It is a shared mobile backend that is populated with realistic data. If you look at the
mobile backend that you created, you'll see very little system analytic data.

4. You can drill further into user and session data in two ways. First, in the lower right corner, click
Sessions to open the Sessions analytics view.

101 of 129
5. Then, in the header area you only see 1 week of data. Click ALL to view the session count for all time.

The report shows a cumulative record of session activity. In the upper right, select All Backends to see
all the usage.

102 of 129
6. Here, you can filter and group data based on the mobile application or location of the user session.

From the Select a group by property drop-down list, select State .

7. To change the view, click the Bar graph icon in the lower right corner of the page.

103 of 129
Then, in the header area, click Session Duration to view details about session duration.

8. You can also drill further into the data by clicking your DEVELOPMENT menu and expanding the
Analytics menu option.

Click Users to view data about users.

104 of 129
Here you can see details about new and active users.

9. Click the ALL button again, and then explore the New Users and Active Users views, where you can
filter and group in different ways to understand the data.

105 of 129
Click quickly between the two views (New and Active) to see the subtle differences in the data.

10. Next, from your DEVELOPMENT - Analytics menu, select API Calls. Here again, API call data has
been generated to give you an idea of what analytics data would look like in a real environment.

106 of 129
platform or custom APIs. For this example, however, the sample data was populated against the
analytics collector (the Analytics API), so you can only see API calls for the analytics collector.

12. Use the drop down and switch back to your mobile backend (FIF_Technician_xx).

13. Then, from the Total API Calls drop-down list, scroll down and select Storage .

107 of 129
If you had created storage collections (which we did not) you would see API Response Time and API
Calls for the Storage APIs from any MAF application..

Test custom events using Postman (optional)


In this section you use Postman to add and send five custom events to your mobile backend. Then you go
into the Analytics dashboard and examine the events that were sent.

1. If not already started, start Postman. You can find it in the Chrome App Launcher, either on your
desktop or in your tool tray.

108 of 129
2. In the upper right of the app, your MCS environment should be showing and you should see the two
headers.

3. Now, you need to add one new headers to process the custom events.

Click the Headers tab and add the first new header and value below the two already there. This first
header tells MCS the content of the data sent.

Name the header Content-Type and set the value to application/json.

109 of 129
You can access the analytic API using the following URL. Copy and past it into Postman's URL box and
replace the MCS connection with your own.

https://<your_MCS_host>:<port>/mobile/platform/analytics/events (see the screen shots below to


understand where this URL can be found in MCS).

Then, on the left of the URL, use the drop down to set the operation to POST.

To find the Analytics URL, go back to the MCS API section and look at the bottom of the page for the
Platform APIs. Not all of them can be displayed at once, so on the far right, click the greater than sign
to reveal more of them.

On the far right, select the Analytics Collector.

110 of 129
Here is where you find the URL you can use to POST records to be viewed in the MCS analytics. You
can use this URL to access the analytics outside of MCS.

5. Now that you have the headers and URL set, add the custom event records to the body. Rather than
typing in all the event records, you can copy and paste them. In your labfiles directory, open the
/code/analyticEvents.txt. These are the five records you add to the body of Postman.

Select all the records and copy them.

111 of 129
6. In Postman, click the Body tab and click the raw radio button. Then, paste all the records.

112 of 129
7. Then click the Send button and you should receive a message stating that 5 events have been
accepted for processing.

113 of 129
8. Now, go back into MCS and examine the events that were logged against your MBE.

In your DEVELOPMENT menu, expand the Analytics node and select the Events menu option.

114 of 129
9. In the upper right corner, select your MBE from the drop down

Next, on the upper left, notice the Select an event drop down From the drop down, select any of the
events option (you may need to select the 1M, 3M or 1Y option to show enough days to see the
December 8th date. Select a different event to see the occupancies.

115 of 129
Test custom events using the MAF MCS Utility Application
(optional)
In this part of the tutorial is optional, you use a tester application to create and send custom events to your
MCS mobile backend. You then use MCS to view the resulting analytics. You must use the MAF MCS
Utility to complete this section of the tutorial.

1. If it is not already running, run the MAF MCS Utility Application.

116 of 129
2. Start the MAF MCS Utility Demo.

117 of 129
4. Select MCS Analytic API.

118 of 129
5. On the Analytics page of the tester, click the Sample tab and then create an event similar to the
following:

Event Name: Food Purchase

Product Id: 9876

Product Name: Bread

Unit Price: 3

Quantity: 6

6. Click Add Event to add the event to the queue and you'll see the product has been added to the event
queue.

119 of 129
7. Add another Food Purchase event. Use any details that you want and click Add Event.

120 of 129
8. Add a couple more events that use the Apparel Purchase event name. Use any details that you want
and click Add Event after specifying each event. The System Feedback section of the page displays
the status of the event.

9. Now that you have added several events, click Send Events and you'll see a events processed

121 of 129
10. Use the burger icon to get back to your DEVELOPMENT menu and find, then expand the Analytics
option.

11. Then click Events.

122 of 129
12. In the upper right corner of the page, under the user name, click the down arrow and use the filter to
find and select your mobile backend.

13. In the Select an event drop-down list to select mafmcsutility-apparel.

123 of 129
14. Use the Select a group by property drop-down list to group the events by ProductName.

All the apparel items you added will be shown. On the right, you see each product name and a
representing color on the graph. I've also just shown data for the current day.

124 of 129
15. If you added events for multiple products, click one of the products in the chart legend to turn off that
item in the chart. Click all but one to see that product only.

125 of 129
16. Use the Events drop-down list to change the events that you see in the graph. Select
mafmcsutility-food.

17. Set the Group by property to ProductName.

126 of 129
18. Just as you did before, deselect one or more items in the legend to remove them from the graph.

19. Click the Add Filter (plus sign) icon next to Filters.

127 of 129
20. Select ProductName as the property and then select one of the products that you used when you
created the event.

21. Click Done to apply the filter.

22. You can use this drop-down list to shape your display to show what you want.

128 of 129
About Oracle (http://www.oracle.com/corporate/index.html) Contact Us (http://www.oracle.com/us/corporate/contact/index.html)
Legal Notices (http://www.oracle.com/us/legal/index.html) Terms of Use (http://www.oracle.com/us/legal/terms/index.html)
Your Privacy Rights (http://www.oracle.com/us/legal/privacy/index.html)
Copyright 2017, Oracle and/or its affiliates. All rights reserved.

129 of 129

Potrebbero piacerti anche