Skip to main content

Jama Connect

The Jama adapter supports extraction of traceability information – items and relationships – from projects (and optionally baselines) of a Jama Connect installation. The adapter communicates with the Jama server via the Jama REST API.

Data access​

The Jama data access configuration specifies the Jama Connect server to connect to and the projects – optionally pinned to baselines – from which ANALYZE will load items and relationships.

Configuration​

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

Supported keywords:

  • host – The host name of the Jama Connect server, without scheme and port, e.g., "mycompany.jamacloud.com". This is the only mandatory connection setting.
  • port – Optional port number. Defaults to 443 for secure connections (*ssl true*) and 80 for non-secure connections (*ssl false*).
  • ssl true / ssl false – Optional. Defines whether the connection uses HTTPS (*true*) or HTTP (*false*). Default is true.
  • rest-api-path – Optional path of the Jama REST API on the server. Default is "/rest/v1".
  • projects { … } – Defines the project(s) from which ANALYZE loads items and relationships. Each project entry consists of:
    • key – The project key of a Jama project, e.g., "PROJ", or
    • name – The name of a Jama project. Use either key or name per project entry.
    • baseline-key / baseline-name – Optionally, for the project, select only this specific baseline, identified either by its baseline key or by its name.

Sample configuration:

host "mycompany.jamacloud.com"
port 443
ssl true
rest-api-path "/rest/v1"
projects {
  key "PROJ-A" baseline-key "BASE-21"
  name "My Second Project"
}

In the example above, ANALYZE connects via HTTPS to the Jama Connect server at mycompany.jamacloud.com, port 443, using the REST API at /rest/v1. ANALYZE considers the items of the baseline with key BASE-21 of the project with key PROJ-A, plus the current (head) items of the project named My Second Project.

The configuration editor offers content assist ([Ctrl]+[Space]): once a connection to the server can be established, the editor proposes the available project keys, project names, baselines, item type keys/names, relationship type names and even item paths. Likewise, the editor validates configured project keys/names and baseline keys/names against the server and marks unknown values with an error.

note

Validation and content assist require an open connection to the Jama server. The connection is established when the configuration is saved (or when data is loaded). We recommend an intermediate save of the configuration after entering the connection settings.

Baselines​

If a baseline-key or baseline-name is specified for a project, ANALYZE loads the item versions contained in that baseline instead of the current (head) item versions. If no baseline is specified, the current items of the project are loaded.

Credentials (OAuth)​

The Jama adapter authenticates against the Jama REST API using OAuth 2.0 client credentials ("machine-to-machine" flow): instead of a user name and password, you provide a client ID and a client secret. You can create these in Jama Connect in your user profile under Set API Credentials – please refer to the Jama Connect documentation for details. The adapter obtains access tokens from the server's token endpoint /rest/oauth/token and renews them automatically.

The credentials are looked up in the following order:

  1. Credentials that have already been verified for the same host in the current session.
  2. Java system properties or environment variables JAMA_LOGIN_CLIENT_ID and JAMA_LOGIN_CLIENT_SECRET (both must be set).
  3. Eclipse's Secure Store.
  4. An interactive login dialog.

When you first start ANALYZE with the adapter enabled and no credentials are available, a dialog will ask you for the client ID and the client secret. You can store this information in Eclipse's Secure Store such that you don't need to re-enter it later. If a login attempt fails, the stored credentials are marked invalid and the dialog is shown again.

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

For batch execution, the login dialog can be disabled by setting the system property or environment variable JAMA_CREDS_USE_DIALOG to false. In this case the adapter only uses credentials from system properties, environment variables, or the Secure Store, and reports an error if none are available or valid.

Artifact type​

The Jama adapter allows for flexible artifact configuration to specify which Jama items itemis ANALYZE should import from the Jama data access, and how their fields are mapped to artifact names and custom attributes.

Configuration​

Open the ANALYZE configuration with the ANALYZE configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Jama data access in the Data access drop-down list.

An empty configuration is valid: in that case all items of the configured projects/baselines are imported, with a default name of the form <id> : <name> (<item type>).

Supported keywords:

  • subset item-type-key – Restricts the imported items to those of the Jama item type with the given type key, e.g., "REQ".
  • subset item-type-name – Restricts the imported items to those of the Jama item type with the given display name, e.g., "Requirement".
  • subset path – Restricts the imported items to those whose location in the Jama project tree starts with the given path. The path consists of the names of the containing sets/folders separated by "/", e.g., "My Project/Requirements/System". Content assist proposes the available paths.
  • include items if ( constraint ) – An optional additional filter ("field filter"). Only items satisfying the constraint are imported. See below for the constraint syntax.
  • name – Optional expression defining the name of the artifacts. It may concatenate string literals and valueOf(…) field references with +. If omitted, the default name described above is used.
  • map { … } – Optional block mapping custom attributes of the artifact type to expressions over the item's fields, e.g., myAttribute to valueOf("status").
  • valueOf("_fieldName_") – References the value of an item field, see below.

Example:

subset item-type-key "REQ"
subset path "My Project/Requirements"
include items if ( valueOf("status") == "Approved" and valueOf("priority") in ("High", "Medium") )
name valueOf("documentKey") + ": " + valueOf("name")
map {
  status to valueOf("status")
  location to valueOf("location-path")
}

In the example above, ANALYZE imports only items of the item type with key REQ that are located below My Project/Requirements and whose status field is Approved and whose priority is High or Medium. The artifact name is built from the item's document key and name. The custom attributes status and location are populated from the item's status field and from its location path.

Subset and filter semantics​

Several subset statements and the include items if filter can be combined. They are evaluated as follows:

  • Multiple subset item-type-key / subset item-type-name statements are combined with a logical OR: an item matches if its item type matches any of the configured item types.
  • Multiple subset path statements are combined with a logical OR: an item matches if its location path starts with any of the configured paths.
  • If both item type subsets and path subsets are configured, they are combined with a logical AND: an item must match one of the item types and one of the paths.
  • The include items if constraint is combined with the subsets with a logical AND: an item must match the subsets and satisfy the constraint.

The constraint inside include items if ( … ) has the form valueOf("<fieldName>") <operator> <value(s)>. Multiple constraints can be combined with && / AND / and (logical and) and || / OR / or (logical or). Supported operators:

  • == – Equality check.
  • != – Inequality check.
  • contains – Substring check.
  • contains_not – Absence of a substring.
  • in – Matches if the field value equals one of the values in the list, e.g., valueOf("status") in ("Approved", "Released").
  • not_in – Negation of in.
note

A subset item-type-key, subset item-type-name or subset relationship-type-name value that does not exist on the server filters out all items or relationships of that subset and is reported as an error in the configuration editor and in the log.

Fields available in valueOf​

Within name, map and include items if expressions, valueOf("_fieldName_") refers to a field of the Jama item. You can use any field name of the item as defined in Jama (including custom fields), e.g., "name", "description", "status". In addition, the following special field names are supported:

  • id – The item's ID.
  • documentKey – The item's document key, e.g., PROJ-REQ-42.
  • globalId – The item's global ID.
  • itemType-key – The key of the item's type, e.g., REQ.
  • itemType-display – The display name of the item's type, e.g., Requirement.
  • project-key – The key of the project containing the item.
  • createdDate, modifiedDate, lastActivityDate – The respective timestamps of the item.
  • version – The item's version number.
  • type – The item's REST entity type (usually items).
  • location-path – The names of the sets/folders containing the item, separated by "/".
  • location-ids – The IDs of the sets/folders containing the item, separated by "/".

Content assist ([Ctrl]+[Space]) inside valueOf( proposes the special fields and the fields of the configured item types. The editor validates field names against the item types configured in the subset statements and marks unknown field names with an error.

Version​

An artifact's version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

The Jama adapter allows to derive ANALYZE links from Jama relationships. Make sure artifact types have been configured before.

Open the ANALYZE configuration with the ANALYZE configuration editor, and add a new link type as described in section "Configuring a link type".

An empty configuration is valid: in that case all relationships between imported artifacts are loaded as links.

Supported keywords:

  • subset relationship-type-name – Restricts the loaded relationships to those of the Jama relationship type with the given name, e.g., "verifies". Multiple subset relationship-type-name statements are combined with a logical OR. Content assist proposes the relationship type names available on the server, and configured names are validated against the server.
  • map { … } – Optional block mapping custom attributes of the link type to expressions over the relationship, e.g., relType to valueOf("typeName"). For relationships, valueOf supports the field names typeId (the numeric ID of the relationship type) and typeName (the name of the relationship type).
  • link source is A|B – This optional statement specifies the association source in Jama. If the configured project contains a relationship from an item X to an item Y, ANALYZE will usually (i.e., without link source statement) create a link from the artifact representing X to the artifact representing Y. The statement link source is B turns this around: a Jama relationship from X to Y will be loaded as a link from the artifact for Y to the artifact for X. You can specify link source is A, but this is equivalent to an empty configuration, because it just defines the default behavior.

Example:

subset relationship-type-name "verifies"
subset relationship-type-name "satisfies"
map {
  relType to valueOf("typeName")
}
link source is B

In the example above, ANALYZE loads only relationships of the Jama types verifies and satisfies, stores the relationship type name in the link attribute relType, and reverses the link direction.

note

A link is only created if both ends of the Jama relationship have been imported as artifacts via the configured Jama artifact types. Relationships whose source or target item is not covered by the artifact type configuration are skipped.

Links of this link type will never become suspicious.

Opening artifacts in Jama Connect​

ANALYZE associates each imported artifact with the URL of the corresponding item in the Jama Connect web application, so that the item can be opened in a web browser from ANALYZE.