Sage CRM Developers Course Validation Rules and Table and Entity Level Scripts

Sage CRM Developers Course

Validation Rules and Table and Entity Level Scripts

Looking ahead to the classes

DP01: Introduction to the Development Partner Program

DP02: Entities and the Data Model (Part 1 of 2)


DP04: Implementing Screen Based Rules (Part 1 of 2)


DP06: Screen and User Independent Business Rules

DP07: Workflow (Part 1 of 2)


DP09: Using the API Objects in ASP Pages (Part 1 of 2)

DP10 : Using the API Objects in ASP Pages (Part 2 of 2)

DP11: Using the Component Manager

DP12: Programming for the Advanced Email Manager

DP13: Using the Web Services API

DP14: Using the Web Services API (Part 2 of 2)

DP15: Coding the Web Self Service COM API (Part 1 of 2)


DP17: Using the .NET API (Part 1 of 2)


Agenda

Validation Rules

Screen and User Independent Business RulesTable Level and Entity Level Scripts including future change in support for Detached/Delayed Table Level scripts

Objects Available

Differences between Values() and FormValues() Collections

Availability of Contextual Information

Rollback behaviour

Validate Script

What are the Objects Available?Core Jscript Objects

Extensibility Module Objects

ActiveX Objects

What is the Scope of Effect?

What are the limitations?

Complex Rules

Validation Rules can support complex multi-row and inter-table rules

Example Wave Budget Validation Rule

var wavebudgetentered = Values('wave_budget');

var myRecordId = CRM.GetContextInfo('Campaigns','camp_campaignid');

var campaignsbudget = CRM.GetContextInfo('Campaigns','camp_budget');

var myRecord = CRM.FindRecord('Waves','wave_campaignid='+myRecordId);

var totalwavesbudget = 0

var brokebudgetbyamount = 0;

while (!myRecord.eof)

{

totalwavesbudget += Number(myRecord.wave_budget);

myRecord.NextRecord();

}

totalwavesbudget += Number(wavebudgetentered);

if (totalwavesbudget >campaignsbudget)

{

brokebudgetbyamount = totalwavesbudget - campaignsbudget;

Valid = false;

ErrorStr = 'You have broken the campaign budget by ' + brokebudgetbyamount;

}

else

{

Valid = true;

}

Validation Rules and onChange Rules

Rule onChange Validation

The field may only contain letters and numbers

var strRuleMessage = 'Field may only contain Letters and Numbers';re =/[Â-Za-z0-9]/;r = this.value.match(re);if (r){window.alert(strRuleMessage);}

var strRuleMessage = "Field may only contain Letters and Numbers";var strFieldData = Values("comp_customfield");re =/[Â-Za-z0-9]/;r = strFieldData.match(re);if (r) {Valid = false;ErrorStr = strRuleMessage;}

The field may only contain uppercase or lowercase letters.

var strRuleMessage = 'The field may only contain uppercase or lowercase letters';re =/[Â-Za-z]/;r = this.value.match(re);if (r){window.alert(strRuleMessage);}

var strRuleMessage = 'The field may only contain uppercase or lowercase letters';var strFieldData = Values("comp_customfield");re =/[Â-Za-z]/;r = strFieldData.match(re);if (r){Valid = false;ErrorStr = strRuleMessage;}

The field may only contain numeric characters.

var strRuleMessage = 'The field may only contain numeric characters';re =/[^0-9]/;r = this.value.match(re);if (r){window.alert(strRuleMessage);}

var strRuleMessage = 'The field may only contain numeric characters';var strFieldData = Values("comp_customfield");re =/[^0-9]/;r = strFieldData.match(re);if (r){Valid = false;ErrorStr = strRuleMessage;}

Using Validation Rules for other purposes

Validation on Search ScreensValidation rules are checked on submission of a search screen even though in this case no data is being inserted or updated.

For example the code below on the comp_name will ensure that it can't be left blank when searching for companies.if (!Values("comp_name")){Valid = false;ErrorStr = "you must fill in this field";}

Example Validation Log ScriptThe example below only needs to log which fields have changed not every field in the screen so we first need to know what fields are in the screen and then examine each field in turn. To do this I've used the fact that the screen object (EntryGroup block) is an enumerable object.

var ForReading = 1, ForWriting = 2, ForAppending = 8;var TristateUseDefault = -2, TristateTrue = -1, TristateFalse = 0;var mySystemObject = new ActiveXObject("Scripting.FileSystemObject");var myFile = mySystemObject.GetFile("c:/customlogs/TEST.TXT");

var myFileTextStream = myFile.OpenAsTextStream(ForAppending, TristateUseDefault);var oldName = "";var myBlock = CRM.GetBlock("CompanyBoxLong");var myE = new Enumerator(myBlock);while (!myE.atEnd()){oldName = CRM.GetContextInfo("company",myE.item());if (oldName != Values(myE.item())){myFileTextStream.WriteLine(oldName +"/"+Values(myE.item())+" changed by "+CurrentUser.user_logon);} myE.moveNext();}

myFileTextStream.Close();

Table and Entity Level Scripts

Four Types of Table/Entity Script

Table LevelDetached Table Level (Deprecated in Sage CRM v7.2)Developers should remove Detached Table Level scripts. Use Escalation rules and other scripts where possible.

Entity LevelEntity Level with Rollback

Objects used in Internal Scripting

Main Objects Other Objects

EntryGroup block is enumerable and it may provide us within a TableLevel script a simple way of checking if certain fields exist on the screen to see if they have changed value.

Entity Level Script Firing Points

Screen System Action EntityScript Function

New Company Newcompany Company InsertRecord()

Change Company

Companysummary

Company UpdateRecord()

Delete Company

Companysummary

Company DeleteRecord()

New Individual Newindividual Person InsertRecord()

Change Person

PersonSummary Person UpdateRecord()

Delete Person Personsummary Person DeleteRecord()

Edit Phone/Email

Phoneemail Email UpdateRecord()

New Address Address InsertRecord()

Edit Address Address UpdateRecord()

Delete Address

Address DeleteRecord()

Values() Usage

Values() FormValues() Reassign Values

Access QueryString

Create Script Can see data in form in View mode not Edit or Save

Can see data in form in Save mode not View or Edit

No both Values () – yesFormValues - no

Validate Script All submitted data defined in blocks used in form

All submitted data defined in blocks used in form

No both Values () – yesFormValues - no

Table level Script Only data in entity screen block e.g. company not address info

All submitted data defined in blocks used in form

Yes Values()No FormValues() -errors

Values () – noFormValues - no

FormValues() and Values()

The Values() collection Allows access the data within the fields associated with the EntryBlock (screen) used to build the edit screen for current record. – E.g. editing a company record you would use the CompanyBoxLong screen.

The FormValues() collection Allows access the data from within the whole of the HTML form submitted.

This means in a screen like the new Company screen when you are actually inserting data to several tables (Company, Person, Address etc) then you can access any of the submitted data. – E.g. So in an InsertRecord event function of an Company Entity script we could access the submitted

address information:

var strPostCode = FormValues("addr_postcode");

Validating Phone Numbers and Email Addresses

We can use an "Entity Level script with Rollback". Entity Level with Rollback scripts can be used when we want to stop an action happening if there is a validation error or other error with the script.

Need to consider

Data Entry

Data Update

Table Level Scripts

Example RuleIf the company is reassigned then reassign all opportunities for that company to that new personid.

The GetContextInfo() method returns the originally assigned user and the Values() collection contains the inbound userid data. When they are different, the record has been reassigned.

if (CRM.GetContextInfo('Company','comp_primaryuserid') != Values('comp_primaryuserid'))

{

var myCompRecordId = CRM.GetContextInfo('company','comp_companyid');

var strSQL = "oppo_status = 'In Progress' and oppo_primarycompanyid="+myCompRecordId;

var myOppoRecord = CRM.FindRecord('opportunity', strSQL);

while (!myOppoRecord.EOF)

{

myOppoRecord.oppo_assigneduserid = Values('comp_primaryuserid')

myOppoRecord.NextRecord();

}

myOppoRecord.SaveChanges();

}

Rollback & Table Level Scripts

Only Entity Level Scripts can rollbackValues() collection contains the new valuesCRM.GetContextInfo() returns the old value

Therefore you are be able to do this...

if (Values('data_whatever')==invalidValue)

{

Valid = false;

ErrorStr = CRM.GetTrans('capt_family','capt_code');

Values('data_whatever') = CRM.GetContextInfo('mytable','data_whatever');

}

Update of Data not submitted from Screen

The Values() collection can be extended to set a value for a field not in the screen.

function UpdateRecord(){

// Handle update record actions herevar strCompany = Values("comp_name");Values("comp_name") = strCompany.toUpperCase();Values("comp_mailrestriction") = 'Y';

}

Insert & PostInsert functions

Two 'Insert' event functions available to you within table level scripts.

InsertRecord()– InsertRecord() event fires as the record is created but before the database insert,

therefore the new unique id for the record is unknown.

PostInsertRecord(). – Have access to the records newly created unique id.– But can’t use

– CRM.GetContextInfo('datatable','data_dataid') – Record is new and is not in context at that moment.

– Neither can we use– Values() collection – Id has not been passed into the system.

Use of the WhereClause

In a PostInsertRecord() function

To obtain the newly created record id.

Use system variable called 'WhereClause'.

Contains after the creation of the record the literal string 'dataid=value' e.g 'lead_leadid=507'.

Variables & Objects

Field Level Scripts

Create Change Validate Table/Entity Scripts

CurrentUser P P P PValid P O P PErrorStr P O P PValues() & FormValues() P O P PWhereClause O O O P

External Triggering of Table Level scripts

Possible to trigger any Table Level script event function

Triggered byCOM API calls– ASP page extensions– Self Service extensions– Windows script– Mail Manager Scripts

SOAP Web Service calls

.NET API calls

Note: Table Level scripts may not be triggered by changes made by Exchange & ERP sync engines

ScriptCommonFunctions

In registry

ScriptCommonFunctions

reg key value

utils\myfunctions.js

Put filename you want. Assumed to be in the custompages folder or use path to subfolder.

Functions in the file will be added to every table level script at execution.

Note: May clash with existing ERP integration e.g. Sage 300 ERP

Q&AQ&A

Looking ahead to the classes

DP01: Introduction to the Development Partner Program





DP06: Screen and User Independent Business Rules



DP09: Using the API Objects in ASP Pages (Part 1 of 2)

DP10 : Using the API Objects in ASP Pages (Part 2 of 2)

DP11: Using the Component Manager

DP12: Programming for the Advanced Email Manager

DP13: Using the Web Services API

DP14: Using the Web Services API (Part 2 of 2)





Documents

Sage CRM Developers Course Validation Rules and Table and Entity Level Scripts