OTX-Mapping

Table of Contents

• Mappings
• Environment Presets
• Proxy Implementation
• Default Custom Implementation
• Own Custom Implementations with OTX-Mapping
  • Properties to be Handle
  • Special Literal Parameters
• OTX-Mapping Editor
• Sample OTX-Mapping (OTF Solution)

One of the most important benefit of OTX is the strict separation of test logic and runtime implementation. Some OTX extensions (HMI, Measure or ExternalServiceProvider) needs access to external systems. This systems are accessed via the OTX-Mapping. The OTX-Mapping is a platform independent access to arbitrary external systems. It can ensure that the same unchanged OTX test logic can be executed in any target system at any time and comes to the same results.

The OTX-Mapping can be edited with the OTX-Mapping Editor inside the OTX Development Environment. All information will be stored inside the so called OTX-Mapping file.

Mappings

The following mappings exists:

• ScreenMapping
  Mapping to graphical interfaces (HMI), which binds a Screen Signature of the HMI extension to an external screen, default implementation see CustomScreenImplementation or HTML-Screen Implementation.
• DeviceMapping
  Mapping of arbitrary measurement device drivers, which binds a Device Signature of the Measure extension to a public method of the external environment, default implementation see MeasureImplementation.
• ServiceProviderMapping
  Mapping of arbitrary classes, including properties, methods and events of the ExternalService extension to the external environment, default implementation see ExternalServiceProviderImplementation.
• ContextMapping
  Mapping environmental data, which binds a Context Variable to a public read only property of the external environment, default implementation see ContextVariableImplementation.
• StateMapping
  Mapping of status information, which binds a State Variable to a public write only property of the external environment, default implementation see StateVariableImplementation.
• Environment Presets
  All Signature InOut- or Out-Parameters as well as context variables which are not available in the external environment can be set to a fix value, see Environment Presets.

All required mapping data for a specific target environment are stored in a XML file. Solely by exchanging this file, see runtime project settings, the same test logic can be executed in various target environments.

Note: The OTX-Mapping file can be set at the OTX-Runtime via the project settings, see IRuntimeSettings.OtxMapping.

Note: A nonexistent environment can be simulated via a so called Proxy, see Proxy Implementation or Environment Presets.

The standardized test logic in OTX only describes the interface inside an OTX-Signature, see left part of picture below. One of multiple so called custom implementations can be bound to this interface via the OTX-Mapping mechanism, see right part of picture below. OTX-Mapping means linking of the parameters of a signature to an element of an external environment and store it inside an OTX-Mapping file. An OTX-Mapping file can be edited in a graphical Mapping-Editor.

Note: The usage of custom implementations together with the API is described here: Custom Implementations.

Environment Presets

It is possible that an external system does not support all parameters which are available in OTX test logic. These parameters can be set (simulated) via the so called environment presets to fix values, see OTX-Mapping Editor and will be stored inside the OTX-Mapping file.

Note: Environment presets are only valid for all not mapped Signature InOut- or Out-parameters as well as context variables (direction from environment into OTX-Runtime).

Note: If available, the Value of the parameter or context variable (not the InitValue) will be set to the environment preset before the related method like OpenScreen or ExecuteDeviceService was called.

Proxy Implementation

If there is no custom implementation available or the custom implementation is not needed, e.g. during authoring of OTX sequences, a proxy can be used. A proxy can simulate a complete environment. It is an implementation without function.

• A proxy can be used if no implementation is available
• A proxy stores its interface in a XML file
• A proxy can be used as a general contract for certain custom implementations
• A proxy can be graphically edited in the Mapping-Editor, see picture below
• The OTX-Mapping Editor can generate screen and device signatures as well as context and status variables from a proxy, and vice versa.

Note: If the Default Custom Implementation is used, all OTX-Mappings which maps to a proxy performs a NOP (no operation).

Default Custom Implementation

The following default custom implementations will be delivered with the OTX-Runtime, see Installation. They give the user an easy way to add its own implementation to OTX.

• Assembly-Screen Implementation
• HTML-Screen Implementation
• Assembly Implementation

Note: The delivered default custom implementations only supports DotNet and are only available for Windows. To support other technologies or other systems like Linux own custom implementations must be written.

To work with the default custom implementations the following steps have to be done:

1. Select an appropriate implementation, e.g. HTML-Screen
2. Create the necessary files for this implementation, e.g. HTML template file with placeholders
3. Write the OTX test logic, e.g. with a ScreenSignature for HTML-Screen

   Note: A ScreenSignature can generated from a custom screen implementation inside the OTX-Mapping Editor

4. Bind the parameters of the ScreenSignature to the placeholders found in the HTML file via the OTX-Mapping Editor
5. Create the OTX-Mapping file
6. Set the OTX-Mapping file inside OTF and/or
7. Set the OTX-Mapping file inside OTX-Runtime

   Note: Before setting the mapping file the related custom implementation must be set, see IRuntimeManager.SetCustomImplementation

Important: An external application and all its dependencies must exist in ExternalAppPath!

Note: The user can also implement its own custom implementations with OTX-Mapping!

Note: If the user uses the OTX-Runtime API the custom implementations must integrated, see Integration. If the user uses the OTX Development Environment the integration is already done.

Own Custom Implementations with OTX-Mapping

The usage of the OTX-Mapping in own custom implementations is optional but recommended. To use the OTX-Mapping inside own custom implementations, the related interfaces for the different OTX-Mappings must be implemented, see table below.

Mapping	Interface	Root Object	Parameter	Description
ScreenMapping	ICustomScreenImplementation	IScreenHandle	IScreenParameter	HMI custom screens which can be opened via OpenScreen
DeviceMapping	IMeasureImplementation	IDeviceService	IDeviceServiceParameter	Measure device services which can be executed via ExecuteDeviceService
ServiceProviderMapping	IExternalServiceProviderImplementation	IServiceProvider	IExternalParameter	ExternalServiceProvider service which can be executed via ExecuteService
ContextMapping	IContextVariableImplementation	IStateVariable	n.a.	Context variables which value can get via GetValue
StateMapping	IStateVariableImplementation	IContextVariable	n.a.	State variables which value can set via SetValue

Properties to be Handle

The information related to OTX-Mapping will be provided by the OTX-Runtime API and must be also managed by the own custom implementation. The table below lists all available properties related to OTX-Mapping.

Important: The OTX-Runtime API only provides the mapping information from the selected OTX-Mapping file. The handling of this information is task of the related CustomImplementation!

Important: All root objects and parameters which have no mapping (empty MappingName) should be ignored!

Property	Scope (see table above)	Description
AppId	Root Object	Gets the Id of the mapped external application. The id identifies the external application inside the mapping file. The Project Setting "Settings.Runtime.ExternalApps" gets a map of all AppIds and the name of the related binary file.
MappingName	Root Object and Parameter	The mapping name is the full qualified name of the element inside the external system, which is mapped to the OTX element. It contains all namespace elements separated by dots (".").
MappingIndex	Parameter	An OTX parameter can be mapping a list element of property inside the external application. This property contains the related index.

Special Literal Parameters

An own custom implementation must handle all parameters which are related to OTX-Mapping, see above. But there are some special parameters, the so called literal parameters, which must be handled too:

• IScreenLiteralParameter
• IDeviceServiceLiteralParameter

A literal parameter exists inside the external system but does not exists in the related OTX Signature. A literal parameter represents a parameter of an external object like a screen or a device, which will be set to a fix (literal) value, if it is mapped to a literal inside the mapping file, see OTX-Mapping Editor.

OTX-Mapping Editor

The OTX Mapping-Editor is part of the OTX Development Environment and can be also executed stand-alone. Inside the OTX mapping editor all mapping can be created and edited graphically as follows:

1. Add the external application to the mapping, see (1)

   Note: An external application and all its dependencies must exist in ExternalAppPath.
   Note: All dependencies to an external application do not need to be added. But they must be exist in the same directory like the external application.

2. Create the mappings separately for screen, device, context, status and external service provider, see (2) and tabs Screen Mapping, Device Mapping, Service Provider Mapping, Context Mapping and State Mapping

   Note: The left part lists all valid elements found in the external application.
   Note: The right part lists the corresponding OTX elements.

3. Select two matching elements on the left and the right list, see (2) and (3)

   Note: Which elements matches is described above.

4. Clicked at the arrow between the two lists.

   Note: If a parent element is selected in the right part, a new OTX element can also be generated by clicking at the create arrow.

5. Optionally, specify environment settings which are not really available (simulation), see tab Environment value settings

   Note: For all not already mapped Signature InOut- or Out-parameters as well as context variables a certain value can be specified. During procedure execution the OTX runtime will set this parameter Value at the specified value.

Sample OTX-Mapping (OTF Solution)

A sample solution for the OTX Development Environment which shows the different kinds of OTX-Mapping can be found below:

OTF Sample Solution for OTX-Mapping with Player

Note: Unzip into the OTF projects folder and open the solution file (EmotiveSampleSolution\EmotiveSampleSolution.otfSln) inside OTF.

Note: The assembly (APP) must be copied into ExternalAppPath.

Note: The source code of the custom implementations can be found in folder \EmotiveSampleSolution\OtxMappingSample\OTX-Mapping.