Schedule Template Upload

Create the schedule template in a spreadsheet.

1. Open Microsoft Excel™.
2. Create a new spreadsheet file in .xlsx format.
3. Name the file for the relevant work location. Example: Emergency Room.
4. 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.

     ​
5. Enter shift templates in the cells to build the schedule template.

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

6. Click Tap Save.

Source file

• File Name: ScheduleTemplateUpload_yyyyMMddHHmmss.csv.

Note: If you do not include the .csv extension, the integration adds it.

• Format: Comma-delimited
• Frequency: On-demand or scheduled
• Header Row: Yes, 1 row
• Footer Row: No
• SFTP Folder: /Inbound

Source file layout

Field	Description	Required
Employee ID	String Maximum length: 15 characters	Required
Employee Name	String	Not required
ORG JOB	String	Required
ROLL OUT	String	Required
Shift Template	String	Required

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

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

1. Configure Access to Integrations.
2. Configure 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.

3. Make sure that the schedule template was created.

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

Deploy the Schedule Template Upload 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 Schedule Template Upload Extension Release integration.

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

Configure the Schedule Template Upload 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 . It can take several seconds before the button becomes active.

3. Scroll to and select the integration pack: Schedule Template Upload > ScheduleTemplateUpload_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
   ScheduleTemplateUpload_iPack_v3_APIGatewayServer	Required	To change the default API gateway server: Clear Use Default. Enter the URL to the server. Example: <tenantURL>/api Use the format <tenantURL>/api.
   ScheduleTemplateUpload_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: For each field, clear Use Default. 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.
   ScheduleTemplateUpload_iPack_v3_Locale_CRT	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 ScheduleTemplateUpload_iPack_v3 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

Property	Required	Actions
ScheduleTemplateUpload_iPack_v3_CRTConfig	Required	For ScheduleTemplateUpload_iPack_v3_Locale_CRT: Clear Use Default. Enter 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.

1. Select Cross Reference.
2. From the Cross Reference dropdown list, select the ScheduleTemplateUpload_iPack_v3_Locale_CRT table.
3. Select Override, which allows you to:

• Download the table when you run the integration.
• Edit the table cells in Extensions.

4. When you finish, click tap OK.

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

Schedule Template Upload — Locale CRT structure

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 (*) 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. Example: Hyperfind or Location not provided.
Description	The description that is shown in Additional Details.

Sample Locale CRT content

Parameter name	Message
Error_NoLocation	Location must be provided.
Error_InvalidAction	Action must be either Roll out or Retract.
Error_InvalidDeleteValue	DeleteFileAfterProcessing must be either true or false.
Error_NoFileName	FileName must be provided.
Error_InvalidFileFormat	File format must be csv.
Error_isEmptyBeginRollOutDate	BeginRollout date must be provided.
Error_InvalidBeginRollOutDateFormat	Value in BeginRollout date is not in correct format, yyyy-MM-dd.
Error_isEmptyEndRollOutDate	EndRollout date must be provided.
Error_InvalidEndRollOutDateFormat	Value in EndRollout date is not in correct format, yyyy-MM-dd.
Error_InvalidEndRollOutDate	EndRollout date must be after BeginRollout date.
Error_isEmptyTemplateStartDay	TemplateStartDay must be provided.
Error_InvalidTemplateStartDayValue	TemplateStartDay value type must be integer.
Error_DefinedTemplateStartDayValue	TemplateStartDay value must be between 1-91.
Error_InvalidLocationType	Select Location instead of Hyperfind.
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_FileNotFound	<FileName> not found in SFTP directory.
Message_ShiftTemplateNotRetrieval	Shift Templates retrieval unsuccessful.
Message_UnsuccessResponseFromRST	Unsuccessful response code received from RetrieveShiftTemplates.
Message_IncorrectRequest	Incorrect Request Parameter or Invalid Request Body.
Message_UnsuccessResponseByLocationByID	Unsuccessful response code received from GetLocationByID.
Message_SFTPError	SFTP connection error encountered.
Message_UnsuccessfulPERetrieval	Person Extension retrieval unsuccessful.
Message_PEError	Internal Server Error of PersonExtension.
Message_SCUnsuccessful	Shift Creation unsuccessful.
Message_EmployeeNotFoundForRolled	Employee <EmployeeID> cannot be found. The Schedule Template cannot be rolled out for Employee ID:<EmployeeID> and Job:<Job>.
Message_EmployeeNotFoundForRetracted	Employee <EmployeeID> cannot be found. The Schedule Template cannot be retracted for Employee ID:<EmployeeID> and Job:<Job>.
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_NoRollOutForJob	Job:<Job> is not valid for the rolled-out Location. The Scheduled Template cannot be rolled out 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_UnsuccessfulOpenShiftCreation	Open shifts creation unsuccessful.
Message_UnsuccessfulResponseCOS	Unsuccessful response code received from CreateOpenShift.
Message_NoSchForLocation	Schedule for location not found.
Message_UnsuccessfulResponseROS	Unsuccessful response code received from RetrieveOpenShifts.
Message_NoOpenShifts	Open Shifts:<ShiftName> is not available for Job:<Job> and Date:<Date>
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_UnsuccessResponseFromRetractST	Unsuccessful response code received from RetractEmployeeShift.
Message_UnsuccessfulRetractOpenShiftCreation	Unsuccessful response code received from RetractOpenShift.
Message_Rollout	OrgJob is not valid for the rolled-out Location.
Message_NoRetractOutForJob	Job: <Job> is not valid for the retracted Location. The Schedule Template cannot be retracted for Job: <Job>.
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_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_MultipleRetractTimesJob	Job:<Job> is found multiple times for the selected Location. The Scheduled Template cannot be retracted for Job:<Job>. Update the 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_Multiple	Job is found multiple times for the selected Location.
Message_NoEmployee	Employee cannot be found.
Message_LocaleTitle	Locale Policy API Status Code:
Message_SourceFile	Source File <FileName> not found in SFTP Directory.
Message_Shiftunavailable	Shift Id is not available.
Message_HeaderErrorFile	Header format is incorrect. Header contains blank columns.
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_TemplateStartDay	Template Start Day value is exceeds the Template Size:
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_FileError	Source file "<FileName>“ <FileErrorMessage>
Message_ShiftTemplate	Shift Template not found.
Message_ErrorKeyShift	Open Shift
Message_ErrorKeyEmployee	Employee ID
Message_ErrorKeyJob	Org Job

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.

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

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.
6. Do not select Allow Minute Interval.
7. Integration template and parameters
   1. In Integration Template, select ScheduleTemplateUpload_iPack_v3.
   2. Click Tap Assign .
   3. (Optional) 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 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 = \Inbound Caution: Make sure that this directory is configured on the SFTP server.	Text	No
FileName	The name of the file which user is uploading. Caution: Make sure that only one file with this filename is on the SFTP server at a time. Otherwise, the data can become corrupted. 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 = 1	Number	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

8. 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. 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 ScheduleTemplateUpload_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 default name ends with a date and time stamp.
2. 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.

3. Select the following:

   • Run Integration: If this is the first time this integration is being run.
   • Re-Run: If this integration has been run before, and the status is not In-Progress, you can run the integration again without entering the parameter values again. Click Tap Yes to continue, or No to not run the integration and to return to the parameter settings.

4. Wait for the confirmation that the integration completed or failed. Close the panel.
5. Click Tap Refresh . 
6. To see details, select the integration run. Select Run Summary.

Check the results

Status indicators

•  In-Progress: The run of this integration has not yet completed.
•  Completed: The integration ran successfully without errors.
•  Scheduled: This integration is scheduled to run later or repeatedly.
• (Grayed out) Scheduled but Deleted: This integration is scheduled to run, but the integration template has been deleted. When it runs, it will generate an error. To prevent this error, delete the scheduled integration run.
•  Completed with Errors: The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
•  Failed: The integration run has errors or could not run.
• To troubleshoot and resolve errors, do the following:

  Check the Run Summary for details.

  • To troubleshoot all types of errors, or if the Run Summary shows a large number of errors, click tap Go to Additional Details (if available), or click tap the Source File to open and examine the input source file.
  • (Only for import integrations) To troubleshoot and resubmit integrations that have transactional or data errors, click tap Go to Transaction Assistant.

To check the results in more detail, do the following:

1. Click Tap the tile for the integration run.
2. Click Tap Run Summary to see the results of the integration run.

   Example Run Summary details

   Note: The available details vary by integration and configuration.

   • Integration Run Name: Name of this run of the integration.
   • Process Name: Name of any integration set that includes this integration.
   • Integration Name: Name of the installed integration.
   • Integration Reference ID: Unique identifier for this integration run (to help in troubleshooting errors).
   • User: The person or user account that ran the integration.
   • Integration Type: Import, Export, or None
   • Start Date: Date and time when the integration run started.
   • End Date: Date and time when the integration run finished.
   • Status: In-Progress, Completed, Completed with Errors, or Failed.
   • Records Processed: Number of records that were processed.
   • Records Created: Number of records that were created.
   • Errors: Number of records that failed.
   • Source Files, Output File, and Error Files: For file-based import integrations, use Manage SFTP to access the source and output files on the inbound (source) and outbound (destination) SFTP folders. See the Manage SFTP topic.
3. Log in to the destination system and make sure that the data has been correctly updated.

Note: You can schedule integrations and integration sets to run once later or at a recurring frequency. See the topic.

API details

API name	Resource path	Type	Description
Retrieve Shift Templates	/v1/scheduling/shift_templates/multi_read	POST	Retrieve details about the shift templates.
Delete Shifts	/v1/scheduling/schedule/shifts/multi_delete	POST	Delete assigned and open shifts by shift ID.
Retrieve Schedule	/v1/scheduling/schedule/multi_read	POST	Retrieve employees and open shifts from the schedule.
Create Shifts from Patterns	/v1/scheduling/schedule/shifts/apply_create	POST	Create assigned and open shifts as defined by patterns.
Retrieve Locations	/v1/commons/locations/multi_read	POST	Retrieve the location name and path by the location ID.
Retrieve Persons	/v1/commons/persons/extensions/multi_read	POST	Retrieve a person’s employment status and primary job.
Retrieve User Preferences for Current User	/v1/commons/user_preferences/locale_policy?userCurrent=true	GET	Return user preferences for the current user or tenant.
Retrieve All Integration Execution	/v1/platform/integration_executions/	POST	Provide additional details about an integration run.
Update Integration Execution Details	/v1/platform/integrations/update_status	POST	Provide the summary of an integration run.
Retrieve Location by ID	/v1/commons/locations/{LocationID}	GET	Retrieve the location name and path by the location ID.