Developing and embedding an AppSDK2 app externally

Document ID : KB000057567
Last Modified Date : 14/02/2018
Show Technical Document Details


We assume that a valid Api Key has been created by the user. Documentation for API Key is available in Rally help.

Here is a user, nicktemp, currently logged in to Rally accesses Create API Key page

User-added image

and successfully creates a key with full access:

User-added image

This example follows steps outlined in the Embedding Apps guide.

1. Develop the app:

We use a short rab instead of long rally-app-builder when issuing rally app builder's commands in the terminal.
The actual app that used in this example is not important: it can be any working custom app written by a customer, but for the ease of troubleshooting it is better to test with one of a simple examples from AppSDK2 documentation.
To make sure that the browser is not using cached credentials, we close all open Chrome windows, and then open a new Chrome incognito window prior to issuing rab run command in the terminal.
If we do not get a prompt to login it will indicate that the browser is using cached credentials, which is not what we want.

When we call rab build command we see this output in the terminal:
Compiling the App.

Creating App-debug.html

Creating App.html

Creating App-external.html

Creating App-uncompressed.html


Next, rab run is called.
In terminal, after rab run command is called, Launching http://localhost:1337/App-debug.html... line appears:
rab run
Launching http://localhost:1337/App-debug.html...
and the app is loads and prompts to login:

User-added image
Cancel out of the prompt, and append ?apiKey=<your key here> in the address bar as shown below. The app loads successfully using credentials supplied by the API Key:

User-added image

We assume that at this point the development phase is over. The next step is to deploy App-external.html to a production server.

A variation of the steps above that does not use rab run command:

rab run command deploys a server on port 1337 by default. If your subscription has jsonp enabled, and if a user skips rab run steps and tries to use apiKey when running the html file locally, and not off an http server, the key is ignored because it is expected to load over the HTTP protocol rather than the local file protocol. If your subscription does not have jsonp enabled (jsonp is disabled by default) it is not possible to load an app over a file protocol. Only http protocol is supported by default.

User-added image

The simplest solution is to use a localhost. In this example python SimpleHTTPServer is used on port 3000. This screenshot shows that if we simply load localhost:3000/deploy/App-external.html we are being prompted to login, as expected. There is no apiKey string there. This screenshot is included to show that we are not logged in to Rally in another tab of the same browser or that the credentials are not being cached by the browser. To keep the test clean, this is run in a Chrome's incognito window.

User-added image

Adding the same apiKey now works:

User-added image

This scenario above was tested on Mac.
The same scenario was tested on Windows. When file protocol is used on Windows apiKey is also ignored:

User-added image
In this Windows example a node http-server is used. Those choices are up to the user. A node sever is started in the command prompt on port 3100, and we make sure that the browser is not using cached credentials:

User-added image
Finally apiKey is used successfully:

User-added image

2. Embed the app:

App-external.html is located in the deploy folder inside the app's folder.

To imitate a production server for the purposes of this example, we create a new folder anywhere, cd to that folder and create simple http server using
python -m SimpleHTTPServer commmand.

HTTP on port 8000 ... appears if server is created successfully.
python -m SimpleHTTPServer 3000
Serving HTTP on port 3000 ...

We copy App-external.html from the app's folder to the folder from which localhost:3000 was deployed.
Next, a new html file, App-embedded.html is created with a content that follows the syntax below. Notice the API Key in the URL to which src property is set.
    <title>Embedded app test: revs</title>
    <iframe src="http://localhost:3000/App-external.html?apiKey=_5o1v6Jg" width="800" height="500"></iframe>

Both html files should be available on localhost:3000. If you are following this example and using localhost, make sure to access localhost:3000 in a new incognito window of Chrome browser, otherwise the cached data from localhost:1337 will cause error:

The 'Access-Control-Allow-Origin' header has a value 'http://localhost:1337' that is not equal to the supplied origin. Origin 'http://localhost:3000' is therefore not allowed access.

Open a new incognito window in Chrome and click on App-embedded.html

User-added image
The app should load successfully:

User-added image

NOTE: It is outside of Rally support's scope to troubleshoot or test this scenario in 3rd party production environments like SharePoint, Confluence, but the steps outlined in the the second part of this article, "Embed the app", are expected to work in those portals.