Integrations Part-1

26 Jul 2024
38 Minutes to read

Print
Share
Dark
Light

Integrations Part-1

Updated on 26 Jul 2024
38 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

THE MAPPING TOOL

Abstract

Product: Workbench

Mapping Tool

The BrassRing Mapping Tool offers you the ability to configure flexible, secure XML integrations.

Self-service and no special training is required.
After an integration is configured in the Mapping Tool, changes can be made by your team at any time. Unless the integration is a premium or custom integration.
Versioning tracks any changes that are made to the integration.
The Mapping Tool can be used by any team member with Tier 0+ access, however it is recommended that a technical resource completes or assists with the completion of the configuration.

The Mapping Tool does not support:

Non-XML Integrations (FTP).
XML does not support full or initial Loads. Infinite recommends that these are completed by using a Workbench Import before to turning on the integration.

Services Provided

Workbench users can build integrations by using a self-service method with no Infinite assistance. No cost associated. If questions arise and guidance is needed a case can be entered with the Product Experts and no cost associated.
If the client is not comfortable with or does not have the resources to build the integration using the mapping tool, then services can be purchased through Infinite Talent. Services would be scoped.
If the client’s vendor cannot work with the pre-defined XML in the mapping tool and needs a custom solution then a premium or custom integration can be built. Services would be scoped.
If the integration desired is outside of XML then Infinite assistance is needed. Services would be scoped.

Mapping Tool Workflow

All integrations must be created and edited in Staging first and then published to Production.

Create project
Create a draft, add the Integration, and Map the fields.
Save the draft and make Version.
Activate the Integrations in Staging and test.
Publish the Integrations to Production.
Activate the Integrations in Production.

Mapping Tool Support

The following resources can be found in the Mapping Tool in the Resources link.

XML Test Harness.
Infinite IP Addresses.
Integration Post URLs.
Mapping Tool Offerings.

Relevant eLearning

Process

Create a Project

Select Tools → Integrations → Mapping Tool.
Select Add Project.
Enter the project details.
Select the Integration Type and select Add.
Enter the properties.
- HRStatus (Type Level): Always selected for Candidate Exports. Indicates that the integration is triggered by an HR Status.
- TalentRecordLaunch (Type Level): No longer used.
- Export: Code or Description. Export either the code or description of option list fields that are pulled into the integration.
- UTFType: UTF8 or UTF16. This is defaulted to UTF8 and should be left unless UTF16 is needed by the vendor.
- ClientErrorMessage: No longer used.
- EmailNotificationOnError: No longer used.
- HRStatus (Subscription Level): Always selected for Candidate Exports. Indicates that the integration is triggered by an HR Status.
- TalentRecordLaunch (Subscription Level): No longer used.
- Status Trigger: Defines which HR Status triggers the integration to run. Multiple HR Statuses can be selected.
- Post URL (Transmission Type URL): Target URL where the Candidate Export XML is sent at the vendor’s endpoint. If the URL https://ingrationsstaging.Kenexa.com or
  https://integrationsproduction.Kenexa.com is shown this means that the integration is a Layer 7 integration and must only be edited by an Infinite technical team member.
- Export Requisition Data with Candidate: Tied to client setting IntegrationExpReqWithCandidate and should be changed with utmost caution. Client settings can only be edited by an Infinite representative. The change impacts all of the candidate export integrations in your account. The setting drives if req form fields should be mapped into the integration. If it is required to change this setting, test ALL candidate export integrations after making the update.
- Export Single Candidate: No longer used.
- RedirectURL: No longer used.
- UserTypes: Lists all User Types in the client’s account. The user types that are selected are allowed to trigger the candidate export integration. If no user type is selected, then
- ANY user type can trigger the integration.
- TransmissionType: Only option or protocol is httppost. If the endpoint does not support httppost the Mapping Tool cannot be used.
- TransmisionURL Type: Only option is Custom.
- SSL Validate: No longer used
- Post Format: Options include form or XML. Ask the vendor which option to use. Form or XML works most of the time.
- HTTP Post content type: Options included: form, XML, SOAP 1.1, SOAP 1.2, UTF-8. Ask the vendor which option to use. If the vendor does not know what format is used, test each option until a successful test is received.
- Encrypt: No longer used.
- Escape Ampersands: Escape the ampersands to make the XML safe for the vendor. Removes the & character that is not supported in XML.
- AuthenticationType: Available option = Basic Authentication. Can be used to use basic authentication to secure the integration, for example username and password.
- AuthenciationKeyGroup: Keygroup Name for basic authentication. Select the icon to name the Keygroup and define the Username and Password, then select that Keygroup.
- URLEncodePost: No longer used.
- Export Country ISO Codes: Options included: Default, 2 Character ISO, 3 Character ISO. Sends 2 or 3 ISO codes for the country name when using the standard country option lists in BrassRing. Default sends the entire country name.
- Export State 2 Character ISO Codes: If yes is selected, then the 2 character ISO code for the state is sent if using the standard state option list in BrassRing. This only works for US States. International states still send the full name. If no is selected then the entire state name is sent.
- SubscriptionName: The name of the integration.
Select Save.
Select Save to return to the project page.
Select the project in the Please Select a Project field, then select Map Draft.
Select the integration in the Integration Type field, and select the Integration instance.
Map the fields by selecting a field and selecting Add to Mapped Fields. Forms can also be added which adds all fields from the form to the mapped fields.
1. XML fields can be edited to match the vendors or your organizations HRIS requirements. Editing an XML field might produce errors in other integrations that use that field. To edit an XML field, select the pencil icon for the Mapped Field. Update the XML tag as needed and select Save.
  1. XML tags can be customized, however it is recommended to use the default XML tag found in the mapping tool.
  2. [Applicant Master fields] can be customized with different XML tags on different integrations.
  3. If your organization customizes an XML tag for a custom field, all other integrations that use that field from the form must be updated to the customized XML tag, as the
  4. XML tag name is updated on the question.
  5. Infinite recommends creating a mapping document to track XML tag names as a reference is useful for maintenance and later updates. For more information, please see Common Service Integrations Mapping Document in this page.
2. Select the Delete icon to delete any mapped fields.
Select Save.
If the sample XML is needed to be sent to the HRIS, select Sample XML.
1. Select Save XML. This XML can be sent to the HRIS to be approved in your organizations HRIS
2. Select Exit to close the window.
Select Approval.
If the integration is ready, select the integration and select Make Version.
Select Projects.
Select the project in the Please Select a Project field, then select the integration in the Version History field.
The Configured status is No. The configured status describes whether the integration is active. Select Configuration.
To activate the integration in the Staging environment select the Configure instance icon.
1. If needed select the Properties icon to view the properties of the integration.
The integration should be tested in the Staging environment.
After all tests are completed select Publish to Producion to publish the integration to the production environment. This performs a check to verify that all of the fields enabled in staging are pulled into production, and pulled into the integration.
1. The database field names in the staging environment should match the database field names in the production environment.

API REFERENCE DOCUMENTS

Abstract

API Reference documents for Inbound direction of data, Outbound direction of data, Single-Sign On (SSO), and Assessments.

Inbound direction of data Application Programming Interface (API) Reference documents (Client/Vendor to BrassRing)

These documents present a detailed view of the architecture and design of the Infinite Talent BrassRing on Cloud Integration offerings. The BrassRing XML integration offerings allow Infinite to work with our clients to configure multi-level, robust integration relationships between BrassRing and any system that can send and receive XML. Examples of these systems include HRIS (i.e. SAP, Oracle, etc.) and systems that perform HR related services like background checks, assessments, or compensation analysis.

Outbound direction of Data Application Programming Interface (API) Reference documents (BrassRing to Client/Vendor)

Candidate Export Technical Specifications API (DOCX)
Data Warehouse Process Specifications (DOCX)
Get Candidate API (PDF)
Rules Automation Manager (RAM) Technical Specifications API (DOCX)
XML Integration Mapping Document Template (XLSX)

Single Sign-on (SSO) Application Programming Interface (API) Reference documents

SAML SSO Technical Specifications API (DOCX)
Talent Gateway Profile Import Specifications API (DOCX)

Assessment APIs

Assessment API Guide (DOCX)

TALENT GATEWAY JOBS AND CANDIDATE API REFERENCE GUIDE (API REFERENCE GUIDE)

Abstract

Talent Gateway jobs and Candidate API Reference Guide (API Reference Guide)

Application Programming Interface (API) Reference

The Talent Gateway Jobs API guide linked on this page provides additional technical information regarding the set up of the API. We have also provided a simplified process in the steps below to get you started.

What can our Talent Gateway Jobs API be used for?

Pulling Req information via XML from the gateway to place out on other sites such as the Corporate Career Site, a microsite, or a Job Board.
Create a “deep link” to pre-defined search results.
Create an RSS feed to for your Corporate Career Site or a vendor-hosted site.

What can our Talent Gateway Jobs API show you?

The API will only be able to show information that is on the talent gateway. It will appear as a search that is completed on the talent gateway. However, you will be able to use a direct link; RSS feed; or XML to move that information to another site such as a Career page or a vendor’s page such as Indeed.com.

Should the below instructions not provide enough technical guidance or answer your questions, please review the document Infinite Talent BrassRing Candidate TG API

How to Build a Talent Gateway Jobs API:

Enable the Client Setting. Contact your Infinite representative to complete this task for you.
Enable the Talent Gateway Settings. Tier 5+ users can complete this step.
1. In Workbench, select Tools → Talent Gateways.
2. Edit the Talent Gateway to run the query against.
3. Enable the Allow the Web service to query this gateway setting.
4. Optionally, enable the Require encryption setting to encrypt your Jobs API.
5. Select Save.
  - During this step, make note of the Talent Gateway Site ID and Client ID (example below). The Client ID is specific to your account and is the same between Staging and Production. The Site ID will be unique per gateway and also per environment.
Synchronize the Talent Gateways by selecting Synchronize changes with Talent Gateways.
Create a ‘Dummy’ User
- When building the Jobs API, you will need to create a user specifically for the use of the API. You could use an existing user’s profile. However, if you do so, you run the risk that if that person’s account is ever inactivated due to leaving the company; the APIs will no longer work. It is recommended to create one ‘dummy’ user specific to the APIs that will not be inactivated. Once a user is created, you will not need to create the user again. Below are the steps to create a user.
  1. In BrassRing, select Menu → Admin → Admin+ → Users → .
  2. Select Add New User.
  3. Complete the required fields including the EMPLOYEE ID field. This is important as it will be one of the IDs that the API requires. Tip: The Employee ID that you add should not be a valid ID within your organization or one that will ever be used.
Look Up Question IDs (QIDs). Tier 5+ users can complete this step.
- Question IDs (QIDs) can be used in the API to limit the search results for a deep link, the jobs pulled back in an XML feed, or an RSS feed of jobs. For example, if you want a deep link that will show all jobs located in Nebraska for a vitual jobs map that your web development team is building, you can use the QID for your State field in the API to pull back only those jobs. Fields that you would like to filter on must be on the Search Jobs page of the Talent Gateway.
- Questions IDs (QIDs) can be used in the API to pull back information about the requisition in an XML feed. For example, if you want to pull back the Department, Location, Job Category, and Position Type, you can use the QIDs for these fields in the API to pull back the information that was entered on the req form. Fields that you would like to pull back information on must be on the Job Detials page of the Talent Gateway.
  1. In `Workbench, select Tools → Forms → Reqs → Req Forms.
  2. Select Preview XML Talent Gateway Integration.
  3. Make your selection from the list of Standard and Custom Req fields that are available and select Preview XML.
  4. Find the QIDs for each field. For example, the QID for the Location(s) field is 82883. For example:
Prepare the Tags by Collecting the IDs from Steps 2-5. Examples below.
- <Id>123456</Id> Is the Employee ID of the active dummy BrassRing user. (Step 4)
- <Credential>26286</Credential> Is the Client ID and is unique per client, but not per environment. (Step 2)
- <ClientId>26286</ClientId> Is the Client ID and is unique per client, but not per environment. (Step 2)
- <SiteId>6441</SiteId> Is the Talent Gatway site ID. This is unique per Talent Gateway, per environment. (Step 2)
- <OutputXMLFormat>0</OutputXMLFormat> The options for this XML node are:
  - “0” if you would like XML returned
  - “1” if you would like a RSS feed returned
  - “2” if you would like a link (deep-link) returned
- <Id>82883</Id> Is an example of a QID of a field that exists on the Talent Gateway Job Details page and that you would like to have pulled back in the XML. These are unique per question, per environment. (Step 5)
- <Value><![CDATA[Lincoln NE]]> Is an example of an option within the Locations field on the Talent Gateway. Adding an option, or options, to this CDATA section will filter the results that are returned. If you are wanting to filter by multiple options you will separate the options with a comma (<Value><![CDATA[Lincoln, NE, Boston, MA]]>). (Note: Use the DESCRIPTION of the option, not the code.) If you do not want to filter the results you will want the tag to read <![CDATA[TG_SEARCH_ALL]]>.
Plug your IDs into the Sample Input XML below. This is a simple input XML that provides us a Link (deep-link) to jobs that are posted in “Lincoln, NE”.
<Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>2</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Id>82883</Id><Value> <![CDATA[Lincoln, NE]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>
Make the call. Access the appropriate Web Service Router URL:
- Staging Environment: http://stagingimport.brassring.com/WebRouter/WebRouter.asmx
- US Production Environment: http://Import.brassring.com/WebRouter/WebRouter.asmx
- EU - Production Environment: http://krb-jobs.brassring.com/WebRouter/WebRouter.asmx
  1. Select route.
  2. Place your XML into the inputXml field and select Invoke.
Clean up the URL. Retrieve the URL from the returned XML.
Example: https://sjobs.brassring.com/tgwebhost/searchresults.aspx?PartnerId=26286&SiteId=6441&Function=LinkQuery&LinkId=2405072
Remove the “amp;” values from the URL. https://sjobs.brassring.com/tgwebhost/searchresults.aspx?PartnerId=26286&SiteId=6441&Function=LinkQuery&LinkId=2405072
- A unique linkID is created each time the input XML is invoked in the router URL. It is incremental based on the database the client's data is stored in.

ADDITIONAL SAMPLE XMLS

XML: Pull back all jobs, via XML, that are posted on the Talent Gateway. This XML will contain the req information and a direct link to the job posting. (The direct URL will have to be cleaned up by removing the “amp;” values.)
<Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>0</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Value> <![CDATA[TG_SEARCH_ALL]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>
XML: Pull back all jobs and specific field information, via XML, that is posted on the Talent Gateway. The resulting XML will include the direct link to the job posting. (The direct URL will have to be cleaned up by removing the “amp;” values.)
<Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>0</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <ReturnJobDetailQues>3916,3920,3923,82883</ReturnJobDetailQues><ReturnLongJobDetailQues/> <Questions> <Question Sortorder="ASC" Sort="No"> <Value> <![CDATA[TG_SEARCH_ALL]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>
XML: Pull back all jobs, their full Job Descriptions, the Recruiter’s information, and the Hiring Manager’s information. The resulting XML will include the direct link to the job posting. (The direct URL will have to be cleaned up by removing the “amp;” values.)
<Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>0</OutputXMLFormat> <JobDescription>YES</JobDescription> <IncludeAllRecruiterInfo>Yes</IncludeAllRecruiterInfo><IncludeAllHiringManagerInfo>Yes</IncludeAllHiringManagerInfo><AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Value> <![CDATA[TG_SEARCH_ALL]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>
Link: Creating a deep-link by filtering on/pulling back job search results for two options (within one field).
<Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>2</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Id>82883</Id> <Value> <![CDATA[Lincoln, NE, Boston, MA]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>
Link: Creating a deep-link by filtering on/pulling back job search results for multiple fields.
<Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>2</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Id>82883</Id> <Value> <![CDATA[Lincoln, NE]]></Value></Question><Question Sortorder="ASC" Sort="No"> <Id>3916</Id> <Value> <![CDATA[Customer Service]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>

JOB BOARD AGGREGATOR INTEGRATION

Abstract

Product: Workbench

Job Board Aggregator Integration

Job Board Aggregator Integrations are Common Services integrations that have been developed for our customers to easily integrate BrassRing with job aggregators. Details of the job are passed from BrassRing to the aggregator vendor through the integration. The BrassRing user can then select what job boards they would like to post the job to through the vendor’s interface.

Job Board Aggregator Integrations can be set up by customers (except for the client settings), and there is no Infinite cost associated. Customers have to partner with a vendor of ours; which might come with a contract or fee. If you would like assistance with the implementation, contact your Infinite representative.

Current Vendor Partners can be found HERE.

As with all configuration tasks in Workbench and integrations, it is recommended to first complete the work in Staging before making any updates in Production. This helps identify and resolve any potential issues before completing the task in your Production environment.

Configuration steps to implement a Job Board Aggregator integration:

Enable the client settings. This configuration task must be completed by an Infinite team member in Workbench. Contact your Infinite representative to inform them of which Job Board Aggregator vendor partner you have chosen to proceed with and have them enable the Posting partner vendor client settings.
Enable the Talent Gateway setting.
- This configuration task can be completed by any Tier 5 or Power User in Workbench.
- This setting should only be enabled for the Talent Gateways that you might send external candidates to by using the posting on the Job Board Aggregator sites.
- In Workbench, select Tools → Talent Gateways → Edit the Talent Gateway.
- Check Add as job apply URL option to Posting Partners.
Map the fields to be sent to the Job Board Aggregator vendor site.
- This configuration task can be completed by any Power User in Workbench.
- Each vendor might have different mapping options, so check with the vendor or your Infinite representative for the latest mapping document.
  1. To map fields, in Workbench, select Tools → Forms → Reqs → Req Forms.
  2. Select Define Custom Req Fields or Define Standard Req Fields based on the type of field to map.
  3. Select the Edit Field Attributes pencil for the field you would like to send to the Job Board Aggregator.
  4. Select the appropriate field to map to in the Posting interface mapping pull-down menu.
  5. Select Save.
- Complete these steps for any field to send to the Job Board Aggregator site. Each aggregator has different requirements and restrictions. It is recommended to review the mapping options before implementing these integrations. Testing in Staging should also confirm the map-ability of specific fields in your site.
Add BrassRing users to be able to post to or access the Job Board Aggregator site.
1. In BrassRing, select Menu → Admin → Posting interface defaults.
2. Select the users to allow to post to the Job Board Aggregator sites through BrassRing by selecting Edit selected users.
  1. If your Job Board Aggregator contact has setup all users with the same User name and Password, you can select all users (you want to be able to post) and enter the credentials. This adds the same credentials across all users.
  2. If your Job Board Aggregator contact has set up the users with individual user names and Passwords, you must select one user at a time to input their credentials.
3. Select Add new posting partner,
4. Select the Job Board Aggregator in the pull-down menu and enter the Account ID, user name, and Password provided by Job Board Aggregator vendor.
5. Select Save.
6. Repeat these steps, if necessary, for any users to grant posting privileges for.

The Job Board Aggregator vendor is listed on the users’ Posting Options page. Selecting the Edit pencil opens an intermediate page (BrassRing page) or takes the user directly into the vendor’s site. This depends on the client settings enabled. Users can then post the job to sites that are available through the Job Board Aggregator’s user interface.

TROUBLESHOOTING THE BRASSRING TO ONBOARD INTEGRATION

Abstract

Troubleshooting the BrassRing to Onboard Integration

Many of the Integration errors are resolvable on the client side, without the intervention of Infinite. If a support ticket must be opened, include:

Time of the integration failure
Candidate’s Name
Job Requisition Number
Error message received

Error Messages

Duplicate.record.found.create

Error Message

[Success: The Candidate and Job details already existed in Onboard, and were updated with any changed information. Please note, this may impact any information which was modified after the Candidate and Job were originally sent to Onboard.]

Old message: duplicate.job.application.found.create

Cause

The error displays when an applicant already exists in Onboard. The applicant is either identified by their Candidate Reference Number in BrassRing (CRUID), or by their email address if the CRUID does not yet exist for the applicant in Onboard.

Resolvable By

N/A

Resolution

Though the message received in BrassRing is technically an error message, Onboard still handles the data from the integration. Meaning that Onboard updates an applicant’s record with any new or changed details even though BrassRing displays the error. This is the current function of the integration and it is functioning as designed. There are no steps to resolve this error message.

Extra Information

When you receive this error message in BrassRing, the applicant, job, and user details that are sent during the BrassRing to Onboard integration have been received and updated in Onboard.

A.Valid.Applicant.CRUID.is.Required

Error Message

[Failure: Candidate Reference Number was not found. Please check the BrassRing Subscription configurations in Workbench, to confirm the Candidate Reference Number is included in the Mapping. Please check the Onboard Mapping XSLT file, in Utilities->Imports, to confirm the Candidate Reference Number is Mapped correctly.]

Old message: A.Valid.Applicant.CRUID.is.Required

Cause

The error message is displayed when the BrassRing to Onboard integration is unable to identify the Candidate Reference Number in BrassRing (CRUID) in the Response Message sent in the integration.

Resolvable By

Infinite. Open a support ticket for resolution as this requires a Mapping XSLT change in Onboard and a Subscription update in BrassRing.

Resolution

This error is caused by the Candidate Reference number being missing from the BrassRing Integration Subscription and from the Onboard Mapping XSLT.

Extra Information

This error was frequently reported when the integration was updated to require the CRUID. This error is normally encountered in testing scenarios or initial Integration configuration in the Staging Environment.

User Already Present with this email: [email protected]

Error Message

[Failure: A User already exists in Onboard with the email Address: <%Email Address%>. Please check the users on the Requisition and ensure all users have unique email addresses.]

Old: User Already Present with this email: [email protected]

Cause

The error displays when a User already exists in Onboard with the same email address but a different username.

Resolvable By

Client

Resolution

To resolve this error message, a BrassRing Req Team member can change the email address of the incoming User, or change the existing user in Onboard.

If the expectation is to have a single user in Onboard with an updated email address to match the user in BrassRing, then update the email address for the impacted user directly in Onboard by selecting Settings → Users.
If the expectation is to have two users in BrassRing with a shared email address, this is not supported in Onboard. In this case, one of the users in BrassRing must be updated with a unique email address.

Extra Information

Users in Onboard must have unique email addresses.

User Type should be mapped

Error Message

[Failure: A User on the Requisition has a User Type which does not exist in Onboard.]

Old message: UserType should be mapped.

Cause

The error message displays when the mapping between BrassRing and Onboard is not accurately selecting a User Type for an incoming user in Onboard.

Resolvable By

Infinite. Open a support ticket for resolution as this requires a Mapping XSLT change in Onboard.

Resolution

Questions to ask:

If a new User Type was recently added to BrassRing, was the corresponding User Type entered in Onboard?
If a new User Type was recently added to BrassRing, was the Mapping XSLT file in Onboard updated to handle this change?
Was there a recent Mapping XSLT update in Onboard that might have impacted the selection of User Types?

All User Types must be accounted for in the BrassRing to Onboard integration, whether 1:1 or through the Mapping XSLT file in Onboard.

Extra Information

It is not required to have all of the same User Types in BrassRing and Onboard, and it is not expected as these systems are responsible for various parts of your Hiring Process. However, all users are required to be of some User Type.

User Group Should be mapped

Error Message

[Failure: A User on the Requisition has a User Group which does not exist in Onboard.]

Old Message: User Group Should be mapped

Cause

The error message displays when the mapping between BrassRing and Onboard is not accurately selecting a User Group for an incoming user in Onboard.

Resolvable By

Infinite. Open a support ticket for resolution as this requires a Mapping XSLT change in Onboard.

Resolution

Based on the Onboard Mapping XSLT, how is the User Group being selected for an incoming user during the BrassRing to Onboard integration?

Should all Users be in the same User Group in Onboard? If Yes, then there might be a Mapping XSLT error to review or resolve.
Should Users be in a User Group that matches their User Type? If Yes, then was there a new User Type added to BrassRing, and were the corresponding User Types and User Groups added to Onboard?

Extra Information

Although User Groups are not explicitly a part of BrassRing, all users in Onboard are required to be in a User Group. The Mapping XSLT in Onboard plays an integral part in the selection of the appropriate User Groups during the integration.

Failed: null

Error Message

[Failure: The Import was unsuccessful due to a problem selecting a valid Workflow in Onboard. Please contact your System Administrator.]

Old Message: Failed: null

Cause

The error message displays when no workflow has been selected for the incoming Job Requisition during the BrassRing to Onboard integration.

Resolvable By

Infinite. Open a support ticket for resolution as this requires a Mapping XSLT change in Onboard.

Resolution

Verify:

Have there been any recent workflow changes in Onboard, or specifically, has the name of any workflow changed?
If using multiple workflows, has there been a change to any field or value that impacts the workflow selection?

Both questions require a Mapping XSLT change in Onboard to resolve.

Extra Information

Under normal circumstances, the correct configuration of the Mapping XSLT means that this error does not occur. If a change has been made to the name of any of the workflows in Onboard, and the corresponding Mapping XSLT changes are not been made, this error displays.

Job.template.is.required

Error Message

[Failure: A Job Template was not selected in Onboard during the Integration. Please check the Onboard Mapping XSLT file, in Utilities->Imports, to confirm that the Job Template is Mapped correctly.]

Old Message: Job.template.is.required

Cause

The error message displays when no Job Template has been selected for the incoming Job Requisition during the BrassRing to Onboard integration.

Resolvable By

Infinite. Open a support ticket for resolution as this requires a Mapping XSLT change in Onboard.

Resolution

To resolve this issue, confirm that the Mapping XSLT in Onboard is selecting the correct Job Template during the BrassRing to Onboard integration.

Extra Information

Under normal circumstances, the correct configuration of the Mapping XSLT means that this error does not occur. If a change is made to the name of any of the Job Templates in Onboard, and the corresponding Mapping XSLT changes have not been made, this error displays.

Failed: Job with requisition no 'N' already exists

Error Message

[Failure: A Job Requisition with Number <%ReqNumber%> already exists in Onboard. Please check the Onboard Mapping XSLT file, in Utilities->Imports, to confirm the Requisition Number and External Key fields are Mapped correctly.]

Old Message: Failed: Job with requisition no 'N' already exists

Cause

The error displays if job already exists in Onboard with the same req number as is being sent during the BrassRing to Onboard integration, but with a different External Key.

Resolvable By

Client. If the problem persists after following the Resolution steps, open a support ticket for resolution.

Resolution

To Resolve this issue, a new Job Req must be created in BrassRing.

Extra Information

During the BrassRing to Onboard integration a Job Req is created in Onboard using the Req Number from BrassRing, for example: [BrassRing Req: 123BR = Onboard Req: 123 with External Key: 123BR]. When the error displays, this either means that a Job Req was created in Onboard manually, and does not have and External Key, for example blank =/= 123BR, or that there is a Mapping XSLT issue. The Mapping XSLT issue is not typical as this configuration is standard.

applicant.valid.internet.email.address.is.required

Error Message

[Failure: A Valid Candidate email Address was not found, or the format was incorrect. ]

Old Message: applicant.valid.internet.email.address.is.required

Cause

The error displays if the Applicant’s email address is either blank or in an incorrect format.

Resolvable By

Client

Resolution

To resolve this issue, confirm the applicant’s email address in BrassRing is both provided and in the appropriate format, for example [email protected].

Extra Information

The email address for an applicant is an important part of the BrassRing to Onboard integration. Its format is as important as this validation is a hard-coded part of the integration, and not a simple field validation.

job.title.is.required

Error Message

[Failure: A Job Title was not selected in Onboard during the Integration. Please confirm that a Job Title is selected on the Requisition.]

Old message: job.title.is.required

Cause

The error displays when the Job Title for a given requisition is either not provided or is not included in the Dictionary of valid Job Titles in Onboard.

Resolvable By

Client or Infinite. If the Job Title should be accounted for in the Onboard dictionary of Job Titles [D_JOB_TITLES], open a support ticket for resolution.

Resolution

To resolve this issue, confirm that the Job Title provided on the Job Requisition in BrassRing is valid.

Extra Information

The Job Title is a default field that is sent as a part of the Job Requisition information during the BrassRing to Onboard integration.
The Job Title is typically enabled with the [Create-on-the-fly] attribute in the Mapping XSLT file in Onboard. This allows new values in BrassRing to be added dynamically to the dictionary [D_JOB_TITLES] in Onboard.

Candidate already exists in Onboard with email address: [email protected]

Error Message

[Failure: A Candidate already exists in Onboard with the email Address: <%email Address%>. Please update the email Address on the BrassRing Candidate Profile to be unique.]

Old Message: Found duplicate applicant with same email address :[email protected]

Cause

The error displays when a new applicant is sent from BrassRing who shares an email address with an existing record in Onboard.

Resolvable By

Client or Infinite. If the error is received, follow the guidance in the Resolution section to troubleshoot the error. If a clear path to resolution cannot be identified, open a support ticket for resolution.

Resolution

To resolve this issue, the email address that is being sent for the applicant in BrassRing must be made unique. If the applicant being sent from BrassRing should be the same as the existing applicant in Onboard and the error is received, verify whether the applicant has multiple profiles in BrassRing. If so, stack the records as needed.

Extra Information

BrassRing allows applicants to share email addresses, Onboard requires that email addresses are unique for all applicants.
If an applicant has multiple profiles in BrassRing that share an email address, each profile has a different Candidate Reference Number. The Candidate Reference Number, CRUID in Onboard, is used as a unique identifier between the two systems, so sharing email addresses for two profiles in BrassRing causes this contention.

Validation

Error Message

[Validation.] There is no Old Message.

Cause

The error displays when a field being sent in the BrassRing to Onboard integration is failing a configured field validation in Onboard.

Resolvable By

Client or Infinite. If the error is received, follow the guidance in the Resolution section to troubleshoot the error. If the validation error is not clear, open a support ticket for resolution.

Resolution

To resolve this issue, it is important to understand what field is failing validation. To find additional information on the failure, access the Monitor Page in Onboard Configuration by selecting System Settings and selecting the Utilities tab. Select Monitor show statement. The Monitor page lists all integrations and allows the user to find the failed integration by timestamp. After selecting the failed integration, additional information for the validation failure displays.

Extra Information

Validations are in place to maintain the consistency of the client’s data, especially when exporting to HRIS systems. When editing or removing validations, keep the data in mind.

If an applicant exists in Onboard with some field value, for example Social Security Number: NNNNNNNNN, and the existing value does not match a newly added validation, SSN: NNN-NN-NNNN, even if a new value is not sent for the field in the Integration, the applicant profile in Onboard is still be validated and the error displays. Be mindful of the existing data when ADDING validations to fields.

KRB Component failed the import.

Error Message

[Failure: The Import was unsuccessful due to a problem in the configuration. Please contact your System Administrator.]

Old Message: KRB Component failed the import.

Cause

The error [KRB Component failed the import.] displays when there is a mapping configuration issue in the Onboard XSLT-Mapping file.

Resolvable By

Infinite. Open a support ticket for resolution as this requires a Mapping XSLT change in Onboard.

Resolution

To resolve this issue, the Professional Services Engineering (PSE) team need to be engaged to review the error and correct the XSLT-Mapping file in Onboard.

Extra Information

Validations are in place to maintain the consistency of the client’s data, especially when exporting to HRIS systems. When editing or removing validations, keep the data in mind.

Passed in UserName is already associated with CRUID

Error Message. [Passed in UserName is already associated with CRUID XXXXX. Please send respective associated UserName or Cruid.]

Cause

The error [Passed in UserName is already associated with CRUID XXXXX. Please send respective associated UserName or Cruid.] is caused when a user is sent to Onboard with a user name that is already associated to a different CRUID. Since both user names and CRUID must be unique, an error is thrown.

Resolvable By

Client

Resolution

Usernames must be unique. In this case, either the username for the current existing user in Onboard must be changed or the incoming user name must be updated to be unique.

Error: Failed

Error Message. [The workflow Responsibe UserType ‘Req Contributer’ does not exist in the job participants.]

Resolution

The error means that the client is not sending someone from BrassRing to Onboard with that user type, and they must because an activity in Onboard is assigned to them.

WORKDAY CANDIDATE EXPORT INTEGRATION

Abstract

Product: Workbench

Scope

This page describes issues and potential solutions for clients that want to implement a Real Time Candidate Export integration from BrassRing into Workday, by using the self-serve Mapping Tool. The integration initiates when a candidate is put into a designated HR status and sends data through a Workday hosted endPoint URL. The protocol used is HTTP POST not SOAP. For further study on the integration, the technical spec can be found in the Candidate Export Technical Specifications API document on the API Reference documents in this page.

Requirement

The Candidate Export API sends data in BrassRing proprietary XML and expects synchronized acknowledgement in a specific XML format to let end users of BrassRing know the success or failure status of transaction on the UI.

Known Issues

Workday is able to host endPoint URL, that complies with HTTP POST, and receive data in BrassRing proprietary XML. However, there are two issues:

Workday is able to send a synchronized acknowledgement back to BrassRing but it is not in the XML format that BrassRing expects and it does not reflect actual status. This leads to an issue where BrassRing shows a [failure transaction] message as it cannot interpret the Workday acknowledgement XML.
It takes some time for Workday to process a candidate and therefore it is not possible to send the actual status back to BrassRing. This creates an issue where the BrassRing end user is unaware of actual processing status of candidate in Workday.

[These issues are based on client feedback as of 26 May 2020 that have such integrations in place.]

Solution

There are various options that can be implement to mitigate the two issues.

Failed transaction message

There are two options to override the [failed transation] message and show one static message for all the transactions regardless of the candidate processing status in Workday. The actual status cannot be shown because Workday does not send it to BrassRing.

A middleware (Layer 7) can be placed between the two systems to intercept transaction and reformat the Workday response to something that BrassRing expects. The middleware can be hosted on the Infinite side. This requires a PSE project and a cost is involved.
Disable the Workbench client setting [Enable XML Integration confirmation] to override the failed status. When disabled, the user interface shows a [Candidate status has been updated] message without any [success] or [failure] status. However, caution should be exercised as this setting impacts ALL Real Time Candidate Export Integrations that are configured by using the Mapping Tool.

Candidate status in Workday

The second issue can be resolved by sending some kind of message back to let end users of BrassRing know the actual status of the candidate in Workday.

Map an email address of a BrassRing end user, for example the recruiter or manager, in the Candidate Export integration to send to Workday. Workday can use the same email to send a notification after the candidate is processed.
Configure an [HR Status Update] integration in the Mapping Tool that Workday can use to update a HR status in BrassRing based on the candidate processing status in Workday.
Configure a [Form Import] integration in the Mapping Tool that Workday can leverage to update the status or message in BrassRing.

Frequently Asked Questions

Can Workday provide SOAP endPoint URL instead of HTTP POST?

The Mapping Tool expects endPoint URL to use HTTP POST. If Workday can only do SOAP, a middleware needs to be placed on Infinite side to configure SOAP and route all the calls through it. A BrassRing PSE project is needed for this as it is configured in middleware (Layer 7).

Can integration use Basic Authentication?

Yes, Basic Authentication can be implemented, however it needs to be for HTTP POST not of SOAP WS. For SOAP WS, a BrassRing PSE project is needed as it is configured in middleware (Layer 7).

Can integration use 2-way SSL authentication?

Yes. However, a BrassRing PSE project is needed as it is configured in middleware (Layer 7)

COMMON SERVICE INTEGRATIONS

Abstract

Product: Workbench

Common Service Integrations

Common services inticates that two partners, for example BrassRing and a vendor, are using a common schema to interact. This common platform allows for a more streamlined integration, which can be offered in a more cost effective and quick manor. While custom integrations require BrassRing engineers to write new scripts, common services already have a script written eliminating the need for engineer involvement during configuration. Types of common service integration include:

Background Checks
Drug Screens
Video Interviewing.

Contact your Infinite representative for an up-to-date list of vendors.

1 Step vs 2 Step

1 Step Overview

System users can trigger a preselected background check, drug screen, or video interview by updating a candidate’s HR Status.
All necessary information is sent to the vendor and a real-time response is received by the user verifying success or failure.
- If successful, no further action is required. The vendor processes the request and sends back results when available.
- If unsuccessful, the user needs to undo the HR Status on the candidate and update the necessary form or field with the missing or invalid information (or might not be a valid user with the vendor). Then, the candidate can be updated to the HR Status again.
RAMs can also be used to initiate 1-Step integrations by updating the candidate to the applicable HR Status.
This integration type saves time when all of the details for the integration have already been collected within BrassRing.
1 Step Workflow:
1. Item to be ordered is selected on the Req or Candidate Form.
2. HR Status is Updated.
  1. If the required data is not available, or some error occurs, the flow returns to the HR status update.
  2. If the required data is available, the data is sent to the vendor.
3. The vendor sends results into a BrassRing candidate form.

2-Step Overview

Upon updating the HR status for a candidate, the vendor user interface (UI) is shown and the system user completes any additional information such as package or account before submitting the request.
RAMs cannot be used to initiated 2-Step integrations.
This integration type is useful when necessary details are not known in advance or are not collected within BrassRing.
2-Step Workflow
- The HR Status is updated.
- In the vendor user interface, select the package and complete the remaining fields to submit the request.
- The Vendor sends the results to a Brassring candidate form.

Prerequisites for Common Services Integrations

Obtain the prerequiste details from the vendor:

A list of code and description packages.
Account credentials, including the account, username, and password.
Any additional values required by the vendor, for example cost center, or business unit. It is recommended to review the vendor-specific mapping document for any requirements and discuss these requirements with the vendor. Mapping documents can be requested from your Infinite representative.

Before beginning the integration configuration:

Configure a BrassRing HR status or statuses that triggers the integration. This HR status cannot trigger any other integrations. For example, the same HR status cannot be used to trigger a drug screen and a background check, or trigger a pre-hire export and a background check.
Configure any additional optional, or vendor required fields that are not already captured in BrassRing on the requisition or a candidate form. For more information, see the vendor-specific mapping document.

Configuration Steps, Power Users only

Infinite recommends that all configurations are completed and tested in staging before to moving to production.

Enable the Client Settings

Client Settings can only be enabled by Infinite Representatives.

Enable the Common Service Integration Type Client Setting.
Enable the Power user edit access: Integrations - Administration Client Setting.
If a RAM triggers a 1-Step integration, enable the RAM - Allow HR status update to trigger candidate export integrations Client Setting.

Data Field Configuration

Two custom req fields are created and added to the custom req field index.

Select Tools → Forms → Reqs → Reforms.
Select Define custom req fields.
If the ordering item, background check package, drug screen package, or video interview, is selected by the recruiter on the requisition update the Background Check Package field. Clients are not required to use this custom field and, if needed, an existing or new custom req field can be used. Alternatively, if the ordering item is selected later in the recruitment process, a candidate form field can be used. Use a single-select field type for the candidate form field.
1. To update the Background Check Packages field, select the administer field options icon for the Background Check Packages field.
2. Add the values provided by the vendor.
  Add the field to the appropriate req templates and set any field level privileges, such as hidden, or required. This field can be populated by job code default data or set by using a req field association.

A candidate form is also created.

Select Tools → Forms → Candidate Forms.
Set the form privileges for each user type as needed, by selecting the Edit from attributes icon. Fields must not be added to the form. However, field attributes can be edited to hide certain fields from user types if needed, or hide fields by language if they are not sent back by the vendor. It is recommended to test the integration on a few test candidates and determine which fields must be hidden from users or all together.

If your organization is already using a common services integration, for example, background check, and a new vendor is being set-up, for example, video interviewing, a separate candidate form can be used for the results.

To create a new form, select Tools → Forms → Candidate Forms.
Select Add new form.
Insert a Database title and Title.
Select Multiple per candidate/req combination for [Form multiples].
Select Save.
Select the Edit form attributes icon for the form.
Select Yes to [Include Common Service vendor results]. This automatically creates all of the appropriate fields on the form to be used by the integration.
Set any form and field attributes as needed, and select Save.

What's Next

Integrations Part- 2

Table of contents