1. INTRODUCTION
The import/export tool in E3 Studio allows you to record CSV files containing information about the objects in Elipse E3, and later use it to create new objects via templates. The information in the file include properties, links, and object collections.
The new Elipse E3’s import/export process has worked since version 2.5, and is now template-based. Templates are INI files (Windows’s initialization files) we use for setting up the import/export tool. With them, you can define items such as the columns separator that will be employed in the CSV file, its columns, etc. Some templates come with Elipse E3’s latest installation, but you can also create templates that are tailored for your application’s specific needs.
In this article, we will show you how to create templates for every situation, as well as usage tips for benefiting from all features in this tool.
2. UNDERSTANDING TEMPLATE STRUCTURE
Although they are text files, templates should abide by a certain structure so that they can be read by the import/export tool. This structure is the same you will use for Windows’s initialization files (INI). These files organization comes in sections; later, you will be able to set up the variables in these sections individually. For example, you can find the Separator variable in the Configuration section; this variable sets up the type of columns separator to be used.
The code below
[Configuration] Separator=','
means you’ll have to use a comma as the CSV file separator.
2.1 INI files format
Usually, INI files follow this format:
- The file is organized into sections, and each section will then contain one or more variables. Their names are identified by a name between brackets.
- Variables are any words before the “=” symbol. Therefore, a section cannot contain two variables with the same name.
- Likewise, blank lines are ignored.
- The text following the “;” character is considered as a comment, and consequently disregarded in the file interpretation.
They are user-friendly, which means the user will be able to edit it easily. You can write a template with a regular text editor, or base it on an old template, or even start one from scratch.
The templates used in Elipse E3 allow establishing new names for the CSV file columns, as well as other types of objects. Besides, they also allow grouping multiple properties onto the same column. This can be done by setting up identifiers, which are keywords used in the CSV file and associated to properties or classes in the INI file.
At E3 Studio, you can set up the import/export templates with the sections and variables presented below. Some of them are mandatory for export, and will be indicated as such in the text, but for the import process, they are all optional. If you omit them, Elipse E3 will them assume the default standard.
[Header]
In this section, you can establish all the allowed identifiers for column names and object types; likewise, you can also establish the order of the CSV file columns while exporting. This section is mandatory for export, and the defined variables are:
header: In this variable, you must list all columns, separated by a comma and in the order they should be displayed in the CSV file. If the column name is not the same as the property, use a identifier in the header variable and then link it to the property’s real name via a variable in the [Columns] section. This variable is mandatory for the export process.
types: Establishes the identifiers for the object types allowed in the CSV file. You must list all identifiers in this variable separated by commas. Set up this variable if any identifier is different from the object’s class name. In this case, there must be a variable for every identifier in the [Types] section.
[Header] header=ObjectType,Name,DocString,N1/B1,N2/B2,N3/B3,N4/B4,Scan,AllowRead types=Tag,Bloco,Elemento
[Configuration]
In this section, you can establish the tool’s general configurations. The defined variables are:
separator: Establishes the separator that will separate columns in the CSV files.
root: Establishes whether the root object (from where the import/export was called) is also imported/exported with its children objects. This option is available from version 2.5 on; previously, the root object (I/O Driver or Alarms Area) could not be exported. In the import process, the root object won’t be created, only its properties are updated.
link: Establishes if you will import/export the object’s associations. The tool’s latest version allows these associations to be exported to the CSV file and then imported to new E3 objects. For the export process, a new line is added to the CSV file per association, identifying its type; an extra column is created for each property in the association. For the import process, each identified line generates an association in the corresponding property.
collection: Establishes if you will import/export objects collection; likewise, properties in the collections generate new columns in the file. For the import process, you can’t create a collection, only edit properties values. So, the collection must have been already created in the object before you start importing.
objectduplicated: Establishes the object’s behavior when you import another object of the same name: overwrite the older object, create a new object with a new name, or keep the existing object.
bindduplicated: Establishes if you should replace an old association with a newer one when it already exists in a previously imported property.
[Configuration] separator=',' root=true link=true collection=true objectduplicated=askalways bindduplicated=askalways
[Types]
In this section, the object type identifiers relate to the actual classes. All identifiers listed in the section’s types variable [Header] that are not equal to an E3 object’s class name should be in the section’s documentation. Each identifier has a variable in format = .
[Types] Tag=IOTag Bloco=IOBlock Elemento=IOBlockElement
[Columns]
In this section, the columns name identifiers relate to the properties names. All identifiers listed in the section’s header variable [Header] that are not equal to a property name should be in the section’s documentation. Each identifier has a variable in format = .
[Columns] N1/B1=N1,B1 N2/B2=N2,B2 N3/B3=N3,B3 N4/B4=N4,B4
[Filter]
In this section, you will establish object classes for import/export. Only one of the following variables can go at a time.
include: Lists the E3 object classes for import/export. When this variable is defined, only the classes in this list will be imported/exported.
exclude: Lists the E3 object classes forbidden from import/export. When this variable is defined, all classes except this one are imported/exported.
[Filter] exclude=IOFolder ; importa/exporta tudo, exceto IOFolders
TEMPLATE EXAMPLE:
[Header] header=ObjectType,Name,DocString,N1/B1,N2/B2,N3/B3,N4/B4,Scan,AllowRead types=Tag,Bloco,Elemento[Configuration] separator=',' ; utiliza a vírgula como separador de colunas no CSV root=true ; exporta/importa o objeto-raiz link=true ; exporta/importa as associações collection=true ; exporta/importa as coleções ; sempre pergunta o que fazer quando encontrar um objeto duplicado objectduplicated=askalways ; sempre pergunta o que fazer quando encontrar uma associação duplicada bindduplicated=askalways[Types] Tag=IOTag ; Tag na coluna ObjectType significa objeto da classe IOTag Bloco=IOBlock Elemento=IOBlockElement[Columns] ; N1/B1 como nome de coluna significa uma das duas propriedades: N1 ou B1 N1/B1=N1,B1 N2/B2=N2,B2 N3/B3=N3,B3 N4/B4=N4,B4[Filter] exclude=IOFolder ; importa/exporta tudo, exceto IOFolders
3. CREATING A TEMPLATE
You can create a template not only via text editor, but also with Elipse E3’s Template Manager. The first option requires knowledge about template structure (as seen in the previous chapter); the Template Manager, on the other hand, features an interface that facilitates the configuration of the desired options.
3.1. Creating a simple template via text editor
In this case, you must follow some ground rules:
- Section names must necessary come between brackets and be isolated on their own row.
- The system does not differentiate between lower and upper cases for section and variables names and other values. Since no two variables with the same name are allowed in a section, upper and lower cases can’t help telling sections and variables apart.
- Blanks are ignored around the = signal, but they count around commas separating values in the same variable.
For example, this snippet
[Header] Header=ObjectType, Name
means the column’s name is Name, with a blank space at the beginning. Since this is not considered a property’s name, it will be handled as an identifier. If this variable does not relate to the right property, the column will be disregarded. To keep this from happening, the correct snippet should be
[Header] Header=ObjectType, Name [Columns] Name = Name
(with a blank space before the variable) or
[Header]
Header=ObjectType,Name
(without a blank space around the comma).
- The ; character cannot be used as part of the identifier’s name, because in templates, this character means the beginning of a comment. Therefore, the file interpretation will stop in this character, and everything after that is disregarded.
For example, this snippet
[Header] Header=ObjectType,Na;me,DocString,Value
reads only up until the first half of the Name variable and disregards everything that comes after that. That means that the actual value for header variable reads “ObjectType,Na”.
- Blank rows are ignored when interpreting the file, therefore you can feel free to use them as much as you need them to organize the template visually.
- Import/export operations won’t fail even if a section or variable is incorrect (exceptions: [Header] section or header variable for export), because variables assume a default value when not defined. As a result, if the operation’s execution has failed, we suggest checking the variables names in the template.
3.2. Creating a template via E3 Studio’s Template Manager
In order to use Elipse E3’s Template Manager, you will first need to click the Import/Export option; once the window opens, then click Configure. Set up all the options available in the tabs below, and to finish the operation click OK.
a) Settings tab
On this tab, you will set up the valid options for import/export, such as columns separator, template name, etc.
b) Import tab
On this tab, you will set up the valid options for import only, such as what to do with duplicated objects or links.
c) Filters tab
On this tab, you will set up the classes you want to import or not, via Change button.
d) Identifiers tab
On this tab, you will set up the identifiers for object classes. Filling it is optional, unless you need to import/export a class with an identifier instead of the name.
e) Properties tab
On this tab, you will list the properties for the import/export process. In case of export, the list should be in the correct order, and filling it is mandatory.
In case of import, the order comes from the configuration in the CSV file and not from the template. Fill out this list only when a column uses an identifier instead of a property. This is also where you can set up two or more properties to be grouped into a single column.
4. USAGE TIPS
4.1. Columns separator
The foundation of a CSV file are its columns. In order to identify them correctly, you will need to make sure the columns separator is the same both for import and for export. To do so, an option is to use the list separator used in Windows, which is at Start–Settings–Control Panel–Customize Regional Options.
Since this configuration may vary between computers, you will need to make sure the same separator was used not only for generating the CSV file but also for importing it.
Another possibility is to set up the columns separator manually via Separator variable, in the template’s [Configuration] section. In this case, the configuration is part of the template, and all you need to do is use the same template for import and export to make sure the separator is properly configured.
4.2. Grouping columns for a more versatile file
Sometimes, different objects with no properties in common are exported in the same CSV file, which will generate a great number of blank columns. For example, I/O tags display properties from N1 to N4; I/O blocks, on the other hand, have B1-B4 properties, but not N1-N4. A CSV file with both I/O tags and I/O blocks at first would look like this:
ObjectType;Name ;N1;N2;N3;N4;B1;B2;B3;B4 IOTag ;Tag1 ;1 ;1 ;1 ;1 ; ; ; ; IOBlock ;Bloco1; ; ; ; ;1 ;1 ;1 ;1
However, you can reduce this file to only six columns if N1-N4 properties are grouped with B1-B4. This is possible because objects either display one type of these properties or the other, never both. But notice this: if grouped properties are common to more than one type of object in the import/export process, you will have to deal with information loss, because one property’s value will overwrite the others.
In order to group these properties, you just need to select them, click Group properties, and then edit the column’s name.
The template generated in this example will look like the one below:
ObjectType;Name ;N1/B1;N2/B2;N3/B3;N4/B4 IOTag ;Tag1 ;1 ;1 ;1 ;1 IOBlock ;Bloco1;1 ;1 ;1 ;1
4.3. Importing files generated by Elipse SCADA
Elipse SCADA can export its tags, screens, and alarms to E2F files, and Elipse E3 can easily import them with no need for a template. But first, you must notice some things:
- I/O tags or OPC tags must be imported from the same I/O driver or OPC driver, respectively, with the same name as the Elipse SCADA’s drivers, so that tag references are imported correctly.
- RAM and Demo tags must be imported in Elipse E3 via a data server called “Data”; this will guarantee the tag references are correct.
- When Elipse SCADA exports tags, it also creates a E2F file with _Alarms suffix, which contains the alarms configuration. After that, in Elipse E3, the alarms are imported from an area previously created inside the AlarmConfig. If the tags were properly imported from Elipse SCADA, they’ll display their names in blue, which indicates the link is working correctly.
- Before importing screens from Elipse SCADA to Elipse E3 for the first time, you will need to register the ActiveX controls of E2Controls at E3 Studio. To do so, access Tools–Add ActiveX, select one of the controls at the E2Controls library, and then click OK.
4.4. Keeping a basic template for every object
To facilitate the tool’s configuration and save time during this procedure, try to keep a pre-designed template for each frequently imported/exported objects, such as drivers, alarms, screens, etc. These templates can contain, for example, all properties you will need to use as well as the desired objects.
So, whenever you start a new import/export process, you will only need to select a basic template and click Configure so that all the settings from this template be loaded. At the option Save the changes in this template in an INI file, choose a new name for the template, so the basic one won’t be overwritten, and make only the necessary changes.
4.5. Importing tag files generated by earlier versions of E3 Studio
The format of the CSV files generated by exporting older versions of Elipse E3 is also supported by the current tool. The proper template for this operation is available in Elipse E3’s installation directory, Templates folder.
In order to set up a new template, follow these procedures:
a. On Settings tab: firstly, select the Windows list separator as your columns separator; then, disable import/export root object options; finally, choose a new name for the template.
b. Then, on Import tab, keep the default configuration.
c. On Filters tab, select Add only these objects and then click Change to include the following classes: IOTag, IOBlock, and IOBlockElement.
d. On Identifiers tab, click (+) in order to add the IOTag, IOBlock and IOBlockElement classes, then set up the identifiers PLC Tag, Block Tag andElement, respectively.
e. On Properties tab, set up the properties to be exported by the older version and then associate them to the identifiers used in the CSV file. As for ObjectType property, link it to type identifier. For the others, follow the instructions below:
- First of all, click (+) to add the properties.
- Then, select IOTag class and add Name, DocString, N1, N2, N3, N4, Scan, AllowRead, AllowWrite, EnableScaling, DeviceLow, DeviceHigh, EULow, EUHigh, ParamDevice and ParamItem properties.
- After that, select IOBlock class and add B1, B2, B3, B4 and Size properties.
- Select IOBlockElement class and add Index property.
- Select N1 to N4 and B1 to B4 properties in pairs and click Group properties. Then, change the name of the columns (N1/B1, N2/B2, N3/B3 and N4/B4).
- Finally, change the name of the columns for the following properties: DocString = Description; Scan = ScanTime; AdviseType = Advise; EnableScaling = Scaling; EUHigh = High2.
f. Click OK.
[HEADER] Header=Type,Name,Description,N1/B1,N2/B2,N3/B3,N4/B4,ScanTime,AllowRead, AllowWrite,Advise,Scaling,DeviceLow,DeviceHigh,EULow,EUHigh,EU,Size, Index,ParamDevice,ParamItem Types=Element,Block Tag,PLC Tag[TYPES]Element=IOBlockElement Block Tag=IOBlock PLC Tag=IOTag[COLUMNS] N1/B1=N1,B1 N2/B2=N2,B2 N3/B3=N3,B3 N4/B4=N4,B4 Scaling=EnableScaling ScanTime=Scan Type=ObjectType Advise=AdviseType Description=DocString[CONFIGURATION] Root=FALSE Link=FALSE Collection=FALSE ObjectDuplicated=AskAlways BindDuplicated=AskAlways[FILTER] Include=IOTag,IOBlock,IOBlockElement
4.6. Editing object types in four easy steps
With Elipse E3’s new import/export tool, you can change object types without compromising already configured properties. This can be done in four easy steps:
a. Firstly, export the objects whose types you intend to change, thus creating a template with all these properties. In the example, we will export all children objects from InitialScreen. Thus, in the templates configuration, we included all properties from DrawRect class, and created an identifier on Identifiers tab at the Template Manager.
b. After that, change the object type in the export template. In the example, DrawRect was replaced with DrawCircle directly at the variable value. Save the template.
c. Then, delete old objects at Elipse E3. In the example, we removed the four rectangles on InitialScreen.
d. Finally, import the objects in the CSV file that were generated at a via a template changed at b. In the example, we created four new circles that keep the properties set up for the rectangles, such as color, position, size, etc.
However, this procedure is only helpful in cases when the objects being transformed share a great number of properties; otherwise, this alternative is not the most indicated.
A good example of when to use this feature is if you lose a library with several XControls from a Screen. If you know the meaning of the properties set up for the XControl, you can not only create a new library but also redefine the ElipseX and, following this procedure, replace the old ElipseX with new ones on the Screen.
