Creating and Configuring a BambooHR System of Record

BambooHR is a comprehensive human resources information system (HRIS) that provides essential employee data and organizational context for access control decisions. By integrating BambooHR with SGNL, you can establish relationships between employees, supervisors, departments, and roles that enable sophisticated policy-based access control throughout your organization.

The BambooHR integration brings critical HR data into the SGNL graph, allowing you to create policies based on employee attributes such as department, job title, employment status, supervisor relationships, and custom fields defined in your BambooHR instance. This integration is particularly valuable for organizations that need to make access decisions based on organizational hierarchy, employment status, or HR-specific attributes.

Prerequisites

  • A BambooHR account with administrative privileges
  • Access to generate API keys in BambooHR
  • Knowledge of your BambooHR company subdomain
  • Understanding of which employee data fields you want to synchronize to SGNL

Permissions Required

To successfully configure the BambooHR integration, you need the following permissions and access:

  • BambooHR Administrator Access: Ability to access the BambooHR Admin Console to generate API keys and configure system settings
  • API Key Generation: Permission to create and manage API keys for system integrations
  • Employee Data Access: Read access to employee records and the specific fields you want to include in SGNL policies
  • Custom Field Access: If using custom fields, ensure the API key has access to read these custom attributes

Configuring BambooHR

Generating an API Key

BambooHR uses API key authentication for system integrations. Follow these steps to create the necessary credentials:

  1. Access the BambooHR Admin Console: Log into your BambooHR account with administrator privileges
  2. Navigate to API Settings: Go to Settings → API Keys or Settings → Integrations → API Keys (the exact path may vary based on your BambooHR version)
  3. Generate New API Key: Click “Add New Key” or “Generate API Key”
  4. Name the Integration: Provide a descriptive name such as “SGNL Integration” to identify this key’s purpose
  5. Copy the API Key: Immediately copy and securely store the generated API key, as it may not be displayed again
  6. Note Access Permissions: Ensure the API key has read access to employee data and any custom fields you plan to use

Identifying Your Company Domain

Your BambooHR company domain is the subdomain used to access your account. For example, if you access BambooHR at https://acmecorp.bamboohr.com, then your company domain is “acmecorp”. You will need this value when configuring the SGNL integration.

Understanding Employee Data Structure

Before configuring SGNL, review your BambooHR employee data structure to understand which fields are available and relevant for your access policies. BambooHR provides both standard fields (like employee ID, email, department) and custom fields that your organization may have defined. The BambooHR Field Names documentation provides a comprehensive list of available standard fields.

Configuring SGNL

Setting Up the BambooHR System of Record

  1. Access SGNL Console: Login to the SGNL Console with appropriate administrative privileges
  2. Navigate to Identity Data Fabric: From the left menu, select “Identity Data Fabric”
  3. Add New System of Record: Click “Add System of Record” or “Add” to open the SoR catalog
  4. Select BambooHR Template: Locate and click on “BambooHR” in the SGNL SoR Catalog to open the configuration screen with pre-populated settings from the BambooHR template

Authentication Configuration

BambooHR uses HTTP Basic Authentication with your API key. Configure the authentication settings as follows:

  1. Select Authentication Method: Choose “Basic” as the authentication method
  2. Configure Username: Enter your BambooHR API key in the username field
  3. Configure Password: Enter “xxx” or any random string in the password field (BambooHR ignores the password when using API key authentication)

The authentication configuration follows BambooHR’s standard approach where the API key serves as the username and the password field can contain any value since it is not validated.

System Configuration

Complete the following required configuration fields:

BambooHR API Address: The address field should be set to “api.bamboohr.com/api/gateway.php” (this is pre-configured in the template)

Company Domain: Replace the {{Input Required}} placeholder in the adapter configuration with your actual BambooHR company subdomain. This is the subdomain portion of your BambooHR URL.

Advanced Adapter Configuration

The BambooHR integration includes several optional configuration parameters that can be customized based on your needs:

Employee Filtering: The onlyCurrent parameter determines whether to synchronize all employees or only current employees. Set this to true if you only want active employees in your SGNL policies, or false to include all employee records including terminated employees.

Date Format Configuration: BambooHR allows different date input formats. The attributeMappings.date parameter should match your BambooHR date format setting. Check your BambooHR Admin Console under Settings → Account → General Settings → Date Input Format to determine the correct format.

Boolean Field Mapping: If your BambooHR instance uses custom boolean fields with non-standard values, you can configure the attributeMappings.bool section to specify how these values should be interpreted. The default configuration handles standard true/false representations.

Entity and Attribute Configuration

The BambooHR template defines an Employee entity with several key attributes that provide comprehensive employee information:

Core Identity Attributes: The id field serves as the unique identifier for each employee, while bestEmail provides the primary email address for the employee. These attributes are essential for establishing identity relationships with other systems.

Personal Information: Attributes like fullName, dateOfBirth, and employeeNumber provide basic employee information that can be used in access policies.

Organizational Relationships: The supervisorEId and supervisorEmail attributes establish supervisor relationships, enabling policies based on organizational hierarchy.

Custom Field Support: The template includes examples of custom fields (like checkboxField1) that demonstrate how to integrate custom BambooHR fields into your SGNL policies.

Audit and Tracking: The lastChanged attribute provides timestamp information for tracking when employee records were last modified.

Relationship Configuration

The BambooHR template establishes a critical “Manager” relationship that connects employees to their supervisors:

Manager Relationship: This relationship uses the employee’s id field and relates it to another employee’s supervisorEId field, creating the organizational hierarchy within SGNL. This relationship enables policies that consider reporting structures, such as allowing managers to access resources for their direct reports.

You can extend these relationships by connecting BambooHR data to other systems in your SGNL configuration. For example, if employee numbers in BambooHR match user identifiers in your identity provider, you can create relationships that bridge HR data with authentication systems.

Testing and Verification

After configuring the BambooHR integration, follow these steps to verify that the connection is working correctly:

Initial Connection Test

  1. Save Configuration: Click “Continue” to save your BambooHR System of Record configuration
  2. Verify Connection: SGNL will attempt to connect to BambooHR using your provided credentials and configuration
  3. Check for Errors: Review any error messages that appear during the initial connection attempt

Enable Synchronization

  1. Review Entities: Examine the Employee entity configuration to ensure it includes the attributes you need for your policies
  2. Enable Entity Sync: Hover over the Employee entity and click “Enable Sync” to start data synchronization
  3. Enable System Sync: After enabling entity synchronization, enable synchronization for the entire BambooHR System of Record

Verify Data Ingestion

  1. Monitor Sync Progress: Watch the synchronization progress indicators to ensure data is being imported successfully
  2. Check Record Counts: Verify that the number of imported employee records matches your expectations based on your BambooHR employee count
  3. Review Sample Data: Use SGNL’s interface to spot-check a few employee records to ensure the data is being imported correctly

Test with DataLens

Once synchronization is complete, use DataLens to explore the imported BambooHR data:

  1. Access DataLens: Navigate to the DataLens feature in your SGNL console
  2. Query Employee Data: Create sample queries to verify that employee attributes are available and accurate
  3. Test Relationships: Verify that the manager relationships are correctly established by querying supervisor connections
  4. Validate Custom Fields: If you’re using custom fields, confirm that they are properly imported and accessible for policy creation

Troubleshooting

Authentication Issues

API Key Not Working: If you receive authentication errors, verify that your API key is correct and has not expired. BambooHR API keys do not typically expire, but they can be deactivated. Try generating a new API key if authentication continues to fail.

Permission Errors: Ensure that the API key has sufficient permissions to read employee data. Some BambooHR configurations restrict API access to specific data fields or employee groups.

Connection Problems

Domain Configuration Errors: Double-check that your company domain is correctly specified without the “https://” prefix or “.bamboohr.com” suffix. Only the subdomain portion should be included.

Network Connectivity: Verify that your SGNL instance can reach “api.bamboohr.com” and that no firewall rules are blocking the connection.

Data Synchronization Issues

Missing Employee Records: If some employees are not appearing in SGNL, check the onlyCurrent configuration parameter. If set to true, only active employees will be synchronized.

Incorrect Date Values: If date fields are not parsing correctly, verify that the attributeMappings.date parameter matches your BambooHR date format configuration.

Custom Field Problems: Custom fields in BambooHR must be prefixed with “custom” in the external ID configuration. Verify that custom field names in the template match exactly with your BambooHR custom field definitions.

Boolean Field Conversion: If boolean custom fields are not converting properly, review the attributeMappings.bool configuration to ensure it accounts for the specific string values used in your BambooHR instance.

Performance Considerations

Slow Synchronization: Large employee datasets may take time to synchronize initially. The template is configured with reasonable default intervals, but you can adjust the syncFrequency and apiCallFrequency parameters if needed.

API Rate Limiting: BambooHR may have API rate limits that could affect synchronization speed. The default configuration respects these limits, but contact BambooHR support if you experience persistent rate limiting issues.

Integration with SGNL Policies

Once your BambooHR integration is successfully configured and synchronized, you can leverage the employee data in your SGNL policies:

Organizational Hierarchy Policies: Use the manager relationships to create policies that grant supervisors access to resources related to their direct reports.

Department-Based Access: Leverage department and job title information to create role-based access policies aligned with your organizational structure.

Employment Status Policies: Use employment status and start date information to automatically manage access for new hires and departing employees.

Custom Field Policies: Incorporate any custom HR fields into your access decisions, such as security clearance levels, project assignments, or office locations.

For comprehensive guidance on creating policies with HR data, refer to the SGNL Policy Management documentation. For understanding how employee entities relate to other systems in your environment, review the Entities and Relationships guide.