Evidence Punch Attestation

Note: This extension, a combined integration and workflow model, is developed outside the normal release schedule to meet specific customer needs. To request one of these extensions, you must submit a Salesforce Service Request to UKG. After the extension is delivered to your tenant, you can edit it accordingly.

In some countries, policies exist limiting full time employees to a specified number of worked hours each week. Punches The entries on a timecard that mark the beginning (in-punch) or end (out-punch) of a work interval, such as the beginning of a shift or transfer. from door access control systems, called Evidence Punches, are compared with corresponding In and Out punches from employee timecards. Deviations exceeding specific thresholds are flagged as exceptions in the timecard, and require that the employee provide justification for any discrepancies. The Evidence Punch Attestation The act of confirming or attesting that something is true. For example, when punching out, users may need to attest that they took their meal breaks. extension supports this process.

Evidence Punch Attestation includes:

  • Evidence Punch Import: This integration imports customer-provided evidence punches from the source file in the SFTP inbound folder. The evidence punches are stored in a comment note of a hidden paycode A category of time or money that employees earn, for example, Regular Hours, Bonus, or Sick. specifically configured as a container that is referenced by the process. Only the first and last punches from the day are required for processing.

  • Evidence Punch Attestation: This attestation initiates when an employee clicks the approve button in their timecard. Actual in, actual out, evidence in, and evidence out punches are fetched for comparison to determine whether the difference between actual and corresponding evidence punches is greater than the threshold value. When differences exceeding the configured threshold are found, the employee is prompted to justify the exception with a comment and note. Timecard approval is allowed after all exceptions are justified by the employee.

  • Evidence Punch Attestation Report: This integration provides managers a way to create an audit report that can be run for any Hyperfind A search engine that filters and selects groups of employees through queries that specify conditions or locations (criteria). or Location and date range selection. The report can be configured to show only days with an exception or provide a full audit —all timecard punches + evidence punches + justification. The generated CSV file is placed on the SFTP site where it can be retrieved for automated reporting or accessed in the UI using ad-hoc reporting.

  • Actual In and Out punches must exist in the timecard on days worked.

  • Workflow notifications Informs people to run business processes or integrations, complete forms, or respond to events in business processes. Example: Approve a time-off request. must be enabled on the tenant.

  • Workflow notifications must contain the same tags that are defined in the configuration section related to error notification.

  • Managers and employees must be configured with a notification profile assignment that allows them to receive notifications.

  • Configuration of the following parameters must match across all three modules:

    • Evidence Punch Paycode

    • Evidence Punch Comment

    • Evidence Punch Comment Note

  • Configuration of the following parameters must match between Attestation and Reporting:

    • Justification Comment

  • Evidence Punch Attestation only generates data for days that have actual In punches.

  • Evidence Punch Attestation only processes the first In and last Out punches for a day, regardless of the number of shifts an employee works.

  • When an employee's first punch of the day is an Out punch, it is treated as an Out punch from the previous day.

  • When no records are processed by Attestation, the Evidence Punch Attestation Report does not generate a file; the download link will be disabled.

  • When the Evidence Punch Attestation Report is generated with the option "Export Only Exceptions," the report only contains days with justified exceptions. Days with exceptions that have not been justified are excluded. For example, if the report is generated during the Current Pay Period where timecards are unapproved, it is likely that no data is generated. Best practice is to run the report for a period where exceptions have been justified and timecards approved.

  • The Evidence Punch Import and Evidence Punch Attestation Report integrations run for all employees regardless of employment status — Active, Inactive, and Terminated.

  • When a punch comment contains multiple notes, the integration exports only the first note to the output file.

Timecard punches can differ from evidence punches for various reasons. For example, an employee remains on site for non-work related reasons, such as completion of personal work or attendance at an office party. Or an employee continues working after intentionally punching out in order to complete their work; preventing this overtime situation is the primary reason for Evidence Punch Attestation.

  1. The employee logs on to the system and navigates to their timecard. Imported evidence punches are hidden so only the In and Out punches entered by the employee are visible.

  2. The employee selects the Approve button, initiating a panel that reveals discrepancies between actual and evidence punches.

  3. For each punch where a deviation exceeds the configured threshold, the employee has two choices.

    • Adjust the timecard punch to reflect reality. Pending overtime is routed to the employee's manager for approval.

    • Justify the exception by selecting an appropriate comment from a configured list and entering a corresponding note explaining the justification.

  4. After all exceptions have been justified, the employee approves their timecard.

Before you configure the Evidence Punch Import integration, you must do the following:

  1. Configure Access to Integrations.

  2. Configure the following:
  • Comment: Configure a comment to which the integration adds evidence punch data. The punches category must be selected during configuration. See the Comments topic.

Example: Evidence Punch Data

Paycode: Configure a hidden standard hour Non-overtime hours that each employee is expected to work. paycode that must be used exclusively by the Evidence Punch Import integration. See the Paycode definition topic.

Example: Evidence Punch

  1. Get the URL, User, and Password for the APIGatewayServer.

Version Description
1

Initial release.

The Evidence Punch Import integration imports evidence punches from a source file to the application as a comment note that is attached to hidden paycode edits.
1.1 Addressed a locale translation issue for Japan-based customers.
iPack_v2 The Evidence Punch Import integration delivery is now by way of an iPack.

Deploy the Evidence Punch Import integration

For more information, see the Deploy Integrations 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.
  1. From the list in the left column, search for and select the Pro WFM Evidence Punch Attestation Extension integration.

Note: If the integration does not display, select Browse Integration Packs to search for and select the iPack.

  1. Click Tap Install.

  1. From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button Select items.

Configure the Evidence Punch Import integration settings

Select the environment

  1. Select the Manage tab > Atom Management.
  2. Select your environment.

Select environment extensions

  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass Search button. It can take several seconds before the button becomes active.
  1. Scroll to and select the integration pack: Evidence Punch Import > EvidencePunchImport_iPack_v3.

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.

  1. Select Connection Settings.

  2. From the Connection dropdown list, select and configure the following:

    Connection Settings
    Setting Required Actions
    EvidencePunchImport_iPack_v3_APIGatewayServer Required

    To change the default API gateway server:

    1. Clear Use Default.
    2. Enter the URL to the server.

      Example: <tenantURL>/api
    EvidencePunchImport_iPack_v3_SFTPServer Required

    The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account.

    To change the default SFTP server parameters:

    1. For each field, clear Use Default.
    2. Enter the following values:

      • Enter the name of the internal Host.

      • Enter the number of the Port for the internal SFTP account.

      • In User, enter the username for the internal SFTP account.

      • In Password, select <Encrypted>. Enter the new password for the internal SFTP account.

      • Click Tap Apply.
    EvidencePunchImport_iPack_v3_Locale Required Enable Override.

Configure process properties

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

  2. Select EvidencePunchImport_iPack_v3_CRTConfig 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
_EvidencePunchImport_iPack_v3_Locale_CRT Parameter Name,Locale Policy,Message,Description

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.

  • 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.
  1. Select Cross Reference.

  2. From the Cross Reference dropdown list, select the EvidencePunchImport_iPack_v3 table.

  3. Select Override, which allows you to:

  • Download the tables when you run the integration
  • Edit the table cells in Extensions
  1. When you finish, click tap OK.

EvidencePunchImport_iPack_v3_Locale_CRT: Allows translation of messages and labels into different languages.

Evidence Punch Import - Locale CRT structure
Column name Description
Parameter Name Key for which localization is defined.
Locale Policy

Locale Policy.

You can use an asterisk (*) as a wildcard, but put the less-restrictive locale policy names at the bottom of the table because the integration scans cross-reference tables from the top.
Message

Message shown in Additional Details, or value of the label defined in the Run Summary section.

Comment was not provided.

Description

The description that is shown in Additional Details.

The employee is not assigned a shift.

Note:

  • Localization of integration extensions remains optional, but is supported.

  • The cross-reference table (CRT) holds all messages represented with standard English labels; these apply to all locales when the Locale is set to a wildcard (*).

  • Some or all messages can be translated by adding lines to the table in their preferred translation for specific locales. Messages for the most commonly used Locale Policy should be defined at the top of the CRT.

  • Names of the parameters in the CRT column "Parameter Name" must be used as is. If any parameter value needs to be localized for a different Locale Policy, copy the "Parameter Name" with the * Locale Policy, add a new row to the CRT with the appropriate Locale Policy, and then add the localized values in the Message (or Value) and Description CRT columns.

  • Do not enter values in the CRT column "Description" if it is blank.

  • Do not modify placeholders (<>) or the configurable values that are included in the CRT column "Message" (or "Value").

Sample Locale CRT content
Parameter name Message Description
Error_BlankSourceFileName Source FileName must be configured.  
Error_InvalidCommentNote Mandatory tags, #Inpunch#, or #Outpunch#, or both, are missing from Comment Note.  
Error_InvalidDateDuration Date range passed in the request exceeds the threshold limit of 365 days.  
Error_NoEmployeeIdandHyperfind A Hyperfind or individual employee ID must be provided.  
Error_NoSourceFileFound Source file <Source Filename> not found in SFTP directory.  
Label_AddedPaycodeEdits Added paycode edits  
Label_IntegrationType Integration type  
Label_IntegrationTypeValue Import  
Label_InvalidEmployees Invalid employees  
Label_ProcessedEmployees Processed employees  
Label_UpdatedPaycodeEdits Updated paycode edits  
Message_AdditionalDetails Process completed with transaction errors. Additional details, such as disqualifications, my be accessible using the button below.  
Message_BlankArchiveDirectory When Archive File After Processing is set as True, the Archive Directory must be configured.  
Message_BlankEvidencePunchComment Evidence Punch Comment must be configured.  
Message_BlankEvidencePunchPaycode Evidence Punch Paycode must be configured.  
Message_CommentLength Comment Note must not exceed 250 characters.  
Message_InvalidEmployeeId Invalid employee ID. Employee with ID <employee number> does not exist.
Message_InvalidEvidencePunchComment Evidence Punch Comment <Comment Name> not found.  
MessageInvalidEvidencePunchCommentCategory Comment is not configured with pay code in the selected category.  
Message_InvalidEvidencePunchPaycode Evidence Punch Paycode <Paycode Name> not found.  
Message_WithErrors Integration completed with errors.  
Message_WithoutErrors Integration completed without errors.  

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.
  1. Select Main Menu  > Administration > Application Setup > Integrations Setup > Install Integrations.
  2. Click Tap Create .
  3. In Integration Name enter a unique name, such as EvidencePunchImport_iPack_v3.
  4. (Optional) Enter a Description.

Note: Do not select API Integration.

  1. In File Access, select None to not select a connection.
  2. (Optional) If the person who runs the integration does not 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.

  3. (Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.

  4. 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 A sequence of integrations that can be run on-demand or be scheduled., the integration set stops.

      Completed with Errors — The integration run has errors or could not run.

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

  1. Integration template and parameters
    1. In Integration Template, select EvidencePunchImport_iPack_v3.
    2. Click Tap Assign .
    3. In Integration Parameters, you can override default settings.
    4. Complete the configuration for each integration control parameter value.

    5. Click Tap Save.

      Repeat this step for each integration control parameter that supports the Evidence Punch Import process.

      Integration Parameters
      Parameter name Description / User prompt / Mandatory Template parameter Parameter type
      Date Format

      Default Date format used for date of the evidence punch, such as:

      • yyyy-MM-dd (default)

      • dd-MM-yyyy

      • MM-dd-yyyy

      User prompt = No

      Mandatory = Yes

      		 DateFormat Text
      Evidence Punch Comment

      Comment to hold Evidence Punch Data.

      User prompt = No

      Mandatory = Yes

      		 EvidencePunchComment Text
      Evidence Punch Comment Note

      Note added to the evidence punch hidden paycode.

      #InPunch# and #OutPunch# are mandatory.

      Default =

      Evidence Punch In Time: #Inpunch#

      Evidence Punch Out Time: #Outpunch#

      User prompt = No

      Mandatory = Yes

      		 EvidencePunchCommentNote Text
      Evidence Punch Paycode

      Hidden paycode used as a container for the evidence punches.

      User prompt = No

      Mandatory = Yes

      		 EvidencePunchPaycode Text
      Hyperfind

      Employees for whom this integration will run.

      Both Hyperfind and Location can be selected by user.

      Only active employees are included for the selected time period.

      Default = All Home A query that returns a list of employees associated with a manager's employee group. All Home finds people who are active employees or active users as of today.

      User prompt = Yes

      Mandatory = Yes

      		 HyperfindAndLocation Hyperfind
      Employee IDs

      A comma-separated list of specific employees for whom the integration is 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.

      User prompt = Yes

      Mandatory = Yes

      		 EmployeeID Text
      Locale

      Locale for CRT lookup. If not provided, tenant locale is used.

      User prompt = No

      Mandatory = No

      		 Locale Text
      Source Filename

      Source File name.

      Supports wildcarding for cases such as:

      • new data is appended to a file using a datetime stamp.

      • a file is archived after import.

      It is recommended that a datetime stamp, formatted as yyyymmddHHmm, be appended as a suffix to the Source Filename.

      EvidencePunchImport* supports cases when a new file is created each time that new evidence punch data is added to the SFTP location.

      User prompt = Yes

      Mandatory = Yes

      		 SourceFilename Text
      SourceDirectory

      SFTP directory where the source file is stored.

      Default = /Inbound

      User prompt = No

      Mandatory = Yes

      		 SourceDirectory Text
      Time Format

      Default time format used for punch times in the source file, such as

      hh:mma

      HH:mm (default)

      User prompt = No

      Mandatory = Yes

      		 TimeFormat Text
      Archive Directory

      Directory name for archive files.

      Default = /Inbound/Archive

      User prompt = No

      Mandatory = Optional, when Archive File After Processing is set to false.

      		 ArchiveDirectory Text
      Archive File After Processing

      Determines whether the source file is moved to the archive directory after import.

      Default = false

      User prompt = No

      Mandatory = Yes

      		 ArchiveFileAfterProcessing Text
      Archive Filename

      Name given to the import file after archive; appended with date timestamp.

      User prompt = No

      Mandatory = Optional, when Archive File After Processing is set to false.

      		 ArchiveFilename Text
  2. Make sure 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 integrations to test that the configuration is set up correctly.

Run the integration

  1. Select the integration:
    1. Select Main Menu  > Maintenance > Integrations. 
    2. Click Tap Run an Integration . 
    3. Select the EvidencePunchImport_iPack_v3 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 system assigns a default name, which ends with a date and time stamp.
  2. Set parameters as follows:
    • Hyperfind: Select a Hyperfind query of employees.
    • 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.

      For 3 employees: 13997,15556,20012

    • Source Filename: Specify the Source Filename of the Evidence Punch Import data file.

  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 check the results in more detail:

  1. Click Tap the tile A container that provides navigation or action from its summary view. 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 ensure 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.

The source file contains only the first and last punches of the day for each employee.

Evidence Punch Import - Source file overview
Name Value
File Name <filename>
File Extension csv
Delimiter <Comma-delimited>
Source Directory /Inbound
Header

Yes (1 row)

ID, Date, Time, Type
Footer No
Evidence Punch Import - Source file layout
Column name Comments and examples
ID Employee ID
Date Date of punch. Adheres to format defined in the Date Format parameter of the Punch Import integration parameters.
Time Time of punch. Adheres to format defined in the Time Format parameter of the Punch Import integration parameters.
Type InPunch or OutPunch.

Evidence Punch Import - Source file sample

ID,Date,Time,Type

081-001,2022-02-14,09:38,InPunch

081-001,2022-02-14,21:00,OutPunch

081-001,2022-02-15,09:00,InPunch

081-001,2022-02-15,18:00,OutPunch

API details - Evidence Punch Import
API name Type Resource path Description
Retrieve Comments as Manager GET v1/commons/comments Retrieve comments from the application.
Execute Hyperfind Query POST /v1/commons/hyperfind/execute Retrieve employees from Hyperfind.
Retrieve User Preferences for Current User GET /v1/commons/user_preferences/locale_policy?userCurrent=true Retrieve the locale of the current user.
Retrieve paycodes POST /v1/timekeeping/setup/pay_codes/multi_read Retrieve paycodes from the application.
Integration Executions POST /v1/platform/integration_executions/ Submit integration details.
Integration Executions Update Status POST /v1/platform/integrations/update_status Populate run summary.
Retrieve Timecards as Manager POST /v1/timekeeping/timecard/multi_read Retrieve employee timecards.
Person extension POST v1/commons/persons/extensions/multi_read Get employee sign-off date and locale.
Bulk paycode edits POST /v1/timekeeping/pay_code_edits/import Add paycodes to the employee timecard.

Before you configure the Evidence Punch Attestation business process An organized flow of activities or tasks that achieves a business goal. An automated business process minimizes the amount of paperwork and manual tasks to complete that process by way of automatic actions, online forms, and automatically generated messages., you must do the following:

  • Comment: Create a comment that the employee selects when justifying a punch exception. The punches category must be selected during configuration. See the Comments topic.

Example: Justification Comment

  • Attestation Conditions: Create an attestation condition type of Always. See the Attestation Conditions topic.

  • Attestation Buttons: Create an attestation button type of Timecard Action with a button subtype of Approve. See the Attestation Buttons topic.

  • Attestation Assignments: After you have deployed the Evidence Punch Attestation model, create an attestation assignment, and then select the appropriate attestation condition, attestation button, and business process model. See the Attestation Assignments topic.

Note: The Attestation Profile assigned to employees who use the Evidence Punch Attestation workflow must be configured with the Attestation Assignment.

  • Workflow Notification: Create a generic workflow notification to notify the manager when an Evidence Punch Attestation error occurs. See the Generic notifications topic.

Example: Evidence Punch Attestation Error

Custom Tag options:
Tag Description

<Message1>

<Message2>

Error message
<timeFrame> Time Period
<Error> Error
Version Description
1

Initial release.

Initiated when the employee approves the timecard, the Evidence Punch Attestation business process fetches and compares the employee's actual In and Out punches with the evidence In and Out punches. When the differences between actual and evidence punches exceed a configured threshold, the attestation prompts the employee to justify the exception with a comment and note. After all exceptions are justified, the timecard is approved.
1.1 Addressed a locale translation issue for Japan-based customers.

Note: The process for configuring and deploying this and any other Business Process Extension is the same as all Business Process models.

Migrate the Evidence Punch Attestation business process model to the tenant

Migrate the Evidence Punch Attestation process model to the customer tenant using Setup Data Manager (SDM) Moves and manages configuration data across software and hardware environments. (SDM Setup Data Manager moves and manages configuration data across software and hardware environments.).

  1. Log in to the appropriate tenant.

  2. Go to Main Menu > Administration > Setup Data Manager.

  3. Select the Source tenant where the Process Model resides, and select the template to copy. It is a .zip file. A message appears in the Source column: Source: Import from <filename>.zip.

  4. Click Tap Review and Publish. The Publish Summary panel appears.

  5. Review the Publish Summary panel. It lists the items that were extracted from the migration file. If you approve, click tap Publish with Comment or just Publish.

  6. Click Tap Go to Publish History at the bottom of the panel to view the status of the data transfer. The Publish History page contains a table that lists the items you have published. If there were errors during the transfer, the button under the Errors column for that row is black.

  7. To view details, click tap the appropriate row and click tap View Selected.

  8. On the History for publish run page, click tap Show all to view the setup data that you published, and the errors that occurred, if any, listed by item type and name.

Configure the Evidence Punch Attestation decision tables

Note: Decision tables are configurable based on user requirements and can be changed accordingly. These tables are dynamic and can be updated at any time without redeployment of the process model.

  1. Go to Main Menu > Administration > Application Setup > Business Process setup > Process Models.

  2. Select the EvidencePunchAttestation_v1.1 process and click tap Edit. The process model enters edit mode.

  3. Select the Decision Tables tab.

  4. Click Tap Everyone's, and then select the decision table to edit.

  5. Click Tap Decision Table Editor to add or update the rows in the table.

  6. Click Tap Save and close.

Caution:

  • Values entered in the decision tables are case-sensitive, and must match configured values in the application

  • Do not remove variables, variable names, or variable types from any decision table.

Edit the following decision tables:

EvidencePunchAttestation_Variables_v1_1 — Controls the Evidence Punch Attestation process.

Evidence Punch Attestation Variables - decision table
Variable name Description
EvidencePunchComment Comment to hold Evidence Punch Data.
EvidencePunchCommentNote

Note that integration adds to a comment during punch import processing.

Default =

Evidence Punch In Time: #Inpunch#

Evidence Punch Out Time: #Outpunch#
ThresholdInPunch Amount of time beyond which an In punch is considered as an exception. Format hh:mm.
ThresholdOutPunch Amount of time beyond which an Out punch is considered as an exception. Format hh:mm.
JustificationComment

Comments to be used by employees to justify punch exception.

Comma-separated values without spaces.

Warning: Comment names must not contain commas.
Locale Locale used to display form values and error messages.
DateFormat

Display date format on exception form, such as:

  • yyyy-MM-dd (default)

  • dd-MM-yyyy

  • MM-dd-yyyy

TimeFormat

Display time format on exception form, such as:

  • hh:mma

  • HH:mm (default)
EvidencePunchPaycode Hidden paycode used as a container for the evidence punch data.
WorkflowNotification Notification which is initiated on error.
Admin

Internal user; do not change.

Default value = SERVICES-LEVEL3
API Details - Evidence Punch Attestation business model
API name Type Resource path Description
Retrieve Timecards as Manager POST /v1/timekeeping/timecard/multi_read Retrieve actual punch from timecard.
Update Timecard as Manager POST /v1/timekeeping/timecard Update the punch with justification comment.
Approve Timecard as Employee POST /v1/timekeeping/employee_timecard_approval Approve employee timecard.

Before you configure the Evidence Punch Attestation Report integration, you must do the following:

  1. Configure Access to Integrations.

  2. Configure the following:

  • Function Access Profile (FAP): The administrator who runs the integration must be assigned a FAP which has been configured with the Retrieve Hidden Pay Code Edits via API access control point set as Allowed. See the Function Access Profiles topic.

  1. Get the URL, User, and Password for the APIGatewayServer.

Version Description
1

Initial release.

The Evidence Punch Attestation Report integration exports a report for any Hyperfind or Location and date range.
1.1 Addressed a locale translation issue for Japan-based customers.
2 Enhanced to support multiple justification comments on a punch.
iPack_v3 The Evidence Punch Attestation Report integration delivery is now by way of an iPack.

Deploy the Evidence Punch Attestation Report integration

For more information, see the Deploy Integrations 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.
  1. From the list in the left column, search for and select the Pro WFM Evidence Punch Attestation Extension integration.

Note: If the integration does not display, select Browse Integration Packs to search for and select the iPack.

  1. Click Tap Install.

  1. From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button Select items.

Configure the Evidence Punch Attestation Report integration settings

Select the environment

  1. Select the Manage tab > Atom Management.
  2. Select your environment.

Select environment extensions

  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass Search button. It can take several seconds before the button becomes active.
  1. Scroll to and select the integration pack: Evidence Punch Attestation Report > EvidencePunchAttestationReport_iPack_v3.

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.

  1. Select Connection Settings.

  2. From the Connection dropdown list, select and configure the following:

    Connection Settings
    Setting Required Actions
    EvidencePunchAttestationReport_iPack_v3_APIGatewayServer Required

    To change the default API gateway server:

    1. Clear Use Default.
    2. Enter the URL to the server.

      Example: <tenantURL>/api
    EvidencePunchAttestationReport_iPack_v3_SFTPServer Required

    The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account.

    To change the default SFTP server parameters:

    1. For each field, clear Use Default.
    2. Enter the following values:

      • Enter the name of the internal Host.

      • Enter the number of the Port for the internal SFTP account.

      • In User, enter the username for the internal SFTP account.

      • In Password, select <Encrypted>. Enter the new password for the internal SFTP account.

      • Click Tap Apply.
    EvidencePunchAttestationReport_iPack_v3_Locale Required Enable Override.

Configure process properties

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

  2. Select EvidencePunchAttestationReport_iPack_v3_CRTConfig 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
_EvidencePunchAttestationReport_iPack_v3_Locale_CRT Parameter Name,Locale Policy,Message,Description

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.

  • 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.
  1. Select Cross Reference.

  2. From the Cross Reference dropdown list, select the EvidencePunchAttestationReport_iPack_v3 table.

  3. Select Override, which allows you to:

  • Download the tables when you run the integration
  • Edit the table cells in Extensions
  1. When you finish, click tap OK.

EvidencePunchAttestationReport_iPack_v3_Locale_CRT: Allows translation of messages and labels into different languages.

Evidence Punch Attestation Report - Locale CRT
Column name Description
Parameter Name Parameters defined in EvidencePunchAttestationReport_v2_Locale_CRT process property.
Locale Policy

Locale Policy.

You can use an asterisk (*) as a wildcard, but put the less-restrictive locale policy names at the bottom of the table because the integration scans cross-reference tables from the top.
Message

Message shown in Additional Details, or value of the label defined in the Run Summary section.

Comment was not provided.

Description

The description that is shown in Additional Details.

The employee is not assigned a shift.

Note:

  • Localization of integration extensions remains optional, but is supported.

  • The cross-reference table (CRT) holds all messages represented with standard English labels; these apply to all locales when the Locale is set to a wildcard (*).

  • Some or all messages can be translated by adding lines to the table in their preferred translation for specific locales. Messages for the most commonly used Locale Policy should be defined at the top of the CRT.

  • Names of the parameters in the CRT column "Parameter Name" must be used as is. If any parameter value needs to be localized for a different Locale Policy, copy the "Parameter Name" with the * Locale Policy, add a new row to the CRT with the appropriate Locale Policy, and then add the localized values in the Message (or Value) and Description CRT columns.

  • Do not enter values in the CRT column "Description" if it is blank.

  • Do not modify placeholders (<>) or the configurable values that are included in the CRT column "Message" (or "Value").

Sample Locale CRT content
Parameter name Message Description
Label_HeaderDate Date Apply Date.
Label_HeaderEmployeeName Employee Name Employee Full Name from People Information.
Label_HeaderEvidencePunchIn Evidence Punch In Evidence In-punch.
Label_HeaderEvidencePunchOut Evidence Punch Out Evidence Out-punch.
Label_HeaderID ID Employee ID from People Information.
Label_HeaderJustificationComment Justification Comment Justification Comment.
Label_HeaderJustificationNote Justification Note Justification Comment Note.
Label_HeaderLocation Location Primary Business Structure Represents the logical structure of an organization as it concerns staffing. It contains the locations and jobs to which an employee may be assigned. assigned to employee.
Label_HeaderPunchIn Punch In Employee's first In-punch.
Label_HeaderPunchOut Punch Out Employee's last Out-punch.
Label_HeaderScheduleInOut Schedule In-Out Schedule assigned to employee.
Label_IntegrationType Integration Type  
Label_IntegrationTypeValue Export  
Label_InvalidEmployees Invalid Employees  
Label_ProcessedEmployees Processed Employees  
Label_ProcessedRecords Processed Records  
Message_AdditionalDetails Process completed with transaction errors. Additional details, such as disqualifications, may be accessible using the button below.  
Message_BlankEmployeeId Hyperfind or Individual Employee ID must be selected.  
Message_BlankEvidencePunchPaycode Evidence Punch Paycode must be configured.  
Message_BlankEvidencePunchComment Evidence Punch Comment must be configured.  
Message_BlankJustificationComment Justification Comment must be configured.  
Message_BlankOutputDirectory Output Directory must be configured.  
Message_CommentLength Comment Note cannot exceed 250 characters.  
Message_DateRange The date range passed in the request exceeds the threshold limit of 365 days.  
Message_EvidencePunchCommentcategory Evidence Punch Comment does not have paycode as selected category.  
Message_InvalidEmployeeId Invalid Employee. Employee with ID <employee number> does not exist.
Message_InvalidEvidencePunchComment Evidence Punch Comment <Comment Name> not found.  
Message_InvalidEvidencePunchPaycode Evidence Punch Paycode <Paycode Name> not found.  
Message_InvalidJustificationComment Justification Comment <Comment Name> not found.  
Message_JustificationCommentCategory Justification Comment <Comment Name> does not have punches as selected category.  
Message_NoEmployeeIdAndHyperfind Hyperfind or Individual Employee ID must be selected.  
Message_WithErrors Integration completed with errors.  
Message_WithoutErrors Integration completed without errors.  
Message_WithZeroProcessedRecords Zero records processed.  

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.
  1. Select Main Menu  > Administration > Application Setup > Integrations Setup > Install Integrations.
  2. Click Tap Create .
  3. In Integration Name enter a unique name, such as EvidencePunchAttestationReport_iPack_v3.
  4. (Optional) Enter a Description.

Note: Do not select API Integration.

  1. In File Access, select None to not select a connection.
  2. (Optional) If the person who runs the integration does not 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.

  3. (Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.

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

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

  1. Integration template and parameters
    1. In Integration Template, select EvidencePunchAttestationReport_v2.
    2. Click Tap Assign .
    3. In Integration Parameters, you can override default settings. Click Tap Create.
    4. Complete the configuration for each integration control parameter value.

    5. Click Tap Save.

      Repeat this step for each integration parameter that supports the Evidence Punch Attestation Report process.

      Integration Parameters
      Parameter name Description / User prompt / Mandatory Template parameter Parameter type
      Date Format

      Default Date format used for date of the evidence punch, such as:

      • yyyy-MM-dd (default)

      • dd-MM-yyyy

      • MM-dd-yyyy

      User prompt = No

      Mandatory = Yes

      		 DateFormat Text
      Evidence Punch Comment

      Comment to hold Evidence Punch Data.

      User prompt = No

      Mandatory = Yes

      		 EvidencePunchComment Text
      Evidence Punch Comment Note

      Note added to the evidence punch hidden paycode.

      #InPunch# and #OutPunch# are mandatory.

      Default =

      Evidence Punch In Time: #Inpunch#

      Evidence Punch Out Time: #Outpunch#

      User prompt = No

      Mandatory = Yes

      		 EvidencePunchCommentNote Text
      Evidence Punch Paycode

      Hidden paycode used as a container for the evidence punches.

      User prompt = No

      Mandatory = Yes

      		 EvidencePunchPaycode Text
      Export Only Exceptions

      true: Export data for all dates during the selected period.

      false (default): Export data only for dates with a justification comment during the selected period.

      User prompt = No

      Mandatory = Yes

      		 ExportOnlyExceptions Boolean
      Hyperfind

      Employees for whom this integration is run.

      Both Hyperfind and Location can be selected by user.

      Only active employees are included for the selected time period.

      Default = All Home

      User prompt = Yes

      Mandatory = Yes

      		 HyperfindAndLocation Hyperfind
      Employee IDs

      A comma-separated list of specific employees for whom the integration is 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.

      User prompt = Yes

      Mandatory = Yes

      		 EmployeeIDs Text
      Justification Comment

      Comments to be used by employees to justify punch exception.

      Comma-separated values without spaces.

      User prompt = No

      Mandatory = Yes

      Warning: Comment names must not contain commas.

      		 JustificationComment Text
      Locale

      Locale for CRT lookup. If not provided, tenant locale is used.

      User prompt = No

      Mandatory = No

      		 Locale Text
      Output File Action

      Determines whether output file is written as new, appended, or overwritten.

      Default = Overwrite

      User prompt = No

      Mandatory = No

      		 OutputFileAction Text
      Output Filename

      Output file name.

      User prompt = No

      Mandatory = Yes

      		 OutputFilename Text
      OutputDirectory

      SFTP directory where the report file is stored.

      Default = /Outbound

      User prompt = No

      Mandatory = Yes

      		 OutputDirectory Text
      Time Format

      Default time format to be used for time in Input file, such as

      hh:mma

      HH:mm (default)

      User prompt = No

      Mandatory = Yes

      		 TimeFormat Text
      Timeperiod

      Time period for which to export data.

      User prompt = Yes

      Mandatory = Yes

      		 Timeperiod Timeperiod
  2. Make sure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. Select Administration > Application Setup > Integrations Setup > Access Profiles.

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

Run the integration

  1. Select the integration:
    1. Select Main Menu  > Maintenance > Integrations. 
    2. Click Tap Run an Integration . 
    3. Select the EvidencePunchAttestationReport_iPack_v3 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 system assigns a default name, which ends with a date and time stamp.
  2. Set parameters as follows:
    • Hyperfind: Select a Hyperfind query of employees.
    • 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.

      For 3 employees: 13997,15556,20012

    • Timeperiod: Specify the time period for which to export the Evidence Punch Attestation Report data.

  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:

  1. 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 ensure 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.

Evidence Punch Attestation Report - Target file overview
Name Value
File Name <file name>
File Extension csv
Delimiter <Comma-delimited>
Target Directory /Outbound
Header

Yes (1 row)

ID, Employee Name, Location, Date, Schedule, Punch In, Punch Out, Evidence Punch In, Evidence Punch Out, Justification Comment, Justification Note
Footer No
Evidence Punch Attestation Report - Target file layout
Column name Comments and examples
ID Employee ID from People Information.
Employee Name Employee Full Name from People Information.
Location Primary Business Structure assigned to employee.
Date Apply date. Adheres to format defined in the Date Format parameter of the Punch Attestation Report integration parameters.
Schedule Schedule assigned to the employee.
Punch In Employee's first In-punch.
Punch Out Employee's last Out-punch.
Evidence Punch In Employee's Evidence In-punch.
Evidence Punch Out Employee's Evidence Out-punch.
Justification Comment Justification Comment.
Justification Note Justification Comment Note.

Evidence Punch Attestation Report - Target file sample

ID,Employee Name,Location,Date,Schedule,Punch In,Punch Out,Evidence Punch In,Evidence Punch Out,Justification Comment,Justification Note

081-001,081-001,Organization/United States/Metropolitan Store/Colorado/Super Market/Admin/Store Manager,2022-02-14,09:00AM-06:00PM,07:00AM,07:00PM,09:38AM,09:00PM,Meeting,Project Call

081-001,081-001,Organization/United States/Metropolitan Store/Colorado/Super Market/Admin/Store Manager,2022-02-15,09:00AM-06:00PM,09:00AM,05:00PM,09:00AM,06:00PM,Meeting,Project Call

(This is the Drop-down text)

API details - Evidence Punch Attestation Report
API name Type Resource path Description
Retrieve Comments as Manager GET v1/commons/comments Retrieve comments from the application.
Execute Hyperfind Query POST /v1/commons/hyperfind/execute Retrieve employees from Hyperfind.
Retrieve User Preferences for Current User GET /v1/commons/user_preferences/locale_policy?userCurrent=true Retrieve the locale of the current user.
Retrieve Symbolic Periods GET /v1/commons/symbolicperiod Retrieve symbolic period.
Retrieve Locale Date Span GET /v1/commons/symbolicperiod/read Retrieve locale date span.
Retrieve Paycode Multiread POST /v1/timekeeping/setup/pay_codes/multi_read Retrieve paycodes from the application.
Retrieve Schedule POST /v1/scheduling/schedule/multi_read Retrieve employee schedule.
Retrieve Timecards as Manager POST /v1/timekeeping/timecard/multi_read Retrieve employee timecard.
Integration Executions POST /v1/platform/integration_executions/ Submit integration details.
Integration Executions Update Status POST /v1/platform/integrations/update_status Populate run summary.