FAQ: OSLC Links Package

Answer

By default, the linkage action between ClearQuest and other OSLC clients/providers (DOORs, RTC, etc) occurs in the following series of steps, assuming the initial oAuth, cross site, and project configurations are correctly established:

1. The user modifies a CQ record, and adds or deletes one of more OSLC links, then saves the CQ record.
2. The ClearQuest record, along with the oslc forward link is saved. Next, the backlink to ClearQuest (on the friend OSLC server) is attempted to be saved, in a separate thread. Because this operation can fail (for example due to a conflict in modifying the CQ record), you can end up with a situation where the forward link from CQ outward to the OSLC provider exists, but the backlink into CQ does not exist. OSLC providers should handle these failures or have a plan to mitigate the discrepancies if the back links are significant to the business.
3. Starting in the 9.0.1.03 patched release of CQ, there is an option to prohibit ClearQuest Web from saving a record unless the OSLC backlink creation is successful [APAR PM68302]:
   
   The following option can be set in cqSiteConfig.pref as follows, along with others in the "currentValue" section:
   appOpt$failCommitIfBacklinkCreationFails": "yes",
   
   When this option is set, ClearQuest will wait for a positive or negative response from the OSLC friend before the CQ record will be saved. This can negatively impact performance since ClearQuest will wait for a response from the OSLC provider before saving. Having this option set makes it far more unlikely that you will have CQ records with OSLC links that are missing backlinks.
   
   Example path for preferences file:
   C:\IBM\RationalSDLC\ClearQuest\cqweb\cqwebprofile\installedApps\dfltCell\TeamEAR.ear\cqweb.war\WEB-INF\config\cqSiteConfig.pref
   

About the OSLC Links Package:
When applying the OSLC Links 1.2 package to a schema it introduces the OSLCLink stateless record type:

Fields:

oslcl_label (SHORT_STRING)
oslcl_link_type (SHORT_STRING)
oslcl_URI (MULTILINE_STRING)

Actions:
Submit, MODIFY, Delete, all with [Action Access Control hook: calls global hook: OSLC_Is_OSLCLink_Editable(), which checks if _OSLC_LINK_UPDATE session variable is set to 1 (true). This normally only gets set by a supported integration. Import has no restrictions. Error returned if session variable not set (fail Action Access Control).]

The following will occur when the package is applied to specific record types:
Fields:

oslc_links (REFERENCE_LIST) [Field value changed hook: If _OSLC_LINK_UPDATE session variable set to true (by integration), remove duplicated links, error if failure removing duplicates.]
oslc_cm-inprogress (INT) [Default value of 0] [Choice List values: 0,1]
oslc_cm-reviewed (INT) [Default value of 0] [Choice List values: 0,1]
oslc_cm-approved (INT) [Default value of 0] [Choice List values: 0,1]
oslc_cm-verified (INT) [Default value of 0] [Choice List values: 0,1]
oslc_cm-fixed (INT) [Default value of 0] [Choice List values: 0,1]
oslc_cm-closed (INT) [Default value of 0] [Choice List values: 0,1]

(All of these oslc_cm field values are state predicates that are offered by the OSLC CM specification and can be queried if values are set, for example oslc_cm:verified ).

Actions:
OSLC_Modify_Links (Modify) [Action Access Control: checks global hook: OSLC_Is_OSLCLink_Editable(), which checks if _OSLC_LINK_UPDATE session variable is set to 1 (true). This normally only gets set by a supported integration. Error returned if session variable not set (fail Action Access Control).]
OSLC_Base_Commit (Base) [Action Commit hook:
If a link removal is attempted, check each link and only permit if ALL links are of type "relatedArtifact", otherwise receive error: "You must remove all related links specified on the Links tab before you can delete this record."
If (both the record type of this entity and OSLCLink have security context enabled)

AND If (either value of the security context fields of this entity OR the value of field "oslc_links" has changed),
then make editable, otherwise, is not editable.

If security context changed, modify the underlying OSLCLink to update the underlying security context of that link.]

OSLC_State_Predicates (Base) [Action Initialization: set OSLC_CQ_State_Mapping($entity, "Initialization")], [Action Validation: set OSLC_CQ_State_Mapping($entity, "Validation")]

Note:
Certain integrations require OSLC to CQ state mapping and refer to these directions:
https://www.ibm.com/support/knowledgecenter/en/SSSH5A_9.0.1/com.ibm.rational.clearquest.integrations.doc/topics/t_clm_int_oslclinks_pkg_apply_proc.htm

Directions instruct creation of a Global Script "OSLC_CQ_State_Mapping":

sub OSLC_CQ_State_Mapping {
   my ($myentity, $hook_type) = @_;
   my $state = $myentity->GetFieldStringValue("State");
   
   if ($hook_type eq "Validation") {
   
       if (($state eq "Assigned") || ($state eq "Opened")) {
           $myentity->SetFieldValue("oslc_cm-inprogress", "1");
       } else {
           $myentity->SetFieldValue("oslc_cm-inprogress", "0");
       }
       
       if ($state eq "Closed") {
           $myentity->SetFieldValue("oslc_cm-closed", "1");
           } else {
           $myentity->SetFieldValue("oslc_cm-closed", "0");
       }

# For DOORs integration also add these two additional predicates per : http://www.ibm.com/support/docview.wss?uid=swg21456993#III.3.%20Configuring%20an%20existing%20r :
        if ($state eq "Resolved") {
            $myentity->SetFieldValue("oslc_cm-approved", "1");
            } else {
            $myentity->SetFieldValue("oslc_cm-approved", "0");
        }

        if ($state eq "ReadyToReview") {
            $myentity->SetFieldValue("oslc_cm-fixed", "1");
            } else {
            $myentity->SetFieldValue("oslc_cm-fixed", "0");
        }
   }
}

The above global script is called by the initialization and validation hook of the OSLC_State_Predicates action of a Defect record. The script has two parameters: the current entity and the hook type. Depending on your requirements, you can add different code according to the value of the hook type parameter. The example script shows a validation hook.

There is detailed discussion on how to enable security context and an access policy for being able to modify OSLC links in this technote section: "Procedure for configuring security context".

Reference:
https://www.ibm.com/support/knowledgecenter/en/SSSH5A_9.0.1/com.ibm.rational.clearquest.integrations.doc/topics/c_clm_int_oslclinks_schema_chgs.htm