continuous delivery – new features in wincc oa version...
TRANSCRIPT
Further information: www.siemens.com/wincc-open-architecture Find also additional brochures and technical descriptions about SIMATIC WinCC Open Architecture
Continuous delivery – New features in WinCC OA version 3.13
ETM professional control GmbH A Siemens Company Marktstrasse 3, 7000 Eisenstadt Austria www.etm.at
Continuous delivery – New features in WinCC OA version 3.13
• Panel format independent from file extension Page 2
From now on the file extension may not be identically with the associated panel-format. In the save-file-dialog there is now an option for the panel-format(.xml/.pnl).
• Panel overview within GEDI Page 3
The GEDI now supports a panel overview which displays a small preview of all currently opened panels.
• Enhanced shape selection in GEDI Page 4
Now it is possible to select shapes that are lying on top of each other via the context menu (right-click with mouse). This menu entry is only visible if more than one shape is hit by the clicked position.
• OPC UA Historical Access Page 5 - 9
The OPC UA client now provides historical access functionality which allows getting historical data from an OPC UA server.
• Enhanced WinCC OA Reporting functionality Page 10 – 75
• The language parameter was added to data set functions. You can now display the DP description and the unit in a report language dependent.
• The “ready-to-use reports” are now available in English and German.
V 3.13
Copyright ETM professional control GmbH 2015 All Rights Reserved
Panel format independent from file extension
From now on the file extension .xml/.pnl may not be identically with the associated panel-format.
A panel newPanel.pnl can also be saved in XML-format. In the save-file-dialog there is now an
option for the panel-format.
The default format for new panels is PNL. With the config entry defaultPanelFormat the default
can be changed and the given format will be preselected in the "Save panel" dialog.
It is possible to use any file extension when saving a panel. If no extension is defined the
extension .xml or .pnl will be appended (depending on the chosen panel-format).
The changes in the UI have also an effect on the xmlConvert function.
For the parameter -xmlConvert a new option is available which allows to define the target format
when converting a panel.
-xmlConvert=XML - the panel(s) will be converted into xml-format
-xmlConvert=PNL - the panel(s) will be converted into pnl-format
When using this option the filenames will not be changed, only the content will be converted if
necessary. If a file already has the correct format it will remain unchanged. The option -o
(overwrite) is used implicit.
Converting panels without or with a different extension than .pnl or .xml is only possible when
using -xmlConvert=PNL/XML or the option -o (overwrite). When using the options -xmlConvert -
o, the panels will be converted and will not be renamed.
For panelfiles with the extension .pnl or .xml the functionality was not changed. If the file format
fits the extension the file will be converted and renamed when using the option -xmlConvert
(without defining the target format).
The option "-o" can be used in this case to overwrite an already existing target file, e.g. when
converting a .pnl file again when there is .xml file already existing.
You can now also use the option -noBackup for xmlConvert, that means that no .bak file will be
created.
+++ Examples +++
Original file Converted file
Used options Filename Format Filename Format
-xmlConvert main.pnl .pnl main.xml .xml
- xmlConvert -o main.pnl .pnl main.pnl .xml
-xmlConvert main.xml .xml main.pnl .pnl
-xmlConvert -o main.xml .xml main.pnl .xml
-xmlConvert=XML main.pnl .pnl main.pnl .xml
-xmlConvert=PNL main.xml .xml main.xml .pnl
-xmlConvert=XML main.pfll .pnl main.pfl .xml
-xmlConvert=PNL main.xpl .xml main.xpl .pnl
V 3.13 Copyright ETM professional control GmbH 2015 All Rights Reserved
Panel Overview Opens a list of all open panels and also displays a small preview of the panels as well as the
following information:
Panel name (or file name if no panel name is defined) + panel format (XML or PNL)
Path including the file name
Project name of the sub project or installation (if the panel is from your project, nothing is
displayed in this field)
V 3.13
Copyright ETM professional control GmbH 2015 All Rights Reserved
Select Shape - Select multiple overlapping Objects
To facilitate the selection of shapes in panels with multiple, overlapping objects the Select
Shape option can be used. Right-click the topmost object and you can select it via "Select
Shape. To select several shapes, right-click the topmost of the overlapping shapes while holding
the CTRL key and select "Select Shape". A list of all shapes is displayed and you can select
several shapes. The shapes are displayed in the following format: <shape name> (<layer>)
[<object type>].
Figure: Selection of several overlapping objects
The "Select Shape" option can also be used for objects inside references. Enable the selection
of reference objects ( ), Right-click the reference and you can select the topmost object via
Select Shape. Right-click the reference while holding the CTRL key and you can select several
objects.
Figure: Select shapes within a Reference
1
OPC UA Historical Access
Historical Access
2
Historical Access
This chapter describes the OPC UA Historical Access functionality of the WinCC OA OPC UA
client which allows to query historical data of an OPC UA server.
To start the reading of historical data as well as configuring the read request, an internal data
point must be used. The queried data can be used in the following ways:
Writing the data to an internal data point: In this case, the received data is mapped onto
an internal data point from where the data can be used for further data processing.
Therefore it is possible to execute historical read requests for historical data nodes of the
server that are not configured via peripheral addresses in the WinCC OA project.
Writing the data to data point element with appropriate peripheral address: This allows
to automatically insert the received data into the _archive config of all data point elements
with the appropriate peripheral address. Therefore, it is possible to retrieve data from the
server e.g. for a time interval in which the connection to the server was lost.
Historical data request
The internal data point element _OPCUAServer.Command.HistoryRead is used for triggering a
historical read request as well as configuring its parameters.
Depending on the configuration of this data point element, the received data is either written to a
response data point of type _OPCUAHistoryReadResponse or to the archive of data point
elements with the appropriate peripheral address.
1. WRITE DATA TO RESPONSE DATA POINT
To map the received data onto a response data point proceed as follows:
Create a response data point
Create a data point of type _OPCUAHistoryReadResponse.
Example: responseDP
After that the created response data point must be entered at the internal data point element
_OPCUA<Treibernummer>.Config.HistoryReadResponseDps. Thus it can be used for receiving
data.
Start the request
Now it is possible to start the reading of historical data via the internal data point element
_OPCUAServer.Command.HistoryRead. In order to write the data to the response data point,
either method 1 (state the NodeId of the item which shall be queried) or 2 (state the BrowsePath
of the item which shall be queried) must be selected (refer to
_OPCUAServer.Command.HistoryRead - Method).
Example - Method 1:
RequestId123
ReadRaw
1
ns=2;s=AirConditioner_2.Temperature
2015.03.03 09:00:00.000
3
V 3.13
Copyright ETM professional control GmbH 2015 All Rights Reserved
2015.03.03 09:10:00.000
20
0
responseDP1
Example - Method 2:
RequestId123
ReadRaw
2
/0:Objects/0:Server/2:AreaAirConditioner/2:AirConditioner_2/2:Tempera
ture
2015.03.03 09:00:00.000
2015.03.03 09:10:00.000
20
0
responseDP1
Click on the Apply button in the PARA module and the request is triggered with the defined
parameters. Click here for a detailed parameter description.
Data processing
The result of the request is written to the defined response data point (responseDP1) and can
be used for further data processing.
2. WRITE DATA TO _ARCHIVE CONFIG OF DATA POINT ELEMENTS
It is possible to write the historical values to data point elements with the specified peripheral
address by using method 3. Proceed as follows:
Peripheral address
You have to determine a valid peripheral address via the data point element HW.HWMask of
internal data point type _DriverCommon. If the _address config is linked to e.g. item ID
"ns=2;s=AirConditioner_2.Temperature", this ID is not the correct peripheral address. In this
case the valid address is:
"opcua_server$Subscription$1$1$ns=2;s=AirConditioner_2.Temperature"
NOTE
It is also possible to define a wildcard which queries exactly this one specific address. In this
case the correct wildcard would be *ns=2;s=AirConditioner_2.Temperature"
It is possible to request historical values from several peripheral addresses and write the result
to the archive of all appropriate data point elements. Therefore, wildcards must be used.
When writing the data of historical requests to the WinCC OA archive the timestamp defined in
the subscription of the appropriate data point element is used. Use the internal data point
Historical Access
4
element OPCUAServer.Config.HistoryReadTimestamps to define which timestamp shall be
used in case that no subscription is defined (the source timestamp is used by default).
NOTE
The OPC UA client only performs historical requests for data point elements where the "history"
checkbox at the peripheral address panel is enabled (see also Notes and restrictions). In order
to label the queried data with a specific user bit the config entry userBitHistoryRead must be
used. If the historical values shall be written as correction values, the config entry histDataBits
must be set additionally.
Response data point
The response data point is not mandatory when using method 3. However, important
information like RequestId, ReturnCode or DpList is returned in case that a response data point
is defined.
Start the request
After defining method 3 as well as a valid peripheral address, the request can be started by
clicking on the Apply button in the PARA module.
Example:
RequestId123
ReadRaw
3
ns=2;s=AirConditioner_2.Temperature
2015.03.03 09:00:00.000
2015.03.03 09:10:00.000
20
0
responseDP2
Redundancy behavior
OPC UA server redundancy
The History Access interface of the WinCC OA OPC UA client supports OPC UA server
redundancy.
In case of a non-transparent redundant OPC UA server the OPC UA client only sends a
HistoryRead request to the first accessible server by default. In order to handle missing
historical data on one of the two redundant servers the OPC UA client provides the possibility to
send the HistoryRead request to both servers. In this case the OPC UA Client will merge the
result of the history read service requests from both servers.
NOTE
In case that both servers return different values for an identical timestamp, the value of the first
server is used.
The Redu.Config.HistoryReadMode data point element must be used for configuring the
redundancy behavior.
5
V 3.13
Copyright ETM professional control GmbH 2015 All Rights Reserved
OPC UA client redundancy
In case of redundant WinCC OA clients, both clients transmit the historical request to the server.
There seem to be two separate requests for the server. The actual active/passive mechanism
as well as the related discarding of values is performed in WinCC OA. In order to avoid data
loss during the switch-over it is recommended that both clients perform historical requests. The
advantage of this redundancy variant is that the server does not have to support any
redundancy abilities.
In case that the passive OPC UA client shall not transmit historical requests to the server,
configure the behavior of the passive client via config entry historyReduMode.
Notes & restrictions
Notes
Since not every node in the OPC UA address space might contain history data, the internal data
point element _OPCUAServer.Browse.AccessLevel indicates whether historical data is
available for the respective nodes.
The _offset attribute of the _address config is used for indicating whether historical data is
available on the server for the peripheral address in WinCC OA. When using method 3, the
OPC UA client only performs a read request if the _offset attribute is set for the peripheral
address. Therefore, the "History" checkbox must be enabled at the panel for defining the
peripheral address of the OPC UA driver. The structure of the _offset attribute is as follows:
Bit Description
0
Indicates whether historical data is available on the server for this peripheral
address.
0 = no historical data available
1 = historical data is available
1-
15 Reserved for future use
The example panel OPCUA_HA_Example.pnl (located in <wincc_oa_path>/panels/examples)
demonstrates the OPC UA Historical Access functionality of the OPC UA client.
Restrictions
Only read access to historical data of an OPC UA server is possible, write requests are not
supported.
The WinCC OA OPC UA client only supports the function ReadRaw of the OPC UA service
History Read.
The WinCC OA OPC UA client does not support historical aggregates.
1
Multilingualism
You can adapt the language settings for the report content, for the report viewer and for the
report designer. This chapter describes how to adapt the language settings.
Two resource files ("localization.properties" and "localization_de_AT.properties) are delivered
with the WinCC OA installation. Hence, you can display the ready-to-use reports delivered with
the WinCC OA installation also in German.
Language Settings of a Report
You can create a report in different languages (for example, Report_DE and Report_EN) or you
can adapt the language by using resource files.
How to create a resource file
1. Create a resource file in the same directory as your report. You need a default file, for
example, with the name "localization" (file name: localization.properties, see figure below). In
order to add further languages, create files such as localization_de_AT.properties or
localization_en_US.properties. Add the "localization" file in the property editor via Add
File..
Figure: The Resource File "localization"
A resource file consists of key-value pairs. A key-value pair must be specified for each element
that should be adapted. Note that each resource file, for example, localization_de_AT.properties
or localization_en_US.properties must contain the same keys as the default file "localization".
2. After creating the "localization" file, click on Browse...:
Figure: Specify Key-Value Pairs
2
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
3. Specify a key-value pair and click on Add. Repeat this step to add more key-value pairs.
Figure: Add Key-Value Pairs
4. Create a new resource file "localization_de_AT". Copy the entries of the "localization" file to
the "localization_de_AT" file and translate the entries.
Figure: The Resource File localization_de_AT and translated entries
3
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
5. Now you can open your report in a browser in German. Add the translated file
"localization_de_AT" to the resources first. Now you can change the default language
directly in the designer by moving the "localization_de_AT" file up in the designer (see the
figures below):
Figure: The Language of a report is set to English (the file "localization" is selected)
Figure: The Language of a report is set to German (the file "localization_de_AT" is selected)
You can also change the language in a browser via the parameter __locale=<language>, for
example, to __locale=de_AT. NOTE the double underline for the "__locale" parameter. If the
__locale parameter is not shown, add it manually to the browser. See also chapter Web view.
Take care that your resource files are located in the same directory with your report.
CAUTION
4
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The resource files must be ASCII encoded (not UTF-8), otherwise display errors might
occur when displaying, for example, Russian characters or umlauts.
You can change the prompt and the help text for the report parameters in the property editor
under Properties/Localization (see figure "Localization" below). These are shown in the
parameter window when you open a report (see figures "Parameter Window and translated
Prompt" and "Parameter window and help text "Erforderliches Format" " below).
Figure: Localization
Figure: The Parameter Window and a translated Prompt
Figure: The Parameter window and the help text "Erforderliches Format"
5
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Language Settings of the Designer
The default language of the designer is English.
To change the language of the designer, download the appropriate language zip file:
http://download.eclipse.org/technology/babel/babel_language_packs/R0.12.1/luna/lu
na.php
e.g.
http://www.eclipse.org/downloads/download.php?file=/technology/babel/babel_langu
age_packs/R0.12.1/luna/BabelLanguagePack-birt-de_4.4.0.v20141223043836.zip
Copy the directories of the zip file into the eclipse installation directory.
Start BIRT via the exe file <eclipsePath>eclipse.exe <language>, e.g.,
D:\eclipse\eclipse.exe -nl en or ru
CAUTION
The language files do not guarantee a full translation (see the percentages on the page
http://download.eclipse.org/technology/babel/babel_language_packs/R0.12.1/luna/luna.p
hp).
6
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Language Settings of the Viewer
The default language of the BIRT viewer is English. To change the language of the viewer,
download the appropriate language zip file and copy the directories of the zip file to the eclipse
installation directory (see the description above). You can then change the language of the
viewer under Window/Preferences/Preview/Choose your locale:
Figure: Language Settings for the Viewer
7
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Data set functions
Configuration of the Function alertGetPeriod
This chapter describes the function alertGetPeriod.
Function type
Select the function type alertGetPeriod after creating and naming a new data set (see create data set)
and click on Next>.
Figure: Select the function type "alertGetPeriod"
Parameters
Shows the parameters that are available for the configuration. Select the parameters and click on Next>
Figure: Parameter Selection
8
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Function Parameters
Parameter Description
startTime Start time of the time range to be queried
endTime End time of the time range to be queried
alertAttribute Data point element whose alert attributes are queried
lang
The project language. If you don't specify the language, the function returns the default language of the project. This means the default language set in the config file of the project (active language). If you, however, specify the parameter "lang" in the config file, the language of
9
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
the "lang" parameter is returned. The parameter "lang" is optional.
NOTE
Wildcards must not be used for defining the data point element (alertAttribute parameter).
NOTE
For further information regarding the function and the parameters, see the CTRL function
alertGetPeriod. Note that the reporting function "alertGetPeriod" contains the parameter "lang" in
addition to the parameters of the normal CTRL function.
SOAP Request
In order to retrieve values from WinCC OA, the generated SOAP request is transferred to the WinCC
OA Reporting Manager in XML format. The SOAP request contains the dynamic parameters which are
replaced by the queried values.
Figure: The SOAP Request
10
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
You can specify default values for each parameter via the Edit Parameter button. This is not mandatory
but necessary if you want to check your settings later on (via Column Mapping - Show Sample Data).
CAUTION
Note that the data type cannot be specified here.
For this example the following default values are used:
Figure: Default Values
The time is specified in the format: <yyyy>-<mm>-<dd>T<hh>:<mm>:<sss>.<msec>, e.g. 2015-05-
05T13:00:00.000
Click on the OK button and click on Next>.
SOAP Response
No changes are necessary for this window. Click on Next>
Figure: SOAP Response
11
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Row Mapping
BIRT reports must use data structured as tables (with rows and columns). In XML code, elements and
attributes are used for providing data. Therefore, you have to define how the XML elements are linked
with rows and columns.
Use the Row Mapping to select which XML element is added as a new data set row. Each occurrence
of the selected XML element is linked with a new data set row. Select "table" and click on the > button
to select the XPath Expression (the selected element in the XML structure). You can pass an absolute,
a relative or a user-defined path. A Path starting with a slash / is absolute, a path starting with // is
relative.
Figure: The Row Mapping
12
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The "Select or edit the XPath expression" window is opened. Select the option "XML elements named
"table" at any location" and click on the OK button. Note that this option is mandatory in order to retrieve
data.
Figure: "Select or edit the XPath expression" Window
13
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Click on the Next > button.
Figure: Row Mapping - XPath Expression //table
14
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Column Mapping
Column Mapping defines the columns for the table row. The columns are mapped to child elements or
attributes within the selected data row element. In contrast to row mapping, you can select several
elements. Select an element from the window on the left and click on the > button. The Column
mapping window is opened
Figure: Column Mapping Window - Column name: value, Data Type: float
15
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Select the data type "float" from the combo box as well as the option "XML elements named "value" at
any location". Click on the OK button.
The element "value" is shown in the "Column mapping" window.
Figure: The element "value" is shown in the Column Mapping Window
16
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Repeat this step for the elements "date", "abbr", "text", "direction", "ack-state" and "ack-time". Select
the correct data type for each element.
CAUTION
The BIRT tool queries dates and time as strings by default. You can, however, change the data
type for dates and time in the output columns (see further below).
Figure: Column Mapping
17
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The column mapping contains the attributes:
value (the data point value),
date (the date when the value was set),
state (the attribute state contains the status bits _obsolete, _ackable etc. in a bit32.),
abbr (the Short sign (e.g.: A for an Alert) of the alert priority.),
prior (the Alert priority),
text (the State text),
direction (the Alert direction: CAME/WENT),
ack-state (the acknowledgement type of the alert),
ack-time (the acknowledgement time of the alert),
ack user (the user who acknowledged the alert),
comment (the user comment for an alert)
You can also return the error code and the error text in addition to the alert attributes. Since these two
elements are located on the same level as the /table, you cannot return them in the same data set.
Thus, a second identical data set must be created to display the error code and the text.
18
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Error code Description
-1 Data point not found
-2 Answergroup error
-3 Error in RDB Query
As mentioned before, you have to specify default values for the parameters in order to use the Show
Sample Data button. If the default values are set, you can check the settings before completing the
configuration.
Figure: Sample XML Data
Edit Data Set
The Edit Data Set menu can be opened by double-clicking the data set in the data explorer. You can
edit the entire data set configuration. The menu items Data source, WSDL operation, SOAP request,
19
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
SOAP response, Row Mapping and Column Mapping are identical to the already described steps and
are therefore not described in detail here.
The following menu items offer further configuration possibilities.
Parameters
Here you can specify default values in the same way as in the SOAP request earlier. These settings do,
however, not have an influence on the output (Show Sample Data) in the column mapping but on the
preview results. Furthermore, you can link the parameters with the report parameters here.
CAUTION
The BIRT tool queries dates and time as strings by default. You can, however, change the data
type for dates and time in the output columns (see further below).
Figure: Default Parameters
Output Columns
Here you can change the data types for the parameters. You can, for example, change the data type of
date and time parameters. Dates and time are queried as strings but can be changed here to "Date"
and "DateTime". Furthermore, you can add an alias and a display name which are shown when the
report is opened in the worksheet.
Figure: Output Columns
20
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
When you drag the function to the template in order to select the columns that are shown for the report
(see chapter View report), the alias is shown:
Figure: Selection of the Columns (Data Set Binding)
The display name "VALUE" and the alias name "This is the value column) (as a tooltip) are shown in the
template (in edit mode):
21
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Figure: The Display name "VALUE" and the alias name as a tooltip
Computed Columns
Allows you to add additional columns to a report. The columns can, for example, be used to perform
calculations.
Figure: Additional Columns (Computed Columns)
Click on New... and select a name and an appropriate data type for the data that is returned.
Figure: Selection of Data Type for a Column
22
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Under Expression you can define the content that is displayed in the column. The Expression Builder
allows you to add the existing data sets and functions with a double- click. The column is displayed in
the Output Columns after completing the configuration.
Figure: Expression Builder
23
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Filters
Defines which values are shown in the report and which are filtered.
Figure: Filters for the Values
24
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Click on New... and choose a column from the combo box. The content of this column is filtered
according to the selected condition.
Figure: A new Filter Condition
Preview Results
25
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Can be used for checking the configuration and returns results according to the default values defined
before under Parameters.
Figure: Sample Data
After creating a data set, you can create report parameters. Report parameters are necessary in order
to use data sets fast and easily in a report. Otherwise the default parameters must be changed in the
data set settings each time when generating a new report. You can also view the report directly without
creating report parameters. For How to view a report, see chapter View report.
26
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Configuration of the Function dpGet
This chapter describes the function dpGet.
Function type
Select the function type dpGet after creating and naming a new data set (see create data set) and click
on Next>.
Figure: Select the function type "dpGet"
Parameters
Shows the parameters that are available for the configuration. Select the parameters and click on Next>
Figure: Parameter Selection
27
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Function Parameters
Parameter Description
dpName Data point element which is queried
lang
The project language. If you don't specify the language, the function returns the default language of the project. This means the default language set in the config file of the project (active language). If you, however, specify the parameter "lang" in the config file, the language of the "lang" parameter is returned. The parameter "lang" is optional.
NOTE
For further information regarding the function and the parameters, see the CTRL function dpGet. Note
that the reporting function "dpGet" contains the parameter "lang" in addition to the parameters of the
normal CTRL function.
28
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
SOAP Request
Figure: The SOAP Request
Click on Edit Parameter to specify values for the parameters:
Figure: Edit Parameters
Click on the OK button and click on Next>.
29
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
See chapter alertGetPeriod for a detailed description of the SOAP request.
SOAP Response
No changes are necessary for this window. Click on Next>
Figure: The SOAP Response
Row Mapping
Select the attribute "return" and click on > button. The "Select or edit the XPath expression" window is
opened:
Figure: XML elements named "return" at any location
30
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Select the "XML elements named "return" at any location" option. The //return element is added to the
XML Element Selection.
Figure: The Row Mapping - XPath Expression //return
31
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Click on the next> button. See also chapter alertGetPeriod for further details.
Column Mapping
The Column Mapping defines the columns for the table row. The columns are mapped to child elements
or attributes within the selected data row element. In contrast to row mapping, you can select several
elements.
Figure: The Column Mapping
32
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The column mapping contains the attributes:
value (a data point value) and the
ErrorCode and Error text:
Error code Error Text
-1 Data point not found
-2 Answergroup error
Select an element and click on the > button. The "Select or edit the XPath expression" window is
opened. Select the "XML elements named "<element>" at any location" option.
Show Sample Data
As mentioned in the chapter alertGetPeriod, you have to specify default values for the parameters in
order to use the "Show Sample Data" button. If the default values are set, you can check the settings
before completing the configuration.
Figure: Sample Data
33
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
If the data point does not exist, the following error code and error text are shown.
Figure: A missing Data point
34
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Configuration of the Function dpGetAsynch
This chapter describes the function dpGetAsynch.
Function type
Select the function type dpGetAsynch after creating and naming a new data set (see create data set)
and click on Next>.
Figure: Select the function type "dpGetAsynch"
35
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Parameters
Shows the parameters that are available for the configuration. Select the parameters and click on Next>
Figure: Parameter Selection
36
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Function Parameters
Parameter Description
time The source time
dpName The data point element which is queried
NOTE
Wildcards must not be used for defining the data point element (the dpName parameter).
NOTE
See chapter dpGetAsynch for further information regarding the function and the parameters.
SOAP Request
Figure: The SOAP Request
37
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Click on Edit Parameter to specify values for the parameters:
Figure: Edit Parameters
The time is specified in the format: <yyyy>-<mm>-<dd>T<hh>:<mm>:<sss>.<msec>, e.g. 2015-05-
05T13:00:00.000
Click on the OK button and click on Next>.
38
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
See chapter alertGetPeriod for a detailed description of the SOAP request.
SOAP Response
No changes are necessary for this window.
Figure: The SOAP Response
Row Mapping
Select "table" and click on the > button to select the XPath Expression. The "Select or edit the XPath
expression" window is opened. Select the option "XML elements named "table" at any location" and
click on the OK button. See chapter alertGetPeriod for a detailed description.
Figure: The Row Mapping
39
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Column Mapping
The Column Mapping defines the columns for the table row. The columns are mapped to child elements
or attributes within the selected data row element. In contrast to row mapping, you can select several
elements. Select an element from the window on the left and click on the > button. The Column
mapping window is opened. Select the data type from the combo box as well as the option "XML
elements named "<element>" at any location". Click on the OK button.
Figure: The Column mapping
40
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The column mapping contains the attributes:
date (the date when the value was set)
value (the data point value)
CAUTION
The BIRT tool queries dates and time as strings by default. You can, however, change the data
type for dates and time in the output columns (see chapter alertGetPeriod).
You can also return the error code and the error text in addition to the alert attributes. Since these two
elements are located on the same level as the /table, you cannot return them in the same data set.
Thus, a second identical data set must be created to display the error code and the text.
Error code Description
-1 Data point not found
-2 Answergroup error
-3 Error in RDB Query
41
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Show Sample Data
As mentioned in the chapter alertGetPeriod, you have to specify default values for the parameters in
order to use the "Show Sample Data" button. If the default values are set, you can check the settings
before completing the configuration.
Figure: Sample Data
Configuration of the Function dpGetPeriod
This chapter describes the function dpGetPeriod.
Function type
Select the function type dpGetPeriod after creating and naming a new data set (see chapter data set)
and click on Next>.
Figure: Select the function type "dpGetPeriod"
42
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Parameters
Shows the parameters that are available for the configuration. Select the parameters and click on Next>
Figure: Parameter Selection
43
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Function Parameters
Parameter Description
startTime The start time of the queried time range
endTime The end time of the queried time range
bonus Number of values that are also displayed before
the startTime and after the endTime
dpName The data point element which is queried
NOTE
44
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Wildcards must not be used for defining the data point element (the dpName parameter).
NOTE
See the CTRL function dpGetPeriod for further information regarding the function and the parameters.
SOAP Request
Figure: The SOAP Request
Click on Edit Parameter to specify values for the parameters:
Figure: Edit Parameter
45
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The time is specified in the format: <yyyy>-<mm>-<dd>T<hh>:<mm>:<sss>.<msec>, e.g. 2015-05-
05T13:00:00.000
Click on the OK button and click on Next>.
See chapter alertGetPeriod for a detailed description of the SOAP request.
SOAP Response
No changes are necessary for this window. Click on Next>
Figure: The SOAP response
46
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Row Mapping
Select "table" and click on the > button to select the XPath Expression. The "Select or edit the XPath
expression" window is opened. Select the option "XML elements named "table" at any location" and
click on the OK button. See chapter alertGetPeriod for a detailed description.
Figure: The Row Mapping
47
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Column Mapping
The Column Mapping defines the columns for the table row. The columns are mapped to child elements
or attributes within the selected data row element. In contrast to row mapping, you can select several
elements. Select an element from the window on the left and click on the > button. The Column
mapping window is opened. Select the data type from the combo box as well as the option "XML
elements named "<element>" at any location". Click on the OK button.
Figure: The Column Mapping
48
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The column mapping contains the attributes:
date (the date when the value was set)
value (the data point value)
You can also return the error code and the error text in addition to the alert attributes. Since these two
elements are located on the same level as the /table, you cannot return them in the same data set.
Thus, a second identical data set must be created to display the error code and the text.
Error code Description
-1 Datapoint not found
-2 Answergroup error
-3 Error in the RDB Query
49
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
CAUTION
The BIRT tool queries dates and time as strings by default. You can, however, change the data
type for dates and time in the output columns (see chapter alertGetPeriod)).
Show Sample Data
As mentioned in the chapter alertGetPeriod, you have to specify default values for the parameters in
order to use the "Show Sample Data" button. If the default values are set, you can check the settings
before completing the configuration.
Figure: Sample Data
50
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Configuration of the Function dpNames
This chapter describes the function dpNames.
Function type
Select the function type dpNames after creating and naming a new data set (see chapter data set) and
click on Next>.
Figure: Select the function type "dpNames"
Parameters
Shows the parameters that are available for the configuration. Select the parameters and click on Next>
Figure: Parameter Selection
51
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Function Parameters
Parameter Description
dpPattern A pattern that defines which data point or which
data point elements are returned.
dpType A data point type used for the additional filtering
of data points.
lang
The project language. If you don't specify the
language, the function returns the default
language of the project. This means the default
language set in the config file of the project
(active language). If you, however, specify the
parameter "lang" in the config file, the language
of the "lang" parameter is returned. The
parameter "lang" is optional.
52
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
descriptionMode
Mode 0: Returns the description of the data
point element. If a description does not
exist, the data point element name
(DP.EL1.EL2) is returned.
Mode 1 (Default option): Returns the
description of the data point element. If a
description does not exist, the text
"RootNode Description DP" and the
description of the master data point element
is returned for the ROOT DP. (Text:
"RootNode Description DP" and the
description of the master data point
element).
For the other DPs, the data point name of
the queried data point and the description of
the DP element of the master data point are
returned (DP name + description of the DP
element of the master data point).
If a description does not exist for the DP
element of the master data point either, the
data point name or the DP element name is
returned (depending on whether you query
a data point or an element).
Mode 2: Returns the description of the data
point element. If a description does not
exist, the description of the master data
point element and the text "RootNode
Description DP" are returned for the root
DP.
(the Description of the master data point
element and the text "RootNode Description
DP").
For the other DPs, the description of the DP
element of the master data point and the
data point name of the queried data point
are returned (the description of the element
of the master data point + DP name).
If a description does not exist for the DP
element of the master data point either, the
data point name or the DP element name is
returned (depending on whether you query
a data point or an element).
Mode3: Returns the description of the data
point element. If a description does not
53
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
exist, the text "RootNode Description DP
<ElementName>" and the description of the
master data point element are returned for
the ROOT DP.
(Text: "RootNode Description DP
<ElementName>" and the description of the
master data point element).
For the other DPs, the data point name and
the data point element name of the queried
data point and the description of the DP
element of the master data point are
returned (DPName +DPE name +
description of the DP element of the master
data point).
If a description does not exist for the DP
element of the master data point either, the
data point name or the DP element name is
returned (depending on whether you query
a data point or an element).
NOTE
See the CTRL function dpNames for further information regarding the function and the parameters.
Note that the reporting function "dpNames" contains the parameters "lang" and "descriptionMode" in
addition to the parameters of the normal Control function.
SOAP Request
Figure: The SOAP Request
54
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Click on Edit Parameter to specify values for the parameters:
Figure: Edit Parameter
Click on the OK button and click on Next>.
See chapter alertGetPeriod for a detailed description of the SOAP request.
SOAP Response
55
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
No changes are necessary for this window. Click on Next>
Figure: The SOAP Response
Row Mapping
Select "table" and click on the > button to select the XPath Expression. The "Select or edit the XPath
expression" window is opened. Select the option "XML elements named "table" at any location" and
click on the OK button. See chapter alertGetPeriod for a detailed description.
Figure: The Row Mapping
56
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Column Mapping
The Column Mapping defines the columns for the table row. The columns are mapped to child elements
or attributes within the selected data row element. In contrast to row mapping, you can select several
elements. Select an element from the window on the left and click on the > button. The Column
mapping window is opened. Select the data type from the combo box as well as the option "XML
elements named "<element>" at any location". Click on the OK button.
Figure: The Column Mapping
57
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The column mapping contains the attributes:
dpName (the data point or data point element name)
description (the description of the data point)
alias (the alias name of the data point)
unit (the data point unit)
lang (the project language). If you don't specify the language, the function returns the default language
of the project. This means the default language set in the config file of the project (active language). If
you, however, specify the parameter "lang" in the config file, the language of the "lang" parameter is
returned. The parameter "lang" is optional.
You can also return the error code and the error text in addition to the alert attributes. Since these two
elements are located on the same level as the /table, you cannot return them in the same data set.
Thus, a second identical data set must be created to display the error code and the text.
Error code Description
58
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
-1 DpIdentification Pointer not found
-2 Error reading the DP list
As mentioned in the chapter alertGetPeriod, you have to specify default values for the parameters in
order to use the "Show Sample Data" button. If the default values are set, you can check the settings
before completing the configuration.
Figure: Sample Data
59
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Configuration of the Function dpQuery
This chapter describes the function dpQuery.
Function type
Select the function type dpQuery after creating and naming a new data set (see chapter data set) and
click on Next>..
Figure: Select the function type "dpQuery"
Parameters
Shows the parameters that are available for the configuration. Select the parameters and click on Next>
Figure: Parameter Selection
60
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Function Parameters
Parameter Description
query SQL Statement
lang
The project language. If you don't specify the
language, the function returns the default
language of the project. This means the default
language set in the config file of the project
(active language). If you, however, specify the
parameter "lang" in the config file, the language
of the "lang" parameter is returned. The
parameter "lang" is optional.
NOTE
For further information regarding the function and parameters, see the CTRL function dpQuery. Note
61
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
that the reporting function "dpQuery" contains the parameter "lang" in addition to the parameters of the
normal Control function.
SOAP Request
Figure: The SOAP Request
Click on Edit Parameter to specify values for the parameters:
Here you can see the query parameter for the function:
SELECT '_alert_hdl.._active, _alert_hdl.._act_text, _alert_class.._ack_type' FROM 'ExampleDP_Rpt1'
Figure: Edit Parameters
62
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
NOTE
A maximum of 6 attributes can be queried via the Reporting function dpQuery. There are 7 elements
available (columns 1 - 7 refer to Column Mapping). The column 1 is, however, automatically used for
the dp element.
Click on the OK button and click on Next>. See chapter alertGetPeriod for a detailed description of the
SOAP request.
SOAP Response
No changes are necessary for this window. Click on Next>
Figure: The SOAP Response
63
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Row Mapping
Select "table" and click on the > button to select the XPath Expression. The "Select or edit the XPath
expression" window is opened. Select the option "XML elements named "table" at any location" and
click on the OK button. See chapter alertGetPeriod for a detailed description.
Figure: The Row Mapping
64
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
Column Mapping
The Column Mapping defines the columns for the table row. The columns are mapped to child elements
or attributes within the selected data row element. In contrast to row mapping, you can select several
elements. Select an element from the window on the left and click on the > button. The Column
mapping window is opened. Select the data type from the combo box as well as the option "XML
elements named "<element>" at any location". Click on the OK button.
Figure: The Column Mapping
65
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
The column mapping contains the attributes:
column1 to column7 (A maximum of 6 attributes can be queried via the dpQuery function. There are 7
elements available (columns 1 - 7). The column 1 is, however, automatically used for the dp element. In
the figure above the following attributes were queried: _alert_hdl.._active, _alert_hdl.._act_text und
_alert_class.._ack_type, see the SQL query under Edit parameter.
You can also return the error code and the error text in addition to the alert attributes. Since these two
elements are located on the same level as the /table, you cannot return them in the same data set.
Thus, a second identical data set must be created to display the error code and the text.
Error code Description
-1 dpQuery failed
-2 Answergroup error
66
V 3.13 Copyright ETM professional control 2015 All Rights Reserved
As mentioned in the chapter alertGetPeriod, you have to specify default values for the parameters in
order to use the "Show Sample Data" button. If the default values are set, you can check the settings
before completing the configuration.
Figure: Sample Data