iotp-adapter is an OSLC server that exposes IBM Watson IoT Platform resources as OSLC resources. The Developer Guid explains how this server was developed and integrated with the IBM jazz.net applications.

Introduction

See the iotp-adaptor User Guide for information on how to install, configure, administer and use the iotp-adaptor OSLC server. This Developer Guide explains how the adaptor was build and integrated with the IBM CE jazz.net applications. The source code is available in a the GitHub iotp-adaptor Project.

iotp-adaptor was designed and initially created using the eclipse/Lyo Designer. This tool using model-based development techniques to generate an OSLC server implementation with a minimal Web UI "debug" application that allows you to browse the OSLC services and adapted resources. The code generator uses M2T templates that were developed using the eclipse/Lyo OSLC4J Bugzilla sample application.

The Lyo Designer code generator creates an OSLC Core 2.0 compliant OSLC server. This server is sufficient to explore the adapted resources using OSLC capabilities, but it is not enough to be able to integrate that server with the IBM jazz.net based applications. Additional considerations must be addressed in order to integrate with these applications including:

Providing a rootservices document for discovering server discovery capabilities
Establishing Consumer/Friend relationships using OAuth to allow servers to interact
Creating project area artifact container associations to enable linking between jazz.net CE tools and OSLC resources provided by adaptors
What link types are available in each of the applications based on the chosen artifact container association
Specific integration requirements of each CE application (RDNG, RTC and RQM) that you need to know to get the integrations working
Creating a TRS provider that can contribute to IBM RELM and LQE.

The iotp-adaptor Developer Guide walks through all of these considerations and provides example solutions. Here's an overview of each of the sections in the Developer Guide:

eclipse environment setup: describes how to setup an eclipse development environment for developing the model and code. Eclipse is required in order to use Lyo Designer, which is an eclipse plug-in.
The toolchain model - describes the design of the Watson IoT Platform OSLC domain model, and the model of the OSLC services that are provided
Generating the server code - explains how to generate the server implementation using the Lyo Designer code generator with additional details for managing embedded user code.
Exploring the generated code - looks at the structure of the iotp-adaptor eclipse project, and discusses the key folders and files of the generated application.
https and SSL support - discusses the important topic of secure connections and how to configure the Web application to support SSL, and how to manage self-assigned certificates.
Authentication - addresses the often sticky problem of end-user login as well as server-to-server connections through OAuth.
Creating the rootservices document - Describes how to provide a rootservices document which is required to establish consumer/friend connections between the jazz.net applications (primarily the Jazz Team Server) and the iotp-adaptor.
Connecting Servers - describes how to create a consumer/friend relationship using OAuth in order to establish server-to-server communications with jazz.net applications
Artifact Container Associations - describes how to configure jazz.net application project areas so they are able to access OSLC services provided by iotp-adaptor
Updating generated dialogs - explains how to customize the preview and delegated dialogs created by the Lyo Designer code generator
Implementing a Domain Class - summarizes all of the user code that needs to be developed to implement an adaptor domain class, using DeviceType as an example.
Implementing a TRS Provider - provides and overview of the design and implementation of the iotp-adaptor TRS provider
JUnit Tests - describes an example of a typical JUnit test that tests the OSLC CRUD operations of an IoT Platform resource.

Resources

Call for Contrubtion

This documentation site is under continuous development as we discover more information about how to develop OSLC clients and servers that integrate with the jazz.net applications. We encourage you to contribute if you find something missing, incorrect, or unclear. You can email suggestions to Jim Amsden.