b-connected api with widget integration
DESCRIPTION
Oracle HRMS Open EnrollmentTRANSCRIPT
B C I B R I D G E S P E O P L E A N D T E C H N O L O G Y . Y O U ’ L L S E E .
B-CONNECTED INTEGRATION GUIDE
Version 3.0
2
Benefit Communications Inc. Proprietary and Confidential
Contents Section 1: B-Connected Integration ............................................................................................................ 3
Audience ................................................................................................................................................... 3
Overview ................................................................................................................................................... 3
Usage and Integration on the Partner's Website ................................................................................... 4
Section 2: Security ....................................................................................................................................... 6
Public Certificate ...................................................................................................................................... 6
Attribute Definitions – MetaData.xml ..................................................................................................... 6
Endpoint URI's – UAT and Production ..................................................................................................... 6
UAT URI ................................................................................................................................................. 6
Production URI ..................................................................................................................................... 6
Section 3: B-Connected API ......................................................................................................................... 7
Audience ................................................................................................................................................... 7
Overview ................................................................................................................................................... 7
Endpoints and URI Formats .................................................................................................................... 8
Operations .................................................................................................................................................... 8
InitEnrollment ............................................................................................ Error! Bookmark not defined.
Demographic ............................................................................................................................................ 9
Layout – Demographic Data................................................................................................................ 9
Layout – Dependent Data ................................................................................................................ 12
Sample JSON Request (POST Data) .................................................................................................... 13
GetBenefit ..................................................................................................... Error! Bookmark not defined.
Sample GetBenefit SAML Assertion (POST Data) ................................... Error! Bookmark not defined.
BenefitConfirmations ................................................................................................................................ 15
FinishEnrollment ........................................................................................... Error! Bookmark not defined.
Appendix A ................................................................................................................................................. 16
3
Benefit Communications Inc. Proprietary and Confidential
Section 1: B-Connected Integration
Audience
This document is intended for partners who integrate the B-Connected application into their system.
This document assumes that the audience is aware of the terminology associated with basic HTML
web pages such as <iframe> and basic JavaScript.
Overview The B-Connected uses BCI's B-Connected API that provides supplemental benefit enrollments in real-
time based on employee eligibility and plan offerings.
The B-Connected service can be plugged in on the partner's website and provides customers with a
seamless end-to-end enrollment experience.
4
Benefit Communications Inc. Proprietary and Confidential
Usage and Integration on the Partner's Website
The B-Connected widget can be integrated on the partner's system in the form of an <iframe>
pointing to B-Connected's implementation for the supplemental benefits:
<iframe id='BciFrame' />
A reference to BCI's JavaScript file will be required in the <head> tag:
<script src="https://www.electbenefits.com/ESS/bciapi.js" type="text/javascript"></script>
Three JavaScript functions will be required in the <head> tag:
<script>
function onBciStart() {
document.getElementById('[button id on partner system]').disabled = true;
}
function onBciFailure() {
document.getElementById('[button id on partner system]').disabled = false;
}
function onBciSuccess() {
document.getElementById('[button id on partner system]').disabled = false;
}
</script>
A full HTML page example using the JavaScript functions and calling those functions from a button
on the page is below.
<!DOCTYPE html>
<html>
<head>
<title>Customer's Site</title>
<!-- BCI'S PROPRIETARY ENROLLMENT SCRIPT -->
<script src="https://www.electbenefits.com/ESS/bciapi.js" type="text/javascript"></script>
5
Benefit Communications Inc. Proprietary and Confidential
<!-- CUSTOMER-SPECIFIC CODE TO CUSTOMIZE UI EXPERIENCE -->
<script>
function onBciStart() {
document.getElementById('btnEnrollment').disabled = true;
}
function onBciFailure() {
document.getElementById('btnEnrollment').disabled = false;
}
function onBciSuccess() {
document.getElementById('btnEnrollment').disabled = false;
}
</script>
</head>
<body>
<!-- CUSTOM UI BUTTON FOR INITIATING ENROLLMENT -->
<button id='btnEnrollment' onclick='BciInit(onBciStart,onBciFailure,onBciSuccess);'>Enroll for Benefits</button>
<br />
<!-- IFRAME FOR CONTENT FROM BCI -->
<iframe id='BciFrame' />
</body>
</html>
6
Benefit Communications Inc. Proprietary and Confidential
Section 2: Security
The B-Connected service uses SAML 2.0 as its initial authentication. In order to access the service
the client must use an assertion with some specific attributes mentioned below. The SAML must be
authenticated using the certificate file (.cer) from where the user is coming from.
The .cer file must be generated from the web server where the host system resides. BCI will need
this file in order for the SSO (Single Sign-On) process to work.
Public Certificate
BCI's public certificate is included in the MetaData.xml file provided as part of this guide. The .cer file
is also provided for convenience. This will be the certificate that will be needed to decrypt the SAML
Response and/or the SAML Assertion.
A SAML 2.0 Assertion is required with the following attributes to the URI's below in order to begin the
process. The ClientID will be assigned by BCI.
Attribute Definitions – MetaData.xml
File
Field
Position
File Field Name Description Required/
Optional Data Type Special Note
1 ClientID Client's Unique ID R Alpha (70) Assigned by BCI
Endpoint URI's – UAT and Production
UAT URI https://dashboard.electbenefits.com/SSOTestBed/ESS/sso/<client>/AssertionService.aspx
Production URI https://www.electbenefits.com/ESS/sso/<client>/AssertionService.aspx
7
Benefit Communications Inc. Proprietary and Confidential
Section 3: B-Connected API
Audience
This document is intended for programmers that consume the B-Connected API. This reference guide
provides examples of the API operation accessible using REST protocol with JSON request and
response.
Overview
BCI offers a REST API that provides the eligibility and plan information for supplemental benefits.
Since BCI's B-Connected API is a REST API based on open standards, you can use any web
development language to access the API.
Security The B-Connected API, uses tokens as its authentication. In order to obtain the {apiToken}, which is
used in each API call, the user must first obtain a token through the hidden API call GET
https://api3.electbenefits.com/api/v1/Tokens/{Username}/{Password} This call will return an {apiToken}
that will be valid for a 48 hour period. A new token can be obtained at any time using this method.
Usernames and Passwords can be obtained by contacting BCI.
Sample JSON Response [
{
"Token": " 138,217,24,220,179,48,50,116,35,172,162,162,157,32,122",
"Message": "Token has been issued for 48 hours!"
}
]
8
Benefit Communications Inc. Proprietary and Confidential
Endpoints and URI Formats
The B-Connected API provides access to resources via URI paths. The API uses JSON as the
communication format and hence, to use the API, your application has to make an HTTP request over
SSL, in JSON format and parse the JSON response.
Endpoint URIs for B-Connected's API will have the following format:
https://api3.electbenefits.com/api/v1
POST Demographics/{apiToken}
POST Benefits/{token}
GET BenefitConfirmations/{id}/{apiToken}
GET BenefitConfirmations/{clientid}/{apiToken}
GET BenefitConfirmations/{id}/{benid}/{apiToken}
Operations API requests are standard HTTP POST and GET requests.
Acceptable request representations: application/json and application/xml
Available response representations: application/json and application/xml
9
Benefit Communications Inc. Proprietary and Confidential
Demographic
The Demographics API call is responsible for sending B-Connected the employee and dependent
demographic data. There is one parameter that is required to be passed into this API called
{apiToken}.
The employee and dependent demographic information will be sent, In the body, to the API via HTTP
POST. The dependent(s) are nested within the employee response. Each dependent will be listed one
after the other. The employee and dependent demographic layouts are below with their coinciding
JSON Requests.
The {apiToken} is a unique GUID assigned to the host and will not change for 48 hours.
Layout – Demographic Data
File
Field
Position
File Field Name Description Required/
Optional Data Type Special Note
1 EEID Employee ID R Alpha (20)
2 SSN Employee Social
Security # R Alpha (11) no dashes
3 FirstName First Name R Alpha (50)
4 MiddleName Middle Name/Initial R Alpha (50)
5 LastName Last Name R Alpha (50)
6 DOB Date of Birth R Date (10) MM/DD/YYYY
7 Gender Male, Female (M/F) R Alpha (6)
8 Address1 Employee Address1 R Alpha (50)
9 Address2 Employee Address2 O Alpha (50) If available
10 City Employee City R Alpha (50)
10
Benefit Communications Inc. Proprietary and Confidential
File
Field
Position
File Field Name Description Required/
Optional Data Type Special Note
11 State Employee State R Alpha (2)
12 Zip Employee Zip R Alpha (10)
13 Email1 Employee E-Mail (work
or personal) O Alpha (128) if available
14 HomePhone Employee Home
Phone # R Alpha (15) if available
15 DepartmentCode Employee Dept Code O Alpha (20)
16 DepartmentDesc Employee Dept
Description/Name O Alpha (50)
17 LocationCode Employee Location
Code O Alpha (20)
18 LocationDesc Employee Location
Description O Alpha (50)
19 JobCode Job Code O Alpha (20)
20 JobDesc Job Description O Alpha (50)
21 FTPT Full Time/Part Time
Status (FT/PT) R Alpha (10)
22 PayFreq 12, 24, 26, 52 R Alpha (10)
23 SalaryClass Hourly or Salary R Alpha (10)
24 Exempt
Exempt Status (Yes /
No / Exempt /
NonExempt)
R Alpha (10)
25 DOH Date of Hire (most
recent date of hire) R Date (10)
MM/DD/YYYY (need date to
base benefit eligibility from)
11
Benefit Communications Inc. Proprietary and Confidential
File
Field
Position
File Field Name Description Required/
Optional Data Type Special Note
26 AnnualSal Annual Salary (Benefit
Salary) R
Decimal
(15)
per pay amount and
scheduled hours also
acceptable
27 Dependents Dependent Object –
defined below O OBJECT
12
Benefit Communications Inc. Proprietary and Confidential
Layout – Dependent Data
File
Field
Position
File Field Name Description Required/
Optional Data Type Special Note
1 SSN Employee's SSN R Alpha (11) no dashes
2 DepID Dependent ID R Alpha (20) Client system unique
dependent identifier
3 Fname Dependent First Name R Alpha (50)
4 Mname Dependent Middle
Name/Initial R Alpha (50)
5 Lname Dependent Last Name R Alpha (50)
6 DOB Dependent Date of Birth R Date (10) Yyyymmdd
7 dpSSN Dependent SSN R Alpha (11) if available
8 Relationship
Relation to EE
(Spouse/Child/Beneficia
ry)
R Alpha (20)
9 Gender Male/Female (M/F) R Alpha (10)
10 Student
Student Status for
Overage Dependents
(Y/N)
O Alpha (1) if available
11 Disabled Disabled (Y/N) O Alpha (1) if available
12 dpSmoker Dependent Smoker
Status (Y/N) S Alpha (1)
required for dependent level
smoker rates
13
Benefit Communications Inc. Proprietary and Confidential
Sample JSON Request (POST Data) {
"EEID":"125874587",
"SSN":"123456789",
"FirstName":"Test",
"MiddleName":"",
"LastName":"Employee",
"DOB":"19790727",
"Gender":"M",
"Address1":"123 anywhere",
"Address2":"",
"City":"Itta Bena",
"State":"MS",
"Zip":"38941",
"Email1":[email protected],
"HomePhone":"1254874580",
"DepartmentCode":"",
"DepartmentDesc":"",
"LocationCode":"",
"LocationDesc":"",
"JobCode":"",
"JobDesc":"attorney",
"FTPT":"FT",
"PayFreq":"26",
"SalaryClass":"S",
"Exempt":"N",
"DOH":"06/1/2001",
"AnnualSal":"25000",
"Dependents":[{
"SSN":"123456789",
"DepID":"234567898-001",
"FName":"Test".
"MName":"",
"LName":"Employee",
"DOB":"07/27/1979",
"dpSSN":"455454544",
"Relationship":"Spouse",
"Gender":"F",
"Student":"N",
"Disabled":"N",
"dpSmoker":"N"
}],
{apiToken}
}
14
Benefit Communications Inc. Proprietary and Confidential
Benefits
The Benefits API is used to pass benefit information directly through the API. There is one parameter
that is required to be passed into this API called {apiToken}.
The benefit information will be passed, in the body, to the API via HTTP POST. There can be multiple
benefits passed into the API.
The {apiToken} is a unique GUID assigned to the host and will not change for 48 hours.
Layout – Benefits Data File
Field
Position
File Field Name Description Required/
Optional Data Type Special Note
1 SSN Employee's SSN R Alpha (11) no dashes
2 BenID Benefit ID R Alpha (20) See chart in Appendix A for
benefit id legend
3 BenDeduction Benefit Per Pay Period
Deduction R Alpha (20)
4 TotalBenAmount Total Benefit Amount
Requested R Alpha (30)
5 InforceBenAmou
nt Benefit Amount inforce R Alpha (30)
6 BenEffDate Benefit Effective Date R Date (10) yyyymmdd
Sample JSON Request (POST Data) {
"SSN":"123456789",
"benefitObject": {
"BenID":"LIF",
"BenDeduction":"12.84",
"TotalBenAmount":"200000",
"InforceBenAmount":"100000",
"BenEffDate":"20150101"
},
{apiToken}
}
15
Benefit Communications Inc. Proprietary and Confidential
BenefitConfirmations
The BenefitConfirmations API call has three versions. One is used to pull all benefit information back
for a person. There are parameters that are required to be passed into this API called {id}, and
{apiToken}.
The {id} parameter maps to the employee SSN. The {apiToken} is a unique GUID assigned to the
host and will not change for 48 hours.
The second version is used to pull all benefit information back for an entire client. There are
parameters that are required to be passed into this API called {clientid}, and {apiToken}.
The {clientid} parameter maps to a BCI defined client ID. The {apiToken} is a unique GUID assigned to
the host and will not change for 48 hours.
The third version is used to pull back benefit information for a particular person and for a particular
benefit. There are three parameters that are required to be passed into this version of the API called
{id}, {benid}, and {apiToken}.
The {id} parameter maps to the employee SSN and the {benid} parameter maps to a unique BCI
defined benefit code. See Appendix A for a chart defining the benefit parameters. The {apiToken} is a
unique GUID assigned to the host and will not change for 48 hours.
16
Benefit Communications Inc. Proprietary and Confidential
Appendix A
Benefit Parameter
Accident ACC
Critical Illness CI
Whole Life WLIFE
STD – worksite STD
Hospital Indemnity GHI
Employee Life LIF
Spouse Life SLF
Child Life CLF
STD - voluntary VSTD
LTD – voluntary VLTD