Using the Formula Extractor to Create Custom Functions

The Formula Expert enables you to create formulas from existing custom functions. The Formula Extractor does the exact oppositeit enables you to create custom functions from previously created formulas. This functionality is accessible by creating a new Custom Report Function and selecting the Use Extractor button. Figure 4.23 displays the Extract Custom Function from Formula dialog accessed when creating custom report functions.

Figure 4.23. The Extract Custom Function from Formula dialog enables the creation of a custom function from an existing formula.

By using the Formula Extractor, it is possible to migrate existing formula logic from a formula field into a custom function. The appropriate part of the migrated formulas can subsequently be replaced with the new custom function and eventually be added to the Crystal Repository.

To create a custom function from an existing formula using the Formula Extractor dialog, follow these steps:

1. In the Formula Workshop, create a new Custom Report Function. Select the Formula Extractor by clicking on the Use Extractor button after you have ensured that the custom function name you have selected follows your personal or organization's standard naming convention.
    
2. Edit the default argument names (v1, v2, and so on) and descriptions that represent the required parameters for the new function. These argument names and descriptions should communicate the expected information to future users of the custom function. The importance of meaningful information here cannot be underestimated with respect to the future usefulness of the newly created custom function.
    
3. Add an appropriate summary description to the Summary window so that future report designers using this custom function will understand its proper use.
    
4. Click on the Modify Formula to Use New Function check box (in the lower-left area of the Extract Custom Function dialog) to place the new custom function into the formula on which you are basing it. This is not a mandatory step, but it is a nice feature that quickly enables you to take advantage of the reusability of your new custom function.
    
5. Click the Enter More Info button to add additional support information for the custom function. Figure 4.24 displays the More Info dialog.
    

   Figure 4.24. The Custom Function Enter More Info dialog enables the specification of supporting information for the newly created custom function.

   

    
6. Enter the custom function author (likely yourself) and custom function category information in their respective text boxes.
    

   NOTE

   When entering a custom function category, it is possible to create it at more than one level of subfolder depth by using forward slashes in the Category text box. For example, by entering MapleLeafBikes/HR, the newly created formula will be added to the Custom Function library under the Maple Leaf Bikes category and the HR subfolder. By adding and maintaining your custom functions in a logical hierarchy, future users will find accessing them much easier.

7. Optionally, set default values for your custom functions arguments by clicking on the default value cells and filling in the Default Values dialog.
    
8. Add Help text describing the custom function by clicking on the Help Text button. Again, it is important to consider future report designers using this custom function when deciding on the detail that you should include in this description.