Getting Started with OSLC integration

You can integrate TRIRIGA application with other applications by using Open Services for Lifecycle Collaboration (OSLC) REST API. IBM® TRIRIGA® provides an OSLC REST API as part of the on-premises IBM TRIRIGA Connector for Business Applications (CBA) license and the IBM Facilities and Real Estate Management on Cloud (TRIRIGA) Enterprise User license.

OSLC integration with IBM TRIRIGA is accomplished between a consumer application and TRIRIGA, the provider application. As the OSLC provider application, TRIRIGA makes its resource data available to the consumer application through containers, which are known as service providers. With the resource data made available, the consumer application can create links between its data and the resource data of TRIRIGA. You can configure and enable any part of TRIRIGA to act as an OSLC provider application.

Contents

I. Creating Prerequisites on TRIRIGA Server

To create and use the OSLC (Open Services for Lifecycle Collaboration) components that integrate with TRIRIGA, you must complete the following:
  • TRIRIGA Server
  • User with access to builder tools
  • Advanced REST Client that can be downloaded to Google Chrome
  • Buisness Object, Form, Query, and Navigation Item
Creating a Module
To create a module:
  1. Login to TRIRIGA and navigate to the Data Modeler.
  2. Click Home > Tools > Data Modeler.
  3. Click New and then select New Module.
  4. Specify the name of the module and then click Save Module.
Create a Business Object (BO)
To create a Business Object:
  1. In newly created module, click New and then click New Business Object.
  2. Speicfy the name of the Business Object and then click SaveBO.
  3. Add fields to the BO by either adding them manually or finding them from an existing BO. The fields added to the BO are triControlNumber (Control Number), triNameTX (Text), triDescriptionTX (Text), triRecordIdSY(System Read Only), triRecordNameSY (System Read Only), and triNumber (Number).
  4. Add a State Transition family:
    1. Click Tools > BO State Transition. Either set up or import the State Transition.
    2. To import the State Transition, click Import> Import From Business Object> triPeople for both Module and BO.
    3. Click Ok, and then click Save.
  5. Create BO Mapping:
    1. Click Tools > BO Mapping. In the following example, the BO mapping set it to show the ControlNumber, then a hyphen followed by Name. You can set it as per your requirement or choice.
    2. Click Save Mapping and then click Publish BO.
Create a Form
To create a module:
  1. Navigate to Home > Tools > Form Builder.
  2. Select the appropriate Module (amOSLCTutorial) and then click New.
  3. Select the appropriate BO in the Properties Window. In this example, only one BO amRecord is assigned to this module.
  4. Click Apply.
  5. Click Add Tab.
  6. Specify the name of the tab and then click Apply.
  7. On the newly created tab click Add Section, provide a name to the section, and then click Apply.
  8. Add the fields required for the form:
    1. On the section created in the previous step, click Add Field.
    2. In the Properties window, select a Data Field from the BO, and then click Apply. In this example, the following fileds are added to the form: fields triControlNumber, triNameTX, triDescriptionTX, and triNumber. The form should look something like this:
    3. Click Publish to publish the form.
Create Query
To create a query:
  1. Navigate to Home > My Reports.
  2. Click System Reports tab.
  3. Click New.
  4. Specify the name of the query.
  5. On the Business Object tab, click Add Business Object. On the form, select the Module, Business Object, and Form that were created in the previous steps and click OK.
  6. Click on the Columns tab. Add the fields from the form (ControlNumber, Description, Name, Number) to display in the query.
  7. Click Save & Close.
Add to Navigation Items
Create a navigation item to access the form and create new records:
  1. Navigate to Home > Tools > Navigation.
  2. Click Add to bring up Navigation Items Library, and then click Add.
  3. In the Navigation Item Editor window, specify the name of the item, and set the Target Type to Master/Detail Default Query.
  4. In the Form section, select the Module and Form created in the previous sections.
  5. In the Action section, add actions to create, update, or delete records, and then click Save & Close.
  6. Select the menu to add the navigation item.
  7. Click Navigation Items Library, search the recently created Navigation Item, and then Save & Close.
  8. Add records to the navigation item by clicking Home > Tools > System Setup.

II. OSLC on TRIRIGA Server

Creating an OSLC Resource for the BO

Create an OSLC resource for the Business Object. The resource is data that can be identified by a URI.

To create an OSLC resource:
  1. Navigate to Home > Tools > System Setup > Integration > OSLC Resource Manager.
  2. Click Add.
  3. Specify the ID, Resource Name, and Title.
  4. In Namespace the prefix "spi" is used which has the base of http://jazz.net/ns/ism/smarter_physical_infrastructure#. The namespace is used to provide unique name to the fields but does not change any logic. You can use any namespace or create your own.
  5. In the Module drop-down menu, select the module that was created earlier. The corresponding BO, Form, and Query created in previous section are now available for selection.
  6. In the Properties section, click Import All Fields to set up the fields for the resource based on the BO fields.
  7. After the import is completed, click Create.
Creating an OSLC Service Provider

A service provider contains the resources that allow use of the resource. This also includes the creation factory and query capability.

To create a Service Provider:
  • Navigate to Home > Tools > System Setup > Integration > OSLC Manager.
  • Click Add.
  • On the Service Provider creation form, specify a name, and then click Create.
Creating an OSLC Service
To create an OSLC service:
  1. Open the Service Provider created in the previous section.
  2. Under the Service section, click Add.
  3. In the new form name the service and set the domain to match what is set in the resource: http://jazz.net/ns/ism/smarter_physical_infrastructure#.
  4. Click Create.
Creating OSLC Query Capability (QC)

The query capability allows to create a base URI that can be used to query the resources easily.

To create OSLC Query Capability:
  1. In the Query Capabilities section of the service form, click Add to bring up the Query Capability form.
  2. In the Resource section, click Find.
  3. Select the OSLC Resource that was created earlier and then click OK.
  4. In the General section, specify a name and title.
    Note: If you want to override the query that is added to the resource, you can select the query from the Query drop-down menu. In this example, the query is already added to the resource. So the Query field can be left blank.
Creating OSLC Creation Factory (CF)

Creating a creation factory proivdes a URI which can then be used to create new records for resources.

To create a creation factory:
  1. In the Creation Factories section of the service form, click Add.
  2. In the Resource section, click Find.
  3. Select the OSLC Resource that was created earlier and then click OK.
  4. In the General section, specify a name and title.

III. Using Advanced REST Client

In this topic, the Advanced REST Client is used and can be downloaded from the Chrome web store. You can use any client for the steps explained in this section. Ensure to create a few records on the TRIRIGA server before you follow these steps.
Important:
  • The commands used in this guide follows this format: http://TRIRIGAServerURL:port/context. The TRIRIGAServerURL, port, and context must be replaced with appropriate values based on your TRIRIGA server.
  • To receive responses that include URI's that you can directly use with the REST Client, you must first set the OSLC_BASE_URI property in the TRIRIGAWEB.properties file. You can find the TRIRIGAWEB.properties file in your TRIRIGA install directory in the config folder. Set the OSLC_BASE_URL property to http://TRIRIGAServerURL:port/context/oslc, save this file, and then restart your TRIRIGA server.
Query All Records using QC
The first command used involves GET command by using the Query Capability that is created in the previous section. Select the GET option, and then enter your in the appropriate format. For example, the command used is http://triqaapp13.tivlab.usnv.ibm.com:12001/sqa/oslc/spq/RecordQC. Replace the appropriate values in the command: http://TRIRIGAServerURL:port/context/oslc/spq/RecordQC and then click Send. You are prompted to enter credentials to sign on to the TRIRIGA server. Specify the same username and password that you use to login into TRIRIGA.
Query all the records

After running the command, you might see that the status is 200 OK. It means the command ran without any errors. Scroll down to see the result in the Response section. The results of the query that was run is displayed. The records that are created are displayed as resources in the command section.

The query can also be expanded by using oslc.select and oslc.where. To see the names assigned in the records, oslc.select can be used for viewing the field values in the query. For example, running a GET command on http://TRIRIGAServerURL:port/context/oslc/spq/RecordQC?oslc.select=* shows all the fields in the response for all the records. You can also display a specific field by replacing the “*” with a specific field to return all the records with that field. To get all the names assigned in the records, run GET on:http://TRIRIGAServerURL:port/context/oslc/spq/RecordQC?oslc.select=*.
Query specific records

You can query a specific field value to return any record that makes mention of the field by using oslc.where command. For example, you can run a query on all records with the word “TRIRIGA” anywhere in its description by running GET on the following URI: http://TRIRIGAServerURL:port/context/oslc/spq/RecordQC?oslc.select=*&oslc.where=spi:triDescriptionTX="%25TRIRIGA%25

The following attributes can be used for displaying information.
  • oslc.where=spi:triDescriptionTX="%25TRIRIGA%25: Displays any records that have “TRIRIGA” anywhere in the description.
  • "%25string%25" = string anywhere in the field
  • "%25string" = string ends the field
  • "string%25" =string starts the field.
Query description

For more information, see OSLC resources.

View a Record
You can view one of the specific records after running the query from the previous section which shows a list of all the records of this type with their unique URI indicated by rdf:about. If you run a GET command on any of these URI, a list with details is displayed. On Advanced REST Client, you can also click on the URI to set it. For example, running the GET command onhttp://triqaapp13.tivlab.usnv.ibm.com:12001/sqa/oslc/so/amRecordRS/20029512 provides the response with the information from the record with the “specId=20029512”. If you click Send, a response is provided with all the information gathered about the record.
View record

All the fields that were defined in the resource including triNumber and triNameTX are displayed in the response. You can also use oslc.properties to specify the fields you want to see in the results. For example if you want to just get the triNumber field, you can run GET on: http://TRIRIGAServerURL:port/context/oslc/so/amRecordRS/20029510?oslc.properties=spi:triNumber

Create Record using POST
To create a new record, use a POST command by using the creation factory that is set up. Before sending the request, first set up the header and request body (payload). The header only needs two things:
  • The Accept field is used to determine what file formats the browser is trying to get.
  • The Content-Type field helps determine how to use the data being received:
    • Header: Accept: application/json
    • Content-Type: application/json;charset=utf-8
The request body allows to specify the action (State Transition) you want to perform on the record and also set the field values. For example: {"spi:action":"Create Draft","spi:triNameTX":"Tom Tommyson", "spi:triNumber": "42", "spi:triDescriptionTX":"This record was made using the advanced rest client" }. This would create a draft for a record with the triNameTX field set to “Tom Tommyson”, the triNumber field to 42, and the triDescriptionTX field to “This record was made using the advanced rest client”.
You can create a record by running POST on: http://TRIRIGAServerURL:port/context/. The status displays 201 Created. You can check to see if this record has is created with the details that you have specified in the request body. One way to do this is to run the query capability again. Ensure to set the command type back to GET if you are running this query. However simply running this command displays all the records and you might be unable to identify the newly created record. To resolve this problem, you can also use oslc.select command to get the exact record details. So you can write a GET command such as: http://TRIRIGAServerURL:port/context/oslc/spq/RecordQC?oslc.select=spi:triNameTX.
Create record
You can then view the record by running a GET command on this new record. In this exampl, you can run a GET command on: http://triqaapp13.tivlab.usnv.ibm.com:12001/sqa/oslc/so/amRecordRS/20029512. The results in the response display the values that are specified in the record.
View newly created record
Update using PUT
The PUT command can also be used to to update an existing record.
Note: Records that are in the read only state cannot be updated by using the PUT command due to their BO state transitions. You must change the state of these records in the ediatble state to update these records.

Use a record that is can be updated by using the PUT command. The newly create record in the previous section is in the draft state and is not in the read only state. You can get the URL for this record by running the query capability again. For example, you can update the triNumber on the record. The header is same from the POST command. To update only the number field, you can set the request body to: {"spi:triNumber":"24" }

This action changes the number in the record from 42 to the new value 24. Ensure to select PUT before clicking SEND.

To confirm that the value has been updated, you can run a GET command on the same URL. Change to the GET option and then click SEND. The response shows the updated number. This update can also be seen on the TRIRIGA Server where you create and view the records.
Update record using PUT

You can also delete a record using PUT. To delete a record, run the delete action that brings the record to the null state. For example, to delete one of the records, run a PUT command with the request body of: {"spi:action":"Delete"}

Delete using DELETE
While it is possible to delete a record by using the PUT command, you can also use the HTTP DELETE operation. In order to use delete, you must set the URI to the record that you want to remove. This URI is identical to the one that you would run a GET command to view the record.
Note: You cannot delete a record unless the record is in the state where a delete action is allowed. Enure that the state transitions end is in the null state for your records.

Run a DELETE command: http://TRIRIGAServerURL:port/context/oslc/

Login with USERNAME/PASSWORD

You can use the REST Client to login to the TRIRIGA Server. When you send the first request upon opening the REST Client, you are prompted to specify your user name and password. To login or switch users you can simply run a GET command on: http://TRIRIGAServerURL:port/context/oslc/login?USERNAME=name&PASSWORD=pass. Set the USERNAME and PASSWORD parameters to the username and password that you would use to login to the TRIRIGA. These login parameters can then be run by using any request.

Another useful command that you can run is to check to see which user account who you are logged in with. A query capability is already included on the TRIRIGA Server and is set up in the triFriendOfAFriendSV (which can be found in the triFriendOfAFriendSP) and is called triCurrentUserQC. To see the user logged in, run a GET command on: http://TRIRIGAServerURL:port/context/oslc/spq/triCurrentUserQC?oslc.select=*. The “?oslc.select=*” part is not manadatory but can be used to view the record details returned.