Additional Parameters

Besides the fields from the contacts table, you can also pass parameters to the customer portal.

Table Parameter Descriptions

Parameter Notes


This parameter represents a contact custom field in Oracle Service Cloud. The * must be replaced with the number of the cf_id for the contact custom field. If this is a menu custom field, the numbers (not the actual text) for each menu item must be specified as the value in the integration login code. See How You Find Code Numbers and Report IDs.


This parameter represents the contact’s social channel. The * must be replaced with the ID number of a valid channel:



The value represents the user name for the channel. For example, if you want to pass the contact’s Twitter user name, you would pass the parameter and value p_chan_11="jane.doe", where jane.doe is the user name.


This parameter is a time stamp that defines how long the PTA login information is valid. When the time expires, the login information is no longer accepted and contacts are redirected to the page specified in the PTA_ERROR_URL configuration setting, and an error code of 16 is passed to the page. See How You Interpret Error Codes.

Note: You can generate the value using a UNIX date/time stamp generator.


This parameter represents the string specified in the PTA_SECRET_KEY configuration setting.

Note: This parameter is required if the PTA_SECRET_KEY configuration setting contains a value and the PTA_ENCRYPTION_METHOD configuration setting does not contain a value.


This parameter represents an organization ID to associate with a contact. See How You Find Code Numbers and Report IDs.

Note: You must manually assign any service level agreements (SLA) that you want to associate with the organization, including those controlling privileged access.


This parameter represents the contact’s state for Oracle RightNow Cloud Service (Service).




This parameter represents the contact’s state for Oracle RightNow Outreach Cloud Service.




This parameter represents the contact’s state for Opportunity Tracking.



How You Interpret Error Codes

When a customer attempts to log in using pass-through authentication, there are a number of factors that can cause login failure, including an invalid user name or password, a duplicate email address in the database, and problems with the PTA string.

To help you debug login errors or provide informational messages, customers can be redirected to a custom page displaying an error code and session information when an error occurs.

The URL of the page where customers are redirected is specified in the PTA_ERROR_URL configuration setting. To display an error code, the URL must be appended with the %error_code% variable. Session information can be provided in the form of a base64-encoded string if the %session% variable is also appended. Session information displays only if login tracking cookies are disabled on the customer’s computer.

Note: The PTA_ERROR_URL configuration setting is blank by default. If you do not specify a value for the setting, customers are redirected to the URL in the PTA_EXTERNAL_LOGIN_URL configuration setting when a login error occurs. If you choose not to use the PTA_ERROR_URL configuration setting, you can append the %error_code% and %session% variables to the end of the URL specified in PTA_EXTERNAL_LOGIN_URL. See How You Define the External Login Page.

For example, assume that you set the configuration setting value to:


If login fails because the password exceeds the 20-character limit, the URL that is returned is:


The error code, 15 in this example, lets you know what caused the failure.

The error codes displayed in the URL when an error occurs are described in the table. These codes are the same whether the %error_code% variable is used in the PTA_ERROR_URL or the PTA_EXTERNAL_LOGIN_URL configuration setting.

Table Error Code Descriptions

Error Code Description


The PTA string parameter was not found. This parameter contains all of the encoded PTA information in the URL, so it must be present to log in.


PTA information after pre_pta_decode hook was not in the correct format. A string or an array was expected, but something else was received.


PTA string could not be Base 64 decoded. There was an error within the string that caused the decoding process to fail.


One of the PTA string parameters was not well formed. For example, it did not contain “p_” or was missing an “=” separator between the key and value.


The p_userid string was passed in, but it did not have a value. This pair is required for login.


The value of the p_li_passwd pair was incorrect. This error applies only if no value is set for PTA_ENCRYPTION_METHOD.


The specified credentials were invalid.


Login failed because PTA is not enabled for the interface.


Data decryption failed.


Login failed because PTA_ENCRYPTION_METHOD does not contain a valid value.


Login failed because PTA_ENCRYPTION_PADDING does not contain a valid value.


Login failed because PTA_ENCRYPTION_KEYGEN does not contain a valid value.


Login failed because PTA_IGNORE_CONTACT_PASSWORD is enabled, but no encryption scheme has been set in PTA_ENCRYPTION_METHOD.


Login failed because the format of the data after the pre_pta_convert hook was not an array.


Login failed because the password exceeded the 20-character maximum length.


Login failed because the PTA token expired and is no longer valid. A new token must be generated to authenticate the customer.


Login failed because two or more email addresses have the same value.

How You Find Code Numbers and Report IDs

You must use code numbers (ID numbers) in pass-through authentication to specify parameters such as countries, provinces, custom fields, and organization IDs.

The administration interface provides three ways to look up the codes for these types of fields:
  • Hovering over the field name

  • Displaying report IDs in the Reports explorer

  • Using the NamedID helper object

When exploring reports, you can view the report ID (ac_id) by displaying the ID column in the explorer details.

Many records and items contain an Info button on the Home tab of the ribbon. When you click the Info button, record details are displayed, including the record ID number.

How You Pass Login Parameters to Oracle Service Cloud

These examples show how to generate a form to pass login parameters to Oracle Service Cloud.

Using these examples, you can retain all query_string parameters and append key-value pair parameters.

Replacing certain variables with meaningful values will make the scripts easier for you to understand.

  • your_domain: the domain name used by your Oracle Service Cloud site

  • your_interface: your interface name

  • li_password: the string specified in the PTA_SECRET_KEY configuration setting

Caution: This example code snippet is for illustrative purposes only and will be improperly formatted if you attempt to cut and paste directly from it.
//Assumption is that user has been validated/logged in and you 
//have their contact record available and can access their profile data
//Build up PTA data array
$ptaDataArray = array(
//Common contact fields (not a complete listing, this is just a sampling)
//The $contact variable is assumed to be the data of the user logging in
'p_userid'     => $contact->login,
'p_passwd'     => $contact->password, //Only needs to be sent if 
'p_email.addr' => $contact->emailAddress,
'p_name.first' => $contact->firstName,
'p_name.last'  => $contact->lastName,
//Example of sending in custom field value where the custom field 
ID is 3 'p_ccf_3'      => $contact->customField3Value,
//Example of sending in channel field value where the channel field ID is 14
'p_chan_14'    => $contact->channelField14Value);

//Add secret key if not using encryption

if (PTA_ENCRYPTION_METHOD configuration setting IS NOT set)


    $ptaDataArray['p_li_passwd'] = Value of PTA_SECRET_KEY config setting;


//Convert PTA data array to string

$ptaDataString = "";

foreach($ptaData as $key=>$value)


    $ptaDataString .= ($ptaDataString === "") ? '' : '&';
    $ptaDataString .= "$key=$value";


//Optionally encrypt data if using encryption with the method, secret key,

//padding a keygen methods. The function called here is made up. The actual function

//will vary depending on which language you are using



    $ptaDataString = encryptData($ptaDataString, PTA_ENCRYPTION_METHOD, 


//Base64 encode the data

$ptaDataString = base64_encode($ptaDataString);

//Make sure the data is URL safe

$ptaDataString = strtr($ptaDataString, array('+' => '_', '/' => '~', '=' => '*'));

//Specify which page to take the user to

if (%next_page% URL parameter exists)

    $redirectPage = %next_page% parameter;


    $redirectPage = 'home';

//Send the user to the PTA controller to log them in

header("Location: http://your _CP_site/ci/pta/login/redirect/$redirectPage/p_li/$ptaDataString");


How You Use the pre_pta_decode Hook

The pre_pta_decode hook lets you write custom PHP code, which is executed after accepting the PTA string from the URL and before calling the login routine.

After the hook runs, the p_li parameter is processed and passed to the PTA controller. The hook also passes the redirect parameter so you can modify the location where the customer is directed.

It is not possible to return a custom error message from this hook, so if you want to cover the situation of an interrupted PTA login, you must add a header() location redirect and exit() in your hook. There are two data formatting options: string or array.

  • String format—After the hook executes, the login integration data that was passed to the hook is evaluated to see if it is still a string. If it is, the data is assumed to be a standard base_64 encoded string. An algorithm is run to convert the string into an array of contact pairdata in key->value pairs. This allows the pass-through authentication to work as it would if no hook handler is defined and no extra encryption is added.

  • Array format—After the hook executes, the p_li parameter is evaluated to see if it has been converted to an array. If so, the format of this array is assumed to be the contact pairdata key->value structure. Here’s an example of this structure.


How You Use the pre_pta_convert Hook

You can use a pre_pta_convert hook that runs after the data has been decoded and converted into an array, and before it is converted to the correct pair data structure.

This lets you modify the PTA data sent in the URL on the fly without having to decrypt and convert it yourself.

In this hook, a single parameter named “decodedData,” which is in the form of an array, is passed. This example shows the data in the URL in the first line and the decoded/decrypted data passed to the hook by reference in the second line.

JnBfdXNlcmlkPXVzZXJuYW1lJnBfZW1haWw9dGVzdEBleGFtcGx lLmNvbQ**
[p_userid => 'username', p_email => 'test@example.com']

Any modifications to the array are picked up by the PTA controller when the data is converted into contact API pairs.