The short answer to this question is:
"You are doing nothing wrong. This is the expected behavior. Externally deployed apps are not meant for interaction with Agile Central. Clicking on objects will bring up the login screen".
To explain it thoroughly we need to take a step back and explain a few Agile Central's concepts, review the SDK architecture and understand what developing apps externally means technically. This will help us understand the limitations of external apps and how to best use them.
1. Session Token.
Session Token is a value that's generated by Agile Central's application server. It is generated when a username logs into the application. The session token allows its holder to act inside Agile Central in accordance with that user's permissions. The session token expires when the user is logging out. A session token is required to allow continuous activity with Agile Central.
2. Api Key.
Api Key is a key that uniquely belongs to its user. It allows the user to authenticate and authorize to Agile Central instead of providing the username/password credentials. It does not expire, but it will only work if the user is enabled. If the user is Locked or Disabled then it won't work. As long as the user is enabled then it will work even if the password keeps changing. It is a 'thumb print' that's unique to the user. Api Keys are normally used by integration programs into Agile Central. The advantage is that the credentials aren't kept on the remote machines and that the api key won't expire. It enables the integration program treat the Api Key as a 'Service Account'. Api Keys will many times be Read-Only in order to limit the possibility of undesirable updates or abuse.
Api Key is not a Session Token. Using an Api Key does not create a session within Agile Central. Api Keys are normally to perform REST calls to Agile's Endpoint using WSAPI. They must be provided to any subsequent call to the same or another Endpoint.
More on Api Keys: https://help.rallydev.com/external-api-keys
More on WSAPI: https://rally1.rallydev.com/slm/doc/webservice/
More on the App SDK: https://help.rallydev.com/apps/2.1/doc/
4. Extending Agile Central.
Agile Central offers a natural way to extend its functionality and behavior. This way is the Agile Central apps. The apps can be included on users' dashboards or on shared custom HTML pages. You can share them across your teams. The apps are provided a separate execution space to run. This design separates the core functionality of Agile Central from its extensions (the apps). Being a SaaS product Agile Central frequently deploys fixes, betas and other core functions. It is critical to separate the product core from the extensions. This allows the the extensions (app, custom pages) to not be impacted by the core frequent deployments, and also allows the core product not to be impacted with updates or problems with the apps.
When you identify a gap, perhaps missing or incomplete behavior you may consider developing an app to fill in the missing function. This may be a simple or complex task, depending on the gap and your requirement. An example of a simple gap could be to extend an already existing app so that it works with additional artifacts. A more complex requirement may be if you would like to display a chart that's based on complex calculations (that will have to be part of your app).
The SDK-based apps live and operate in the context of Agile Central's user interface. They require a Session Token to operate. These apps are hosted in pages inside Agile Central. They 'participate' in the same session the user already has open. The user will authenticate and log into Agile Central, then that Session Token is shared between the core pages, the apps and custom HTML pages. All live under the same Agile Central's session context.
Let's examine what this actually means:
Consider an that lists User Stories where clicking a Story's name will open another frame to display its details. The session token allows the smooth operation between your browser and the application server so the screens can change without requesting you to login every time. This is what enables the experience of continuous interaction for both the core product and the apps.
5. Accessing and interacting with yours app.
We covered accessing your app when they are part of Agile Central itself. But,
Customers may want to access the apps "externally", maybe from a corporate portal for example. "Externally" means that you are not logged into Agile Central when accessing the app.
Can it be done? Let's elaborate.
There are two ways to do that, each with implications and constraints. Let's examine these ways.
Custom HTML Page
a. You can share your app on a Custom HTML page in Agile Central. Your app is given a unique HTML page with a unique URL. To find the URL of your page, visit your page, then look at your browser address bar. It will look like:
You can invoke this page from anywhere - But:
i. Since it's part of Agile Central then you will be prompted to login. If your browser has another tab open that's already logged on then your page will share the session token and be 'already logged in'.
ii. Once you call that page you will see the full menu bar of Agile Central (as you actually are in Agile Central). There is nothing preventing you from start navigating Agile Central , browse to any page, click every button etc.
iii. There is an option to append an 'expandApp' argument to the page URL, that will display your app expanded. Still, you will be able to click this button and get back to a non-expanded mode so you again can navigate Agile Central.
Custom HTML pages can not be made to display your app stand-alone. It can not be made exclusive on the browser window or frame.
Develop Apps Externally
b. You can "develop and deploy your app externally".
To achieve exclusivity , that is displaying your app and only your app on the browser's frame, and even to embed it to your own corporate portal's page, you will need to deploy your app 'externally'.
See on External development: https://help.rallydev.com/apps/2.1/doc/#!/guide/developing_externally
See on Embedding your app: https://help.rallydev.com/apps/2.1/doc/#!/guide/embedding_apps-section-develop-the-app
There are a few things to explain about this concept. It also comes with its limitations:
i. You will run your app in a different web server. It is not part of Agile Central at all. Your app's execution is stand-alone and exclusive to your page.
ii. You append the Api Key to your app's HTML page URL. Your app's entry page will be displayed.
iii. Further clicks in your app to bring up additional information from Agile Central will land you on the login screen.
Let's examine again an app such as what we examined earlier, a list of User Stories where clicking the Story's name shall display the details in another frame:
Using the External/Embedding method you will get to the app's entry screen (the list of User Stories), but clicking on the stories name will get you to Agile Central's login screen. It will not display the story's details.
This is because:
No Session Token was ever created.
The Api Key got you passed for the call to the entry page. The SDK isn't 'keeping it' to reuse for any next calls of your app. Since no other session token on your browser then you're landing on the login page. The SDK is designed to work inside Agile Central and share/participate with the browser/app-server session token. As we explained the SDK is intended to extend the Agile Central app. It is not designed to allow for continuous interaction on an external server.
Externally deployed apps therefore are not meant for continuous interaction with Agile Central. They should be used mainly for information that is read-only in nature and not interactive, such as charts, graphs or reports. Apps such as Burnup, Burndown Charts are good examples for apps that can and should be deployed externally and embedded on your corporate pages.
Let us summarize
- We started by asking why clicking any object in an externally embedded app results in a login screen to Agile Central.
The answer is because external/embedded apps can only display information. Further interaction will require a login.
- The SDK is a library that is designed to extend Agile Central's user interface and application experience. It can not interact with Agile's back-end on its own, it must do that through a session token.
- Api Key can allow a 'poke' one-time call into Agile Central. They do not hold a session for a continuous interaction. When integrations or WSAPI based calls are made they must provide the Api Key with every call to each REST Endpoint. Each call is a one-time transaction.
- As such, you can append the Api Key to your call of your external/embedded SDK based app and be able to 'poke' for Agile Central data. The SDK can not re-use the Key. External apps are best to display read-only data such as Charts or Reports.