Appendix B - Import Formats

Import formats

The following chapters of Appendix B discuss the formats used by Safran to import new/update existing Activities, Links, Resources, Progress, and expended information.

General information

In addition to importing a complete project, Safran Project also provides facilities that allow you to import a wide range of specific project data such as Activity, Link, Resource, and Progress from files.

All import facilities allow you to add new information, while certain facilities also allow you to update existing information.

All formats accept tab-separated text files, while the Import Progress & Expended facility also accepts XML files. The tab-separated text file is the most commonly used format and may easily be created using MS Excel.

Some Import formats, such as Activities, require an initial header line informing Safran which fields are in the import file. In contrast, in others, such as the Progress & Expended import in a fixed format, i.e., data columns must be presented in a specific order.

Below is an example of an import file created using Excel. Note that the first line contains header information, while the remaining lines contain the data to be imported.

When you are finished creating the import file, make sure you save it using the 'Save as Type' Text (Tab delimited) as shown below:

A word of advice

Remember that Safran is fairly sensitive when reading import files, and error messages might occur when reading the file.

In addition to an obvious misspelling of a field header or incorrect data value for a field, Safran will produce an error message related to 'Case Sensitivity' if your database is set up with Case Sensitive field names and your file does not observe this.

Additionally, to prevent erroneous cells from being included in the import file that would also cause Safran to fail, it's a good idea to outline and copy the exact data range to be imported to a new/empty Sheet and export that sheet to the file.

Finally, after saving the data to the file, please close the Excel file to allow Safran to access the resulting import file.

Notepad may also be used to check or make minor adjustments to your import file. Again, be sure to save the file before opening it with Safran.

Import Activities

File format & requirements

Activity/Milestone/Hammock data may easily be imported directly to Safran Project from a file. The Import Activities facility also allows you to update information on existing activities.

As previously mentioned, the file must be a tab-delimited text file.

Further, the first line of the file (also called the Header line) must always contain a description of each field to be imported.

Most Activity input fields may be imported in any order. However, the first field must always be the Activity ID.

Header

Remember that the field descriptions in the header are not the field/friendly names you use in Safran. However, they are the internal database names.

Typical Safran system fields and their short names used when importing are:

Similarly, your Safran User-defined fields must also be referred to by their Database Column names when importing data.

Below is a conceptual overview of Safran's user-defined field types and their corresponding Database Column names:

A list of your User defined fields and their corresponding Database Column Names (referred to under the 'Field' column) may be found by selecting Data/Userfields in Safran as shown below:

Remember that Reference/Outline Code values are imported using their 'Short'/'Code' name, while the remaining field types are imported by their value, i.e., 22-aug-22, 10034.65, 'This is a description.'

Importing Multiple-choice fields

When importing simple Multiple choice type fields such as Always on Schedule, Activity duration fit, or User defined flag fields that only allow Yes/No values, remember that they must be imported as 0 for No or 1 for Yes.

Safran Project also contains several complex Multiple-choice fields with more than Yes/No options. Examples are Calendar, Activity type, and Must start on day/time where each option for the field will have its index value, i.e., Activity type=Start milestone has an index of 5 while Must start on=Wednesday has an index of 3.

(22.1.00 Feature): You can easily identify the correct index for a complex Multiple-choice field by selecting Properties for the relevant and choosing Code or Code + description for Format as shown below:

After choosing the extended format Code + Description for the field and clicking on the field value, Safran provides you with a complete list of valid values and their relevant codes/indexes to use when importing the field.

A typical Activity import file from Excel might look like this:

Importing national characters (Æ/Ø/Å)

When saving your import file, you must select the correct encoding to ensure the correct import of text values containing national characters such as Æ/Æ/Å (or any other national character sets). Safran primarily supports UTF 16 LE encoding, ANSI, and UTF 8 BOM.

If you use Excel to create your import file, you'll find that Excel doesn't allow you to choose UTF 16 LE encoding. One way of specifying this is to open the text file in Notepad and save it after having chosen the encoding as shown below:

Importing

Before executing the import, ensure that you are in the project you want to import the activities.

From the Ribbon menu, choose File/Import/Activities.

Browse the file to import from and press 'Open' from the Select Import File window.

You should then see the panel below:

If your import file only contains new activities to be added, ensure the Import Mode is set to 'Append.'

If your import file contains updates to existing activities, make sure the 'Update/Insert' Import Mode is selected. This option will also allow new activities to be added in combination with updates to existing activities.

Then press the Import button. When the import has been completed, Safran Project will tell you how many activities have been added/updated.

After pressing the Close button, Safran will ask whether or not to refresh your data. The newly imported activities will be included in the barchart editor by selecting Yes. Consequently, if you press the No button, you cannot view your newly imported activity data.

Troubleshooting/Potential Errors

During the import process, Safran executes a validation process to ensure the quality and consistency of the data imported. If errors occur, Safran will then present a message:

Notepad is opened with the relevant list of errors found by selecting Yes.

By pressing No, you are returned to the Import Activities panel without listing your errors. You may then edit/correct your import file and re-run the import if you know which errors are present.

A variety of typical error messages are shown below:

The date value '1-oct-20922' is an Invalid date format. Safran will also produce a similar message for 31-Jun-2022' as June only has 30 days.

The activities listed in the error message already exist in your schedule. Change the Activity ID and re-import. Alternatively, if you are trying to update existing activities, please remember to use the 'Update/Insert' Import Mode.

Invalid column name. In this case, the database column name for 'Calendar' is wpn. If you are sure your column names are correct, the error message may be due to your database being set up with 'Case Sensitivity.' Try using capital letters.

In most cases, you can edit your file and run the import again without closing the import facility.

Copy-paste from excel

It is also possible to "import" many activities by copy-paste from Excel.

For this to work smoothly, you must ensure that the columns in the Barchart Editor match 100% with your columns in Excel and that the first column is the Activity ID.

Watch the video below for a quick demonstration of how to do it:

Below is a longer video demonstrating how to paste from Excel to Safran Project Barchart Editor.

It contains a few tips and tricks for importing resources and what to do if you have an activity ID starting with '0'.

Importing and Exporting Links

Safran Projects allows you to both export and import links.

If you are uncertain about the import format, a good tip is to simply test the 'Export links' functionality first and then use the export file as a template for import.

If you are working on Project Groups, see Import Cross Project Links.

Export Links

Go to File/Export/Links

Enter the filename location and press Save.

Keep all links or exclude links using the various filtering options. Click Export.

The Export file, which you may use as an import file, should look like this:

File format & requirements

Link data may easily be imported directly to Safran Project from a file. The Import Links facility also allows you to update information on existing links.

The file must be a tab-delimited text file.

Further, the first line of the file (also called the Header line) must always contain a description of each field to be imported.

Most Link input fields may be imported in any order. However, the first two fields must always be the Preceding Activity ID (pan) and Succeeding Activity ID (san).

Header

Remember that the field descriptions in the header are not the field/friendly names you use in Safran. However, they are the internal database names.

Typical Safran system fields and their short names used when importing are:

A typical Link import file from Excel might look like this:

Importing

Before executing the import, make sure that you are in the project that you want to import the links to.

From the Ribbon menu, choose File/Import/Links.

Browse to find the file to import from and press 'Open' from the Select Import File window.

You should then see the panel below:

If your import file only contains new links to be added, make sure the Import Mode is set to 'Append.'

If your import file contains updates to existing links, you will notice that the 'Message' column to the right initially reminds you that your import file contains existing links.

In this case, select the 'Update' Import Mode.

After switching to 'Update' mode, your link updates are considered ready for updating.

The Import Links panel also lets you delete links before the import if needed. To do so, set focus on a link (highlighted in blue/mark to the left) and press the 'Remove From Import' button as shown below:

When you are satisfied with your import data, press the Save button. When the import has been completed, Safran Project will tell you how many links have been added/updated.

After pressing OK, you are returned to the Import links panel.

After pressing the Close button, Safran will ask whether or not to refresh your data. The newly imported links will be included in the barchart editor by selecting Yes. Consequently, if you press the No button, you cannot view your newly imported link data.

Important link import information

Unlike the Import Activities facility, combining adding new links and updating existing links in a single import file is impossible. This is because Safran Project allows you to link the same two activities more than once. When Safran Project reads the import file, it cannot determine whether an entry should be considered a new link or an update to an existing one apart from your choice of 'Append/Update.'

Importing Cross-Project Links

Importing Cross Project Links in Safran Project is possible using the Import->Links function. A cross-project link is a link between an activity in one project and an activity in another project. Importing cross-project links is only possible when working with a project group. The project group needs to include all the projects you want to link between.

These are the column headers that need to be in the tab-separated text file

pan san ntypec lagc split_target pan_project_name pan_project_owner san_project_name san_project_owner

Here is a description of what each of these headers represents:

pan - predecessor activity

san - successor activity

ntypec - link type

lagc - lag

split_target - split target date

pan_project name - project name for the project that contains the predecessor activity

pan_project_owner - the name of the owner for the project that contains the predecessor activity

san_project_name - project name for the project that contains the predecessor activity

san_project_owner - the name of the owner for the project that contains the predecessor activity

Here is an example text file opened in Excel. It is a cross-project link between activity a10 and B10 in projects A1 and B1; the owner of A1 is TMS and B1 by JHA. The link is of type FS.

Importing and Exporting Resources

As of version 22.2, Safran Project allows you to both import and export resources.

Additionally, this version allows you to import the full range of resource data fields such as Lag, Duration, Profile, Calendar, Unit Rate, Contract QTY/Cost, and VO.

Further, the new import facility provides more control over how the import will be executed regarding adding new/updating existing resources and default settings for missing VO and Total/Per unit type.

The new import facility provides a more comprehensive validation process, including a detailed error list and a 'Data on file' overview.

The Import Resources facility still supports the 'Legacy - resource matrix' import format, and Safran Project will detect which format is read and provide the appropriate user dialog/import facility.

Exporting and Importing is done by using text files of the so-called Tab Delimited format.

Export (from v22.2)

The Safran Project Export Resources function intends to support two different needs.

One is used to export resource information to a foreign (non-Safran) system, potentially including Activity information such as Activity ID, Description, and any user-defined field.

The second is intended when importing resource information to Safran Project, as the format will only export the Activity ID plus any selected resource data field.

The Export Resources function is not supported when working with a Project Group.

Select Export Resources from the ribbon file tab to export your resource information.

When the Export Resources panel opens, press the square icon to the right of the Export file line to specify/select your export file name and location.

When you have selected your export file and pressed Save, you'll return to the export resources configuration panel, as shown below. You can select the relevant Activity and Resource columns for your export here.

By pressing the Filter button, you can select/specify an activity-based filter to limit the export of resources to a subset of your project's activities.

If you have selected a filter, you'll see that the 'Filtered' checkbox is checked to remind you that not all resources will be exported.

After configuring your export, press the Export button to create your file.

The screenshot below is an example of a resource export file when opened with MS Excel. Note the 'friendly' field/column names used as header information for your user-defined fields.

If you intend to use the export facility to import resource data to Safran Project, select the Safran Import format check box.

You'll then notice that all activity columns are now de-selected/grey apart from the Activity ID column.

This is because these fields are irrelevant as part of a resource import to Safran Project.

New import (from v22.2)

The new resource import format requires column header information. An example is shown below.

The resource table field names may also be found in the Safran Project System Guide (your Safran system administrator will have this available). However, if you are unsure of a field's name, you can always do a resource export using the 'Safran Import format' checked and have a look at the resulting file with header information.

The fields in your import file may be a subset of the resource table fields available and may be in any order; however, it's always a good idea to start with Activity ID (AN) and resource.

Select Import Resources from the File tab on the ribbon to import your resource information.

When the Select Resources File panel opens, navigate to select your import file and press Open.

If you import resources to a project in progress and the Lock Scope property is selected, you must nominate a VO/Change for any new or updated resource. If the VO/Change number is missing or not present for one or more resources, you can drop into the change selection dropdown to select a default change for the relevant resource lines.

Suppose you utilize the Contract QTY/Cost facility to work with two separate sets of scope and haven't included a Contract scope in your import file. In that case, Safran can set the Contract scope equal to the Internal (Planned QTY/Cost) scope by checking the relevant tick box.

The resource type (Total/Per Unit) may also be set as a default for any resource line with a missing resource type.

You must also consider the content of your import file, as Safran Project can either add new resources, update existing resources, or combine the two.

Add will always add new resource entries.

Add/Update will add a new resource line if the resource does not previously exist and update existing resources. If multiple similar resource entries exist, Safran will update the first/initial resource line found.

When adding/updating a QTY-type resource, remember that entering a Cost/Cost1 value is irrelevant as these fields are calculated values for this resource type. The Cost/Cost1 fields may be added/updated for resources of type Cost.

Remember that you cannot update a resource entry if the Lock Scope/Resource data Project Property is configured to lock and you have set a baseline or baseline and status update (depending on your configuration). If you want to update the quantity/cost, this must be done as a change/VO.

In general, it's a good idea to do some test resource imports on a copy of your project until you are comfortable with the functionality to ensure that you get the results you are looking for.

When you are satisfied with your import configuration, press the Read button.

As a part of the Read process, a validation of the data file is carried out. A number of the validations are listed below:

- Activity ID/Resource/Profile/VO name must exist.

- Resource lag must be a positive and less than activity duration

- Resource Lag + Duration must not exceed activity duration

By selecting the Errors tab, you can see a detailed list of all errors found during the validation.

The Data on the file tab contains a list of all records in the import file and is particularly useful when searching for errors or just getting an overview of the import.

Note that the Import Resources window is expandable and that you may modify the width of the fields for increased readability.

When you are satisfied with your import file, press the Save button to save your resources.

Note that if errors should exist, Safran will save the valid entries and omit the entries containing errors.

Entries with missing or incorrect Activity ID, Resource, Profile, or VO are considered errors. In contrast, warnings related to resource Lag/Duration are considered valid as the Barchart editor facilities will overrule these.

After the Save operation, Safran informs you of how many resources have been updated/saved.

Legacy import (still supported)

The legacy import format is still supported, and Safran Project will automatically detect your current format.

To import resource information, choose File > Import > Resources

Creating a Resource import file

You can import resources (both QTY and Cost type resources are supported) from a tab-separated text file.

To import resources, you need to create an Activity/Resource matrix with the following format:

The first row is a header row telling Safran which columns/resources are to be imported.

The second and following rows are data rows containing Activity IDs and their relevant resources/quantities/costs.

MS Excel is a practical tool to use when creating import files. The picture below is an example of a simple resource import file.

Your header row should start with the column = an (database field name for Activity ID), followed by resource short names (as defined in Data > Resources).

The quantity/cost may be left empty for one or several columns. The resource - shortname must be an existing Resource definition, and 'an' must be a valid Activity ID in your project.

When you are finished creating your file, remember to select the Text (Tab-delimited) (*.txt) format:

Importing resources

Specify your import file name or browse your computer for files.

The Add to Change drop-down list box provides a selection of variation orders to which the resources and quantities may be added.

Selecting a variation order is mandatory if the current project has the "Lock Scope" property set.

Importing Progress and Expended

Safran Project supports the import of progress (Actual %) and expended QTY/Cost. To do this Safran Project requires a file with the relevant data. Safran Project supports import from tab-separated text files (with or without headers) and XML files. If you use the costing functionality, Safran Project will calculate the Actual Cost based on Cost type and cost rate during import.

Running the import

To import progress, select File > Import > Progress.

1. Browse to your import file and select open. The Progress Import window will now open.
2. Select the current Cut-off or Initiate a new cut-off.
3. Select whether you want to display warnings for Progress and Actual Expended decrease from the previous cut-off.
4. Click read to read the data of the file. The Statistics will now be updated. Any Warnings or Errors will be shown in the corresponding tabs. The data on file can be reviewed in the Data on File tab.
5. Select to Update All Resources or Use Resource Logic on Activity Progress.
6. Choose how to handle the Remaining Duration. (From version 7.3.1)
7. Click Save to Import progress.

When importing progress & expended, Safran Project allows you to define how resource-level progress should be distributed.

For activities with resources without any Resource Duration or Resource delay, the 'Update all Resources' option is the most relevant choice. In this case, entering a progress figure at the activity level would result in Safran entering the exact figure for all the activity's resources.

For activities containing any 'resource logic', i.e. that either resource durations or delays have been specified, the 'Use Resource Logic' is more relevant.

Consider the following:

You have an activity with a 20-day duration containing two resources. Each resource has the same quantity and a duration of 10 days. Additionally, the second resource has a delay of 10 days. After two weeks of work, you find that the activity is 50% complete. You then enter Actual %=50 at the activity level. When using 'Resource Logic', Safran would consider the first resource 100% complete and the second resource 0% complete, thereby honouring the activity's resource logic.

When importing expended quantities at the activity level, Safran will always allocate the quantities on the first resource record entered.

The chosen Resource % Method will also be valid for both the text-based Progress & Expended and the Barchart Editor tools.

Import from a tab-separated text file (with headers)

Safran Project supports the import of progress (Actual %) and expended QTY/Cost from a tab-separated text file with headers.

Supported headers for tab-separated text files are listed below. Please note that the Activity ID column is mandatory, and the column order may be random when using tab-separated text files with headers.

1. Activity ID: "activity id", "an", "activity"
2. Resource: "resource", "res", "resource name"
3. Progress: "actual %", "current progress", "cap"
4. Expended QTY: "actuals", "expended", "actual qty", "expended qty"
5. Expended Cost: "cost", "expended cost", "actual cost"
6. (Current) Actual Start: "actual start", "start", "as", "acs"
7. (Current) Actual Finish: "actual finish", "finish", "af", "acf"
8. Remaining duration: "remaining", "remaining dur", "rem dur", "rdu" *****
9. Remaining work: "remaining work", "rem work", "rwo" *****
10. Change Order: "vo_no", "vo", "change"

***** Remaining work and remaining dur are currently not in use, but headers are reserved for future usage.

Import from a tab-separated text file (without headers)

Safran Project supports the import of progress (Actual %) and expended QTY/Cost from a tab-separated text file** without headers. This file format does not support Expended Cost, Actual Start, Actual Finish, Remaining Duration, Remaining Work, and Change Order.

Using the format below is important, as the column order is locked when using tab-separated text files without headers. Please ensure it is in the following format:

Activity ID tab Resource ID tab Actual Progress tab Actual Man-hours

Import progress from an XML file

The progress file must be a text file with the *.xml file extension.