Signal Descriptions and Documents

Each signal may have textual descriptions and related documents, which are usually shown in the detail of the signal in client apps. For the sake of maintainability, the data are aggregated from multiple mapping files. Technically a signal mapping file is an XML document saved in file App_Data\signals\descriptions with the extension .desc. During startup, the system analyzes all such files, extracts the text descriptions/documents and maps it to the appropriate signals.

The structure of the mapping file is shown on the following sample. It has

• signalDescriptions - root element
  • signal - contains mapping for one particular signal. The signal is specified by one or more matching attributes (they are evaluated in AND manner, therefore a signal must match all specified conditions in order to receive specified description)
    • description - textual description which is attached to signal
    • signalIds - list of signal Id that are related to this description (autogenerated after first startup and after every reindexation - see API for more details)

<?xml version="1.0" encoding="utf-8"?>
<signalDescriptions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <signal nameExpression="%CL11AP001" pageInfoExpression="B001">
    <description><![CDATA[
            Zkušební popis signálu
            ]]></description>
    <signalIds>
      <signalId>0x0001.8.16.0[83.1].601.-3</signalId>
      <signalId>0x0001.8.16.0[83.2].601.-3</signalId>
      <signalId>0x0001.8.16.0[83.3].601.-3</signalId>
    </signalIds>
  </signal>
</signalDescriptions>

The mapping process for documents is the same like for descriptions. The structure of the mapping file (stored in App_Data\signals\documents) is also very similar.

• signalDocuments - root element
  • document
    • title - document title (presented to the end-users)
    • file - document filename (should be in the same directory)
    • clientFile - (optional) file name which is used when client downloads this file
    • signalIds - list of signal Id that are related to this description (autogenerated after first startup and after every reindexation - see API for more details)

<?xml version="1.0" encoding="utf-8"?>
<signalDocuments xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <document nameExpression="%CL11AP001" signalTypeExpression="SZ/EI" pageInfoExpression="B001" file="__MBY10EP001.pdf" clientFile="10MBY10EP001.pdf" title="Logical diagram">
    <signalIds>
      <signalId>0x0001.8.16.0[83.3].601.-3</signalId>
      <signalId>0x0001.9.26.0[91.3].601.-3</signalId>
    </signalIds>
  </document>
</signalDocuments>

The matching attributes are common to both the descriptions and documents.

• nameExpression - string is matched using SQL equality (or like query if % sign is contained) against the table kks, column kks, eg. %CL11AP001
• nameRegExpression - string is matched using SQL regular expression against the table kks, column kks, eg. ^[0-9A-Z]?[0-9]ADA01GS001A
• pageInfoExpression - string is matched using SQL equality (or like query if % sign is contained) against the table kks, column fup_page, eg. B001
• pageInfoRegExpression - string is matched using SQL regular expression against the table kks, column fup_page, eg. B[0-9][0-9][0-9]
• signalTypeExpression - string is matched using SQL equality (or like query if % sign is contained) against the table kks, column sgn, eg. XG03
• signalTypeRegExpression - string is matched using SQL regular expression against the table kks, column sgn, eg. ^K[0-9][0-9]$
• signalIdExpression - string is matched using SQL equality (or like query if % sign is contained) against the table kks, column ikz, eg. %.3].17.-3
• signalIdRegExpression - string is matched using SQL regular expression against the table kks, column ikz

It's good to know:

• Files are evaluated in the order provided by the file-system. In this order the textual descriptions are appended to the particular signal
• Since the mapping of signals and their descriptions takes some time, it is done during the start up of the application. The results of the mapping (particular signalIds) are than stored within the original XML file using the signalId tags (see above). Therefore next time, when the application loads the file, it detects the signalIds tag and does not evaluate the conditions, it simply maps the description to specified signals. In order to update the mappings (for example after change in the mapping conditions), one should run the reindexSignals method of the API.
• One rule (either signal or document) may conform to multiple signals. The information is then mapped to all of them.
• Each description file may contain multiple rules.