Understanding Custom Components

Custom components enable developers and partners to incorporate content and functionality from an external application into a Bullhorn entity page (e.g., the candidate overview). There are two types of custom components within Bullhorn:

• Display components can appear on overview pages or custom tabs. While they can be interactive, they do not directly modify Bullhorn data.

• Edit components are used on edit forms in Bullhorn and can modify the data that is saved when the user submits the form to Bullhorn.
   

From an implementation point of view, a custom component is a self-contained IFRAME hosted by the Bullhorn browser application. The IFRAME can request any URL that has been configured in Bullhorn. When the IFRAME is created, the Bullhorn application automatically appends the context data necessary for the remote server to identify the calling user and responds with the appropriate data or content for that Bullhorn record.

All requests to the remote system are made from the user’s client computer, so the remote application can reside on any system to which the user can gain access. The custom component can be as simple as some customized content relevant to the current record, or it can involve multiple user interactions and component refreshes.

To illustrate how a custom component might be used in practice, the following example walks through how a fictitious company called Quick Assessments could create a custom display component that integrates Bullhorn with its service.

Example

Quick Assessments provides online assessments for common skill areas. Recruiters with an account can create a new assessment by providing the candidate’s key contact information and selecting the required assessment from a list of pre-configured options.

To simplify the process of registering candidates for assessments, Quick Assessments has created a custom component and tab that live on the Candidate record in Bullhorn. The component provides a button that enables users to register a candidate for an assessment directly from the candidate record.

It also presents a list of existing assessments for candidates that have already taken tests through the Quick Assessments application.

The following illustrates how this custom component interacts with the Bullhorn web application and the Bullhorn API to enable the integration.

As this example illustrates, custom components offer a flexible mechanism for integrating external applications into the Bullhorn application user interface.

Creating a Custom Display Component

Custom display components are dedicated portions of a screen in Bullhorn that are programmed to show non-Bullhorn content that is served from a remote application or service. Building a custom display component is as simple as creating a web application that can process requests from the IFRAME component and render an HTML user interface that fits into the space allotted by the Bullhorn UI.

When a custom component is initialized within the Bullhorn application, it issues a GET request for the URL that has been configured in the Default Value property of the Custom Component field. These values must be configured by the Bullhorn administrator using the Field Mappings tool. In addition to a URL that should be called, the default value property can also include any variables needed to authorize this account with the external application (e.g., username, password, account number, etc.). Each customer or private label can have a unique URL/variable combination, but all requests made from that private label contain the values configured in the Default Value property.

If additional personalization or authorization is required, you can use the dynamically appended variables listed below or use a login screen and cookies to manage authentication. When the request is made, the following dynamic variables are appended to the component’s URL on a per request basis.

The page that processes the request made by the custom component should use these values to authorize the request and determine what content should be returned to the user when the component is loaded.

The method for accessing these variables varies depending on your programming environment. For example, in PHP, they become accessible in the $_REQUEST variable; in ASP.NET, they become accessible in the Page.Request object.

Placing Custom Display Components in the Bullhorn User Interface

Custom components can be placed either on the overview (main) page for a record or on a custom tab. Components that reside on the overview page have a limited amount of space, but they have the advantage of being immediately visible to the user when the record is opened. Components that are placed on a dedicated tab can present more data, but users must click the tab to access the component.

Developers creating custom components should decide which placement makes sense for their component based on the data it must present and how the user will interact with it. Bullhorn partners creating components for multiple customers should also provide instructions that specify where administrators can or should place their component for it to render properly.

Configuring a Custom Display Component

Configuring a custom display component for use in the Bullhorn application involves the View Layout and the Field Mappings tools. Each of the supported records in Bullhorn includes three fields that can be used for custom components: CustomComponent1, CustomComponent2, and CustomComponent3. To configure the URL for a custom component:

1. On the Tools menu, select Field Mappings.

2. Select the entity to which you would like to add the component.

3. Click the name of one of the available custom component fields (CustomComponent1-3).

4. In the Default Value field, add the URL that should be requested for this component.

5. Click Save.

Once your customer display component has been configured in the Field Mappings tool, it is ready to be placed on either the overview tab of that record type (the default view) or on a custom tab on that record type.

Placing Custom Display Components on the Overview Tab

There are five potential locations for a custom component on the overview tab. The following table and figure illustrate the available placements and the corresponding sizes for custom components. The size values will be included as URL variables (see above).

To configure the placement of the custom component on the overview tab of the entity page:

1. On the Tools menu, select View Layout.

2. Select the entity where the custom component should appear.

3. Select the Overview Tab section.

4. Locate the section where you would like to include the component

5. Select the component from the list of fields in the Exclude from View list.

6. Click the right arrow to move this field to the Include in View list.

7. Click Save.

Placing a Custom Display Component on a Custom Tab

The amount of space available to a custom component that is hosted on a dedicated tab will vary depending on the user’s screen resolution and UI configuration, and the pages should be designed to easily adapt to multiple widths.

To ensure that no vertical scroll bars appear, the custom tab feature provides a way for your application to communicate its height to the hosting page. This communication is done via the URL configured for the custom component that is placed on the tab. To take advantage of this feature, you should add a URL variable called displayHeight to the URL when it is configured in the Field Mappings tool (e.g., .../test.html?displayHeight=3000px). If no value is provided, the default height of the IFRAME will be 4000px.

You can also dynamically modify the height of the IFRAME by changing the displayHeight variable after Bullhorn has initialized the IFRAME. This is useful if your custom tab page dynamically shows or hides regions of the DOM, or if users will navigate through multiple pages of different heights. The following JavaScript functions can be added to any page that appears in a custom tab:

function addResizeParameterToUrl()

{

var size = document.body.scrollHeight;

var currentHref = decodeURIComponent(getQueryStringParameter(location.href,

"currentBullhornUrl").replace(/\+/g, " "));

var fragment="displayHeight=" + size;

currentHref+="#" + fragment;

parent.location.href=currentHref;

}

The hosting Bullhorn page will listen for changes to the displayHeight URL variable and adjust the dimensions of the IFRAME accordingly. To ensure this variable is updated, you must also attach the addResizeParameterToURL() function as a listener to the page's onresize and onload events. This can be done by adding the following to the page's body tag.

<body onresize="addResizeParameterToUrl();" onload="addResizeParameterToUrl();">

Depending on the amount of DOM scripting in your pages, you may also need to call this function from other places in your application as well.

To configure the custom component to appear on its own tab:

1. On the Tools menu, select View Layout.

2. Select the entity where you would like this custom tab to appear.

3. Select the Custom Tabs section.

4. Enter the name you would like for the custom tab.

5. Select the component from the list of fields in the Exclude from View list.

6. Press the right arrow to move this field to the Include in View list. Note: only one custom component can be configured per tab.

7. Click Save.

The custom component should now appear either on the overview tab of the entity or on the custom tab bearing the name that was configured within Bullhorn.

Creating a Custom Edit Component

Custom edit components allow you to override the built-in edit controls in Bullhorn and replace them with controls that present data not managed by the Bullhorn application. When the user saves the form, Bullhorn takes the value set by the custom edit component and inserts it into the appropriate field in the Bullhorn record.

Like custom display components, custom edit components are displayed within an IFRAME. The URL requested by the control includes all of the parameters listed above for custom display components. In addition, the current value for the edit control’s field will also be included in the URL, as follows:

Once they have been loaded, custom edit components communicate with the Bullhorn application form by changing the parent href property (the href of the form that launched the custom external control).

The following example illustrates the HTML and JavaScript for a drop-down control that is configured for the experience property.

<html>

<head><title></title></head>

<body onload="initialize()">

<script type="text/javascript">

function initialize(){

// Get the name of the control and its current value from the href property

var controlName=getQueryStringParameter(location.href, "baseControlName");

var initialValue=getQueryStringParameter(location.href, "value");

//Set the experience drop-down to the current value

var dropdown = document.getElementById("experience");

for(i=0;i<dropdown.options.length;i++){

if(dropdown.options[i].value==initialValue){

dropdown.options[i].selected =true;

return;

}

}

}

function setValue(value) {

//Get control Name (passed in url src)

var controlName=getQueryStringParameter(location.href, "baseControlName");

//Get current url from currentBullhornUrl param

var currentHref=decodeURIComponent(getQueryStringParameter(location.href, "currentBullhornUrl").replace(/\+/g,  " "));

//Build controlName and value in the format controlName=value

var fragment=controlName + "=" + value;

currentHref+="#" + fragment;

parent.location.href=currentHref;

}

//Generic function to extract values from the referring URL

function getQueryStringParameter(href, paramName){

var regexS = "[\\?&]"+ paramName +"=([^&#]*)";

var regex = new RegExp( regexS );

var results = regex.exec( href);

if( results == null ){

return "";

} else {

return results[1];

}

}

</script>

<select id="experience" onchange="setValue(experience.options[selectedIndex].value)">

<option selected>Please select one...</option>

<option value="beginner">Beginner</option>

<option value="intermediate">Intermediate</option>

<option value="advanced">Advanced</option>

<option value="expert">Expert</option>

</select>

</body>

</html>

Configuring a Custom Edit Component

Configuring a custom edit component for use in the Bullhorn application involves the Field Mappings tool. To configure one of the Bullhorn fields to use a custom edit component:

1. On the Tools menu, select Field Mappings.

2. Select the entity to which you would like to add the edit component.

3. Click the name of the field whose edit control you want to replace (e.g., experience). Note: You cannot use any of the customComponent1-3 fields, as these do not represent record values that are stored in Bullhorn. You must use a standard Bullhorn field, such as experience or customText1.

4. Select Custom External Control from the Edit Type drop-down.

5. In the Default Value field, add the URL that should be requested for this component.

6. Click Save.

Configuring the Client Browser for Custom Edit Components

To function properly, the website where the control(s) are hosted must be added to Internet Explorer 7 and 8 Trusted Sites and the Navigate sub-frames across different domains custom setting must be enabled for the trusted sites.