Putting It All Together

1. Click Development.

   

2. Click User Management.

   

3. Click Realms in the left navbar to take a quick look at the user realms page. A realm partitions users in an environment (in this case, the Development environment). A realm called Default 1.0 is created by default.

   

4. Click Roles in the left navbar and then click New Role.

   

5. Enter FIF_Technician in the New Role dialog and then click Create.

   

In this step, you'll create the FIF Technician user. You'll use this user's credentials to login in to the mobile app itself and also to test the API endpoints.

1. Click Users in the left navbar and then click New User.

   

2. Enter the following in the Create User dialog:

   • Enter a user name. The user name and passwords must be unique. These are not are not case-sensitive, meaning that MCS views JJones as the same as jjones.

   • Enter an email address. For added security, Oracle Mobile Cloud sends users a confirmation email that contains a temporary password.

   • Enter the name by entering first and last names.

     

3. To give this user access permission to the mobile app's data, choose FIF_Technician role and then click Create.

   

   By default, MCS creates the users in the Default 1.0 user realm.

   

   After you create a user, Mobile Cloud Service sends you a confirmation email with the subject line, New Account Information. This email includes a temporary password. Keep this email close at hand, as you'll need the password to log into the technician app. You'll also need it to test a custom API.

   

1. Click Storage.

   

2. You don't have any collections created for this mobile backend, so click New Collection.

   

3. Complete the New Collection dialog as follows:

   1. Name the collection FIF_UserData.

   2. Choose User Isolated so that customers cannot override each other's images when they upload.

4. Click Create.

   

5. Now, you're going to assign the access permissions to this collection so that it can be used by the mobile app. In the Properties page (which opens by default), give the FIF_Technician role Read/Write access to incident report images by selecting FIF_Technician in the Read-Write field.

   

6. The Make this collection available when the client is offline option makes the data available offline. This option is selected by default. Accept this setting.

1. Click Development.

   

2. Click APIs.

   

3. Click New API.

   

4. Drag the FIF_incidents.raml file into the upload field. Although you're using a RESTful API Modeling Language (RAML) document in this tutorial, you don't need to know RAML to use the API Designer. The API Designer creates a RAML document for you.

   

5. In the Short Description field, enter a description, like Fix it Fast Incident Reports API and then click Create.

6. In the Designer page, click Security.

   

7. In the API Access section, add FIF_Technician to the Roles field to allow your technician mobile user access to the endpoints.

   .

8. Click Implementations in the left navbar.

   

9. Click Upload an Implementation archive and then browse to, and select, the fif_incidents.zip file.

   

10. Click Save.

1. Click Development.

   

2. Click Mobile Backends.

   

3. Choose the FIF_Technician mobile backend and then click Open.

   

4. Choose APIs from the left navbar.

   

   Right now, the FiF_Technician mobile backend isn't using any custom APIs.

   

5. To open the API catalog, click Select APIs.

   

6. In the API Catalog, click FiF Incidents.

   

   After you select the FIF Incidents API, it appears in the Selected APIs panel.

   

In this step, you'll get acquainted with the MCS API explorer, which lets you test endpoints and see the returned results. Normally, you'd create a connector to get application data, but for this tutorial, you're going to add a table called FIF_Incidents that contains the incident reports by testing the POST /populate endpoint. Call this endpoint if you need to reset the data.

To seed the data:

1. Return to the FiF Technician mobile backend page by clicking FiF_Technician 1.0 at the top of the page.

2. Select APIs from the left navbar.

   

3. Click the FiF_Incidents API.

   

4. In the Endpoints page, click the POST /populate endpoint.

   

5. Enter your MCS credentials.

   

6. Click Test Endpoint.

In this step, you can view methods and test the endpoints of the FiF Incidents API. By testing an endpoint, you can find out if it can return requests from a mobile app.

1. Click the FiF_Incidents API.

   

2. In the Endpoints page, click Default Test Credentials and enter the username and password for the user to whom you assigned the FIF_Technician role. You'll use these credentials for testing the calls that are made from the FIF Technician app. You'll configure and run this mobile app later.

   

   The FIF_Incidents API uses the following endpoints. You can test each of these using the Endpoints page. Enter the appropriate parameters for each resource and then click Test Endpoint.

   Method	Endpoint	Description
   GET	/mobile/custom/FIF_Incidents/incidents /mobile/custom/FIF_Incidents/incidents?customer={customer_username} /mobile/custom/FIF_Incidents/incidents?technician={technician_username}	Gets all of the incident reports (filtered by customer name or technician name).
   POST	/mobile/custom/FIF_Incidents/incidents	Submits a new incident report.
   PUT	/mobile/custom/FIF_Incidents/incidents	Update an existing incident report (based on ID).
   GET	/mobile/custom/FIF_Incidents/incidents/{id}	Get a single incident report by ID.
   GET	/mobile/custom/FIF_Incidents/directions?origin={o}&destination={d}	Returns driving directions.

3. Test GET /incidents:

   1. Go to the Get /incidents endpoint.

   2. Click Test Endpoint.

      

   3. Take a look at the HTTP 200 (OK) response. Click Test Endpoint a few more times.

      

4. To test the Google Maps API, select the GET /directions endpoint.

5. In the Parameters section, enter the following addresses:

   • origin: 200 Oracle Parkway Redwood City, CA 94065

   • destination: 20883 Stevens Creek Cupertino, CA 95014

     

6. In the Response section, take a look at the JSON returned for a 200 response.

   

7. Return to the FiF Technician mobile backend page by clicking FiF_Technician 1.0 at the top left of the page.

   

8. Choose Diagnostics. When you first created the mobile backend, the Diagnostics page had no data. Because you have tested some endpoints, MCS can graph the API calls.

   

9. In the Overview page, click Requests.

   

10. In the Requests page, click 2xx and then de-select 4xx and 5xx (which are selected by default) to enable the page to display only the 200 (Success) messages.

    

11. To see more details about the request, click a timestamp.

    

12. Take a look at the message details. These include:

    • The request details, such as the response code.

    • The mobile backend that made the request.

    • The API, its version number, and the method (such as GET or POST).

    • Performance data, such as the overall time for the request, the actual time servicing the request.

    • The Correlation ID, which associates log messages to a specific API request. Clicking the Request Correlation ID in the message details enables you to view log records from the API request history.

      

The Database Management API is a platform API that lets you curate database tables. In this step, you use the Database Management API explorer to see the rows and columns of the FIF_Incidents table as a JSON object. The explorer that you use in this step is similar to the ones provided for the other MCS platform APIs. Because the Database Management API is used by administrator-level users, you must use your MCS user name and password to test its endpoints instead of the FIF Technician credentials that you use to test the FIF_Incidents API endpoints.

1. Click Development.

   

2. Click APIs.

   

3. At the bottom of the page, expand Platform APIs and then click Database.

   

4. From the list of endpoints, choose GET /tables/{table}.

   

5. Enter FIF_Incidents as the table name.

   

6. Expand Authentication. Enter your MCS user name and password and then click Test Endpoint.

   

7. Take a look at the returned JSON.

   

   The returned JSON looks like the following:

   {
     "name": "FIF_Incidents",
     "primaryKeys": [
       "id"
     ],
     "requiredColumns": [
       "id"
     ],
     "columns": [
       {
         "name": "id",
         "type": "decimal"
       },
       {
         "name": "phone",
         "size": 266,
         "type": "string"
       },
       {
         "name": "title",
         "size": 398,
         "type": "string"
       },
       {
         "name": "technician",
         "size": 258,
         "type": "string"
       },
       {
         "name": "status",
         "size": 256,
         "type": "string"
       },
       {
         "name": "address",
         "size": 299,
         "type": "string"
       },
       {
         "name": "priority",
         "type": "integer"
       },
       {
         "name": "imageLink",
         "size": 274,
         "type": "string"
       },
       {
         "name": "notes",
         "size": 615,
         "type": "string"
       },
       {
         "name": "customer",
         "size": 265,
         "type": "string"
       },
       {
         "name": "createdBy",
         "size": 80,
         "type": "string"
       },
       {
         "name": "createdOn",
         "type": "dateTime"
       },
       {
         "name": "modifiedBy",
         "size": 80,
         "type": "string"
       },
       {
         "name": "modifiedOn",
         "type": "dateTime"
       }
     ]
   }

To enable the mobile backend to act on behalf of the mobile app, you need to update the app's configuration with the values for the application key, the mobile backend's base URL, the mobile backend ID, and the anonymous key that displays in the mobile backend's Settings page. MCS generated these values when you created in the FIF_Technician mobile backend in Setting Up the Mobile Backend for the FIF Technician App.

To do this:

1. Unzip FixItFastTechnicianApp_v1.0.zip.

2. Start Android Studio.

3. From the Quick Start menu, choose Import Non-Android Studio Project.

   

4. In the Select Eclipse or Gradle Project to Import dialog, navigate to the FixItFastTechnicianApp project and then click OK.

   

5. Wait for Gradle to build the project.

6. In the Project tree, open app > src > main > assets > oracle_mobile_cloud_config.xml.

   

7. Refer to the Settings page of the FIF_Technician mobile backend to update the following elements in theoracle_mobile_cloud_config.xml file:

   • <appKey>: Enter the Application Key that is displayed in the Client Application section of the mobile backend's Settings page. For example, enter <appKey>d91cc5ea-bada-48a9-a28e-93e7520b64e</appKey>.

     

   • <baseURL>: Enter the URL for the FIF_Technician mobile backend that's displayed in the Environment Details section of the mobile backend's Settings page. For example, enter <baseUrl>https://example.com:7001</baseUrl>.

   • <mobileBackendID>: Enter the mobile backend ID for the FIF_Technician mobile backend. For example, enter <mobileBackendID>ceff19d8-e1c7-422a-acfa-671ff5f3497</mobileBackendID>.

   • <anonymousKey>: Enter the Anonymous Key for the FIF_Technician mobile backend. For example, enter <anonymousKey>TU9CSUxFTEFCMklERE9NQUlOX01PQklMRUxBQjJERVZfTU9CSUxFX0FOT05ZTU9==</anonymousKey>.

     

8. Click the Sync Project with Gradle Files button in the tool bar.

   

9. Click the Run button in the tool bar.

   

In this step, you'll launch the FIF Technician mobile app to see the custom code calls in action.

1. Open the FiF application on a simulator or device.

   

2. Login as the FIF_Technician user.

   

3. View the incident reports.

   

4. Open an incident report and take a look at the Details page.

   

5. Take a look at the customer sticker.

   

6. Re-prioritize this incident and then click OK.

   

7. Click Directions.

   

8. Update the incident report with a note. Click POST.

   Note: To retrieve driving instructions, you must enable GPS on your phone or emulator. If a driving route is not available from your current location, or GPS is not activated, then you will see the Directions Unavailable message. You can also return driving directions using the Endpoints page described in Testing the Endpoints. To do this:

   1. In the Endpoints page, click POST /incidents.

   2. Click Use Example.

   3. Replace the address in the sample JSON with a location near you and then click Test Endpoint.

      { 
         "title": "Water heater is leaking",
         "customer": "Lynn Smith",
         "address": "475 Sansome Street, San Francisco, CA 94111",
         "phone": "(555) 212-4567",
         "technician": "jwhite",
         "status": "Open",
         "notes": "lynnf|2015-05-01T21:00:17.564727+00:00|Initial incident report description",
         "priority": 1,
         "imageLink": "http://link.to.storage"
      }

9. Click Activity. In the Activity page, update the incident report with a note. Click POST.

   

10. Return to the Details page and then click the Status field. Use the Set Status dialog to change the incident report's status. Click OK.

    

In this step, you'll revisit MCS diagnostics. Before, you viewed logging data generated when testing the endpoints using the API Designer. This time, you'll review the logging for calls made from a mobile app to MCS.

1. Click Diagnostics.

   

2. In the Overview page, click Requests.

   

3. In the Requests page, click 2xx and then de-select 4xx and 5xx (which are selected by default) to enable the page to display only the 200 (Success) messages.

   

4. For any request to the FIF_Incidents API or to the connector, click a time stamp to drill down to the message details.

   

5. Take a look at the message details for the request. The Overview tab, which appears by default, displays the 200 (Success) response code, and notes that the FIF_Technician mobile backend made the request. This page also shows the API that made the call (such as FIF_Incidents), its version number, the method (such as GET or POST), and any request parameters that were sent with the request. It also includes the name of the mobile user who logged into the FIF Technician mobile app and performance data, such as the overall time for the request, the actual time servicing the request in the custom code, and details about the number of bytes of returned data.