Developing and embedding an AppSDK2 app externally

Products

• CA Agile Central On Premise (Rally)
• CA Agile Central SaaS (Rally)

Issue/Introduction

Developing and embedding an AppSDK2 app externally

Environment

Release:
Component: ACPREM

Resolution

Resolution

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

<Please see attached file for image>

and successfully creates a key with full access:

<Please see attached file for 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

Success

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:

<Please see attached file for 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:

<Please see attached file for 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.

<Please see attached file for 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.

<Please see attached file for image>

Adding the same apiKey now works:

<Please see attached file for 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:

<Please see attached file for 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:

<Please see attached file for image>

Finally apiKey is used successfully:

<Please see attached file for 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.

Serving HTTP on 0.0.0.0 port 8000 ... appears if server is created successfully.

python -m SimpleHTTPServer 3000
Serving HTTP on 0.0.0.0 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.

<html>
  <header>
    <title>Embedded app test: revs</title>
  </header>
  <body>
    <iframe src="http://localhost:3000/App-external.html?apiKey=_5o1v6Jg" width="800" height="500"></iframe>
  </body>
</html>

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

<Please see attached file for image>

The app should load successfully:

<Please see attached file for 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.
?