Mobile Punch Time Zone Adjustment

Overview

In some regions, business locations such as stores are in different time zones. These locations can be close enough that employees transfer between the locations. Employees can use their mobile device to punch. However, the employee’s default time zone is always used because the geolocation of the punch and the time zone at scheduled locations are not linked. Transfer punches can be offset from the scheduled start and end times, and result in unexpected punch exceptions, shortfalls, or overtime. Managers modify the punches to make corrections.

Note: Greenwich Mean Time (GMT) is not offset from Coordinated Universal Time (UTC).

Example

The Beach Store is located in Queensland (GMT+10).
The Mall Store is located in New South Wales (GMT+11).
Employee’s home store = Mall Store.
Employee is scheduled to start at 9 am in the Beach Store.
The punch in at 9 am at the Beach Store is recorded as 10 am by the mobile device.

Expectation:

Depending on the transfer direction, adjust the punch times (+/-).
Depending on the time zone, adjust the punch by 1:00 or 0:30 hours.

Example time-zone adjustments

Example Mobile Punch Time Zone Adjustments

Home store	Scheduled store	Punch adjustment	Note
Burleigh QLD	Tweed Heads NSW	+1:00	GMT+10 > GMT+11
Tweed Heads NSW	Burleigh QLD	—1:00	GMT+11 > GMT+10
Mount Gambier SA	Warnambool VIC	+0:30	GMT+10:30 > GMT +11
Warnambool VIC	Mount Gambier SA	—0:30	GMT+11 > GMT+10:30

Daylight saving time

Some time zones have the same GMT offset but don’t observe daylight saving time (DST) or may start and end DST on different dates.

Example: Sydney NSW and Brisbane QLD share the same time zone (GMT+10), but Brisbane does not change to summer time.

Example time zones and DST

Example Time Zones and Daylight Savings Times in Australia

Time zone and city	Offset	DST start	DST end
Australian Western Standard Time (AWST), Perth WA	GMT+8	DST not observed	DST not observed
Australian Central Standard Time (ACST), Adelaide SA	GMT+9:30	Last Sunday in October at 2 am	Last Sunday in March at 3 am
Australian Eastern Standard Time (AEST), Sydney NSW	GMT+10	First Sunday in October at 2 am	first Sunday in April at 3 am
Australian Eastern Standard Time (AEST), Brisbane QLD	GMT+10	DST not observed	DST not observed

The punch adjustment logic of the integration accounts for these differences.

Examples:

Transfers between locations in the same time zone with the same DST = do not adjust punches.
Transfers between locations in the same time zone with different DST = adjust punches only during the summer according to the correct DST start and end dates.

Considerations and limitations

All shifts must be worked in the same time zone; this integration does not adjust times for shift segments. If an employee works a single shift that is split between locations in different time zones, you must make the punch adjustments manually.
Employees must be scheduled in advance for the transfer locations; this integration does not make adjustments for transfers that employees initiate.

Before you start

Before you configure this integration, you must do the following:

Configure Access to Integrations.
Configure the following:
- Hyperfind: Create a Hyperfind that identifies employees who work in locations in different time zones. See the Hyperfind Queries topic.
- Comment: Create a comment to add to adjusted punches to identify the home and worked time zones. Select the Pay Codes category during configuration. See the Comments topic.
  
  Example: Adjusted by Mobile Punch Time Zone Adjustment
Get the URL, User, and Password for the APIGatewayServer.

Configure the Mobile Punch Time Zone Adjustment integration

Deploy the Mobile Punch Time Zone Adjustment integration
Note: For more information, see the Deploy Integration Packs to your Atom topic.
1. Open the Integration Template Designer: Select Main Menu Administration > Application Setup > Integrations Setup > Design Integration Templates.
  
  Note: If prompted, enter your Username and Password. Click Tap Log in.
2. Make sure that the Account is correct. If not, select the right account.
3. Select the Deploy tab > Integration Packs.
4. From the list in the left column, search for and select the Pro WFM Mobile Punch Time Zone Adjustment Extension integration.
  Note: If the integration does not display, select Browse Integration Packs to search for and select the iPack.
5. Click Tap Install.
6. From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button .
7. Configure Access to Integrations.
Configure the Mobile Punch Time Zone Adjustment integration settings
1. Select the environment
  1. Select the Manage tab > Atom Management.
  2. Select your environment.
2. Select environment extensions
  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass . It can take several seconds before the button becomes active.
  3. Scroll to and select the integration pack: Mobile Punch Time Zone Adjustment > MobilePunchTimeZoneAdjustment_iPack_v2.

Configure connection settings

Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

Select Connection Settings.

From the Connection list, select and configure the following:

Connection Settings

Connection Settings for the Mobile Punch Time Zone Adjustment integration

Setting	Required	Actions
MobilePunchTimeZoneAdjustment_iPack_v2_APIGatewayServer	Required	To change the default API gateway server: Clear Use Default. Enter the URL to the server. Example: `<tenantURL>/api`
MobilePunchTimeZoneAdjustment_iPack_v2_Locations_CRT	Required	Enable Override.

Setting

Required

Actions

MobilePunchTimeZoneAdjustment_iPack_v2_APIGatewayServer

Required

To change the default API gateway server:

Clear Use Default.
Enter the URL to the server.
Example: <tenantURL>/api

MobilePunchTimeZoneAdjustment_iPack_v2_Locations_CRT

Required

Enable Override.

Configure process properties

Select Process Properties.
Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

Select MobilePunchTimeZoneAdjustment_iPack_v2 to set process properties that must be configured before the integration can run. This main process starts the integration process and handles errors.

Process properties

Process property name	Column header value
_MobilePunchTimeZoneAdjustment_iPack_v2_Locations_CRT	Location,Time Zone

Configure cross-reference tables

Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

Note:

If more than one row matches a reference value, the first match is the output value.
If no match is found, the output value can be null, or the integration can produce errors.

Select Cross Reference.
From the Cross Reference dropdown list, select the MobilePunchTimeZoneAdjustment_iPack_v2_Locations_CRT table.
Select Override to:
- Download the tables when you run the integration
- Edit the table cells in Extensions
When you finish, click tap OK.

MobilePunchTimeZoneAdjustment_iPack_v2_Locations_CRT: Gets the time zones of the locations.

Note: You can use wildcards.

Mobile Punch Time Zone Adjustment — Locations CRT structure

Column name	Description
Location	Name of the location.
Time Zone	Use the database name for the time zone.

Install the Mobile Punch Time Zone Adjustment integration

After the integrations are deployed and the connection settings and process properties are configured, install the integrations to make them available for running or scheduling.

Note:

An integration template is the configured integration that you deploy to an Atom and then install to make available for running or scheduling.
An installed integration is a single instance of an integration that is based on an integration template. When you install an integration, you can define parameters or set parameters to be defined when the integration is run.

Select Main Menu Administration > Application Setup > Integrations Setup > Install Integrations.
Click Tap Create .
In Integration Name, enter a unique name, such as MobilePunchTimeZoneAdjustment_iPack_v2.
(Optional) Enter a Description.

Example: This integration adjusts the punches based on the time zone of the scheduled location when employees use their mobile device to transfer between these locations.

Note: Do not select API Integration.
In File Access, select None to not select a connection.
(Optional) If the person who runs the integration doesn't have full access to integrations, select Execute Integration with System Account. This allows the integration access to all APIs in the FAP, and the relevant permissions and data, regardless of the FAP and GDAP of the person who runs the integration.
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
Email Notifications

(Optional)
1. Select Yes to send email and control center notifications for integration runs.
2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces:
  In Progress — The integration run started and has not finished.
  Completed — The integration ran successfully without errors.
  Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
  Completed with Errors — The integration run has errors or could not run.
In Skip Configuration, select None(default) to allow multiple integrations to run at the same time or with the same data without restrictions.
Note: Do not select Allow Minute Interval.
Integration template and parameters
1. In Integration Template, select MobilePunchTimeZoneAdjustment_iPack_v2.
2. Click Tap Assign .
3. In Integration Parameters, you can override default settings. Click Tap Create .
4. Complete the configuration for each parameter.
5. Click Tap Save.
Repeat this step for each integration control parameter that supports the Mobile Punch Time Zone Adjustment process.

Integration parameters

Parameter name	Description / User prompt / Required	Template parameter	Parameter type
Data Source	The source of punch data for this integration. Default = `Time Stamp`. User prompt = No Mandatory = No Note: Only the Time Stamp option is supported, and manually added punches are excluded.	DataSource	Text
Hyperfind	Hyperfind or location for which the integration will run. Default = `All Home` User prompt = Yes Mandatory = Yes Note: Ad-hoc Hyperfinds are not supported. All Home does not include terminated and inactive employees even if they have totals during the period. To include these totals, configure a Hyperfind that includes terminated and inactive employees, and select that Hyperfind in this process property. The maximum number of employees in a Hyperfind is 3500. To process more employees, divide the population into smaller Hyperfinds to run sequentially.	HyperfindAndLocation	Hyperfind
Employee IDs	Comma-separated list of employee IDs for which the integration will run. When no value is entered, the integration defaults to the Hyperfind parameter. To process the integration for only a limited group of employees, enter the person numbers as defined in the source system, each separated by a comma (,) but not spaces. Example: `13997,15556,20012` User prompt = Yes Mandatory = No	EmployeeIDs	Text
Time Period	The date range or symbolic time period for which the integration is run. Supported values include: `0` = Previous pay period `1` = Current pay period `2` = Next pay period `3` = Previous schedule period `4` = Current schedule period `5` = Next schedule period `6` = Week to date `7` = Last week `8` = Yesterday `10` = Range of relative dates `11` = Specific date `12` = Relative specific date `13` = Today User prompt = Yes Mandatory = No	TimePeriod	Time period
Update Comment	The comment that identifies the adjusted punch. Default = `Adjustment by Mobile Punch Time Zone Adjustment`. User prompt = No Mandatory = Yes	UpdateComment	Text

Ensure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. See Configure Access to Integrations .

Run and test the Mobile Punch Time Zone Adjustment integration

Run integrations to test that the configuration is set up correctly.

Note: You can re-run this integration until the last sign-off date.

Run the integration
1. Select the integration:
  1. Select Main Menu Maintenance > Integrations.
  2. Click Tap Run an Integration .
  3. Select the MobilePunchTimeZoneAdjustment_iPack_v2 integration from the list. Click Tap Select.
  4. (Optional) Enter a unique Integration Run Name to make it easier to identify the run of the integration. Otherwise, the default name ends with a date and time stamp.
2. Set parameters as follows:
  - Hyperfind: Select a hyperfind query of employees.
  - Individual Employee ID: To process data for only a limited group of employees, enter the person numbers, as defined in the source system, each separated by a comma ( ,) but no spaces.
    Example:
    
    Generate a report for an individual or a few employees to show what they were paid and whether those amounts are correct.
    For 3 employees: 13997,15556,20012
  - Time Period: Select a pay period.
3. Select the following:
  - Run Integration: If this is the first time this integration is being run.
  - Re-Run: If this integration has been run before, and the status is not In-Progress, you can run the integration again without entering the parameter values again. Click Tap Yes to continue, or No to not run the integration and to return to the parameter settings.
4. Wait for the confirmation that the integration completed or failed. Close the panel.
5. Click Tap Refresh .
6. To see details, select the integration run. Select Run Summary.
Check the results
Status indicators
- In-Progress: The run of this integration has not yet completed.
- Completed: The integration ran successfully without errors.
- Scheduled: This integration is scheduled to run later or repeatedly.
- (Grayed out) Scheduled but Deleted: This integration is scheduled to run, but the integration template has been deleted. When it runs, it will generate an error. To prevent this error, delete the scheduled integration run.
- Completed with Errors: The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
- Failed: The integration run has errors or could not run.
- To troubleshoot and resolve errors, do the following:
  Check the Run Summary for details.
  - To troubleshoot all types of errors, or if the Run Summary shows a large number of errors, click tap Go to Additional Details (if available), or click tap the Source File to open and examine the input source file.
  - (Only for import integrations) To troubleshoot and resubmit integrations that have transactional or data errors, click tap Go to Transaction Assistant.
To check the results in more detail, do the following:
1. To see detailed results, click tap the tile for the integration run.
2. Click Tap Run Summary to see the results of the integration run.
  Example Run Summary details
  
  Note: The available details vary by integration and configuration.
  - Integration Run Name: Name of this run of the integration.
  - Process Name: Name of any integration set that includes this integration.
  - Integration Name: Name of the installed integration.
  - Integration Reference ID: Unique identifier for this integration run (to help in troubleshooting errors).
  - User: The person or user account that ran the integration.
  - Integration Type: Import, Export, or None
  - Start Date: Date and time when the integration run started.
  - End Date: Date and time when the integration run finished.
  - Status: In-Progress, Completed, Completed with Errors, or Failed.
  - Records Processed: Number of records that were processed.
  - Records Created: Number of records that were created.
  - Errors: Number of records that failed.
  - Source Files, Output File, and Error Files: For file-based import integrations, use Manage SFTP to access the source and output files on the inbound (source) and outbound (destination) SFTP folders. See the Manage SFTP topic.
3. Log in to the destination system and make sure that the data has been correctly updated.
Note: You can schedule integrations and integration sets to run once later or at a recurring frequency. See the Schedule Integrations topic.

APIs

API details

APIs for the Mobile Punch Time Zone Adjustment integration

API name	Type	Resource path	Description
Retrieve Symbolic Periods	GET	/v1/commons/symbolicperiod	Returns all symbolic periods in the system.
Execute Hyperfind Query	POST	/v1/commons/hyperfind/execute	Executes a Hyperfind query by ID or qualifier and returns the result.
Retrieve Timecards as Manager	POST	/v1/timekeeping/timecard/multi_read	Returns a list of timecards based on the employees or Hyperfind details provided.
Retrieve Timezone by ID	GET	/v1/commons/setup/timezones/{id}	Returns a timezone by ID.
Submit Integration Execution Additional Details	POST	/v1/platform/integration_executions/{id} /additional_details	Submits all additional details related to an integration execution (API or batch) into system.
Update Integration Execution Details	POST	/v1/platform/integrations/update_status	Updates and returns the callback instance against the provided integration execution details.
Retrieve Comments as Manager	GET	/v1/commons/comments	Returns a filtered list of Comments.
Retrieve Schedule	POST	/v1/scheduling/schedule/multi_read	Returns a schedule pertaining to a set of employees or locations within a specified date range.
Retrieve Locale Date Span	POST	/v1/commons/symbolicperiod/read	Returns a locale date span, or symbolic period, according to the data provided.
Retrieve Persons	POST	/v1/commons/persons/extensions/multi_read	Returns multiple person records based on search criteria.
Update Timecard as Manager	POST	/v1/timekeeping/timecard	Updates a timecard for an employee as a manager.

Version history

Version	Description
1	Initial release.
iPack_v2	The Mobile Punch Time Zone Adjustment integration delivery is now by way of an iPack.