Agile Central: SDK Apps - Why despite using api key we are prompted to log into Rally by our externally deployed app?
Article ID: 100436
Updated On:
Products
Issue/Introduction
We followed the documentation, developed an SDK app, deployed it externally and appended an Api Key. The app is loading well, but any subsequent action within the app, any click on any object - results in a Rally login screen.
When this app runs on the dashboard or on a custom HTML page then we are not getting the login screen and we can click on the Feature ID and see it.
Environment
Component: ACSAAS
Resolution
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 Rally. Clicking on objects will bring up the login screen".
To explain it thoroughly we need to take a step back and explain a few Rally'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 Rally's application server. It is generated when a username logs into the application. The session token allows its holder to act inside Rally 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 Rally.
2. Api Key.
Api Key is a key that uniquely belongs to its user. It allows the user to authenticate and authorize to Rally 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 Rally. 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 Rally. 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/
3. Rally's JavaScript App SDK.
The SDK is a javascript library that allows you to develop apps for Rally. The SDK classes include much of the Rally's look, feel and behavior as you experience when using the user interface. It includes the same grids, trees, buttons, filter widgets, grid menu options (including for bulk operations), coloring, style-sheets and more. Much of the default behavior that you see and experience in Rally is integral built-in part of the SDK.
More on the App SDK: https://help.rallydev.com/apps/2.1/doc/
4. Extending Rally.
Rally offers a natural way to extend its functionality and behavior. This way is the Rally 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 Rally from its extensions (the apps). Being a SaaS product Rally 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).
You will use the SDK to develop your apps using javascript. While you can always build from scratch, it's a good practice to find similar apps and reuse parts of their code. Rally's apps are open source (kept in public repositories in Git Hub), you can download them and modify the code to essentially develop your own app. You will normally use the Rally App Builder to create, build, test and deploy your code. The 'Additional Information' section below has the references to the repositories.
The SDK-based apps live and operate in the context of Rally's user interface. They require a Session Token to operate. These apps are hosted in pages inside Rally. They 'participate' in the same session the user already has open. The user will authenticate and log into Rally, then that Session Token is shared between the core pages, the apps and custom HTML pages. All live under the same Rally'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 Rally 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 Rally 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 Rally. 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.
You can invoke this page from anywhere - But:
i. Since it's part of Rally 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 Rally (as you actually are in Rally). There is nothing preventing you from start navigating Rally , 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. This button and get back to a non-expanded mode so you again can navigate Rally.
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 Rally 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 Rally 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 Rally'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 Rally and share/participate with the browser/app-server session token. As we explained the SDK is intended to extend the Rally 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 Rally. 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 Rally.
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 Rally'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 Rally. 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 Rally data. The SDK can not re-use the Key. External apps are best to display read-only data such as Charts or Reports.
Feedback
