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

No comments:

Post a Comment