Search

What best practices and guidelines should be followed when developing customizations using the CPM/Process Designer?

Environment:

Process Designer, Custom Processes (CPM)
All product versions

Resolution:

Click here to view product documentation on 'Best Practices: Testing Object Event Handler Scripts'. The following can be helpful in addition to the information provided in the product feature documentation.

The following best practices and guidelines are important to understand when creating and testing object event handler scripts:

• Log details necessary to troubleshoot the customization. There needs to be a log entry at the top of the apply function identifying the object being processed. Exception details must also be logged, as well as any details needed for troubleshooting. For further details see  Answer ID 9897: Adding custom logging to your CPHP customizations.
   
• Handle expected and possible errors with try/catch statements. Scripts should catch generic PHP and Connect for PHP exception types and should log errors to an accessible location. For further details see the section on 'PHP try/catch for CPM customizations' here  Answer ID 9640: Connect for PHP Best Practices and Gotchas.
   
• Consider selecting the Can Suppress check box when mapping CPM customization's to be triggered in the Process Designer. This is important to be able to suppress CPMs from running in various scenarios (including when using the Data Import Wizard), and when including SuppressExternalEvents in a ->save in your script. If these steps are not performed, the script can run unintentionally, and might even enter into a infinite loop (there is a limit reached with synchronous CPMs that will produce an error in such a case, and asynchronous CPMs can re-queue in a loop indefinitely). Make sure you specify both the 'Can Suppress' checkbox from within the Process Designer, and also pass whatever 'Suppress' value is applicable for the API used. For further details see Answer ID 7890: Enabling API suppression in Connect for PHP Customizations.
   
• When modifying custom objects or custom fields utilized by a custom process script, prior to deploying such a change the script should be unmapped from the configured object within the Process Designer and the scripts should be re-deployed as not mapped. Once the custom object/field deployment has completed the script should be re-mapped and changes re-deployed to complete such a change.
   
• To avoid production problems custom processes should be developed and tested on a test site, or clone of a production site, before implementing on a production site.
   
• The CPHP API is initialized by default in CPM customizations, and there is no need to add code for API initialization to CPM code. Further, adding unnecessary code for API initialization (such as the inclusion of Connect_init.phph, and the initConnectAPI function) can cause difficult to troubleshoot errors.
   
• It is important to escape the RightNow\CPM namespace when importing/aliasing classes within CPM customizations. This is typically done by including a leading slash when identifying classes with the PHP 'use' statement in custom code ("use \My\Classname;" for example). Similarly, using a leading slash when identifying the PHP Exception type ("\Exception" for example) is important if code is expected to catch any type of exception in a CPM customization.
   
• PHP shutdown callback functions, such as the use of register_shutdown_function, are not allowed/supported in CPM customizations.
   
• The PHP exit function should not be used in CPM code, and rather return statements can be used to exit functions and allow the CPM to complete normally.
   
• Global variables should not be used in CPM customizations. For further details see Answer ID 6701: Use of global variables in Custom Process object event handler scripts
   
• The API version used in all CPHP code must match, and this holds true for all external scripts used by a CPM customization. For further details see Answer ID 8655: Custom Processes must have matching version information between the annotation and included Connect library
   

• Ensure that any asynchronous CPM scripts using PHP curl have set the curl timeout to a value smaller than the maximum runtime for a CPM custom process script (157 seconds). A value of five seconds or under is highly recommended, as any external call through a CPM can cause queue delays in processing of the queue. There is a maximum of three asynchronous CPM processes running at a time, and if any of them are waiting on the response from an integration call this is going to reduce the speed that the queue is able to process. A value of 155 seconds is the maximum that should be used. The following is an example:

  curl_setopt($curl, CURLOPT_TIMEOUT, 5);

  For further details see Answer ID 11903:  Coding for PHP curl call timeouts and re-tries in CPM customiizations

• The utility that processes asynchronous CPMs may already have PHP curl loaded from a previous CPM run in the process. For this reason, we need to ensure that the following check is performed before loading the libraries, to prevent any code failures:

  if(!extension_loaded('curl')) { load_curl(); }

  For further details see Answer ID 10789: Use of load_curl() function in multiple scripts

• PHP file_get_contents is not allowed in CPM customizations. Use PHP curl instead.

• A database commit is run automatically after CPMs have processed. Add API commit statements to the code only when necessary, or if it will be somehow useful to troubleshoot a problem, as API commit statements in CPM code adds overhead to processing and can make troubleshooting at a deeper level (using server trace files when appropriate, for example) much more complex. API commit statements can be useful when using PHP curl, however, and for further details see Answer ID 11387: Commit before making cURL calls in a Customer Portal CPHP customization

• Excessive API save statements on the same object should be avoided, as each save can trigger CPMs and business rules (depending on the particular implementation). Extra saves add unnecessary processing overhead and result in added complexity when troubleshooting problems that may come up. Save the object after modifications have been applied, and before the CPM code completes.

• Do not destroy the object that triggered a CPM within the CPM code itself, as this is considered an invalid use case and will cause unexpected problems.

• For file-based logging, close resource handles promptly. This is particularly important if an asynchronous CPM customization is logging between save and commit operations. If the CPM were to be triggered concurrently for the same object, this could cause resource contention as one thread waits for the database lock and the other waits for the file handle.

Keep the following points in mind when testing an object event handler script before deployment:

• The test harness code will be run for each action defined in the comments/"flower basket" section of the script.

For further information refer to Answer ID 5169: Technical Documentation and Sample Code

Answer ID 6604:  There are two types of execution for Object Event Handlers

Answer ID 11934:  Alternatives to using CPM customizations for event-driven functionality that needs to happen immediately