Elipse Knowledgebase



Creating templates for E3 Studio’s import/export tool

1) Introduction

E3 Studio's import/export tool allows users to record a CSV file with new information about E3's objects, and to use it later to create new objects. The information recorded in the file includes properties, links, and collections.

Import/export process was reformulated for E3's 2.5 version, and it is now template-based. Templates are INI files (Windows initialization files) used to configure the import/export tool. With these templates you can specify which column separator will be used in the CSV, which columns will be displayed in the file, etc. Some templates are provided by Elipse Software alongside the installation of E3's new version, but it is also possible to create templates that are specific for each user's needs.

Throughout this article, instructions on how to create appropriate templates for each situation will be presented, as well as tips on how to enjoy this tool's functionalities.

2) Understanding templates structure

Although templates are text files, they should respect a certain structure to be understood by the import/export tool. This structure is the same as the one found in Windows initialization files (INI). These files are organized into sections, and in each one of these sections it is possible to define variables for what you need to configure. For instance, in Configuration section, you will find Separator variable, which defines the column separator to be used.

The excerpt below

[Configuration]
Separator=’,’ 
means that a comma will be used as the CSV file's column separator.

INI files, as a general rule, follow this format:

  • The file is organized into sections, and each section contains one or more variables. Sections are identified by names between brackets ( [ ] ).
  • Variables are the words before the symbol '='. A section cannot contain two variables with the same name.
  • Blank lines are ignored.
  • The text following a ';' is considered to be a commentary, and it is not considered in the file's interpretation.


Its format is a text that presents its information in a highly organized manner, which makes it user-friendly and easy to understand and to alter. It is possible to generate a new template from scratch or from an older template, and you will only need a common text editor to do so.

The templates used in E3 allow you to redefine values for the names of the columns in the CSV file, as well as the names for the object types. In addition to that, they also allow you to group more than one property in the same column. This is all accomplished by the identifiers, which are keywords used in the CSV file and associated to properties or classes in the INI file.

In E3, the templates of the import/export tool must be defined with the sections and variables presented next. Some are mandatory for export, and will be indicated as such in the text; as for import, they are all optional. If they are omitted, E3 will assume the default behavior.


[Header]

In this section, you must define which identifiers are allowed for column names and object types, as well as which order the columns will take in the CSV file, in case of export. This is a mandatory section for export, and the defined variables are:

header: in this variable, you must list all columns, separated by commas, and in the order they should appear in the CSV file. If the column's name is not the same as a property's name, you must use an identifier in header variable, and its connection to the property's actual name must be done through a variable in [Columns] section. This variable (header) is mandatory in the export process.

types: defines the identifiers for the object types allowed in the CSV file. The identifiers must be separated by commas when listed in this variable. You only need to define this variable if there is an identifier different from the name of the object's class. In this case, for each one there should also be a variable in [Types] section.

[Header]
header=ObjectType,Name,DocString,N1/B1,N2/B2,N3/B3,N4/B4,Scan,AllowRead
types=Tag,Block,Element 



[Configuration]

In this section, you must define the tool's general configurations. This section's variables are:

separator: defines the type of separator used between columns in the CSV file.

root: defines whether the root-object (object where the import/export option was called) will be imported or exported alongside its child-objects. This is option is new for this version of the tool, because in its older version the root-object (I/O Driver or Alarm Area) was never exported. As for import, the root-object is not created, only its properties will be updated.

link: defines whether object's links will be imported or exported. Now, it is possible to export the links defined in the objects to the CSV file, and then to import them to new objects in E3. When exporting, for each link a new line is added in the CSV file, identifying the link type; for each property of the link, a new column is created in the file. When importing, for each line identified, a new link is generated in the corresponding property.

collection: defines whether object collections are imported or exported. Collections can be exported, generating each a line in the CSV file. Likewise, collections properties generate new columns in the file. However, it is not possible to create collections when importing, only to alter the value of properties. So, it is necessary that the collection be previously created in the object, and only then to perform the import operation.

objectduplicated: indicates how to behave when an object carrying the same name as an already existing object is imported. You should define whether the older object must be overwritten, if the new object must be renamed, or if the existing object must be kept.

bindduplicated: defines how to behave when a link is imported to a property that already has one. You should define whether the old link must be replaced by the new one or not.

[Configuration]
separator=','
root=true
link=true
collection=true
objectduplicated=askalways
bindduplicated=askalways 



[Types]

In this section, you must connect object types identifiers to actual classes. Each identifier listed under types variable, in [Header] section, and which is not the same as the name of one of E3's object classes, must be documented in this section. A new variable will be created for each identifier, in the format <identifier> = <class name>.

[Types]
Tag=IOTag
Block=IOBlock
Element=IOBlockElement 



[Columns]

In this section, you must connect column names identifiers to property names. Each identifier listed under header variable, in [Header] section, and which is not the same as a property's name, must be documented in this section. A new variable will be created for each identifier, in the format <identifier> = <property name>

[Columns]
N1/B1=N1,B1
N2/B2=N2,B2
N3/B3=N3,B3
N4/B4=N4,B4 



[Filter]

In this section, you must define which object classes will be imported or exported. Variables in this section are displayed below. Only one of these two can be defines, not both at the same time.

include: in this variable, you must list all classes of objects in E3 that can be imported or exported. When you define this variable, it means that only classes here are to be imported or exported.

exclude: in this variable, you must list all classes of objects in E3 that cannot be imported or exported. When you define this variable, it means that all classes are to be imported or exported, with the exception of the ones listed here.

[Filter]
exclude=IOFolder ; imports/exports everything, except IOFolders 


Below, there is a complete, commented example of a template.

[Header]
header=ObjectType,Name,DocString,N1/B1,N2/B2,N3/B3,N4/B4,Scan,AllowRead
types=Tag,Block,Element

[Configuration]
separator=',' ; uses a comma as a column separator in the CSV
root=true ; exports/imports the root-object
link=true ; exports/imports links
collection=true ; exports/imports collections
; always asks what to do when there is a duplicated object
objectduplicated=askalways
; always asks what to do when there is a duplicated link
bindduplicated=askalways

[Types]
Tag=IOTag ; Tag on ObjectType column means object from IOTag class
Block=IOBlock
Element=IOBlockElement

[Columns]
; N1/B1 as column names means one of the following properties: N1 or B1
N1/B1=N1,B1
N2/B2=N2,B2
N3/B3=N3,B3
N4/B4=N4,B4

[Filter]
exclude=IOFolder ; imports/exports everything, except IOFolders 



3) Creating a template

There are two ways you can create a template: from a common text editor, or using E3's Template Manager. For the first option, you have to know the template's structure, which was presented in the previous section. For the second, an easily configurable interface will be presented. Both options are presented below.


Creating a simple template from a text editor

To create a template from a text editor you must be familiar with E3's templates structure, to know which sections and variables must be defined and to ensure template's structure is correct.

You can use any text editor for this purpose (such as Notepad), but you must follow some rules.

  • Section names must necessarily be between brackets and stand alone in the row.
  • There is no difference between uppercase and lowercase, be it for section and variable names as well as for values. This means that, since no two variables with the same name are allowed for a given section, the use of uppercase or lowercase to differentiate them is not enough.
  • Blank spaces surronding '=' are not considered, but blank spaces surrounding the commas separating the values in the same variable are. For example,

[Header]
header=ObjectType, Name 
means the name of the column is "Name", with a blank space in the beginning. Since this is not considered a property's name, it will be dealt with as an identifier. If there is no definition for "Name" variable, connecting it to the correct property, the column will not be considered. The correct way to it is as displayed below:
[Header]
header=ObjectType, Name
[Columns]
Name = Name ; Noticee the blank space before the variable 

or

[Header]
header=ObjectType,Name ; no space around the comma 

  •  The character ';' cannot be used as part of an identifier's name, because it characterizes the beginning of a comment in a template. The template is interpreted up until the point where there is a ';' and nothing after that is considered. For example:

[Header]
header=ObjectType,Na;me,DocString,Value
[Columns]
Na;me = Name 

When reading header variable, the ';' in the middle of "Name" makes neither "Na;me" column, nor the next columns (DocString and Value) be considered. The value effectively read for header variable is "ObjectType,Na"

In addition to that, some important tips are shared below.

  • Blank lines are ignored when interpreting the file. So, you can use them as much as you want to organize your template better.
  • Even when a section or a variable are written incorrectly, import/export operations are not going to fail (except if [Header] section or header variable are incorrect when exporting). Variables have default values, which are assumed when they are not defined. So, when the operation is not executed as expected, you should check to see how variables were written in the template.



Creating a template from E3 Studio's Template Manager

To use E3's Template Manager, just click on the option Import/Export, and once the options window is open, click on the button [Configure...]. The tabs available for configuration are displayed below. To finish creating a template, just click [OK], on any tab.


Settings tab

On this tab, you can set valid options both for import and export. These options include configuring the column separator; configuring import/export of root-object, links, and collections; and defining template's name, in case you wish to save it to re-use it.


Picture 1: Settings tab


Import tab

On this tab, you can set valid options for import only, such as the behavior the template should adopt for importing a duplicated object or link.


Picture 2: Import tab


Filters tab

On this tab, you can define which object types must be imported and which ones must not. Object types list is filled by pressing [Change...] button.


Picture 3: Filters tab


Identifiers tab

On this tab, you can define identifiers for object types. Filling this tab is not mandatory; use it only if you need to import or export some object type using an identifier instead of its actual name.


Picture 4: Identifiers tab


Properties tab

On this tab, you can list all properties to be imported or exported. The properties must be displayed in the exact order they are to be exported. In case of import, however, the order is defined by the CSV file, and not by the template. Filling this list is mandatory in case of export.

In case of import, you just need to fill this list if a column is using an identifier instead of the property’s name. This way, the variable defining the identifier is created correctly. Here is also the place you can define the grouping of two or more properties into just one column.


Picture 5: Properties tab


4) Tips for better using templates and this tool

Columns separator

CSV file's structure is based in columns. To correctly identify these columns, it is important that its separator is the same both for import and export, so that objects are correctly imported. One way to do it is by using the lists separator set in Window. This can be configured via Start—Settings—Control Panel—Regional and Language Options.


Picture 6: Windows Regional and Language Options


Since this configuration varies from one computer to another, it is important to check if the separator used when the CSV file is generated is the same one configured when the import is being performed.

Another option is to manually configure the columns separator, via Separator variable, on template's [Configuration] section. In this case, the configuration remains in the template, and you just need to use the same template in both import and export to ensure the separator is correctly configured.


Group your columns and get a more versatile file

The new tool brings a practical option to downsize the number of columns in the CSV file. Sometimes, when different objects are exported in the same CSV file, there may be properties that are not common to different objects, and this generates files with several blank columns. For example, suppose you have I/O tags and I/O blocks. N1 to N4 properties are tags properties, but not blocks. B1 to B4 properties, on the other hand, are blocks properties, but not tags. A CSV file for these eight properties would look like these:

ObjectType;Name ;N1;N2;N3;N4;B1;B2;B3;B4
IOTag ;Tag1 ;1 ;1 ;1 ;1 ; ; ; ;
IOBlock ;Block1; ; ; ; ;1 ;1 ;1 ;1 


This file could be reduced to only 6 columns if N1 to N4 properties are combined with B1 to B4 properties. This is possible because these objects do not have any of these properties in common.
If the combined properties are common to more than one type of object imported or exported, there will be loss of information because one property's value will overwrite the other property's value.
To combine properties, just select them and then click on [Group properties] button. Later, just edit the name of the column, if necessary.


Picture 7: Grouping properties into one column


The generated template will then look like these:
ObjectType;Name ;N1/B1;N2/B2;N3/B3;N4/B4
IOTag ;Tag1 ;1 ;1 ;1 ;1
IOBlock ;Block1;1 ;1 ;1 ;1 


Easily import files generated by Elipse SCADA

One of Elipse SCADA's options is to export its Tags, Screens and Alarms to a E2F file, and E3 can import these objects very easily with no need for templates, all you have to do is to observe some details:

  • Importing IOTags or OPCTags should be done from a IODriver or an OPCDriver, respectively, with the same name of Drivers at Elipse SCADA, so the references to the tags will be imported correctly.
  • Importing RAM and Demo Tags should be done from a Data Server named "Dados", also to to make sure that references will be imported correctly.
  • When Elipse SCADA exports tags, it's also created another E2f file with _Alarms suffix, containing the alarms’s configuration. Importing these alarms in E3 should be done from an Area previously created in Alarm Configuration. If tags have already be imported, the references to the tags in these alarms will appear in blue, indicating that the link is correct.
  • Before to import Screens from Elipse SCADA to E3 at the first time, it's necessary to registry E2Controls in E3, that is ActiveX controls of screen's objects. To do this, select the option Tools—Add ActiveX, and then select one of the E2Controls controls at the list, for example, E2Animation, after clicking [OK].



Always keep a basic template for each object

It is a good idea to have basic templates for each of the most commonly imported and/or exported objects. For example, a template for I/O Drivers, a template for Alarms, a template for Screens, and so on, according to each user's needs. These basic templates make it easier for you to configure this tool.

They may contain, for example, all properties to be used, and the preferred object types. When you start a new import or export procedure, just select the basic template and click on [Configure...] button. All configurations found in the basic template will be loaded into it.

In the option Save the template's changes in an INI file, chose a new name for this template (so that the basic template is not overwritten), and make the necessary changes to customize it.


Import tag files generated by E3 Studio's former versions

To support CSV files generated by tag export in older versions of E3, all you have to do is to correctly configure a template for it. Elipse Software provides you with the proper template for this import, found in E3's installation directory, in Templates folder. But, if necessary, configuring a new template is easy.

In E3 Studio's Template Manager, follow these procedures:

  1. On Settings tab, select Windows list separator as your column separator; disable the options for importing/exporting the root-object, links and collections; and choose a name for your template.
  2. On Import tab, leave the default configuration.
  3. On Filters tab, select the option Include only these objects, and click on [Change...] button to include the following classes: IOTag, IOBlock and IOBlockElement.
  4. On Identifiers tab, define three type identifiers. Click on [+] button and include the following classes: IOTag, IOBlock and IOBlockElement; respectively, define the following identifiers: PLC Tag, Block Tag and Element.



Picture 8: Defining identifiers for object classes


     5. On Properties tab, define the properties the older version (2.0 or previous) will be exporting, and associate it with the identifiers used in the CSV file. Link ObjectType to type identifier. For the others, follow these instructions:


Picture 9: Properties choices

  • Click on [+] button to add the properties.
  • Select IOTag class and include the following properties: Name, DocString, N1, N2, N3, N4, Scan, AllowRead, AllowWrite, EnableScaling, DeviceLow, DeviceHigh, EULow, EUHigh, ParamDevice, ParamItem.
  • Select IOBlock class, and include the following properties: B1, B2, B3, B4 and Size.
  • Finally, select IOBlockElement class, and include Index property.
  • Select N and B properties in pairs, and click on [Group properties] button. Then, change each column's name to N1/B1, N2/B2, etc.
  • Change the name of the columns of these properties:
     - DocString to Description.
     - Scan to ScanTime.
     - AdviseType to Advise.
     - EnableScaling to Scaling.
     - EUHigh to High2.


     6. Click on [OK]. The template will be saved, and ready to be used by the tool. The file with .INI extension should look like the one below:

[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 


Change object type in four steps

Up until version 2.0, there was no way of changing object type other than destroying the old one and creating a new one. It meant you lost the previous configurations, and they had to be remade in the new object. With the new import/export tool, there is now the possibility to change object type without losing the configured properties.

See how to accomplish this in only four steps.


Picture 10: Application (example)

  1. Export the objects whose type you want to change, thus creating a template that includes all properties from that object type. In the example, export all child-objects from InitialScreen. In the template configuration, include all properties from DrawRect class. To make it easier, create an identifier for this class on Template Manager's Identifiers tab, for example "object".
  2. Change the template used for export, replacing object types. In the example, replace DrawRect with DrawCircle. Do this simply by changing the value of "Object" variable in the template, with the help of a text editor. Replace "Object = DrawRect" por "Object = DrawCircle", and save the template.
  3. Erase all old objects from E3. In the example, remove all four rectangles from InitialScreen.
  4. Import the objects of the CSV file generated in step 1 by using the template changed in step 2. In the example, four new circles are created, but they will maintain the properties configured for the rectangles, such as color, position, size, etc.



Picture 11: Application after the objects have been changed (example)


It should be noted that this procedure is advantageous when the objects share a series of properties. Objects that are totally distinct from one another do not profit from this procedure. A practical use for this is when a Screen contains several XControls whose defining library was lost. Knowing the values of the properties defined for the XControl, it is possible to create a new library, define the ElipseX again, and then use these steps to replace the old ElipseX by the new ones, on the Screen.


5) Conclusion

Up until E3's 2.0 version, the only objects that could be imported or exported were I/O Drivers and Alarm areas, and only the child-objects’ properties were considered. The files generated in both cases, although in CSV format, were completely different, which made it very difficult for these tools to interact.

The main improvement for this tool, in 2.5 version, is that it is available for all types of objects, and uses the same procedures and format (CSV file) for any object. In addition, it is also possible to include links and collections alongside the properties, and also to import and export properties from the object where the operation is being made, which allows to generate identical copies from the exported objects.

By using templates, the new import/export tool has become more versatile, allowing quick adaptation to any type of object at E3, and more configurable, better adjusting itself to the unique needs of each user.



Related Articles

No related articles were found.

Attachments

No attachments were found.

Visitor Comments

No visitor comments posted. Post a comment

Post Comment for "Creating templates for E3 Studio’s import/export tool"

To post a comment for this article, simply complete the form below. Fields marked with an asterisk are required.

   Name:
   Email:
* Comment:
* Enter the code below:

 

Article Details

Last Updated
24th of October, 2008

Autor
Sheila Moreira Souza

Would you like to...

Print this page  Print this page

Email this page  Email this page

Post a comment  Post a comment

 Subscribe me

Subscribe me  Add to favorites

Remove Highlighting Remove Highlighting

Edit this Article

Quick Edit


User Opinions

No users have voted.

How would you rate this answer?




Thank you for rating this answer.

Continue