Retrieving Agent Info in a Browser Control

When building any Workspace in the CX Agent Console, Browser Controls are a powerful tool for integrating external systems and features seamlessly into the agent experience. Browser Controls display a configurable web page inside of the Workspace. Additionally, contextual data from the Workspace can be passed through the url to the web page. The Oracle RightNow Connect Desktop Integration (JavaScript API) defines what values can be passed via the URL and the format for doing so. For details, see the following section:

JavaScript API -> Operational Behavior -> URL Parameters

The URL Parameter Feature Gap

The available parameters give you a lot of power for passing contextual data to your webpage, but there is a feature gap when it comes to retrieving data about the logged in Agent. Many of the use cases I've seen require some sort of information about the Agent, whether for system integration purposes or for authentication reasons. The only available agent-related parameter provided natively by the framework is the Agent's Session ID ($p_sid from the guide), but this is mostly useless since this field is not available to the SOAP API, ROQL or Analytic Reports.

Often times you need to retrieve something more about the agent such as their ID, Login, or some Custom Field value. Fortunately there is a solution.

Using a proxy script and the AgentAuthenticator class

While Agent Session ID is mostly worthless outside of the RightNow platform boundaries, it can be used inside of the platform through a Custom Script (PHP) or Customer Portal controller (PHP) to validate an Agent's authentication and retrieve their Agent ID. We do this using a class called "AgentAuthenticator" which provides functionality for validating an agent and ultimately returning an Agent ID. Once we have the Agent ID, we can use any of the APIs to retrieve more data about the Agent.

This tutorial will show how this can be done using a proxy script hosted inside of the "Custom Scripts" directory of your RightNow site.

The Tutorial

Write a "proxy" script (PHP)

The purpose of this proxy script is to receive an Agent's Session ID through a URL parameter, use it to look up more information about the Agent, then redirect to an external page with the additional Agent data as URL parameters.

  1. Create a file named "agent_info_proxy.php" somewhere on your computer.

  2. As a starting point, copy and paste the code from this example: agent_info_proxy.php

    <?php
        
        /**
         *  AgentInfoProxy
         *  For use with Browser Controls in CX Agent Console. Script takes the Agent's
         *  Session ID supplied by a GET parameter, authenticates the Agent, then retrieves
         *  additional agent data. Finally a redirect is performed to an external URL with
         *  the additional Agent data.
         *
         *  Usage:
         *  Upload the script through the File Manager workspace in the CX Agent Console
         *  to the 'custom scripts' directory.
         *  Through the Workspace Editor, open a workspace and place a Browser Control
         *  Configure the Browser Control to point to the following URL:
         *  https://your_site.custhelp.com/cgi-bin/your_interface.cfg/php/custom/agent_info_proxy.php?p_sid=$p_sid
         *  
         *  @TODO - make redirect URL a GET parameter
         *
         *  @author: andy@45n.co
         *  @url: 
         *  @version: 1.0  
         *
         */
        try 
        {
            //Redirect URL with placeholder for Agent Login
            //Change this value for your own use
            $url = "https://www.google.com#q=%s";
        
    
            if (!isset($_GET['p_sid']) || empty($_GET['p_sid'])) 
            {
                throw new \Exception("Missing required GET parameter: p_sid");
            }
            
            $sessionId = $_GET['p_sid'];
            
            // Set up and call the AgentAuthenticator
            require_once (get_cfg_var('doc_root') . '/include/services/AgentAuthenticator.phph');
            
            $account = AgentAuthenticator::authenticateSessionID($sessionId);
            if (!isset($account)) 
            {
                throw new \Exception("Couldn't Authenticate Agent using Session ID");
            }
            
            //Use Agent ID to retrieve Staff Account object using ConnectPHP
            $agentObj = \RightNow\Connect\v1_2\Account::fetch((int) $account['acct_id']);
            
            //Construct Redirect URL with Agent values
            $url = sprintf($url, $agentObj->Login);
            
            //Perform Redirect
            header("Location: $url");
            exit();
            
            
        }
        catch(\Exception $ex)
        {
            echo "No input file specified.";
            exit;
        }
            
  3. On line 28 I define a URL ($url) variable that represents the external URL that I will ultimately redirect to. For my demo purposes, I am redirecting to the Google search page and querying Google with the Login field value of my agent. For your own implementation you would want to provide your own URL and define what parameters you wish to pass. I use a PHP format string in my example so that I can use the sprintf later in my script.

    
            //Redirect URL with placeholder for Agent Login
            //Change this value for your own use
            $url = "https://www.google.com#q=%s";
            

    Note: To make this proxy script more flexible I would expand upon this demo and allow the redirect url to be provided by a URL parameter instead of being hard coded. For the sake of simplicity in this tutorial, the URL is hard coded.

  4. Lines 31 to 45 deal with grabbing the Session ID from the URL and using the AgentAuthenticator class to validate the session and retrieve the Agent's ID.

    The AgentAuthenticator class is a standard class that is part of the RightNow platform. The source is not available through your Customer Portal WebDAV connection, but with a little creativity you can retrieve (file_get_contents) the file and inspect if for yourself.

    
            if (!isset($_GET['p_sid']) || empty($_GET['p_sid'])) 
            {
                throw new \Exception("Missing required GET parameter: p_sid");
            }
            
            $sessionId = $_GET['p_sid'];
            
            // Set up and call the AgentAuthenticator
            require_once (get_cfg_var('doc_root') . '/include/services/AgentAuthenticator.phph');
            
            $account = AgentAuthenticator::authenticateSessionID($sessionId);
            if (!isset($account)) 
            {
                throw new \Exception("Couldn't Authenticate Agent using Session ID");
            }
    
            
  5. Once I have the Agent ID, I can use Connect PHP to retrieve the full Agent object.

    
            //Use Agent ID to retrieve Staff Account object using ConnectPHP
            $agentObj = \RightNow\Connect\v1_2\Account::fetch((int) $account['acct_id']);
    
            
  6. The rest of the script will depend on your own use case. In my demo I choose to retrieve my Agent's Login field, combine that with my URL template using sprintf, and finally redirect to the external URL. I could easily change the format of the URL or pass multiple values from my Agent context. Additionally, I could choose to pass through all of the original GET parameters to my external page since it is very likely I'm including additional contextual parameters.

    
            //Construct Redirect URL with Agent values
            $url = sprintf($url, $agentObj->Login);
            
            //Perform Redirect
            header("Location: $url");
            exit();
    
            

Upload the agent_info_proxy.php script using File Manager

Most RightNow sites have access to the Custom Scripts directory. The Custom Scripts directory is an area on your RightNow site where you can upload custom PHP scripts that can be executed from a public URL. We use the File Manager workspace in the CX Agent Console to upload files to this area.

You can execute/access the Custom Script through a URL with the following pattern:
https://your_site.custhelp.com/cgi-bin/your_interface.cfg/php/custom/script_name_and_extension.php

  1. Open your RightNow CX Agent Console and log in with an Account that has permissions to use the File Manager

  2. Navigate to the "Configuration" component -> "Site Configuration" folder and open the "File Manager" workspace

  3. Select "custom scripts" from the Switch To drop down

  4. Browse and select the agent_info_proxy.php script from your computer and upload it by hitting the Go button.

Configure a Browser Control in a workspace

Open your workspace in the Workspace Editor and place a Browser Control in the desired location. Double clicking on the Browser Control will activate the configuration settings in the ribbon. In the settings, select the URL parameter and enter the location of your proxy script. Additionally, be sure to include the p_sid GET parameter and dynamic value placeholder ($p_sid):

https://your_site.custhelp.com/cgi-bin/your_interface.cfg/php/custom/agent_info_proxy.php?p_sid=$p_sid

Finally, save your workspace and open a record to test your changes. You should see a Google Search page in the Browser Control that has automatically searched for your currently logged in Agent's username.

Comments

The value from $p_sid can be compared with the sessions.entity_id. This was earlier available as accounts.sessionid. The sessions table has been newly added and joins with the accounts table. So session validation should be possible with a RightNow report as well.

Sorry, I stand corrected. The Session id is indeed not available. The entity id joins with the accounts table and has the same data as the acct_id.

This is very useful workaround especially for agents working with a 3rd party application from RN console

Very useful code

This article is a few years old now, but it mentions the following:

"While Agent Session ID is mostly worthless outside of the RightNow platform boundaries, it can be used inside of the platform through a Custom Script (PHP) or Customer Portal controller (PHP) to validate an Agent's authentication and retrieve their Agent ID."

Does anyone have an example on how to validate an agent via a Customer Portal controller (PHP) ?

Because the usual Agent Authenticator class cannot be called from customer portal.

Essentially, how can a CP controller or page be protected so it is only accessible from the Agent Desktop (with agent session ID or similar), and not viewed directly via a web page.

Thanks

Zircon - This is a contributing Drupal Theme
Design by WeebPal.