> ## 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.

# Install and Set Up FieldKo

> Install the FieldKo packages, assign permissions, and complete the setup reps need before they log in.

Install FieldKo in your Salesforce org and get it ready for your reps. This page takes you through setup from start to finish. Work through the sections in order. Each one ends with a quick check so you know it worked before you move on.

| To do this | You need |
| - | - |
| Complete settings on the **FieldKo Configuration** tab | FieldKo Manager Permission Set |
| Run the Metadata Collector | FieldKo Manager Permission Set and FieldKo Native Permission Set |

## Before You Begin

* Get the FieldKo package install link from your FieldKo contact.
* Make sure you can create an API key in Google Cloud. You need it to replace the shared Google Maps key.
* Plan about one session to work through steps 1 to 11. Most of them are one-time tasks.

## Setup at a Glance

1. [Install the FieldKo package](#install-the-fieldko-package).
2. [Install the FieldKo Native package](#install-the-fieldko-native-package).
3. [Assign permission sets](#permission-sets), starting with yourself.
4. [Review the connected app](#connected-app).
5. [Add remote site settings](#remote-site-settings).
6. [Complete the FieldKo Configuration tab](#complete-the-fieldko-configuration-tab), including your [Google Maps key](#google-maps-key).
7. [Run the Metadata Collector](#run-the-metadata-collector).
8. [Create call cycles for reps](#create-call-cycles-for-reps).
9. [Set up tasks, surveys, and visit templates](#set-up-tasks-surveys-and-visit-templates).
10. [Schedule background jobs](#scheduled-jobs).
11. [Send reps the app](#send-reps-the-app), and check that a test visit reaches a rep.

For reference, see [Defaults After Install](#defaults-after-install). To share orders with retailers, see [Customer Portal (Optional)](#customer-portal-optional). When a rep leaves, see [Remove a Rep's Access](#remove-a-reps-access).

## Install the FieldKo Package

1. Open the FieldKo package install link from your FieldKo contact.
2. Select **Admins only** or **Specific profiles**. You grant access to everyone else through permission sets in step 3.
3. Click **Install**, and wait for the installation to finish.

On a new install, the package creates default values for its custom settings. See [Defaults After Install](#defaults-after-install).

**To confirm:** From Setup, in the Quick Find box, enter `Installed Packages`, and then select **Installed Packages**. The FieldKo package is in the list.

## Install the FieldKo Native Package

Install the FieldKo Native package the same way. Install it after the FieldKo package, because it depends on it.

The FieldKo Native package turns on the default mobile visit actions and sets sync to fetch 999 records per request.

**To confirm:** On the **Installed Packages** page, both the FieldKo package and the FieldKo Native package are listed.

## Permission Sets

FieldKo checks **permission set assignments** to decide whether someone is a rep or a manager. Every FieldKo user needs one of the FieldKo permission sets from the FieldKo package. Without one, sync fails with "Insufficient Privilege: User does not have access to FieldKo".

Start with yourself. To complete the FieldKo Configuration tab and run the Metadata Collector in the next steps, assign yourself the **FieldKo Manager Permission Set** and the **FieldKo Native Permission Set**. Then assign permission sets to each manager and rep, using this table.

| User | Assign |
| - | - |
| Rep using the FieldKo Atlas app | **FieldKo Representative Permission Set** and **FieldKo Native Permission Set** |
| Sales manager or FieldKo admin | **FieldKo Manager Permission Set**. To review sync details, attendance, incidents, and pack-outs, or to run the Metadata Collector, also assign **FieldKo Native Permission Set**. |
| Restricted users | **FieldKo Basic Representative** or **Basic Manager Permission Set** marks a user as a rep or manager without granting full access. Use these only if you build your own permission sets alongside them. |
| Experience Cloud (portal) users | See [Customer Portal (Optional)](#customer-portal-optional). |

<Note>
  The FieldKo Native Permission Set grants access to the mobile services, settings, sync logs, and FieldKo Native objects. It doesn't make someone a FieldKo user by itself. Always pair it with the Representative or Manager permission set.
</Note>

This table shows what the main permission sets allow.

| Access | Representative | Manager |
| - | - | - |
| Visits, tasks, survey answers | Create, read, edit, delete | Create, read, edit, delete |
| Task types, surveys, questions, visit templates | Read | Create, read, edit, delete |
| Call cycles | Read, edit | Create, read, edit, delete |
| Orders | Create, read, edit | Create, read, edit, delete |
| Products, price books, contracts | Read | Create, read, edit, delete |
| Tabs | My Visits, Visit Calendar, Visit Planner, Map, Place Order, objectives | Adds Call Cycles, Field Campaigns, Recurring Visits, Account Sets, Clone Visits, FieldKo Configuration, Hierarchical View, and more |

If you sync any of your own objects, also give reps object and field access to them. See [Control What Syncs to the App](/admin/offline-data).

**To confirm:** On each user's record, the **Permission Set Assignments** related list shows the permission sets from the first table. For your own user, check that you can find **FieldKo Configuration** in the App Launcher.

## Connected App

The FieldKo Native package includes the **FieldKo Native App** connected app, which the FieldKo Atlas app uses to log in. The package installs it with these defaults:

* Lets all users self-authorize
* Requires PKCE and rotates refresh tokens
* Keeps refresh tokens until they're revoked
* Relaxes IP restrictions

If your security policy requires stricter settings, tighten these policies:

1. From Setup, in the Quick Find box, enter `Connected Apps`, and then select **Manage Connected Apps**.
2. Click **FieldKo Native App**.
3. Update these policies as needed:
   * **Permitted Users:** Select **Admin approved users are pre-authorized**, and then add your FieldKo profiles or permission sets.
   * **IP Relaxation:** Enforce IP restrictions if reps always connect from known networks.
   * **Refresh Token Policy:** Set an expiry to make reps log in again periodically.
4. Save your changes.

**To confirm:** On the **Manage Connected Apps** page, **FieldKo Native App** is listed. If you changed **Permitted Users**, check that every FieldKo rep's profile or permission set is in the connected app's list. Reps who aren't in the list can't log in.

## Remote Site Settings

FieldKo needs these remote sites. Add any that aren't already there.

| Remote Site | URL | Needed For |
| - | - | - |
| Your Visualforce domain for FieldKo Native | `https://<your-domain>--fieldkonativev1.vf.force.com` | The **Metadata Collector**, which calls the Salesforce Tooling and Metadata APIs. Without it, you see "Error while querying through Tooling API". |
| Google Maps | `https://maps.googleapis.com` | Geocoding accounts, distance calculations, and maps in Salesforce |
| Einstein Vision (optional) | `https://api.einstein.ai` | Planogram image recognition |

Add each remote site in Setup:

1. To find your Visualforce domain, from the App Launcher, find and select **Metadata Collector**. Copy the domain from your browser's address bar.
2. From Setup, in the Quick Find box, enter `Remote Site Settings`, and then select **Remote Site Settings**.
3. Click **New Remote Site**.
4. Enter a name and the URL from the table.
5. Save your changes.
6. Repeat steps 3 to 5 for each remote site you need.

**To confirm:** The **Remote Site Settings** list shows each URL you added. You test the Visualforce domain for real in step 7: if the Metadata Collector runs without "Error while querying through Tooling API", it's set up correctly.

## Complete the FieldKo Configuration Tab

The **FieldKo Configuration** tab holds the main settings for visits, maps, and surveys. Set your record types and Google Maps key first:

1. From the App Launcher, find and select **FieldKo Configuration**.
2. Click **Basic**, and then select the **Account Record Types for Visit Planning** that match your record types.
   * After install, this is set to `Store`.
3. Click **Calendar and Map**, and then enter your own **Google Map API Key**. See [Google Maps Key](#google-maps-key).
4. Work through the remaining settings on **Basic**, **Calendar and Map**, **Visit**, and **Survey**. See [FieldKo Configuration Tab](/admin/configuration-reference#fieldko-configuration-tab).
5. Save your changes.

### Google Maps Key

The package includes a shared default Google Maps key. Replace it with your own.

1. In Google Cloud, create an API key with the Maps JavaScript, Geocoding, Directions, and Distance Matrix APIs enabled.
2. On the **FieldKo Configuration** tab, click **Calendar and Map**.
3. Paste your key into **Google Map API Key**.
4. Click **Save**.

The FieldKo Atlas app's maps and routes don't use this key.

If the key doesn't save on the tab, enter it in Setup instead. The tab saves the key to the **Map Configurations** custom setting. From Setup, in the Quick Find box, enter `Custom Settings`, and then select **Custom Settings**. Next to **Map Configurations**, click **Manage**, and then enter your key in the **Key** field at the default organization level.

#### Billing and Key Restrictions

Google requires a billing account on the Google Cloud project that owns your key. For current prices and free usage, see [Google Maps Platform pricing](https://mapsplatform.google.com/pricing/). To avoid unexpected charges, set a budget alert on the project. See [Create, Edit, or Delete Budgets and Budget Alerts](https://cloud.google.com/billing/docs/how-to/budgets) in the Google Cloud documentation.

Restrict the key so that it works only with the APIs FieldKo uses:

| API | What FieldKo Uses It For |
| - | - |
| Maps JavaScript API | Maps on FieldKo's Salesforce pages |
| Geocoding API | Finding account coordinates from addresses |
| Directions API | Routes on the Salesforce map pages |
| Distance Matrix API | Travel distances and times on the Salesforce map pages |

Use API restrictions only. Don't add a website (HTTP referrer) restriction: FieldKo uses the same key in browser pages and in server-side geocoding from Salesforce, and a referrer restriction blocks the server-side calls. For more about restricting keys, see [Google Maps Platform security guidance](https://developers.google.com/maps/api-security-best-practices).

**To confirm:** Reopen the **FieldKo Configuration** tab. Your account record types are selected under **Basic**, and your key is in **Google Map API Key** under **Calendar and Map**. Then open the **Account Map** tab and check that the map loads.

## Run the Metadata Collector

The Metadata Collector stores your objects, fields, layouts, record types, and profile layout assignments for the app. The app can't sync until you run it.

Before you start, make sure you've completed step 3 (you need the FieldKo Native Permission Set) and step 5 (you need the Visualforce domain remote site).

* Follow steps 1 to 3 in [Collect Metadata](/admin/offline-data#collect-metadata) to collect objects and layouts metadata, and then profiles metadata.

**To confirm:** You see both success messages: "Objects and Layouts Metadata stored successfully." and "Profiles Metadata stored successfully". If you see an error instead, see [Metadata Collector Messages](/admin/offline-data#metadata-collector-messages).

Rerun the Metadata Collector every time you change objects, fields, layouts, or record types. See [Run the Metadata Collector](/admin/offline-data#run-the-metadata-collector).

## Create Call Cycles for Reps

Reps receive visits, tasks, and orders only when they have an **active call cycle** that covers today. Without one, no error appears, and the rep sees no visits.

Create call cycles in either of these ways:

* Create them for each rep. See [Call Cycles](/admin/call-cycles-and-visits#call-cycles).
* Schedule `CallCycleBatchscheduler`, which creates call cycles for this year and next for reps who don't have them. See [Scheduled Jobs](#scheduled-jobs).

**To confirm:** On the **Call Cycles** tab, each rep has an active call cycle that covers today.

## Set Up Tasks, Surveys, and Visit Templates

1. Create task types, surveys, and visit templates. See [Set Up Call Cycles, Tasks, and Visit Templates](/admin/call-cycles-and-visits) and [Build Surveys](/admin/surveys).
2. If your reps take orders or record ranging, set up products, price books, and ranging. See [Set Up Products, Ordering, and Ranging](/admin/products-ordering-ranging).

**To confirm:** You check this in step 11, when a test visit reaches a rep's app with its tasks.

## Scheduled Jobs

The packages don't schedule any jobs automatically. Schedule the jobs for the features you use, in either of these ways:

* From Setup, in the Quick Find box, enter `Apex Classes`, and then select **Apex Classes**. Click **Schedule Apex**, and then select the class.
* In the Developer Console, open **Execute Anonymous**, and run the scheduling code shown in the table.

| Job (Apex Class) | What It Does | Suggested Schedule |
| - | - | - |
| `MissedVisitCheckInScheduler` | Sends Salesforce notifications for missed check-ins and check-outs. Needs **Enable Visit Reminders On Backend** and **Enable Visit Checkin Checkout Reminders**. | Every 15 minutes: run `MissedVisitCheckInScheduler.scheduleEvery15Minutes();` |
| `CallCycleBatchscheduler` | Creates call cycles for this year and next for reps who don't have them | Daily: `CallCycleBatchscheduler.scheduleCallCycleCreationDaily();` |
| `NextVisitToDoAssigneeSchedular` | Applies Next Visit To Do's created in Salesforce to the next planned visit | Hourly, using your own cron expression |
| `VisitSummaryPdfSchedular` | Creates and emails visit summary PDFs | As needed |
| `SendOrderMailsSchedular` | Emails order PDFs to contacts. Salesforce limits single emails to 1,000 per day. | As needed |
| `SplitOrderPDFGeneratorBatchScheduler` | Creates PDFs for split orders | As needed |
| `MeetingInviteScheduler` | Sends meeting invites for visits marked **Send Meeting Invite** | Using your own cron expression |
| `TravelDistanceCalculatorSchedular` | Calculates each rep's daily distance traveled | Daily |
| `CalculateActualTimeWorkedScheduler` (FieldKo Native package) | Totals time spent on completed visits into each day's attendance record | Daily, after working hours |

<Note>
  In Execute Anonymous, start each class name with the FieldKo package's namespace prefix, shown on the Installed Packages page, followed by a period. For `CalculateActualTimeWorkedScheduler`, use the FieldKo Native package's prefix instead.

  For `MeetingInviteScheduler` and `NextVisitToDoAssigneeSchedular`, the built-in helper methods schedule a daily run. To run these jobs more often, schedule them with your own cron expression using `System.schedule()`.
</Note>

**To confirm:** From Setup, in the Quick Find box, enter `Scheduled Jobs`, and then select **Scheduled Jobs**. Each job you scheduled is listed with its next run time.

## Send Reps the App

When setup is complete, give reps what they need to install the app and log in:

1. Share the FieldKo Atlas app links with reps: [App Store](https://apps.apple.com/us/app/fieldko-atlas/id1605506891) for iPhone and iPad, and [Google Play](https://play.google.com/store/apps/details?id=com.fieldko.reactnative) for Android. See [Install the FieldKo Atlas App](/getting-started/install).
2. If you use My Domain or SSO, also share your login URL.

**To confirm the whole setup works**, test it with one rep:

1. Plan a visit for today for the rep. See [Plan Visits in Salesforce](/managers/plan-visits).
2. Ask the rep to log in to the app and wait for the first sync to finish.
3. Check that the visit appears on the rep's **My Visits** screen, with its tasks.
4. In Salesforce, click the **Sync Details** tab, and check that the rep's sync is listed.

If the test doesn't work, use this table.

| What the Rep Sees | What to Do |
| - | - |
| "Insufficient Privilege: User does not have access to FieldKo" | Assign the rep the **FieldKo Representative Permission Set** and **FieldKo Native Permission Set**. See [Permission Sets](#permission-sets). |
| "No profile metadata found. Please contact to you administrator to generate it." | On the **Metadata Collector** tab, click **Collect Profiles Metadata**. See [Metadata Collector Messages](/admin/offline-data#metadata-collector-messages). |
| The rep can't log in | If you changed **Permitted Users** on the connected app, check that the rep's profile or permission set is in the list. See [Connected App](#connected-app). |
| The app syncs, but the visit is missing | Check that the visit's **Sales Representative** is the rep, the rep has an active call cycle that covers today, and the rep owns the account or is on its account team. See [Accounts in Scope](/admin/offline-data#accounts-in-scope). |

If you still can't find the cause, see [Diagnose Rep Issues](/admin/support-diagnostics).

## Remove a Rep's Access

When a rep leaves your company or no longer uses FieldKo, follow the checklist in [Remove a Rep's Access](/platform/day-to-day/remove-a-rep) to deactivate them, revoke app access, and hand their accounts and visits to another rep.

## Defaults After Install

On a new install, the FieldKo package sets these defaults. Upgrades don't change your settings.

| Setting | Default |
| - | - |
| Visit Configurations | Capture geolocation on; post check-in and check-out to the account's Chatter feed |
| Account record type for visit planning | `Store`. Change this on the **FieldKo Configuration** tab, under **Basic**, to match your record types. |
| Visit Duration | 60 minutes |
| Fiscal year start month | Your org's fiscal year setting |
| Distance unit | Kilometers |
| Calendar | Month view |
| Survey Settings | Instructions, partial save, and Save and Next/Previous on |
| Order PDF Setting | Currency `$`, remarks shown |
| Core ranging | Show previously captured ranging |
| Account search results | Up to 2,000 accounts, sorted by name |

The FieldKo Native package turns on these visit actions: Add Note, Add Task, Attach File, Core Ranging, Log an Incident, Next Visit To Do's, Place Order, and View Account. Cancel Visit is off. The package also excludes the **Chatter Only User** profile from metadata collection.

## Customer Portal (Optional)

FieldKo can share orders, price books, and products with retailers through an Experience Cloud site that you build. Setting up the portal takes 3 steps:

<Steps>
  <Step title="Create the Site">
    Create an Experience Cloud site, and add the FieldKo Order, Place Order, Product, and Price Book tabs.
  </Step>

  <Step title="Assign Permission Sets">
    For full access, assign portal users **Community Place/Edit FieldKo Order**. For read-only access, assign **Community View FieldKo Orders** and **Community View FieldKo Pricebooks and Products**. Partner-licensed reps use **FieldKo Community Permission Set**.
  </Step>

  <Step title="Turn On Sharing">
    From Setup, in the Quick Find box, enter `Custom Settings`, and then select **Custom Settings**. Next to **Share Records with Community**, click **Manage**. Select **Enable Sharing** and the matching options, and then save your changes.
  </Step>
</Steps>

Portal users work in the site from a browser. To give community-licensed reps the FieldKo Atlas app, contact FieldKo support at [support@fieldko.com](mailto:support@fieldko.com).

## See Also

* [FieldKo for Admins](/admin/overview)
* [Control What Syncs to the App](/admin/offline-data)
* [Configuration Reference](/admin/configuration-reference)
* [Install the FieldKo Atlas App](/getting-started/install)


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