Creating and Using Extensions

Servlet Imports

The servlet should include the following import statement to access the Extension framework:

import com.peoplesoft.crm.omk.external.GenericAnnuncioServlet

Servlet Class Inheritance

The servlet class should be declared to extend the GenericAnnuncioServlet class. For example:

Public class myDemoServlet extends GenericAnnuncioServlet

This extension provides access to logging and tracing.

Output

Extension output for merge purposes can use the standard servlet ServletOutputStream provided with the servlet class via its response mechanism.

Extension Framework Error Handling

The Extension framework handles errors for custom content extensions in the following ways, depending on the type of document:

Extensions That Call Classes in External jar Files

If the custom extension needs to call classes in external jar files (such as CI methods or third-party methods), then these jar files must be added to the system classpath of the webserver to be available to the extensions. The procedures for doing so are as follows:

WebLogic:

1. Put the jar files in a known location (for example, C:\Jars\myci.jar).

2. Go to [PS_APP_HOME]\webserv\[DOMAIN]\applications\crm.

3. Open the setenv.cmd file.

4. Scroll to near the end, where you will see a line setting the CLASSPATH variable. For example:

   SET CLASSPATH=%PSCLASSPATH%;%PLATFORM_PATCH%;%JAVA_HOME%\lib\tools.jar;%WL_HOME%\
   server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar
   

5. Add your jar file location to the end of the CLASSPATH setting. For example:

   SET CLASSPATH=%PSCLASSPATH%;%PLATFORM_PATCH%;%JAVA_HOME%\lib\tools.jar;%WL_HOME%\
   server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar;c:\Jars\myci.jar
   

6. Restart the DES server.

WebSphere:

1. Go to the lib directory of the WebSphere installation.

2. Put the external jar file in this directory.

3. Restart the DES server.

Example PeopleCode Function

The following is an example extension, written in a PeopleCode extension class, that uses MessageBox to write its parameter names and values to the Application Server log:

import RY_DATAOBJS:*;

class CustomAction;
   method CustomAction();
   method actionMethod(&params As MapObj);
end-class;

method CustomAction
end-method;

method actionMethod
   /+ &params as RY_DATAOBJS:MapObj +/
   Local string &msg;
   Local array of string &keys;
   Local integer &i;
   &msg = "actionMethod(";
   &keys = &params.keys();
   For &i = 1 To &keys.Len
      If &i > 1 Then
         &msg = &msg | ",";
      End-If;
      &msg = &msg | &keys [&i] | "=" | &params.get(&keys [&i]).value;
   End-For;
   &msg = &msg | ");";
   
   MessageBox(0, "", 0, 0, &msg);
end-method;

The custom action receives a single parameter of type RY_DATAOBJS:MapObj. This is a name/value map which maps parameter names to parameter values. All names are strings; all values are of type RY_DATAOBJS.StringObj.

To get a PeopleCode string from StringObj, use its value property. The contents of the map will consist of all parameters defined when the action was registered, any additional parameters added when the action was included in a dialog, plus any document/profile fields on the page that was submitted to cause the action to be invoked.

PeopleCode actions are invoked asynchronously, and need not return a value.

See the product documentation for PeopleTools: PeopleCode Language Reference and PeopleTools: Application Designer Developer's Guide.

Global Extension Parameters

The following parameters can also be used in Extensions, and can appear in any order. These parameters apply to both custom content and custom action extensions. They are set in the Settings feature.

Notes on Designing Extensions

The following usage notes describe things you should be aware of when creating and using Extensions.

• Caching Extensions

  Because caching custom content extensions has a direct impact on the WebLogic or WebSphere Application Server memory usage, you may need to modify the memory settings of the webservers to support cache content. You should tune elements of the system based on usage; caching all extensions is not necessarily a good idea. Exceeding the memory size value can result in unpredictable DES behavior.

• Checking for Timeout

  The Extension framework cannot force a running servlet to stop when it is timed out—it can only request that the servlet stop processing and clean up after itself. Therefore, a well-behaved servlet should periodically check to see if it has been timed out, and stop processing if it has been.

  The recommended way to do this is to check to see if the servlet's thread has been interrupted. This can be accomplished using the following call sequence:

  import java.lang.Thread
  ...
  boolean keepRunning = Thread.currentThread().isInterrupted();
  if (!keepRunning)
  {
  	//... cleanup and exit code goes here
  }

  Note that default timeouts have an order of precedence depending on where they occur. The order in which they are used, from first to last, is:

  1. The value specified in the merge content.

  2. The value specified where the extension is registered

  3. The global default value registered for the Extension framework

  4. The internal, hard-coded default

  A good rule to follow is that you should not specify a timeout in merge content unless it is very important to override the more general defaults.

• Throwing Exceptions

  If the extension is to be used by the Mailcaster, you have control as to whether the entire job or only a single email is aborted.

  If you want to abort the entire job, the servlet should throw a ServletException. You should do this, for example, if there is some resource needed for all contacts that is unavailable. The user can then reschedule the mail job after the problem is corrected.

  If you want to suppress the sending of mail to the single contact then a VCSingleContactException should be thrown. This would be useful in the case where a resource for a single end user was not available.

Registering a Java Extension

Access the Extension Registration page (Navigate to Set Up CRM, Product Related, Online Marketing, Extension Summary).

Image: Extension Registration page - Java servlet

This example illustrates the fields and controls on the Extension Registration page - Java servlet.

Registering a PeopleCode Extension

Registering a PeopleCode extension is similar to registering a Java extension, except that a PeopleCode extension cannot be used in the Dialog Process tree. Because of this, the Usage check box is selected and disabled.

Image: Extension Registration - PeopleCode function

This example illustrates the fields and controls on the Extension Registration - PeopleCode function.

See Register the Extension in Online Marketing.

Managing Extensions

Only users with the role of Dialog Administrator can register extensions or change global settings. Once an extension is registered and its status set to Active, it cannot be deleted from system. However, the following modifications can be made, depending on the extension's status:

Custom Action Error Troubleshooting

If your custom action extensions are not functioning correctly, the problem could be due to blocking in the Integration Broker queue. This problem can affect all custom action extensions, including the following delivered extensions:

• SMS.

• Correspondence.

• Push Lead.

• Access Marketing Event.

• Credit Card Services.

To check for this, do the following:

1. Determine whether the domain is active by navigating to PeopleTools, Integration Broker, Quick Configuration.

   Change the status to Active if it is not already activated.

2. Determine whether operations in error exist in the Integration Broker by navigating to PeopleTools, Integration Broker, Service Operations Monitor, Asynchronous Services.

3. Search for RY_XMSG_AREQ.

4. Click Detail, then click Cancel for each item with the status Error.

Refer to the PeopleTools 8.52: Integration Broker Service Operations Monitor for more information on asynchronous service operation services.

Update Case Score

The Update Case Score extension is used by Case Integration to update survey scores to Support and HelpDesk. You cannot modify the Update Case Score extension using the Extension Registration page, which is disabled for this extension.

See Understanding Surveys.

See Send Case Survey Page.

Access Case Information

The Access Case Information extension allows you to include information about a particular support case in a web or email document. You can choose to include the following information:

• Case ID.

• Case Status.

• Case Summary.

• Case Description.

• All of the previous four parameters.

Access Marketing Event

The Access Marketing Event custom content extension is used as custom content in Online Marketing documents to support Event Management.

Image: Access Marketing Event extension (1 of 2)

This example illustrates the fields and controls on the Access Marketing Event extension (1 of 2).

Image: Access Marketing Event extension (2 of 2)

This example illustrates the fields and controls on the Access Marketing Event extension (2 of 2).

The extension includes the following parameters:

The following table shows the possible return values for each of the parameters:

For all parameters except set_paid, set_guest_counts, guest_Email, guest_First Name and guest_Last Name, the default value is N. For set_paid, the default is 0.

For all parameters except update_note, set_paid, guest_Email, guest_First Name and guest_Last Name, the extension implements the functionality of the first parameter from top to bottom (i.e., the first parameter it encounters) that has the value of any word beginning with “Y” or “y”.

See PeopleSoft Event Management documentation for a description of how to use the Access Marketing Event extension.

Credit Card Service

The Credit Card Service extension supports credit card “Authorization” and “Authorization and Bill” services. It can be used only in documents as a Custom Content Extension. Only one field, Timeout, is available for editing.

To edit the Timeout field, access the Extension Registration page (Set Up CRM, Product Related, Online Marketing, Extension Summary, open the Credit Card Service extension).

Image: Credit Card Service extension

This example illustrates the fields and controls on the Credit Card Service extension.

The extension includes several parameters which are entered when the credit card information is provided. All parameters are required unless specified as optional.

Image: Credit Card Service parameters

This example illustrates the fields and controls on the Credit Card Service parameters.

Credit Card Service Extension Execution

When the dialog containing the Credit Card Service extension is run, the following occurs:

1. The credit card data is validated.

2. An Authorize or Authorize and Bill request is sent to CyberSource.

3. The extension returns:

   • An authorization code if the authorization is accepted.

   • 0 if authorization or data validation fails.

   • -1 if there is a system error for the document field.

4. The extension logs a transaction in the CRM Credit Card history table (PS_RB_CARD_HISTORY). You can review this history by navigating to Main Menu, Review Electronic Card History and selecting Online Marketing from the Card Owner ID list. Note that when you view the transaction in the History list, the credit card number will appear encrypted.