LoginKey

Note: This is deprecated legacy technology. API Key is the current method. There is some overlap between the two but they are not equivalent.

The following section describes the steps needed to generate and use an encoded login key with CA Agile Central's App SDK LoginKey functionality. This will provide viewer-level functionality for apps into which this code is incorporated.

Using the App SDK LoginKey Feature

Running an App outside of CA Agile Central

This document explains how to create an app which runs outside of CA Agile Central (from your desktop or an Intranet portal, for example) without requiring the user to manually enter CA Agile Central credentials. The credentials are encoded using CA Agile Central's Encoder Page and supplied to the app using the “loginKey=” parameter on the script tag used to include the App SDK.

Since the encoded credentials could possibly be reverse-engineered by a savvy JavaScript programmer, we require the encoded username and password to refer to a read-only user, for example, one which has only Viewer permissions for all project to which that user has access. This restriction to read-only users is enforced by both CA Agile Central's Encoder Page and the App SDK at the time your app is initialized. As noted above in the Disclaimer box, this read-only user can not be a workspace administrator account which was demoted to a read-only account, as it would still be considered a NON-read-only account by the LoginKey.

Steps to create a sample app:

  1. Create a sample app:
    Copy and paste the following example code (app) into a local file named ExternalAppExample.html:
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <!-- Copyright (c) 2011 CA Agile Central Software Development Corp. All rights reserved -->
    <html>
    <head>
    <title>Login Component Example</title>
    <meta name="Name"    content="App Example: LoginKey CA Agile CentralDataSource" />
    <meta name="Version" content="2011.04" />
    <meta name="Vendor"  content="CA Agile Central Software" />
    <script type="text/javascript" src="https://rally1.rallydev.com/apps/1.25/sdk.js?loginKey=ENCODED STRING GOES HERE"></script>
    <script type="text/javascript">
    function onLoad() {
    var rallyDataSource = new rally.sdk.data.CA Agile CentralDataSource(
    '__WORKSPACE_OID__',
    '__PROJECT_OID__',
    '__PROJECT_SCOPING_UP__',
    '__PROJECT_SCOPING_DOWN__');
    var config = {type: "hierarchicalrequirement", columnKeys:["FormattedID", "Name"]};
    var table = new rally.sdk.ui.Table(config, rallyDataSource);
    table.display("tableDiv");
    }
    rally.addOnLoad(onLoad);
    </script>
    </head>
    <body>
    <div id="tableDiv" style="float:left;width:400px"></div>
    </body>
    </html>
  2. Modify your sample app to fit your environment:
    In the sample app you've created (from above), modify the 3 "meta" tags to reflect your own Name, Version, and Vendor. For example:

    <meta name="Name"    content="App: your app name here" />
    <meta name="Version" content="your version here" />
    <meta name="Vendor"  content="your company name here" />

    If you do not want your app to use the default workspace and project of the "LoginKey user", then replace the strings '__WORKSPACE_OID' and '__PROJECT_OID__' with the specific workspace and project object ids you want to use in your app.

    Replace '__PROJECT_SCOPING_UP__' and '__PROJECT_SCOPING_DOWN__' with 'true' or 'false' if you wish to override the defaults (false and true, respectively).

  3. Generate an encoded login key for your sample app:
    To generate the encoded username/password string, visit CA Agile Central's Encoder Page (https://rally1.rallydev.com/apps/html/EncoderPage.html). If you are not running on rally1.rallydev.com, replace the rally1.rallydev.com portion of the URL with the CA Agile Central server your sample app will connect to (such as trial.rallydev.com).

    A CA Agile Central login dialog box will display when you access CA Agile Central's Encoder Page. Enter the credentials for a read-only ("Viewer") CA Agile Central user. This must be a user which has only Viewer permissions to any projects to which it has access.

    Note: For the purpose of the LoginKey feature, a workspace administrator account which has been demoted to a read-only account will not work as it is still considered a NON read-only account by the LoginKey.

    Enter the password for this user in the Password text box and click the 'Submit' button to generate the encoded string which will appear in the "Encoded Output:" box.. Copy the encoded string into your clipboard (to be used in the next step).

  4. Add the encoded username/password string to your sample app:
    Paste the encoded string as the value for the loginKey parameter in the sdk.js script tag in your sample app, replacing "ENCODED STRING GOES HERE". The resulting script tag will look similar to the following. Line breaks have been added here for readability, but should not be added when you paste the string into your script tag:

    <script type="text/javascript" src="/apps/1.25/sdk.js?debug=true&loginKey=acda07bd5e53c99ae953f5374cf6e9c4cd996a7ad133a5 c2c8cc406caf1d9beb|f9f08a4699e83a27ecfbc462c3b51314|e5217f5acc26020b9a45f0009f0b028757b3a2ecfd7a72ed7a6ab5fb2f47df0ab64024ef268bd302a4117e0f93ed9bfb|71,50,65,97,121,3,17,51,117,7,150,38,80,97,148,71"></script>

  5. Security warning:
    The encoder page requires a read-only ("Viewer") user to generate the encoded key string. The key is visible to anyone who loads the app into a browser by using the browser’s View Page Source feature. This means it is possible for a malicious user to determine the read-only username/password by inspecting the code. Treat the encoded username/password string just as you would a password! Don’t share your sample app code (which contains the encoded string) with anyone you don’t trust.
  6. Run the sample app:
    Open your new sample app ExternalAppExample.html using your browser. When working properly, the browser page should show a table with story ids and names, similar to the screenshot below. If there are errors (such as an error copying and pasting the encoded string), they will be displayed in the App Header.
  7. More information:
    Refer to the App SDK documentation to learn more about writing CA Agile Central apps.

Running a Shared App outside of CA Agile Central

Similar to the steps above, you can also display shared CA Agile Central apps. This means the App must be "shared" to run outside of CA Agile Central. An unshared app will result in a 404 Page Not Found error.

Confluence access to Standard Reports

This example shows how to display CA Agile Central Standard Reports in a Confluence page without requiring Confluence users to enter CA Agile Central credentials.

  1. Create a Confluence page and open it for editing. Make sure you select the "Wiki Markup" tab in the Confluence editor.
  2. Important! Do not reselect the 'Rich Text' editor tab once your code has been copied into the editor. Doing so will escape some of the content and your page will not work.

  3. Copy and paste the example code below into the Confluence editor.
  4. Replace "ENCODED STRING GOES HERE" text with the encrypted login key produced by the Encoder Page as described above in Running an App outside of CA Agile Central. You must log in to the Encoder Page as a viewer-only user.
  5. Enter a title for the page and click the 'Save' button.
  6. The CA Agile Central Standard Reports should be displayed on the Confluence page.
  7. Read the Standard Reports page in the CA Agile Central help wiki to learn more about the different kinds of Standard Reports and additional parameters you can modify.

    Notes:

    • Your installation of Confluence must be set up to support the {html} tag. More information about how to get this for your Confluence installation can be found here and here.
    • In general, you should be able to convert any app to run in Confluence by removing <html>, <head>, and <body> tags (and the corresponding closing tags), and adding the {html} macro as the first and last lines.

Example Code:

<title>Login Component Example</title>
<meta name="Name" content="App Example: Confluence Standard Report" />
<meta name="Version" content="2011.04" />
<meta name="Vendor" content="CA Agile Central Software" />
<script type="text/javascript" src="https://rally1.rallydev.com/apps/1.25/sdk.js?loginKey=ENCODED
STRING GOES HERE"></script>
<script type="text/javascript">
function onLoad() {
rally.sdk.ui.AppHeader.destroy();
var reportConfig = {
report: rally.sdk.ui.StandardReport.IterationBurndown,
width : 400,
height: 300
};
var report = new rally.sdk.ui.StandardReport(reportConfig);
report.display("reportDiv");
}
rally.addOnLoad(onLoad);
</script>
<div id="reportDiv" style="float:left; width: 400px; margin-left:20px"></div>

SharePoint access to Standard Reports

This example shows how to display a CA Agile Central Standard Report in a SharePoint form Web Part without requiring SharePoint users to enter CA Agile Central credentials.

  1. Copy and paste the example code below into a text editor to begin creating your own page.
  2. Replace "ENCODED STRING GOES HERE" text with the encrypted login key produced by the Encoder Page.

    You must log in to the Encoder Page as a read-only user.

  3. Add a new Web Part Page in SharePoint and open that page.
  4. Select "Edit Page" from the Site Actions Menu.
  5. Select "Add a Web Part" on the area of the page you want to add the report.
  6. In the "Add a Web Part" menu select Form Web Part.
  7. Click the Source Editor... button to edit the code for the web part, and paste in your example code.
  8. Click the Save button in the Source Editor. Your report should display in the Web Part.

Example Code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!-- Copyright (c) 2011 CA Agile Central Software Development Corp. All rights reserved -->
<html>
<head>
<title>Login Component Example</title>
<meta name="Name" content="App Example: SharePoint Standard Report" />
<meta name="Version" content="2011.04" />
<meta name="Vendor" content="CA Agile Central Software" />
<script type="text/javascript" src="https://rally1.rallydev.com/apps/1.25/sdk.js?loginKey=ENCODED STRING GOES HERE"></script>
<script type="text/javascript">
function onLoad() {
rally.sdk.ui.AppHeader.destroy();
var reportConfig = {report: rally.sdk.ui.StandardReport.IterationBurndown, width: 400, height: 300};
var report = new rally.sdk.ui.StandardReport(reportConfig);
report.display("reportDiv");
}
rally.addOnLoad(onLoad);
</script>
</head>
<body>
<div id="reportDiv" style="float:left; width: 400px; margin-left:20px"></div>
</body>
</html>

Multiple CA Agile Central Standard Reports in one SharePoint WebPart

Adding a second WebPart to a SharePoint page will cause the first WebPart to stop displaying its CA Agile Central content. Instead, use only one WebPart, but modify your HTML code to put each chart in its own div. You will need to use a separate config object for each Standard Report.

Example Code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!-- Copyright (c) 2011 CA Agile Central Software Development Corp. All rights reserved -->
<html>
<head>
<title>Login Component Example</title>
<meta name="Name" content="App Example: SharePoint Standard Reports" />
<meta name="Version" content="2011.04" />
<meta name="Vendor" content="CA Agile Central Software" />
<script type="text/javascript" src="https://rally1.rallydev.com/apps/1.25/sdk.js?loginKey=ENCODED STRING GOES HERE"></script>
<script type="text/javascript">
function onLoad() {
rally.sdk.ui.AppHeader.destroy();
var reportConfig1 = {report: rally.sdk.ui.StandardReport.IterationDefectsbyState, width: 400, height: 300};
var report1 = new rally.sdk.ui.StandardReport(reportConfig1);
report1.display("reportDiv1");
var reportConfig2 = {report: rally.sdk.ui.StandardReport.IterationDefectsbyPriority, width: 400, height: 300};
var report2 = new rally.sdk.ui.StandardReport(reportConfig2);
report2.display("reportDiv2");
}
rally.addOnLoad(onLoad);
</script>
</head>
<body>
<div id="reportDiv1" style="float:left;width:400px"></div>
<div id="reportDiv2" style="float:left; width: 400px; margin-left:20px"></div>
</body>
</html>

On Premise Caveats

LoginKey functionality works out of box for CA Agile Central's on-demand (SAAS) editions. It still works in On-Premises CA Agile Central environment but with some limitations. LoginKey with on-demand CA Agile Central has a capability to trick the browser to create a separate session cookie to work in a scenario when a user loads a CA Agile Central app or a report externally in a browser (using encoded read-only credentials) alongside with another tab in the same browser where an editor user is already logged in to CA Agile Central tool. This use case should be avoided and is not supported with On-Premises.

Feedback

Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.