How To Use Control Files

This document discusses creating and using Control Files.

Control files allow you to attach a script to any field or form in the Collect! system. The script can do logical processing and then it can write the result onto the screen or into the database. This requires that you are familiar with Collect!'s Printable Field codes and that you have access rights to modify field properties in your database.

Control files open up a host of customization possibilities that let you tailor Collect! to suit your exacting requirements. To help understand how control/script files can help, here are two real life scenarios.

1. An international collections user wants to automatically select the correct operator based on the country the debtor resides in.

Solution: A control file attached to the Country field. When data entry personnel completes the Country field and presses Tab or Enter, the control file runs, and the correct operator is selected for the account.

2. Some accounts require special attention. We want the status field on the Debtor form to change color when the account is delinquent.

Solution: A control file attached to the Debtor form that changes the color of the status field depending on its value.

These simple examples show how control files can let you customize Collect! to an amazing level of detail.

Control File Operations

Control files can perform various operations:

1. Edit data in the database.

2. Change field attributes such as visibility, color, and captions.

3. Display a message to the end user.

4. Do whatever reports can do - define variables and
equations, perform calculations, write results to the database or display them to the screen.

5. Work at the Form and Field level.

Control files attached to forms are invoked just before the form is displayed.

Control file attached to fields are invoked as the user exits the field. Field level control files will execute on leaving a field if the field data has changed.

At the FORM level, control files run UNCONDITIONALLY. At the FIELD level, CONDITIONS CAN BE SET to determine when attributes change or calculations occur for the particular field.

User level 99 does not read control files. Please sign in as a user other than level 99 if you are using control files.

Edit And Set Commands In Control Files

Control files support the @EDIT and @SET commands.

@EDIT

This command edits the data in a database field. After changing the data in the field the record is immediately written to the database.

Syntax: @EDITde.u1 = {value}

value can be a variable, a database field or a date.

If you are changing more than one field in a record at a time, use the @SET command to alter the fields in the record, and only on the last change should you use the @EDIT command.

Typically control files use the @SET command. The @EDIT command is only needed when you actually want to physically write an updated record to the database. Since control files trigger off the 'current' record, you should generally use the @SET command and only use the @EDIT command when altering data in related records.

@SET

This command changes the value in the selected field of the database record, but does not write the record to disk until you exit from the form.

Syntax: @SETde.na = {value}

value can be a variable, and database field or a date.

Typically control files use the @SET command. The @EDIT command is only needed when you actually want to physically write an updated record to the database. Since control files trigger off the 'current' record you should generally use the @SET command and only use the @EDIT command when altering data in related records.

Log To Notes

You should use @SET when your control file is on a field and you also want to Log to Notes when modifications have occurred. For instance, the Set Timezone sample uses a control file on the Debtor Home field to change the Time Zone. By using @SET in the control file, instead of @EDIT, we ensure that changes to the phone number are still logged to notes.

Changing Field Attributes With Control Files

Field attributes can be changed through control files. Examples are Color, Caption, Rights.

In the script, these would be referred to as follows:

de.na.color

This means the color attribute of the Debtor Name field.

de.na.caption

This is the label attribute of the Debtor Name field.

de.in.rights

This is the access rights attribute of the Debtor Interest field.

COLOR

Setting this attribute changes the color of a field. Colors are defined as #RRGGBB in hexadecimal form, as in standard HTML color usage.

Syntax: @SETde.na.color = #RRGGBB

RR is a hexadecimal Red color component between 0 and 255 (0 to FF hex).
GG is a hexadecimal Green color component between 0 and 255 (0 to FF hex).
BB is a hexadecimal Blue color component between 0 and 255 (0 to FF hex).

Example:

// control file to set color of Debtor Name field

@SETde.na.color = #3399FF

// End of file

Please refer to Color Chart for a quick reference to sample colors that you may use and to Using Color In Collect! for additional examples.

You cannot change the color of the Debtor's Mode field using a control file.

RIGHTS

Set this attribute to control whether a field on a form is hidden, read only or able to be edited by the user.

Rights are defined as:

0 = Full
1 = No Delete
2 = Read Only
3 = No Access

// Set at FORM level to grant Read Only access to the Debtor Status field

@SETde.sta.rights = 2

// End of file

CAPTION

Set this attribute to change the caption of a field.

Example:

// Set this at FORM level in the Attachment form to change the label of the Index 1 field.

@SETat.i1.caption = "Driver's License"

// End of file

You may need to put the caption in quotes to get this to work.

Control File Examples

The following snippets give examples of ways that you can use control files to

- alert the Operator regarding certain accounts
- change the appearance of a form
- write a value to a field in a form

This is a fairly technical subject. Writing the scripts for control files requires a familiarity with the various commands that can be used in the report writer. You may have to experiment a bit to get the results you need.

When a control file changes the value or appearance of a form or field, you may have to go off the form and back on to see the effects.

1. Change Debtor Status

If the status is PRA, we may want to make the color of the Status field green.

// Set this at the FORM level

@SETde.sta.color = #FFFFFF
@SETde.sta.color = #00FF00 if (@de.sta = PRA)
@SET de.sta.color = #FFFFFF if (@de.sta <> PRA)

// End of file

We make the default color white before deciding what else to do. We set a color for our TRUE condition and one for all other cases.

2. Debtor Delinquent

This Control File will change the color of the Debtor Delinquent field on the Debtor form.

Set at FORM level.

// Control file for Debtor Delnqnt
// Please add your report snippet below.
// This field can contain up to 10 numbers without a decimal.

@SETde.de.color = #99FF99 if (@de.de > @d-30)
@SETde.de.color = #00FFFF if (@de.de <= @d-30)

// End of file

When the Debtor Delinquent is within the past month, the color of the field changes to green. When the Debtor is over a month delinquent, the color of the field changes to blue.

3. Debtor Range

This Control File can be used to identify Debtors in a range of file numbers. Different colors can be used to indicate different ranges.

Set at FORM level.

// Control file for Debtor Client
// Please add your report snippet below.
// This field can contain numbers.

@SETde.na.color = #FFFFFF
@SETde.na.color = #CCFF00 if (@de.fi < 11000)
@SETde.na.color = #CC99FF if (@de.fi = 11000 .. 13999)
@SETde.na.color = #FFCCCC if (@de.fi = > 13999)

// End of file

This snippet changes the color of the Debtor Name field (@de.na) depending on the Debtor File Number (@de.fi).

4. Attachment

This Control File changes the labels of fields on the Attachment form depending on the value chosen from the Class field pick list. For the examples below to work, the Class field pick list needs to be edited to add Invoice and Assets to the existing list.

Set at FORM level.

Here is an example of script to change the caption of the Index 1 field to Invoice # or Assets and the caption of the File field to View Invoice or View Assets. Notice that strings are enclosed in quotes.

// Control file for Attachment
// Please add your report snippet below.
// This field can contain numbers.
//The first two lines below initialize the default captions

@SETat.i1.caption = "Index 1"
@SETat.fi.caption = "File"
@SETat.i1.caption = "Invoice #" if (@at.cl = Invoice)
@SETat.fi.caption = "View Invoice" if (@at.cl = Invoice)
@SETat.i1.caption = "Assets" if (@at.cl = Assets)
@SETat.fi.caption = "View Assets" if (@at.cl = Assets)

// End of file

In the above snippet, the line "//End of file" must be included to tell Collect! to stop looking. So make sure you include it.

If the user chooses 'Invoice' from the Class field pick list (@at.cl), the caption of the Index 1 field (at.i1) will change to "Invoice #" and the text in the File field will read "View Invoice".

If the user chooses 'Assets' from the Class field pick list, the caption of the Index 1 field (at.i1) will change to "Assets" and the text in the File field will read "View Assets".

You will have to go off of the attachment for the change to register. In the future, when you open this particular attachment, the labels will display the correct captions according to the choice displayed in the attachment Class field.

5. Debtor Other Phone Number Written To User 1 Field

This Control File will put the Debtor Other Phone number in the Transaction form in the User 1 field.

By default, Collect!'s Check reports use User 1 for the Check Number. If you plan to use the check printing features, you would need to modify the check reports to take the check number from one of the other User fields on the Transaction form.

Set at FORM level

// Control file for Transaction
// Please add your report snippet below.
// This field can contain numbers.

@EDITtr.u1 = @de.ot

// End of Control File

This control file will run whenever the transaction is opened to view.

6. Using Variables With Control Files

You can also use variables with control files. The following snippets are set at the FORM level, using variables. In this example, the color of the Status field will change to GREEN if there have been more than 3 phone calls made to the debtor.

// Control file for Debtor
// Please add your report snippet below.

@varPHO# = 0
@de.con no total where (@co.ty = Phone)
@varPHO = @(varPHO+1) if (@co.do = Yes)
@de.con
@SETde.sta.color = #FFFFFF
@SETde.sta.color = #00FFFF if (@varPHO>3)

// End of file

7. Pick List

Use these commands to dynamically attach a Pick List to a field.

This only works with pick list files that are numerically named, such as 11.pck or 333.pck. It does not work with alpha-names such as attach.pck or myown.pck.

Example 1:

Set at FORM level.

// Attach pick list to Debtor state field - FORM level

@SETde.st.picklist = 1.pck

// End of file

In the example above, the pick list (1.pck) needs to already exist in the system so that you can use it. For more information about creating a pick list please refer to How To Modify Or Create A Pick List.

Example 2:

Set at FIELD level with conditions declared with an IF statement.

//Attach pick list at FIELD level with conditions and range.

@SETde.st.picklist = 15.pck if (@de.zi = 04000 .. 16999)
@SETde.st.picklist = 11.pck if (@de.zi = 89000 .. 95999)

// End of file

For the above example the following two pick lists were created.

//Pick list (15.pck) for Zip Code range 04000 .. 16999

" New York"
"Maine"
"Washington DC"
"New Jersey"

//End of File

//Pick list (11.pck) for Zip Code range 89000 .. 95999

"California"
"Nevada"
"Arizona"

//End of File

Please refer to How To Modify Or Create a Pick List for information on creating these pick lists.

Messaging

You can use a control file to display a message to the end user when a certain condition is encountered.

For example:

This control file will display a message alerting the operator that the account has been worked today.

Set at the FORM level.

@tvarText* = ""
@tvarText2* = ""
@varDate! = @d
@tvarText = "Don't phone this debtor. Already worked today."
@tvarText2 = @tvarText if (@de.wo = @varDate)
@message(@tvarText2)

//End of File

Message Displayed by Control File

Troubleshooting Control Files

Control Files take effect ONLY when you are signed in as a user with a level other than 99. If you are signed in as an operator with User Level 99, you will not see any changes you have made to field labels and you will not invoke any code to edit fields and perform calculations. Please make sure your operators have a valid User Level other than 99.

Run Contact Plan From Control File

You can run a contact plan from a control file using the command @RUNPLAN

SYNTAX:

@RUNPLAN({record},{planID}) {if ( @var = n )}

{record} = Either Client or Debtor
{planID} = Contact plan code
{if conditional} is optional and behaves normally

EXAMPLE:

@RUNPLAN(Client,REV)

This would run the REV contact plan on the Client who is current when the report or control file is executed.

{planID} can also be a variable.

For example, @RUNPLAN(Debtor,@varPlan) where @varPlan is set elsewhere in the report.

The optional "if" conditional works just as it does normally.

For example:

@RUNPLAN(Debtor,CLO) if ( @de.ow < 1.00 )