> ## Documentation Index
> Fetch the complete documentation index at: https://support.fieldko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up Call Cycles, Tasks, and Visit Templates

> Create call cycles, task types, visit templates, and visit types so reps can plan and complete visits.

Call cycles, task types, visit templates, and visit types are the building blocks reps use to plan and complete visits. Use this page to set them up once, so reps can schedule visits and work through the right tasks in every store. If these terms are new to you, see [Key Concepts](/getting-started/key-concepts).

## User Permissions Needed

| To do this | You need |
| - | - |
| Create call cycles | FieldKo Manager Permission Set |
| Create task types and visit templates | FieldKo Manager Permission Set |

## Before You Begin

Set things up in this order, because each item uses the one before it:

1. **Call cycles**, so reps can create visits and their visits sync to the app.
2. **Surveys**, if tasks will open a survey. See [Build Surveys](/admin/surveys).
3. **Task types**, which can each point to a default survey.
4. **Visit templates**, which group task types.

Visit types, visits from other objects, and account objectives are optional.

## Call Cycles

A call cycle is a planning period for one rep, such as 4 weeks. **Every visit must fall inside an active call cycle for its rep.** Without one:

* The rep's visits, tasks, and orders don't sync to the app.
* No one can create or reschedule visits. Reps see **No Call Cycle.**, and Salesforce shows "Sorry! No Call Cycle available. Please Contact your Manager or Administrator".

### Call Cycle Rules

Check these rules before you create cycles. You can't change a cycle's dates, rep, or duration after you save. If you try, Salesforce shows "Cannot change the start and end dates, or the representative as well as Duration in weeks after creation".

* The first cycle must start on the fiscal year's start date, and the last cycle must end on its end date. The start month comes from **FieldKo Configuration** > **Basic** > **Fiscal Year Start Month**.
* Each cycle must start the day after the previous one ends.
* You can't create cycles for a rep who already has active cycles for that year.

When FieldKo generates cycles, on the **Call Cycles** tab or through the scheduled job, it lines them up with weeks that start on Monday:

* If the fiscal year doesn't start on a Monday, the first cycle is short. It runs from the fiscal year's start date to the first Sunday.
* Each later cycle starts on a Monday and runs for the full duration.
* The last cycle ends on the fiscal year's end date, so it can also be shorter than the others.

### Create Call Cycles

FieldKo generates a full year of cycles for each rep you select, and you review them before you save:

<Steps>
  <Step title="Open the Call Cycles Tab">
    From the App Launcher, find and select **Call Cycles**.
  </Step>

  <Step title="Choose the Year, Duration, and Reps">
    1. Select the fiscal year (up to 5 years ahead).
    2. Enter the **Duration in weeks** (1 to 52).
    3. Select the reps.

    FieldKo generates the cycles for each rep.
  </Step>

  <Step title="Review the Generated Cycles">
    Check the dates carefully, because you can't change them after you save.

    Optional: Adjust the dates, or add or remove the last cycle.
  </Step>

  <Step title="Save Your Changes">
    Click **Save**.
  </Step>
</Steps>

FieldKo uses a call cycle only when its **Active** checkbox is selected. After you save, check that the new cycles are active.

<Tip>
  Create next year's cycles automatically by scheduling `CallCycleBatchscheduler`. The default length comes from the **Call Cycle Configuration** custom setting's **Duration in Weeks** field. See [Scheduled Jobs](/admin/installation#scheduled-jobs).
</Tip>

### Copy Visits to Another Call Cycle

Use **Clone Call Plan** to copy every visit in one call cycle into another cycle for the same rep. By default, FieldKo copies each visit's tasks and surveys too. The copied visits are **Not Started**.

<Steps>
  <Step title="Open the Source Call Cycle">
    Open the call cycle record whose visits you want to copy, and then click **Clone Call Plan**.
  </Step>

  <Step title="Choose the Fiscal Year">
    Under **Step 1. Select Fiscal Year to clone Call Cycle Into**, select the **Fiscal Year**.
  </Step>

  <Step title="Choose the Destination Cycle">
    Under **Step 2. Select Call Cycle to copy visits to**, select a cycle. The list shows only the rep's cycles that start on the same day of the week and have the same length as the source cycle.
  </Step>

  <Step title="Optional: Leave Out Tasks and Surveys">
    Select **Copy Visits without Tasks and Surveys**. The copied visits then use the minimum default visit duration.
  </Step>

  <Step title="Clone the Visits">
    Click **Clone Visits**.
  </Step>
</Steps>

If the destination cycle already has visits, FieldKo lists them and tells you "The Existing Visits will not be deleted." To copy the visits anyway, click **Confirm Clone**.

## Task Types

Task types are the reusable tasks reps complete on visits, such as "Check shelf pricing" or "Complete display survey". To create one, from the App Launcher, find and select **Task Types**, and then click **New**.

| Field | What It Does |
| - | - |
| **Task Type Name** | The name reps see. For action tasks, see [Action Tasks](#action-tasks). |
| **Estimated Time(In mins)** | Required. FieldKo uses it to extend a visit's planned end when its tasks need more time. |
| **Group Name** | Groups tasks in the app. To filter tasks by visit type, match it to a visit type's label. |
| **Default Survey** | The survey this task opens. You can't set both a default survey and a task action on the same task type. |
| **Possible Reasons for incompletion** | The reasons reps can select when they tap **Can't Do**. Enter them comma-separated. |
| **Task Action Name** / **Task Action Label** | Makes the task open a screen in the app instead of being marked done. The label is the button text, and it's required when you set an action. |
| **Active** | Only active task types can be added to visits. |

### Action Tasks

Set **Task Action Name** to make a task open a screen in the app.

| Task Action Name | Opens in the App |
| - | - |
| Place Order | [Place an Order](/field-work/place-order) |
| Ranging | [Record Core Ranging](/field-work/core-ranging) |
| Visit Note | Notes |
| Next Visit ToDo's | Next Visit To Do's |
| Log an Incident | [Log an Incident](/field-work/log-incident) |

The app also recognizes **pack out** and **display** actions if your org has added those picklist values.

Don't use **New Contact** for mobile reps. The app doesn't support this action and shows a "not implemented yet" message.

<Note>
  On Salesforce screens, action tasks work only when the task type's **name** exactly matches one of the Task Action records that come with FieldKo: "Place Order Action", "Core Ranging Action", "Visit Note Action", "New Contact Action", "Log an Incident Action", or "Next Visit ToDo's Action".
</Note>

## Visit Templates

A visit template is a reusable set of tasks and surveys that reps can add to a visit in one step. Create the task types first.

### Create a Visit Template

Build the template from your active task types:

<Steps>
  <Step title="Start a New Template">
    From the App Launcher, find and select **Visit Templates**, and then click **New**.
  </Step>

  <Step title="Name the Template">
    Enter a **Template Name**.
  </Step>

  <Step title="Add Task Types">
    Select the task types to include. FieldKo preselects each task type's default survey.

    * Tip: To use a different survey for a task, select another active survey.
  </Step>

  <Step title="Optional: Set Task Groups and Products">
    Set a **Task Group** and products for each task.
  </Step>

  <Step title="Save Your Changes">
    Click **Save**.
  </Step>
</Steps>

When reps create a visit, they select the template under **Use Visit Template**.

### Assign Default Templates to Accounts

To have FieldKo create visits with a template automatically, assign the template to accounts, and then turn on the matching setting:

1. On the template, click **Assign to Accounts**, and then select the accounts. FieldKo sets each account's **Default Visit Template**.
2. From the App Launcher, find and select **FieldKo Configuration**.
3. Click **Visit**.
4. Turn on **Create Visits using default Visit Template**.

When a rep drops an account that has a default template onto the calendar, FieldKo creates the visit immediately with that template's tasks. To skip this for an account, select **Ignore Default Visit Template** on the account.

## Visit Types

Visit types, such as "Merchandising" or "Audit", label and color visits. Turn on visit types, and then add a record for each type:

<Steps>
  <Step title="Turn On Visit Types">
    From the App Launcher, find and select **FieldKo Configuration**. Click **Visit**, and then turn on **Allow Special Visits**.
  </Step>

  <Step title="Open the Visit Type Records">
    From Setup, in the Quick Find box, enter `Custom Metadata Types`, and then select **Custom Metadata Types**. Next to **Visit Type**, click **Manage Records**.
  </Step>

  <Step title="Add a Record for Each Visit Type">
    For each record:

    * Set **Color** to a color name or hex code.
    * Select **Is Default?** on one type only.
    * To limit a type to visits created from one object, enter the object's API name in **Object API Name**. Find it in Setup > Object Manager.
  </Step>
</Steps>

The **Visit Configurations** custom setting has related options: **Make Visit Type Required**, **Allow Multiple Visit Type Selection**, **Filter Task Type by Visit Type**, and **Require Task Per Visit Type**. See [Visit Configurations](/admin/configuration-reference#visit-configurations).

## Set Up Check-In Location Checks

FieldKo can record where reps check in and warn them when they're far from the account. The check is a warning, not a block: a rep who's farther away than the distance you set can confirm and check in anyway. To see what reps experience, see [Check In](/visits/visit-details#check-in).

### Turn On the Location Check

Turn on location capture, and then set the distance:

<Steps>
  <Step title="Turn On Capture Geolocation">
    From the App Launcher, find and select **FieldKo Configuration**. Click **Visit**, turn on **Capture Rep's geolocation on visit Check-In and Check-Out**, and then save your changes. This option sets **Capture Geolocation** in the **Visit Configurations** custom setting.
  </Step>

  <Step title="Open Visit Configurations">
    From Setup, in the Quick Find box, enter `Custom Settings`, and then select **Custom Settings**. Next to **Visit Configurations**, click **Manage**.
  </Step>

  <Step title="Set the Distance">
    Edit the org default record, or a profile or user record. In **Max Distance From Store To Checkin**, enter the distance in meters. The package default is 1000.
  </Step>

  <Step title="Save Your Changes">
    Click **Save**.
  </Step>
</Steps>

When a rep checks in farther away than this distance, the app shows **Confirm Check-In**. If the rep taps **Continue**, the app saves "Checked in", the distance, and "meter(s) away from Store" in the visit's **Check In Compliance Reason** field. The rep's location is saved in **Checked In Location**.

If **Max Distance From Store To Checkin** is blank or 0, or the account has no coordinates, the app records the location but doesn't check the distance. Reps who turn off location permission for the app can't check in while **Capture Geolocation** is on.

### Where Account Coordinates Come From

The app compares the rep's location with the account's coordinates. It uses the first of these that has a value:

1. The custom latitude and longitude fields set in **Account Latitude Field API Name** and **Account Longitude Field API Name** in the **Account search result Configuration** custom setting. See [Account Location Fields](/admin/configuration-reference#account-location-fields).
2. The FieldKo **Latitude** and **Longitude** fields on the account, which show the shipping coordinates.
3. The account's shipping latitude and longitude.
4. The account's billing latitude and longitude.

To fill in coordinates for an account that has none, open the account in Salesforce and use the **Update Geolocation** action. It looks up the account's shipping address and saves the shipping latitude and longitude. The action uses the **Google Map API Key** on the **FieldKo Configuration** tab, under **Calendar and Map**.

## Create Visits from Other Objects

By default, reps create visits for accounts. To let reps create visits from another object, such as Opportunity, add a **Visit Creation Configuration** custom metadata record:

1. From Setup, in the Quick Find box, enter `Custom Metadata Types`, and then select **Custom Metadata Types**.
2. Next to **Visit Creation Configuration**, click **Manage Records**.
3. Add a record for the object.

The following table shows what to enter in each field, using an Opportunity record as the example. Where a field asks for an object or field, enter its API name, which you can find in Setup > Object Manager.

| Field | What to Enter |
| - | - |
| **Object API Name** | The API name of the object reps create visits from, such as the Opportunity object |
| **Menu Label** | `Create Visit for Opportunity` |
| **Account ID Field** | The API name of the object's lookup to Account, for example the Opportunity's **Account** field. For Account itself, enter the record ID field's API name. |
| **Display Name Field** | The API name of the field to show as the record's name, such as the Opportunity's **Opportunity Name** field |
| **Display Fields** | The API names of the fields to show, comma-separated, such as **Opportunity Name**, **Stage**, and **Close Date** |
| **Search Fields** | The API names of the fields reps can search, comma-separated, such as **Opportunity Name** and **Stage** |
| **Filter Criteria** | One filter per line: a field's API name, an equals sign, and the allowed values, comma-separated, such as the **Stage** field with the values Prospecting and Qualification |
| **Visit Lookup Field** | A lookup on Visit that stores the record |
| **Sort Order** / **Is Active** | `2` / selected |

## Account-Based Tasks (Objectives)

Use account objectives to assign tasks to many accounts without planning visits. Create an objective, and then assign it to accounts:

1. Create an **Account Objective** with a start date, end date, and **Visit Template**, and then select **Active**.
2. On the objective, click **Assign Accounts**, and then select the accounts.

FieldKo creates a task for each account and each task in the template. The account owner owns each task. If anything fails, FieldKo emails you the errors.

## Next Visit To Do's

Managers and reps can leave tasks and notes for the next visit to an account. Reps do this in the app. See [Next Visit To Do's](/visits/notes-and-follow-ups#next-visit-to-dos). In Salesforce, use the **Next Visit ToDo's** quick action on a visit. FieldKo keeps only one active to-do per account and assignee.

## Visit Rules Enforced by Salesforce

When a visit breaks one of these rules, Salesforce blocks the save and shows the message.

| Rule | Message | What to Do |
| - | - | - |
| Planned end must be after planned start. | "End Date should be greater than Start Date" | Set a planned end that's after the planned start. |
| A visit must have a sales representative. | "Sorry! No Representative for visit/s" | Set the visit's sales representative. |
| A visit must have an account. | "Sorry! No store for visit/s" | Set the visit's account. |
| The planned date must be inside an active call cycle for the rep. | "Sorry! No Call Cycle available. Please Contact your Manager or Administrator" | Create or activate a call cycle for the rep that covers the date. See [Call Cycles](#call-cycles). |
| In Progress and Completed visits need actual start and end times. | "Sorry! Invalid record. Please Contact your Manager or Administrator" | Enter the actual start and end times. |

FieldKo sets the visit's owner to its sales representative. When a visit is completed, FieldKo updates the account's **Last Check-Out** and **Next visit plan date**.

## See Also

* [Build Surveys](/admin/surveys)
* [Plan Visits in Salesforce](/managers/plan-visits)
* [Install and Set Up FieldKo](/admin/installation)
* [Configuration Reference](/admin/configuration-reference)
* [Check In and Complete a Visit](/visits/visit-details)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.