Describes UDFs, describes some uses for them, and then provides a simplistic guide to setting them up and accessing them.

UDF stands for User Defined Field. This is a piece of code the user can add to Cyrious to capture information not available in CFL. With UDFs you can do things like capture information about a Customer providing guidelines about product parameters. For example, a UDF to flag that a customer requires “Blind Shipments” can be integrated with a shipping product and even have the product look to a customer UDF to determine the preferred carrier and the ship code to be billed to that customer. Other uses might be to flag certain conditions for Work Orders and Estimates which control they way Crystal prints a work order or what is on it. For example, we have a section at the top of our work orders which shows initials of all the production centers required to complete the order which is done by setting Transaction UDFs to True when certain products are selected – routing, engraving, printing, etc. This is also used to provide schedules for each of those centers. The more you understand UDFs, in fact, the more applications you find for them.

For transaction UDF's, these must be set in the advanced tab of the Product Pricing page. Open the Advanced Tab and, depending on whether you want the macro executed in an Order or Estimate, select either “Order/Recurring Order Save Formulas” or “Estimate Save Formulas”. In each of those tabs you can select where to put the CFL to set the UDF, depending on when you want them set. Below is an example of Code set in the Order/Recurring Order Save Formulas/On Order Edit page. For these settings, you can create a list of conditions each ended with a semi-colon (;) and CFL will execute them all. Note that for settings dependent on selections within the “Product”, we have found it a good idea to create code to reverse the UDF setting if the transaction is altered with later edits. In other words for the example below, the UDF will always be set if the product has been selected. The“ Check PMS Colors” UDF will be set only if those selections are made on the Pricing Form. To unset the “Has Digital Printing” UDF, we set the UDF to False in the “On Line Item Deleted” CFL page. Be sure to test all code carefully. If the UDF name in these formulas does not match exactly, the formula will not work. Even a space will prevent CFL from finding the UDF –E.G. in the example below SetTransactionUDF(“ Check PMS Colors”) will fail because of the space between the quotation marks and the “C”.

SetTransactionUDF("Has Digital Printing", TRUE);
    DTS_CheckPMSColors THEN SetTransactionUDF("Check PMS Colors",TRUE)
    DTS_ColorsToMatch  "" THEN SetTransactionUDF("Check PMS Colors",TRUE)
   DTS_NumberOfColorsToMatch  0 THEN SetTransactionUDF("Check PMS Colors",TRUE)
  1. The UDF features are accessed from the Setup Menu by clicking on User Defined Field Setup. That brings up a page (See Screen Shot below) showing a column of UDF types on the far left. You will note that they are categorized as Company, Contact, Transaction, Part, Product. The UDFs in these categories appear in a UDF tab when you go to the form for that category. For example, when you create a transaction –Work Order or Estimate – you will see a tab with all the UDFs for transactions.
  2. The UDF Layout section at the bottom of the UDF list provides a way to create attractive or functional groupings of your UDF fields. It is analogous to a pricing form for UDFs.
  3. You create a UDF by navigating to the category for the UDF you are creating – e.g. Transaction – and then clicking on the Add button. You will get a menu asking for a name, type, etc. You may have spaces in the name of a UDF but a caution– the code to access these UDF requires you to use the name in quotation marks. You will thank yourself for very short and simple names, preferably of one word only.
  4. When creating the UDF, you must also decide what type. As with cfl_ch_5-variables, you can select YES/NO (cfl_ch_2-the_cfl_language), List, Number, Date, etc. Be very careful to choose the correct designation for how the UDF will be used.
  5. For UDFs containing Lists you also have the choice to create the List and prevent Users from adding to them or the opposite. The list will grow as Users enter additional items.

Below is a screen shot showing the UDF Setup Page with a new Transaction UDF being created: Note the checkboxes providing options for where you want this UDF to be available – For Orders, Estimates, etc. Other extremely useful options allow you to clear the UDF when cloned or when an Estimate is converted to an Order.


  1. The UDF field is accessed through cfl_ch_2-the_cfl_language according to the type it is.

Transaction UDFs: TransactionUDF("Architects")


CustomerUDF("Blind Ship")

The following are some examples which are in the Formula Builder.

  1. You can integrate these UDF fields into your code for the kinds of uses noted above. Below is the code > we use to determine if a customer requires us to use his Shipper and, if so, the Ship Code which will cause them to be billed directly for the shipment. This code is inserted in the Use Formula field of a Yes/No Variable which is then used on the Pricing Form. If the UDF is checked in the Customer Record, then this will open as checked in the pricing form. Note there are 2 entries for this code–the name of the UDF and a second entry which is what will be returned if the UDF is not found. The Company UDFs, like the others, are available for all company records; so if a customer decided he would like his carrier used, the Shipping Clerk or Salesperson or whomever is appropriate simply opens the Customer record and enters the data. If written properly, all future Ship Tickets will be created with this information.
  2. The code below shows how the data was captured for the pricing form shown at the bottom. The Variables assigned to the Pricing Form objects “Use Customer Carrier”, the Carrier Name, and the Carrier Code were drawn from the UDF fields. Importantly, if the Customer has been selected for the Estimate or Work Order, these fields are filled out as shown when the Product Pricing Form is opened. This information is also integrated into the Pricing formula so that customer is charged only “handling” and not the full ship charge.
Used in Yes/No Variable:
COMPANYUDF( "Always Use Customer Shipper",0)
Used in Text Variable
Used in Text Variable
COMPANYUDF( "CO Shipper","")


  1. Transaction UDFs can now be overridden.
    1. A new “Default Formula” field will allow you to enter a CFL formula that can be used for setting a UDF's default value.
    2. When a UDF's value has changed, the field becomes overridden and a small 'x' appears on the right hand side of the field to allow the default value to be restored.
    3. Once overridden, a UDF will remain overridden until it has been restored by clicking the small 'x'.
  2. Transaction UDFs can now be recalculated.
    1. In the bottom right-hand corner of the UDF tab you will notice a “Recalculate” button. When the Transaction is being edited, the button is enabled and, when clicked, will reevaluate all non-overridden UDFs.
    2. In addition to being manually recalcuated by using the “Recalculate” button, Transaction UDFs now reevaluate while being edited when:
      1. Other UDFs have changed.
      2. A line item is added.
      3. The Transaction's customer has changed.
    3. When not editing, Transaction UDFs recalculate when:
      1. Cloning an Order or an Estimate.
      2. A status change occurs.
      3. A payment is applied.
  3. New functions and extended CFL functionality include:
    1. TransactionUDFIsOverridden(
    2. TransactionUDFIsAssigned( CompanyUDFIsAssigned( ContactUDFIsAssigned(
    3. TransactionUDFObject( CompanyUDFObject( ContactUDFObject(
    4. SetTransactionUDFObjectID( SetCompanyUDFObjectID( SetContactUDFObjectID(
    5. Local Object References: Just as before when using “Order.OrderNumber”, you can create a local variable that is the equivalent to Order. For example,
      1. Declare X := TransactionUDFObject(“Shipment Date”);
      2. X.OrderNumber;
  4. More information on the CFL enhancements can be found cfl_reference.

Contributor: Steve Gillispie, Acorn Sign Graphics

Date: 02/05/2010

Version: Control 4.3

You could leave a comment if you were logged in.