PTC Integrity

Data access

The PTC Integrity data access provides access to documents being hosted by PTC Integrity as traceable artifacts. A reliable connection to the server is needed.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select PTC as data access type.

Supported keywords:

  • server – Defines which server is to be used.
  • port – Defines which port is to be used.
  • secure true / secure false – Defines whether the connection should use a secure communications protocol – please refer to PTC Integrity documentation for details. The keyword is optional, default is secure false.
  • undefined attribute value = – Defines the value which is assumed for a field if no field with a configured name exists. The default is „...”.
  • fields for {} – Defines the attributes of a PTC item which are taken into account to represent the item in YT. As default, Integrity items are labeled in YT with ID and summary or (if summary is empty) with ID and text.
    • contains (inside fields for) – Defines the reference defining the containment reference in the document structure. Default is contains.
    • summary (inside fields for) – Defines the field defining the summary. Default is summary.
    • text (inside fields for) – Defines the field defining the text. Default is text.
    • document id (inside fields for) – Defines the field containing the document id. Default is document id.
    • suspect count (inside fields for) – Defines the field containing the suspect count for items with suspect links. Default is Suspect Count.
  • projects – Defines which projects are to be imported.

Within the configuration panel, further configuration is required. Below you can see a sample configuration which will be described subsequently.

Sample data access configuration:

server "ptc.itemis.de"
port 7001
secure false
projects {
  "/Pedelec"
}

The connection to the PTC Integrity server is configured here. In the above example the connection to the server is defined by the hostname ptc.itemis.de and the server port 7001. A secure connection is not configured, but the option secure can be set to true, if the server supports secure connections. Integrity items are represented in YT by their text attribute.

Furthermore, the PTC Integrity projects to be considered should be listed here.

Hint: The editor supports you during the selection of projects and also during the selection of PTC item types during configuration of relevant artifacts. Entering [Ctrl]+[Space] in the projects section shows a list of projects that are available on the server. In order to retrieve this information, YAKINDU Traceability must be connected to PTC Integrity. The connection is established on save. Thus, we recommend an intermediate saving of the configuration after entering server and port.

Prerequisites

The PTC Integrity adapter requires the manual installation of the mksapi.jar file. By default a dialog is shown which will help installing the file. The mksapi.jar file can be found on the PTC Integrity server here:

  • /IntegrityClient10/lib/mksapi.jar
  • /IntegrityServer10/server/mks/lib/mksapi.jar

To prevent the dialog to appear or to prepare the installation, the mksapi.jar file can be copied manually into the plugin folder /plugins/com.yakindu.traceability.integrity.interface.lib_1.1.1/lib/.

Advanced data access configuration

For some PTC Integrity installations it is necessary to change the fields that are used as labels or the reference name for the document structure. This can be configured in the fields for section of the data access configuration. All fields have to be defined for all fetched items, including documents. At first, the summary field is used, and if not set the value of the text field is used. The contains reference is used to load the document structure of „Workflow and documents” in Integrity.

server "ptc.itemis.de"
port 7001
secure false
undefined attribute value = "..."
fields for {
    summary "summary"
    text "text"
    document id "document id"
    contains "contains"
}
projects {
  "/Pedelec"
}



Artifact type

The PTC Integrity adapter provides requirements hosted by PTC Integrity as artifacts. A sample configuration shows how the mapping works.

Configuration

Supported options:

  • map to type {…} – A block that defines which Integrity items are relevant for traceability and how they are mapped to YT artifact types.
  • name … – Define the expression to name an artifact.
  • if( … and … ) (inside map to) – Defines a boolean expression which is evaluated on Integrity items. If the evaluation result is true YT considers the Integrity item as a traceable artifact of the given artifact type. The expression may contain several attribute evaluations concatenated by the keyword and.
  • … to … (inside map to ) – Defines how attributes of YT artifacts should be populated with values from Integrity items' fields.
  • valueOf( fieldName) – Refers to the value of an Integrity field whose name is specified by fieldName.

Example:

map to "Requirement"
    if ("Category" = "User Requirement") 
    name valueOf("ID") + ":" + valueOf("Text")
    {
        "text" to "Text: " + valueOf("Text")
 }

In the above example, the YT artifact type is mapped to the PTC Integrity type Requirement if the Category attribute of the Integrity item is set to User Requirement. Artifacts name will be a concatenation of the ID and the Text. The if condition and the name parts are optional. Furthermore, the value of the PTC Integrity attribute Text is mapped to the YT custom attribute text, preceded by the static string „Text: ”. The attribute mapping is optional.

The if clause supports the operators =, !=, >, <, <=, >=, contains, doesNotContain.

Please note that depending on the attribute type some operators are not allowed by PTC Integrity, e.g., text fields (i.e., fields of type longtext, shorttext, fva, etc.) support contains and doesNotContain but not > or <.

Please also note that contains is a heuristic operator – refer to the PTC Forum for more information.

Loading the document structure

For artifacts which are structured in a document in Integrity, it is also possible to show the document structure in the search dialog. The document structure is not loaded by default, but must be requested for each project separately. This can be achieved via context menu of a document in the search dialog.

In this example, the artifacts of type User Requirement are saved in a document in Integrity. The first image shows the default hierarchy after initial load where artifacts are grouped by document. In the second image the hierarchy was loaded and the artifacts were re-ordered after the document structure was fetched.

Support of copy and paste from PTC Integrity to YAKINDU Traceability

In order to support fast link creation, YAKINDU Traceability supports copy and paste of artifacts from PTC Integrity to the YT Editor as described in the YT Editor chapter as follows:

In the Integrity Client, mark and copy a set of items. On paste, YT analyzes the clipboard content with respect to the configuration of the selected artifact type. If the ID of an item in the clipboard matches an item that is covered by artifact type configuration then YAKINDU Traceability adds this item to the YT Editor area.

Please note:
Not all versions of PTC Integrity support copying of items. If you cannot copy items with your PTC Integrity version we recommend to apply the support of YAKINDU Traceability within PTC Integrity.

Please also note:
If the clipboard contains artifacts that are not covered by the configuration of the artifact type (to put it crudely: The selection is „too large”), YAKINDU Traceability notifies the user about such items. The user can turn off this notification.

Support of YAKINDU Traceability editor within PTC Integrity client

Especially for users who are primarily working with the PTC Integrity client, YAKINDU Traceability supports an integration of YT Editor functionalities into the PTC Integrity client using custom actions.

Configuration

To configure the PTC Integrity client to work with a running YAKINDU Traceability instance, you have to configure a custom action within the view set of your current PTC Integrity client installation. Technically, a custom action is a program which is executed by the PTC Integrity client.

This program which will be configured in the following steps and can be found in the traceability\integrity folder included in the root folder of your YAKINDU Traceability installation.

Copy the files IntegrityClientIntegration.jar, Set_A.gif and Set_B.gif to any location you prefer, e.g., C:\IntegrityClientIntegration.jar etc. Open your PTC Integrity client, select ViewSet → Customize… from the menu bar, and choose the Actions tab. Within the tree on the left side choose Custom.

After the custom item is selected a list of possible custom actions becomes visible on the right side of the details view. Custom actions are bound to predefined keyboard shortcuts and you can configure whether the custom action should also be visible in the menu or in the toolbar. If you wish to use custom buttons, the drop-down must be set to Visible, on Toolbar.

By clicking Edit next to a free action, you will get to a custom action configuration dialog where at least the parameters mentioned below should be configured.

Please note:
To use the full YT Editor integration it is necessary to configure two custom actions, one for Set A and another one for Set B.

  • Name: the name of the action, e.g., Add to A
  • Program: the full path to your local Java executable, e.g., C:\Program Files\Java\jdk1.8.0_45\bin\javaw.exe
  • Parameters: the following parameters are passed to the executed Java program:
    • -jar PATH_TO_YT_CLIENT_JAR
    • -s A|B : select the section of YT Editor where artifacts are added
    • Sample -jar „C:\IntegrityClientIntegration.jar” -s A
  • Optional
    • Icon File: custom action icon, absolute path on local machine

Optionally the following parameters are available:

  • -h HOST : host YT is running on
  • -p PORT : port YT is listening on
  • -ce: keeps the command-line window open; makes sense if java.exe is used instead of javaw.exe
  • -logLvl OFF|FATAL|ERROR|WARN|INFO|DEBUG|TRACE|ALL|DEV : log output level
  • -logFile ABSOLUTE_FILE : log file

If the actions are configured it is necessary to ensure that YAKINDU Traceability is enabled. Find more information in section TCP Server.

Usage

Once the two custom actions are configured and the TCP Server is enabled as described in the previous section, it is possible to add issues selected in the PTC Integrity client to the A and B section of the YT Editor by just clicking the toolbar buttons or menu actions in the PTC Integrity client. The link creation will be done within the YT Editor itself.

If there are any issues selected in the PTC Integrity client which can not be associated with any artifacts by YAKINDU Traceability, the following notification will be shown. This happens just in case YT can not determine any artifact based on the current selection.

Prerequisites

The PTC Integrity adapter requires the installation of API files from the Integrity Server installation. See Prerequisites for details.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is the item’s modified date.

The trace links YT derives from PTC Integrity are based on the PTC Integrity data access. If PTC Integrity relations should be mapped to YT trace links, a mapping must be defined at the corresponding YT link types.

Supported keywords:

  • map – Starts a mapping block.

Example:

map to "Validated By"

In the above example, trace links from PTC Integrity are mapped to YT links using the PTC Integrity attribute Validated By. It is defined at the PTC item type which is mapped to the YT artifact type of link end A.

Links of this type are suspicious if the corresponding suspicious flag on the PTC Integrity server is true.

Working without view admin rights

If a user has no viewAdmin rights in Integrity, some commands need to be restricted to visible data only. This can lead to incomplete data, like fields not available for attributes or missing links or artifacts. If you have no viewAdmin rights in Integrity you need to disable „Integrity: Work with view admin rights” in Window → Preferences → YAKINDU Traceability → Adapters.