Background Check Common Services for Generic Vendors

For more information on the processes on this page, including project scoping, contact your IBM Representative.

Introduction

This document serves as a guide for integrating with the Background Check Common Service (BG-CS). The BG-CS uses a common schema to interact with Background Check Service Vendors and ATS (IBM Kenexa Applications). Therefore, BG-CS merely acts as a router or conduit between ATS and Vendor systems. The BG-CS interface is the Canonical Data Model for Background Checks. This includes data interactions for procurement and fulfillment of screening services. The terms Screening Service, Background Check Service and BG-CS are used interchangeably and all refer to the Background Check Common Service.

The integration schema is based on the HR-XML (2.5) recommendation, but included a few IBM-specific changes. The integration protocol is based on https post.

For the purposes of the document, the Background Check Vendors who integrate with Background Check Common Service are referred to as Vendors, Background Check Common Service Consumers (‘IBM Kenexa Applications’) as ATS, and the Background Check Common Service as BG-CS.

Versioning: HR-XML is an evolving standard; as such not all operation schemas are available, for example, Get link request to Vendor’s website (Get Vendor URL). IBM provides schema for this type of cases. This interface specification must also be a living standard within IBM, and adhere to versioning standards to ensure flexibility and completeness, while protecting any existing implementations from change and being able to support as many integrations as required. Furthermore, future versions of BG-CS should update this document rather than create a new document detailing the interface.

Integration Schema: The Integration Schema defines the data that is required for communication with the BG-CS. This includes Order Entry, Order Modification, Order Updates, Order Response, and Order Viewing. These schemas are same as HR-XML2.5 except a few variations, and all the types that were in different namespaces are flattened into one namespace. These schemas also include types that are not available in HR-XML 2.5. For example, Type for Get Vendor URL. All the types (HR-XML 2.5 and Custom) are defined under the namespace of “http://kenexa.com/Common/Screenings/Service/2.0”.

System Overview

Background Check Common Service integration illustration with Vendors and ATS by using HR-XML 2.5 and https standards.

The Background Check Common Service Architecture is based on the premise that the BG-CS ATS is able to integrate with several Vendors without needing changes per Vendor. The new Vendor integration is done with zero development effort. The changes are limited to adding new Vendor configuration at BG-CS and ATS systems. This goal is achieved with power of data abstraction that is provided by HR-XML. As illustrated in above diagram BG-CS integration can be categorized into following three operations:

Create background check request.
Background Reports (Accept status or result from Vendor)
Get Vendor URL (Get link request to Vendor website)

Vendor accepts both CreateBackgroundCheck and GetVendorUrl requests from a single URL because BG-CS sends both XML requests to the same URL.

1. Create Background Check

Create Background Check can be done in following two possible integration modes that are further detailed below:

One-Step
Two-Step

a. One-Step Integration

The One-Step integration mode is one where there is no interaction of the ATS with the Vendor’s website. The request is transparently relayed from the ATS to the Vendor, and messages from the Vendor back to the ATS. This option is available by populating the packages within the IBM® Kenexa® application, along with identifying and capturing the required field information. This is available for Vendors as their abilities permit.

The following is an overview of the standard feature set involved in One-Step integration (dependent on vendor capabilities).

List of available packages shown within ATS
Association of packages with jobs in ATS – at job code level or specific job
Request background check through ATS for given candidate (that is, set HR Status or Activity)
Request that satisfies data requirements that are automatically submitted to vendor in the background.

b. Two-Step Integration

This is the simplest form of integration that involves the ATS posting all information to the BG-CS. The BG-CS relays this information in the format or protocol specific to the Vendor. The ATS is returned a URL that redirects the user to the Vendor website where package selection and related data entry can be completed previous to submitting the order. After the order is submitted, the Vendor responds to the BG-CS with an Order Submission message and later, Order Completion information. This is transformed to the BG-CS schema and relayed to the ATS.

The following is an overview of the standard feature set involved in Two-Step integration (dependent on vendor capabilities).

Request background check through ATS for given candidate (that is, set HR Status or Activity)
Automatic authentication into vendor user interface
Data transfer of available candidate information from ATS (might require mapping)
Selection of packages or screenings, input of additional required fields, and submittal of request through vendor user interface

In both the modes, a create background check request is sent to Vendor system. The create background check request is a request for a background check order to the Vendor’s fulfillment system. It contains candidate and other important order information. A request becomes an order after the Vendor receives, accepts, and assigns it an order number. This is acknowledged back to the BG-CS. The request uses a push model for communication to and from the BG-CS.

A background check consists of one or more screenings. A screening is a particular type of search or verification procedure that is conducted as part of a background check. For example, a background check could include screenings of Criminal Check, Motor Vehicle Record Search, Education Verification, Employment Verification etc.

The steps that are involved in submitting a One-Step order are as follows.

Create background check request – BG-CS maps and sends this to the Vendor. BG-CS returns an Acknowledge message to the ATS with a transaction number.
Request goes into a load-balancing queue. Request is then routed to Vendor.
Vendor acknowledges receipt of the request, and assign an order number if request meets data requirements.
BG-CS receives the order submitted response, packages it into the BackgroundReports message, and posts asynchronously to the ATS.
ATS handles the message and updates the order status and details.

The steps that are involved in submitting a Two-Step order are as follows.

Create background check request – BG-CS receives this request and sends to the Vendor. BG-CS returns an Acknowledge message to the ATS with a redirect URL.
The user is navigated to the Vendor website, where the order entry is completed and submitted.
BG-CS receives the order submitted response and packages into the BackgroundReports message and posts asynchronously to the ATS Service.
ATS handles the message and updates the order status and details.

Important Note: For new Vendor integration, a Vendor-specific configuration is required to set up both at BG-CS and ATS. Also, for One-Step integrations, additional configuration such as package information is required to set up.

Background Check is represented by the BackgroundCheck element, which is the parent element for all background check requests. This includes information that is related to authentication (account, user id, or password), candidate demographic information (Name, SSN, and Address), Candidate History (Past addresses, Education details, Experience details, etc.) and other screening-specific fields. If a package is specified in a One-Step request (a package is usually composed of more than one screening) then the package would need all data that is required to fulfill all screenings that are requested within the package before the package is marked complete. An alternative mechanism employed by some Vendors is to allow an email to be sent to the candidate requesting the candidate to complete missing information. In the case of most Vendors, for a Two-Step process, the package is not a required field. This allows the ATS to gather whatever information is available for a candidate, and allow the user to select the packages from the Vendor website, which may or might not use the information that was sent over. This provides flexibility on the completeness of required data from a package composition perspective.

Once an order is submitted (all data is provided to the Vendor, and the order submit action is complete), the Vendor responds with an Acknowledgement to confirm that the order has been submitted. This confirmation usually includes details about the order including the screenings that are selected. This can be used by the ATS to update information that is related to the order such as order status.

The following sections include information on the XML schema to be used for a request. An XML sample is available on request.

BackgroundCheck XML schema

Request sent to Vendor

<BackgroundCheck xmlns="http://kenexa.com/Common/Screenings/Service/2.0" userId="GB-CS user ID" password="BG-CS password" account="GB-CS account for vendor">
	<!-- Authenticating credentials -->
	<BackgroundSearchPackage>
		<ProcessingInformation>
			<AccessCredential type="vendorid">ATS provided value</AccessCredential>
			<AccessCredential type="productid">ATS provided value</AccessCredential>
			<AccessCredential type="operationmode">ATS provided value</AccessCredential>
			<!-- UserName can be a shared username for multiple users, or mapped to user employee ID or email address from ATS -->
			<AccessCredential type="UserName">Vendor provided value</AccessCredential>
			<AccessCredential type="Account">Vendor provided value</AccessCredential>
			<AccessCredential type="Password">Optional (Vendor provided value) </AccessCredential>
		</ProcessingInformation>
		<ReferenceId>
			<IdValue name="UniqueKey">ATS provided value (Unique value - Identifies order submission)</IdValue>
			<IdValue name="Token">BG-CS Provided value (a BG-CS internal unique key, can be ignored by vendor)</IdValue>
		</ReferenceId>
		<ClientContact>
			<ContactMethod>
				<Telephone>
					<FormattedNumber> ATS provided value </FormattedNumber>
					<Extension> ATS provided value </Extension>
				</Telephone>
				<Mobile>
					<FormattedNumber> ATS provided value </FormattedNumber>
					<Extension> ATS provided value </Extension>
				</Mobile>
				<Fax>
					<FormattedNumber> ATS provided value </FormattedNumber>
					<Extension> ATS provided value </Extension>
				</Fax>
				<InternetEmailAddress> ATS provided value </InternetEmailAddress>
			</ContactMethod>
		</ClientContact>
		<PersonalData>
			<PersonName type="subject">
				<GivenName> ATS provided value </GivenName>
				<MiddleName> ATS provided value </MiddleName>
				<FamilyName> ATS provided value </FamilyName>
				<LegalName> ATS provided value </LegalName>
			</PersonName>
			<!-- Multiple instances: -->
			<PersonName type="alias">
				<GivenName> ATS provided value </GivenName>
				<MiddleName> ATS provided value </MiddleName>
				<FamilyName> ATS provided value </FamilyName>
				<LegalName> ATS provided value </LegalName>
			</PersonName>
			<!-- Multiple instances: -->
			<PostalAddress type="current" validFrom=" ATS provided value yyyy-mm-dd" validTo=" ATS provided value yyyy-mm-dd ">
				<CountryCode> ATS provided value </CountryCode>
				<PostalCode> ATS provided value </PostalCode>
				<Region> ATS provided value </Region>
				<Municipality> ATS provided value </Municipality>
				<DeliveryAddress>
					<AddressLine> ATS provided value </AddressLine>
					<AddressLine> ATS provided value </AddressLine>
					<Unit> ATS provided value </Unit>
				</DeliveryAddress>
			</PostalAddress>
			<!-- Multiple instances: -->
			<PostalAddress type="prior" validFrom=" ATS provided value yyyy-mm-dd " validTo=" ATS provided value yyyy-mm-dd ">
				<CountryCode> ATS provided value </CountryCode>
				<PostalCode> ATS provided value </PostalCode>
				<Region> ATS provided value </Region>
				<Municipality> ATS provided value </Municipality>
				<DeliveryAddress>
					<AddressLine> ATS provided value </AddressLine>
					<AddressLine> ATS provided value </AddressLine>
					<Unit> ATS provided value </Unit>
				</DeliveryAddress>
			</PostalAddress>
			<!-- Multiple instances: -->
			<ContactMethod>
				<Telephone>
					<FormattedNumber> ATS provided value </FormattedNumber>
					<Extension> ATS provided value </Extension>
				</Telephone>
				<Mobile>
					<FormattedNumber> ATS provided value </FormattedNumber>
					<Extension> ATS provided value </Extension>
				</Mobile>
				<Fax>
					<FormattedNumber> ATS provided value </FormattedNumber>
					<Extension> ATS provided value </Extension>
				</Fax>
				<InternetEmailAddress> ATS provided value </InternetEmailAddress>
			</ContactMethod>
			<DemographicDetail>
				<!-- Multiple instances: -->
				<GovernmentId issuingAuthority="SSN"> ATS provided value </GovernmentId>
				<DateOfBirth> ATS provided value yyyy-mm-dd </DateOfBirth>
				<GenderCode> ATS provided value </GenderCode>
				<Race> ATS provided value </Race>
			</DemographicDetail>
		</PersonalData>
		<Screenings>
			<PackageId>
				<IdValue>Vendor provided value</IdValue>
			</PackageId>
			<ClientReferences>
				<!-- Multiple instances: -->
				<!--ClientReferences/IdValue can contain custom fields required by vendor, limit of 12 available -->
				<IdValue name="Vendor provided value">Vendor provided value</IdValue>
			</ClientReferences>
			<SupportingDocumentation>
				<Documentation>
					<Text> ATS provided value </Text>
					<InternetWebAddress> ATS provided value </InternetWebAddress>
				</Documentation>
			</SupportingDocumentation>
			<UserArea>
				<PositionAppliedFor> ATS provided value </PositionAppliedFor>
			</UserArea>
			<CopyToApplicant> ATS provided value </CopyToApplicant>
			<!-- Multiple instances: -->
			<Screening type="education">
				<SearchEducation>
					<EducationHistory>
						<SchoolOrInstitution schoolType=" ATS provided value ">
							<SchoolName> ATS provided value </SchoolName>
							<PostalAddress>
								<CountryCode> ATS provided value </CountryCode>
								<Region> ATS provided value </Region>
								<Municipality> ATS provided value </Municipality>
							</PostalAddress>
							<Degree degreeType=" ATS provided value ">
								<DegreeName> ATS provided value </DegreeName>
								<DegreeDate>
									<StringDate> ATS provided value yyyy-mm-dd </StringDate>
								</DegreeDate>
								<DatesOfAttendance>
									<StartDate>
										<StringDate> ATS provided value </StringDate>
									</StartDate>
									<EndDate>
										<StringDate> ATS provided value yyyy-mm-dd </StringDate>
									</EndDate>
								</DatesOfAttendance>
							</Degree>
						</SchoolOrInstitution>
					</EducationHistory>
					<AdditionalItems>
						<Text> ATS provided value </Text>
					</AdditionalItems>
				</SearchEducation>
			</Screening>
			<!-- Multiple instances: -->
			<Screening type="employment">
				<!-- SearchEmployment  type can be either "current" or "prior" -->
				<SearchEmployment type=" [current | prior] ">
					<EmploymentHistory>
						<EmployerOrg>
							<EmployerOrgName> ATS provided value </EmployerOrgName>
							<PositionHistory>
								<Title> ATS provided value </Title>
								<Description> ATS provided value </Description>
								<StartDate>
									<StringDate> ATS provided value yyyy-mm-dd </StringDate>
								</StartDate>
								<EndDate>
									<StringDate> ATS provided value yyyy-mm-dd </StringDate>
								</EndDate>
								<Compensation>
									<EndingCompensation intervalType=" ATS provided value " currency=" ATS provided value "> ATS provided value </EndingCompensation>
								</Compensation>
								<Verification>
									<ContactInfo>
										<PersonName>
											<FormattedName> ATS provided value </FormattedName>
										</PersonName>
										<ContactMethod>
											<Telephone>
												<FormattedNumber> ATS provided value </FormattedNumber>
												<Extension> ATS provided value </Extension>
											</Telephone>
											<Mobile>
												<FormattedNumber> ATS provided value </FormattedNumber>
												<Extension> ATS provided value </Extension>
											</Mobile>
											<Fax>
												<FormattedNumber> ATS provided value </FormattedNumber>
												<Extension> ATS provided value </Extension>
											</Fax>
											<InternetEmailAddress> ATS provided value </InternetEmailAddress>
											<Location> ATS provided value </Location>
											<PostalAddress>
												<CountryCode> ATS provided value </CountryCode>
												<PostalCode> ATS provided value </PostalCode>
												<Region> ATS provided value </Region>
												<Municipality> ATS provided value </Municipality>
												<DeliveryAddress>
													<AddressLine> ATS provided value </AddressLine>
													<AddressLine> ATS provided value </AddressLine>
												</DeliveryAddress>
											</PostalAddress>
										</ContactMethod>
									</ContactInfo>
									<PermissionToContact> ATS provided value </PermissionToContact>
									<ReasonForLeaving> ATS provided value </ReasonForLeaving>
								</Verification>
							</PositionHistory>
						</EmployerOrg>
					</EmploymentHistory>
					<AdditionalItems>
						<Text> ATS provided value </Text>
					</AdditionalItems>
				</SearchEmployment>
			</Screening>
			<!-- Multiple instances: -->
			<Screening type="military">
				<SearchMilitary>
					<MilitaryHistory>
						<ServiceDetail branch=" ATS provided value "/>
					</MilitaryHistory>
					<AdditionalItems>
						<Text> ATS provided value </Text>
					</AdditionalItems>
				</SearchMilitary>
			</Screening>
			<!-- Multiple instances: -->
			<Screening type="criminal">
				<SearchCriminal>
					<AdmittedCharges>
						<CriminalCase>
							<!-- Multiple instances: -->
							<Charges>
								<ChargeOrComplaint> ATS provided value </ChargeOrComplaint>
								<ChargeTypeClassification> ATS provided value </ChargeTypeClassification>
							</Charges>
						</CriminalCase>
					</AdmittedCharges>
					<AdditionalItems>
						<Text> ATS provided value </Text>
					</AdditionalItems>
				</SearchCriminal>
			</Screening>
			<!-- Multiple instances: -->
			<Screening type="reference">
				<SearchReference>
					<Contact>
						<PersonName>
							<FormattedName> ATS provided value </FormattedName>
						</PersonName>
						<ContactMethod>
							<Telephone>
								<FormattedNumber> ATS provided value </FormattedNumber>
								<Extension> ATS provided value </Extension>
							</Telephone>
							<Mobile>
								<FormattedNumber> ATS provided value </FormattedNumber>
								<Extension> ATS provided value </Extension>
							</Mobile>
							<Fax>
								<FormattedNumber> ATS provided value </FormattedNumber>
								<Extension> ATS provided value </Extension>
							</Fax>
							<InternetEmailAddress> ATS provided value </InternetEmailAddress>
							<PostalAddress>
								<Region> ATS provided value </Region>
							</PostalAddress>
						</ContactMethod>
						<YearsKnown> ATS provided value </YearsKnown>
					</Contact>
					<AdditionalItems>
						<Text> ATS provided value </Text>
					</AdditionalItems>
				</SearchReference>
			</Screening>
			<!-- Multiple instances: -->
			<Screening type="license">
				<SearchLicense>
					<License>
						<LicenseNumber> ATS provided value </LicenseNumber>
						<LicensingAgency> ATS provided value </LicensingAgency>
						<!--LicenseName can be used to indicate if it is Driver's license screening or professional certificate-->
						<LicenseName> ATS provided value </LicenseName>
						<LicenseDescription> ATS provided value </LicenseDescription>
						<EffectiveDate>
							<StartDate>
								<StringDate> ATS provided value yyyy-mm-dd </StringDate>
							</StartDate>
							<EndDate>
								<StringDate> ATS provided value yyyy-mm-dd </StringDate>
							</EndDate>
						</EffectiveDate>
					</License>
					<AdditionalItems>
						<Text> ATS provided value </Text>
					</AdditionalItems>
				</SearchLicense>
			</Screening>
			<!-- Multiple instances: -->
			<Screening type="drug">
				<SearchDrugs>
					<SpecimenIdNumber>
						<IdValue> ATS provided value </IdValue>
					</SpecimenIdNumber>
					<AdditionalItems>
						<Text> ATS provided value </Text>
					</AdditionalItems>
				</SearchDrugs>
			</Screening>
		</Screenings>
	</BackgroundSearchPackage>
</BackgroundCheck>

Response expected from Vendor

For one-step operation:

<ApplicationAcknowledgement xmlns="http://kenexa.com/Common/Screenings/Service/2.0">
	<PayloadResponseSummary>
		<ProcessingTimestamp description="(optional)">Vendor provided value</ProcessingTimestamp>
		<AcknowledgementCreationTimestamp> Vendor provided value </AcknowledgementCreationTimestamp>
	</PayloadResponseSummary>
	<PayloadDisposition>
		<EntityDisposition>
			<EntityInstanceXPath>(optional)</EntityInstanceXPath>
			<EntityIdentifier>
				<IdValue name= “BackgroundCheckOrderNumber"> (vendor order ID) </IdValue>
			</EntityIdentifier>
			<EntityNoException> true/false </EntityNoException>
			<EntityException>
				<Exception>
					<ExceptionIdentifier>(optional)</ExceptionIdentifier>
					<ExceptionSeverity> (optional) </ExceptionSeverity>
					<ExceptionMessage> (required)</ExceptionMessage>
				</Exception>
			</EntityException>
		</EntityDisposition>
	</PayloadDisposition>
</ApplicationAcknowledgement>

For two-step operation:

<ApplicationAcknowledgement xmlns="http://kenexa.com/Common/Screenings/Service/2.0">
	<PayloadResponseSummary>
		<ProcessingTimestamp description="Vendor provided value">Vendor provided value</ProcessingTimestamp>
		<AcknowledgementCreationTimestamp> Vendor provided value </AcknowledgementCreationTimestamp>
	</PayloadResponseSummary>
	<PayloadDisposition>
		<EntityDisposition>
			<EntityInstanceXPath> Vendor provided value </EntityInstanceXPath>
			<EntityIdentifier>
				<IdValue name=" BackgroundCheckRedirectURL "> Vendor provided value </IdValue>
			</EntityIdentifier>
			<EntityNoException> Vendor provided value (true/false) </EntityNoException>
			<EntityException>
				<Exception>
					<ExceptionIdentifier> Vendor provided value </ExceptionIdentifier>
					<ExceptionSeverity> Vendor provided value </ExceptionSeverity>
					<ExceptionMessage> Vendor provided value </ExceptionMessage>
				</Exception>
			</EntityException>
		</EntityDisposition>
	</PayloadDisposition>
</ApplicationAcknowledgement>

2. Background Reports (Accept Background Check Status and Results from Vendor)

After the background check is completed by the Vendor, results are sent back in the Background Reports Message. This is received asynchronously from the request. Background Reports consist of screening results of one or more screenings that are requested in the Background Check Request.

The following sections include information on the XML schema to be used in the reports. An entire XML sample is available on request.

Request from Vendor

<BackgroundReports xmlns="http://kenexa.com/Common/Screenings/Service/2.0" account="" userId=" (optional) ">
	<BackgroundReportPackage type=" (optional) ">
		<ProcessingInformation>
			<AccessCredential type="Vendor"> (Vendor Name, required) </AccessCredential>
		</ProcessingInformation>
		<ProviderReferenceId>
			<IdValue> (required, vendor order id, uniquely identifies order) </IdValue>
		</ProviderReferenceId>
		<ClientReferenceId>
			<IdValue> (Rreuired, this is the same UniqueKey sent from the backgroundCheck Order)</IdValue>
		</ClientReferenceId>
		<PackageId>
			<IdValue> (optional) </IdValue>
		</PackageId>
		<ScreeningStatus>
			<OrderStatus> (required) </OrderStatus>
			<ResultStatus> (optional) </ResultStatus>
			<Score> (optional) </Score>
			<DateOrderReceived> (required) </DateOrderReceived>
		</ScreeningStatus>
		<ScreeningsSummary>
			<PersonalData>
				<PersonName>
					<GivenName> (required) </GivenName>
					<MiddleName> (needed if available) </MiddleName>
					<FamilyName> (required) </FamilyName>
				</PersonName>
			</PersonalData>
			<ClientReferences>
				<IdValue name=" (optional) "> (optional) </IdValue>
			</ClientReferences>
		</ScreeningsSummary>
		<Screenings>
			<!-- Multiple instances: -->
			<Screening qualifier=" (optional) " type=" (optional) ">
				<ScreeningStatus>
					<OrderStatus> (optional) </OrderStatus>
					<ResultStatus> (optional) </ResultStatus>
				</ScreeningStatus>
			</Screening>
		</Screenings>
	</BackgroundReportPackage>
</BackgroundReports>

Response sent to Vendor (this is IBM Kenexa proprietary)

<BackgroundReportResponse>
	<Status> (success / fail) </Status>
	<Description> (error message if fail) </Description>
</BackgroundReportResponse>

Post Background Check Results to ATS

The background check results are asynchronously posted from the BG-CS to the ATS. This implies that the ATS must implement a web service, or a web page that handles the results posted to it. The ATS, after receiving the results, must post an Acknowledge message back to the BG-CS to confirm receipt of the results.

3. Get Vendor URL (Get link request to Vendor website)

ATS can use another BG-CS operation called Get Vendor URL, which returns the appropriate URL for viewing order details within the Vendor system. Validation occurs by BG-CS to authenticate ATS, and returns a redirect URL based on the Vendor support for one of the two options.

The returned URL from BG-CS is, depending on Vendor support:

Configured Hard link that requires a subsequent login by the user in Vendor system.
Automatic authentication link that authenticates the user and automatically redirects to the order details page in Vendor system. This can be achieved when BG-CS route ATS request to Vendor supported GetVendorURL operation. Upon triggering this operation vendor generates an expiring link and sending the same in response.

Request sent to Vendor

<VendorUrlRequest xmlns="http://kenexa.com/Common/Screenings/Service/2.0" type="view" vendor="BG-CS provided value" productId="BG-CS provided value" account="Vendor provided value" userId="Vendor provided value" password="Vendor provided value">
	<ProviderReferenceId> Vendor provided value (vendor background order number) </ProviderReferenceId>
	<AccountCredential>
		<Account> (client ordering account) </Account>
		<UserName> (client user name) </UserName>
		<!--password and token will not be provided -->
		<Password/>
		<Token/>
	</AccountCredential>
</VendorUrlRequest>

Response from Vendor

<ApplicationAcknowledgement xmlns="http://kenexa.com/Common/Screenings/Service/2.0">
	<PayloadResponseSummary>
		<ProcessingTimestamp description="Link Response"/>
		<AcknowledgementCreationTimestamp/>
	</PayloadResponseSummary>
	<PayloadDisposition>
		<EntityDisposition>
			<EntityInstanceXPath/>
			<EntityIdentifier>
				<IdValue name="Status">Complete</IdValue>
				<IdValue name="LinkURL"> Vendor provided value </IdValue>
			</EntityIdentifier>
		</EntityDisposition>
	</PayloadDisposition>
</ApplicationAcknowledgement>

A valid LinkURL should always be returned from vendor even if the result is not ready. Kenexa ATS always follows the LinkURL to redirect user to vendor’s web page. When the result is not ready, or the result cannot be displayed for some reason (that is, user not authorized to view report), a meaningful message should be displayed.

Implementation Setup Iinformation Needed from Vendor:

To start integration testing the following is needed from Vendor:

Is this integration a one-step or two-step integration?
What communication protocol does this integration use? SOAP or pureXML through HTTP POST?
IBM Kenexa Background Check Common Service system has systems in US and EU with different endpoints. US clients are set up in BGCS US system and EU clients are set up in BGCS EU system. Which system is the vendor to integrate with? or both?
Vendor needs to complete the mapping document with the column highlighted (Required by Vendor), indicating Required (R), Optional (O), or Not used (N/A).
Provide us the URL (test environment) for sending request to create BackgroundCheck order and request for getVendorURL. This needs to be configured in the common service staging environment.

Provide us the test account/username/password for both integration account and test client account. IBM configures the staging common service environment for integration test.

Common Service Integration account:

<BackgroundCheck account="" password="" userId="">

Client Test Account:

<BackgroundCheck>
    <BackgroundSearchPackage>
        <ProcessingInformation>
            <AccessCredential type="Account"/>
            <AccessCredential type="UserName"/>
            <AccessCredential type="Password"/>

If this is one-step integration, then provide the PackageID they would use for testing.
For US system integration, configure your system to send background results back to common service staging at:
https://comsvc-stage.kenexa.com/v2/BackgroundCheckService/BackgroundCheckResponse

For EU system integration, configure your system to send background results back to common service staging at:

https://comsvc-eu.kenexa.com/v2/BackgroundCheckService/BackgroundCheckResponse
After the test is complete, before the integration is certified, the setup information (2,3,4) for production environment is needed. Also, configure your production system to point to our common service production URL:
US: https://comsvc.kenexa.com/v2/BackgroundCheckService/BackgroundCheckResponse

EU: https://comsvc-eu.kenexa.com/v2/BackgroundCheckService/BackgroundCheckResponse

Implementation Guidelines to vendor:

There is only one integration account per vendor as it is used to identify integration between BG-CS and a vendor. This integration account is configured in BG-CS.

There can be multiple client integration accounts configured in ATS system, each to identify a client integration that is configured to integrate with background check vendor though BG-CS

When ATS send background check request to BG-CS, it only contains client integration account credentials. BG-CS then adds the BG-CS integration account information in the request before route it to vendor (ATS or user does not have BG-CS integration account information).

For security reasons, the integration partner needs to verify both BG-CS integration account and client integration account.

Note: Vendor should accepts both CreateBackgroundCheck and GetVendorUrl requests from a single URL because BG-CS sends both XML requests to the same URL.

Schema files defined in Appendix B.
- CommonServicesTypes.xsd – Vendor host endpoint by using this schema.
- BackgroundReportTypes.xsd – IBM host endpoint by using this schema
Host an endpoint and possibly integrate it with existing system. There are the two ways to host endpoint:
- Simple XML through HTTP endpoint: This accepts the xml packet as per the schemas in CommonServicesTypes.xsd. In this option, only IBM schemas are used.
- SOAP WebService endpoint: If this option is selected, then Vendor should use the wsdl that is provided in Appendix A. In this option, both IBM schema and wsdl are used.
Endpoint should support following two operations:
- CreateBackgroundCheck – Receives request, generates order and ApplicationAcknowledgment as response.
- GetVendorURL – Receives request, generate non-expiring auto login link and ApplicationAcknowledgment
Vendors are free to choose their convenient platform and technology to do this.
The endpoint should be supporting https xml post.

Integration with multiple data centers:

Currently common service system is available in two data centers - US data center and EU data center. Common service US data center is integrated with US ATS (BrassRing US) and common service EU data center is integrated with EU ATS (Brassring EU). If vendor needs to support both US and EU customers then it is suggested to also have two environments to integrate with our two systems. If for some reason vendor only has one system available then vendor needs to be able to post background result status back to the correct US or EU endopoints.

One way to tell if an order request was from US or EU data center is by referring to the productid field in the below XML document. Where it can contain the following values:

KRBPROD - Kenexa Recruiter BrassRing Prod in US
KRBPRODEU - Kenexa Recruiter BrassRing Prod in EU
KRBSTG - Kenexa Recruiter BrassRing Staging in US
KRBSTGEU - Kenexa Recruiter BrassRing Staging in EU

<BackgroundSearchPackage>
		<ProcessingInformation>
			<AccessCredential type="vendorid"> (The vendor ID) </AccessCredential>
			<AccessCredential type="productid"> [KRBPROD/KRBPRODEU/KRBSTG/KRBSTGEU] </AccessCredential>

Appendix A – WSDL

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="BackgroundCheckService" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:messages="http://kenexa.com/Common/Screenings/Service/2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://kenexa.com/Common/Screenings/Service/2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<wsdl:types>
		<xs:schema attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://kenexa.com/Common/Screenings/Service/2.0">
			<xs:include schemaLocation="CommonServicesTypes.xsd"/>
		</xs:schema>
	</wsdl:types>
	<wsdl:message name="BackgroundCheckRequest">
		<wsdl:part element="messages:BackgroundCheck" name="BackgroundCheckRequest"/>
	</wsdl:message>
	<wsdl:message name="Acknowledge">
		<wsdl:part element="messages:ApplicationAcknowledgement" name="Acknowledge"/>
	</wsdl:message>
	<wsdl:message name="VendorUrlRequest">
		<wsdl:part element="messages:VendorUrlRequest" name="VendorUrlRequest"/>
	</wsdl:message>
	<wsdl:portType name="BackgroundCheckPort">
		<wsdl:operation name="CreateBackgroundCheck">
			<wsdl:input message="messages:BackgroundCheckRequest"/>
			<wsdl:output message="messages:Acknowledge"/>
		</wsdl:operation>
		<wsdl:operation name="GetVendorUrl">
			<wsdl:input message="messages:VendorUrlRequest"/>
			<wsdl:output message="messages:Acknowledge"/>
		</wsdl:operation>
	</wsdl:portType>
	<wsdl:binding name="BackgroundCheckBinding" type="messages:BackgroundCheckPort">
		<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
		<wsdl:operation name="CreateBackgroundCheck">
			<soap:operation style="document" soapAction=""/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
		</wsdl:operation>
		<wsdl:operation name="GetVendorUrl">
			<soap:operation style="document" soapAction=""/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
		</wsdl:operation>
	</wsdl:binding>
	<wsdl:service name="BackgroundCheckService">
		<wsdl:port binding="messages:BackgroundCheckBinding" name="BackgroundCheckPort">
			<soap:address location="REPLACE_WITH_ACTUAL_URL"/>
		</wsdl:port>
	</wsdl:service>
</wsdl:definitions>

Appendix B – Common Service XML Schemas

Get following XSD’s from IBM:

CommonServicesTypes.xsd – Types defined for implementing CreateBackgroundCheck and GetVendorURL operation.
BackgroundReportTypes.xsd – IBM hosted results endpoint by using the types that are defined in this xsd.

: Email WatsonTalentTraining@us.ibm.com if you have a suggestion for improvement, or encounter an issue on this documentation. Include the product and page title in your email.