Professional Documents
Culture Documents
Tilos7 Exchange Manual PDF
Tilos7 Exchange Manual PDF
with
TILOS
Linear Scheduling Software
Exchange Applications
2011-06-01 Primavera API Functionality enhanced for task templates. This is described
in 5.3.
1 Introduction ........................................................................................................... 4
1.1 Basics ............................................................................................................ 4
1.2 Best Practices ................................................................................................ 5
1.3 Scope of exchange ........................................................................................ 6
1.4 The TILOS Exchange Wizard ........................................................................ 8
1.5 XML data exchange schema ......................................................................... 9
2 Installing TILOS Exchange Modules ................................................................. 11
2.1 General ........................................................................................................ 11
2.2 MS Project ................................................................................................... 12
2.3 ASTA Powerproject...................................................................................... 13
2.4 Primavera installation .................................................................................. 14
3 Primavera data Exchange .................................................................................. 30
3.1 Importing data to Primavera ........................................................................ 30
3.2 Exporting Data from Primavera to TILOS XML file. ..................................... 31
3.3 Sample profiles supplied for Primavera ....................................................... 35
4 Profile Editor ....................................................................................................... 37
5 Task data Attributes ........................................................................................... 38
5.1 Task ID and Update criteria ......................................................................... 38
5.2 General task data......................................................................................... 40
5.3 Task Template ............................................................................................. 40
5.4 Calendar ...................................................................................................... 44
5.5 Dates, Duration and constraints .................................................................. 44
5.6 Distance data ............................................................................................... 45
5.7 Category assignments ................................................................................. 47
6 Links ..................................................................................................................... 48
7 Cost and resource data ...................................................................................... 49
7.1 Library data .................................................................................................. 49
7.2 Task planned resources .............................................................................. 50
7.3 Task actual resources .................................................................................. 51
8 Progress .............................................................................................................. 51
8.1 Simple progress exchange .......................................................................... 51
8.2 Advanced progress ...................................................................................... 52
For each of the three options listed below, there is a separate program available to read and
write the files to these applications. This allows you to specify exactly which data should be
exchanged from a project and also the ability to update only a subset is possible without
exchanging all the information .
The Excel exchange module can also read and write multiple objects types (e.g. tasks, links,
allocations), where each data type is stored in an separate Excel data worksheet of a
workbook.
The ASCII exchange works in a similar way to Excel but can only exchange one data type
during import or export.
All data exchange functions are started from the File menu by choosing either Import or
Export. This will then start a four step data exchange wizard designed to assist users with the
exchange process
The XML based data exchange provides a user to exchange a wider set of data between
TILOS and other project management systems (including calendar information).
At the beginning of the project the goal of the data exchange should be clearly defined so that
it is clearly understood where data is updated and where it is imported into. Each application
has it’s own task / link and resource models. The user must be careful to avoid unwanted side
effects that can occur.
TILOS may have enhanced task calculations based on profile data applied to one or more
tasks . The duration for these tasks is then based on calculations using the variable quantity of
work along the project. The result is that the start date can be changed, but not the duration,
as this is based on these calculations.
TILOS can also calculate the lag between tasks based on distance parameters specified by
the planner. These attributes are not supported by any other project management system so
updating a link in TILOS from an external program will reset this option. TILOS translates
these distance based links to normal CPM links when exporting data from TILOS to another
project management system.
A good example might be a highway project with many overpasses. Each overpass is typically
planned with Gantt charts outside TILOS and may be a separate project in MS Project. Making
a master project in MS Project, that includes all these overpass projects, allows the user to
create a simple export run using filters to import all relevant linear tasks to TILOS. The TILOS
exchange module generates world wide unique ID’s (GUID) for these tasks, that make later
updates possible.
This use of unique ID’s makes TILOS very powerful: We do not have to exchange complete
files but rather we can create any subset of data in one system and put this as a subset of
data to the other system. Updating or modifying a task should be done only in one system and
the other gets updated and vice versa.
Another approach is to use TILOS for planning and coordinating the linear work on the site. In
this approach the non-linear (supply chain, with design and maufacturing) is kept in Primavera
(for example). The TILOS plan then creates tasks in Primavera and puts constraints on them
so that they can not be moved. Now the other, non-linear work can be planned around these
tasks.
TILOS can also export the full plan, including cost and resource utilisation for cross project
analysis and portfolio management. TILOS can import a complete schedule With the layout
and task attributes predefined, very little post import editing work is needed. In this case
TILOS is then the time location viewer.
To summarize, it should be clearly defined which application is the leading planning system for
which area and which application is used to edit the data gets.
For each special case a special configuration for the exchange can be done to fullfill the
specific needs. The full integration using API programming or VBA macros leave the rest of
project untouched and replaced data only on demand.
Hammocks
Steps
Links
Micro Progress
Task Templates
For ASCII and Excel these parameters can be set in the exchange dialog in step 3 (left
picture), for XML in the profile editor (right picture).
Using ASCII exchange, the data is copied to the clipboard. For import, the data is taken from
clipboard and export data are copied to the clipboard.
The Excel exchange reads an Excel file on import and generates a new file on export that you
have to save as. Optionally you can select an existing Excel file as a template.
In both of the above options, one of the standard exchange profiles is used.
For XML you need to specify a data file and a profile containing the exchange options.
2 - Define Datasource
For export, after step 4 the exchange file is created or the content is stored in the clipboard.
Now you can start any further application to process the data.
For import, after step 4 the data inside TILOS are updated and you can view the changes.
Before import you should have created an exchange data file or copied the data into the
clipboard.
In Step 3 of the wizard, an exchange profile is defined to specify which objects and which
attributes of each object should be exchanged. For ASCII and Excel, these profiles are stored
in one file in the user area. One file can contain many profiles.
For XML, each profile is stored in a separate file which contains the rules for both of the
programs taking part in the data exchange. To modify the installed XML exchange profiles,
there is a profile editor installed along with the exchange modules.
- Launch application*
(See below)
- Select option: Import
- Set Profile to use
- Set Input file to use
- Select or Create New Project*
(Only for Primavera)
- Import data
- Launch application*
(See below)
- Select option: Export
- Set Profile to use
- Set Input file to use
- Select Project and Filter for export
(Only Primavera)
- Export data
With version 7.0.02, a separate install program is used to install all xml based exchange
programs. This can be downloaded from our web server:
http://tilos.org/fileadmin/downloads/prg/tilos7/Setup-Tilos7-Exchange.exe
Download this program and execute it. It works in the same way as the TILOS installation
program, but you select which modules you want to install on your computer (based on your
license agreement).
Before you install one these exchange programs you should have the master program
installed as well.
For Primavera, java runtime minimum version 6 is needed and the Oracle primavera
integration API needs to be installed and configured. Please check for further
information in the section Primavera (2.4 Primavera)
At the end of the installation with option MS Project checked, then MS Project is started and
the macro installation file is executed. If you did not do that, then you need to do this activation
manually. Double click on that file in installation folder to install or update the macros.
For MS Project 2003 and 2007, a menu entry is created automatically during installation. For
MS Project 2010 you will need to do this manually as described below.
Start ASTA Powerproject afterwards and create a menu entry or an icon for the installed
macro.
3 Drag the sub entry: Main.TILOSExchange either to the Menu or to the toolbar and drop
it there.
For more help, please use the help system of the TILOS exchange function inside ASTA
Powerproject.
The API needs Java Runtime 1.6.x or higher for the Primavera API installation.
You need to download the “Primavera P6 Enterprise Media Pack” in the required version of
your current TILOS installation from www.edelivery.oracle.com or from the support area.
After you entered your name and address data, select what you want to download.
Press continue and you will get the list of downloads for Version 7.
After successful download subtract the zip file and you with get the following files structure:
Click on next.
On the next screen, we are going to select the first option from the list: Local mode.
On the next screen, click on “select all” before you click on next.
After you select all, click next and will bring you to below screen.
On a 64 bit system, this folder might be located in: “C:\Program Files (x86)”
Do not select Java i.e. one level higher (as shown above) since that folder may contain
multiple versions of java and will have more than one folder.
The following screen is automatically started when you execute the API install program. You
may execute this afterwards at any time by double clicking on the file “dbconfig.cmd” in the
API directory.
The next screen will ask what database you are using. Here, we will select MS SQL Server.
Click next and it will take you to the database name and password screen as shown below:
User name and Password: Here you do not enter your Primavera user name, but a
priviledged database user with password. Default values are: User name: privuser and
privuser as password sa with password works also.
If you are not sure what to enter here, startPrimavera and select Help=>Aboutthen select the
system tab.
The Database host address is localhost or the name of your database server.
User name and Password: Here you do not enter your Primavera user name, but a
priviledged database user with password. Default values are: User name: privuser and
privuser as password.
If you are not sure what to enter here, startPrimavera and select Help=>Aboutthen select the
system tab.
The system administrator needs to set this right for each user that wants to connect to the
Primavera database.
If you are not sure about which service pack version of Primavera is installed check the Help /
About information.
For version 7 and 8 the setup detects automatically where the Primavera API is installed. For
Primavera version 6 the API folder can’t be detected by the setup program.
If the API install folder can’t be detected, you need to select this during the installation.
- C:\P6IntegrationAPI
- C:\Program Files\Primavera\P6IntegrationAPI
In some case a _1 or _2 or higher is added if you have multiple versions of the API
installed on your computer.
Press OK to log into your database. The data exchange control panel appears.
Please make sure, that .jar files installed into the API directory are connected with Java
runtime environment. Sometimes other programs set connection.
To check which file is connected, use the right mouse button and check the option Open with
…. Here should Java be listed.
Click on Next and enter your User name and Password. This is your Primavera account.
Please contact your local TILOS support for further information and instructions.
If the sample application is not running, please call your Oracle support for further help.
This error message indicates a version conflict. In most cases it happens, if a Primavera
service pack is installed, but API is not on the same level of patches.
This is due to invalid calendars for activities and is known Oracle problem.
XML profile file: This file contains the settings how to map the data inside the xml data file to
Primavera as well as Program Parameters. You can set the default pathes to use in your
settings. Sample files are delivered along with your installation.
XML data file: This file contains the data to import. This file has to be created first by
exporting your project from TILOS or received this from a colleague.
Click Save settings to store the values about file and path of the profile for the next data
exchange. The defaults can be changed using Edit settings dialog.
After you have selected a Profile and Source file, click on next to select a project.
XML profile file: This file contains the settings how to map the data inside the xml data file to
Primavera as well as Program Parameters. You can set the default pathes to use in your
settings. Sample files are delivered along with your installation.
XML data file: This file you select here will later be filled with the export data. This file is later
needed to import the data into TILOS.
After you have selected a Profile and Source file, click on next and select a project in the
following dialog.
- Select a filter, that you want to apply for your export from the list.
- Use the remove button (red cross) to reset the filter for this export run. It will not delete the
filter.
Each filter can have multiple filter lines that gets evaluated. There are different filter line types.
The type of the filter line gets set, when a new line is created and can not be changed
afterwards.
Activity: This types allows to filter activities. In the edit filter line dialog, you can select a
data field from the list of available data field, select an operator and enter a
value.
You can set more than one activity filter line. They work like “and”.
If you want to apply complex filters also in combination with code and other
Primavera data, we recommend to create inside Primavera a User defined
field with the Name e.g. TilosExport as type text.
Then run inside Primavera a global change which is setting the value:
TilosExport to may TILOS for all tasks you want to export.
Code: This type allows to filter codes. For each Code library you want to export, one
filter line has to be created. The codes are exported in TILOS to Categories. In
the field value enter the name of the code library you want to export. The
fields Property and Operator are not used. Only those codes get exported
which are listed within the filter list. By default no Codes are exported
unless they are in the filter list.
Resource: Resources can be filtered in the same way as tasks can be filtered. By this
you can select, which items of the resource library should be exchanged.
The operator “Between” need 2 values to be set. Those get separated with the keyword and.
To select Planned Start Date between 2 values, you should enter in the field value: 2010-04-
01 and 2010-05-01. This takes all tasks that start between this 2 dates.
Date entries have to be done in fixed format: YYYY-MM-DD, this means year always in 4
digits, month in 2 digits and day also in 2 digits. The separator is always a "-".
Calendar: Calendars are enabled in all profiles supplied. They are exchanged in a fixed
way. The length of the name is restricted to the TILOS calendar name length of
32 characters. All longer names will be truncated.
Only those calendars are exported, which are used by tasks which are
exported. Others were skipped.
Holiday are only exchanged for the duration of the project plus 2 years. This
reduced the number of exceptions.
Day name are generated in TILOS. They refers to the 30 minutes working / non-
working patterns. The name is there for 48 characters long and has 0 for
working and 1 for non-working. These names can’t be edited in TILOS.
Codes Code libraries are only exported, when they are nominated in the filters. This
reversed filter protects from exchanging unneeded data (see filters).
Codes can also be mapped with TILOS task template or other information.
How to identify the correct code library: TILOS first looks if there is a project
code library with the matching name on import. If it does not exist, then a it
looks for a global library with that name. If it does not exist, then a project code
library is created.
On Export, if there is a global and project library with the same name, then an
error is produced as we have no unique names.
Resources If you exchange resource assignments and library resources, then only those
resources are exchanged, that are used inside the project. All others are
skipped. The same is for units.
This profile enables the simplest data exchange, just tasks and no links. Calendars are also
exchanged. The TILOS start and end location data are stored within 2 user defined fields:
TILOSStartLoc and TILOSEndLoc.
The task template name is mapped to a code library named Work Type. If on import this does
not exist, it is created and the values are assigned. Code value is generated from the first 20
characters of task template name.
Using the exchange in both directions calendars should only go in one direction.
During installation of TILOS Exchange, the profiles for the specified links are added to the
TILOS data area. For Windows 7 the common data folder is: “C:\ProgramData\” for Windows
XP: “C:\Documents and Settings\All Users\”.
If you run the profile editor, then it prompts normally with this directory using a standard TILOS
installation.
You may change default directors of the profile locations inside TILOS in the settings area.
(Tools / Options tab Configuration).
However in TILOS and the exchange module, the last used profile and data file is stored with
the program.
For further information how to edit profiles, please check the help system of the profile editor.
In all exchange data sets there is a field called Task-Identifier. This controls how data are
identified during import. This field needs to be part of each exchange run and is added to each
new exchange profile by default.
For XML:UID
and the attribute controlling the content is set in the profile editor.:
TASK-ID: The field “Task-ID” of TILOS is used to identify the task. During import, if a
task with that TASK-ID is not found then a new task is created and the
content of UID field is set to Task-ID value.
GUID The GUID (Global Unique ID) field is a simple text field assigned to each
task inside TILOS. If the exchange options are based on GUID (rather than
Task-ID), then the following rules apply:
- If content of UID does not match with any GUID of TILOS, a new task is
created. This gets the imported GUID value assigned. A new TASK-ID is
generated and assigned to this task.
- User has full control of those fields, he can overwrite this at any time, but
this might affect future updates.
The GUID field of TILOS can be made visible in the task general tab in the
section other attributes.
Our recommendation is to use the TASK-ID for either the ASCII or Excel based exchange as
this is simple to read. XML based exchanges should use the GUID technology.
For Primavera having no summary tasks, the ParentUID field is not supported.
XML
Setting a template name during import reduces the editing effort afterwards a lot. The import
field used to reference the TilosTaskTemplate can be either the Task Template ID or the Task
Template Name.
If the imported template does not exist, then a new entry is generated at the root level. If the
attributes of this template are edited and the button Adjust Task to Task Template is pressed
in the Task Template library, all tasks will be updated to the new settings.
You need to add either Task Template Name or Task Template ID to your exchange profile.
For import you should have only one set.
The XML based data exchange provides more options, which can be set in the profile editor.
The easiest way of defining the task template name is to set a text field containing the names.
For Primavera and ASTA you need to create a udf then.
Inside the profile editor you need to link TILOS template with this user defined field.
Change the entry as in picture above: udftext: followed by the name of the udf created.
This works the same for ASTA. For MS Project just select one of the free text fields you used.
TILOS:
The whole task library can be exported. Check the options in the line Task Templates exports
or imports the whole task library.
Further attributes for task templates are exported based on the definition of the task object.
Primavera
If you check the Task Templates object for export in a primavera designed for Primavera, then
the exchange module will fill the tasks templates object.
It takes that code library, that is used to fill the XML tag TaskTemplateUID or
TaskTemplateName in combination with the function setCodeAssignmentEntry… on task
level.
ASTA Powerproject
The ASTA VBA can’t access the TaskTemplate object. However on exporting the data from
TILOS to XML, the TILOS parameter Export task template as category (in the XML profile
editor) forces TILOS to export the task template library as a category library. The name of that
category is set in the parameter Name of Category for Templates. This allows to the user to
export the TILOS template library to ASTA Powerproject code libraries for subsequent use in
filters.
Enabling these options in the XML profile editor, TILOS will exchange the task template
library. You can set structure by adding parent UID to the exchange scope. CopyUID defines
from which template the annotation should be copied, if a new template is generated.
On import, although the name of calendars and the definitions are the same, the calendar
might look different. This is because generated day time types are used, as MSP and P6 have
different definition sets.
The UID length has been expanded from 25 to 32 characters and now has the same length as
the field name.
If CalendarID = Name and Name is changed, then CalendarID is always set to name.
As most other programs do not have a UID assigned to a calendar, the calendar name can
easily be used as the mapping criteria.
Day definitions names, that are imported from others applications have a special names
generated from the working shifts.
For ASTA Powerproject it starts with PP-. The names of imported day definitions can’t be
changed in TILOS. Day definitions are built from working time defined by work pattern overlaid
by the exception of that day. On Export, for each day an exception is generated.
DD for day
MM for month
hh for hours and nn for minutes. The separator between hours and minutes is “:”.
Sample: dd.mm.yyyy hh:nn AM/PM will export “31.01.2011 8:00 AM” or “02.03.2011 1:00
PM” but on import am and pm will also be recognized.
Durations are always interpreted in display time unit active for that project.
XML used always internal date format supplying time information, durations are in minutes.
For ASTA Powerproject make sure, that in Tools / Options the setting for tasks date changes
is set to Change duration.
Distance unit name Enter the name of the distance unit, that should be used to convert
imported distance values. If not set, then the default is used.
Use equation Enter Yes / No to define whether an equation created by you is used
to define the coordinates.
For ASC and text based imports the unit that is expected for distance data is the same as the
default unit set in TILOS settings.
For XML based imports, the distance values are always expected to be in numeric in base
values. This is that distance unit, where factor = 1. So, there have always to be numeric
values.
In the delivered profiles, we use always numeric fields for the distance units:
If you are entering the data inside MS Project in Km with decimal values and TILOS base unit
is m, you can apply a factor to convert the values.
The following setting for the distance start and end value are done for the case, that you you
have in Primavera e.g. km. In the TILOS factor field we enter the value 1000. This multiplies
during import e.g. 17.500 km to 17500 m. On export the value is converted back to 17.5 by
division.
It is very important is to set the name of the category that you want to export in the field Extra
Parameter. In the picture above, column 7 will export the path of the category assignment for
the category “Companies”.
In order to support multiple levels inside a category, the path has to be supported using a “.”
as separator between the levels.
If there are multiple assignments of the same category to a task, only the first is exported.
XML
XML works in a similar manner but there is an additional option to use the sub entry of tasks:
Category assignment. This allows the user to transfer as many assignments as required.
This way of exchanging categories works well for Primavera, where we build the code libraries
and the code assignments and also for ASTA Powerproject Codes.
However, for Primavera only those codes are exported that are explicit nominated in the filter
definition for the export.
Lag type Working = Working time and Elapsed means calendar time.
All the other link attributes and settings can also be exchanged if required.
To select the following exchange options, run the XML exchange module and edit the
parameters for TILOS as shown below:
Export links to not exported sub-projects: Check this box to export even those links that are
related to any other Sub-Project that is not in
export scope (see also Task Links).
Delete not updated local links: If this option is set, all remaining not updated
Local Links during import get deleted after import.
Delete not updated external links: Same as above, but for External Links.
Support TILOS link attributes Yes means that any additional TILOS link
attribute, if defined in a profile, are exported.
The identification for update is always controlled by the ID fields for each type of library data
(i.e., Acount-ID for Accounts). If an item already exists it is updated. Each item is represented
by one line, the data fields can be separated by tab or any other specified field.
Categories
Eg. Path: Pre work.Clearing is translated in TILOS to main entry Pre work and sub item
Clearing.
Distance and time profiles can be exchanged directly from the edit dialog of the profiles in the
library section. This sets automatically the profile to which the data are exported or imported.
Task-Identifier This field is required to identify the task to which resource data
should be assigned to. (See 5.1)
AccountID This defines the account to which the costs are allocated.
Setting the parameter “Resource import mode” in the TILOS application parameters dialog box
in the XML profile editor
In this mode, only simple resource values are exchanged and not the advanced models from
TILOS. This allows a simple exchange of resource data with other programs. The following
data fields are evaluated:
Quantity This value contain the total consumption or effort of the resource.
Each cost record gets a time stamp, at which day / time the costs should be booked.
8 Progress
In order to monitor detailed progress, different models apply leading to a split of the tasks. The
split can be done based on distance or quantity but also reflecting both: A certain quantiity is
performed between 2 points having nonlinear quantity profiles.
To be sure, that all imported tasks are set to Percentage (simple) , it should be pre-defined in
the TILOS task template that is used.
Should be always set true. Assuming that the task has been split based on progress entry,this
option forces TILOS to work in the following way:
It analyzes which part belongs to the previous planning task in the progress group. It
calculates earliest start and latest end for the data export and calculates the % progress based
on the progress rules set in the task.
On import, the 1:n relation from planning tasks to actual makes updating difficult. Therefore an
option was introduced. If set true, then already progressed tasks will be skipped on import.
NOTE: this is strongly recommended if tasks in TILOS are split based on progress situation.
This method allows you to import daily progress, but apply this in weekly or even monthly
periods. Entering data directly in TILOS works the same as importing just one record, this
mean no direct evaluation is done.
Depending on the progress model, different data fields are analyze in step 2 for checking and
applying progress.
The identification, to which task the micro progress applies is based the field Import-Key, that
can be set in Options / Progress tab.
From one task e.g. with Task-ID A-0010, many sub tasks are
created based on progress split. Each completed section is
represented as a separate task. Those have the extension “-
001” and higher assigned. On import, TILOS checks, how
many tasks exist with the leading TASKID A-0010 and assigns
that task, with best matching distance coordinates.
Work Break Down structure Same as above, but now WBS field is used to connect the
progress data with task field. This allows you to assign for a
special crew a WBS code and plan many tasks inside the
project with same WBS code.
Import key The field refers to the setting of the import key.
UID Each import record can have a UID field. This is used for
updating already imported records. Applied record can no
longer be updated.
Quantity This field gets only evaluated for the model: Quantity simple
or Quantity (split task). In all other cases this value will be
ignored.
Start / End date This fields describe start and end of working period, in which
progress has been applied. For simple mode, only the start
date of first progress entry is used to set the start date of the
task and max end date is later used, when task gets finished.
Start and end distance This values get only evaluated for those models having (split)
as part of the name.
After the import, the micro progress record are shown in the Micro Progress tab of the task or
in the view context in the Microprogress tab.
In this context you can view all imported progress segments and filter them in different ways:
Filter only not evaluate This shows only new imported or created.
Filter conflicts This shows only segments, where conflict flag is set.