Creating Imports
Here we will delve into the ins and outs of import creation, covering the planning process and the actual setup.
Import creation is limited by security groups, usually to an Administrator. Typically, the Administrator role has import permissions by default. See Administration for Imports at the end of this page.
Planning Import Creation
Before diving into creating an import, it's crucial to pin down your business goals and requirements. Having these in place ensures a smooth and effective import process.
Questions to consider:
Purpose of the Import: What’s driving the need for this import?
Example: Are you bringing in PO records from a separate financial system? Or maybe updating task dates from a vendor spreadsheet?
Need for Import Group: Will this Import be assigned to an existing Import Group for organizational purposes or does an Import Group need to be created?
Type of Import Action:
When configuring an import, Administrators have the option to enable one or multiple actions. Users can then choose from these enabled actions when they run the import. Therefore, a single import setup could offer a mix of the following actions:
Insert: Add new Trackor records into the database, expanding your dataset effortlessly.
Update: Modify existing fields using a key match, ensuring data remains current and relevant.
Insert/Update: A combination action that either creates new Trackor records if no key match is found or updates existing data if a match is identified, optimizing data consistency.
Target Trackor Type: On what Trackor Type will records be updated and/or inserted? What parent relationships need to be included when setting up the import?
Users and Permissions:
Who is going to use this import primarily?
What restrictions need to be in place to ensure only approved users make changes?
Does this import need to be limited to only allow specific fields of a Trackor Type to be updated when using this import?
Field Restrictions: Double check if any fields have restrictions in the GUI.
Trackor selector fields or drop-downs must be spelled correctly (case-sensitive) and multi-selector options separated by a comma.
Locked fields will not update and will present an error.
Read-only fields can be updated unless explicitly excluded.
See the Troubleshoot Imports page.
Data Validation: Think through how you want to handle potential errors during the import. Typically you are choosing between not starting the import with errors or warn when import has errors, with the recommendation to choose warn when import has errors.
Adding an Import Group
To enhance the organization and management of imports, we have Import Groups accessible on the Import Data and Import pages. Administrators can add, edit and delete Import Groups to accommodate their sets of imports.
Steps to Add an Import Group | ||
|---|---|---|
1 | Navigate to the Administrator Import page: |  |
2 | Click Import Group from the Command Bar or ellipsis menu. |  |
3 | Click Add. |
|
4 | Enter the Import Group Name and Group Label. |  |
5 | Click OK. |
|
6 | Click Close. The new Import Group will be part of the drop-down list for the Import Group field on the General tab. |
|
Ways to Create an Import
Recommended best practice is to build, test, and perfect any new or modified imports in a development environment before moving into production.
This avoids import recovery issues in the production environment that happen when there are changes between when the import is run and the associated recovery is run.
Ready to create an import? Let's dive in.
You have two routes to initiate the process:
Default Data Import: Kickstart this from the Trackor Types page. It systematically crafts an import for the chosen Trackor Type, using an external procedure for the import and eliminating the need to map out every field to be imported. Additionally, fields can still be mapped to make relationships which makes them required (Expected Fields) for the import.
We'll explore this method in the guide below.
Note that Imports which run External Procedures (including all Default Data Imports) allow the importing of any field on the Trackor Type and should be used with care.
Manual Import: For users with advanced knowledge and specific import needs, the Manual Import option is available. Choosing this method allows you to manually configure every aspect of the import. It's best suited for Administrators who are experienced with the system.
If your import needs to be limited to only specific fields, it must be set up using the Manual Import method.
See Workplan Task Imports for information on creating a manual import.
An additional import process is available for cascading fields. See Importing Cascading Fields.
Imports support Object References.
Creating the Default Data Import
Steps to Create a Default Data Import | ||
|---|---|---|
1 | Navigate to the Dev Center > Design Applications > Trackor Types. |
|
2 | From the Trackor Types page, you can use Search to find the specific Trackor Type for which you are creating the import. Highlight the record and find Create Default Data Import in the Command Bar or ellipsis menu. |  Create Default Data Import |
3 | A window will open including an autogenerated Import Name [Trackor Type Name Default Data Import (date time)]. This can be changed now or later; however, the name must be unique for the import to create. Click OK. |  Create Default Data Import |
4 | Navigate to Dev Center > Build Applications > Import. The import will have a description of “This import was generated automatically.” You have successfully created the import. |  Newly Created Import |
Customizing the Default Data Import
Now that your Default Data Import has been created, you can customize it.
Steps to Customize a Default Data Import | ||
|---|---|---|
1 | Navigate to the Dev Center > Build Applications > Import. |
|
2 | Select the import to customize and click Edit. |
|
3 | Complete the General tab fields. See Import - General Tab. Best Practice is to at least change the Import Name, select the Action(s), and provide an accurate description.) Click Apply to save changes. | 
|
4 | Click the Fields tab to rename the Key Field Name (will include “XITOR_KEY”). Best practice is to use the label for the field on the Trackor Browser page. For data to import correctly, add Fields that should be included in every import to make them part of the required data. For example, if you always want PO ID and PO Line ID, both should be included here. Click Add to add additional Fields, which will be mapped in the next step. See Import - Fields Tab. All Fields on this tab become “Expected Columns”, which are required when users run imports. |  Fields Tab |
5 | Click the Mappings tab to add any mappings. Fields that are added on the Fields Tab (excluding the default XITOR KEY) need to be mapped to import correctly. |  Mappings Tab |
Import - General Tab
Field Name | Description |
|---|---|
Import Name* | Name of the import. This is what users see on the list of imports. Default data imports have auto-populated names that should be updated to be descriptive for users and include the Trackor Type. |
Import Group | Available options in drop-down list. To add to this list, see Adding an Import Group above. (Import Groups are used to organize imports into groups on the Import and Import Data Pages. You’ll need to edit the page view to include “Group” as a column in order to organize page by groups.) |
Data Preprocessor | This allows for a SQL statement to be written that will convert or modify data prior to the import sequence. This is not used in most applications of the Vizion Platform. Please contact your Customer Success Manager for details. |
External Procedure | Stored code that is part of the Vizion Platform, that can be run repeatedly. For a default import, this field is pre-filled and can be edited if necessary. However, when setting up a Manual Import that should run an External Procedure, an admin will need to input this information manually. See External Procedures below. |
Actions* | This is a multi-selector that allows you to choose among Update, Insert/Update, and Insert actions. For definitions of these actions, please refer to the Introduction to Imports page. Selections here determine the options users have when executing the import. Consider carefully when selecting between Update, Insert/Update, and Insert options. Allowing users to create new records via import can pose a risk to data integrity. For a more controlled approach, consider creating separate imports for 'Insert' and 'Update' actions. This can minimize errors and help maintain data quality. |
Default Action | The options here are dependent on what is selected in the Actions field. The selection here will be the default for running the import. If a default action is not selected, the import defaults to the first option selected in the Action field. Why make a selection? You can reduce clicks for the user running the import. For example, if the import will be used most often for updating, setting this to “Update” reduces a click for the user when running the import. |
Data validation mode* | Indicates which validation mode the import uses.
Note: Validation options apply only to fields set up in the 'Mappings' tab with "Configured Field*" import data types and are limited to basic checks like drop-down selections and date formats. They won't catch complex issues such as locked fields or rules. |
Keep parsed data for ___ days | Number of days to save the parsed data. Set it to a non-zero number so that data is available for post-importing debugging. Data will delete via a nightly job after the entered number of days. |
Line Delimiter* | Contains the available line delimiters which marks the end of a line in a text file. The recommended Line Delimiter is <new line>. |
Date Format* | Contains the format in which dates will be inserted into the database, which must be an Oracle supported date format (e.g., MM/DD/YYYY). |
Field Delimiter* | Contains the available field delimiters which are used to separate individual data fields in text. The recommended Field Delimiter is a comma. |
Time Format* | Contains the format in which times will be inserted into the database. |
String Quote* | Contains the available list of string quote values, which enclose strings in data files and allow for special characters or whitespace. The standard String Quote is a double quote (“ ”). |
Max Runtime (Minutes) | Enter a time estimate in minutes for the longest import you anticipate and then add an extra 20% buffer. If an import takes longer than this time, a notification will be sent to the admin email as defined in the system parameters. |
Description | Provide a description for the import that users will see. This description should clearly explain the purpose of the import, instructions on how to use it, list “Expected Columns”, and any potential warnings or precautions. |
Template File | To ensure better understanding of and compliance to the import data format, you can upload a template file: an *.xlsx or a *.csv table containing column names, data examples, comments etc. This file will be available to users as a reference for the import data format. See Creating the Import Template File below. |
Generate the template file | The Vizion Platform can generate a template for manual data imports that have mapped fields. Clicking this on a default data import, will give an error. |
Creating the Import Template File | ||
|---|---|---|
1 | Navigate to the Trackor Browser page for the Trackor Type to import. |
|
2 | Find or create the view that includes the fields you want to import. |
|
3 | Click Export (select Grid to CSV) and click Export. Download the file. |
|
4 | Open the file to see that the second row includes the field names that you need. Any field that has “XITOR_KEY” for the field name needs to be changed to the name defined on the Fields tab in the import. |
|
5 | Make the data in the second row your top row and delete everything else. Save the file. |
|
6 | Navigate to the Import page and click the hyperlink for the import or highlight the import record and click Edit. |
|
7 | On the General tab, find the Template File field, and click the ellipsis to select the file you just created. Click Open and OK. The file is now available for the Run Imports process. |  Add Template to the Import
 Template is Available for Run Import |
Import - Fields Tab
For imports designated as Default Data imports, the Key field (XITOR KEY) from the Trackor Type is pre-populated in the Column Name.
Renaming the Key Field: It is advisable to rename the Key field (XITOR KEY) to a more recognizable name. Best practice is to change this to be the field label on the Trackor Browser.
To rename, either click directly on the ID or select Edit.
In the “Edit Field” window, input the new name for the key field. This is the name users will include in their import file.
Confirm changes by clicking OK, which will save the new field name and close the window.
Adding Additional Fields
As needed, you can add extra fields to this tab that will be required in the import and mapped in the Mappings tab.
For guidance on the types of data that can be mapped, refer to the Mapping Data Types section below.
Example - Adding a Field for a Relation Mapping
If a Trackor Type has a parent relation that needs to be assigned via import, then you need to add a field for the parent Trackor Type’s Key field (XITOR Key) that you will later use in the Mappings tab.
Click Add.
Input the Field Name and its Description.
Click OK. The field will now have an ID assigned and will be displayed in the list.
Remember: Simply adding fields here won't establish relationships or apply restrictions. Those adjustments need to be made under the 'Mappings' tab.
Import - Mappings Tab
For each Default Data import, a SQL statement is auto-generated to transfer data to the corresponding Trackor Browser. You'll find this on the Mappings tab.
Viewing the SQL and Required Fields:
Access the SQL by clicking on the Mapping ID. This will display the system-generated SQL on the General tab, along with any Required Fields.
While there's no necessity to alter this SQL for typical imports, those with advanced knowledge (like experienced administrators) have the option to customize the SQL to accommodate specific import handling.
Adding Specific Data Mappings: When your data import involves constraints (e.g., drop-down menus, selectors, multiselectors), dates, or relation dependencies on other data or Trackor Types, you'll detail these specifications as mappings on this tab, all without modifying the SQL directly.
The steps below explain how to set up a relation mapping. A list of all the possible Mapping Data Types is below. Each of these will have different considerations when building the mapping.
Create a Mapping - Relation Example | ||
|---|---|---|
1 | Expand the view by clicking the + next to the ID on the Mappings tab. |  Mappings Tab - Expand Mappings |
2 | Click Add inside the inner box. (There are two Add buttons on this screen.) This will open the Add Mapping applet. |  Mappings Tab - Add a Mapping |
3 | For this example, we will build a Relation. Exact steps may vary for different Data Types. The full list of Data Types are listed below. In the Column Name field drop-down, you will be able to select from the names of fields that you added in the previous step on the Fields tab. To build a relation, select the parent field you created here. |  Add Relation Mapping |
4 | Next to Data Type, click the ellipsis to open the list, and select Relation. Click OK. |  Relation Data Type |
5 | Click the Params button to the right of the Data Type. This opens the Data Type Parameters window. Here you see parent Trackor Types in the Parent xitor type dropdown. Select the Trackor Type for the parent field you created for the import. Additionally, decide yes/no to deleting existing relations.
The best practice is to select yes to delete existing relations (except many-to-many relations); otherwise, one record can unintentionally end up with multiple parents. |  Data Type Params |
| Click OK in the Params window. |
|
6 | Back in the Add Mapping applet, change your Mapping Name to something that explains the mapping (for other admins and future reference). Click OK to save and close. |
|
Additional relations can be added by repeating these steps, provided they exist in the Trackor Tree.
Mapping Data Types
This is a list of the other data type options that can be set up in an import mapping.
Data Type | Description |
|---|---|
Config Field MultiSelector | Use this option to import Multiselector and Trackor Multiselector types that you want to run through data validation when an import is loaded. |
Configurable Field | Use this option so that the imported data field will run through data validation when an import is loaded. |
Configurable Field (ID Value) | Set up the configuration using the numeric field ID instead of field name. Use this option so that the imported data field will run through data validation when an import is loaded. |
Configurable Field (Keep Existing) | Data in the import will be only update fields with no data (NULL) and will not overwrite existing data. |
Configurable Field Allow NULL | Use this option so that the imported data field will run through data validation when an import is loaded. NULL values will update to a blank field. |
Configurable Field Allow NULL (ID Value) | Set up the configuration using the numeric field ID instead of field name. Use this option so that the imported data field will run through data validation when an import is loaded. NULL values will update to a blank field. |
Configurable Field Comments | Use this option to set up an import to insert a comment on a field in the Comments.  Field Comments |
Configured Field - Force Number | If you need to use SQL to find a Number, use this one. |
Configured Field Update Overriding Lock | Use this option to set up an import that will load changes even if a lockable field is locked (which otherwise causes an import error.) |
Delete Relation by Trackor ID | Deletes relation using the parent's Trackor ID. |
Delete Trackor | Deletes Trackor record by xitor_key. |
EFile | Use to update an EFile field. (You cannot import from a directory.) The import file should contain:
 |
Create relation between xitors, using column value as xitor_key of parent xitor. | |
Relation - Force Locked | Create relation between xitors, using column value as xitor_key of parent xitor and lock the relation to prevent changes. |
Relation by xitor_id | Create relation between xitors, using column value as numeric xitor_id of parent xitor. |
Relation by xitor_id - Force Locked | Create relation between xitors, using column value as numeric xitor_id of parent xitor and lock the relation to prevent changes. |
Static Date Field | Choose a Table, and Field where this Table has the same Key Field as the Entity this Mapping Belongs to. That Date Field will be updated. |
Static Field | Choose a Table, and Field where this Table has the same Key Field as the Entity this Mapping Belongs to. That Field will be updated. |
Static Field (Character Truncate) | Choose a Table, and Field where this Table has the same Key Field as the Entity this Mapping Belongs to. That Field will be updated and truncated to the number of characters specified. |
Static Lookup | Static field populated from a Look-up or VTable that is not Project Specific. |
Task Predecessor Update | Update a particular task's predecessor list in the workplan. |
Task set Block Calc. | Use to set the Block Calc flag on a task by order number. Empty value makes no change. |
Task set N/A | Use to set the N/A flag on a task by order number. Empty value makes no change. Import file column name contains "NA" followed by the task order number -e.g. "NA123". |
WP Task Date | Workplan task is the entity. Import file column name contains the representative letter of the date type (Baseline, Projected, Actual, or pRomised) followed by 'S' for Start or 'F' for Finish, and the task order number - e.g. "PF123". |
WorkPlan Date by Task Name (All Subs) | Given a task name and a workplan as the entity, the date for this task is updated for all tasks belonging to ALL workplans. |
WorkPlan Set Not Applicable | This updates all tasks in the workplan with the n/a flag. Empty value makes no change. Workplan is the entity. Yes or 1 or n/a sets n/a and no or 0 unsets n/a (not case sensitive.) Import file column name contains "NA" followed by the task order number -e.g. "NA123". |
WorkPlan set Block Calc. | This sets the Block Calc flag for all tasks in the workplan. Empty value makes no change. Yes or 1 blocks the task from calculations and no or 0 unblocks (not case sensitive.) Import file column name contains "BlockCalc" followed by the task order number - e.g. "BlockCalc123". |
Workplan Date by Trackor | Given the Trackor record as the entity, choose a wokplan, task order number and which date field to update. Import file column name contains the representative letter of the date type (Baseline, Projected, Actual, or pRomised) followed by 'S' for Start or 'F' for Finish, and the task order number - e.g. "PF123". Accepts NULL as a value to delete date. Uses V_WP_DATE_TYPE and V_WP_DATE_SF V_ tables to populate parameter values. |
Manual Import
If the Default Data Import doesn't meet your needs for more complex or specific tasks, then the Manual Import method is your go-to option. This approach gives you full control, allowing you to manually configure every detail of the import.
In the sections below, we'll walk you through the steps for creating a manual workplan import and discuss external procedures you can use for other types of manual imports.
Create a Manual Import for Workplan
When you are aiming to update tasks in a workplan, the Default Data Import method will not work. Instead, you will need to use the Manual Import method.
Here's how to set it up:
Navigate to Dev Center > Build Applications > Import.
Click Add. This will open the window to create a New Import on the General Tab.
Although the fields will look familiar (as they match those above), this time around you'll need to populate each one manually. Set up the import as it best fits your needs, but pay special attention to the following:
External Procedure: When updating task data, your input should mirror this format:
pkg_dl_support.AllowNulls := 1; pkg_ext_imp.WPDatesByOrderNum(:rid, 100009999);
Breaking it down:
pkg_dl_support.AllowNulls := 1; lets users input NULL values for tasks. Without this, any NULLs would be ignored during the data load.
pkg_ext_imp.WPDatesByOrderNum(:rid, 100009999); is a procedure that permits the loading of workplan modifications, including changes to dates, BlockCalc settings, and N/As for regular and independent Workplans.
You must update the number in the procedure (100009999 in this example) to the Trackor Type ID for the workplan’s Trackor Type. You can find this ID in the Trackor Types list.
For the Description field, you'll want a concise yet detailed guide on utilizing the import. Here's a template:
File Format: Acceptable formats are CSV or Excel. Essential columns: Project ID, Workplan ID. For task updates, include additional columns. For instance, a column labeled "PF123" would update the Projected Finish date for task 123. Only tasks that have updates should be included as a column.
Column Naming Conventions: Date Types: Use the representative letter of the date type (Baseline, Projected, Actual, or pRomised) followed by 'S' for Start or 'F' for Finish, and the task order number - "PF123". N/As: "NA" followed by the task order number - "NA123". BlockCalc: "BlockCalc" followed by the task order number - "BlockCalc123".
Value Inputs: Set a column to N/A or BlockCalc using: "1", "Y", or "Yes". These are not case sensitive. Remove an N/A or BlockCalc using: "0", "N", or "No". Again, not case sensitive. Leaving a value blank won't trigger any changes. To erase data, input "NULL" (case-sensitive) in the desired field.
Given the complexity of this particular import setup, it's a good idea to provide a template file in the "Template File" field. Here is a sample template, but remember to tailor it to fit your specific system needs. (Click to open in preview and then download the Excel file.)
External Procedures for Other Manual Imports
An external procedure refers to a function or method that you define outside of the current module, allowing complex operations to be encapsulated into a single callable routine. In the Vizion Platform, these procedures enhance the import process by providing additional functionalities. Below is a list of external procedures available for use within the platform. To execute multiple procedures in sequence, simply separate them using a semicolon (;).
Remember: Imports which run External Procedures allow the importing of any field on the Trackor Type and should be used with care. This applies to manually created imports if using an External Procedure.
If an import should be limited to only specific fields, they all need to be mapped and the import should not use an External Procedure. In this case, you would add all needed fields on the Fields tab and map them on the Mappings tab.
External Procedure | How to use it |
|---|---|
Configured Fields External Procedure = pkg_ext_imp.XitorConfiguredFieldLoad(:rid) |
|
Allow NULLs External Procedure = pkg_dl_support.AllowNulls := 1 |
|
User Creation External Procedure = pkg_ext_imp.USERSLOAD(:rid,1,100005678,'XITOR_KEY') |
|
VTable Load External Procedure = PKG_EXT_IMP.CONFIGUREDVTABLELOAD(:rid) |
|
Create/Update Configured Fields External Procedure = pkg_ext_imp.configuredfields(:rid) |
|
Tenant Label Text, Multi Language Updates External Procedure = pkg_ext_imp.label_program_load(:rid) |
|
System Labels Text, Multi Language Updates External Procedure = pkg_ext_imp.label_system_load(:rid) |
|
Task Labels Text, Multi Language Updates External Procedure = pkg_ext_imp.label_task_load(:rid) |
|
Tabs with Assigned Classes External Procedure = pkg_ext_imp.ConfiguredFieldsWithTabs(:rid); | Used to update / import tabs and assign classes Import file example including Trackor Type, Field Data, Tab Data, and Classes:  The classes listed for TAB_Classes need to be separated by a comma without spaces and must be assigned to the Trackor Type. Note: Imported tabs must be added to an applet to be used in the system. |
Workplan Updates External Procedure = pkg_ext_imp.WPDatesByOrderNum(:rid, 100009999) |
|
Administration for Imports
The user must have these security groups to create imports:
The user working with the import will also need add / edit privileges for the Trackor Type(s) the import affects.
It is also recommended that users have:
The ImportRunErrorHistoryPurgePeriod system parameter sets the number of months the system stores log data.
Tip: Don’t change individual user settings to add these security groups. Edit at the role level. This makes it much easier to monitor and control who has access. |
|---|
