Imprint Privacy policy Terms & Conditions Sitemap

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 ANALYZE configuration with the ANALYZE 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 ANALYZE. As default, Integrity items are labeled in ANALYZE 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 ANALYZE 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, ANALYZE 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.

When you first start ANALYZE with the adapter enabled, a dialog will ask you for a user name and password for the login. You can store this information in Eclipse’s Secure Store such that you don’t need to re-enter it later.

You can also provide the login credentials as java system properties PTC_INTEGRITY_USERNAME and PTC_INTEGRITY_PASSWORD. You can set these properties either directly via the the command line or in a configuration file that you specify with ANALYZE’s --properties command line option (see Executing ANALYZE in batch mode ). Alternatively, you can define environment variables with the same names.

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 analysis and how they are mapped to ANALYZE 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 ANALYZE 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 ANALYZE 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 ANALYZE 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 ANALYZE 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 ANALYZE

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

In the Integrity Client, mark and copy a set of items. On paste, ANALYZE 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 ANALYZE adds this item to the ANALYZE 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 ANALYZE 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”), ANALYZE notifies the user about such items. The user can turn off this notification.

Support of ANALYZE editor within PTC Integrity client

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

Configuration

To configure the PTC Integrity client to work with a running ANALYZE 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 analyze\integrity folder included in the root folder of your ANALYZE installation.

Copy the files IntegrityClientIntegration.jar, Set_A.png and Set_B.png 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 ANALYZE Editor integration it is necessary to configure three custom actions, one for Set A and Set B and a third one for Select.

  • 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 or --select: select the section of ANALYZE Editor where artifacts are added or specify, that the artifact should be selected
    • 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 ANALYZE is running on
  • -p PORT : port ANALYZE 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 ANALYZE 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 ANALYZE Editor by just clicking the toolbar buttons or menu actions in the PTC Integrity client. The link creation will be done within the ANALYZE Editor itself.

If there are any issues selected in the PTC Integrity client which can not be associated with any artifacts by ANALYZE, the following notification will be shown. This happens just in case ANALYZE 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 ANALYZE derives from PTC Integrity are based on the PTC Integrity data access. If PTC Integrity relations should be mapped to ANALYZE trace links, a mapping must be defined at the corresponding ANALYZE link types.

Supported keywords:

  • map – Starts a mapping block.
  • link source is A|B – Optionally specifies whether the link source in PTC Integrity should be artifact A or artifact B of the link type. By default it is A, which means that a link in PTC Integrity from an element X to an element Y will result in a link in ANALYZE from A to B. If you define the link source to be B, the same link in PTC Integrity from X to Y will result in a link in ANALYZE from B to A.

Example:

map to "Validated By"
link source is B

In the above example, trace links from PTC Integrity are mapped to ANALYZE links using the PTC Integrity attribute Validated By. Because of link source is B, the link is evaluated in opposite direction, i.e., the item in PTC Integrity that is the source of Validated By corresponds to link end B in ANALYZE.

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 → ANALYZE → Adapters.

Polarion Pure::Variants