# Installation & Setup

Follow these steps in order. Steps 1–5 are one-time org setup; steps 6 and 7 are repeated for each campaign you want to sync.

## 1. Install the package

Open the installation link below while logged into your org and choose **Install for Admins Only**. Access for other users is granted through the permission set in the next step.

Current version — **1.2.0**:

- Production org: [https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000LVyTAAW](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000LVyTAAW)
- Sandbox: [https://test.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000LVyTAAW](https://test.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000LVyTAAW)

Previous versions — 1.1.0: [production](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000JbWvAAK) · [sandbox](https://test.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000JbWvAAK) · 1.0.0: [production](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000GfdVAAS) · [sandbox](https://test.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000GfdVAAS)

:::note Install links are version-specific
Each release has its own installation link (the `p0=` id is the package version). This page always carries the link for the latest version; Aktify will also send the new link directly when a release ships.
:::

:::caution The link installs into whichever org you're logged into
The installer targets your current browser session. Before clicking **Install**, confirm the username shown top-right is the org you intend — installing into production when you meant a sandbox is an easy mistake. When in doubt, open the link in a private/incognito window and sign in deliberately.
:::

During installation you'll see a warning that you're installing a **Non-Salesforce Application that is not authorized for distribution as part of Salesforce's AppExchange Partner Program**. This is expected — Aktify Lead Sync is distributed directly by Aktify rather than through the AppExchange marketplace. Check the acknowledgment box to enable the **Install** button.

## 2. Assign the permission set

Assign the **Aktify Managed Package Permissions** permission set to every user who creates or manages leads that should sync to Aktify. (The admin performing this setup gets it automatically when they open the Aktify app in step 5 — this step is for everyone else.)

1. Go to **Setup → Permission Sets**.
2. Select **Aktify Managed Package Permissions**.
3. Click **Manage Assignments** and add your users.

Or from the command line:

```
sf org assign permset --name Aktify_Managed_Package_Permissions
```

:::warning Re-assign after reinstalling
Permission set assignments are removed when the package is uninstalled. If you ever uninstall and reinstall the package, you must assign the permission set again — leads created by unassigned users fail to sync silently.
:::

## 3. Add the packaged fields to your page layouts

Installing a package never modifies your page layouts, so the Aktify fields won't appear until you add them.

On the **Lead** layout, add:

- Aktify Campaign Id
- Aktify Synced
- Aktify Sync Failed Reason
- Aktify Lead Status
- Aktify Calls Placed
- Aktify Calls Received
- Aktify Messages Sent
- Aktify Messages Received
- Aktify Undeliverable Reason

On the **Campaign** layout, add:

- Aktify Campaign API Key
- The **Aktify Metadata Mappings** related list (optional — see step 7). Its default column shows each mapping as a summary such as `plan_tier ← Aktify_Plan_Tier__c (default: basic)`; to see the parts as separate columns, click the related list's wrench icon in the layout editor and add **Metadata Key**, **Lead Field**, and **Default Value**. The related list's **New** button opens the same form as the card in step 7, with a dropdown of your Lead fields.

To manage metadata mappings directly on Campaign records, also add the **Aktify Metadata Mapping** component to the Campaign Lightning record page: open a Campaign, choose **Setup (gear) → Edit Page**, drag **Aktify Metadata Mapping** from the *Custom* section of the component list onto the page, then **Save** and **Activate**. This is optional: the same mappings can be edited from the **Aktify Create Lead Config Setting** tab.

:::caution Edit the layout your users actually see
Most orgs have multiple Lead page layouts. Make sure you edit the layout **assigned to your users' profiles**, not just the default one. If the fields still don't appear after you save, hard-refresh the browser or log out and back in — Lightning caches layouts aggressively.
:::

## 4. Enable Campaign creation (if needed)

Users who need to create Campaigns must have the **Marketing User** checkbox enabled on their User record (**Setup → Users**). Without it, the **New** button simply doesn't appear on the Campaigns tab — even for System Administrators — so a "missing" New button means this checkbox, not a package problem.

## 5. Review the sync configuration

Installing the package creates the sync configuration automatically. Opening the config tab (below) completes activation — it grants you the package permission set, verifies the package's credential plumbing, and schedules the hourly status poll under your user. Saving a campaign API key (step 6) does the same, so activation happens during normal setup either way. To review or customize:

1. Open the **App Launcher** and select the **Aktify** app.
2. Open the **Aktify Create Lead Config Setting** tab.
3. Optionally adjust the lead selection criteria (**Save Criteria**) or the **Status Sync Schedule**.

## 6. Connect a campaign

For each Salesforce Campaign whose leads should sync to Aktify:

1. Open the Campaign record.
2. Check **Active**.
3. Paste the campaign API key provided by Aktify into **Aktify Campaign API Key**.

The API key determines which Aktify campaign receives the leads.

4. Add leads to the campaign the way you normally would — **Add Leads** on the campaign, **Add to Campaign** from a list view or report, or an import. Each Lead added becomes a Campaign Member, gets its **Aktify Campaign Id** set automatically, and is posted to Aktify. (Setting **Aktify Campaign Id** directly on a Lead works too.)

If the campaign already had members before you pasted the key, they are synced when the key is saved. To sync members added later while the campaign was inactive, or after an upgrade from an earlier version, open the **Sync Campaign Members** tab in the **Aktify** app and click **Sync Members** on the campaign. See [Campaign Members and the Aktify Campaign Id field](./lead-sync#campaign-members-and-the-aktify-campaign-id-field).

:::tip Campaigns that require metadata
If Aktify told you the campaign requires metadata keys, complete step 7 for this Campaign **before** pasting the key. Otherwise the leads posted when the key is saved are rejected with `Missing required metadata fields`.
:::

:::caution Pasting a key syncs existing leads immediately
Adding an API key to an Active campaign immediately syncs **all** of that campaign's leads that haven't synced yet. See [How Lead Sync Works](./lead-sync#when-a-lead-syncs).
:::

## 7. Map metadata for the campaign (if Aktify requires it)

Some Aktify campaigns use **metadata** on each lead to personalize outreach — for example a `plan_tier` key whose value (`basic`, `plus`, or `premium`) is dropped into the first message. Aktify tells you which keys a campaign expects when they hand you its API key. If a campaign requires a key and a lead arrives without it, Aktify rejects the lead, so set up the mapping **before** you paste the API key.

1. In the **Aktify** app, open the **Aktify Create Lead Config Setting** tab and find the **Aktify Metadata Mapping** card. (Or open the Campaign record, if you added the component in step 3.)
2. Select the Campaign.
3. Click **Add Row** and fill in:
   - **Metadata Key** — exactly the key name Aktify gave you (letters, digits, `_` and `-` only).
   - **Lead Field** — the Lead field whose value should be sent, or leave it as *No Lead field* to always send the default.
   - **Default Value** — sent when the Lead field is blank.
4. Click **Save Mappings**.

Repeat for each key the campaign requires. See [Sending metadata with leads](./lead-sync#sending-metadata-with-leads) for how values are chosen and formatted.

## 8. (Advanced) The callout endpoint

The package calls Aktify through the **Aktify API** named credential (**Setup → Named Credentials**). It points to Aktify production by default and normally should not be changed.

## Updating to a new version

When Aktify releases a new version of the package, we'll send you a new installation link. Upgrading works the same way as installing:

1. Check your current version under **Setup → Installed Packages → Aktify Lead Sync**.
2. Open the new installation link while logged into your org and choose **Install for Admins Only**.

Salesforce upgrades the package in place — your sync configuration, campaign API keys, metadata mappings, page layout changes, lead sync history, and permission set assignments are all preserved. Upgrading from 1.0.0 or 1.1.0 to 1.2.0 works this way.

After upgrading to **1.2.0**, open the **Sync Campaign Members** tab in the **Aktify** app and click **Sync Members** on each connected campaign to post the Campaign Members that earlier versions never synced.

:::warning Pre-release (0.x) versions can't be upgraded in place
Pre-release builds were distributed as Salesforce *beta* packages, which Salesforce does not allow to be upgraded. If your org still has a 0.x build, uninstall it (**Setup → Installed Packages → Uninstall**), then install the current version and repeat steps 2, 3, 5, 6, and 7 above.

Uninstalling removes the packaged fields and their data, including **Aktify Synced**. When you reconnect a campaign after reinstalling, leads that already synced will attempt to sync again; Aktify rejects them as duplicates, so they'll show a duplicate-lead failure reason rather than creating duplicate records.
:::