Thursday, September 7, 2017

Oracle Mobile Cloud Service: team members accessing APIs

Oracle Mobile Cloud Service is setup around different personas. When you login to MCS you see a list of roles.

The Mobile App developer is the developer that is creating a mobile application and is using APIs that are exposed in MCS. The Service developer is the developer that creates the APIs, connectors etc.

This distinction is very useful: it helps in making sure the documentation is targeted to the right people and the content is organized in a way that makes sense for these different personas.

Sometimes, however, it does not work as well. As I discussed in an earlier post: the command line tools to deploy and test services is hidden in software that is targeted at mobile app developers.  In this post I want to discuss another use case that is not that obvious apparently: a service developer calling an API.

In our project we are creating APIs for several different mobile app developers. Before we publish an API and a mobile backend we want to test this mobile backend. We secured the APIs with security roles, because we want to make sure that APIs for internal use are not accidently exposed to external companies.  To be able to test the API, we had to assign the correct role to the team member. This is when the challenge started.

Assigning roles to users in MCS
There are two ways of assigning roles to users for MCS. The first method is using the MCS Mobile User Management, which can be accessed using the mobile portal ui:

Manage users and roles from the MCS portal

The second way is using the services dashboard, using the "Users" tab and clicking "manage roles" for a specific user:
Manage roles of a user using the "users tab" from the service dashboard

But before you can assign the role, you have to go to the user management part of the MCS and create a role in a realm. This is described in the documentation of MCS: "Set Up Mobile Users, Realms and Roles". It also describes naming conventions, for example for roles: 

"The naming convention for Oracle Cloud custom roles that represent MCS mobile user roles is: {serviceName}_MobileEnvironment_{rolename}. For example, for a role named “APIRole” in the environment with service name “poeo342ed” the custom role in Oracle Cloud would be poeo342ed_MobileEnvironment_APIRole." 

Then you can create a new user account for the tester and assign the newly created role to this user. (S)he then uses account after logging into MCS and changing the default password to test the API from postman, adding the username and password as Basic Authentication to the header of each call.

This all works very nicely. But we wanted to assign this role to ourselves. However, the users that were set up as team members did not show up in the MCS User management list of users. 

So I navigated to my services dashboard again and clicked on the tab "custom roles". Sure enough the role I just created was there, so I assigned my own user to the role and added my username / password to the Postman API call.
The result: "Unauthorized"


Users should not only be assigned to a role to access an API, they should also be part of the realm that is associated with the mobile backend. Unless, of course you use anonymous access, which does not work when you are securing your APIs with roles.
In our example we did not explicitly create a realm, so the mobile backend was associated to the Default Realm. We created the new tester in the default Realm, so this 'role' was automatically assigned to this user. The team members were not added to that realm and therefore did not show up in the list of users of the default realm.

We added the team members to the Default 'role', which corresponds to the realm in the mobile user management instance and voila! We can access the APIs :)

Role that represents the default realm in the mobile cloud service instance

Happy coding!

Sunday, July 23, 2017

MCS implementation: How to deploy your custom code with additional libraries

When implementing APIs that you have defined in Oracle Mobile Cloud Service (MCS), you don't want to reinvent the wheel.  That is why it is important to know how to deploy other libraries with your custom code implementation.

The custom code service that you use when implementing your APIs is backed by the following libraries:

  • Node
  • Request
  • Express
  • Bluebird
  • Custom code SDK
The internal code of MCS uses these libraries. These libraries (with the exception of the '.then' construct from bluebird) are not available for you in your custom code, unless you add them to your custom code zip file. So let's look at an example I ran into during the project, using bluebird.

Adding bluebird

A lot of the Platform APIs that you call from your custom code is executed asynchronously. These methods return a so called 'promise'. A common use case is to chain the calls, using a '.then' clause. in that case you don't need to add bluebird to your project. However, in our project we needed to join multiple asynchronous calls, not just chain them.  

An example: 

var productIds = req.oracleMobile.database.getAll([table_name], {fields: 'id'}, httpOptions);
var orders  = req.oracleMobile.database.getAll([another_table_name, {fields: 'id,name, productId'});

var Promise = require('bluebird');

Promise.join(productIds, orders).then(
            function (result) {
                //your code here
                //your error code here

Since this uses not just ".then" but also ".join" you need to add the required library to your javascript file (var Promise = require('bluebird');)

According to the documentation you should add bluebird to your zip file, however in our case it worked by just adding the ('require') statement. There is no need to add the bluebird library to the zip.

Adding other libraries

In our current project a custom implementation is depending on a barcode generator library. You can add this to the custom code zip file that is uploaded to MCS. Note that these additional modules are not shared across custom code modules and you can't install a module that depends on a binary (executable file) on the server.

To use the modules in your code you have to add it to the dependency list in the package.json file and run npm install.

Note: when you download the scaffolding code, MCS automatically creates a package.json file. This contains the version "1.0". This results in an error message, because npm uses semantic versioning.
Running npm install on this code will result in the following errors:

npm WARN Invalid version: "1.0"
npm WARN sales No description
npm WARN sales No repository field.
npm WARN sales No README data
npm WARN sales No license field.

You can solve this by changing the version to 1.0.0. See for more details:

In the rest of this blog, I assume you have setup the MCS custom code testing tools.
In that case you need to take the following steps to deploy the custom code with the additional libraries to MCS:

  1. Edit package.json
  2. Run npm install
  3. Test the code locally with mcs-ccc and mcs-test or postman (or cURL)
  4. Deploy the code with mcs-deploy

1. Edit Package.json 

In our case the package.json looks as follows:
  "name" : "sales",
  "version" : "1.0.0",
  "description" : "The API that facilitates ordering tickets based on a barcode.",
  "main" : "sales.js",
  "dependencies": {
    "bwip-js": "1.4.2"
  "oracleMobile" : {
    "dependencies" : {
      "apis" : { },
      "connectors" : { }

2. Run npm install

Navigate to the root directory of your custom code API and install the npm modules you need in your project. In this case the module name is bwip-js. 
  npm install bwip-js
 npm install

3. Test the code locally

Make sure the code is working as expected before uploading it to MCS. This is described in a previous post.

4. Deploy the code to MCS

You can run the deployment as usual, from the MCS testing tools: 
mcs-deploy toolsConfig.json --verbose

Monday, July 17, 2017

Testing, packaging and deploying custom code using MCS custom code test tools

In a previous post I have described how to setup your MCS custom code test tools. In this post I will describe how to test, package and deploy your custom code using these tools. You should have installed the MCS custom code tool and updated the toolsConfig.json file with the correct url, mobile backend id and OAuth data.

Test your code

Once you have implemented your custom code, you want to test it. Of course you can test it by uploading the implementation into MCS. However, it is much better to test it locally and make sure it works, before you upload it to MCS. Since your custom code probably uses MCS platform APIs, it is convenient to use the mcs-ccc as a local 'container'. Note that when you run the test, it will call the platform APIs in your instance in MCS, so if you insert data in the database, it ends up in the cloud, even though you are running the code locally!

Components of the MCS testing tools and communication with MCS instance

You can either run the tests that are defined in the toolsConfig.json or you can run tests in Postman or cUrl.

When you want to run the test from Postman or cURL, simple point to localhost:4000 instead of the  MCS path. Don't forget that the mcs-ccc runs on http, not https.

The correct values for the port can be found in the output of the console when you start mcs-ccc in verbose mode.

Instead of running tests from Postman or cURL, you can also run tests that are automatically generated in toolsConfig.json:
  1. Run npm install
  2. Run mcs-ccc toolsConfig.json --verbose
  3. Open a separate command line
  4. Run mcs-test <path to toolsConfig.json> <testname> --verbose In this case mcs-test toolsConfig.json getProductsprices --verbose
  5. This returns the response in the command line
If you have a template parameter in your call, you have to hard code this in toolsConfig.json and run the test (you can spot these by looking for "PARAMETER").

Advantages of this approach are that the test is automatically generated. The disadvantage is that none of the results are validated. Last but not least, you have to hard code the parameters. For that reason we usually run real system tests in Postman. The testing tool can help the developer in the beginning, to make sure the code that is uploaded will run. It is more for 'smoke-testing' than for real testing of your code.

Package and deploy your code

Once you are ready to package and deploy your code to MCS, you can use mcs-deploy:

  1. Navigate to the package
  2. Run  mcs-deploy toolsConfig.json --verbose
  3. Enter the username and password when prompted
You should see the implementation in the MCS API implementation page.
sales 1.0 added as default implementation after running mcs-deploy

Sunday, July 16, 2017

Set up your MCS (development) environment: database creation policies

As mentioned in a previous post (Setup your MCS development environment: MCS custom code test tools, MCS is a cloud native platform that offers several platform APIs. One of these APIs is the database API.

It consists of two parts: 
  1. Database access. This is used by mobile applications and can only be executed from within custom code
  2. Database management. This allows you to create tables, remove tables etc. 
The first question you might ask is 'why on earth would I want to create tables in MCS, don't we have database cloud service and other sources for that?!?' 

Let me start by saying I agree with that. However, in this project we are starting with a simple API and we want to make them available as quickly as possible. The data will move (eventually) to the proper back-end system and in MCS we will use a connector to access this data that will be exposed on the Oracle Service Bus. However, at the moment the system does not contain the data and the Oracle Service Bus is not exposing services for this particular system yet. 

To save cost, minimize complexity and maximize time to market, we decided to use the database platform API. 

You can create database tables on the fly, using the Database_CreateTablesPolicy environment setting. This will cause a table or a column to be added or resized when you insert a row using custom code if it does not exist yet.

According to the documentation the following values can be used: 
  • allow: enables calls from custom code that perform implicit operations; 
  • explicitOnly: disables implicit calls from custom code;
  • implicitOnly: only implicit creation of database tables using custom code is allowed, the database management api can't be used;
  • none: curtails implicit calls from custom code.
This documentation is a bit unclear so let me elaborate on that:

ValueUse API in custom codeUse implicit calls in custom code 

These values are used to control the privileges for custom code, it does not control calling the database management API from outside of MCS (postman, curl etc).

There are several disadvantages to this approach:
  1. You can accidentally end up with multiple columns because of spelling errors ('address' and 'adress' for example);
  2. When unit testing custom code with 'faulty' data, instead of failing with the error you would get into your production environment (which is recommended by Oracle, to switch it off in production) you create new columns and the test fails with a different error (if it fails at all);
  3. We use the environment that we are working as a production environment. 
We decided to use "explicitOnly" and use the REST APIs to create, update and remove tables with Postman. However when I used one of the APIs I got the following response:

    "type": "",
    "status": 403,
    "title": "Forbidden",
    "detail": "403 - Forbidden",
    "o:ecid": "005L4J3QBg63j4C_nDWByZ0000x^0000yX, 0:3",
    "o:errorCode": "MOBILE-15229",
    "o:errorPath": "/mobile/system/databaseManagement/tables"

When creating a database table from outside the custom code (using the REST API and postman for example), you  need to call it with a user that has the role Mobile_DbMgmt. Unfortunately, there is no easy way to check your role from inside MCS, as can be seen in this picture

No easy navigation to inspect or change your role from within MCS
So, I opened a new tab and navigated to and signed in again. This brought me to my service dashboard, and offers the opportunity to manage users, using the "users" button in the upper right hand corner.
Click users and find yourself. Check your roles and add [environment name] Mobile Database management to the roles.

Now I was able to create the table 😊.

NB: According to the documentation the default value is 'allow'. In our instance the value was set to 'explicitOnly', so make sure you check the value when you use the database platform API. 

  1. Login to MCS
  2. Click on "Administration"
  3. Scroll to the bottom of the page
  4. Click Export and save the policy file.
  5. Edit the policy (if needed)
  6. Upload
The setting is applied instantly.

Thursday, July 13, 2017

Setup your MCS development environment: MCS custom code test tools

Oracle Mobile Cloud Service is a so called 'cloud native' product in the Oracle PaaS offering: it runs in the Oracle Public Cloud and there is no on premise variant in the Oracle Fusion Middleware stack.

In our current MCS project we have set up a number of things to make sure that we can achieve the same quality in our software development lifecycle (sdlc) as we have in our 'traditional' projects. One of the measures is the ability to run unit tests locally before deploying the code.

MCS is a cloud service that is based on node.js. It offers a number of platform APIs that you can use when creating custom APIs for mobile developers. The figure below shows these platform APIs: storage APIs to store files, Database APIs to store relational data, notifications etc. When you write a custom API, you use the platform APIs and you call connectors in the implementation.

When you use a tool like Netbeans (or any other javscript tool), these platform APIs are not available, which makes it hard to test your code without installing it on MCS.  To solve this problem, MCS offers MCS custom code test tools.

Description of intro-arch.png follows
Architecture of MCS (from the documentation)

MCS custom code test tools

It took me a while to discover the MCS testing tools, because I am a so-called 'service developer'. The testing tools are located in the SDK which is targeted at the role 'mobile app developer' who use, not build,  the custom APIs. (Hint @Oracle: please make the MCS tools available in the implementation page for the API). 

  • local version of node.js (6.10) and npm 
  • An account on Oracle Mobile Cloud Service (MCS) with role 'developer'
  • An API scaffolding to test the setup
  • A development tool of choice (in this case Netbeans)

The following steps need to be taken to go through the entire lifecycle: 
  1. Download the MCS custom code test tools
  2. Install the MCS custom code test tool on your machine using npm
  3. Setup your mobile backend for testing
  4. Set the custom API up for testing
  5. Run it locally (yay!! 😊) with the MCS custom code test tools

Download the MCS custom code test tool

1. Navigate to the MCS download page.

NB: don't use the downloal link on the applications page, it will bring you to a download page, without the mcs-tools folder!!

Don't click on this link!!

2. Select any SDK (every SDK contains MCS custom code test tools), unfortunately there is no separate download for service developers and download it (hint @Oracle)
3. Extract the file to a location of choice. Navigate to the mcs-tools folder and extract this folder into the location of choice. Note that the mcs-tools folder contains the mcs-tools folder. This is the folder you need. 

SDK files

mcs-tools directory containing mcs-tools directory

Install the MCS testing tool

  1. open a terminal session and navigate to the deepest mcs-directory: mcs-tools
  2. run npm to install the tool on your machine
  3. test the installation, it my case it returns 17.2.5
cd {sdk path}/mcs-tools/mcs-tools
npm install -g
mcs-test --version

Setup your mobile backend for testing

  1. Create a new API that will act as a proxy for your local tests by adding the OracleMobileAPI.raml in the "Create API" dialog. 
  2. Add the implementation by uploading the "" to the implementation of the API.
  4. Switch off "Login required" in the security tab. 
  5. Add the API to the mobile backend. 

Setup your custom API for local testing

  1. navigate to the root folder of your local API implementation (or the scaffolding if you did not create an implementation yet)
  2. run npm install
  3. update the 'toolsConfig.json' file and enter the mobile backend id, the anonymous key and the OAuth data that are used to deploy to MCS. They can be found in the mobile backend settings page. For obvious reasons, I don't show the details here 😉

Run it locally

1. Open a terminal
2. Run the mcs-ccc with the correction options (you can also use --debug to debug in Chrome)

mcs-ccc toolsConfig.json --verbose

The result is:
C:\Users\ldikmans\Documents\api-straat\product\productapi> mcs-ccc .\toolsConfig.json
Warning: Configuration property "proxy" is undefined
To display help and examples associated with warnings, use the --verbose option

Ping OracleMobileAPI to verify that OracleMobileAPI-uri and authorization are correct.
OracleMobileAPI ping succeeded!
The Node server is listening at port 4000

The downside of this approach is that you have added a 'foreign' API to your mobile backend. You can handle this in two ways, depending on how many environments you have:
  1. Remove the OracleMobileAPI from the mobile backend as soon as you publish it
  2. Remove the OracleMobileAPI from the mobile backend in your test or production instance. 

In the next blog I will describe how you can test, package and install your custom code into MCS, using 'mcs-tools'. 

Happy coding 😊

Friday, December 2, 2016

Securing Cross-Site Requests to MCS APIs

When your Oracle Mobile Cloud Service APIs are being accessed by a remote server, it is important you manage cross-origin resource sharing (CORS) We ran into this issue when we were building the solution for the Oracle cloud day. The MCS APIs were accessed by a Web Application that was hosted on a different domain, not on our Oracle PaaS domain. When calling an API from the application, we received the error:

XMLHttpRequest cannot load: [request url]. Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin [origin domain] is therefore not allowed access. The response had HTTP status 401.

You can either disallow CORS altogether, or whitelist specific sites.  This is done by setting a property in Security_AllowOrigin.

An example of the property can be seen below:


This means that requests coming from from port 80 are allowed.

More information can be found in the Using Oracle Mobile Cloud Service, Part II: Setting up Mobile Apps, Chapter 5. This chapter explains in detail the pattern matching that is applicable.

To summarize:

1. Login to MCS
2. Click on "Administration"
3. Scroll to the bottom of the page
4. Download
5. Edit or add the property
6. Upload

Administration page in MCS

The setting is applied instantly.

Saturday, November 19, 2016

Editing Application Roles in Oracle Process Cloud Service

The other day I was working on my demo of Oracle Process Cloud Service (PCS) for UKOUG Apps 2016.  After creating the application, I wanted to start working on the process. My use case fits an out of the box pattern nicely, so I started with "Form Approval with Integration Pattern" and PCS created a default process for me; with two swimlanes and a number of activities. The resulting process is shown below.

Process created based on "Form Approval with Integration Pattern"

Every PCS application is provisioned with three standard roles:
  1. Process Owner. Users with this role have access to process activity history, can take actions, alter the process flow etc. Process owners typically manage deployed business processes and use metric analysis tools such as dashboards to monitor the business process. 
  2. Process Reviewer. This role gives access to process activity, but process reviewers can not take actions on tasks or alter tasks flows.  Process reviewers are not participating but typically responsible for reporting on current process instance status. 
  3. Analytics Viewer. assigned this role can create and view business analytics dashboards associated with the specified application.
In this example, I don't want to use these global application roles, I want two other roles:
  1. Expense Submitter. An employee that submits an expense because of traveling or other reasons
  2. Expense Approver.  The manager of the employee that approves the expense items on the expense report.
You can edit the swimlane by clicking on the pencil icon next to the swimlane and select a role. 

Assigning an application role to a swimlane

I did not see the role I was looking for in the list, but that is not a problem: I can add an Application Role to the list by clicking the "+" icon.

So far so good. I added a role "Expenser" and assigned the first swimlane to it. Then I did the same for the second swimlane: I edited the swimlane and added a new role "Expense Approver".

Unfortunately, I made a mistake....

Editing the role

I wanted to call the first swimlane/role "Expense Submitter", remember? I accidentally named it "Expenser". I want to change this name, because I don't like it.

My first attempt is in the current screen. I have the pencil next to the swimlane, so probably I can edit the role here, right? Wrong.
It will bring me back to assigning a role to a swimlane. I can assign it to a different role or a new role. But not edit it. 
So let's look at another option, there is another place to manage roles, on an application level.

Click on the tab "Application Home". This will bring you back to the Application Home. When you click on the "Organisation" link, you will get a pop-up that allows you to delete or add roles. However, you can't edit roles. 

Because I really wanted a new name, I deleted the role and added a new one.

Remember, adding a role will not only impact the swimlane, but also adds an application role for the application. This role will be available for all processes in this application.
Application Home with Dialog to add and remove Application Roles

Of course this makes you wonder what happened with the swimlane that was using the role we just deleted?

Let's see:

Unassigned role after deleting a role from the application

It results in a swimlane with a 'Unassigned role'. So I assigned the newly created role and continued with implementing the process. 


From a functional perspective, the ability to create a process based on a pattern is very powerful. The responsiveness of the process composer is very good. It is a pleasure to work with it, it feels like a modern application. However from a user experience perspective, I see plenty of room for improvement: 
  1. Navigation
    • Buttons versus links. Why is 'Organization' a link, not a button at the right hand side of the Application Home? Why is closing the application implemented with a link and not a button? There are multiple levels of navigation, and it is not always clear why which pattern is used for what level.
    • Moving from the Workspace to the Process Composer. It is unclear to me how to get back to the workspace once you have entered the process composer, apart from saving the link as a favorite in your browser.
  2. Internationalization
    • Some concepts are translated, some are not. 
    • Consistency. It seems that in the Dutch version, a project role is edited (see illustration), in the English version the dialog is called "edit Application roles" (the correct concept) . 
  3. Concepts. 
    • The name of the Swimlane is the same as the role you assign to it. The role is defined on an Application Level, not a process level. This is not clear from the way it is presented to the user and will only occur to the process developer, once (s)he will develop more than one process
    • It is not possible to edit the name of the role. You have to delete it and then add a new role. This will result in swimlanes with unassigned roles in existing processes. 
    • It is unclear for the process developer what a role entails, the pop-up window does not show where the role is used or what permissions are associated with it
    • By default the submitter of a form is defined as the process owner. In most cases this will not be the case: the receiver of the form is typically the process owner, who will approve or deny the request and has the ability to change the process etc.
This is not an extensive list, but just the issues I ran into while trying to change the name of a process role after having created a process based on a pattern. 

From a functionality perspective PCS is becoming more and more powerful. However, it is very important to keep the User Experience that comes with the functionality consistent within itself and with the other Oracle products as well. Including the Oracle Applications. Because for users, the difference between PaaS and SaaS is inconsequential, they just use the tools. In the end, to users it does not matter whether Oracle calls these tools a 'Platform' or 'Software'. What matters is that they are productive and that the tools are easy to understand. 

I think it is time that Oracle repositions the Oracle Usable Apps group to a higher level to include the PaaS products. And please, as a first recommendation from a UX perspecive, let me edit roles 🙏