Blueprint XML Import Field Descriptions

The Blueprint Import is used to create blueprint based events using the Blueprint Import XML format. Some organizations generate production schedules using a third party system, such as an Enterprise Resource Planning (ERP) system. The Blueprint Import XML file allows these organizations to import blueprints using a matching criteria to create blueprint based events on the Planning Board for the purpose of staffing.

>> IMPORTANT:

The import tool does not create setup items, such as Blueprint labels, external IDs, SKUs, product information - if they do not exist.
The Import Log is located on the Planning board.
Multiple blueprints can be applied to a single Unit, meaning the same Unit. Allow Blueprint overlap is set at the “Institution” or “Unit” level of the Organizational structure.
Import notification settings are located in Setup > System > Import Manager > Blueprint Import.
Blueprint imports use the same “integration” folder as that of the other XML based imports. The system will route the import to either: ongoing.unprocessed, ongoing.processed, or ongoing.skipped
Blueprint import samples are located in the distribution files. The default location is: C:\Program Files\”application name”>\integration\import\samples
As of application version 6.2 all blueprints require a shift or a shift split. All blueprints in setup have a new required field, Shift Splits. Blueprint import behavior will remain the same. Upon upgrade, if the application finds blueprints without a shift association it will create a default shift labeled, Default Shift for Splits, with no days or times defined and will be associated with all set institutions. A new split shift will be created and labeled, Default Split Shift, the Default Shift for Splits will be attached to the Default Shift Split. Existing blueprints will be associated with this new required shift split. The application will respect date and times initially set on preexisting blueprints. In version 6.2, the import manager will automatically apply shift splits based on the blueprint definition in Setup. This means if the blueprint shows Split 123, and Shift 1, Shift 2, Shift 3 are applied in Split 123, the blueprint will use the applicable Shift or Shifts on the deployed event based on the start and end datetime supplied. For example, if you deploy and event on 5/1/2017 start 8am through 1pm, the application will look at the shift split group associated with the blueprint, then locate the shift that matches the time period and deploy the event using the matching shift.
In application version 6.4.1.4, and 6.7+ the startDate time and endDate time tags were deprecated and replaced with new tags as follows <startDate> and <endDate>.
In version 6.4.1.5 the import logic for the ID field in blueprints changed to address shift split functionality. Blueprints deployed by a single XML node with a value or a blank space supplied in the ID tag will have and show the same value in the ID field of the blueprints and the ID field will be disabled via the user interface. If no ID tag is supplied, or you supply the ID with no value in the ID tags, then the ID field will be enabled and allow for editing with the limitation of the ID field being a unique field when manually updated via the user interface. Simply put, a set of blueprints cannot have a common ID when manually updated in the application. A common ID in a set of blueprints is only possible via the import.

Import Directory Formats are typically created by vendor partners. The format provided below is required if you intend to automate a regular feed from an external source. The sample shown below is for reference only please review and refer to required fields (tags) section for Add, Update, Remove action imports; for example if you are not importing the <blueprintID> then remove that XML tag from your file.

Deploy-Blueprint-Import-Sample-Insert

<?xml version="1.0" encoding="UTF-8"?>
<DeployBlueprintImportRequest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:common="http://telestaff.kronos.com/ws/v410/common"
xmlns="http://telestaff.kronos.com/ws/v410/blueprint/DeployBlueprintImport"
xsi:schemaLocation="http://telestaff.kronos.com/ws/v410/blueprint/DeployBlueprintImport DeployBlueprintImport.xsd"
insertNew="true" updateExisting="true" allOrNone="true">
<DeployBlueprintImportRecord optional="true" action="Insert" includeAfterPositions="true" includeBeforePositions="true">
<blueprintId>200101</blueprintId>
<institutionId type="abbreviation">1</institutionId> <!-- Required when institution focus is enabled-->
<unitId type="abbreviation">S1</unitId>
<productId>H</productId>
<quantity>10</quantity>
<labels>
label>L1</label>
<label>L2</label>
</labels>
<id>1</id>
<startDate>2016-10-26</startDate>
<endDate>2016-12-26</endDate>
<orderInformation>ABC</orderInformation>
</DeployBlueprintImportRecord>
</DeployBlueprintImportRequest>

Deploy-Blueprint-Import-Sample-Remove

<?xml version="1.0" encoding="UTF-8"?>
<DeployBlueprintImportRequest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:common="http://telestaff.kronos.com/ws/v410/common"
xmlns="http://telestaff.kronos.com/ws/v410/blueprint/DeployBlueprintImport"
xsi:schemaLocation="http://telestaff.kronos.com/ws/v410/blueprint/DeployBlueprintImport DeployBlueprintImport.xsd" allOrNone="true">
<DeployBlueprintImportRecord optional="false" action="Remove"
includeAfterPositions="false" includeBeforePositions="false">
<id>1</id>
</DeployBlueprintImportRecord>
</DeployBlueprintImportRequest>

Deploy-Blueprint-Import-Sample-Update

<?xml version="1.0" encoding="UTF-8"?>
<DeployBlueprintImportRequest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:common="http://telestaff.kronos.com/ws/v410/common"
xmlns="http://telestaff.kronos.com/ws/v410/blueprint/DeployBlueprintImport"
xsi:schemaLocation="http://telestaff.kronos.com/ws/v410/blueprint/DeployBlueprintImport DeployBlueprintImport.xsd" allOrNone="true">
<DeployBlueprintImportRecord optional="false" action="Update"
includeAfterPositions="false" includeBeforePositions="false">
<blueprintId>EXTID1</blueprintId>
<unitId type="abbreviation">S1</unitId>
<productId>SKU1</productId>
<quantity>10</quantity>
<labels>
<label>abc</label>
</labels>
<<startDate>2016-11-09</startDate>
<endDate>2016-11-11</endDate>
<orderInformation>ABC</orderInformation>
</DeployBlueprintImportRecord>
<DeployBlueprintImportRecord optional="true" action="Update"
includeAfterPositions="false" includeBeforePositions="false">
<blueprintId>200101</blueprintId>
<id>ID2</id>
<blueprintId>EXTID1</blueprintId>
<unitId type="abbreviation">S1</unitId>
<productId>SKU1</productId>
<quantity>10</quantity>
<labels>
<label>abc</label>
</labels>
<startDate>2016-11-19</startDate>
<endDate>2016-11-20</endDate>
<orderInformation>ABC</orderInformation>
</DeployBlueprintImportRecord>
</DeployBlueprintImportRequest>

The import tool will choose which blueprint to apply on the Planning Board upon import by matching the field values of the blueprint. Each row or set of data in the import file must correspond to a single blueprint and must specify these required fields for each action type:

ADD

Institution¹ (Institution abbreviation or external ID required if Institution Focus is turned on otherwise optional)
Unit² (Unit abbreviation or external ID)
Start Date³
End Date⁴

UPDATE

ID (deployed blueprint id)
Institution (abbreviation or external ID required when institution focus is enabled)
Unit (abbreviation or external ID)
Start Date
End Date
Optional - Order Information

REMOVE

ID (deployed blueprint id)

If more than one Blueprint (template) matches the criteria provided, the activity log will show, More than one Blueprint matched. Providing precise or more than the required fields are typically needed to return the best Blueprint (template) match when multiple Blueprint (template) possibilities exist.

Additionally, Labels, Product ID (SKU), and Quantity fields can not be updated via the XML. These fields uniquely identify the anatomy of a blueprint (template), simply put, data inputs in these fields typically relate to other fields in the blueprint (template); for example the product ID, label, or quantity could identify a mix of jobs, job count, skills, or which production lines to use either because of the type of equipment needed or volume, and so on. To update Label, Product ID, or Quantity you must either update the blueprint (template) in Setup if the update applies to the Blueprint (template) - or - if the update applies to an instance of a deployed blueprint on the Planning board then creating a new template for future use may be needed. If you need to deploy a new blueprint template, you must remove the deployed blueprint manually or via the XML first, and then add the new Blueprint using the new blueprint template via the XML process.

Each <DeployBlueprintImportRecord> can optionally have a section where one or more records can be supplied. The following is the list of fields that are included for each <DeployBlueprintImportRecord>.

Important
Non-key field names are optional. If supplied, the corresponding field will be updated. When targeting a specific template only required fields by Action type must be supplied, and must match a template. This means if you are targeting a blueprint with Label 1, and Label 2, and insert Label 1 and Label 3 in the XML file the import will fail because Label 3 is not in the target blueprint and ‘Label’ is used for matching. Conversely, if you provide Order Information that is not on the target blueprint the import will pass the data because ‘Order Information’ is not used for matching.

Important

Non-key field names are optional. If supplied, the corresponding field will be updated. When targeting a specific template only required fields by Action type must be supplied, and must match a template. This means if you are targeting a blueprint with Label 1, and Label 2, and insert Label 1 and Label 3 in the XML file the import will fail because Label 3 is not in the target blueprint and ‘Label’ is used for matching. Conversely, if you provide Order Information that is not on the target blueprint the import will pass the data because ‘Order Information’ is not used for matching.

Lay term (*REQUIRED)	Format (*case sensitive)	Used for Matching Y/N	Field Name
ID <id>	Text	Y	A unique identification code for a blueprint instance stored in the ID field of a deployed or imported blueprint. The ID is used to differentiate, identify, and target blueprints. This unique ID is typically generated and supplied by a third party system on the Blueprint Import XML file where it is used to identify and target a blueprint that is imported into this application. Hence, also used for matching when updating or removing blueprints. This application does not auto generate this ID for blueprints and as such when a blueprint is manually deployed on the Planning board the ID field is blank. To locate the ID field on a blueprint, edit a blueprint on the Planning board. An ID must be unique. MAX: 40 Characters. Note: The ID is not the internal identifier of the blueprint (the gray number). The ID is supplied by another application or a user.
*Location Abbreviation - or - Location External ID <InstitutionID type=”abbreviation”> or <InstitutionID type=”externalId”> Note: (Institution level of the Organizational Structure).	Text	Y	* *Required only if Institution Focus is turned on.* The XML property file uses either the supplied institution’s abbreviation or the External ID of the institution. Institution Abbreviation: Max 10 Characters, or Institution External ID: 40 Characters
*Line Abbreviation - or - Line External ID <UnitID type=”abbreviation”> - or - <UnitId type=”externalId”> Note: (Unit level of the Organizational Structure).	Text	Y	The XML property file uses either the supplied Line’s (Unit) abbreviation or the External ID of the Line. Unit Abbreviation: Max 10 Characters, or Unit External ID: Max 40 Characters Note: The blueprint will be deployed on the Unit associated with this abbreviation or external ID. If the blueprint has Security set to disallow the selected unit, the deploy will not occur and an error is logged.
*Start Date Time <startDate>	DateTime	Y	The start date and time of the blueprint when applied on the Planning Board. Format: 2016-10-26T21:32:52 Note: <startDate Time> deprecated. <startDate> available as of v6.4.1.1, v6.7+
*End Date Time <endDate>	DateTime	Y	The end date and time of the blueprint when applied on the Planning Board. Format: 2016-10-26T21:32:52 Note: <endDate Time> deprecated. <endDate> available as of v6.4.1.1, v6.7+
SKU/Product <ProductId>	Text	Y	The SKU or Product field on the Blueprint. The SKU or Product code associated with the target blueprint for matching and returning the most fitting blueprint via the Blueprint Import. Max: 40 Characters
Quantity Range <quantity>	Number	Y	The Quantity on the Blueprint. Also Used to indicate the minimum and maximum amount of product associated with the target blueprint for matching and returning the most fitting blueprint via the Blueprint Import. Max: 9 Integers (999999999)
Order Information <orderInformation>	Text	N	The Order Information on the scheduled blueprint or when applied on the Planning Board. Also, used for matching and returning the most fitting blueprint via the Blueprint Import. Max: 40 Characters
Labels <label>	Text	Y	The text of the label attached to a blueprint. Also, used for matching and returning the most fitting blueprint via the Blueprint Import. Accepts multiple values. Max: 40 Characters
External ID <blueprintId>	Text	Y	A unique and external ID of the blueprint (template) in Setup > Blueprint that is used to import blueprints on the Planning board. This ID identifies the blueprint (template) to be used and must be unique. Format: Text. Max: 40 Characters

Blueprint Attributes

The following optional attributes can be supplied with the <DeployBlueprintImportRecord> tag to override the default behavior of the import process. For example, you can ensure that only an update is performed on a given row and that a failure will not stop the process by starting the row section with <DeployBlueprintImportrecord optional=”true” action=”Update” includeAfterPositions=”true” and includeBeforePositions=”true”>

Name	Format (*case sensitive)	Description
Action	One of... Insert: <DeployBlueprintImportRecord optional=”true” action=”Insert> Update:<DeployBlueprintImportRecord=”true” action=”Update”> Remove:<DeployBlueprintImportRecord=”true” action=”Remove”>	The default behavior seeks to update and insert if an existing record is not found. This attribute allows you to specify how this individual row is treated. Valid actions (case sensitive) are: `action=”Insert”` - creates the record. `action=”Update”` - updates the record. `action=”Remove”` - removes the record `optional=”true”` is the default and recommended setting that applies to `Update` or `Remove` actions. `Optional=”true”`skips the record if that record does not exist and the import process continues. `Optional=“false”`halts the entire process if `allOrNone=”true”`or if `allOrNone=”false”` that record is skipped.
Optional	*true or false (default)	If true, then match failures will be overlooked. For example, a record designated with <DeployBlueprintImportRecord optional=”true” action=”Update” includeAfterPositions=”true” and includeBeforePositions=”true”> indicates that you want to update if a match is found but that you don’t want to fail if a match is not found.
Include After	Boolean <includeAfterPositions=”true” includeBeforePositions=”true”>	Whether to import After Positions associated with the target blueprint. “false” means the After Positions are not included when imported. “true” means the After Positions are imported if available. The default value for this field is “true”.
Include Before	Boolean <includeAfterPositions=”true” includeBeforePositions=”true”>	Whether to import Before Positions associated with the target blueprint. “false” means the Before Positions are not included when imported. “true” means the Before Positions are imported if available. The default value for this field is “true”.

Notable Import Behaviors
If institution focus is enabled <institutionId type=”abbreviation”>1</institutionId> is required -- or-- use <institution type=”externalId”>abc</externalId>. If more than one blueprint match exists the import will not create, remove or update the blueprint. If required field data is missing or does not match the import will not create, remove or update the blueprint. If multiple blueprints are applied to the same Unit and Blueprint Overlap Severity are turned off in the Organizational structure for the Institution or that Unit the import will not create the blueprint. A blueprint update via XML will only update the Start and End datetime. This means if you update a blueprint with a new date and include an additional label, only the date will be updated. Errors identified in the Import List error log include: There is required data that is missing in a file (start/end datetime, Institution (if Institution Focus is on), or line). A data row did not match to a Blueprint. More than one Blueprint is matched. If there are more than one Blueprints matched, these will NOT be placed on the Planning Board. Multiple Blueprints are assigned to the same line for an overlapping time. If overlapping blueprints are set to "Warning", then the import should show a warning. If the overlapping blueprints are allowed, then the import will not show a warning.

Notable Import Behaviors

If institution focus is enabled <institutionId type=”abbreviation”>1</institutionId> is required -- or-- use <institution type=”externalId”>abc</externalId>.
If more than one blueprint match exists the import will not create, remove or update the blueprint.
If required field data is missing or does not match the import will not create, remove or update the blueprint.
If multiple blueprints are applied to the same Unit and Blueprint Overlap Severity are turned off in the Organizational structure for the Institution or that Unit the import will not create the blueprint.
A blueprint update via XML will only update the Start and End datetime. This means if you update a blueprint with a new date and include an additional label, only the date will be updated.

Errors identified in the Import List error log include:

There is required data that is missing in a file (start/end datetime, Institution (if Institution Focus is on), or line).
A data row did not match to a Blueprint.
More than one Blueprint is matched. If there are more than one Blueprints matched, these will NOT be placed on the Planning Board.
Multiple Blueprints are assigned to the same line for an overlapping time. If overlapping blueprints are set to "Warning", then the import should show a warning. If the overlapping blueprints are allowed, then the import will not show a warning.