PK4 Tech

PK4 Projects & Time (also called TimeTracker) can turn qualifying Outlook Calendar events into time entries in Salesforce. An administrator connects your Microsoft 365 organization once, configures which events to import and assigns an Outlook Sync license to each TimeTracker user who needs the integration.

After setup, users continue working in Outlook. They do not need to connect their Microsoft accounts individually or do anything else at all, as long as they have a current Outlook Sync license assigned.

Note: The integration works in one direction: Outlook Calendar → PK4 Projects & Time in Salesforce. Changes made to time entries in Salesforce are not sent back to Outlook.

Before you begin

You will need:

• A PK4 Projects & Time installation of a version where Outlook Calendar integration is available (2.13 or later).
• A Salesforce administrator or other authorized user who can manage App Config, TT Users and PK4 Licenses. The person connecting and configuring Calendar needs the Microsoft Calendar Manager permission-set in Salesforce, together with the relevant TimeTracker record access.
• A Microsoft 365 work or school organization with accessible Outlook mailboxes.
• A Microsoft Entra Global Administrator or Privileged Role Administrator who can sign in and approve the organization's connection. This connector requires one of these roles; an ordinary Microsoft user or a personal Outlook account cannot connect the organization.
• Available Outlook Sync licenses in your PK4 subscription.

The Salesforce administrator and Microsoft administrator may be different people, since a Salesforce administrator role does not automatically provide Microsoft administrator rights.

The connector imports each eligible user's primary Outlook calendar. Secondary calendars, shared calendars or other calendars displayed in Outlook are NOT included.

Choose your rollout order. Connection starts sync automatically for users who already qualify (meaning: They have an Outlook ID on their TT Users record AND they have a current Outlook Sync license). To connect first, configure second and enroll users last, wait until configuration is saved before assigning Outlook Sync licenses. If users already have those licenses and Outlook email addresses, configure the integration before connecting.

1. Connect your Microsoft 365 organization

1. In Salesforce, open the relevant App Config record and go to its Integrations tab.
2. Find the Outlook Calendar tile and select Connect.
3. Read the Connect Outlook Calendar popup. It explains the Microsoft administrator requirement and what the connection will do.
4. Select Connect to Microsoft 365. If your browser blocks the new window or tab, allow it for this operation.
5. On Microsoft's sign-in page, sign in using the administrator account for the organization whose calendars you want to import.
6. Review and approve the permissions Microsoft presents. These allow the application to read calendars and identify mailboxes in your organization.
7. Return to Salesforce after the connection completes.

TimeTracker discovers your Microsoft organization during sign-in. While the Connect popup is open, Salesforce checks for completion automatically. After it confirms the connection and starts sync, the popup closes and the tile shows Sync active. BTW, status also loads when the integration component opens.

Microsoft may ask for account selection, multifactor authentication, or other verification required by your organization's policies.

Sync active means the integration is ready to process eligible users. It does not mean every person in your Microsoft organization is being imported. Each user still needs the TT User setup and Outlook Sync license described.

If the connection attempt expires or fails, return to the Salesforce popup and select Start new attempt. Do not refresh or reuse the Microsoft callback page. Keep any displayed error reference for support.

2. Configure which events to import

On the Outlook Calendar tile, select Configure to open Configure Outlook Calendar.

You can configure the integration before or after connecting. The settings determine event eligibility and the additional values applied when a new time entry is created.

Set the event date window

Each blank field uses its own default. Setting a start date while leaving the end date blank means “from the specified start date through the next 30 days.”

For a historical period entirely before the default window, or a future period entirely beyond it, set both dates. Otherwise, the remaining default bound may leave you with no eligible interval.

The default window moves forward with time. It is not permanently anchored to the day you connected Microsoft or assigned a license.

For example, on October 20, blank date fields give a window of approximately September 20 through November 19. A newly created Outlook event scheduled for August 15 is outside that window. Creating or editing the event today does not make its August start date eligible.

The date test uses the event's start time, not its creation date, last-modified date, or end time. A meeting that starts outside the window is excluded even if part of it overlaps the window.

Configured dates are evaluated in UTC. A configured end date includes that entire UTC day. Blank bounds are rolling timestamps exactly 30 days before and after processing time, so the default boundaries can fall partway through a displayed local day. Salesforce may display the same timestamps in your user's time zone.

These rules apply to initial imports, pulls after configuration changes and notifications about new or changed Outlook events.

Add subject keywords

The keyword fields examine the Outlook event's subject:

Enter one keyword or phrase per line. Matching ignores uppercase and lowercase and looks for text anywhere in the subject. These are literal text matches, not whole-word searches, wildcard patterns, or regular expressions.

For example, put these lines in the inclusion field:

Client
Project review

This admits a subject containing either Client or Project review. It does not require both.

You might also put these lines in the exclusion field:

Personal
Lunch

A meeting called Client lunch would then be excluded even though it matches the inclusion keyword Client.

The system evaluates the date window first, then exclusion keywords, then inclusion keywords. Leave a keyword field empty to apply no restriction of that kind. Empty keyword fields do not remove the default date window.

Private and all-day events are always excluded, regardless of your keywords or dates.

Set defaults for new time entries

Use New time-entry defaults to fill additional TT Detail fields automatically:

1. Select Add field default.
2. Choose a TT Detail field.
3. Enter or select its Value. Depending on the field, the popup presents text, a number, a checkbox, a picklist, or a Salesforce record selector.
4. Repeat for additional fields.
5. Use Remove default to remove a rule. Use Set blank when you intentionally want an allowed field to be empty on newly created entries.

For example, you can set Billable to true if qualifying meetings should be treated as billable time, or select a common project for imported meetings.

Defaults are optional. With no defaults, qualifying meetings still create TT Details. The connector does not require a project, task, or client match before attempting insertion. Your organization's Salesforce validation rules and other time-entry rules still apply.

Defaults apply only when a TT Detail is first created. Changing a default does not rewrite existing time entries. A meeting imported for the first time after the change receives the new defaults.

Select consistent lookup values: a task must belong to the selected project and a client/account must agree with that project's billing account. The popup only offers supported, writable fields. Event identity, user mapping, subject, notes and start/end timestamps are managed by the integration.

Calendar time is not automatically billable time. Imported duration comes from the meeting's scheduled start and end. Set an appropriate Billable default if needed and use your normal review, approval and invoicing processes. Importing a meeting does not prove attendance or automatically approve an invoice.

Choose the organization default when you have several App Config records

The Organization default checkbox identifies the App Config whose Outlook settings should take priority for the organization.

Only one set of Outlook settings is effective for all enrolled users:

• If only one App Config has Outlook settings, its settings are used whether or not the checkbox is selected.
• If several have Outlook settings, those marked Organization default take priority.
• If several are marked as the default, the most recently updated app-key configuration wins.
• If none is marked as the default, the most recently updated app-key configuration wins.

For a predictable setup, designate one App Config as the organization default and maintain the Outlook settings there. Editing a different App Config does not necessarily change the effective settings.

Save and apply your settings

Select Save Outlook settings. On success, the popup closes and Salesforce shows:

Outlook Calendar settings have been saved.

When the organization is connected, saving also requests a fresh pull for eligible users using the effective configuration. This lets previously excluded meetings become time entries when you widen the date range or relax keywords, without having to edit those meetings in Outlook.

The pull runs in the background. The save confirmation means the settings were saved; it does not mean every mailbox has finished processing.

If you tighten filters, existing TT Details are retained. A subsequently processed event that no longer qualifies is marked Excluded in Calendar Review. Saving more restrictive settings is not a bulk cleanup or deletion operation.

If another administrator changed the configuration while your popup was open, use Reload configuration, review the latest settings and reapply your intended changes.

3. Prepare each TT User

For every person whose calendar should be imported:

1. Open their TT User record in Salesforce.
2. Make sure Inactive is unchecked.
3. Enter their work Microsoft mailbox address in Microsoft Outlook Email ID.
4. Save the TT User.

Use the mailbox belonging to the connected Microsoft organization. Map each mailbox to one TT User; do not assign the same mailbox to multiple TT Users.

This address identifies the calendar owner. It does not need to be the email address of the administrator who connected Microsoft.

For administrators working with data imports or APIs, the field is dftlytime__Microsoft_Outlook_Email_ID__c.

4. Assign an Outlook Sync license

The integration checks a PK4 License assigned to the TT User. A Microsoft Calendar Manager permission set or a standard Salesforce user license does not substitute for this module license.

1. Open PK4 Licenses from the Salesforce App Launcher or your app's navigation.
2. Select New, or edit an appropriate existing license assignment.
3. Complete the fields:

4. Save the license.
5. Repeat for other users.

The assignment must be valid today. A future start date does not enroll the user immediately and an expired or inactive assignment does not qualify.

License assignment is subject to your organization's available Outlook Sync entitlement and normal PK4 license validation. If Salesforce reports that no licenses are available, ask your PK4 subscription administrator or support contact to check the entitlement.

When the TT User and license conditions are satisfied, enrollment starts automatically in the background. You can add the email address first or assign the license first; completing the remaining condition triggers the same enrollment process.

The newly enrolled user receives an initial pull using the configured date window, or the default 30 days back and 30 days ahead. They do not need to sign in to Microsoft themselves.

What happens after setup

The integration has three main parts:

1. Salesforce controls eligibility and scheduling. It tracks TT Users, licenses, connection state and time records. Changes to a user's Outlook address, active status, or license request an eligibility check.
2. Microsoft sends change notifications. TimeTracker automatically registers a subscription for each enrolled mailbox. When an event changes, Microsoft notifies the PK4 service through a shared webhook.
3. The PK4 service processes the event. Background workers fetch the current event, check the user's eligibility and your filters and send the result to Salesforce. Salesforce creates or updates the TT Detail and records the outcome in Calendar Review.

Processing is asynchronous. Small changes may appear quickly, while larger initial imports, configuration changes, or temporary provider limits can take longer. A saved Outlook event is not a guarantee of an immediate Salesforce record.

Salesforce also starts periodic checks, approximately every 15 minutes, with subscription maintenance and recovery work requested daily. These checks help reconcile eligibility, recover missed changes and advance the rolling date window.

Microsoft's short-lived access tokens and mailbox notification subscriptions are handled automatically. You do not need to sign in every few hours or every few days. Renewing a notification subscription is different from renewing an access token; both are background responsibilities of the integration. An administrator may need to reconnect if Microsoft access is revoked or organizational policy prevents access.

What becomes a time entry

Each qualifying event occurrence creates a TT Detail, including meetings scheduled in the future. Recurring meetings are processed as individual occurrences.

Repeated notifications and pulls use the stored event identity to update the existing entry rather than create another entry for the same occurrence.

A meeting on two separately licensed users' calendars can create a time entry for each user. Those entries represent each person's scheduled time.

What happens when an event changes

For an existing, unprotected entry that still qualifies, the connector can update the subject, notes and scheduled times from Outlook. It does not reapply creation defaults.

If the entry has been submitted, approved, billed, or edited in tracked fields in Salesforce, a conflicting Outlook change is held for review rather than silently replacing the protected values.

There is an important distinction between filter changes and source-event withdrawal:

• Outside the date window or excluded by keywords: an existing TT Detail is retained.
• Deleted, cancelled, made private, or changed to all-day in Outlook: an unchanged, unprotected imported TT Detail can be removed. If the time entry is protected or has relevant Salesforce edits, it is retained and flagged for review.

Future meetings are imported as scheduled time. If a meeting is cancelled or its duration changes, the resulting entry may therefore change before it is submitted.

Check results in Calendar Review

Open Calendar Reviews from the Salesforce App Launcher. It opens a standard Salesforce object list. Select All Calendar Items to see the available records rather than only recently viewed items.

If you cannot access the object or the relevant records, ask your Salesforce administrator to check your Calendar permissions and record access. The Microsoft Calendar Reviewer permission set supports users responsible for reviewing import outcomes.

Calendar Review stores the latest processed Outlook snapshot and the import outcome. It is not a history of every previous version of an event.

Useful fields include:

• Meeting, Start and End.
• TT User and the resulting TT Detail lookup.
• Outlook Calendar Owner Email — the mailbox that supplied the event.
• Outlook Organizer Email — the meeting organizer, who may be someone else.
• Status and Review Reason.
• Outlook Modified At — the modification timestamp supplied by Outlook.
• Last Synced At — when the connector last stored the processed result in Salesforce.

The snapshot can also include the organizer, location, categories, attendees and a body preview. Some long values are truncated to fit Salesforce fields. Private or withdrawn source content is cleared as part of exclusion handling.

Older records may also show Pending or Imported. Read their reason and linked records rather than assuming those labels describe a new import.

Calendar Review is not a complete mirror of the mailbox. Events outside a full pull's requested range may never be fetched and therefore may have no review record.

Verify your setup

After enrolling one user:

1. Confirm the Outlook Calendar tile shows Sync active.
2. Create a short event in that user's primary calendar, with a start time inside the effective window.
3. Give it a subject that passes your keywords and leave it non-private and not all-day.
4. Allow time for background processing.
5. Open Calendar Reviews → All Calendar Items and find the meeting.
6. Confirm Inserted, the correct TT User and owner email and a populated TT Detail lookup.
7. Open the TT Detail and check its times, duration, notes and creation defaults.

Use a clearly identifiable test meeting and account for its resulting time entry in your normal cleanup process.

Troubleshooting

If you need support, provide the Calendar Review record identifier, relevant timestamps and any displayed error reference. Do not send passwords, access tokens, or the full Microsoft callback URL.

Stop syncing a user or disconnect the organization

To stop one user from qualifying, deactivate their Outlook Sync license, remove their Outlook email mapping, or mark the TT User inactive, as appropriate for your administration process. An expired license also stops the user from qualifying. These changes do not delete previously imported time entries.

To stop the organization's Calendar integration, open Configure and select Disconnect. This stops the integration for its enrolled users; it does not clean up existing TT Details. Removing the application's consent in Microsoft is a separate administrative action.