Data Policies

From LongJump Support Wiki
(Redirected from Data Policy)

Designer > Objects > {object} > Data Policies

Data policies model your business rules and enable automation of processes around data records. They let you define a series of checks and validations, automatically update dependent data, send emails, and carry out many other tasks. For example, when a Prospect is converted to an Account, you could automatically send emails to related Contacts to say thanks or congratulations.

About Data Policies

A data policy lets you make things happen automatically in a variety of circumstances. Data policies have a variety of attributes that determine how and when they execute, how many things they do, and what kinds of things they do:

Activation Type
The way in which the data policy is initiated. There are two activation types: Action-Based (somebody did something) and Calendar-Based (an alarm went off).
Triggering Criteria
When a data policy is activated, the triggering criteria is checked to see if the policy should "fire" (execute). By default, a policy always executes. But by specifying different criteria, you can cause the policy to execute only under certain conditions--for example, based on data in the record, who the current user is, or what role they play.
Data Policy Actions
The things the data policy does when it executes. Multiple data policy actions can be defined for any given data policy.

Action Based Data Policies

Thumbsup.gif

Tip: When you hear "action-based", think "event-based". This kind of data policy is initiated by a "triggering event". That event can be an Action-button in the GUI, or it can be one of several other kinds of events.

An action-based data policy:

  • Can be triggered by one or more events.
  • Can be conditioned to fire only when certain conditions are met.
  • Can be invoked before or after a record is applied to the database.
  • Can be invoked before or after batch updates.
DataPolicy-ActionBased.png
Activation Sequence
An action-based data policy can be set to execute either before or after the triggering event. For example:
  • Before adding or updating – Validate the incoming data, accept it or reject it by throwing an exception
  • After adding or updating – Update Related Objects
Triggering Action
One or more events can be chosen to trigger a data policy.

Notepad.png

Note:
The Import Batch event occurs before a data import starts, or after it ends.
The Import Record triggering event occurs before or after a record is imported.

Examples of Action Based Data Policies
  • In a sales department, the local sales representative automatically receives an email notification when a prospective client requests information from the organization's web site. The data policy is triggered by the addition of a new record (prospect), choosing the email recipient based on the territory.
  • In a manufacturing operation, the parts department wants to know if the inventory on a popular part is low. The data policy is triggered by an update to the quantity of units in inventory.
  • When adding new records, validate the address/phone/email fields before allowing the records to be added to the database
  • When importing records (leads file from a tradeshow, for example), verify that the record is not a duplicate of any already existing person/company

Learn more: Build an Action Based Data Policy

Calendar Based Data Policies

Calendar based data policy actions are triggered on a schedule, defined by the following parameters:

  • Start Date and Time
  • Non Repeating or Repeating (Daily, Weekly, Monthly, Yearly)
  • End Date or Never-ending

Thumbsup.gif

Tip: A job will start at the time you specify. But the time it takes to complete depends on the system load, so it's a good idea to schedule actions well in advance, to ensure that it completes at the desired time.

Examples

  • Drip Campaigns use Calendar-based data policies. These policies detect values and conditions of the data fields and based on them, execute a combination of actions including: sending an email, assigning a task, updating the record content, delivering a Send Outbound message to an external system, or running Java code.
  • In a front-desk reservation system, set the criteria to verify that the check-in date must be in the future (after Today) and that the check-out date follows the check-in date
  • In a doggy daycare system, check that the pet owner's account has enough pre-paid credits for that week's care

Learn more:

About Policy Triggering Criteria

To see if a data policy should be triggered, tests are run on its Triggering Criteria. There are three kinds of criteria you can specify, alone or in combination:

Date Criteria
Trigger the policy when one of the standard date fields in the record (date created, date modified, or date of change in workflow state) or when one of the custom date fields defined in the object is within a specified date range:
  • Within the current, next, or previous week, month, or day.
  • Within a specified calendar year or calendar quarter.
  • Within a specified Financial Period.
Field Criteria
Trigger the policy when one or more fields compare successfully against specified values. (For example, order_total > $5,000.)
Formula-based Criteria
Create a formula-expression from a combination of object fields and User fields, where the user is the person performing the action on the record.

Considerations

  • If no criteria are specified, the criteria resolves to TRUE. (The actions associated with the Data Policy are always performed.)
  • If a combination of criteria is specified, all of them must return true for the Data Policy to fire.
  • Formula-based Criteria are Expressions, which must resolve to TRUE or FALSE
  • If the Expression described by the criteria is FALSE, the associated actions are not applied. If TRUE, the Data Policy is executed, and any associated Actions are invoked.

Field and Formula Triggers

In these examples of criteria expressions, note that the Field Display Type and Formula Function are used together to create a Logical result for the Policy Triggering Criteria.

These examples are presented as questions, because the result must be Logical: YES/NO or TRUE/FALSE.

Example Expression
Is the submitted date more than seven days before the departure date?
DATECOMP(departure_date, submit_date) > 7
Note that the Field Display Type is DATE for both arguments
Is the inventory count less than 25?
Inventory_Count < 25
In this example, the Field Display Type for Inventory_Count is NUMBER
Is the inventory value missing?
Inventory_Count = BLANK
The test for an empty numeric or date field is BLANK.
Is a text field empty?
state = ''
The test for an empty string is two single quotes (''), not the double-quote character (").
Learn more: Filter Expressions in Reports and Data Policies

Triggering Criteria in Action Based Data Policies

This list describes the action triggers, and eligible objects:

Note: Data policies can be created for all objects, except Products and Price Books
Trigger Triggered when... Eligible Objects
Add Adding a new record All
Update Updating an existing record All
Delete Deleting an existing record All
Ownership Change Changing a record's owner All, except Tasks/Appointments
Workflow State Change Changing a record's workflow state All
Import Batch During a batch import All
Import Record During a record import All, except Tasks/Appointments
Signed This event occurs when a record is signed using a Digital Signature All
Unsigned This event occurs when a signature is invalidated. It also occurs when a user clicks Verify Signature on an invalid signature. All
Merge When converting a Prospect to an Account with the Merge option Prospects and Accounts Only
Convert to Account When converting a Prospect to an Account without the Merge option Prospects Only
When Due When a Task or Appointment becomes due Tasks/Appointments Only

Triggering Criteria in Calendar Based Data Policies

Calendar Based Data Policies offer additional date-driven triggers that don't depend on any particular action.

About Data Policy Actions

Things to know:

  • Multiple data policy actions can be specified for a data policy
  • Several types of data policy actions can be executed
  • They can be invoked in any order (or reordered as needed)
  • In a Calendar Based Data Policy, all of the following actions are available
  • In an Action Based Data Policy, the Activation Sequence determines which actions are available
Actions Description Activation Sequence

Before Triggering Actions (Pre)

Activation Sequence

After Triggering Actions (Post)

Create Task Create a task and assign it to selected users (Record Owner, Supervisor of Record Owner, Specific User, System Administration) Checkmark.gif
Send Email Send an email message based on roles; optionally, send the message to an individual email address Checkmark.gif
Change Record Owner Change the record owner, reassigning the record and effectively managing data flow Checkmark.gif
Add Record Select an object to add a record to, and choose whether or not to execute data policies triggered by the addition. Checkmark.gif
Update Record

Update the record; change the value of any field, using any formula you define.

In addition to fields in the current record, you can specify fields in Lookup-target records using "dot notation". For example, a data policy action for an Order record could update a field in a related Customer record: related_to_Customer.email_address. (In the GUI, Lookup fields appear with a ">" after the name. Clicking one opens a new list box opens that displays fields from the target object.)
Learn more: Updating a Field in a Related Record during a Data Policy "Update Record" Action

Important:
This action does not generate record update events (in order to prevent infinite recursions).
Checkmark.gif
Send Outbound Message With this data policy action, REST messages can be sent to a valid end point Checkmark.gif
Post Item to Relay Feed Post a message to a Relay Feed. (All existing feeds are available.) Checkmark.gif Checkmark.gif
Assign Follower in Relay Assign a user as a follower of a record (Available if Relay is enabled for the object.) Checkmark.gif Checkmark.gif
Remove Follower in Relay Remove a user as a follower of a record (Available if Relay is enabled for the object.) Checkmark.gif Checkmark.gif
Invoke Java Method Invoke a method in a Java class Checkmark.gif Checkmark.gif
Execute Java Code Execute a custom data policy action by writing Java code and making calls to the Java API Checkmark.gif Checkmark.gif

Add a Data Policy

  1. Click Designer > Objects > {object}
  2. Click the Data Policies tab
  3. Click the [New Policy] button
  4. Enter the following information:
    Name
    Policy name
    Enabled
    Check the Enabled checkbox Checkboxicon.gif icon to enable the policy
  5. Select the Activation Trigger:
    Action Based
    Calendar Based
  6. Follow the instructions in sections below to build an action-based or calendar-based data policy.

Build an Action Based Data Policy

  1. Complete the steps to Add a Data Policy.
  2. Fill in the information described below.
  3. Click [Save]
Policy Information
Activation Sequence
Choose whether to invoke the policy before or after the triggering actions occur, depending on what goals the data policy needs to achieve:
Writes (adds, updates, deletes)
Before Triggering Actions Validate data before committing the action to the database. For example: Prevent the addition of duplicate records, or verify that an essential field is not empty.
After Triggering Actions Take some action based on the data in the record. For example: Send an email when a count exceeds some threshhold.
Triggering Action(s)
Choose to invoke the data policy when any of these activities are applied to a record in the current object. Learn more: Available Triggers and Eligible Objects
  • Add activates the policy when a record is added
  • Update activates the policy when a record is updated
  • Delete activates the policy when a record is deleted
  • Ownership Change activates the policy when a record changes ownership (not available in Tasks/Appointments)
  • Workflow State Change activates the policy when the workflow state changes
  • Import Batch activates the policy during a batch import
  • Import Record activates the policy when a record is imported
  • Merge activates the policy when the Merge option is selected while Converting Prospect to Accounts
  • Convert to Account activates the policy when converting Prospect to Accounts
  • When Due activates the policy when a Task or Appointment becomes due (on End Date) (only available in Tasks/Appointments)
Run As
Executes an action using the permissions of the specified User, (not the User creating the data policy, or the User who causes the data policy to fire); Choose a User with the required Data Access Permissions to carry the actions defined in the policy.
Date Criteria (optional)
  • Select a field (Date Completed/Date Created/Date Modified/Due Date)
  • Select an operator to specify a range of dates
  • Optionally, add additional date criteria
Field Criteria (optional)
  • Specify fields and values to check for.
  • Combine field checks into logical expressions using AND, OR, and parentheses
Formula-Based Criteria (optional)
Specify Filter Expressions:
  • Select fields, operators, and functions.
  • Type literal values in single quotes to complete the expression.

Notepad.png

Note:

  • When building a formula, click the [Check Syntax] button to validate the expression.
  • Remember that Policy Triggering Criteria expressions must resolve to a Logical type.

Build a Calendar Based Data Policy

  1. Complete the steps to Add a Data Policy.
  2. Fill in the information described below.
  3. Click [Save]
Policy Settings
Activation Date
The date to start the actions
Activation Time
The time to start the actions
Repeating Frequency
Select a Repeating Frequency option to schedule repetitions.
Run As
Executes an action using the permissions of the specified User, (not the User creating the data policy, or the User who causes the data policy to fire); Choose a User with the required Data Access Permissions to carry the actions defined in the policy.


Date Criteria (optional)
  • Select a field (Date Completed/Date Created/Date Modified/Due Date)
  • Select an operator to specify a range of dates
  • Optionally, add additional date criteria
Field Criteria (optional)
  • Specify fields and values to check for.
  • Combine field checks into logical expressions using AND, OR, and parentheses
Formula-Based Criteria (optional)
Specify Filter Expressions:
  • Select fields, operators, and functions.
  • Type literal values in single quotes to complete the expression.

Notepad.png

Note:

  • When building a formula, click the [Check Syntax] button to validate the expression.
  • Remember that Policy Triggering Criteria expressions must resolve to a Logical type.

Add Actions to a Data Policy

To specify the actions that occur when the Data Policy is executed:

  1. Click Designer > Objects > {object}
  2. Click the Data Policies tab
  3. Select an existing Data Policy or click [New Policy] to create a new one.
    Note: When you create a new policy, you specify its triggering criteria, but it has no actions until you take the steps that follow.
  4. Click the [New Action] button to add a new action
  5. Select one of the actions below:
  6. Click [Save].
  7. Optionally, add additional actions, or [Reorder] the actions

Create Task

To create a Task, complete the following fields:

Action Name
Name of the action
Assigned To
Select one of the following:
  • Record Owner
  • Supervisor of Record Owner
  • Specific User
  • System Administrator
Subject
Subject of the Task
Days from trigger for when task is due
Automatically make this task due for a specified number of days after the policy is triggered; '0' will use the Trigger Date as the Due Date
Do not notify
Turn off the notification message that would otherwise go out to the owner of the task.
Description
Task description

Send Email

To send an email message, complete the following fields:

From
Sender, choose from: Record Owner, Record Owner Supervisor, or a Specific User (opens a lookup window to Users)
To
Recipent(s), choose from: Record Owner, Record Owner Supervisor, Specific Email Addresses (opens a lookup window to Users and Contacts), System Administrator, Primary Contact, or other Related to options
Cc
Email address of person(s) who should be copied
Bcc
Email address of person(s) who should be blind-copied (these email addresses are hidden from all recipients, and are visible only to the sender)
Subject
Subject of the email message
Editor Type
Select a type of editor
Learn More: Send Email
Description
Description of the message

Change Record Owner

Assign the record to a new owner.

Update Record

Change a field in the record (status, date, description, etc.)

Considerations
  • Data policies are executed after field validations occur. That sequence assures that the data policy is acting on valid data. (But it also means the data policy has the ability to put invalid data into the current record, since that data will not be validated.)
  • Data policies are executed after formula-fields are evaluated. So if data in the current record is modified by the data policy, any relevant formula-field calculations need to be carried out by the data policy, since they will not occur automatically.

Send Outbound Message

In a Data Policy, it is possible to Send an Outbound Message via REST.

Considerations
  • The services which support HTTP POST requests can be accessed and the response HTTP status code is logged into the Debug Log
  • For a pre-trigger action-based policy, the only available action is Invoke Java Method
  • If the Delete triggering action is chosen, the only available action is Invoke Java Method
  • To change a post-trigger policy to a pre-trigger policy, all actions associated with post-trigger policy must be deleted, since none of them are possible for a pre-trigger action

Note:

Pre-trigger = Before Triggering Actions
Post-trigger = After Triggering Actions

Post Item to Relay Feed

Use Relay to post a message.

Assign follower in Relay

Add a follower to a Relay feed.

Remove Follower in Relay

Remove a follower from a feed.

Invoke Method

Select a method to execute from an existing Java class.
Learn more: Invoke a Java Method From a Data Policy

Considerations
  • When modifying a different record (possibly in a different object), that modification will cause any relevant data policies to fire for that record, as well.

Execute Java Code

Give the action a name, and enter the Java code to execute.
Click [Select Java API] button to automatically enter code from a list of APIs for the platform.
Learn more:

Writing Java Code for a Data Policy

When an action-based data policy fires, a single record is processed. When a calendar-based data policy fires, multiple records may be processed.

In the latter case, the conditions defined by the data policy decide which rows will be processed. The Java code is invoked for each record that matches.

In both cases, the code needs to be written to operate on a single record.

Accessing the Incoming Parameters

To access the incoming parameters:

Thumbsup.gif

Tip: During updates, you can also use the getPriorParams method in the Parameters object to access the record's previous values.

Accessing and Updating Record Data

For most Data Policy triggers, record data is available as key/value pairs in the incoming Parameters object. Field names (not display labels) are the keys, and field contents are the values.

So if the Parameters object is named requestParams, the code to access and/or update the record data typically looks like this (in this case, to access String data):

String data = requestParams.get("field_name");
...
requestParams.put("field_name", data);

There are only a few exceptions to that rule:

  • For a Data Policy action triggered by a Batch Import, record data is not available.
  • For a Data Policy action triggered by the display of a single record (On View), the Parameters object contains a copy of the record data, so you can modify the view of the record without changing the underlying data. Assuming that the Parameters object is named requestParams, the code to access that data looks like this:
import com.platform.api.*;
...
HashMap record = (HashMap) requestParams.getObject(CONSTANTS.RECORD.RESULT);
  • For a Data Policy action triggered by the display of multiple records (List View), the Parameters object contains a list of records. You process that list using code like this:
import com.platform.api.*;
...
ArrayList<HashMap> recordList = 
    (ArrayList) requestParams.getObject(CONSTANTS.SEARCH.SEARCH_RESULTS);
if (recordList != null && recordList.size() > 0) {
    for (HashMap record : recordList) {
        ...
    }
}

In the latter two cases, once you have a record, you access and update field variables using code like this:

String data = record.get("field_name");
...
record.put("field_name", data);

Thumbsup.gif

Tip: Since the constant identifiers are rather long, it can be helpful to create shorter synonyms for them. For example:

static final String RECORDS = CONSTANTS.SEARCH.SEARCH_RESULTS;
static final String RECORD  = CONSTANTS.RECORD.RESULT;

Accessing Other Parameters

In addition to the record's field names and values, the following key/value pairs are included in the Parameters:

policy_action
This parameter contains one of the constants defined in the CONSTANTS.POLICY.ACTION class, to specify the trigger action that activated the data policy. (The "triggering action" is some event that occurred in the platform. The code you are writing, on the other hand, defines that "data policy action" that will be carried out, as a result.)
action_event_sequence
This parameter contains one of the constants defined in the CONSTANTS.POLICY.ACTIVATION class, to specify whether the data policy action is carried out before or after the triggering action.
data_policy_id
The ID of the data policy being executed.
data_policy_action_id
The ID of the data policy Action being executed.
That value can be used to write re-usable classes or code that can handle a variety of conditions and data policies.

Edit a Data Policy

  1. Click Designer > Objects > {object}
  2. Click the Data Policies tab
  3. Click the Data Policy Name link
  4. Click the [Edit] button
  5. Make changes to the fields
  6. Click the [Save] button

Edit an Action

  1. Click Designer > Objects > {object}
  2. Click the Data Policies tab
  3. Click the Data Policy Name link
  4. Click the Action Name link
  5. Click the [Edit] button

Reorder Actions

  1. Click Designer > Objects > {object}
  2. Click the Data Policies tab
  3. Click the Data Policy Name link
  4. Click the [Reorder Actions] button
  5. Select an action in the list and click the up or down arrow buttons
  6. Click [Save]

Delete an Action

  1. Click Designer > Objects > {object}
  2. Click the Data Policies tab
  3. Click the Data Policy Name link
  4. Click the Action Name link
  5. Click the [Delete] button

Delete a Data Policy

  1. Click Designer > Objects > {object}
  2. Click the Data Policies tab
  3. Click the Data Policy Name link
  4. Click the [Delete] button

Invoke a Java Method From a Data Policy

Invoking a Java method, lets you use the Java APIs to interact with the platform, and do anything else that you can accomplish using Java code.

Method Signature

You can select any method defined in a Java class, as long as it has the required signature:

public void someMethod(com.platform.api.Parameters requestParams);
Considerations
  • The method can be either a static class method or an instance method. An instance of the object is created before making the call.
  • The method must be public, return void, and take a single Parameters argument.

Example: Validate Incoming Data

In addition to the rudimentary data validation that is part of every Custom Object, Data Policies give you the capacity for more sophisticated validation.

In this example, the data policy action ensures that the credit number is in the proper format to begin with. (Exactly 16 digits, with no characters or spaces.) The policy action is designed for the Orders object in the Sample Order Processing System, which has field named credit_card_number.

This is an important technique for more sophisticated validations. In this case, for example, a credit card number is too big to use a numeric field, while normal validation mechanisms are limited to simple field comparisons. The solution is to use a data policy to parse the data, and throw an exception in the event of an error.

This code throws an exception if the format isn't valid. The exception will abort the transaction before it is committed. If it were activated in after the triggering event ("post-trigger") then the transaction would have to be rolled back. So it is better practice to configure the data policy so it is activated before the triggering event is carried out.

    
    public void validate_order(Parameters requestParams)
    throws Exception
    {
      // Functions.debug("Validating order");
       String errMsg = "Invalid credit card number format. Needs 16 digits.";
       String ccn = (String) requestParams.get(ccn_field);
       if ((null != ccn) && (ccn.length() != 16)) {
           throw new Exception(errMsg);
       }
       for (int i=0; i<=15; i++) {
           char c = ccn.charAt(i);
           if (c < '0' || c > '9') {
               throw new Exception(errMsg);
           }
       }
       // Format validated
       return;
    }

Additional Examples

For many more examples of data policies that execute java code, see Java Code Data Policy Examples.

About Data Policies in Workflows

When a record is processed through a Workflow, it is associated with a workflow state, or condition. If that workflow state contains a data policy, the data policy is executed on the record. This combination of workflow plus data policy can be used to automate record processing when a user clicks an Action button on a record.

Data Policies can be used with Workflows in two ways:

Calendar Based Data Policies
Can be used to automatically initiate a new workflow or move the record into a new workflow state.
  • Usage Examples:
  • If a request is waiting in IT Manager inbox for more than three days (the Last Workflow State Change Date field available in every object has not changed), then send a reminder email.
  • If a request is waiting in the Supervisor inbox for more than two days, use the Java API to move the request to the IT Manager inbox
Action Based Data Policies
When a record arrives in a state that has data policy linked to it, that policy is executed
  • Usage Examples:
  • Send additional email notifications when record arrives in certain state
  • Throw errors if some specific requirements are not met

About Data Policies in Tasks and Appointments

Data policies can be added to Tasks and Appointments to carry out Data Policy Actions when the Task or Appointment is due.

Learn more:

Using a Data Policy to Send a Message

Send a Message to an Email Account

  1. Create a Data Policy Criteria which will trigger an action.
  2. Create a Data Policy Action to Send an Email.
  3. For the To: field select Specific Email Addresses.

Send a Message to a Mobile Phone

SMS is the protocol for sending text messages to mobile devices. Read about it at: http://en.wikipedia.org/wiki/SMS.

This article covers information about how you can use SMS text messaging to send information out. It can be used with any email function within the platform.

Using Data Policies with SMS

Want to be alerted on your mobile phone whenever you have new data or updates within the platform? It's easy using our Data Policies to send an SMS message to mobile phones for you or your team.

  1. Create a Data Policy Criteria which will trigger an action.
  2. Create a Data Policy Action to Send an Email.
  3. For the To: field select Specific Email Addresses.
  4. In the select Specific Email Addresses field, type in the SMS-email address. (see table below)
  5. Type the message you want to send to the phone. You can also embed template variables related to that record. For example: $account.name.

Below are the most popular carriers and their formats and their character limits for messages. Just replace 5551234567 with your own number.

Carrier Email Format Limit
AT&T 5551234567@txt.att.net 160
Verizon Wireless 5551234567@vtext.com 140
T-Mobile USA 5551234567@tmomail.net 160
Metro PCS 5551234567@mymetropcs.com 120
Sprint PCS 5551234567@messaging.sprintpcs.com 160
Alltell 5551234567@message.alltel.com 116

For a complete list of carriers and their formats you can go to: http://www.livejournal.com/tools/textmessage.bml?mode=details