Schedule Template Upload
Schedule templates assign shifts and jobs in a recurring pattern that makes a reusable, stable schedule that covers several weeks. The Schedule Template Upload integration rolls out or retracts a schedule template for selected employees at a location and for a time period. This integration imports the schedule template from a flat file (CSV).
To upload schedule templates directly to UKG Pro Workforce Management, do the following:
- Create the schedule template in a flat file.
- Run the Schedule Template Import integration to import the schedule template from the spreadsheet.
- Check the schedule template in the Scheduler.
Create the schedule template file
Create the schedule template in a spreadsheet.
- Open Microsoft Excel™.
- Create a new spreadsheet file in
XLSXformat. - Name the file for the relevant work location. Example: Emergency Room.
- Include the following columns:Caution: If any column header is missing, the integration runs fail.
- EMPLOYEE ID: Unique identifier for each employee:
When specified, the employee is assigned the specified shift jobs.
When not specified, the shifts in that row automatically generate open shifts.
- EMPLOYEE NAME: Enter the employee’s name for ease of identification even though this field is informational only and not used during the rollout.
- ORG JOB: Enter only jobs that are active at the location. Validation for active jobs is done during rollout.
- ROLL OUT: Set for granular control over which records to roll out. Enter either of the following:
Yes: Roll out the record.
No: Do not roll out the record.
Example: Enter No, if a rollout does not require all of the open shifts that are in the schedule template. These records remain in the template but are not rolled out.
- Day 1 to Day xx: Create a column for each day in the period.
Maximum = 91 days (13 weeks).
Example: For a 2-week pay period, create columns for Day 1—14.
- EMPLOYEE ID: Unique identifier for each employee:
- Enter shift templates in the cells to build the schedule template.
Example Schedule Template
Location: Nursing
EMPLOYEE ID
EMPLOYEE NAME
ORG JOB
ROLL OUT
DAY 1
DAY 2
DAY 4
DAY 5
DAY 6
DAY 7
007-008
Banner Bruce
Nursing/Med Surg 1/Nurse Mgr
Yes
HC-D8
HC-D8
HC-D8
HC-D8
HC-D8
HC-D8
001-004
Gibson Emmy
Nursing/Med Surg 1/CNA
Yes
HC-D8
HC-D8
HC-N8
007-007
Stark Tony
Nursing/Med Surg 1/Nurse Mgr
No
HC-N8
HC-N8
HC-N8
Nursing/Med Surg 2/Charge RN
Yes
HC-N8
HC-N8
HC-N8
HC-N8
HC-N8
Note: Shifts in the template that are not assigned to employees generate open shifts.- Enter a shift template for each day.
- If a day has no shift template, that day is not scheduled.
- Manual shifts are not supported; you can use only shift templates. Examples: Early, Day, Night, Late.
- If any rows are blank, the integration run has errors.
- Click Tap Save.
Source file
- File Name:
ScheduleTemplateUpload_yyyyMMddHHmmss.csvNote: If you do not include theCSVextension, the integration adds it. - Format: Comma-delimited
- Frequency: On-demand or scheduled
- Header Row: Yes, 1 row
- Footer Row: No
- SFTP Folder:
/Inbound
|
Field |
Description |
Required |
|---|---|---|
|
Employee ID |
String
|
Required |
|
Employee Name |
String |
Not required |
|
ORG JOB |
String |
Required |
|
ROLL OUT |
String |
Required |
|
Shift Template |
String |
Required |
Considerations
-
Employees, shift templates, and jobs contained in the source (CSV) file must exist in the application before running the Schedule Template Upload integration.
-
Transfer locations specified in the shift template take precedence over the transfer locations specified in the source (CSV) file.
Boomi extension setup
- Get the URL, User, and Password for the APIGatewayServer.
- Install and attach the iPack.Note: For more information, see the Deploy Integration Packs to your Atom topic.
- Configure the Schedule Template Upload Extension integration settings:
- Configure connection settingsCaution: 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.
- Configure process properties:
Configure the Schedule Template Upload integration
After the integration is deployed, complete the following configurations before you utilize this integration.
Application setup
Before you configure this integration, you must do the following:
- Configure Access to Integrations.
- Complete the following:
- Integration List Parameters: Configure an integration list parameter. Retract and rollout parameter values must be selected during configuration.
See the Configure Integration List Parameters topic.
- Integration List Parameters: Configure an integration list parameter. Retract and rollout parameter values must be selected during configuration.
- Make sure that the schedule template was created.
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.
To make a cross-reference table available for integration processes, populate the table with data.
- 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.
-
Values entered in the CRTs are case-sensitive, and must match values configured in the application, where appropriate. Comma entries are not supported.
-
Wildcards configured in the CRTs must be defined at the bottom of the table.
ScheduleTemplateUpload_iPack_v3_Locale_CRT: Allows translation of messages and labels into different languages.
|
Column header |
Description |
|---|---|
|
Parameter Name |
Parameters defined in ScheduleTemplateUpload_iPack_v3_Locale_CRT process property. |
|
Locale Policy |
The name of the locale policy. You can use an asterisk ( |
|
Message |
Message shown in Additional Details, or value of the label defined in the Run Summary section. Example: |
|
Description |
The description that is shown in Additional Details. |
- 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").
|
Parameter name |
Message |
|---|---|
| Error_DefinedTemplateStartDayValue | TemplateStartDay value must be between 1-91. |
| Error_InternalPartialFailure | value |
|
Error_InvalidAction |
Action must be either Roll out or Retract. |
| Error_InvalidBeginRollOutDateFormat | Value in BeginRollout date is not in correct format, yyyy-MM-dd. |
|
Error_InvalidDeleteValue |
DeleteFileAfterProcessing must be either true or false. |
| Error_InvalidEndRollOutDate | EndRollout date must be after BeginRollout date. |
| Error_InvalidEndRollOutDateFormat | Value in EndRollout date is not in correct format, yyyy-MM-dd. |
| Error_InvalidFileFormat | File format must be csv. |
| Error_InvalidLocationType | Select Location instead of Hyperfind. |
| Error_InvalidTemplateStartDayValue | TemplateStartDay value type must be integer. |
| Error_isEmptyBeginRollOutDate | BeginRollout date must be provided. |
| Error_isEmptyEndRollOutDate | EndRollout date must be provided. |
| Error_isEmptyTemplateStartDay | TemplateStartDay must be provided. |
|
Error_NoFileName |
FileName must be provided. |
|
Error_NoLocation |
Location must be provided. |
|
Error_Parentlocation |
Multiple parent locations selected. Choose a single parent location for successful execution. |
|
Label_AdditionalDetails |
Process completed with transaction errors. Additional details may be accessible using the button below. |
|
Label_FailTransaction |
Integration failed and an unexpected error occurred while executing the integration. |
|
Label_IntegrationStatus_SuccessMessage |
Integration completed without errors. |
|
Label_IntegrationStatus_SuccessWithDisqualify |
Integration completed without errors, but certain records were disqualified. Click additional details for more information. |
|
Label_IntegrationExecutionId |
Integration Execution ID |
|
Label_IntegrationTypeName |
Integration Type |
|
Label_IntegrationTypeValue |
Import |
|
Label_ProcessedSourceRecords |
Processed Source Records |
|
Label_RollOutEmployeeShiftSuccess |
Rolled Out Employee Shifts |
|
Label_FailedTransactions |
Failed Transactions |
|
Label_DisqualifiedTransactions |
Disqualified Transactions |
|
Label_RollOutOpenShiftSuccess |
Rolled Out Open Shifts |
|
Label_RetractEmployeeShiftSuccess |
Retracted Employee Shifts |
|
Label_RetractOpenShiftSuccess |
Retracted Open Shifts |
|
Label_ProcessCallback |
Unsuccessful response code received from Process Callback. |
|
Label_Integration |
Integration started |
|
Label_APIUnsucess |
Unsuccessful response code received from API when submitting custom integration details. |
| Message_EmployeeNotFoundForRetracted | Employee <EmployeeID> cannot be found. The Schedule Template cannot be retracted for Employee ID:<EmployeeID> and Job:<Job>. |
| Message_EmployeeNotFoundForRolled | Employee <EmployeeID> cannot be found. The Schedule Template cannot be rolled out for Employee ID:<EmployeeID> and Job:<Job>. |
| Message_ErrorKeyEmployee | Employee ID |
| Message_ErrorKeyJob | Org Job |
| Message_ErrorKeyShift | Open Shift |
| Message_FileError | Source file "<FileName>" <FileErrorMessage> |
| Message_FileRowError | File format is incorrect. File contains blank rows or missing Org Job. Source file must contain continuous rows and each row must contain an Org Job. |
|
Message_FileNotFound |
<FileName> not found in SFTP directory. |
| Message_HeaderErrorFile | Header format is incorrect. Header contains blank columns. |
| Message_IncorrectRequest | Incorrect Request Parameter or Invalid Request Body. |
| Message_LocaleTitle | Locale Policy API Status Code: |
| Message_Multiple | Job is found multiple times for the selected Location. |
| Message_MultipleRetractedTimesJobEmployeeID | Job:<Job> is found multiple times for the selected Location. The Scheduled Template cannot be retracted for Employee ID:<Employee ID>and Job:<Job>. Update the Location. |
| Message_MultipleRolloutTimesJob | Job:<Job> is found multiple times for the selected Location. The Scheduled Template cannot be rolled out for Job:<Job>. Update the Location. |
| Message_MultipleRolloutTimesJobEmployeeID | Job:<Job> is found multiple times for the selected Location. The Scheduled Template cannot be rolled out for Employee ID:<EmployeeID>and Job:<Job>.Please refine the Location. |
| Message_NoEmployee | Employee cannot be found. |
| Message_NoOpenShifts | Open Shifts:<ShiftName> is not available for Job:<Job> and Date:<Date> |
| Message_NoRetractForEmployeeID | Job:<Job> not valid for the retract Location. The Scheduled Template cannot be retracted for Employee ID:<Employee ID> and Job:<Job>. |
| Message_NoRetractOutForJob | Job: <Job> is not valid for the retracted Location. The Schedule Template cannot be retracted for Job: <Job>. |
| Message_NoRollOutForEmployeeID | Job:<Job> not valid for the rolled-out Location. The Scheduled Template cannot be rolled out for Employee ID:<EmployeeID> and Job:<Job>. |
| Message_NoRollOutForJob | Job:<Job> is not valid for the rolled-out Location. The Scheduled Template cannot be rolled out for job:<Job> |
| Message_NoSchForLocation | Schedule for location not found. |
| Message_NoShiftavailable | Shift:<ShiftName> is not available for Employee Id:<EmployeeID> Job:<Job> and Date:<Date> |
| Message_OSJob | OrgJob is not valid for the rolled-out Location. |
| Message_PEError | Internal Server Error of PersonExtension. |
| Message_Rollout | OrgJob is not valid for the rolled-out Location. |
| Message_SCUnsuccessful | Shift Creation unsuccessful. |
| Message_SFTPError | SFTP connection error encountered. |
| Messgae_ShiftInvalidEmployee | Shift Template: <ShiftName> not found. The Schedule Template cannot be rolled out for Employee ID: <EmployeeID> and Job :<Job>. |
| Message_ShiftInvalidJob | Shift Template: <ShiftName> not found. The Schedule Template cannot be rolled out for the Job: <Job>. |
| Message_ShiftInvalidRetractedEmployee | Shift Template: <ShiftName> not found. The Schedule Template cannot be retracted for Employee ID: <EmployeeID> and Job: <Job>. |
| Message_ShiftInvalidRetractedJob | Shift Template: <ShiftName> not found. The Schedule Template cannot be retracted for the Job: <Job>. |
| Message_ShiftTemplate | Shift Template not found. |
| Message_ShiftTemplateNotRetrieval | Shift Templates retrieval unsuccessful. |
| Message_Shiftunavailable | Shift Id is not available. |
| Message_SourceFile | Source File <FileName> not found in SFTP Directory. |
| Message_TemplateStartDay | Template Start Day value is exceeds the Template Size: |
| Message_UnsuccessfulOpenShiftCreation | Open shifts creation unsuccessful. |
| Message_UnsuccessfulPERetrieval | Person Extension retrieval unsuccessful. |
| Message_UnsuccessfulResponseCOS | Unsuccessful response code received from CreateOpenShift. |
|
Message_UnsuccessResponseByLocationByID |
Unsuccessful response code received from GetLocationByID. |
| Message_UnsuccessResponseFromRST | Unsuccessful response code received from RetrieveShiftTemplates. |
|
Message_UnsuccessfulResponseROS |
Unsuccessful response code received from RetrieveOpenShifts. |
|
Message_UnsuccessResponseFromRetractST |
Unsuccessful response code received from RetractEmployeeShift. |
|
Message_UnsuccessfulRetractOpenShiftCreation |
Unsuccessful response code received from RetractOpenShift. |
Install the Schedule Template Upload integration
After the integrations are deployed and the connection settings and process properties are configured, install the integrations to make them available for running or scheduling.
- An integration template is the configured integration that you deploy to an Atom and then install to make available for running or scheduling.
- An installed integration is a single instance of an integration that is based on an integration template. When you install an integration, you can define parameters or set parameters to be defined when the integration is run.
- Select .
- Click Tap .
- In Integration Name, enter a unique name, such as ScheduleTemplateUpload_iPack_v3.
- (Optional) Enter a Description.
Note: Do not select API Integration.
- In File Access, select None to not select a connection.
- (Optional) If the person who runs the integration doesn't have full access to integrations, select Execute Integration with System Account. This allows the integration access to all APIs in the FAP, and the relevant permissions and data, regardless of the FAP and GDAP of the person who runs the integration.
-
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
-
Email Notifications
(Optional)
- Select Yes to send email and control center notifications for integration runs.
- Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces:
In Progress — The integration run started and has not finished.
Completed — The integration ran successfully without errors.
Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
Completed with Errors — The integration run has errors or could not run.
- In Skip Configuration, select None(default) to allow multiple integrations to run at the same time or with the same data without restrictions.
Note: Do not select Allow Minute Interval.
- Integration template and parameters
- In Integration Template, select ScheduleTemplateUpload_iPack_v3.
- Click Tap .
- (Optional) In Integration Parameters, you can override default settings. Click Tap .
- Complete the configuration for each integration control parameter value.
- Click Tap Save.
- Repeat this step for each integration parameter that supports the Schedule Template Upload process.
Integration parameters
Parameter name
Description
Parameter type
User prompt
SourceDirectory
The directory path on the SFTP server where the integration process reads the file.
Default =
\InboundCaution: Make sure that this directory is configured on the SFTP server.Caution:Do not change the name of the folder from
Inbound. Additional or differently named folders are not supported by .Text
No
FileName
The name of the file which user is uploading.
Caution: Import integrations accept only UTF-8 encoded input files.Text
Yes
BeginRollout
The start date of the rollout of the schedule template.
Default format =
yyyy-MM-dd.Date
Yes
TemplateStartDay
To roll out the template starting on a different day from the first day of the schedule template, enter the number of days to offset.
Supported values =
1—91(13 weeks)Default =
1Number
Yes
EndRollout
The end date of the rollout of the schedule template.
The date must be after the BeginRollout date.
Default format =
yyyy-MM-dd.Date
Yes
Location
Select the location query that identifies the parent location of the schedule template rollout.
Default = 1
Note:- Blank values and Hyperfinds are not supported.
- The default is set = 1, but it must be reconfigured to meet the needs of the organization.
- The location query must contain only one parent location.
- Multiple parent locations are NOT supported.
Hyperfind
Yes
Action
The action that the integration performs.
Supported values:
-
Roll Out: Export and roll out the schedule template to the Scheduler. -
Retract: Cancel a previously rolled-out template and clear the schedule.
Dropdown
Yes
DeleteFileAfterProcessing
Delete the source file after processing.
Supported values:
-
false(default): Do not delete the source file. -
true: Delete the sources file.
Boolean
Yes
- Ensure that the generic data access profiles (GDAP) allow access to the Schedule Upload Template integration for the people who need to run the installed integrations.
Run and test the Schedule Template Upload integrations
Run integrations to test that the configuration is set up correctly.
- Run the integration
- Select the integration:
- Select .
- Click Tap .
- Select the ScheduleTemplateUpload_iPack_v3 integration from the list. Click Tap Select.
- (Optional) Enter a unique Integration Run Name to make it easier to identify the run of the integration. Otherwise, the default name ends with a date and time stamp.
- Set parameters as follows:
- FileName: Enter the name of the flat file to import.
- BeginRollout: Select the date to start the rollout.
- EndRollout: Select the date to end the rollout.
- TemplateStartDay: If you need to roll out the template starting on a different day from the first day of the schedule template, enter a number from 1— 91 days (13 weeks) to offset the rollout.
- Location: You can select a different location query.
- Action: Select one of the following:
- Roll Out: Export and roll out the schedule template to the Scheduler.
- Retract: Cancel a previously rolled-out template and clear the schedule.
- Delete File After Processing: Select whether to delete the source file after the integration runs successfully.
- 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.
- Wait for the confirmation that the integration completed or failed. Close the panel.
- Click Tap .
- To see details, select the integration run. Select Run Summary.
- Select the integration:
- Check the results
Status indicators
-
In-Progress: The run of this integration has not yet completed. -
Completed: The integration ran successfully without errors. -
Scheduled: This integration is scheduled to run later or repeatedly. - (Grayed out) Scheduled but Deleted: This integration is scheduled to run, but the integration template has been deleted. When it runs, it will generate an error. To prevent this error, delete the scheduled integration run.
-
Completed with Errors: The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops. -
Failed: The integration run has errors or could not run. - To troubleshoot and resolve errors, do the following:
Check the Run Summary for details.
- To troubleshoot all types of errors, or if the Run Summary shows a large number of errors, click tap Go to Additional Details (if available), or click tap the Source File to open and examine the input source file.
- (Only for import integrations) To troubleshoot and resubmit integrations that have transactional or data errors, click tap Go to Transaction Assistant.
To check the results in more detail, do the following:
- Click Tap the tile for the integration run.
- 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.
- Log in to the destination system and make sure that the data has been correctly updated.
Note: You can schedule integrations and integration sets to run once later or at a recurring frequency. See the Schedule Integrations topic. -
APIs
|
API name |
Resource path |
Type |
Description |
|---|---|---|---|
|
/v1/scheduling/shift_templates/multi_read |
POST |
Retrieve details about the shift templates. | |
|
/v1/scheduling/schedule/shifts/multi_delete |
POST |
Delete assigned and open shifts by shift ID. | |
|
/v1/scheduling/schedule/multi_read |
POST |
Retrieve employees and open shifts from the schedule. | |
|
/v1/scheduling/schedule/shifts/apply_create |
POST |
Create assigned and open shifts as defined by patterns. | |
|
/v1/commons/locations/multi_read |
POST |
Retrieve the location name and path by the location ID. | |
|
/v1/commons/persons/extensions/multi_read |
POST |
Retrieve a person’s employment status and primary job. | |
|
/v1/commons/user_preferences/locale_policy?userCurrent=true |
GET |
Return user preferences for the current user or tenant. | |
|
/v1/platform/integration_executions/ |
POST |
Provide additional details about an integration run. | |
|
/v1/platform/integrations/update_status |
POST |
Provide the summary of an integration run. | |
|
/v1/commons/locations/{LocationID} |
GET |
Retrieve the location name and path by the location ID. |
Version history
|
Version |
Description |
|---|---|
|
1 |
Initial release. Provides a mechanism to upload and roll-out a schedule template for a location and time period. |
|
2 |
Enhanced to support:
|
|
iPack_v3 |
The Schedule Template Upload delivery is now by way of an iPack. |
|
The Schedule Template Upload integration failed with a script error that was caused when the source file contained records for employees who did not yet exist in the system. Partial success responses from the Person Extension API are now handled correctly. |
