Configuring Classic Cycle Plans

The Classic Cycle Plans module consists of four objects covering Classic Cycle Plan creation, design, and execution.

Cycle Plan (cycle_plan__v)

Cycle Plan records are used for capturing foundational information for each cycle plan. This includes the plan's name, its active time frame, and the assigned territory. Each active Cycle Plan can only be assigned to one territory.

Cycle Plan Target (cycle_plan_target__v)

Cycle Plan Target records define which accounts are included in the plan and the interaction goals for each targeted account. As users complete calls relevant to the plan, those activities are reflected on the Cycle Plan Target record.

Cycle Plan Detail (cycle_plan_detail__v)

Cycle Plan Detail records define which products are included in the plan, and product interaction goals for each targeted account. When users capture product detailing activities relevant to the plan on a call report, those activities are reflected on the Cycle Plan Detail record.

Cycle Plan Adjustment (cycle_plan_adjustment__v)

The Cycle Plan Adjustment object captures discrepancies in cycle plan counts between mobile devices and the online database. Cycle Plan data is not stored on the object; data is kept locally on the mobile device.

Product Catalog (product__v)

Products in a cycle plan are sourced from the Product Catalog. Products are available in a cycle plan if they are assigned to the user in My Setup, and are not excluded from cycle plans.

Configuring Classic Cycle Plans for

To configure this module:

  1. Ensure the following configuration is complete:
  2. Navigate to Admin > Configuration > Tabs.
  3. Create a tab for the cycle_plan__v object.
  4. Navigate to Admin > User & Groups > Permission Sets.
  5. Select the appropriate permission set.
  6. Select the Objects tab.
  7. Grant the following permissions:

    Object

    Object Permission

    Object Types

    Fields

    Field Permission

    cycle_plan__v

    CRED

    n/a

    All

    Edit

    cycle_plan_adjustment__v

    CRED

    n/a

    All

    Read

    cycle_plan_detail__v 

    CRED

    n/a

    All

    Edit

    cycle_plan_target__v

    CRED

    n/a

    All

    Edit

  8. Grant Execute permission to the following actions on the cycle_plan__v object:
    • cp_submit__v
    • cp_unlock__v

  9. Grant View permission to the cycle_plan_target_section__v section control on the cycle_plan__v object. This enables the Cycle Plan Targets table, for an overview of progress towards call goals.

  10. Grant View permission to the following field controls on the cycle_plan_target__v object:

    • cycle_plan_add_target__v - Enables adding targets to a cycle
    • cycle_plan_apply_list__v - Enables applying an account list to the cycle
    • cycle_plan_schedule_calls__v - Enables scheduling calls for the selected targets
    • display_product_details__v - Enables displaying cycle plan metrics by detail product in the Cycle Plan Targets table, in addition to an overview of metrics for all products in the plan

  11. Select the Tabs tab in the permission set.

  12. Grant View permission to the Cycle Plans tab.

  13. Select the Pages tab in the permission set.

  14. Grant View permission to the Cycle Plan Target page.

  15. Navigate to Admin > Configuration > Objects > cycle_plan__v > Fields.

  16. Ensure the attainment_difference__v and expected_calls__v formula field expressions do not reference any other formula fields. Referencing other formulas from a formula field expression is not supported.

Since the attainment_difference__v formula field expression subtracts the attainment__v formula field expression from the expected_attainment__v formula field expression, the attainment_difference__v expression must be manually edited to reflect changes to attainment__v or expected_attainment__v, if those formula field expressions are edited.

Configuring Layouts for Classic Cycle Plans

To configure layouts for this module:

  1. Navigate to Admin > Configuration > Objects > cycle_plan__v > Layouts.

  2. Place the cycle_plan_target_section__v section control on the appropriate cycle_plan__v layouts.

  3. Place the Cycle Plan Targets related object section on the appropriate cycle_plan__v layouts.

  4. Add any additional columns to be displayed in the Cycle Plan Targets table to the Cycle Plan Targets related object section (optional).

    5. By default, actual_calls__v and total_calls__v columns are included. These two columns enable the display of all standard cycle plan target columns: Actual, Planned, Scheduled, and Percent Attainment. actual_calls__v enables these columns for the current user’s activity (My Calls), while total_calls__v enables these columns for all activity across the territory (Total Calls).

  5. Select Layout Rules for the cycle_plan__v layout.

  6. Create a layout rule to hide the Cycle Plan Targets related object section:

    • Populate the IF this Layout Rule Expression is TRUE box with the expression 'true'
    • Apply the following display effects for the layout rule:
    • Effect: Hide
    • Type: Sections
    • Value: Cycle Plan Targets

  7. Navigate to Admin > Configuration > Objects > cycle_plan_target__v > Layouts.

  8. Place the following field controls on the appropriate cycle_plan_target__v layouts.

  9. cycle_plan_add_target__v - Enables adding targets to a cycle
  10. cycle_plan_apply_list__v - Enables applying an account list to the cycle
  11. cycle_plan_schedule_calls__v - Enables scheduling calls for the selected targets
  12. display_product_details__v - Enables displaying cycle plan metrics by detail product in the Cycle Plan Targets table, in addition to an overview of metrics for all products in the plan

  13. Select Layout Rules for the cycle_plan_target__v layout.

  14. Create a layout rule to hide field controls on cycle_plan_target__v layouts:

    • Populate the IF this Layout Rule Expression is TRUE box with the expression 'true'
    • Apply the following display effects for the layout rule:
    • Effect: Hide
    • Type: Controls
    • Value: cycle_plan_add_target__v, cycle_plan_apply_list__v, cycle_plan_schedule_calls__v, display_product_details__v

  15. Navigate to Admin > Configuration > Objects > veeva_settings__v.
  16. Place the calc_cycle_plans__v field on the appropriate veeva_settings__v layouts. Ensure the field default value is: (cycle_plan__vr.active__v = 'true') AND (cycle_plan__vr.start_date__v <= last_days:1) AND (cycle_plan__vr.end_date__v > last_days:1)

To configure this module:

  1. Ensure the following configuration is complete:
  2. Navigate to Admin > User & Groups > Permission Sets.
  3. Select the appropriate permission set.
  4. Select the Objects tab.
  5. Grant the following permissions:

    Object

    Object Permission

    Object Types

    Fields

    Field Permission

    cycle_plan__v

    At least RE*

    n/a

    • actual_calls__v
    • planned_calls__v

    Edit

    • active__v
    • attainment__v
    • attainment_difference__v
    • comments__v
    • created_by__v
    • created_date__v
    • cycle_plan_status__v
    • end_date__v
    • expected_attainment__v
    • expected_calls__v
    • external_id__v
    • legacy_crm_id__v
    • link__sys
    • lock__v
    • mobile_id__v
    • modified_by__v
    • modified_date__v
    • name__v
    • ownerid__v
    • remaining__v
    • start_date__v
    • status__v
    • territory__v
    		At least Read*

    cycle_plan_adjustment__v

    CRED

    n/a

    All

    Read*

    cycle_plan_detail__v 

    At least RE*

    n/a

    • actual_details__v
    • scheduled_details__v
    • total_actual_details__v
    • total_scheduled_details__v

    Edit

    • attainment__v
    • created_by__v
    • created_date__v
    • cycle_plan_target__v
    • legacy_crm_id__v
    • link__sys
    • mobile_id__v
    • modified_by__v
    • modified_date__v
    • name__v
    • planned_details__v
    • priority__v
    • product__v
    • remaining__v
    • status__v
    • total_attainment__v
    • total_planned_details__v
    • total_remaining__v
    		At least Read*

    cycle_plan_target__v

    At least RE*

    n/a

    • actual_calls__v
    • scheduled_calls__v
    • total_actual_calls__v
    • total_scheduled_calls__v

    Edit

    • attainment__v
    • created_by__v
    • created_date__v
    • cycle_plan__v
    • cycle_plan_account__v
    • external_id__v
    • legacy_crm_id__v
    • link__sys
    • mobile_id__v
    • modified_by__v
    • modified_date__v
    • name__v
    • original_planned_calls__v
    • planned_calls__v
    • remaining__v
    • remaining_schedule__v
    • status__v
    • total_attainment__v
    • total_planned_calls__v
    • total_remaining__v
    • total_remaining_schedule__v
    		At least Read*

    6. * To enable end users and managers to create or edit cycle plans, also grant Create object permission and additional Edit field permission as needed.

  6. Grant View permission to the cycle_plan_section__v section control on the account__v object.
  7. Grant View permission to the cycle_plan_target_section__v section control on the cycle_plan__v object. This enables the Cycle Plan Targets table, for an overview of progress towards call goals.

  8. Grant View permission to the following field controls on the cycle_plan_target__v object:

    • cycle_plan_add_target__v - Enables adding targets to a cycle
    • cycle_plan_apply_list__v - Enables applying an account list to the cycle
    • cycle_plan_schedule_calls__v - Enables scheduling calls for the selected targets
    • display_product_details__v - Enables displaying cycle plan metrics by detail product in the Cycle Plan Targets table, in addition to an overview of metrics for all products in the plan

  9. Grant View permission to the home_page_cycle_plan_section__v section control on the vmobile_home_page_layout__v object.

  10. Select the Tabs tab in the permission set.

  11. Grant View permission to the Cycle Plans tab.

  12. Select the Pages tab in the permission set.

  13. Grant View permission to the Cycle Plan Target page.

Configuring Layouts for Classic Cycle Plans

To configure layouts for this module:

  1. Navigate to Admin > Configuration > Objects > account__v > Layouts.

  2. Place the cycle_plan_section__v section control on the appropriate account__v layouts. This enables an attainment dial on Account Detail pages, visualizing cycle plan progress for end users.

  3. Navigate to Admin > Configuration > Objects > vmobile_home_page_layout__v > Layouts.

  4. Place the home_page_cycle_plan_section__v section control on the appropriate vmobile_home_page_layout__v layouts, to display the cycle plans widget on the iPad home page (optional). For more on the home page, see Vault CRM Mobile Application Home Page.

Configuring Veeva Settings, Veeva Messages, and VMOCs

To configure Veeva Settings, Veeva Messages, and VMOCs for this module:

  1. Navigate to Business Admin > Objects > veeva_settings__v.

  2. Select the cycle_plan_no_data_display__v Veeva Setting check box. This enables displaying a brief explanatory message on the Account detail page when the user does not have an active cycle plan for the account, rather than displaying an empty section.

  3. Select the enable_cycle_plans_remaining__v Veeva Setting check box to change the Attainment column to Remaining, at either the global or profile level (optional). When this setting is enabled, the R (Remaining) column displays in place of the % (Attainment) column as the last column for each product in the Cycle Plan Targets table.

  4. Navigate to Business Admin > Objects > message__v.
  5. Ensure the TAB_NAV_DISPLAY Veeva Message contains ;;MyCyclePlan;;. (For more information on tab visibility, see Managing Tab Visibility and Display Order.)

  6. Navigate to Business Admin > Objects > vmobile_object_configuration__v.

  7. Edit VMOC WHERE clauses for the cycle_plan__v and cycle_plan_target__v objects:

    • Ensure cycle_plan__v VMOC WHERE clauses match the following: WHERE (territory__v CONTAINS (@@USER_TERRITORY_NAMES@@) OR ownerid__v = @@USER_ID@@)
    • Ensure cycle_plan_target__v VMOC WHERE clauses match the following: WHERE (cycle_plan__vr.territory__v CONTAINS (@@USER_TERRITORY_NAMES@@) OR cycle_plan__vr.ownerid__v = @@USER_ID@@)

  8. Enable VMOCs for the following objects:

    • cycle_plan__v
    • cycle_plan_adjustment__v
    • cycle_plan_detail__v
    • cycle_plan_target__v

Customizing My Calls and Total Calls Fields

Optionally, admins can configure additional fields to display for Cycle Plan Detail products, to provide additional context. By default, Actual Details, Planned Details, and Scheduled Details values display for each Cycle Plan Detail product on Cycle Plan pages, the View Plan Details modal in My Schedule, and the Cycle Plan section on Account Detail pages. For Total Calls, the corresponding Total values display.

To configure additional fields for Cycle Plan Detail products:

  1. Navigate to Admin > Configuration > Objects > cycle_plan_detail__v > Layouts

  2. Create two new sections on the cycle_plan_detail__v layout, named as follows:

    • cycle_plan_detail__c - For fields to be displayed as My Calls values
    • total_cycle_plan_detail__c - For fields to be displayed as Total values, across the territory

    To continue displaying standard columns after creating these new sections, admins must place Actual, Planned, and Scheduled fields in each new section.

  3. Place the following fields in the cycle_plan_detail__c section:
    • actual_details__v
    • planned_details__v
    • scheduled_details__v

  4. Place the following fields in the total_cycle_plan_detail__c section:

    • total_actual_details__v
    • total_planned_details__v
    • total_scheduled_details__v

  5. Place the appropriate additional fields in the new sections, for example, the priority__v field.

For information on viewing the Cycle Plan Targets table and the Cycle Plan section on Account Detail pages, see Monitoring Classic Cycle Plan Progress. For information on the View Plan Details modal, see Viewing Cycle Plan Details from My Schedule.

Customizing Attainment Thresholds

To customize how performance thresholds display to end users in cycle plan attainment dials, cycle plan admin users can modify attainment thresholds. Modifying attainment thresholds changes when the cycle plan attainment dial changes color from green to yellow, and yellow to red. This visual cue helps users and managers immediately recognize areas needing attention.

Dial colors indicate whether activity is on track relative to the time elapsed in the plan:

  • Green - Plan is on track
  • Yellow - Targets are underreached, meaning users need to complete more activities
  • Red - Targets are overreached, meaning users completed too many activities

To customize attainment thresholds:

  1. Navigate to Business Admin > Objects > message__v.

  2. Modify the value in the Text field on the CYCLE_PLAN_THRESHOLD;;Tablet Veeva Message, using best practices for editing Veeva Messages. The message value is two integers separated by a comma:

  • The first number represents the threshold where the dial color changes from green to yellow, indicating targets are underreached
  • The second number represents the threshold where the dial color changes from green to red, indicating targets are overreached

By default, the message value is 10,25.

Threshold values are compared against the current cycle plan’s Attainment Difference to determine dial color. For example, the Attainment Difference for a plan is 20, indicating users are 20 calls behind the expected attainment relative to time elapsed in the cycle. The CYCLE_PLAN_THRESHOLD;;Tablet Veeva Message text value is 10,25. The cycle plan attainment dial displays in yellow because the Attainment Difference is greater than 10 and less than 25. If users complete enough calls to cause the Attainment Difference to drop to nine, then the dial color changes from yellow to green.

Customizing Heading Labels for Cycle Plan Targets

Column heading labels in the Cycle Plan Target table can be replaced with customer-specific values through Veeva Messages. The Veeva Messages for Cycle Plan Target column headings are delivered as follows, by default:

Message Name

Category

Language

Default Value

ABBR_ACTUAL

CyclePlan

en_US

A

ABBR_PLANED

CyclePlan

en_US

P

ABBR_REMAINING

CyclePlan

en_US

R

ABBR_SCHEDULED

CyclePlan

en_US

S

The Attainment column heading is not customizable. The label always displays as %.

To customize column heading labels, modify the value in the Text field on the appropriate Veeva Messages, using best practices for editing Veeva Messages:

  • ABBR_ACTUAL;;CyclePlan
  • ABBR_PLANED;;CyclePlan
  • ABBR_REMAINING;;CyclePlan
  • ABBR_SCHEDULED;;CyclePlan

Any value can be entered. Note that the column width expands based on label length, meaning a long header label could expand the column, requiring users to scroll to view the full table content.

Enabling Cycle Plan Processing as

As part of configuring Classic Cycle Plans, cycle plan admin users must enable processing by enabling the cycle plan SDK job and scheduling the job to run at the appropriate intervals.

Only the Vault Owner can run this job.

To enable processing:

  1. Navigate to Admin > Operations > Job Definitions.

  2. Select the cycle_plan_progress_calculation__v SDK job.

  3. Set the appropriate Schedule. It is recommended to run the job during off-peak hours, for example, overnight.

  4. Set the Status to Active.

  5. Select Save.

For more on how plans are updated during processing, see Using Cycle Plan Batch Processes. Real-time calculations can be enabled in addition to the SDK job, if desired.

Customizing Cycle Plan Calculations

Cycle plan admin users can customize which cycle plans and call reports are considered in calculations when plans are processed.

To customize which cycle plans are considered in cycle plan calculations:

  1. Navigate to Business Admin > Objects > veeva_settings__v.

  2. Modify the VQL WHERE clause in the calc_cycle_plans__v Veeva Setting (label: CALC CYCLE PLANS). By default, the value is: (cycle_plan__vr.active__v = 'true') AND (cycle_plan__vr.start_date__v <= last_days:1) AND (cycle_plan__vr.end_date__v > last_days:1)

If the setting is cleared, all active plans where the current date is within the cycle plan start and end dates are processed.

To customize which call reports are considered in cycle plan calculations:

  1. Navigate to Business Admin > Objects > message__v.

  2. Modify the VQL WHERE clause in the CALC_CYCLE_PLANS_ACTUAL;;CyclePlan Veeva Message to customize which call reports are considered in the cycle plan, using best practices for editing Veeva Messages. By default, the value is: (call2_status__v = 'submitted__v' or (call2_status__v = 'saved__v' and call_date__v <=TODAY)). This includes call reports where the status is saved or submitted, and the call date is the current date or earlier.

     

    For example, to only count saved or submitted Face to Face calls in the cycle plan, change the value to: (call2_status__v = 'submitted__v' OR (call2_status__v = 'saved__v' and call_date__v <=TODAY and call_channel__v = 'face_to_face__v'))

     

  3. Modify the VQL WHERE clause in the CALC_CYCLE_PLANS_SCHEDULED;;CyclePlan Veeva Message to customize which call reports are counted as scheduled calls in the cycle plan, using best practices for editing Veeva Messages. By default, the value is: (call2_status__v = 'planned__v' or (call2_status__v = 'saved__v' and call_date__v >TODAY)). This includes call reports where the status is planned or saved, and the call date is later than the current date.

WHERE clause modifications must use proper VQL syntax. Clause components in these Veeva Messages are limited to the following:

  • Objects - Queries must be for fields on the cycle_plan__v or call2__v objects
  • Field Types - Only date or datetime fields, or date literals, are supported
  • Functions - Date functions are limited to TODAY () and Last_DAYS(). For example, Last_DAYS:3
  • Operators - The following operators are supported:
  • =
  • !=
  • <
  • >
  • <=
  • =>
  • AND
  • OR

Consider the following when modifying WHERE clauses for cycle plan calculations:

  • Parentheses must be used to define the order in which field expressions are evaluated. When nesting operators, parentheses must be used.
  • Nested select statements are not supported
  • Joins or multiple object queries are not supported
  • Querying by territory is not supported, since the territory on a cycle plan must match the target account territory

For more information on operators and functions in Vault, see the Vault Formula Reference Guide on the Vault Platform help site.

If the queries in these Veeva Messages are cleared, or the values in the calc_cycle_plans_actual__v and calc_cycle_plans_scheduled__v Veeva Settings pointing to these messages are cleared, all call reports within the cycle plan's time frame and territory are included in cycle plan calculations.

Related Topics

Creating Classic Cycle Plans

Using Cycle Plan Progress Calculations

Real-Time Calculations for Classic Cycle Plans