GTOR Document Attachment with HRSD

Note: This 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. is an extension model that is developed outside the normal release schedule to meet specific customer needs. To request one of these models, you must submit a Salesforce Service Request to UKG. After the model is delivered to your tenant, you can edit it to meet your needs.

Many organizations allow employees to submit absence requests using global time-off requests Request subtypes that employees use to request time off for vacation, illness or recovery, appointments, personal time, or other absences. Time-off requests can be configured to support many different employment scenarios. (GTOR). In some cases, supporting documentation is required to justify the absence request before it can be submitted for approval. This workflow extension offers a seamless user experience for providing documentation.

The GTOR Document Attachment with HRSD workflow process connects UKG Pro Workforce Management (UKG Pro WFM) with the HR Service Delivery (HRSD) platform. Users access the HRSD Document Manager module with SSO to upload and store HR documents in a central location. This location, which adheres to compliance and security measures, is structured by companies to enable rapid document access.

The process allows users to:

  • Attach a document as part of the absence request process.

  • Initiate the document upload task from UKG Pro WFM.

  • Verify that a document has been uploaded to the system.

Because not every absence requires justification, only paycodes A category of time or money that employees earn, for example, Regular Hours, Bonus, or Sick. that require documentation are chosen for processing. Two validation options, configured on a paycode basis, are offered:

Suspend Request = Yes: This more restrictive option, of the two, requires documentation before the request can proceed to the approval sequence Requests can be configured to require approval by a series of people. Example: A time-off request goes first to the manager, then to human resources, and finally to another supervisor. Each must approve the request.. The designated approver remains unaware of the requested absence until a justification document is uploaded by the employee.

Suspend Request = No: This option allows the request to proceed to the approval sequence even when the justification document is not provided. The manager is able to react quicker to the upcoming absence. If the document is not available at approval, the manager assumes responsibility for ensuring that the employee provides the document at a later time.

When employees submit an absence request, the process checks whether documentation is required. The employees receive a message indicating that a task is assigned to them in Control Center. Multiple options to justify the request are in the assigned task.

Option 1 — Upload a new document: This option starts the document upload from UKG Pro WFM.

  • A hyperlink on the Control Center task provides navigation to Document Manager with SSO.

  • The employee uploads the required document in HRSD Document Manager. Details of the uploaded document are presented to the employee.

  • The employee returns to the Control Center to complete the task, ending the process.

Note: Suspended requests remain suspended until documentation is provided. The task remains active in Control Center until completed by the document upload.

Option 2 — Connect an existing document: This option is used when the document has already been uploaded directly into HRSD Document Manager.

  • From the Control Center task, the employee is prompted for the document upload date.

  • UKG Pro WFM retrieves the documents from HRSD Document Manager found on the specified date and presents them to the employee.

  • The employee selects the appropriate document, and then completes the task.

Option 3 — Cancel this request: This option cancels an unapproved request.

  • The action removes the task and cancels the request.

Note: This action can only be performed on unapproved requests.

Until the employee completes the document attachment task, the workflow keeps the request in a suspended state. A schedule tag A graphic on the schedule that identifies a specific characteristic that applies to a specific employee on a specific day. Not a shift or a pay code. Example: On call., such as Document Pending, displays on the requested date in Schedule Planner.

After the task is completed, the workflow updates the schedule tag with another tag, such as Document Provided, and then places the request in a Pending Approval state. A workflow notification Informs people to run business processes or integrations, complete forms, or respond to events in business processes. Example: Approve a time-off request. containing a hyperlink to the document is sent. Upon manager approval of the request, the shift override is placed in the Schedule Planner. A comment and note containing document details are added to the paycode for future reference.

  • Notifications are configurable for both the employee and designated approver. The employee receives notifications when the document attachment task is assigned and completed. The approver receives a notification when the document is provided. Notifications are sent to both the employee and approver when the absence request transitions from a suspended to a submitted state, and when the request is processed.

    • Users of this business process can take advantage of the enhanced cancellation request states.

    Organizations that have enabled the UseNewRequestCancelSubmittedStatuses feature switch will see new states:

    • Cancel Approved — the employee's request to cancel a previously approved request is approved.

    • Cancel Refused — the employee's request to cancel a previously approved request is refused.

    Existing Canceled and Approved states remain, and retain their original use.

    • The HRSD team must provide configuration information during deployment for:

    HRSD Client ID

    Application ID

    Application Secret

    URLs

    SSO

    • Function access profiles assigned to employees and managers must allow access to Control Center and basic access to request or approve time off.

    • Notification profiles must be assigned to employees and managers.

    Before you configure the GTOR Document Attachment with HRSD process model, you must configure the following:

    • Comments: Configure a comment that is added to the paycode upon absence request approval. Select Pay Codes from the Available Categories list. See the Comments topic.

      Example: Document Details

    • Reviewer lists: Create a Scheduling Requests reviewer list to ensure that confidential documents are dynamically routed to the correct approver. Add the appropriate reviewer at each of the required steps. For example, Leave Administrator, Attendance Administrator, Manager, or a named user. See the Reviewer Lists topic.

      Note:

      • Only one reviewer is configured at each step. Do not repeat the same reviewer on multiple steps.

      • Assign the Reviewer List to the employee in People Information under Timekeeping > Approvals & Reviewers.

    • Schedule tags: Configure schedule tags to display justification document status in the Schedule Planner. See the Tag Definitions topic.

      Examples: Document Pending or Document Provided

      Note: Do not delete schedule tags created by this workflow process from the Schedule Planner.

    • Workflow notifications: Configure a generic workflow notification to send the justification document details to the approving manager and employee. See the Configure Notifications for Business Processes topic.

      Example:

      Name: Document Attachment Notification

      Long Message:

      Pay Code: <Paycode>

      Date: <TimeDuration>

      Document Provided: <Document Name>

      Document ID: <DocumentID>

      Document Link: <DocumentLink>

      Control center fields:
      Field Label Value Description
      1 Paycode <Paycode> Absence Paycode
      2 Date <TimeDuration> Time off duration.
      3 Document Provided <Document Name Name of the uploaded document.
      4 Document ID <DocumentID Document ID of the uploaded document.
      5 Document Link <DocumentLink> Link to the uploaded document.

      Select one or more checkboxes from the Recipients area.

      Select Do not suppress duplicates.

      Note: For best results, tags used in the workflow notification must match both workflow process logic parameters and parameter values in Document Attachment decision tables. These include: <Paycode>, <TimeDuration>, <Document Name>, <DocumentID>, and <DocumentLink>.

    • Request subtype transition Suspends a request between state transitions, such as pending and approved, while a business process completes a task. Example: Pause a process until a manager completes and submits a form.: Configure the request subtype Classifications of schedule requests from employees. transition to manage the various time-off request state transitions. After configuration, the request subtype transition must be attached to the request subtype used in the workflow process. See the Request Subtype Transitions topic.

      Example:

      Name: Document Attachment

      External Actions
      Select From State Select To State Select Pre-Processing Select Post-processing
      Draft Submitted DocumentAttachment_v2  
      Validation Actions
      Select From State Select To State Select Pre-Processing Select Post-processing
      Pending Cancelled   DocumentAttachment_v2
      Approved Cancelled   DocumentAttachment_v2
      Submitted Refused   DocumentAttachment_v2
      Pending Refused   DocumentAttachment_v2
      Pending Approved   DocumentAttachment_v2
      Cancel Submitted Cancelled   DocumentAttachment_v2

      Note: The business process must be deployed with External Action and Validation Actions as Template Categories for it to be available to attach to the request subtype transition.

    • Request subtype: Configure the request subtype with the request subtype transition. In the Request Subtype Transition list, select the request subtype transition, such as Document Attachment. This configuration initiates the business process. See the Configure Request Subtypes topic.

    • Message configuration: Customize the time-off request acknowledgment for one-click request submission. See the Translation - User Interface topic.

    1. Select Main Menu  > Administration > Application Setup > System Configuration > Translation > User Interface.

    2. Select the Export option.

    3. Select the appropriate Language, and Country.

    4. Select Master Container from the Domain list. The Group list is populated.

    5. Select container_web-common_timeoffRequest_strings.properties and container_web-common_one-click-time-off_strings.properties from the Group list.

    6. Click Tap Export. An Excel file automatically downloads.

    Customize the message configuration

    1. Open the downloaded Excel file and search in each worksheet for parameters:

      2. one-click-time-off.success.suspended.message

      timeoff.success.suspended.message

    2. For each parameter, enter a TRANSLATED_VALUE in Column C of each worksheet.

    3. Save the file.

    Modified Excel file sample
    A B C
    KEY ORIGINAL_VALUE TRANSLATED_VALUE
    one-click-time-off.success.suspended.message Your time-off request has been suspended. You have been assigned a task to provide a document for this request. GoTo Control Center.
    timeoff.success.suspended.message Your time-off request has been suspended. You have been assigned a task to provide a document for this request. GoTo Control Center.

    Upload customized message configuration

    1. Select Main Menu  > Administration > Application Setup > System Configuration > Translation. > User Interface.

    2. Click Tap the Import option.

    3. Click Tap Choose File.

    4. Select the modified Excel file and click tap Open. File Name is populated.

    5. Click Tap Upload.

    Version Description
    1

    Initial release.

    Provides a mechanism for employees to attach supporting documentation to global time-off requests (GTOR).
    1.1 Enhancement allows users to take advantage of the enhanced cancellation request states.
    2

    The GTOR Document Attachment with HRSD extension now:

    • supports Reviewer List and multi-step Approval Settings.

    • applies the schedule tag only on the first day of the time off request.

    • removes redundant confirmation when only one document is uploaded.

    • includes Go Back buttons in the forms to improve usability.

    • is optimized to use the appropriate ID when making API calls to HRSD.

    • fetches the schedule tag color values using an API call.

    • is no longer known as Document Attachment.

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

    Migrate the process model to the tenant

    Migrate the GTOR Document Attachment with HRSD 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 GTOR Document Attachment with HRSD 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 DocumentAttachment_v2 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 system.

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

    Edit the following decision tables:

    DocumentAttachment_v2_InternalParameters — Controls internal document attachment parameters.

    Document Attachment — Internal Parameters decision table structure
    Parameter name Description Default value
    Admin Admin user for API calls. SERVICES-LEVEL3
    SuspendedStatus

    Comma-separated list of system status names representing suspended time-off requests.

    		 Suspended (Request Status)
    SubmittedStatus Comma-separated list of system status names representing submitted time-off requests. Submitted (Request Status)
    ApprovedStatus Comma-separated list of system status names representing approved time-off requests. Approved (Request Status)
    PendingStatus Comma-separated list of system status names representing pending time-off requests. Pending (Request Status)
    RefusedORCancelledStatus Comma-separated list of system status names representing refused or canceled time-off requests. Refused, Cancelled, Cancel Submitted (Request Status)
    PendingStatusForAPIRequest Comma-separated list of system status names representing pending states contained in API requests. Pending (Request Status)
    CancelStatusForAPIRequest Comma-separated list of system status names representing canceled states contained in API requests. Cancelled (Request Status)
    TimeOffRequestIDActivitiVariableKey

    Workflow Activit variable used to retrieve the time-off request ID.

    		 RequestID (Time-off request ID)
    RequestSubtypeActivitiVariableKey Request subtype variable. RequestSubtype
    HRSDEmployeeIDInternalVariable Common ID that connects UKG Pro WFM and HRSD. PRO_EEID

    DocumentAttachment_v2_Parameters — Used to dynamically retrieve parameters.

    Document Attachment — Parameters decision table structure
    Parameter name Description Additional information
    HRSDApplicationID HRSD Application ID.

    Values for these parameters are provided by the HRSD and Cloud Identity teams during deployment.

    • HRSD team sets up SSO on the document manager side.

    • HRSD team provides the metadata file.

    • Share metadata with CloudIdentityEngineering@ukg.com.

    • Request SSO setup on the UKG Pro Workforce Management side.

    • Share metadata files between UKG Pro Workforce Management and HRSD Teams.
    HRSDClientID HRSD Client ID.
    HRSDApplicationSecret HRSD Application Secret.
    HRSDAPIBaseURL URL to make API call.
    HRSDDocumentBaseURL Base URL for Document.
    HRSDEmployeePortalURL HRSD Login URL.
    GenericNotificationName

    Document attachment notification. Defined in the system.

    Default = Document Attachment Notification

    		 User configurable.
    TimeOffCommentTypeName

    Comment for time-off request. Defined in system.

    Default = Document Details
    DocumentType

    Document type defined in HRSD.

    Default = Absence

    		  
    AdditionalDelay

    Additional delay in between API calls.

    Default = 2

    		 Internal parameters; do not change.

    DocumentAttachment_v2_ReviewerList — Used to retrieve the appropriate reviewer list when the request subtype is configured with approval setting.

    Document Attachment — Reviewer List decision table structure
    Parameter name Description
    Approval Setting Name of the approval setting associated with request subtype.
    Reviewer List Name of the reviewer list associated with the approval setting.

    DocumentAttachment_v2_Paycode — Provides granular control over paycodes that require document justification and whether requests remain suspended until the document is provided. Only paycodes for which documentation is required should be added to this table.

    Document Attachment — Paycode decision table structure
    Parameter name Description Default value
    Paycode Paycode name that requires justification. Sick
    Suspend Request

    Determines whether requests remain suspended until the document is provided.

    Case-sensitive supported values include:

    Yes

    No

    		Yes
    Note:

    • First (Single Pass) must be selected from Hit Policy when editing the decision table.

    DocumentAttachment_v2_Locale — Allows translation of business process messages and labels on the task form into different languages.

    Document Attachment — Locale decision table structure
    Parameter name Description
    Key Key for which localization is defined.
    Locale

    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 Form label or message shown as the result of a processing error.
    Note:

    • Localization of business process workflows remains optional, but is supported.

    • The decision table 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 decision table. Text within tags ("<>") must not be changed.

    • Names of the parameters in the decision table 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 decision table with the appropriate Locale Policy, and then add the localized values in the Message column.

    • The last row in the decision table must remain empty ("!=empty".)

    Sample Locale content
    Key Locale Message
    Error_Authentication != empty Client authentication failed.
    Error_EmptyReviewerList != empty Reviewer list is empty.
    Error_Form != empty Error encountered
    Error_GenericError != empty Error encountered. Please retry and if the error persists contact your Administrator.
    Error_InactiveReviewerList != empty Reviewer list is empty.
    Error_IncorrectURL != empty HRSD URL provided is not correct/Server Error.
    Error_InvalidReviewerInReviewerList != empty None of the reviewers present in reviewer list are valid for request status change.
    Error_InvalidReviewerListInDecisionTable != empty Invalid reviewer in decision table.
    Error_NoAttendanceLicense != empty User does not have required license to view attendance admin.
    Error_NoLeaveLicense != empty User does not have required license to view leave admin.
    Error_NoReviewerListFound != empty No reviewer list present in decision table for given approval setting.
    Error_WrongClientID != empty Please provide a valid Client ID.
    Error_WrongComment != empty Comment not found.
    Error_WrongDocTag != empty Tag Definition not found.
    Error_WrongNotification != empty Notification not found.
    Label_Action != empty Action
    Label_CancelButton != empty Cancel
    Label_CancelRadio != empty Cancel this request
    Label_ConnectRadio != empty Connect an existing document
    Label_Date != empty Date
    Label_DateFormat != empty

    MM/dd/yyyy

    Note:

    Acceptable values include:

    dd-MM-yyyy

    dd/MM/yyyy

    MM-dd-yyyy

    MM/dd/yyyy

    yyyy-MM-dd

    yyyy/MM/dd

    Label_DocFound != empty Connect an existing document. The following document(s) were uploaded. Please select and complete your task when done.
    Label_ErrorSubmitButton != empty Ok
    Label_Form1Button != empty Next
    Label_Form2ConnectExistingButton != empty Next
    Label_Form2UploadDocButton != empty Complete task
    Label_Form3Button != empty Submit
    Label_Paycode != empty Paycode
    Label_PendingScheduleTagName != empty Pending Schedule Tag
    Label_ProvidedScheduleTagName != empty Provided Schedule Tag
    Label_RadioForm2OptionYes != empty Go back to previous form
    Label_RadioForm3OptionYes != empty Go back to previous form
    Label_ReqDetails != empty Request Details
    Label_SelectDate != empty When was the document uploaded?
    Label_UploadRadio != empty Upload a new document.
    Message_AlreadyCancelForm != empty Your request is already cancelled.
    Message_ApproveCancelForm != empty Approved requests cannot be cancelled. Please submit a cancel request.
    Message_CancelForm != empty Your request has been cancelled.
    Message_ConnectLoopDisplayText != empty No documents were found on the selected date.
    Message_NoSelectionOnForm2 != empty Please make a selection
    Message_NoSelectionOnForm3 != empty Please make a selection
    Message_UploadLoopDisplayText != empty No documents were found. Please upload a new document.

    Deploy Process Model

    Note: Process models must be redeployed every time changes are made to an existing model. Re-deployment is not required for decision table changes.

    Follow these steps to deploy the process model. For detailed information, see the online help topic Deploy Business Process Models.

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

    2. Select the DocumentAttachment_v2 model and click tap Deploy .
    3. On the Business Process page, configure the required parameters and deployment dates.
    • (Optional) In Description, enter Document Attachment.
    • In Display Name, enter DocumentAttachment_v2.
    • In Start Effective, select the effective start date.
    • In End Effective, select Forever to make the Business Process available indefinitely.
    • In Status, select Active.
    • In Action List, select Hide.
    • In Tile A container that provides navigation or action from its summary view. List, select Hide.
    • In GoTo List, select Hide.
    • From Template Categories, select External Actions and Validation.
    1. Click Tap Save and then Return.
    API details — UKG Pro Workforce Management
    API name Type Resource path Description
    Retrieve Time Off Request by ID as Manager GET /v1/scheduling/timeoff/{timeOffRequestId} Returns a time-off request by ID.
    Retrieve User Preferences for Current User GET /v1/commons/user_preferences/locale_policy?userCurrent=true Returns user preferences for the current user.
    Retrieve Schedule POST /v1/scheduling/schedule/multi_read Validates whether or not the schedule has been updated.
    Delete Schedule Tags POST /v1/scheduling/schedule/schedule_tags/multi_delete Deletes one or more schedule tags according to the specified parameters.
    Update Paycode Edits POST /v1/scheduling/schedule/pay_code_edits/multi_update Updates one or more paycode edits.
    Create Schedule Tags POST /v1/scheduling/schedule/schedule_tags/multi_create Creates one or more schedule tags according to the IDs provided.
    Update Time Off Request as Manager POST /v1/scheduling/timeoff/apply_update Updates the state of a time-off request by transitioning a time-off request from one state to another.
    Update Schedule Tags POST /v1/scheduling/schedule/schedule_tags/multi_update Updates one or more schedule tags according to the IDs provided.
    Retrieve Persons POST /v1/commons/persons/extensions/multi_read Returns multiple person records based on search criteria.
    Retrieve Tag Definitions with Criterion POST /v1/scheduling/setup/tag_definitions/multi_read Returns tag definitions by references, by assignment context, or returns all tag definitions.
    Update Employee Time Off Request POST /v1/scheduling/employee_timeoff/apply_update Updates the state of a time-off request by transitioning a time-off request from one state to another.
    Retrieve Request Subtype by Name GET /v1/scheduling/setup/request_subtypes?name= {name} Returns a request subtype by name.
    Retrieve Reviewer List by Criteria GET /v1/commons/reviewer_lists?name={name} The associated Access Control Point is REQUEST_REVIEWERS.
    Retrieve Leave Admin by Person Number GET /v1/commons/persons/leave_admin?person_number={person_number} Returns the administrator assigned to a Leave employee by person number.
    Retrieve Attendance Admin by Person Number GET /v1/commons/persons/attendance_admin?person_number={person_number} Returns the administrator assigned to an Attendance employee by person ID.
    API details — HR Service Delivery
    API name Type Resource path Description
    Get OAuth Access Token POST {HRSD_API_Host}/api/v2/client/tokens Returns HRSD authentication token.
    List and search employees GET {HRSD_API_HOST}/api/v2/client/employees?external _id={wfdEmployeePersonNumber} Returns employee details from HRSD.
    List and search employee documents GET {HRSD_API_HOST}/api/v2/ client/employee_documents?document_type_id=absence&employee_id={HRSDEmployeeID}&created_at_since={documentDate}&created_at_until={documentDate} Returns employee documents.