Sender and Receiver Clients

info

If you are communicating with the IAS API directly (recommended), you can skip this section.

OCAS has built two Windows services (C# .NET Framework 4.6) to help facilitate the two-way communication between the IAS API and the College's SIS systems. The clients handle all of the HTTPS/TLS and communication with the IAS API HTTP Endpoints. Beyond that, you need to build the integration between sql table data and your SIS.

Configuration

The following section outlines the various configuration options found in both the Receiver and Sender Clients.

Database Connectivity Configuration

The sender and receiver clients support Microsoft SQL Server and Oracle 11G and above.

Property	Default
ocasIntlSis	Database Connection String

Example SQL Server Connection String Data Source=(SERVER_HERE)\INSTANCE_HERE;Initial Catalog=ocas_sis_intl;UserId=USERID_HERE;Password=PASSWORD_HERE

Example Oracle Connection String Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=HOST_HERE)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=SERVICE_NAME_HERE)));Password=PASSWORD_HERE;User ID=USERID_HERE;

Sleep Interval Configuration

The following configuration will dictate how often the Sender and Receiver client will poll for new events to process.

Property	Default
client:scheduleSleep:duration	300ms (5 min)

Dead Letter Table Configuration

For Outbound SIS Events, if an error is encountered, IAS API will stop processing until the issue is fixed. But we offer the ability to have a second table where we log the error response and mark the event as 'Failed', and continue processing. We do recommend to use this with great care. You must:

1. Poll the dead letter table and view the error message, and take action. Do not let items just sit there forever.
2. Be aware that if for example you send two events that pertain to the same Application, if the first one fails, and we move it to the dead letter table, then the second one still might be processed successfully. You have to be very aware of what events you are sending and when/if they could fail.

Property	Default
client:useDeadLetterTable	false

Logging Configuration

The Sender and Receiver clients leverage Serilog for event and error logging.

Property	Default
serilog:minimum-level	Information

serilog:using:RollingFileAlternate

The rolling file feature creates application event logs within a series of rolling files.

Property	Default
serilog:write-to:RollingFileAlternate.logDirectory	C:\Logs\ocas-sis-intl-receiver
serilog:write-to:RollingFileAlternate.fileSizeLimitBytes	10485760 (10MB)
serilog:write-to:RollingFileAlternate.retainedFileCountLimit	50

serilog:write-to:RollingFileAlternate.outputTemplate {Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level}] [{SourceContext}] {Message}{NewLine}{Exception}

serilog:using:EventLog

The event log feature creates application event logs within the Windows Event Viewer.

Property	Default
serilog:write-to:EventLog.source	ocas-sis-intl-receiver
serilog:write-to:EventLog.logName	ApplicationFull
serilog:write-to:EventLog.manageEventSource	false
serilog:write-to:EventLog.restrictedToMinimumLevel	3 (Error)

serilog:write-to:EventLog.outputTemplate {Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level}] [{SourceContext}] {Message}{NewLine}{Exception}

serilog:using:Console

The console feature outputs process information to the console window.

Property	Default
serilog:write-to:console	(blank)

Identity Configuration

See Getting Started for more details on how to obtain a username, password and secret.

Property	Default
ocas:idsvr:publicOrigin	<ToBeProvided>
ocas:idsvr:sts	<ToBeProvided>
ocas:idsvr:clientId	<ToBeProvided>
ocas:idsvr:scope	<ToBeProvided>
ocas:idsvr:secret	See Getting Started
ocas:idsvr:username	See Getting Started
ocas:idsvr:password	See Getting Started

Receiver Client

The receiver client will retrieve pending SIS Events from the OCAS SIS API in the sequence they were generated. These events will be inserted into the SisInboundEvents table in the JSON (default) or XML format (if specified).

Receiver Client Configuration

You can configure the output format by setting the following configuration property.

Property	Default
client:eventFormat	json/xml (Default: json)

Sender Client

The sender client will read pending SIS Events sequentially from the source database. Data will always be transmitted as JSON to the OCAS SIS API. Data in XML format will be converted prior to transmission.

Sender Client Configuration

No custom sender configurations.

Service Installation

The following commands will install the Receiver and Sender clients as Windows Services.

Service Installation - Receiver Client

Ocas.Sis.International.ReceiverClient.Service.exe install -displayname:Ocas.Sis.Intl.ReceiverClient -servicename:Ocas.Sis.Intl.ReceiverClient --delayed

PowerShell 7.x

& "Ocas.Sis.International.ReceiverClient.Service.exe" install -displayname:Ocas.Sis.Intl.ReceiverClient -servicename:Ocas.Sis.Intl.ReceiverClient --delayed

Service Installation - Sender Client

Ocas.Sis.International.SenderClient.Service.exe install -displayname:Ocas.Sis.Intl.SenderClient -servicename:Ocas.Sis.Intl.SenderClient --delayed

PowerShell 7.x

& "Ocas.Sis.International.SenderClient.Service.exe" install -displayname:Ocas.Sis.Intl.SenderClient -servicename:Ocas.Sis.Intl.SenderClient --delayed

Enabling Windows Event Logging

The following commands will allow the SIS Receiver and Sender applications to create logging entries within the Windows Event Viewer without administrative rights.

> [System.Diagnostics.EventLog]::CreateEventSource("ocas-sis-intl-receiver", "Application")
> [System.Diagnostics.EventLog]::CreateEventSource("ocas-sis-intl-sender", "Application")

Monitoring

When processing, some messages may be skipped by the Send/Receiver Clients while others may cause processing to halt altogether (when client:useDeadLetterTable is not present, or set to false).

In both cases, the college’s technical support team will need to investigate further. When all processing has stopped, the users of the system will likely be blocked in their workflow. This is why maintaining the order of Events is important.

Things to consider when processing is halted:

• How are business processes impacted? When do business users rely on the system?
• What are the steps to investigate and resume processing?
• What are the detailed use cases that could cause processing to halt?
• Have you tested all scenarios that may cause processing problems and accounted for them in your technical solution and/or support processes?

NOTE: When using the Sender/Receiver Clients to understand your technical and functional workflows, it is important to know when errors occur. Using the Windows Application Event log allows college IT staff to set up monitors (e.g., Microsoft System Center Operations Manager or equivalent) to alert the appropriate support team members if an error occurs.

Database Structure

The SIS Receiver and Sender applications each have an individual database table required to write and read events respectively.

Name	Type	Purpose
SisOutboundEvents	table	Sis Outbound Event Queue
SisInboundEvents	table	Sis Inbound Event Queue

SisInboundEvents Schema

Column Name	Column Type	Purpose
id	bigint	Event Unique Primary Key
eventInfo	nvarchar(max)	Event Payload Data
eventFormat	nvarchar(5)	Event Format Type (json, xml)
createdDate	datetime2	Created Date

SisOutboundEvents Schema

Column Name	Column Type	Purpose
id	bigint	Event Unique Primary Key
status	nvarchar(50)	Event Status (Default: Pending)
type	nvarchar(50)	Outbound Event Type 'Key'
eventInfo	nvarchar(max)	Event Payload Data
eventFormat	nvarchar(5)	Event Format Type (json, xml)
createdDate	datetime2	Created Date
lastModifiedDate	datetime2	Last Modified Date

SisOutboundDeadLetterEvents Schema

Column Name	Column Type	Purpose
id	bigint	Unique Primary Key
eventid	bigint	Outbound Event Id Foreign Key
httpstatuscode	int	Http Response Status Code (400-499)
errormessage	nvarchar(max)	Error Response Payload
createdDate	datetime2	Created Date