RapidRedPanda.ISBM.ClientAdapter 2.0.1.2

RapidRedPanda.ISBM.ClientAdapter

An ISBM Client Adapter package is available to assist anyone interested in trying out the Open Industrial Interoperability Ecosystem (OIIE). Since OIIE involves multiple industry standards at different levels of the technology stack, it is helpful to have a simple and easy-to-use NuGet package for everyone interested in quickly building IoT/IoE solutions using OIIE.

This NuGet package includes three flavors of ISBM 2.0 Client Adapters: .NET 6, .NET Core 3.1, and .NET Standard 2.0. They support a wide range of .NET implementations and OS or hardware platforms; see details in the ISBM 2.0 Client Adapter Architecture Diagram. By using the adapter, you can deliver and receive CCOM messages (Common Conceptual Object Model) through ISBM services (ISA-95 Message Service Model) with just a few lines of code! It cuts down on the learning curve, allowing you to try out your ideas using OIIE without delving into the technical details of the standards.

Contents

1. Package Information
2. Code Samples
3. Quick reference
4. Useful Links

Package information

Description

This package is designed to manage all the details of ISA-95 Message Service Model specifications for communication with ISBM-compliant servers. The ISBM interface will be accessible through object classes that developers will find user-friendly and easy to use. This will significantly reduce the learning curve associated with building ISBM-compliant devices or applications.

It targets three different .NET platforms to support device development across a wide range of operating systems and device hardware. There is also a repository, ISBM-2.0-Client-SDK, a full development kit for anyone wishing to learn more using the ISBM Client Adapter.

Prerequisites

You need a functional ISBM 2.0 Server in order to test your project code. If don't have an ISBM 2.0 Server, an ISBM Server project implemented with a set of basic Publication interface using Azure Service Bus is available in this repository, https://github.com/claire-wong/ISBM-2.0-Server-Adapter.

Implemented ISA-95 ISBM 2.0 RESTful Interface

Provider Publication Service

1. Open Publication Session
2. Post Publication
3. Expire Publication
4. Close Publication Session

Consumer Publication Service

1. Open Subscription Session
2. Read Publication
3. Remove Publication
4. Close Subscription Session

Provider Request Service

1. Open Provider Request Session
2. Read Request
3. Remove Request
4. Post Response
5. Close Provider Request Session

Consumer Request Service

1. Open Consumer Request Session
2. Post Request
3. Expire Request
4. Read Response
5. Remove Response
6. Close Consumer Request Session

Code Samples

Provider Publication Service

Open Publication Session

Opens a publication session for a channel

 ProviderPublicationService myProviderPublicationService = new ProviderPublicationService();

  //Required for secured channels only.
  //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myProviderPublicationService.Credential.Username = userName;
 myProviderPublicationService.Credential.Password = password;

 OpenPublicationSessionResponse myOpenPublicationSessionResponse = myProviderPublicationService.OpenPublicationSession(hostAddress, channelId);
 //ISBM Adapter Response.
 string sessionId = myOpenPublicationSessionResponse.SessionID;

Post Publication

Posts a publication message on a channel to a single topic

 ProviderPublicationService myProviderPublicationService = new ProviderPublicationService();
 string topic = "Test.Topic.1";
 PostPublicationResponse myPostPublicationResponse = myProviderPublicationService.PostPublication(hostAddress, sessionId, topic, bODMessage);
 //ISBM Adapter Response
 string messageId = myPostPublicationResponse.MessageID;

Posts a publication message on a channel to multiple topics

 ProviderPublicationService myProviderPublicationService = new ProviderPublicationService();
 string[] topics = new string[] { "Test.Topic.1", "Test.Topic.2" };
 PostPublicationResponse myPostPublicationResponse = myProviderPublicationService.PostPublication(hostAddress, sessionId, topics, bODMessage);
 //ISBM Adapter Response
 string messageId = myPostPublicationResponse.MessageID;

Post a publication with expiry

 PostPublicationOptions myPostPublicationOptions = new PostPublicationOptions();
 myPostPublicationOptions.Expiry = "P2D";

 ProviderPublicationService myProviderPublicationService = new ProviderPublicationService();
 string topic = "Test.Topic.1";
 PostPublicationResponse myPostPublicationResponse = myProviderPublicationService.PostPublication(hostAddress, sessionId, topic, bODMessage, myPostPublicationOptions);
 //ISBM Adapter Response
 string messageId = myPostPublicationResponse.MessageID;

Expire Publication

Expires a posted publication

 ProviderPublicationService myProviderPublicationService = new ProviderPublicationService();
 ExpirePublicationResponse myExpirePublicationResponse = myProviderPublicationService.ExpirePublication(hostAddress, sessionId, messageId);
     

Close Publication Session

Closes a publication session

 ProviderPublicationService myProviderPublicationService = new ProviderPublicationService();
 ClosePublicationSessionResponse myClosePublicationSessionResponse = myProviderPublicationService.ClosePublicationSession(hostAddress, sessionId);

Consumer Publication Service

Open Subscription Session

Opens a subscription session for a channel to a single topic

 ConsumerPublicationService myConsumerPublicationService = new ConsumerPublicationService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myConsumerPublicationService.Credential.Username = userName;
 myConsumerPublicationService.Credential.Password = password;

 string topic = "Test.Topic.1";
 OpenSubscriptionSessionResponse myOpenSubscriptionSessionResponse = myConsumerPublicationService.OpenSubscriptionSession(hostAddress, channelId, topic);
 //ISBM Adapter Response.
 string sessionId = myOpenSubscriptionSessionResponse.SessionID;

Opens a subscription session for a channel to multiple topics

 ConsumerPublicationService myConsumerPublicationService = new ConsumerPublicationService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myConsumerPublicationService.Credential.Username = userName;
 myConsumerPublicationService.Credential.Password = password;

 string[] topics = new string[] { "Test.Topic.1", "Test.Topic.2" };
 OpenSubscriptionSessionResponse myOpenSubscriptionSessionResponse = myConsumerPublicationService.OpenSubscriptionSession(hostAddress, channelId, topics);
 //ISBM Adapter Response.
 string sessionId = myOpenSubscriptionSessionResponse.SessionID;

Opens a subscription session for a channel with listener

 ConsumerPublicationService myConsumerPublicationService = new ConsumerPublicationService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myConsumerPublicationService.Credential.Username = userName;
 myConsumerPublicationService.Credential.Password = password;

 OpenSubscriptionSessionOptions myOpenSubscriptionSessionOptions = new OpenSubscriptionSessionOptions();
 myOpenSubscriptionSessionOptions.ListenerURL = "http://notifications.yourisbmserver.com";
 string topic = "Test.Topic.1";
 OpenSubscriptionSessionResponse myOpenSubscriptionSessionResponse = myConsumerPublicationService.OpenSubscriptionSession(hostAddress, channelId, topic, myOpenSubscriptionSessionOptions);
 //ISBM Adapter Response.
 string sessionId = myOpenSubscriptionSessionResponse.SessionID;

Opens a subscription session for a channel with filter expression

 ConsumerPublicationService myConsumerPublicationService = new ConsumerPublicationService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myConsumerPublicationService.Credential.Username = userName;
 myConsumerPublicationService.Credential.Password = password;

 OpenSubscriptionSessionOptions myOpenSubscriptionSessionOptions = new OpenSubscriptionSessionOptions();
 
 FilterExpression my1FilterExpression = new FilterExpression();
 ApplicableMediaType my1ApplicableMediaType = new ApplicableMediaType();
 my1ApplicableMediaType.MediaType = "application/json";
 my1FilterExpression.ApplicableMediaTypes.Add(my1ApplicableMediaType);

 my1FilterExpression.ExpressionString.Expression = "$['LoremIpsum'][?(@.field == 'SomeText')]";
 my1FilterExpression.ExpressionString.Language = "JSONPath";
 my1FilterExpression.ExpressionString.LanguageVersion = "com.jayway.jsonpath:json-path:2.4.0";

 myOpenSubscriptionSessionOptions.FilterExpressions.Add(my1FilterExpression);

 string topic = "Test.Topic.1";
 OpenSubscriptionSessionResponse myOpenSubscriptionSessionResponse = myConsumerPublicationService.OpenSubscriptionSession(hostAddress, channelId, topic, myOpenSubscriptionSessionOptions);
 //ISBM Adapter Response.
 string sessionId = myOpenSubscriptionSessionResponse.SessionID;

Read Publication

Returns the first non-expired publication message or a previously read expired message that satisfies the session message filters

 ConsumerPublicationService myConsumerPublicationService = new ConsumerPublicationService();
 ReadPublicationResponse myReadPublicationResponse = myConsumerPublicationService.ReadPublication(hostAddress, sessionId);
 //ISBM Adapter Response
 messageId = myReadPublicationResponse.MessageID;
 topic = myReadPublicationResponse.Topic;
 bODMessage = myReadPublicationResponse.MessageContent;

Remove Publication

Removes the first, if any, publication message in the subscription queue

 ConsumerPublicationService myConsumerPublicationService = new ConsumerPublicationService();
 RemovePublicationResponse myRemovePublicationResponse = myConsumerPublicationService.RemovePublication(hostAddress, sessionId);

Close Subscription Session

Closes a subscription session

 ConsumerPublicationService myConsumerPublicationService = new ConsumerPublicationService();
 CloseSubscriptionSessionResponse myCloseSubscriptionSessionResponse = myConsumerPublicationService.CloseSubscriptionSession(hostAddress, sessionId);

Provider Request Service

Open Provider Request Session

Opens a provider request session for a channel for reading requests and posting responses to a single topic

 ProviderRequestService myProviderRequestService = new ProviderRequestService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myProviderRequestService.Credential.Username = userName;
 myProviderRequestService.Credential.Password = password;

 string topic = "Test.Topic.1";
 OpenProviderRequestSessionResponse myProviderRequestServiceResponse = myProviderRequestService.OpenProviderRequestSession(hostAddress, channelId, topics);
 //ISBM Adapter Response.
 string sessionId = myProviderRequestServiceResponse.SessionID;

Opens a provider request session for a channel for reading requests and posting responses to multiple topic

 ProviderRequestService myProviderRequestService = new ProviderRequestService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myProviderRequestService.Credential.Username = userName;
 myProviderRequestService.Credential.Password = password;

 string[] topics = new string[] { "Test.Topic.1", "Test.Topic.2" };
 OpenProviderRequestSessionResponse myProviderRequestServiceResponse = myProviderRequestService.OpenProviderRequestSession(hostAddress, channelId, topics);
 //ISBM Adapter Response
 string sessionId = myProviderRequestServiceResponse.SessionID;

Opens a provider request session for a channel for reading requests and posting responses with listener

 ProviderRequestService myProviderRequestService = new ProviderRequestService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myProviderRequestService.Credential.Username = userName;
 myProviderRequestService.Credential.Password = password;

 OpenProviderRequestSessionOptions myOpenProviderRequestSessionOptions = new OpenProviderRequestSessionOptions();
 myOpenProviderRequestSessionOptions.ListenerURL = "http://notifications.yourisbmserver.com";
 string topic = "Test.Topic.1";
 OpenProviderRequestSessionResponse myProviderRequestServiceResponse = myProviderRequestService.OpenProviderRequestSession(hostAddress, channelId, topic, myOpenProviderRequestSessionOptions);
 //ISBM Adapter Response
 string sessionId = myProviderRequestServiceResponse.SessionID;

Opens a provider request session for a channel for reading requests and posting responses with filter expression

 ProviderRequestService myProviderRequestService = new ProviderRequestService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myProviderRequestService.Credential.Username = userName;
 myProviderRequestService.Credential.Password = password;

 OpenProviderRequestSessionOptions myOpenProviderRequestSessionOptions = new OpenProviderRequestSessionOptions();
 
 FilterExpression my1FilterExpression = new FilterExpression();
 ApplicableMediaType my1ApplicableMediaType = new ApplicableMediaType();
 my1ApplicableMediaType.MediaType = "application/json";
 my1FilterExpression.ApplicableMediaTypes.Add(my1ApplicableMediaType);

 my1FilterExpression.ExpressionString.Expression = "$['LoremIpsum'][?(@.field == 'SomeText')]";
 my1FilterExpression.ExpressionString.Language = "JSONPath";
 my1FilterExpression.ExpressionString.LanguageVersion = "com.jayway.jsonpath:json-path:2.4.0";

 myOpenProviderRequestSessionOptions.FilterExpressions.Add(my1FilterExpression);

 string topic = "Test.Topic.1";
 OpenProviderRequestSessionResponse myProviderRequestServiceResponse = myProviderRequestService.OpenProviderRequestSession(hostAddress, channelId, topic, myOpenProviderRequestSessionOptions);
 //ISBM Adapter Response
 string sessionId = myProviderRequestServiceResponse.SessionID;

Read Request

Returns the first non-expired request message or a previously read expired message that satisfies the session message filters

 ProviderRequestService myProviderRequestService = new ProviderRequestService();
 ReadRequestResponse myReadRequestResponse = myProviderRequestService.ReadRequest(hostAddress, sessionId);
 //ISBM Adapter Response
 requestMessageId  = myReadRequestResponse.MessageID;
 bODMessage = myReadRequestResponse.MessageContent;

Remove Request

Deletes the first request message, if any, in the session message queue

 ProviderRequestService myProviderRequestService = new ProviderRequestService();
 RemoveRequestResponse myRemoveRequestResponse = myProviderRequestService.RemoveRequest(hostAddress, sessionId);

Post Response

Posts a response message on a channel

 ProviderRequestService myProviderRequestService = new ProviderRequestService();
 PostResponseResponse myPostResponseResponse = myProviderRequestService.PostResponse(hostAddress, sessionId, requestMessageId, bODMessage);
 //ISBM Adapter Response
 string messageId = myPostResponseResponse.MessageID;

Close Provider Request Session

Closes a provider request session

 ProviderRequestService myProviderRequestService = new ProviderRequestService();
 CloseProviderRequestSessionResponse myCloseProviderRequestSessionResponse = myProviderRequestService.CloseProviderRequestSession(hostAddress, sessionId);

Consumer Request Service

Open Consumer Request Session

Opens a consumer request session for a channel for posting requests and reading responses

 ConsumerRequestService myConsumerRequestService = new ConsumerRequestService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myConsumerRequestService.Credential.Username = userName;
 myConsumerRequestService.Credential.Password = password;

 OpenConsumerRequestSessionResponse myOpenSubscriptionSessionResponse = myConsumerRequestService.OpenConsumerRequestSession(hostAddress, sessionId); 
 //ISBM Adapter Response
 string sessionId =  myOpenSubscriptionSessionResponse.SessionID;

Opens a consumer request session for a channel for posting requests and reading responses with listener

 ConsumerRequestService myConsumerRequestService = new ConsumerRequestService();

 //Required for secured channels only.
 //To open a session on a secured channel, set up the Credential object properties with the user's valid authentication information.
 myConsumerRequestService.Credential.Username = userName;
 myConsumerRequestService.Credential.Password = password;

 OpenConsumerRequestSessionOptions myOpenConsumerRequestSessionOptions = new OpenConsumerRequestSessionOptions();
 myOpenConsumerRequestSessionOptions.ListenerURL = "http://notifications.yourisbmserver.com";
 OpenConsumerRequestSessionResponse myOpenSubscriptionSessionResponse = myConsumerRequestService.OpenConsumerRequestSession(hostAddress, sessionId, myOpenConsumerRequestSessionOptions; 
 //ISBM Adapter Response
 string sessionId =  myOpenSubscriptionSessionResponse.SessionID;

Post Request

Posts a request message on a channel

 ConsumerRequestService myConsumerRequestService = new ConsumerRequestService();
 string topic = "Test.Topic.1";     
 PostRequestResponse myPostRequestResponse = myConsumerRequestService.PostRequest(hostAddress, sessionId, topic, bODMessage);
 //ISBM Adapter Response
 string requestMessageId = myPostRequestResponse.MessageID;

Posts a request message on a channel with expiry

 ConsumerRequestService myConsumerRequestService = new ConsumerRequestService();
 PostRequestOptions myPostRequestOptions = new PostRequestOptions();
 myPostRequestOptions.Expiry = "P2D";
 string topic = "Test.Topic.1";     
 PostRequestResponse myPostRequestResponse = myConsumerRequestService.PostRequest(hostAddress, sessionId, topic, bODMessage, myPostRequestOptions);
 //ISBM Adapter Response
 string requestMessageId = myPostRequestResponse.MessageID;

Expire Request

Expires a posted request message

 ConsumerRequestService myConsumerRequestService = new ConsumerRequestService();
 ExpireRequestResponse myExpireRequestResponse = myConsumerRequestService.ExpireRequest(hostAddress, sessionId, requestMessageId);

Read Response

Returns the first response message, if any, in the session message queue associated with the request

 ConsumerRequestService myConsumerRequestService = new ConsumerRequestService();
 ReadResponseResponse myReadResponseResponse = myConsumerRequestService.ReadResponse(hostAddress, sessionId, requestMessageId);
 //ISBM Adapter Response
 messageId = myReadResponseResponse.MessageID;
 bODMessage = myReadResponseResponse.MessageContent;

Remove Response

Deletes the first response message, if any, in the session message queue associated with the request

 ConsumerRequestService myConsumerRequestService = new ConsumerRequestService();
 RemoveResponseResponse myRemoveResponseResponse = myConsumerRequestService.RemoveResponse(hostAddress, sessionId, requestMessageId);

Close Consumer Request Session

Closes a consumer request session

 ConsumerRequestService myConsumerRequestService = new ConsumerRequestService();
 CloseConsumerRequestSessionResponse myCloseConsumerRequestSessionResponse = myConsumerRequestService.CloseConsumerRequestSession(hostAddress, sessionId);

Quick reference

1. OIIE - OpenO&M Open Industrial Interoperability Ecosystem
2. ISBM - International Society of Automation ISA-95 Message Service Model
3. CCOM - MIMOSA Common Conceptual Object Model
4. BOD - OAGIS Business Object Document

Useful Links

Standard Organizations

1. OpenO&M
2. MIMOSA
3. International Society of Automation
4. OAGi