Chapter 1. Projects, Apps, and Services

1.1. Projects

1.1.1. Overview

The projects section allows you to create and manage projects. Once a project has been created, multiple Apps can then be associated with those projects. If you have an existing App, the 'Import' feature can be used to import it into the Platform.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Domain — Project (View and Edit)

1.1.2. New Project

A Project consists of Apps for different platforms, and a Cloud App that they talk to.

Note

Although a new project generally consists of one Client App and a Cloud App for it to communicate with, multiple Apps can be added to any given project.

1.1.2.1. Client Platforms

All Projects have a template as an initial starting point. The following example describes the makeup of a template:

  • A single App that uses the technology Cordova and a Cloud App that uses the technology Node.js.

1.1.3. Import

As well as creating Apps, existing Apps can be imported into the Platform. When importing an App, you have the choice to either create a new project and add the App to it, or to simply add the App to an existing project. There are a number of different App types that can be imported into the Platform. These include Native iOS, Native Android, PhoneGap, Basic Web App, and Advanced Web App. There are also a number of different ways in which an App can be imported to the Platform. These include :

  • Cloning an existing Git repo
  • Uploading a Zip
  • Creating an App with a blank repo, and then pushing the code there
  • Not importing source, but integrating RHMAP SDK

Step by step instructions will be provided, informing users of how to successfully import their Apps into the Platform. These steps will differ slightly depending on which import method was selected. For example, only the 'Cloning an existing Git repo' option has instructions on how to clone Git repositories.

1.1.4. Apps, Cloud Apps & Services

The Apps, Cloud Apps & Services section allows for the managing of Client Apps and Cloud Apps within a project. Here, new Client and Cloud Apps can be added to a project. Cloud Apps serve as a gateway between the Client App and the cloud back-end storage and services.

1.1.4.1. Apps

A project can consist of multiple Apps. In general, a project will consist of at least one Client App, along with a Cloud App for it to communicate with. Multiple Apps and Cloud Apps can be added to a project. When adding a Client App, Apps can be created based on a number of Native or Hybrid templates. Multiple Cloud Apps can also be added to a project. As mentioned above, an existing App can also be imported into an existing project.

1.1.4.2. Cloud Code Apps

Cloud Apps allow developers to link their Apps to back-end cloud storage. It allows for extensive user management, where users can manage mBaaS Services such as online data storage, web based email services, push notifications, and more. Client Apps will communicate with Cloud Apps to avail of this functionality. For example, since all functionality created in your cloud can be accessed via a simple API call, you can make use of a cloud cache for performance so less work needs to be done by the device itself.

1.1.4.3. Services

External mBaaS Services can be added to a project in order to provide increased functionality. Services can be added to a project in the same way as a Client App or mBaaS Cloud Instance. Cloud Instances make calls to these services to avail of increased functionality such as PayPal. Only a user with the Service Administrator role can provision mBaaS services. When a Service Administrator is creating a service, they have the option to make the service globally available to all projects. If it is made globally available, users with the Developer role can select it for inclusion in their project.

1.1.5. Add Apps to a Project

You can add as many Apps to a Project as you like - you have three options to choose from:

1.1.5.1. Create a New App

Creating a new App allows you to select template to base your new App on - alternatively, if you have an existing App, you may want to select the "Import Existing App" option

1.1.5.2. Import Existing App

If you have an existing App, you can select this option and we’ll guide you through importing and integrating your existing Apps with the Platform. You’ll need to select an appropriate App Type and make sure the pre-requisites are met - the App Studio will help guide you through the process.

1.1.5.3. Clone Existing App

If there’s an App in this (or another Project) that you’d like to clone, select this option. You’ll be asked to give your cloned App a new name. Depending on the source App, you may also be presented with some additional choices in terms of cloning depending on the source App.

Some Apps can have their types changed while being cloned, and other Apps can share their Git repositories with existing Apps. We recommend that Apps have their own dedicated Git repository, but there are some instances where it’s desirable to share Git repositories between Apps (for example, where a Basic Web App and a Cordova App share extremely similar source) - in these cases, Apps can share repositories and choose to elect folders within a shared repo to be used for Building, Previewing and Deploying.

1.1.6. Connections

The connections section provides an overview of Binaries built in the selected project, along with running Cloud code. A project contains both Client Apps, and Cloud Apps. A Connection dictates which Cloud Instance a Client App points towards. A connection will point towards a particular Cloud App in a given environment. The Dashboard provides an overview of connections that are present in all environments. From the dashboard, users can see how each Client App is connected to a Cloud Instance. Connections between Client Apps and Cloud Apps can be reconfigured or disabled as often as you like.

1.1.6.1. SDK Config

When a connection between a Client App and a Cloud Instance is created, an SDK configuration file is generated. Selecting the SDK Config option displays this config file. The contents of this file can be copied and pasted into your Client Apps fhconfig.json file in order to instruct the Client App to use that particular Connection.

1.1.6.2. Reconfiguring a connection

Connections can be reconfigured to allow a Client App to communicate with a different Cloud Instance. Cloud connections are refreshed by Apps upon startup.

1.1.6.3. Disabling a Connection

This removes the connection between a Client App and a Cloud Instance. This may be necessary if a new App has been added to a project and an update is required. Disabling a connection can cause a Client App to stop functioning. It is possible to send a message to clients informing them of a connection being disabled.

1.1.7. Git QuickStart

The Git QuickStart page shows how to access Client and Cloud code of an App on your local system by using Git. To access your project from your computer, you must first clone the repository. Cloning a repository creates an exact copy of an existing repository. All versions of all files in project are pulled down when a 'git clone' is performed. However before you can clone a repository, you need to upload your SSH Public Key. Once a Public Key has been uploaded, repositories can be cloned at will.

For more information regarding cloning a Git repository, see the Git Documentation on Getting started with Git.

For a more in-depth list of useful Git commands, see Git Reference.

1.1.8. Resources

The Resources section shows resource usage, such as CPU usage, Memory usage & Disk usage, for all Apps in the Project across all environments. If an App is not deployed in a particular environment, no resource usage will be shown for it. The status of deployed Apps can be managed from this screen as well. For example, if a particular App is showing high memory usage, it can be stopped. Resource graphs are based on live data, and as such may take a while to show trends while data is fetched periodically.

1.1.9. Lifecycle Management

A Project typically starts as a single App (for example, a Cordova App) and a Cloud App (for example, Node.js Application). As a Project progresses, it goes through various stages, that is, a Project Lifecycle. Every Project moves at a different pace, and grows & varies in composition over time. The goal of the Lifecycle Management Dashboard is to make this process easier for both the developer(s) and the project manager.

The Dashboard provides a snapshot view of a Project at the current point in time. All Apps are represented by a row on the dashboard. Each Environment corresponds to a column on the dashboard. This grid can give a quick overview of the stage that each part of the Project is in, without having to consult with each team member.

If an App has been built, the most recent build will be shown in the column that represents the Environment it is targeting a Cloud App in. The App binary can be downloaded from here, or rebuilt from a different git branch or tag. The 'Promote' option is a shortcut to rebuild the same code, but connect it to a different Cloud App Environment.

If a Cloud App has been deployed, the most recent deploy details and status will be shown in the corresponding Environment column. The Cloud App code can be deployed (or redeployed) to any available Environment. The 'Promote' option for Cloud Apps is a shortcut to deploy an already deployed git branch or tag to a different Environment.

Note

Any App binary builds done outside the platform will not be reflected on the Lifecycle Management Dashboard.

1.1.10. Forms

The Forms configuration page allows users to both associate Forms and Themes with a Project, and also configure Client Side AppForms settings. Users can manage settings relating to Camera Settings, Submissions, Admin Users, Client Logging, and Cloud Logging.

Submissions associated with a project can also be viewed from this page.

Note

If a user does not have sufficient privileges, they will not be able to view submissions. For more information regarding user roles, see the Administration Documentation.

1.1.11. Reporting

Note

The Reporting data is generated once per day.

The reporting section offers high level graphical representation of analytical information for both Client and Cloud Apps in a given project. Users can access a variety of information, such as how many Device Installs were performed, how many App Startups occurred, and more. Any one of these areas can be further investigated to access analytical information based on Date, Platform, and Location.

In Studio, this information is represented via a number of different graphs. Date specific data is represented by a line graph. This allows users to see a breakdown of App activity for a specific date range. Users can see the volume of activity for any given date in the range. For example, users could see how many Cloud Requests were performed on any given date in a date range.

The donut graph shows a breakdown of activity per platform. For example, the number of installs performed per platform inside a specified date range. Location specific data is represented on a Geographical map. This provides users with a breakdown of App activity based on geographical location. Each graph has a corresponding legend. Hovering the cursor over any of these charts will provide more info on the corresponding value in the legend.

The date range from which the data is gathered can be altered. Predefined ranges display information based on the 'Last 7 Days', 'Last 30 Days', and 'Previous Month', however if none of these are applicable, it is also possible to manually select a start and end date for the Range. This enables users to retrieve App data for a specific date range by simply selecting a data category, and then entering a date range.

1.1.12. Settings

From the Project Settings page, projects can be renamed or deleted.

1.1.12.1. Deleting a project

Once a project is deleted, it can not be undone. All Git repositories, Client Apps, and Cloud Apps will be removed. Any Apps that are associated with the project will no longer function.

1.1.12.2. Renaming a project

Here a project can be renamed.

1.2. Apps

1.2.1. Overview

There are a wide variety of Apps that can be built via the Red Hat Mobile Application Platform (RHMAP), including hybrid, HTML5, or Native Apps. Both Client and Cloud Apps can be added to any project. Apps have access to a number of JavaScript API’s that offer access to features such as geolocation or back-end storage. Form based Apps can now be created via a simple drag and drop interface.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Domain — Project (View)
  • Client App (View & Edit) — Analytics (View)

Related Resources

1.2.2. Details

The Details page is opened by default when the Apps, Cloud Apps and Services screen is selected. Here users can access overview information regarding the currently selected App. This information includes:

  • App Type: The type of your App.
  • App Name: The name of your App. For Client Apps, this is also the name of the App as it will appear on a device.
  • App Description: A description of your App.
  • App ID: Unique identifier for the App. This can be used to perform actions on this App with FHC.
  • App Description: Brief description of the App.
  • App API Key: This is used in conjunction with App ID to allow the App to communicate with a chosen Cloud App.
  • Source Path (Cordova only): The folder containing all source files of the app.

    Typically this is www. If you want to use a different folder when building or deploying your App, it can be changed here. Preceding and trailing slashes are stripped from paths. For example, if your source folder is /mysource/folder/, the path you enter here should be mysource/folder. Any build processes you have for your App (Grunt minification etc.) should place finalised assets in this folder.

  • Git SSH URL: URL to clone repository. If this repository is shared with other Apps, these Apps will be listed here.
  • Git Branch: The branch to checkout from the Git repository.

Any of the App details can be updated from this page. In Studio, there is also an App Preview on this screen. Users can choose to preview how the App would appear on either a phone, tablet, or desktop. After one of the devices has been selected in the App preview window, the user can preview how the App would appear on specific device by selecting a specific device from a list of dropdown options.

Apps can also be deleted from the Apps, Cloud Apps & Services page.

Note

When an App is deleted, its associated Git Repository will be removed and if it’s a Cloud App, it will be undeployed.

1.2.3. Editor

The built in editor allows users to edit code within their Apps. The built in syntax highlighting feature makes it easier to distinguish between syntactical elements. Users can create new files and folders, with saved changes being automatically pushed back to the corresponding Git repository.

After a change has been made, the preview automatically refreshes so you can instantly see your changes take effect. Changes can also be pulled in from a Git Repository by performing a 'git pull'.

The App Preview in the Editor section allows users to view how the current App appears on a number of selectable devices.

1.2.4. Docs

If your App contains a README.md markdown file in its route, it will be rendered and shown here.

1.2.5. Analytics

Note

The Analytics data is generated once per day.

The Analytics section provides access to a graphical representation of App usage statistics. Data can be examined via a number of categories including Installs, Cloud Requests, StartUps, and Active Devices. This data can be further categorized by date, platform, and location. Graph content is displayed by platform, with the exception of the 'Installs by Location'. Each platform is represented by a different key in the legend. Content in the graphs can be toggled on/off by clicking on the respective platform in the legend.

The date range can be also be customized. Predefined ranges include 'Last 7 days', 'Last 30 days', and 'Previous Month'. Users can also apply their own start and end date to the range.

Note

The Analytics page is not to be confused with the 'Reporting' tab. The Reporting tab shows analytical information on a per project basis. The 'Analytics' page shows displays data on a per App basis.

1.2.6. Push

The Push section allows users to configure push notifications for an App. Learn more about using push notifications in the Push Notifications chapter.

1.2.7. Building

The Build feature enables users to build a set of binaries for a selected platform. When performing a build operation, the Cloud App you want the Binary to connect to must be selected. This can be any of the Cloud Apps associated with the project. Builds can be done for any of the following platforms:

  • Android
  • iPhone
  • iPad
  • iOS Universal
  • Windows Universal Apps

One of a number of Build Types must also be selected. These include:

  • Development Build
  • Distribution Build
  • Release Build
  • Debug Build

Depending on the platform that has been selected, along with the Build Type, a Credential Bundle may be needed to sign the Binary. For more information on Credentials, see the Credentials section below.

Once a build has been successful, its Artifact is added to the Artifact History. The Artifact History provides summary information of the build, including the Platform the binary was built for, the Build Type, and the Credential Bundle used for the build. Selecting an Artifact from the Artifact History gives the option to download the binary again.

Note

In order to be able to perform some build operations, you must have first uploaded the relevant credentials via the Credentials page.

1.2.7.1. Publishing App Binaries to Third-party MAM and MDM providers

RHMAP provides support for uploading app binaries to third-party MAM and MDM providers. You can enable or disable support for individual providers in the Admin > Mobile App Management > Third-party MAM/MDM section.

If at least one MAM or MDM provider is enabled, the Build screen of Client Apps shows an MDM integration section with options for individual providers.

1.2.7.1.1. Apperian

To have the generated binary uploaded to the Apperian App Catalog after building, follow these steps before the build.

  1. Ensure the domain name of your RHMAP instance is added to a whitelist in Apperian’s EASE Portal. See Enable a Domain Whitelist for Custom Admin Sites in official Apperian documentation for detailed steps.
  2. Ensure that the app binary meets the requirements imposed by the Apperian App Catalog. See Add an Application in the official Apperian documentation for the full list of requirements.

    Note

    Some of the RHMAP Client App Templates do not fulfill all of the requirements. For example, you might need to configure an icon file for the app in some cases.

  3. Enable publishing to Apperian for a particular build.

    1. Select Push the generated app binary to the Apperian App Catalog.
    2. Provide your Apperian username and password.
    3. Click Apperian Login. After a successful authentication, the OAuth Token field will show a token that will be used for communication with the Apperian API.

The app binary resulting from a subsequent build will be uploaded to the Apperian App Catalog.

1.2.8. Exporting

The Export section allows the user to export an App via a number of selected platforms. When exporting an App, the Cloud App you want the Binary to connect to, the Platform, and the Version of the Platform must all be specified. Apps are exported as a zip file. When an export is complete, the export is added to the Artifcat History where it cab be redownloaded at any time.

1.2.9. Credentials

The Credentials section enables users to manage Credential Bundles. New Credential Bundles can be added or imported. A list of existing Credential Bundles can also be viewed.

1.2.9.1. Credential Bundles

In order to be able to perform certain types of build, an App must be signed with a Credentials Bundle. A Credential bundle is a combination of resources, such as certificates, provisioning profiles, and private keys, necessary for performing specific types of builds, be it a development build, distribution build, debug build etc. Depending on both the platform, and the build Type, a combination of different resources will constitute a bundle. For more information regarding the individual resources that make up a Credentials Bundle, see the Components of a Credentials Bundle page.

Note

To be able to develop Apps for iOS, you must have an Apple Developer Account.

The required credentials for each build type for specific platforms can be seen below:

Note

Ensure that the Private Key and its password are stored in a secure location as the Private Key and password are required when configuring a Credential Bundle on RHMAP. When generating a Certificate, ensure that the correct Private Key is used, for example: when working with an iOS Credentials Bundle, use the Development Build’s Private Key to generate the Development Build’s Developer Certificate.

iOS Credentials Bundle

  • Development Build

    • Developer Certificate
    • Private Key
    • Development Provisioning Profile
  • Distribution Build

    • Distribution Certificate
    • Private Key
    • Distribution Provisioning Profile
  • Release Build

    • Distribution Certificate
    • Private Key
    • Distribution Provisioning Profile

Android Credentials Bundle

  • Debug Build

    • None
  • Release Build

    • Certificate
    • Private Key

Windows Phone Credentials Bundle

  • Debug Build

    • None
  • Release Build

    • None
1.2.9.1.1. Create New Bundle

Here a new Credentials Bundle can be created and later used to sign binaries during a build. Depending on the platform choosen, different credentials may need to be added to the bundle. For example, when creating an Android Credentials Bundle, a Private Key, and Certificate are required, whereas when creating an iOS Credentials Bundle, a Private Key, Certificate, and Provisioning Profile are required.

1.2.9.1.2. Migrate Existing Dev Resources

This migrates existing credentials from the old App Studio, and adds them to the Credentials Bundles list.

Once a new bundle is created, or imported via migration, it will appear in the Credentials Bundle List.

1.2.10. Integrate

The Integrate section allows users to import an existing Client App into a RHMAP project. In order to import an app, you must clone the repo and integrate the app with the RHMAP SDK.

  1. Clone a Git Repo

    Cloning a repository creates an exact copy of an existing repository. All versions of all files in project are pulled down when a 'git clone' is performed. However before you can clone a repository, you need to upload your SSH Public Key. Once a Public Key has been uploaded, repositories can be cloned at will.

    For more information regarding cloning a Git repository, see the Git Documentation on Getting started with Git.

    For a more in-depth list of useful Git commands, see Git Reference.

  2. Download SDK

    In order to get your app to function, you must integrate it with the RHMAP SDK. An on-screen link is provided to download the most up to date RHMAP JavaScript SDK.

  3. Copy the JavaScript file to your Project

    After the RHMAP SDK has been downloaded, it can be referenced by moving it into the Project you created.

  4. Copy Initialisation Snippet

    You must create an fhconfig.json file that contains the id of the app, the app key, the host domain, and the id of the project to be associated with.

  5. Git Commit and Push

    After the SDK has been successfully integrated with the app, the changes can be committed and pushed. The app will now be successfully associated with the project.

1.3. Cloud Apps

1.3.1. Overview

A Cloud App is a server-side application that runs on an MBaaS - our cloud execution environment. Client Apps communicate with Cloud Apps in order to access back-end functionality such as data storage, authentication, caching etc.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Domain — Project (View)
  • Cloud App (View & Edit) — Analytics (View)

1.3.2. Details

The Details section provides access to overview information regarding the Cloud App. This section allows users to edit and manage this data.

An App can be in one of two states, either Running or Stopped. The state of the App can be controlled by the Start App, Stop App, and Restart App buttons. If an App is Running, on device builds of that app will function as expected. However if the app is Stopped, on-device users will not be able to use the app if it relies on Cloud functionality.

There is also a list of general information such as the App ID, App API Key, name, etc. This information can be edited and updated from this section.

  • App Id: Unique identifier for the App.
  • Name: The name of the Cloud Instance
  • Description: Brief description of the Cloud Instance
  • App API Key: This is used in conjunction with the App Id to allow the App to communicate with the Cloud
  • Git URL: URL to clone repository
  • Git Branch: The branch to checkout from the Git repository

1.3.3. Editor

The built in Editor can be used to edit code within the Cloud App. The built in syntax highlighting feature makes it easier to distinguish between syntactical elements. Users can create new files and folders, with saved changes being automatically pushed back to the corresponding Git repository.

After a change has been made, the preview automatically refreshes so you can instantly see your changes take effect. Changes can also be pulled in from a Git Repository by performing a git pull.

The App Preview in the Editor section allows users to view how the current App appears on a number of selectable devices.

1.3.4. Environment Variables

You can define environment variables using the Studio and those variables can be accessed in the cloud code. The Studio will show a list of current defined environment variables and current deployed environment variables for each cloud environment. You can also view the list of environment variables defined by the system.

1.3.4.1. Environment Variables List

You can find the environment variables option in the left hand menu. The initial view shows a list of all environment variables for this Cloud Instance.

1.3.4.1.1. App Environment Variables

This section lists the variables defined by you. These variables may not have been pushed to the cloud yet so the values here may be different from the values that are currently active. Any inconsistency between the defined values and deployed values will be highlighted in red. You can click on the value field to update it.

1.3.4.1.2. Deployed User Environment Variables

This section lists the current deployed environment variables created by you. Again, any inconsistencies will be highlighted. However, those values can not be updated directly.

1.3.4.1.3. Deployed System Environment Variables

This section lists the current deployed environment variables created by the platform. Those values are for your reference only and you should not change the values of those variables.

1.3.4.2. Create Environment Variables

You can create a new environment variable by clicking on the Add Variable button. The name of the environment variable should follow these rules:

  • Should NOT begin with FH_ or MONIT_
  • Should NOT be one of

    • PATH
    • HOME
    • PWD
    • USER
    • NODE_PATH
    • LD_LIBRARY_PATH

1.3.4.3. Unset/Delete Environment Variables

In the current environment variables list, when you check any of the variables, you will get the option to unset/delete the variable.

  • Unsetting a variable removes it from the currently selected environment.
  • Deleting a variable removes it from all environments.

You can unset/delete multiple variables at the same time.

1.3.4.4. Push Environment Variables

After finishing updating the values of the variables, you need to push the updated variables to the cloud by clicking on the "Push Environment Variables" button. This will also cause the app to be restarted.

1.3.4.5. Referencing Environment Variables In Code

An environment variable can be referenced in cloud code directly using process.env.variable name. For example

// PIN_ENABLED is the environmental variable created in the Studio.
var pin_enabled = process.env.PIN_ENABLED  || true  // defaults to true if no value defined

If you wish to obtain the value of the variable from the client side, the best method is to export a function on the cloud side returning the value of the variable and calling the function from the client side. For example

// On the cloud side using node.js
exports.getEnvVariable = function(params, cb){
  var pin_enabled = process.env.PIN_ENABLED  || true

  return cb(null, {
    enabled : pin_enabled
  });
};

// On the client side
$fh.act({
  act : 'getEnvVariable',
  req : {}
  }, function(res){
   // run this in the event of success.
}, function(err){
   // run this in the event of failure.
});

1.3.5. Data Browser

The Data Browser section of the App Studio allows a developer to

  • Graphically and interactively view the data associated with their app,
  • View, create and delete, import and export collections,
  • Modify data in a collection.

For more information, see the Data Browser Guide.

1.3.6. Deploy

The Deploy section allows a developer to:

  • Deploy the cloud code of the current App and view a log of the deploy
  • Choose (if more than 1 available) which environment to deploy the cloud code to
  • Choose (if available) which git 'branch' or 'tag' to deploy
  • Choose (if available) which Runtime & Version to run the cloud code with
  • Perform a clean deploy, where the entire deploy directory (including dependencies) is removed and redeployed to from scratch
  • Choose whether the app should be deployed automatically on future Git pushes to a selected branch

The Deploy process for Node.js applications typically does the following:

  • Retrieves the cloud code at the specified branch or tag reference
  • Gathers all environment variables values (both internal and custom), and any other config (for example, runtime) for the chosen environment
  • Pushes the cloud code, environment variables values and any other config to the chosen environment
  • Cloud code is extracted/copied to the relevant deploy folder
  • Environment variables are configured in the app startup script
  • Any other config sent along is acted upon for example, configured the correct runtime in the startup script
  • Dependencies are resolved and installed (from package.json)
  • The App is started using the startup script

The steps above will differ depending on the options chosen, the type of App and the presence & content of certain files.

In addition, developers may also configure the Platform to deploy cloud code to OpenShift Online. For more information, see the Staging Cloud Apps to RedHat OpenShift Online PaaS guide.

1.3.7. Stats

There are 2 types of stats available in the Studio: App Endpoint stats and Custom Stats. These are found in the 'Stats' section for any Cloud Apps.

There are some common UI features in the charts that represent this stats data. The data can be downloaded in different formats (for example, csv). The date range can be altered using the scrollbar and sliders below each chart. Each line in a chart can be toggled on/off by clicking that item in the legend.

1.3.7.1. App Endpoints

App Endpoint stats are available for all Apps without any additional setup required. Any endpoints defined in main.js will begin to produce stats as soon as the endpoint is called. A combined chart for 'All Endpoints' will also become available when stats are produced.

For each endpoint that is producing stats, the following summary information is available:

  • Requests per minute - Number of requests in the last minute (calculated value based on smaller intervals)
  • Average Request Time - Average time per request in the last interval
  • Average Concurrent Requests - Average number of concurrent requests being processed in the last interval (calculated based on requests per interval and average request timer per interval)

The default chart view shows the following data series:

  • Requests per second - Number of requests processed by the App per second (based on last interval)
  • Average Concurrent Requests - Average number of concurrent requests being processed in the last interval (calculated based on requests per interval and average request timer per interval)
  • Average Request Time (90th percentile) - Average duration of the requests in the last interval, ignoring outliers

The other graph items, Longest Request Time and Shortest Request Time, can be shown, by clicking on their names in the legend above the graph. The graph below show those stats included, and the Requests per second and Average Concurrent Requests, deselected.

1.3.7.2. Custom Stats

Custom stats are defined by the developer using the $fh.stats API.

1.3.7.2.1. Counters

Counters can be viewed on a line graph, showing the counter value for each interval.

Note

Counters are reset after each interval

1.3.7.2.2. Timers

Timers can also be viewed on a line graph. Each timer value is the average value (90th percentile) of that timer for that interval. The upper and lower values in each interval are also graphed on separate lines. These value give an overview of how the timer varies around the average time.

1.3.8. Notifications and Events

An app will generate events when certain actions are invoked against it. Those events will be recorded by the platform and presented to the developers through the App Studio and FHC. For example, when an app is deployed by an developer, the platform will record when the deployment happened, who invoked it and what are the results.

Each event has a category, a severity level and a name. The following events are generated by the platform at the moment:

Event NameEvent CategoryEvent SeverityDescription

CREATE_REQUESTED

APP_STATE

INFO

App creation is requested

CREATED

APP_STATE

INFO

App is created

CREATE_FAILED

APP_STATE

ERROR

App creation failed

DEPLOY_REQUESTED

APP_STATE

INFO

App deploy is requested

DEPLOYED

APP_STATE

INFO

App is deployed

DEPLOY_FAILED

APP_STATE

ERROR

App deploy failed

START_REQUESTED

APP_STATE

INFO

App start is requested

START_SUCCESSFUL

APP_STATE

INFO

App started

START_FAILED

APP_STATE

ERROR

App start failed

SUSPEND_SUCCESSFUL

APP_STATE

INFO

After one week of inactivity due to zero REST API calls between the App and the Platform, the App is stopped. Next REST API call automatically starts the App.

STOP_REQUESTED

APP_STATE

INFO

App stop is requested

STOP_SUCCESSFUL

APP_STATE

INFO

App is stopped

STOP_FAILED

APP_STATE

ERROR

App stop failed

CRASHED

APP_STATE

ERROR

Uncaught exception is thrown from the app and causes it to stop. It will be restarted automatically by the system monitoring process.

KILLED_RESTARTED

APP_STATE

ERROR

App is stopped then started

TERMINATED

APP_STATE

FATAL

App is terminated by the system due to too many restarts within a short time (currently 10 restarts in 20 seconds). It will not be restarted by the system monitoring process.

DELETE_REQUESTED

APP_STATE

INFO

App deletion is requested

DELETED

APP_STATE

INFO

App deleted

DELETE_FAILED

APP_STATE

ERROR

App deletion failed

CHANGE_REQUESTED

APP_ENVIRONMENT

INFO

Environment variables change is requested

CHANGE_SUCCESSFUL

APP_ENVIRONMENT

INFO

Environment variables changed

CHANGE_FAILED

APP_ENVIRONMENT

ERROR

Environment variables change failed

1.3.8.1. System Events View

You can view all the events generated by the platform in the "Notifications" section in the Cloud App view in the Studio. You can also use the filters to search for events. More information of an event is available when you click on an event entry.

1.3.8.2. Alerts & Email Notifications

Email notifications can be sent to developers when certain cloud events occur. This is done through alerts. An alert is to define in what condition an email notification should be triggered and what email addresses should be used.

1.3.8.2.1. Alerts View

In the alerts view, there are two tables. The first table will list all the alerts that are created for this app, and the second table will show all the cloud events that matches the selected alerts' settings. More information of an alert is available when click on the entries in the first table.

1.3.8.2.2. Creating Alerts

When click on the "Create An Alert" button, you will be presented with the alert creation view. In this view, you can specify the name of the alert, what events the alert should be monitoring on and the email address to receive the alert.

When specify the events, you can use any of the three criteria (event categories, severities and names), or any combination of them. You don’t need to select values in all these fields. Once an alert is created, if an event matching the criteria occurred, an email notification will be sent to the address specified in the alert.

1.3.8.2.3. Notifications View

The platform will keep records of all the email notifications that have been sent and you can view them in the Studio as well. Click on the table entry will show the full details of the notification.

1.3.9. Logs

Users can access current and archived App logs created in each App environment.

1.3.10. Endpoint Security

The endpoint security feature allows you to decide the level of security you wish to apply to your App’s endpoints.

1.3.10.1. Managing Endpoint Security

You can find the endpoint security option in the left hand menu for a Cloud Instance. There are a couple of ways to configure security.

1.3.10.1.1. App Security

App security defines a default level of security that will be applied across all of your endpoints. The default is HTTPS. This means all requests to your App’s endpoints will be sent over HTTPS. The App API Key options means that HTTPS will still be used, but that in order to access an endpoint the App API Key must be sent and must match the key created with your App. You can find this key under the details menu option for your App. This key is sent by default from the RHMAP SDKs. Enabling this option will mean your endpoints are only accessible when a correct App API Key is sent. If is not present, a 401 (Not Authorised) http response will be sent and your endpoint will not be called.

1.3.10.1.2. Individual Endpoint Security

You can change the security applied to an App’s endpoints at an individual level also. When you update the list, your Cloud Instance will be restart.

Note

If you have a running App and have not staged it for sometime, that you may need to re-stage the App once in order to pick up the latest version of the software.

1.3.10.2. The Audit Log

In order to allow you to transparently see what has been done to your App, whenever a change is made to your security setting, an entry is created in the audit log. You can view this log by clicking the Audit Log tab at the top of the Endpoint Security screen. The audit log shows you a clear log of what has happened with your App’s security settings. The filters allow you to get a smaller selection of the audit log.

1.3.10.3. CORS Support

Cross-origin resource sharing (CORS) is a mechanism that allows JavaScript on a web page to make XMLHttpRequests to another domain, not the domain the JavaScript originated from. For more on CORS, see CORS on Wikipedia. RHMAP automatically enables CORS for all cloud requests.

You can restrict this access to a domain of your choice as follows:

  • Under the 'Cloud Management' section of the Studio, click on 'Environment Variables'
  • Add a new Environment Variable called CORS_WHITELIST
  • Set its value to be the domain you wish to restrict access to
  • Hit the 'Push Environment Variables' button to apply the change to the currently selected environment

1.4. MBaaS Services

1.4.1. Overview

A Service is a running Cloud App used by projects to integrate with back-end systems for example, an Oracle integration service. Services are added to one or more projects to make them available to Apps in that project.

Requirements

In order to be able to provision an Cloud Service, the Service Administrator Role must be assigned to an account.

In order to be able to create an instance of a Cloud Service, users must have either a Developer Admin Role or Developer Role assigned to their account, in order to be able to create and manage projects. Services can then be added to a project in the same way an App or Cloud Instance is added.

1.4.2. Provisioning an MBaaS Service

Service Administrators can provision new MBaaS microservices that allow developers access to various back-end systems. Users can choose from a number of available services. After a service has been provisioned, it is then available to be used within Projects on the Platform. By default, when a service is created, it is marked as private. In order for the service to be available to all projects on a domain, the 'Global Service' option must be enabled. This declares the service as being publically available.

1.4.3. Details

Here you can access general overview information related to a specific service.

1.4.3.1. Service Details

The Service Details section provides you with overview information.

  • Service ID: This is the unique identifier for a particular service. It is used to reference a particular service through FHC.
  • Service API Key: This is used in conjunction with App Id to allow the App to communicate with the Cloud.
  • Git URL: URL to clone repository.

1.4.3.2. Service Settings

The Service Settings section allows users to edit details related to the service.

  • Name: The name of the service.
  • Projects: A list of projects that have access to the service.
  • Global Service: Selecting this option makes the service globally available to all projects on the domain. If this setting is enabled, developers will be able to select the service for use within their projects.
  • Delete Service: Deletes a service.

1.4.4. Docs

The Docs section contains an API documentation viewer, which clearly shows important aspects of the service’s API for each of its endpoints, such as:

  • expected request headers and an example of a request body,
  • an example of a response for the sample request,
  • a complete snippet of a $fh.service call to invoke the method on the given service,
  • a form for invocation of the service directly from the documentation viewer.

All of this is automatically generated if the root directory of the service contains a README.md file adhering to the API Blueprint specification. To learn more about the specification, take a look at the API Blueprint Tutorial or refer to the Language Specification for a full reference.

1.4.5. Editor

The built in Editor allows users to edit cloud code related to their service instance. The built in syntax highlighting feature makes it easier to distinguish between syntactical elements. Users can create new files and folders, with saved changes being automatically pushed back to the corresponding Git repository.

After a change has been made, the preview automatically refreshes so you can instantly see your changes take effect. Changes can also be pulled in from a Git Repository by performing a 'git pull'.

The App Preview in the Editor section allows users to view how the current App appears on a number of selectable devices.

1.4.6. Environment Variables

You can define environment variables using the Studio and those variables can be accessed in the cloud code. The Studio will show a list of current defined environment variables and current deployed environment variables for each cloud environment. You can also view the list of environment variables defined by the system.

1.4.6.1. App Environment Variables

This section lists the variables defined by you. These variables may not yet have been pushed to the cloud so the values here maybe different from the values that are currently active. Any inconsistency between the defined values and deployed values will be highlighted in red color. You can click on the value field to update it.

1.4.6.2. Deployed User Environment Variables

This section lists the current deployed environment variables created by you. Again, any inconsistencies will be highlighted. However, those values can not be updated directly.

1.4.6.3. Deployed System Environment Variables

This section lists the current deployed environment variables created by the platform. Those values are for your reference only and you should not change the values of those variables.

1.4.6.4. Create Environment Variables

You can create a new environment variable by clicking on the "Add Variable" button. The name of the environment variable should follow these rules:

  • Should NOT begin with FH_ or MONIT_
  • Should NOT be one of

    • PATH
    • HOME
    • PWD
    • USER
    • NODE_PATH
    • LD_LIBRARY_PATH

1.4.6.5. Unset/Delete Environment Variables

In the current environment variables list, when you check any of the variables, you will get the option to unset/delete the variable.

  • Unsetting a variable removes it from the currently selected environment.
  • Deleting a variable removes it from all environments.

You can unset/delete multiple variables at the same time.

1.4.6.6. Push Environment Variables

After finishing updating the values of the variables, you need to push the updated variables to the cloud by clicking on the "Push Environment Variables" button. This will also cause the app to be restarted.

1.4.7. Data Browser

The Data Browser section of the App Studio allows a developer to

  • Graphically and interactively view the data associated with their app,
  • View, create and delete, import and export collections,
  • Modify data in a collection.

For more information, see the Data Browser Guide.

1.4.7.1. Enabling the Data Browser

Selecting the Data Browser tab in the App Studio will present you with one of three screens.

  • The Data Browser, if you have already enabled the Data Browser.
  • A screen asking you to enable the Data Browser.
  • A screen asking you to migrate your data to enable to Data Browser.

Clicking on the enable button will perform the following steps:

  • Your app is stopped.
  • A new database is created specifically for your app.
  • An environmental variable is set for your app containing the raw connection string to the mongodb.

If your app’s data needs to be migrated, you will see a screen with a migrate button. This button will do the following:

  • Your app is stopped. This is to ensure no more data can be written during the migrate.
  • A new database is created specifically for your app.
  • Your existing data is migrated from the old database to the new one.
  • Your data is validated in the new database.
  • An environmental variable is set for your app containing the raw connection string to the app’s MongoDB instance.
  • Finally, if everything has succeeded, your old data is removed.
Note

You may also need to update the contents of your cloud/application.js and your cloud/package.json. If this is the case you will be informed on the migrate screen.

After all data migration steps have completed, you will be asked to re-stage your app.

1.4.7.2. Using the data browser

1.4.7.2.1. Viewing/Adding Collections

The collections associated with an app can be viewed by selecting the Data Browser tab in the Cloud Management section of the Studio.

This screen has two controls located at the top of the collection list, with buttons for:

  • Adding a collection.
  • Refreshing the list of collections.

Clicking on the button to add a collection prompts you to enter the collection name. Click on the Create button to create the collection.

1.4.7.2.2. Viewing Data In A Collection

To view the data stored in a collection simply click on one of the collections listed in the Data Browser. This view shows the data associated with the collection. At the top of the screen are the main listing functions:

  • Switch Collection. Selecting this option presents you with a list of collections for the app. Click on a collection to list the data in that collection.
  • Add an entry to the collection.
1.4.7.2.2.1. Sorting Data

To sort the data by a specific field, simply click in the field name at the top of the list. Sorting will alternate between ascending and descending order.

1.4.7.2.2.2. Filtering Data

To filter the displayed data, select the "Filter" button at the top of the Data Browser screen. Clicking this button displays the filtering options. These options allow you to filter the displayed data by one or more fields.

1.4.7.2.3. Editing Data

Editing data in the Data Browser can be done using either the Inline or Advanced Editor

  • The Inline Editor is used to edit simple data in a collection (for example, changing the text in a single field).
  • The Advanced Editor is used to edit more complex data types. This can be done using an interactive Dynamic Editor or a Raw JSON editor.
1.4.7.2.3.1. Editing Using the Inline Editor

To edit an entry using the Inline Editor, select the Edit option to the right of a data entry and select Edit Inline. The option will turn to a green tick and black arrow icons. When a field is too complex to edit in the Inline Editor, the "Advanced Editor Only" text is shown. This field is editable only in the Advanced Editor.

When finished updating the entry, select the green tick button to commit the changes to the data or the black arrow button to cancel any changes made.

1.4.7.2.3.2. Editing Using the Advanced Editor

The advanced editor is used to edit more complex data types (for example, where a field is composed of multiple nested fields).

To open the advanced editor, select the Edit option to the right of a data entry and select Advanced Editor. The advanced editor has two modes

  • A Dynamic Editor to interactively add/edit fields.
  • A Raw JSON Editor to directly edit the data in JSON format.
1.4.7.2.3.3. Editing Using the Dynamic Editor

The Dynamic Editor is an interactive editor for JSON data. It presents a structured view of each field to allow adding/editing complex data types. The actions menu provides all the functionality needed to manage complex fields for the entry:

  • Type: The type option changes the data type of the field to an array, JSON object or string. It is also possible to set the field to auto, where the data type is automatically selected from the data entered.
  • Sort: The sort option sorts the sub-fields of a complex type in ascending or descending order.
  • Append: The append option adds a field after the object selected.
  • Insert: The insert option inserts a field before the object selected.
  • Duplicate: The duplicate option copies the object selected and appends it to the end of the selected object.
  • Remove: The remove option deletes the field from the entry.
1.4.7.2.3.4. Editing Using the Raw JSON Editor

The Raw Editor allows for editing the JSON representation of the data. It is important to ensure that the data entered is in valid JSON format. The JSON data can be displayed in either formatted or compact form.

1.4.8. Deploy

The Deploy section allows users to manage the deployment of their current mBaaS code. Deployment targets can be created and selected, and deploys can be staged to either the live or development environments. As the Cloud Instance is being deployed, a deployment log is displayed, allowing users to closely examine all details of the deploy.

1.4.9. Stats

There are 2 types of stats available in the Studio: App Endpoint stats and Custom Stats. These are found in the 'Stats' section for any Cloud Instances.

There are some common UI features in the charts that represent this stats data. The data can be downloaded in different formats (for example, csv). The date range can be altered using the scrollbar and sliders below each chart. Each line in a chart can be toggled on/off by clicking that item in the legend.

1.4.9.1. App Endpoints

App Endpoint stats are available for all Apps without any additional setup required. Any endpoints defined in 'main.js' will begin to produce stats as soon as the endpoint is called. A combined chart for 'All Endpoints' will also become available when stats are produced.

For each endpoint that is producing stats, the following summary information is available:

  • Requests per minute - Number of requests in the last minute (calculated value based on smaller intervals)
  • Average Request Time - Average time per request in the last interval
  • Average Concurrent Requests - Average number of concurrent requests being processed in the last interval (calculated based on requests per interval and average request timer per interval)

The default chart view shows the following data series:

  • Requests per second - Number of requests processed by the App per second (based on last interval)
  • Average Concurrent Requests - Average number of concurrent requests being processed in the last interval (calculated based on requests per interval and average request timer per interval)
  • Average Request Time (90th percentile) - Average duration of the requests in the last interval, ignoring outliers

The other graph items, Longest Request Time and Shortest Request Time, can be shown, by clicking on their names in the legend above the graph. The graph below show those stats included, and the Requests per second and Average Concurrent Requests, deselected.

1.4.9.2. Custom Stats

Custom stats are defined by the developer using the $fh.stats API.

1.4.9.2.1. Counters

Counters can be viewed on a line graph, showing the counter value for each interval.

Note

Counters are reset after each interval

1.4.9.2.2. Timers

Timers can also be viewed on a line graph. Each timer value is the average value (90th percentile) of that timer for that interval. The upper and lower values in each interval are also graphed on separate lines. These value give an overview of how the timer varies around the average time.

1.4.10. Notifications and Events

An app will generate events when certain actions are invoked against it. Those events will be recorded by the platform and presented to the developers through the App Studio and FHC. For example, when an app is deployed by an developer, the platform will record when the deployment happened, who invoked it and what are the results.

Each event has a category, a severity level and a name. The following events are generated by the platform at the moment:

Event NameEvent CategoryEvent SeverityDescription

CREATE_REQUESTED

APP_STATE

INFO

App creation is requested

CREATED

APP_STATE

INFO

App is created

CREATE_FAILED

APP_STATE

ERROR

App creation failed

DEPLOY_REQUESTED

APP_STATE

INFO

App deploy is requested

DEPLOYED

APP_STATE

INFO

App is deployed

DEPLOY_FAILED

APP_STATE

ERROR

App deploy failed

START_REQUESTED

APP_STATE

INFO

App start is requested

START_SUCCESSFUL

APP_STATE

INFO

App started

START_FAILED

APP_STATE

ERROR

App start failed

SUSPEND_SUCCESSFUL

APP_STATE

INFO

After one week of inactivity due to zero REST API calls between the App and the Platform, the App is stopped. Next REST API call automatically starts the App.

STOP_REQUESTED

APP_STATE

INFO

App stop is requested

STOP_SUCCESSFUL

APP_STATE

INFO

App is stopped

STOP_FAILED

APP_STATE

ERROR

App stop failed

CRASHED

APP_STATE

ERROR

Uncaught exception is thrown from the app and causes it to stop. It will be restarted automatically by the system monitoring process.

KILLED_RESTARTED

APP_STATE

ERROR

App is stopped then started

TERMINATED

APP_STATE

FATAL

App is terminated by the system due to too many restarts within a short time (currently 10 restarts in 20 seconds). It will not be restarted by the system monitoring process.

DELETE_REQUESTED

APP_STATE

INFO

App deletion is requested

DELETED

APP_STATE

INFO

App deleted

DELETE_FAILED

APP_STATE

ERROR

App deletion failed

CHANGE_REQUESTED

APP_ENVIRONMENT

INFO

Environment variables change is requested

CHANGE_SUCCESSFUL

APP_ENVIRONMENT

INFO

Environment variables changed

CHANGE_FAILED

APP_ENVIRONMENT

ERROR

Environment variables change failed

1.4.10.1. System Events View

You can view all the events generated by the platform in the "Notifications" section in the Cloud App view in the Studio. You can also use the filters to search for events. More information of an event is available when you click on an event entry.

1.4.10.2. Alerts & Email Notifications

Email notifications can be sent to developers when certain cloud events occur. This is done through alerts. An alert is to define in what condition an email notification should be triggered and what email addresses should be used.

1.4.10.2.1. Alerts View

In the alerts view, there are two tables. The first table will list all the alerts that are created for this app, and the second table will show all the cloud events that matches the selected alerts' settings. More information of an alert is available when click on the entries in the first table.

1.4.10.2.2. Creating Alerts

When click on the "Create An Alert" button, you will be presented with the alert creation view. In this view, you can specify the name of the alert, what events the alert should be monitoring on and the email address to receive the alert.

When specify the events, you can use any of the three criteria (event categories, severities and names), or any combination of them. You don’t need to select values in all these fields. Once an alert is created, if an event matching the criteria occurred, an email notification will be sent to the address specified in the alert.

1.4.10.2.3. Notifications View

The platform will keep records of all the email notifications that have been sent and you can view them in the Studio as well. Click on the table entry will show the full details of the notification.

1.4.11. Logs

Users can access current and archived service logs created in each App environment.

1.4.12. Endpoint Security

The endpoint security feature allows you to decide the level of security you wish to apply to your App’s endpoints.

1.4.12.1. Managing Endpoint Security

You can find the endpoint security option in the left hand menu for a Cloud Instance. There are a couple of ways to configure security.

1.4.12.1.1. App Security

App security defines a default level of security that will be applied across all of your endpoints. The default is HTTPS. This means all requests to your App’s endpoints will be sent over HTTPS. The App API Key options means that HTTPS will still be used, but that in order to access an endpoint the App API Key must be sent and must match the key created with your App. You can find this key under the details menu option for your App. This key is sent by default from the RHMAP SDKs. Enabling this option will mean your endpoints are only accessible when a correct App API Key is sent. If is not present, a 401 (Not Authorised) http response will be sent and your endpoint will not be called.

1.4.12.1.2. Individual Endpoint Security

You can change the security applied to an App’s endpoints at an individual level also. When you update the list, your Cloud Instance will be restart.

Note

If you have a running App and have not staged it for sometime, that you may need to re-stage the App once in order to pick up the latest version of the software.

1.4.12.2. The Audit Log

In order to allow you to transparently see what has been done to your App, whenever a change is made to your security setting, an entry is created in the audit log. You can view this log by clicking the Audit Log tab at the top of the Endpoint Security screen. The audit log shows you a clear log of what has happened with your App’s security settings. The filters allow you to get a smaller selection of the audit log.

1.4.12.3. CORS Support

Cross-origin resource sharing (CORS) is a mechanism that allows JavaScript on a web page to make XMLHttpRequests to another domain, not the domain the JavaScript originated from. For more on CORS, see CORS on Wikipedia. RHMAP automatically enables CORS for all cloud requests.

You can restrict this access to a domain of your choice as follows:

  • Under the 'Cloud Management' section of the Studio, click on 'Environment Variables'
  • Add a new Environment Variable called CORS_WHITELIST
  • Set its value to be the domain you wish to restrict access to
  • Hit the 'Push Environment Variables' button in order for the changes to apply