Chapter 5. Working With the Platform Using FHC

5.1. Managing API Keys with FHC

When certain FHC commands are executed, it needs to communicate with the platform using the user’s identity. This requires the user to login to the platform using the fhc login command. User API keys provides an alternative way to use FHC. You don’t have to run the login command anymore if you have set the user API key in FHC. FHC can use the user’s API key to authenticate when communicating with the platform.

5.1.1. Set User API Keys

In FHC, the command related to API keys management is fhc keys. If you run this command without any additional argument, you will be shown the command help.

To set a user API key for the current FHC target, you should enter the following command:

fhc keys user target eb8d9b9ea050b9b23fea59e50ba281c67f3715e5
Note

This requires you to have previously set the target using fhc target.

To check which API key is currently used for FHC, you can run this command

fhc keys user target

After setting a user API key in FHC, you can run other FHC commands as usual.

For example, you can list, create, update and revoke user API keys using FHC.

5.1.2. List User API Keys

If you have logged in or set the user API key using FHC, you can see all the API keys associated with the current user by running this command:

fhc keys user list

If the output format is set to json in your FHC config, each key object will look like this:

{
  "key": "eb8d9b9ea050b9b23fea59e50ba281c67f3715e5",
  "keyReference": "1j6qcwiziRkbYy6sUUHDooAY",
  "keyType": "user",
  "label": "test 1",
  "revoked": "2012-04-20T15:18:17.258Z",
  "revokedBy": "1j6qcwiziRkbYy6sUUHDooAY",
  "revokedEmail": "dev@example.com"
}

5.1.3. Create User API Keys

To create a user API key, run this command:

fhc keys user create test2

You should get a response similar to:

{
  "key": "22d0c0ac5990e8fd2c466c26db1a9eff8a171511",
  "keyReference": "1j6qcwiziRkbYy6sUUHDooAY",
  "keyType": "user",
  "label": "test2",
  "revoked": "",
  "revokedBy": "",
  "revokedEmail": ""
}

5.1.4. Update User API Keys

To update a user API key using FHC, you can run this command:

fhc keys user update 22d0c0ac5990e8fd2c466c26db1a9eff8a171511 test3

You should get a response similar to:

{
  "key": "22d0c0ac5990e8fd2c466c26db1a9eff8a171511",
  "keyReference": "1j6qcwiziRkbYy6sUUHDooAY",
  "keyType": "user",
  "label": "test3",
  "revoked": "",
  "revokedBy": "",
  "revokedEmail": ""
}

5.1.5. Revoke User API Keys

To revoke a user API key using FHC, you can run this command:

fhc keys user revoke 22d0c0ac5990e8fd2c466c26db1a9eff8a171511

You will be prompted to confirm the revoke action. After confirmation, you should see something similar to:

{
  "key": "22d0c0ac5990e8fd2c466c26db1a9eff8a171511",
  "keyReference": "1j6qcwiziRkbYy6sUUHDooAY",
  "keyType": "user",
  "label": "test3",
  "revoked": "2012-04-20T16:14:11.702Z",
  "revokedBy": "1j6qcwiziRkbYy6sUUHDooAY",
  "revokedEmail": "dev@example.com"
}

5.2. Create a service using FHC

Overview

This tutorial shows you how to create a service and associate it with a project. For more information regarding services, and their functionality, see the Cloud Services documentation.

Requirements

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

  • Project (View & Edit)
  • Service (View & Edit)

For more information on Permissions, see Teams & Collaborations.

5.2.1. Log in to the platform

fhc login myUsername myPassword

5.2.2. Create a Project

Now that you have successfully logged in to the platform, we will create a project that we will then associate a service with. In order to create the project, enter the following command:

fhc projects create serviceProject

To verify that the project has successfully been created, enter the following command to search for projects on the domain:

fhc projects | grep 'serviceProject'

This should return the newly created project. Notice that there are currently two apps in this project. A Client App, and a Cloud App.

5.2.3. Create a Service

Services can be added to a project to allow the Client to access back-end functionality they would otherwise not have access to. Before we create a service, we will view a list of available templates. To view the service templates, enter the following command:

fhc templates services

This will output a list of all available service templates. We will add the PayPal service to the project. To do this, copy the service id of the PayPal service.

When creating a service, we must also specify a name. Enter the following command:

fhc services create paypalService paypal

This has successfully created a new service that can be associated with Projects.

5.3. Building an App Binary

Overview

This tutorial will cover how to build a mobile app binary using FHC. Building App Binaries with the Red Hat Mobile Application Platform Hosted (RHMAP) makes use of the cloud hosted "Build Farm" which is used to turn source code into mobile apps. If you have local developer tools installed (such as Xcode or ADT), you are free to build app binaries locally yourself. However, using the RHMAP Build Farm allows you to automate the build process, maintain a history of previous builds and build apps for platforms which you may not have developer tools for (for example, building iOS binaries from a Linux OS).

Requirements

Before starting this tutorial, you should have completed the following tutorials:

5.3.1. fhc build command

There are a number of parameters that need to be specified to perform a build using fhc. This will vary depending on the type of build, and the platform for which you are building. During the Working with Projects and Apps tutorial, we created a cordova hybrid app as part of the project. We will now use that app to perform a build for Android.

The fhc build command takes the following parameters:

  • project=<project-id> — the guid of the project.
  • app=<app-id> — the guid of the Client App to build app.
  • cloud_app=<cloud-app-id> — the guid of the Cloud App which the Client App should connect to.
  • tag=<tag> — the Semver tag to use for this build. See Connections for more details.
  • destination=<destination> — the type of build — e.g android, iOS, windowsphone.
  • version=<version> — the specific OS version to target for the destination.
  • config=<config> — the type of build to perform — 'debug' (default), 'distribution' or 'release'.
  • keypass=<private-key-password> — the password for the private key used for building (only needed for release builds).
  • certpass=<certificate-password> — the password for the certificate used for building (only needed for release builds).
  • download=<true|false> — whether or not to download the generated binary.
  • provisioning=<path-to-provisioning-profile> — the path to the provisioning profile to be used for the build.
  • cordova_version=<cordova-version> — the version of cordova to use.
  • environment=<environment> — the id of a target environment — e.g dev.

Not all of these parameters are required for all build types. For more information use the fhc build --help command.

When building an app, we must tell fhc the project the app is in as well as the app id. You must then enter the id of the Cloud App that the Client App speaks to. Client Apps are pointed towards Cloud apps via a connection. Clients can communicate with various Cloud apps via a number of different connections, and so when performing a build you must also specify the connection tag you wish to use.

fhc build project=XME5iUr2VoBV3DbXrVF7qApG app=XME5iNsoeRA2xvbmaDYMCdsi cloud_app=XME5iHzfwW9hcGw6_F7Eiwvf tag=0.0.3 destination=android config=debug keypass= certpass= download=true

When the build has been completed, you will get confirmation output similar to what is displayed below.

Download URL: Download URL: https://ngui-demo.sandbox.feedhenry.com/digman/android-v3/dist/3e0837f2-76b6-4512-881c-bd3bf427929d/android~4.0~7~HelloWorldClient.apk?digger=diggers.digger206u

5.3.1.1. Artefacts

After a build has been successful, a build artefact is added to the build history. These artefacts allow users to re-download an app without having to perform the build again.

To list all artefacts for a given app, you must use the fhc artefacts <projectId> <appId> command.

fhc artefacts XME5iUr2VoBV3DbXrVF7qApG XME5iNsoeRA2xvbmaDYMCdsi

A list will be displayed containing all artefacts for the specified app.

5.3.2. Next Steps

5.4. Viewing App Stats with FHC

FHC can be used to access raw, JSON stats data for your apps.

To access your app stats (timers and counters) for a particular app, use the following command:

fhc stats <APP_ID> app <NUMBER_OF_RESULTS>

Where APP_ID is the ID of your app as listed in an fhc apps command, and NUMBER_OF_RESULTS is the maximum number of results you wish to see returned. See below for a sample Stats response.

{
  interval: 10000,
  results: [
    {
      "ts": 1333107734000,
      "numStats": 6,
      "counters": [
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME_active_requests",
          "value": {
            "value": 3,
            "valuePerSecond": 0.3
          }
        },
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME2_active_requests",
          "value": {
            "value": 27,
            "valuePerSecond": 2.7
          }
        },
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME3_active_requests",
          "value": {
            "value": 456,
            "valuePerSecond": 45.6
          }
        }
      ],
      "timers": [
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME_request_times",
          "value": {
            "upper": 86,
            "lower": 63,
            "count": 17,
            "pcts": [
              {
                "pct": "90",
                "value": {
                  "mean": 76,
                  "upper": 86
                }
              }
            ]
          }
        },
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME2_request_times",
          "value": {
            "upper": 99,
            "lower": 82,
            "count": 41,
            "pcts": [
              {
                "pct": "90",
                "value": {
                  "mean": 88.66666666666667,
                  "upper": 99
                }
              }
            ]
          }
        },
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME3_request_times",
          "value": {
            "upper": 99,
            "lower": 75,
            "count": 2783,
            "pcts": [
              {
                "pct": "90",
                "value": {
                  "mean": 79.1254547827,
                  "upper": 99
                }
              }
            ]
          }
        }
      ]
    }
  ]
}