Document Attachment

Note: This business process 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 (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 Document Attachment workflow process connects UKG Pro Workforce Management™ with the HR Service Delivery platform (HRSD). 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 Workforce Management™.

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

Because not every absence requires justification, only paycodes 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. The manager 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 Workforce Management™.

  • 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 Workforce Management™ retrieves the documents from HRDS 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, 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 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 manager. The employee receives notifications when the document attachment task is assigned and completed. The manager receives a notification when the document is provided. Notifications are sent to both the employee and manager 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.

    You must configure the following:

    Schedule tag configuration

    Schedule tags: Configure schedule tags to display justification document status in the Schedule Planner.

    See the Tag Definitions topic.

    1. Select Main Menu  > Administration > Application Setup > Scheduler Setup > Tag Definitions.

    2. Click Tap Create.

    3. Enter a Name, such as Document Pending or Document Provided.

    4. Select Schedule from the Tag Type list.

    5. Click Tap Save.

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

    Request subtype transition and request subtype configuration

    Request Subtype Transition: Configure the request subtype 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.

    1. Select Main Menu  > Administration > Application Setup > Employee Self Service > Request Subtype Transitions.

    2. Click Tap New.

    3. Enter a Name, such as Absence Request.

    4. (Optional) Enter a Description.

    5. In External Actions, select a From State and a To State, and then select the Document Attachment business process model for Pre-Processing.

    6. In Validation Actions, for each subtype transition, select a From State and a To State, and then select the Document Attachment business process model for Post-Processing.

    7. Click Tap Save.

    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. This configuration initiates the business process.

    1. Select Main Menu  > Administration > Application Setup > Employee Self Service > Request Subtype.

    2. Edit, or create a new Request Subtype for use in Document Attachment processing.

    3. In the Request Subtype Transition list, select the request subtype transition, such as Absence Request.

    4. Click Tap Save.

    Comment configuration

    Comment: Configure a comment that is added to the paycode upon absence request approval.

    See the Comments topic.

    1. Select Main Menu  > Administration > Application Setup > Common > Comments.

    2. Click Tap Create.

    3. Enter Comment Text, such as Document Details.

    4. Select Pay Codes and Requests from the Available Categories list.

    5. Click Tap Save.

    Workflow notification configuration

    Workflow Notification: Configure a workflow notification to send the justification document details to the approving manager and employee.

    See the Configure Notifications for Business Processes topic.

    1. Select Main Menu  > Administration > Application Setup > Event/Notification > Workflow Notifications.

    2. Click Tap New.

    3. In the Selection Notification Type box, select Generic notification and click tap Ok.

    4. Give the notification a Name, such as Document Attachment Notification.

    5. (Optional) Add a Description.

    6. Select the Recipient List will be supplied at runtime and send to employee checkboxes.

    7. Enter the Subject line, as appropriate.

    8. Enter a Long Message, such as:

    Pay Code: <Paycode>

    Date: <TimeDuration>

    Document Link: <DocumentLink>

    Control center fields:
    Field Label Value
    1 Document Provided <Document Name>
    2 Document ID <DocumentID>

    1. Select the Do not suppress duplicates checkbox.

    2. Click Tap Save.

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

    Message configuration

    Message in UKG Pro Workforce Management™: 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 in Control Center to provide a document for this request.
    timeoff.success.suspended.message Your time-off request has been suspended. You have been assigned a task in Control Center to provide a document for this request.

    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.

    Migrate the process model to the tenant

    Migrate the Document Attachment process model to the customer tenant using Setup Data Manager (SDM).

    1. Log in to the tenant to which you are migrating the process model.
    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.
    4. In the Source column, a message reads: Source: Import from <filename>.zip. Click 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 Publish with Comment or just Publish.

    6. Click 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 the appropriate row and click View Selected.

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

    Configure decision tables

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

    Decision tables are configurable based on customer requirement and can be changed accordingly. These tables are dynamic tables that can be modified without redeployment of the process model. Decision tables used in this process model include:

    • Document Attachment Leave 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 Parameters: Used to dynamically retrieve parameters.

    • Document Attachment Locale: Allows localization and customization of the labels on the task form.

    Configure the Document Attachment Leave Paycode decision table

    Edit the decision table: DocumentAttachment_DocumentLeave Paycode

    1. Go to Main Menu > Administration > Application Setup > Business Process Setup > Process Models.
    2. Select the DocumentAttachment_v1.1 process and click Edit.
    3. Click Tap Visual Editor for the process model to enter edit mode.
    4. Select the Decision Tables section.
    5. Click Tap on the decision table DocumentAttachment_DocumentAttachmentLeave Paycode. A new window displays multiple decision tables.
    6. Select DocumentAttachment_DocumentAttachmentLeave Paycode and click tap Open. Do not uncheck the selected decision table.

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

    8. Click Tap Save and close.
    DocumentAttachmentLeaveCodes - sample
    PayCode SuspendRequest(Yes/No)
    =="Bereavement Hours" "Yes"
    =="Casual Leave" "Yes"
    =="Doctor Visit" "Yes"
    =="Family Emergency" "No"
    =="Personal Leave" "Yes"
    =="Sickness" "No"
    Note:

    • All parameter values are case-sensitive, and paycodes must match the configured values in UKG Pro Workforce Management™.

    • Valid values for the SuspendRequest(Yes/No) parameter are Yes and No.

    • First (Single Pass) must be selected from Hit Policy.

    Configure the Document Attachment Parameters decision table

    Edit the decision table: DocumentAttachment_DocumentAttachmentParameters

    1. Go to Main Menu > Administration > Application Setup > Business Process Setup > Process Models.
    2. Select the DocumentAttachment_v1.1 process and click tap Edit.
    3. Click Tap Visual Editor for the process model to enter edit mode.
    4. Select the Decision Tables section.
    5. Click Tap on the decision table DocumentAttachment_DocumentAttachmentParameters. A new window displays multiple decision tables.
    6. Select DocumentAttachment_DocumentAttachmentParameters and click tap Open. Do not uncheck the selected decision table.

    7. Click Tap Decision Table Editor to update the rows in the table.

    8. Click Tap Save and close.

    Document Attachment Parameter descriptions
    Parameter name Parameter 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. User configurable.
    PendingScheduleTagName Schedule tag for pending document. Defined in the system.
    ProvidedScheduleTagName Schedule tag for provided document. Defined in the system.
    TimeOffCommentTypeName Comment for time-off request. Defined in system.
    DocumentPendingTagColour Color of the Pending tag.
    DocumentProvidedTagColour Color of the Provided tag.
    AdditionalDelay Additional delay in between API calls. Internal parameters; do not change.
    CallAsAdmin Administrative user for the API calls.
    Suspended Status

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

    		  
    Submitted Status Comma-separated list of system status names representing submitted time-off requests.  
    Approved Status Comma-separated list of system status names representing approved time-off requests.  
    Pending Status Comma-separated list of system status names representing pending time-off requests.  
    RefusedORCancelled Status Comma-separated list of system status names representing refused or canceled time-off requests.  
    PendingStatusForAPIRequest

    Comma-separated list of system status names representing pending states contained in API requests.

    		  
    CancelStatusForAPIRequest

    Comma-separated list of system status names representing canceled states contained in API requests.

    		  
    TimeOffRequestID Workflow activit variable used to retrieve the time-off request ID.  
    DocumentType Document type defined in HRSD.  

    Note:

    • Do not add or delete rows in the Parameters table.

    • Do not update values in the Parameter Name column.

    • All parameter values are case-sensitive and must match the configured values in UKG Pro Workforce Management™.

    • The workflow process ignores the tag color selected during tag creation. Instead, the process utilizes colors defined by the DocumentPendingTagColour and DocumentProvidedTagColour parameters.

    • Hexadecimal values must be entered in the DocumentPendingTagColour and DocumentProvidedTagColour rows. For example, the respective values for Yellow and Green are FAEE00 and 00FA04.

    • First (Single Pass) must be selected from Hit Policy.

    Configure the Document Attachment Locale decision table

    Edit the decision table: DocumentAttachment_DocumentAttachmentLocale

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

    2. Select the DocumentAttachment_v1.1 process and click tap Edit.

    3. Click Tap Visual Editor for the process to enter edit mode.

    4. Select the Decision Tables section.

    5. Click Tap on decision table DocumentAttachment_DocumentAttachmentLocale. A new window displays multiple decision tables.

    6. Select DocumentAttachment_DocumentAttachmentLocale and click Open. Do not uncheck the selected decision table.

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

    8. Click Tap Save and close.

    Document Attachment Locale table
      Key Locale Message
    1 _MessageReqDetails !="empty" "Request details:"
    2 _MessageUploadRadio !="empty" "Upload a new document."
    3 _MessageConnectRadio !="empty" "Connect an existing document."
    4 _MessageCancelRadio !="empty" "Cancel this request."
    5 _MessageDate !="empty" "Date"
    6 _MessagePaycode !="empty" "Pay Code"
    7 _MessageAction !="empty" "Action"
    8 _MessageDocFound !="empty" "The following documents were uploaded. Please select and complete your task when done."
    9 _MessageSelectDate !="empty" "When was the document uploaded?"
    10 _MessageConnectLoopDisplayText !="empty" "No documents were found on the selected date."
    11 _MessageGenericError !="empty" "Error encountered. Please retry and if the error persists contact your Administrator."
    12 _MessageWrongComment !="empty" "Comment not found."
    13 _MessageWrongDocTag !="empty" "Tag Definition not found:"
    14 _MessageAuthenticationError !="empty" "Client authentication failed."
    15 _MessageWrongClientID !="empty" "Provide a valid Client ID."
    16 _MessageWrongNotification !="empty" "Notification not found."
    17 _MessageIncorrectURL !="empty" "HRSD URL provided is not correct / Server error."
    18 _MessageErrorForm !="empty" "Error encountered."
    19 _MessageDateFormat !="empty" "Date format."
    20 _MessageApproveCancelForm !="empty" "Approved requests cannot be canceled. Please submit a cancel request.
    21 _MessageAlreadyCancelForm !="empty" "Your request is already canceled."
    22 _MessageCancelForm !="empty" "Your request has been canceled."
    23 _MessageUploadLoopDisplayText !="empty" "No documents were found. Please upload a new document."

    Note:

    • Values entered in the Locale decision table are case-sensitive.

    • Avoid using special characters in the table.

    • The Message value must be consistent with the Locale specified in the same row.

    • (Optional) Comments can be added to the Description column in the Locale decision table.

    • Acceptable values for the _MessageDateFormat row include:

      dd-MM-yyyy

      dd/MM/yyyy

      MM-dd-yyyy

      MM/dd/yyyy

      yyyy-MM-dd

      yyyy/MM/dd

    • First (Single Pass) must be selected from Hit Policy.

    • The !="empty" rows must always be the last row in the Locale decision table.

    • Do not edit or remove the !="empty" rows of the Locale decision table.

    • Names of the parameters in the "Key" column of the Locale decision table must be used as is. If any parameter value needs to be localized for a different Locale Policy, copy the "Key" with the “not empty” Locale Policy, add a new row to the table with the appropriate Locale Policy, and then add the localized values in the Value and Description decision table columns.

    • All parameters in the Locale decision table with "not empty" Locale values should be located at the bottom of the table; these are the default error messages.

    • Stencil fields, such as Submit, Next, and Cancel buttons cannot be dynamically translated into a non-English language. When a request form needs to display in a language other than English, a language-specific copy of the process must be deployed.

    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. From the Main Menu, go to Application Setup > Business Process Setup > Process Models.
    2. Select the process and click tap Deploy .
    3. On the Business Process page, configure the required parameters and deployment dates.
    4. Select External Actions and Validation from the Template Categories.
    5. Click Tap Save and then Return.
    API details — UKG Pro Workforce Management™
    API name API section Type Resource path Location
    Retrieve Time-off Details API/Employee Self- Service/Manager Time Off Requests/Retrieve Time Off Request by ID as Manager GET /v1/scheduling/timeoff/{timeOffRequestId} Get Time-off Request Status
    Retrieve Tenant Locale API/Common Resources II/Locale Settings/User Preferences/Retrieve User Preferences for Current User GET /v1/commons/user_prefer ences/locale_policy?userCurrent=true Locale API for Tenant Locale
    Retrieve Employee Schedule API/Scheduling/Manager Schedules/Retrieve Schedule POST /v1/scheduling/schedule/multi_read Schedule for TagID
    Delete Schedule Tags API/Scheduling/Schedule Tags/Delete Schedule Tags POST /v1/scheduling/schedule/schedule_tags/multi_delete Delete schedule tags
    Update Paycode Edits API/Scheduling/Paycode Edits for Scheduling/Update Paycode Edits POST /v1/scheduling/schedule/pay_code_edits/multi_update Update comment in Paycode
    Create Schedule Tags API/Scheduling/Schedule Tags/Create Schedule Tags POST /v1/scheduling/schedule/schedule_tags/multi_create Insert Schedule Tags
    Update Time Off Request as Manager API/Employee Self- Service/Manager Time Off Requests/Update Time Off Request as Manager POST /v1/scheduling/timeoff/apply_update Update Time-off Request Comment and Status
    Update Schedule Tags API/Scheduling/Schedule Tags/Update Schedule Tags POST /v1/scheduling/schedule/schedule_tags/multi_update Update Schedule Tag

     

    API details — HR Service Delivery
    API name API section (HRSD) Type Resource path Location
    Get OAuth Access Token Platform: OAuth — Tokens POST {HRSD_API_Host}/api/v2/client/tokens Get HRSD token
    List and search employees Platform: Employees GET {HRSD_API_HOST}/api/v2/client/employees?external _id={wfdEmployeePersonNumber} Get HRSD EMPID
    List and search employee documents Document Manager: 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} Fetch Doc from HRSD