The primary steps to launch a BenSelect enrollment using Selerix web services is to build a Selerix data transmittal XML, convert it to HTML Entities, add the transmittal XML to the SOAP message and transmit it to BenSelect via secure HTTP POST to obtain an authentication GUID for use with subsequent web service calls.  Due to the wide variety of languages and implementation methodologies that might be employed to perform these steps, the instructions that follow focus on the SOAP XML that is necessary to establish an enrollment session with BenSelect and do not include implementation source code.  For that, refer to the SDK source which includes both C# .NET web services and Java NetBeans examples.

Although a web services integration can be handled by building the necessary XML and posting it to BenSelect manually, we recommend using a combination of our .NET library to build the transmittal XML and web service interfaces to execute the remote procedure calls.  These developer interfaces greatly improve productivity and insure well-formed and compliant transmittal XML.

 

Reference material

• Refer to the sample Selerix transmittal XMLs which show the minimum information required to initiate a single family enrollment for a case that does not contain preloaded enrollee data.  This reference will help you better understand the process described here.
• The C# sample source describes the steps to upload applicant census and initiate a BenSelect enrollment session.  While the C# sample code applies to .NET development environments, the order of web service calls and the steps required to launch an enrollment are the same regardless of the development language. 
• If your development environment cannot utilize .NET technologies you can still benefit from the data accessors that serve as a data dictionary to the transmittal XML using BenSelect reporting online to build a customized sample transmittal XML.

 

SOAP example templates

 The library of sample SOAP templates are available at https://benselect.com/qx/enrollment.asmx.  These include HTTP POST header parameters at the top, an example of which is cited below.  Developers change the orange values to an appropriate value for their case: 

POST /qx/enrollment.asmx HTTP/1.1

Host: benselect.com

Content-Type: text/xml; charset=utf-8

Content-Length: complete length of the SOAP XML including transmittal

SOAPAction: "https://benefits-selection.com/qx/enrollment/Upload" 

 

Steps to launch a BenSelect enrollment

The SOAP v1.2 steps below assume you have been given a list that defines all of the information necessary to launch a BenSelect enrollment.  Your enrollment group administrator or Selerix should have given you a Portfolio Summary Report that contains some of the core information, along with a user name and password for authentication.  You should also have received a list of any other data requirements dictated by case and product setup.  Remember to use SSL3, TLS, TLS11 or TLS12 when posting your SOAP messages over HTTPS.

1. Create and populate a new Selerix transmittal XML with information that identifies the employee.  Create a new Applicant node to house data for the target employee for the enrollment.  On cases with preloaded applicant data, this can be any of the following:

Assign a new GUID to the ID element to identify the SOAP message and set Type to "UploadApplicants".  Be sure to add a Group element even if you are not setting any elements within it.  If Group is absent, BenSelect will return an error.  Assign the PortfolioID GUID that BenSelect uses to uniquely identify the enrollment group.

If applicant data has not been preloaded on the group you will also need to include all target employee and dependent Applicant census information in the transmission.  You will also need to add an Employment node and assign a value to, at least, these elements which are always required: Department, HireDate, JobClass and Location.

2. Using the SOAP XML at https://benselect.com/qx/enrollment.asmx?op=Upload as a template, create and populate a new SOAP message XML.

Set the user and passwd elements of the Upload node with values given to you by the group case builder to authenticate the web service call.

Set the data element of the SOAP message to the entire converted Selerix data transmittal XML created earlier.  Orange text in the sample XML identifies variable information that you populate.

 Because the SOAP message is used as an envelope to carry the data transmittal, the transmittal XML must first be converted to a format that will not interfere with the carrier XML.  This is accomplished by converting the open and close tag characters, "<" and ">", to their respective HTML Entity Codes "&lt;" and "&gt;" before injecting the transmittal into the SOAP XML.

HTTP POST the request to call the BenSelect Upload service request.  

3. Verify the transmission was successful by checking the Status attribute of the TransmittalResult element under Transmittal.  If the transmission was successful, Status will be "OK".
4. Next, using the SOAP 1.2 template at https://benselect.com/qx/enrollment.asmx?op=GetLoginGUID, obtain a login GUID that will be used to launch the enrollment.  Extract UniqueID from Transmittal/Applicants/Applicant from the response XML, then call the GetLoginGUID service request, passing the user, passwd, and portfolioID, and the uniqueID from the Upload response. 
5. Verify the transmission was successful as described earlier.
6. Lastly, launch the BenSelect enrollment.  Extract the login GUID from the GetLoginGUIDResult element of the GetLoginGUIDResponse node.  Construct a URL that consists of your unique URL, the login GUID from GetLoginGUIDResult, and any optional arguments that toggle various elements of the BenSelect user interface. 

 The URL must be used quickly or the credential will expire.

The following sample URL is suitable for embedding a BenSelect enrollment in an IFrame within your application.  Orange text indicates information you supply:

theLaunchURL = "https://benselect.com/Enroll/Login.aspx?login_guid=" +
theLoginGuidAsString +     // From GetLoginGUIDResult
"&personalinfo=no" +       // Don't show employee personal info page
"&welcome=no" +            // Don't show the welcome page
"&benefitsnapshot=no" +    // Don't show the benefit snapshot page
"&review=no" +             // Don't show the benefits review page
"&header_footer=no" +      // Don't show the BenSelect top UI
"&topmenu=no" +            // Don't show the main menu UI
"&sidebar=&no";            // Don't show the BenSelect sidebar UI