Adding External Data to the Data Hub

After working with your Bullhorn Account Manager to confirm your external connection to Data Hub, follow the steps below to complete your integration.

Steps

These steps are for clients who are building their own integration to Data Hub instead of contracting Bullhorn Professional Services to connect to Data Hub.

  1. Meet with your assigned Bullhorn Services team member for a consulting session to determine scope of work and expected outcomes.
  2. Make sure you can answer the following questions before starting your integration to Data Hub:
    1. What is the source system (or systems) from which you want to send data?
      1. How will this data be exported or received from the source system?
      2. How many entities will you likely be defining and sending?
    2. What volume are you expecting for each source system and will you send data in batches or as single transactions to the API?
    3. What key metrics are you looking for insights on?
      1. What Bullhorn entities will this data be augmenting? (What links or references will be present?)
    4. What type of data is it?
      1. Singular value (e.g.: Reference Score)
      2. Activity (time-based) - multiple (e.g.: activity of surveys sent out)
      3. Nested (hierarchical)
    5. What kind of application will be built or used to send data to Data Hub?
      1. Technology
  3. Familiarize yourself with the Bullhorn API by navigating to Using Data Hub.
  4. Review Custom Attributes on Data Hub Schema Definitions for help creating your data schema.
  5. Define a data schema(s) for the entity types of the source system that will support your reporting needs.
    1. Validate the schema setup/definition using a JSON validator.
      1. This does not mean that the schema will work for the Data Hub, but it should be valid JSON at a minimum. If you followed the other parts of the best practices guide, then you should be set to send data.
  6. Request a new API key for use specifically with Data Hub by submitting a ticket with Bullhorn Support.
    1. The new API key allows for rate limiting separately from other API calls that you may make with other integrations with Bullhorn.
  7. Submit a support ticket (or work with your Bullhorn Services team) with your source system, entities, and schema definition. You will need to provide all of the following information:
    1. Source System (Name and Display Name)
      1. Source System Name: <ClientName><SourceSystemData> (e.g.: AcmeRecruitingStaffsuite)
        • Be descriptive but simple. It should contain the name of the integration data point.
      2. Source System Display Name: (eg: StaffSuite Placement Data)
      3. This display name can be used for visualization in Analytics or other reporting tools.
    2. Number of Entities and Types of Entities (e.g.: Survey, SurveyResponse)
      1. Entity Name
        • Unless specified, the entities will be tied to one Source System described above. If you need to add additional entities to a SourceSystem that was created/setup before, please specify that SourceSystem Name.
      2. Entity Display Name
    3. Entity Schema Definition (one schema per entity)*
      1. Entity Schema Name
      2. Entity Schema Description
      3. Schema
        • Example: Recruitment Funnel Analysis
        • Copy
          {
            "jobID": {
              "type": "integer",
              "link": {
                "type": "ATS",
                "entity": "JobOrder"
              },
              "label": "Job ID"
            },
            "candidateID": {
              "type": "integer",
              "link": {
                "type": "ATS",
                "entity": "Candidate"
              },
              "label": "Candidate ID"
            },
            "stage": {
              "type": "string",
              "label": "Recruitment Stage"
            },
            "enteredStageAt": {
              "type": "string",
              "format": "date-time",
              "label": "Entered Stage At"
            },
            "source": {
              "type": "string",
              "label": "Candidate Source"
            }
          }
  8. You can now use your API Key and schema to send data to Data Hub. You can validate your data in the following ways:
    1. Data Hub API supports a FIND method which allows you to do a POST request and specify the sourceId’s that you have sent (you can find up to 100 records at a time).
    2. API Endpoint: /data-hub/data/find
    3. If using Analytics, you can confirm the new entities have synced from Data Hub by navigating to Analytics and clicking Admin, then Metric Editor. Data Hub entities appear on this page alongside your existing Bullhorn entities.
  9. Visualize your data in Bullhorn Analytics or Data Replication.
    1. Data Hub Reporting in Bullhorn Analytics
      1. Note: It can take up to 2 hours for new Data Hub entities to appear in Bullhorn Analytics.
    2. Data Hub Reporting in Data Replication
      1. Note: Historical data will not automatically flow to Data Replication if replication is turned on after sending data into Data Hub.

*For entity definitions, Data Hub allows versions which you need to specify in each API call when sending data. Unless you have a specific version naming convention that you want to use, we assume the initial version isnamed as “1” (the version name can be a string). If you need to update the entity definition in the future, a new version needs to be created. But for the purposes of any analytics or reporting that is dependent on the data being sent, you should only make additive field changes to any subsequent version.