Using Connector API

OSLC Links validators

OSLC Connect for Windchill provides a set of OSLC Links validators that can be used in Workflow management or Lifecycle Event listeners. The goal is to test the value of a property on a remote artifact.

There are 3 different validators:

Criteria matches on at least one OSLC link
Criteria matches on all OSLC links
Criteria matches on no OSLC link

The main class to access the validators is OslcPropertyValidator which has 3 methods:

OslcPropertyValidator.oneLinkMatcher(primaryBusinessObject)
OslcPropertyValidator.allLinksMatcher(primaryBusinessObject)
OslcPropertyValidator.noneLinkMatcher(primaryBusinessObject)

The primaryBusinessObject parameter expected is the Part or the Change Object (extending the wt.fc.WTObject abstract class) on which to apply the criteria.

The matcher will then allow to validate the criteria on a specific link type or on all of them:

OslcPropertyValidator.oneLinkMatcher(primaryBusinessObject)
		     .validateForLinkType("http://open-services.net/ns/cm#implementsRequirement", "status", "approved");

OslcPropertyValidator.oneLinkMatcher(primaryBusinessObject).validate("status", "approved");

The matchers will return the response as a WorkflowFeedback object containing error messages if something went wrong or if the criteria is not validated. The OslcPropertyValidator also exposes a class allowing to format the WorkflowFeedback as a String if it is to be displayed in Workflow activities.

It is to be noted that, in workflow activities, Java classes must be prefixed with the package name as no import statement can be used. To keep examples readable i did not include the package name.

com.sodius.oslc.app.wc.server.process.workflow.OslcPropertyValidator

com.sodius.oslc.app.wc.server.process.workflow.WorkflowFeedback

The following example shows how the WorkflowFeedback object can be used in a workflow activity (the result variable is the system variable used by Workflows to trigger routing):

WorkflowFeedback feedback =  OslcPropertyValidator.oneLinkMatcher(primaryBusinessObject)
						  .validateForLinkType("http://open-services.net/ns/cm#implementsRequirement", "status", "approved");

if (feedback.hasErrors()) {
	result = "KO";
	oslcReview = OslcPropertyValidator.formatFeedbackToString(feedback);
} else {
	result="OK";
}

The WorkflowFeedback object will also contain, as information messages:

The result of the criteria matching on all links tested (only the lines starting with INFO or ERROR in the following example are from the WorkflowFeedback messages).
The list of matching and non-matching links (feedback.getMatchingUris() and feedback.getNonMatchingUris()).

Interacting with a remote resource

Using generic `OslcPropertySetter`

The class OslcPropertySetter<T extends IExtendedResource> is to set properties on a set of remote resources. It has 2 constructors:

OslcPropertySetter(URI resourceUri, Class<T> type)
OslcPropertySetter(List<URI> resourceUris, Class<T> type)

The type parameter is the OSLC type of the remote resource: For example ChangeRequest.class, Requirement.class....etc

There are 2 ways for the class to update a resource:

Build the list of properties using the method provided by the class.
Use a consumer passed as a parameter to perform the updates.

Using dedicated method to build the properties list

After the call to the OslcPropertySetter constructor, you can call the property method to set the properties to update:

property(String namespace, String name, Object value)

You must provide the namespace and the name of the property to update, then call the updateArtifact() method to perform the update(s).

Using a consumer to update the artifact(s)

The method updateArtifact can be called passing a Consumer<ResourceType> as a parameter. You will have to specify the properties to update, because the only operation performed by the method will be to execute the consumer on each of the artifact URIs passed to the constructor. No additional operation will be performed. Example with a ChangeRequest resource type:

Consumer<ChangeRequest> action = artifact -> {
			artifact.setTitle("Windchill Validation");
			artifact.getExtendedProperties().put(new QName(namespace, property), value);
		};
oslcPropertySetter.propertyUpdater(artifactUri).updateArtifact(action);

Using Jira CM specific `OslcJiraCmPropertySetter`

To simplify the use of OslcPropertySetter the class OslcJiraCmPropertySetter is to set properties on a set of Jira CM resources. It has 2 constructors:

OslcJiraCmPropertySetter.propertyUpdater(URI resourceUri)
OslcJiraCmPropertySetter.propertyUpdater(List<URI> resourceUris)

Using methods to build the properties list

After the call to the OslcJiraCmPropertySetter constructor, you can apply methods to set the properties to update:

property(String namespace, String name, Object value): you must provide the namespace and the name of the property to update
nativeProperty(String name, Object value): updates a native Jira property, http://atlassian.com/ns/cm# namespace
customProperty(String name, Object value): updates a custom Jira property, http://atlassian.com/ns/cm-x# namespace

Then call the updateArtifact() method to perform the update(s).

Like the OslcPropertySetter class you can pass a consumer to the updateArtifact(Consumer<ChangeRequest> action) method to perform the updates. When calling this method, the properties defined by method calls are not taken into account, only the consumer is executed.

In the following example the customfield_10200 custom property is updated. You can find the internal names of the custom fields in Jira's settings.

OslcJiraCmPropertySetter.propertyUpdater(artifactUri)
			.customProperty("customfield_10200", "Validated in Windchill")
			.updateArtifact();

Update the label native property:

OslcJiraCmPropertySetter.propertyUpdater(artifactUri)
			.nativeProperty("label", "WINDCHILL_VALIDATED")
			.updateArtifact();

Update the dcterms:title generic property:

OslcJiraCmPropertySetter.propertyUpdater(artifactUri)
			.property("http://purl.org/dc/terms/", "title", "Test Windchill Validation")
			.updateArtifact();

You can mix as many properties as you wish:

OslcJiraCmPropertySetter.propertyUpdater(artifactUri)
			.customProperty("customfield_10200", "Validated in Windchill")
			.nativeProperty("label", "WINDCHILL_VALIDATED")
			.property("http://purl.org/dc/terms/", "title", "Test Validation Windchill")
			.updateArtifact();

Creating a CM remote resource

The class OslcRemoteResourceCreation is to create a CM resource (ChangeRequest resource type) in a Jira remote project. You get an instance of the class by calling one of those 2 methods:

OslcRemoteResourceCreation.fromServiceProviderUri(serviceProviderUri, primaryBusinessObject)
OslcRemoteResourceCreation.fromResourceUri(resourceUri, primaryBusinessObject)

The Service Provider is the uri of the project in which the resource will be created. If the fromResourceUri(...) method is used, the class will look into the resource to find the Service Provider of the corresponding project.

After the call to the OslcRemoteResourceCreation constructor, 2 methods will allow you to define the remote resource to create:

createResource(LinkType linkType,String issueType)
createResource(LinkType linkType, Consumer<ChangeRequest> action)

Creating a resource by providing the Issue Type

If you call this method a minimal Change Request will be created of the given issue type and the title will be based on the Windchill artifact's title. Note that, as this functionality is designed to create a Jira Resource, the issue type is a native Jira one.

Creating a resource by providing a Consumer<ChangeRequest>

By calling this method you must provide all the required data to create the resource. Only the rdf:type ChangeRequest will be set on the resource, the rest will be set by the consumer.

Consumer<ChangeRequest> action = resource -> {
            resource.addDctermsType("Bug");
            resource.setTitle("Resource Title");};
OslcRemoteResourceCreation.fromServiceProviderUri(serviceProviderUri, primaryBusinessObject)
  			  .createResource(linkType, action);