Protecting Patients through Background Checks
BcsHost and BcsClient Use in Integration
Background Check System
IT Technical Design Guide
Version 01
4/22/2015
Table of Contents
1 Overview 3
2 BcsHost 3
2.1 Bcs.Integration.Services.BcsHost 3
2.2 Projects 5
2.3 WCF Web Service 7
2.4 CustomUserNamePasswordValidator 8
3 BcsClient 8
3.1 Bcs.Integration.Services.BcsClient 9
3.2 IBcsClient 10
3.3 BcsClientMethods 10
1 Overview
The purpose of this document is to detail the BcsHost and BcsClient projects and their role in state-specific integration.
2 BcsHost
The BcsHost web services are state-specific and contain web methods for integration processes such as:
· Applicant Information
· Appointment Save
· Fingerprints Taken
· Fingerprints Rejected
· Criminal History Available
· Criminal History Rap Back
· Change To SID
Although several different states may implement a common method, such as FingerprintsTaken, each state is free to define their own request parameters, response properties, and business logic. Therefore, there is limited code re-use across BcsHost implementations. Please refer to the state-specific integration requirements documents for details on a specific BcsHost.
2.1 Bcs.Integration.Services.BcsHost
There is a common project called Bcs.Integration.Services.BcsHost that defines two common types:
2.1.1 Agency
The Agency enumerated type is used in methods, such as FingerprintsRejected or CriminalHistoryAvailable, both of which can support state or federal information.
2.1.2 Response
The Response class is the base class for every BcsHost web method’s return value. This class closely mirrors the Bcs.Result class:
· IsSuccessful – Boolean value indicating success or failure.
· Messages – List of error messages detailing why a particular method failed.
Every BcsHost method follows the pattern of XxxxResponse Xxxx (XxxxRequest request) where “Xxxx” is a method name such as “FingerprintsTaken”. In many cases, the derived XxxxResponse class does not add any additional properties. In other cases, such as ApplicantInfo methods, the derived response class contains many properties.
2.2 Projects
Each state supporting BcsHost integration will contain the following set of projects:
· Service Definition
· Implementation
· Logging
· Windows Communication Foundation (WCF) Web Service
2.2.1 Service Definition
The Service definition project will contain an interface named IBcsHostXX where “XX” is the state-code. The DTO folder will contain definitions for each method’s request and response types.
2.2.2 Implementation
The BcsHost implementation layers are standard. The root file of the partial class will contain constant definitions for all the various error codes that the service may return upon errors. These error codes are completely arbitrary and not consistent across state implementations.
2.2.3 Logging
The BcsHost logging layers are standard as well. The most significant difference between them and normal BCS logging layers is the manner in which the current username is determined. Since these are WCF services, the username comes from the ServiceSecurityContext as shown below.
2.3 WCF Web Service
The WCF Web Service project is straightforward. Due to the nature of the decorator pattern employed throughout the BCS, almost no code is required to create the WCF service from the IBcsHost interface and implementations. The service class definition derives from the logging layer and passes the implementation to its base class constructor.
2.4 CustomUserNamePasswordValidator
The CustomUserNamePasswordValidator is responsible for authenticating BcsHost web method calls against the database. Unfortunately, this WCF authentication process prevents the return of a “graceful” response and requires a security exception to be reported instead.
3 BcsClient
The BcsClient projects were initially a way for the BCS to call out to external state-specific web services, but eventually encompassed other state-specific integration efforts as well. Unlike BcsHost projects, all BcsClient projects are responsible for implementing a subset of an explicit interface.
Many BcsClient methods are implemented using TaskItems (see the “Task Service and Task Items” IT Guide) which allows for asynchronous processing with retries, in case an external dependency is unavailable.
3.1 Bcs.Integration.Services.BcsClient
The Bcs.Integration.Services.BcsClient project contains the IBcsClient interface and a BcsClientMethods enumerated type. The Bcs.Integration.Services.BcsClient.Impl project contains the implementation of the IBcsClient interface, which dispatches calls to a state-specific implementation. The Bcs.Integration.Services.BcsClient.Log project is responsible for logging any implemented calls to IBcsClient methods.
3.2 IBcsClient
The IBcsClient interface defines the methods supported.
3.3 BcsClientMethods
The BcsClientMethods enumerated type lists the methods that correspond to IBcsClient methods.
· ApplicationSubmitted – This method is invoked whenever an application changes to submitted status.
· DeterminationsSubmitted – This method is invoked by a scheduled task to process any determinations submitted since its last execution.
· FingerprintsRejected – This method is executed whenever a set of fingerprints has been rejected.
· RapBackRemove – This method is executed when a person is removed from rap back.
· PaymentCompleted – This method is invoked when an application with payment pending has had its payment completed.
· FileProcess – This method is invoked to handle state-specific, file-based integration processing.
· CustomProcess – This method is triggered by a scheduled task to allow state-specific integration.
· IntegrationRejectionRetry – This method supports bulk retries of integration rejections.
Not every state needs to support BcsClient methods, but those that do need to supply their state-specific information. When the BCS AppContext is initialized, each state department that has a BcsClient implementation is checked against the database and passed to the BcsClientImpl constructor.
When an IBcsClient method is invoked by the application, it checks to see if that department has a BcsClient registered and also checks to see if that particular method is supported. If so, the method call is dispatched to that department’s implementation. The following is an example of a basic BcsClient method implementation demonstrating this process.
The state-specific implementation of the IBcsClient interface then implements the dispatched method in whatever manner is necessary. In the case of IBcsClient.IsMethodSupported, each implementation returns true if the queried method is supported. Methods that a particular state implementation does not support return null.
BcsHost and BcsClient Use in Integration Page 11 of 13
Version 01 | 4/22/2015 | IT Technical Design Guide | Audience: State IT Staff