What best practices and guidelines should be followed when developing customizations using the CPM/Process Designer?
Process Designer, Custom Processes (CPM)
All product versions
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. It is advantageous for several reasons for CPM customizations to use the CPM Logging product feature. 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 on the process designer and including SuppressExternalEvents in a ->save in your script. If these steps are not performed, the script might re-enter itself in an infinite loop. Make sure you specify both the 'Can Suppress' checkbox from within the Process Designer and passing whatever 'Suppress' constant is applicable for the purpose of the affected CPM to the save method. 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 Connect for PHP API is already initialized and authenticated behind the scenes in a CPM customization, and therefore the initConnectAPI and related statements should not be included in CPM code.
- 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 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. A value of 155 seconds is the maximum that should be used. The following is an example:
- curl_setopt($curl, CURLOPT_TIMEOUT, 5);
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.