HowTo:Write Java Code for Data Policies

HowTo:Write Java Code for Data Policies

From LongJump Support Wiki

HowTo:Write Java Code for Data Policies
Jump to: navigation, search

For:    Designers
Level: Advanced
Time: 6-10 min.s per example

See more:
    ◾ HowTo Guides

This section contains step-by-step examples for creating Java-based Data Policies, with pointers to the Code Samples they execute.

Contents

Data Policy Examples

These examples illustrate how to execute Java code in Data Policies.

To apply any of these code samples, first create a Data Policy and set the appropriate parameters from the platform user interface.

Use a Plain Text Editor to copy the code samples and paste them into the Data Policy Action field. If a plain text editor is not used, hidden characters may be introduced that can cause the action to fail.

Learn more: For a large code sample that includes multiple actions, see Getting Started with the Java API.

Log Activity On Update Prospect

When triggered (by updating a Prospect), the Java code in this Data Policy causes an Activity to be Logged to the Primary Contact of the Prospect record. See Log Activity for details about call logging.

How it Works

Follow the steps in the example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Log Activity On Update Prospect Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name
    Log a Call when Prospect is Updated
    Enabled
    Checked
    Activation Trigger
    Action Based
    Activation Sequence
    Before Triggering Actions
    Triggering Actions
    Select the 'Update' checkbox
    Policy Triggering Criteria
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Try it Out

Verify that the action works as intended:

  1. Open the Prospects tab
  2. Click the Edit link for the record you want to try out
  3. Make changes and click the [Save] button
  4. Look under Activity History to see the activity was logged

Add Task On Field Changes

When triggered (by updating the Description in an Opportunity), the Java code in this Data Policy adds a Task to the Opportunity.

Compare this action to Add Task.

How it Works

Follow the steps in the example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Create a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Choose one of the Add Task On Field Changes Code Samples for the method:
    • Sample 1: Simple Task Addition
    • Sample 2: Task Addition with Reminder, Repeat, End flag and Invitee List
  3. Copy your chosen code sample into the class
  4. Create a data policy, or edit an existing data policy, using these parameters:
    Name
    Update Activity with a Script
    Enabled
    Checked
    Activation Trigger
    Action Based
    Activation Sequence
    Before Triggering Actions
    Triggering Actions
    Select the 'Add' and 'Update' checkboxes
    Policy Triggering Criteria
    ISCHANGED(description)
  5. Save your changes
  6. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Limitations

  • no action is taken when when the record ownership is changed
  • no action is taken when this action is part of a batch import
  • no action is taken when any other field in the record is changed (task is added only when the description field changes)

See Also

Add Appointment On Update Prospect

When triggered (by updating a Prospect), the Java code in this Data Policy creates an appointment in the Prospect's calendar.

How it Works

Follow the steps in the example to:

  • add a custom field: appointmentID, which will contain the recordID of the appointment
  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add Custom Field to Prospect Object

  1. Click Designer > Objects > Prospects > Fields
  2. Click the [Add Field] button to create a new field
  3. In the Basic Information section, enter this information in the required fields:
    Label
    Appointment recordID
    Display Type
    Text Field
    Maximum Storage Length
    default
    Include in Quick Edit
    Uncheck
    Field Name
    (auto populated, do not change)
  4. In the Display Attributes section, enter this information:
    Section
    Basic Information
    Required
    Unchecked
  5. In the Description Information section, enter this information:
    Description
    Contains the recordID of the appointment
  6. Click [Save]

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Add Appointment On Update Prospect Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name
    Add Appointment when a Prospect is Updated
    Enabled
    Checked
    Activation Trigger
    Action Based
    Activation Sequence
    Before Triggering Actions
    Triggering Actions
    Select the 'Update' checkbox
    Policy Triggering Criteria
    ISNULL(description)
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Try it Out

Verify that the action works as intended:

  1. Open the Prospects tab
  2. Click the Edit link for the record you want to try out
  3. Make changes and click the [Save] button
  4. Open the Calendar to see that the appointment was added. Note that the Appointment ID is displayed in the custom field you created.

Send an Email Message to Request a Contract Renewal

When triggered (by Field Criteria), the code in this Data Policy causes an email message to be sent, requesting contract renewal.

For a Contract date when the expiry date is reached, send an Email to renew the contract.

How it Works

Follow the steps in this example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Send an Email Message to Request a Contract Renewal Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name
    Track Contract End Date
    Enabled
    Select the check box
    Activation Trigger
    Action Based
    Activation Sequence
    Before Triggering Actions
    Triggering Actions
    Select the 'Update' checkbox
    Policy Triggering Criteria
    Check for Contract expiry date or remaining days
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Result

An email message is sent to the email addresses specified in the sendEmail method parameters.

Convert a Prospect to Account, Triggered by an Add

When a Prospect record is added, the Prospect (LEAD) is converted to an Account.

How it Works

Follow the steps in the example to:

  • create a Data Policy with appropriate triggering actions
  • create an action with Java code

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Convert a Prospect to Account, Triggered by an Add Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name
    Convert a Prospect to an Account when a new Prospect is Added
    Enabled
    Checked
    Activation Trigger
    Action Based
    Activation Sequence
    Before Triggering Actions
    Triggering Actions
    Select the 'Merge' checkbox
    Policy Triggering Criteria
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Try it Out

Verify that the action works as intended:

  1. Open the Prospects tab
  2. Add a new prospect
  3. Click [Save]
  4. View the record you have added in the Prospect and find it is added to the Account object and record is updated with 'Conversion Information'

Search for an Account and Update the Primary Contact for that Account

Search the database for an Account record and change the Primary Contact Name.

How it Works

Follow the steps in the example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Search for an Account and Update the Primary Contact Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name 
    Search for Account names containing 'Challenge'
    Enabled 
    Select the check box
    Activation Trigger
    Action Based
    Activation Sequence
    After Triggering Actions
    Triggering Actions
    Select the 'Update' checkbox
    Policy Triggering Criteria
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Send an Email Notification on an Ownership Change for a Project

The following sample sends an email message to inform the user of an ownership change for a project.

How it Works

Follow the steps in the example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Send an Email Notification on an Ownership Change for a Project Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name
    Log a Call when Prospect is Updated
    Enabled
    Checked
    Activation Trigger
    Action Based
    Activation Sequence
    Before Triggering Actions
    Triggering Actions
    Select the 'Ownership Change' checkbox
    Policy Triggering Criteria
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created
Result
An email message is sent to the email addresses specified in the sendEmail method parameters.

Try it Out

Verify that the action works as intended:

  1. Open the Prospects tab
  2. Click the Edit link for the record you want to try out
  3. Make changes and click the [Save] button
  4. Verify that the email message was received

Update the Primary Contact's Address with Account's Address

When an ACCOUNT record is added or updated, the Primary Contact is updated with the address of the ACCOUNT record. An email message is sent after the CONTACT record's address is updated with ACCOUNTs address.

How it Works

Follow the steps in the example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Update the Primary Contact's Address with Account's Address Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name 
    Check Account address
    Enabled 
    Select the check box
    Activation Trigger
    Action Based
    Activation Sequence
    After Triggering Actions
    Triggering Actions
    Select the 'Add' checkbox
    Policy Triggering Criteria
    Street, City of Account should have been populated
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Add Contact On Importing Prospect Records

When triggered (by importing Prospect(s)), the Java code in this Data Policy causes an addition of contact record. You can extend this sample further by associating the contact with the prospects imported using another data policy that can be triggered after the import is completed on an 'After Triggering Actions' sequence.

See addRecord for details about using this Java API method.

How it Works

Follow the steps in the example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Add Contact On Importing Prospect Records Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name
    Add Contact on import to Prospect
    Enabled
    Checked
    Activation Trigger
    Action Based
    Activation Sequence
    Before Triggering Actions
    Triggering Actions
    Select the 'Import' and/or 'Import Batch' checkbox
    Policy Triggering Criteria
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Try it Out

Verify that the action works as intended:

  1. Traverse through the link : Settings > Data Management > Import Data
  2. Select 'Prospect' object from the drop down list
  3. In the 'Import Prospects' layout, enter all the details to start the import
  4. Check the 'Import Queue' to make sure the import action is listed.
  5. A contact is added first and then the data is imported in to 'Prospects' object.
  6. In case of an error in the custom code, the import does not go through.
  7. The error that is thrown in the custom code is displayed in the 'Import Queue'

Calendar Based Policy To Add A Task, using Execute Java Code

This example uses the Java API to invoke a function defined in a Java class, using an Action in a Data Policy as the trigger.

How it Works

Follow the steps in the example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Follow the instructions in the next sections to create an action that will update the Contact associated with the account

Add a Data Policy

This data policy will Execute a Java Code Utility call (exec), which executes a function.

  1. Create a class and a method for the data policy to execute.
  2. Use the following code for the method:
    Functions.exec("add_task", requestParams);
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name 
    Enter an appropriate name for this policy
    Enabled 
    Select the check box
    Activation Trigger
    Calendar Based
    Activation Date
    Select a date
    Activation Time
    Input a time when this data policy should be triggered
    Repeating Frequency
    Does not repeat
    End Date
    This policy never ends
    Run As
    Optionally, change this to another user
  4. Save your changes
  5. Specify the Data Policy action:
    • Click [Add Action]
    • Click Execute Java Code
    • Enter an Action Name
  6. Copy and paste the following code into the editing area, then click [Save]
     Parameters params = Functions.getParametersInstance();
     params.add("reference_id", requestParams.get("record_id"));
     params.add("reference_type", requestParams.get("object_id"));
     params.add("description", "Task added for: "
                    + requestParams.get("record_id"));
     params.add("status", "In Progress");
     params.add("subject", "Task added on:" + new Date());
     params.add("action_type", "Email");
     params.add("date_created", new Date());
     params.add("date_modified", new Date());
     params.add("due_date", new Date());
     //params.add("end_date", new Date());
     params.add("assigned_id", Functions.getEnv(ENV.USER.ID));
     params.add("created_id", Functions.getEnv(ENV.USER.ID));
     Result result = Functions.addTask(requestParams.get("object_id")
                   + " : Task for - "
                   + requestParams.get("record_id"), new Date(),
       Functions.getEnv(ENV.USER.ID), params);
     Functions.debug("Result of addTask" + result.getMessage());
     if(result.getCode() != -1)
     {
       requestParams.add("description", result.getID());
     }
     else
     {
        String msg = "Error adding Task";
        Functions.debug(msg + ":\n" + result.getMessage());  // Log details
        Functions.throwError(msg + ".");                     // Error dialog
     }

Try it Out

Verify that the action works as intended:

  1. Verify under Tasks tab after the Activation Time
  2. You will see a task added and associated with the object from which the data policy was enabled

Retrieve and Verify Prospect Fields on Convert to Account

When converting a Prospect to an Account, this code sample will retrieve these Account fields: (name, city, description, lead_source), and check if they are populated or not.

If any of these fields are not populated (empty), the debug log is updated and the error string is set.

How it Works

Follow the steps in the example to:

  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Retrieve and Verify Prospect Fields Code Sample for the method
  3. Create a data policy, or edit an existing data policy, using these parameters:
    Name
    Retrieve and Verify Prospect Fields on Convert to Account
    Enabled
    Checked
    Activation Trigger
    Action Based
    Activation Sequence
    After Triggering Actions
    Triggering Actions
    Convert to Account
    Policy Triggering Criteria
    <none>
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Update Opportunity with Data Calculated from a Related Object

In this example, we will use the Java API to update an opportunity with information calculated when a record is added or updated to one of its related objects.

In this example, an opportunity record is populated (updated) with related expenses. It's triggered when a related expense record is added or updated.

Two objects are used Opportunities and Expense Items.

How it Works

Follow the steps in the example to:

  • add a new field to the Opportunities object (Total Expenses)
  • add new fields to the Expense Items object (Lookup to Opportunities field and Billable checkbox field)
  • relate the Opportunities and Expense Items objects
  • create a data policy with appropriate triggering actions
  • create an action with Java code

Add New Fields

  1. In the Opportunities object, add this field:
    • Total Expenses; Type=Currency
  2. In the Expense Items object, add these fields:
    • Opportunities Lookup; Type=Lookup to the Opportunities object; Choose to display the Total Expenses field
    • Billable; Type=Checkbox
  3. Add the fields to the Opportunities Form
    • Click Designer > Objects > Opportunities > Forms
    • Click the New Related Information link to create a new section; Enter the following information:
    Information Source
    Object
    Object
    Expense Items
    Title
    (Automatically populated)
    Specify Fields to Link
    Expense Items Field:Opportunities Lookup, links to Opportunities Field:ID

Add a Data Policy

  1. Create a class and a method for the data policy to execute.
  2. Copy the Update Opportunity with Data Calculated from a Related Object Code Sample for the method
  3. In the Expense object, create a data policy using these parameters:
    Name
    Update Opportunity when Expense Items are added or updated
    Enabled
    Checked
    Activation Trigger
    Action Based
    Activation Sequence
    Before Triggering Actions
    Triggering Actions
    Select 'Add' and 'Update' checkboxes
    Policy Triggering Criteria
    No additional criteria. The data policy is activated every time an expense record is added or updated. (As a refinement, activate the data policy only when the expense is marked as "billable".)
  4. Save your changes
  5. Specify the Data Policy action:
  • Click [Add Action]
  • Click Invoke Java Method
  • Enter an Action Name
  • Choose the class and method you created

Try it Out

Verify that the action works as intended:

  1. Open the Opportunity tab
  2. Add a new record and save
  3. Open the Expense Items tab
  4. Add a new record and save
    The data policy is triggered; All records in Expense Items related to this Opportunity are found; If those records are billable, the Amount field of the Expense record is summed and populates the Total Expenses field in the Opportunities record
  5. Open the Opportunity tab and check the record to see the changes

Integration to a Web Service Using HttpConnection

This code is intended for use as part of a Data Policy. It is a complex example of the use of Java code to take a series of actions, each based on the previous code section. For information on the use of this code sample, see: Integration to a Web Service Using HttpConnection.

To implement this code, copy and paste the following Java code into a Data Policy action. Be sure to use a Plain Text Editor to manipulate the code.

A cut-and-paste code sample is available here: Web Service HttpConnection
Personal tools