Default Rules - NUUPDF

The Nucleus Default Rules (NUUPDF) page is used to define certain data elements that could default for users during data entry. Logic can be used to default in values for new records or updated records based on what has already been entered. Each default consists of two parts: VBScript and XML. The VBScript is used to create subroutines that are called when business rules are fired on a particular BT20 (table). The XML is used to define which routine is executed for each kind of event that can happen on a BT20.

The page is made up of three sections:

Entity List for navigating existing defaults. This is a list of each BT20's default that has been created. New ones can be added by clicking the "+" button in the navigation bar.
VBScript/XML Editor. This is where you can edit the default rules that are executed for the selected BT20.
BT20 Tree View. This view allows you to see the attributes for the selected BT20 that can be used in the VBScript/XML editors.

Entity List

The Entity List allows navigation of existing records and the ability to delete and create new ones. The navigation bar at the top of the page can be used to choose records or simply click the one you wish to view in the entity list with the mouse. When you are done editing a default (or creating a new default), click the Save button to save your changes to the database. Both the XML and VBScript are stored in the database in a BLOB to be accessed by the 7i server. When the save is complete, a Record Accepted message appears. At this time, the page has also notified the 7i server to reload the defaults it has loaded, so your new changes are ready to take effect. Any open 7i pages need to be closed and re-opened for the new defaults to take effect.

If you delete a record, it is permanently destroyed, and the defaults have to be recreated.

VBScript Editor

There are two separate tabs to define a default rule: the VBScript tab for editing the VBScript that runs when a business rule in 7i is fired, and the XML tab to tell 7i which routine to execute on a business rule.

The BusinessPlus defaults are written with the VBScript language. The editor highlights keywords for you to assist in writing your defaults. Once you make a change to the script and save the record, the changes take effect immediately in 7i. We recommend that you first test your script changes in a test account to avoid encountering problems in your live environment when developing your defaults.

There are some built-in variables and functions that can be used within your scripts:

Finance.CurrentRecord: The data structure that holds the current record on the page. Each column of the BT20 is defined on the data structure. See the screen shot below for an example on the PEPhoneDetail.
Finance.LastAddedRecord: The same data structure as above, but it contains the last record that was added through the 7i page.
Finance.SetValueOnce(property, value): Sets the named "property" on the BT20 to provided "value". If a second call to Finance.SetValueOnce is made within the same script, it does not update the value. Calling Finance.ResetValueList() allows additional changes to be saved.
Finance.ResetValueList(): Clears the set property list so that Finance.SetValueOnce() can set new values.
Finance.User: Retrieves the user id of the current user in the 7i page.
Finance.UserName: Retrieves the User Name off the us_usno_mstr.
Finance.UserDesc: Retrieves the User Description off the us_usno_mstr.
Finance.Manager: Retrieves the user's Manager off the us_usno_mstr.
Finance.Location: Retrieves the user's Location code off the us_usno_mstr.
Finance.CurrentScreenMask: Retrieves mask of the current 7i page.
Finance.ClientId: Retrieves the Client ID.
Finance.AddMode: Returns 1 if the page is in add mode, set to 0 otherwise.
Finance.FinanceVersion: Retrieves the current BusinessPlus version that the 7i server is running.
Finance.CurrentLedger.GlLedger: Retrieves the current user's GL Ledger.
Finance.CurrentLedger.JlLedger: Retrieves the current user's JL Ledger.
Finance.TranslateText: Retrieves translated strings for known tokens. For example, "\CD8" returns the date in YYYYMMDD format. Below is a list of acceptable values.

finance.TranslateText changes all "\xxxx", where:
\Xxxx = "G" GL side or "J" JL side
\xXxx = "K" key part, "O" object part
"L" Ledger, "B" Budget
\xxXx = "F" Fund
"X" Function
"O" Budget officer
"D" Description (S,M,L valid)
"1-8" Array part (S,M,L valid)
"A" Account Type
"B" Budget Category
"9-0" Array part (only valid for xBXx)
"W" Working Budget (S,M,L valid)
\xxxX = "S", "M", "L" short, medium, or long
\xTn = GL Account title from GEN master with n = "B" meaning both desc's.

Other options:
\xSnn = Subsystem ID (2 char.); n=01 through 10 for the 10 subsystems defined in GLG-GEN-MSTR
\xPnn = Period name; n=01 through 14
\xDyxxx = Symbolic Date conversion
y = Date Output Format (eg S-Z,6,8)
xxx = Symbolic Date (eg FYB,FYE,...)
\xMnn = Misc. Code desc.; n=01 through 08

Other non-ledger/AR-specific:
\USER = Upshifted USER ID
\CDx = Current date
Currently supported values of "x" date format:
T = MM/DD/YYYY
8 = YYYYMMDD
M = HHMMSS (time)

Script Examples:

Setting a field value if a condition is true: The below script is a sample for the PEAddrDetail which is the BT20 for the Address Detail in PE. In the InitNew routine, the script sets the zip code to “95973” and the city to ”Chico” if the user’s Location is set to ”CHICO”. Every time a user with this Location adds a new address record in PEUPPE, the city and zip will default in. Notice we call Finance.ResetValueList() first to ensure that our Finance.SetValueOnce() calls will take effect and save their values.

Sub PEAddrDetail_InitNew()

Call Finance.ResetValueList()

'Default in the City and Zip for users in the home office of Chico
If Finance.Location = "CHICO" Then

Call Finance.SetValueOnce("City","Chico")
Call Finance.SetValueOnce("Zip","95973")
Exit Sub

End If

End Sub

Setting a field value if a condition based on another field is true: The below is a sample for the PEAddrDetail’s PreAccept routine (see the XML tab section for more information on PreAccept). Notice we call Finance.ResetValueList() first to ensure that our Finance.SetValueOnce() calls will take effect and save their values. We then up shift the City on the current record and check to see if it equal to “CHICO”. If it is, we set the zip code to 95973.

Sub PEAddrDetail_OnPreAccept()

Call Finance.ResetValueList()

'Default in the Zip if the city is Chico
If UCASE(Finance.CurrentRecord.City) = "CHICO" Then

Call Finance.SetValueOnce("Zip","95973")
Exit Sub

End If

End Sub

Setting field values from the last added record: The below script is a sample for the PENameMaster which is the BT20 for the Name Master in PE. If a user is going to add more than one record in succession, we can set fields on the new record to what was previously entered to help speed up data entry. In the InitNew routine, the script first checks to see the user has previously added a record in the page. Then the various fields on the record are set on the CurrentRecord from the LastAddedRecord.

Sub PENameMaster_InitNew()

If IsObject(Finance.LastAddedRecord) = false Then

Exit Sub

End If

Finance.CurrentRecord.AffilCd = Finance.LastAddedRecord.AffilCd
Finance.CurrentRecord.Name = Finance.LastAddedRecord.Name
Finance.CurrentRecord.Nickname = Finance.LastAddedRecord.Nickname
Finance.CurrentRecord.Suffix = Finance.LastAddedRecord.Suffix
Finance.CurrentRecord.SecurityCd= Finance.LastAddedRecord.SecurityCd
Finance.CurrentRecord.PeId= Finance.LastAddedRecord.PeId
Finance.CurrentRecord.SaluteCd= Finance.LastAddedRecord.SaluteCd
Finance.CurrentRecord.SelCd1= Finance.LastAddedRecord.SelCd1
Finance.CurrentRecord.SelCd2= Finance.LastAddedRecord.SelCd2
Finance.CurrentRecord.Ssn= Finance.LastAddedRecord.Ssn
Finance.CurrentRecord.IdStatus= Finance.LastAddedRecord.IdStatus

ADVANCED - Setting values with TranslateText: The below script is a sample for the ARBirMaster which is the BT20 for the AR Batches in ARBTARUB. This script first checks the current page to be ARBTARUB. If it is not that page, the script exists. At the end, it checks the GlLedger code to be “GL”. If it is, it sets the “RefDt” equal to the current date in “MM/DD/YYYY” format with Finance.TranslateText(“\CDT”).

SubARBirMaster_AR_InitNew()

If not(CurrentScreenMask = "ARBTARUB") Then

Exit Sub

End If

If IsObject(Finance.LastAddedRecord) = false Then

Exit Sub

End If

Finance.CurrentRecord.RefDt = Finance.LastAddedRecord.RefDt

Call Finance.ResetValueList()

'Global settings for all users
If Finance.CurrentLedger.GlLedger = "GL" Then

Call Finance.SetValueOnce("RefDt",Finance.TranslateText("\CDT"))

End If

End Sub

ADVANCED - Reading NU Common Codes: This is an example of reading an NU Common Code from a default script and setting the “Addr3” (Address line 3) field equal to the Medium description of the NU Common Code. When reading NU Common Codes, you must specify all three columns, the Gr, Category, and CdCode or else the NU Common Code will not be fetched. A returned result of 1 from ReadByKey on a BT20 object means we successfully read the record we were searching for.

Sub PeAddrDetail_PreAccept()

Call Finance.ResetValueList()

dim codesReader
set codesReader = CreateObject("BT20.CDCodesMaster")

codesReader.Gr = "@@"
codesReader.Category = "PECO"
codesReader.CdCode = "US"

dim result
result = codesReader.ReadByKey()

'A result of one means we successfully read the record

If result = 1 Then

Call Finance.SetValueOnce("Addr3",codesReader.DescM)

End If

End Sub

ADVANCED - Issuing error messages: This is an example of how to issue an error message from a default. Please refer to the “7i System Documentation” on how to create your own custom errorcat with your error messages. The ErrorLevel can be set to a 1 for an error, 2 for a warning and 4 for informational. The below example is for a warning. The replaceable fields with the ”~” are not implemented from default scripts at this time. You may only issue static error messages.

Sub PEAddrDetail_PreAccept()

Call Finance.ResetValueList()

If UCASE(Finance.CurrentRecord.City) = "CHICO" Then

dim btError
set btError = Finance.AddErrorMessage("PE",32)
btError.ErrorLevel = 2

End If

End Sub

XML Editor

The XML editor is used to define which VBScript business rules are fired when certain events happen on a BT20. Below is an example of the PE Address Detail with a few routines defined. The XML needs to be defined in this specific way with the <XML> and <BUSINESSRULES> nodes. Remember, XML is case sensitive.

Creating an error with the XML definitions prevents 7i from saving records for that BT20.

XML Syntax

Below is sample XML with all of the available nodes defined that can be set to perform different actions on the BT20.

Node Definitions

<XML> Required starting XML tag.

<SORTS> Used to make client-defined sorts.

Here is a sample to sort the addresses by city:

Adding a sort on columns that are not indexed causes a big hit in performance.

<FILTERS> Not for use at this time.

<COLDATA> Used to specify which columns are required. Below is a sample to make City required on the PEAddrDetail:
<COLDATA>
<City><REQUIRED/></City>
</COLDATA>

<BUSINESSRULES> Used for executing business rules on a BT20 object when certain events occur on that object. The node directly under <BUSINESSRULES> must be the exact BT20 name that the default has been created for with a .1 on the end of it.

Example for PEAddrDetail:

Each triggering event node has a similar format with a RULEOBJECT node and a METHOD node. In all cases, the SCRIPTLOCATION attribute needs to be set to "Defaults". The SCRIPTNAME attribute needs to be the same name as the Default. The METHOD node's ID attribute is the name of routine you create in the VBScript for this default.

Example for PEAddrDetail:

Each node under the BT20 node is a triggering event on the BT20, which can fire a business rule from the VBScript that is created in the other VBScript tab. Below is each type of triggering event and when it gets fired:

<INITNEW> This executes a VBScript routine when in Add mode and a new record is initialized. The default 7i INITNEW fires first, then your custom one defined here can set any changes after.
<INITNEW>
<RULEOBJECT SCRIPTLOCATION="Defaults" SCRIPTNAME="PEAddrDetail">
<METHOD ID="PEAddrDetail_InitNew" />
</RULEOBJECT>
</INITNEW>

<TAGNAME> This executes a VBScript routine when the tags on the page are created. You can set the tag names (or field label) from your script. An IIS Reset on each web server when users are not connected must be performed, then start a new browser session for the tags on the page to take effect.

Script sample:

Sub PEAddrDetail_TagName()
Call finance.CurrentRecord.SetTag("ZIP", "Zip Code")
End Sub

If BusinessPlus is already setting the tagname, setting it in your own custom script does not override it. Setting it should only be done on additional fields you have added.

<AFTERFIELD> This executes a VBScript routine when a field on the page is left and its value has changed. For example, changing a field from "1" to "2" and tabbing out of that field triggers this event.

There is additional triggering information on this event. The <BT20OBJ> node is to signify that we are going to pass the BT20 object (CurrentRecord) into the routine. The <RETPROP> node below it specifies that we are going to allow changes to the PEID field and return its changes. The <TRIGPROP> node is used to specify which field triggers this AFTERFIELD method.

Script sample:

Sub PEAddrDetail_OnChangePEID_GLOBAL_001(Obj)
Call finance.ResetValueList()
'Global settings for all ledgers
Call finance.SetValueOnce("Addr1","123 Main St.")
End Sub

<PREACCEPT> This executes a VBScript routine when a record has been submitted by the page to be inserted or updated into the database. It triggers this business rule prior to the update/insert taking place. If the business rule has an error, the update/insert does not happen.

<PREINSERT> The same as PREACCEPT, except it is for inserted records only and not updated records.

<POSTINSERT> The same as PREINSERT, except it is triggered after a record has been inserted instead of before.

<PREUPDATE> The same as PREINSERT, except it is for updated records only and not inserted records.

<POSTUPDATE> The same as POSTINSERT, except it is triggered after a record has been updated instead of before.

<PREDELETE> The same as PREACCEPT, except it is triggered after a record has been deleted instead of before.

<SetControlProperties> Fields on the page can be given default behavior by setting them in the SetControlProperties node. An IIS Reset on each web server when users are not connected must be performed, then start a new browser session for the VBScript changes to take effect.

Below is a list of what can be set on each field. The PENameMaster's URL field was used as an example.

ScreenMask: Set this equal to the mask that you want this control property to apply to. Leaving it off applies to all masks.
Qbe: Set this equal to "1" to disable the control in Find mode.
Add: Set this equal to "1" to disable the control in Add mode.
Update: Set this equal to "1" to disable the control in Update mode.
Init: Set this equal to "1" to disable the control in when a record is first initialized.
Length: Set this to limit the length of accepted data in the control.
Enabled: Set this equal to "false" to allow setting the Update/Add/Init/Qbe attributes to "1" to disable.
PreserveCase: Set to false to upshift the control's values.

<TOOLS> Not for use at this time.

BT20 Tree View

The tree view displays BT20 information that can be used to help you write your VBScripts and XML definitions for defaults. Drag and drop any of the BT20 columns into the editor with the mouse. Double-click an item to insert it where the cursor is positioned.