brynq-sdk-bob 2.6.2.dev4__py3-none-any.whl

brynq_sdk_bob/__init__.py

@@ -0,0 +1,77 @@
+import base64
+import re
+from typing import Union, List, Optional, Literal
+import pandas as pd
+import requests
+import os
+from brynq_sdk_brynq import BrynQ
+from brynq_sdk_functions import Functions
+from .bank import Bank
+from .company import Company
+from .documents import CustomDocuments
+from .employment import Employment
+from .named_lists import NamedLists
+from .payments import Payments
+from .people import People
+from .salaries import Salaries
+from .timeoff import TimeOff
+from .work import Work
+from .custom_tables import CustomTables
+
+class Bob(BrynQ):
+    def __init__(self, system_type: Optional[Literal['source', 'target']] = None, test_environment: bool = True, debug: bool = False, target_system: str = None):
+        super().__init__()
+        self.timeout = 3600
+        self.headers = self._get_request_headers(system_type)
+        if test_environment:
+            self.base_url = "https://api.sandbox.hibob.com/v1/"
+        else:
+            self.base_url = "https://api.hibob.com/v1/"
+        self.session = requests.Session()
+        self.session.headers.update(self.headers)
+        self.people = People(self)
+        self.salaries = Salaries(self)
+        self.work = Work(self)
+        self.bank = Bank(self)
+        self.employment = Employment(self)
+        self.payments = Payments(self)
+        self.time_off = TimeOff(self)
+        self.documents = CustomDocuments(self)
+        self.companies = Company(self)
+        self.named_lists = NamedLists(self)
+        self.custom_tables = CustomTables(self)
+        self.data_interface_id = os.getenv("DATA_INTERFACE_ID")
+        self.debug = debug
+
+    def _get_request_headers(self, system_type):
+        credentials = self.interfaces.credentials.get(system='bob', system_type=system_type)
+        if type(credentials) is list:
+            credentials = credentials[0]
+
+        print(credentials)
+        auth_token = base64.b64encode(f"{credentials.get('data').get('User ID')}:{credentials.get('data').get('API Token')}".encode()).decode('utf-8')
+        headers = {
+            "accept": "application/json",
+            "Authorization": f"Basic {auth_token}",
+            "Partner-Token": "001Vg00000A6FY6IAN"
+        }
+
+        return headers
+
+    def get_paginated_result(self, request: requests.Request) -> List:
+        has_next_page = True
+        result_data = []
+        while has_next_page:
+            prepped = request.prepare()
+            prepped.headers.update(self.session.headers)
+            resp = self.session.send(prepped, timeout=self.timeout)
+            resp.raise_for_status()
+            response_data = resp.json()
+            result_data += response_data['results']
+            next_cursor = response_data.get('response_metadata').get('next_cursor')
+            # If there is no next page, set has_next_page to False, we could use the falsy value of None but this is more readable
+            has_next_page = next_cursor is not None
+            if has_next_page:
+                request.params.update({"cursor": next_cursor})
+
+        return result_data

brynq_sdk_bob/bank.py

@@ -0,0 +1,31 @@
+import pandas as pd
+from brynq_sdk_functions import Functions
+from .schemas.bank import BankSchema
+
+import time
+from tqdm import tqdm
+
+class Bank:
+    def __init__(self, bob):
+        self.bob = bob
+        self.schema = BankSchema
+
+    def get(self, person_ids: pd.Series, field_selection: list[str] = []) -> (pd.DataFrame, pd.DataFrame):
+        data = []
+        for person_id in tqdm(person_ids, desc="Fetching bank accounts"):
+            resp = self.bob.session.get(url=f"{self.bob.base_url}people/{person_id}/bank-accounts", timeout=self.bob.timeout)
+            resp.raise_for_status()
+            temp_data = resp.json()['values']
+            # when an employee has one or more bank accounts, the response is a list of dictionaries.
+            for account in temp_data:
+                account['employee_id'] = person_id
+            data += temp_data
+
+            # rate limit is 50 per minute
+            time.sleep(1.3)
+
+        df = pd.DataFrame(data)
+
+        valid_banks, invalid_banks = Functions.validate_data(df=df, schema=BankSchema, debug=True)
+
+        return valid_banks, invalid_banks

brynq_sdk_bob/company.py

@@ -0,0 +1,23 @@
+import pandas as pd
+
+
+class Company:
+    def __init__(self, bob):
+        self.bob = bob
+
+    def get_variable_values(self, list_name: str = None) -> dict:
+        values = {}
+
+        if list_name is not None:
+            resp = self.bob.session.get(url=f"{self.bob.base_url}company/named-lists/{list_name}", timeout=self.bob.timeout)
+            resp.raise_for_status()
+            data = resp.json()
+            values.update({data["name"]: [value['id'] for value in data['values']]})
+        else:
+            resp = self.bob.session.get(url=f"{self.bob.base_url}company/named-lists", timeout=self.bob.timeout)
+            resp.raise_for_status()
+            data = resp.json()
+            for list_key, list_data in data.items():
+                values.update({list_key: [value['id'] for value in list_data['values']]})
+
+        return values

brynq_sdk_bob/custom_tables.py

@@ -0,0 +1,75 @@
+import pandas as pd
+from brynq_sdk_functions import Functions
+from .schemas.custom_tables import CustomTableSchema, CustomTableMetadataSchema
+
+
+class CustomTables:
+    def __init__(self, bob):
+        self.bob = bob
+        self.schema = CustomTableSchema
+
+    def get(self, employee_id: str, custom_table_id: str) -> tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Get custom table data for an employee
+
+        Args:
+            employee_id: The employee ID
+            custom_table_id: The custom table ID
+
+        Returns:
+            A tuple of (valid_data, invalid_data) as pandas DataFrames
+        """
+        resp = self.bob.session.get(url=f"{self.bob.base_url}people/custom-tables/{employee_id}/{custom_table_id}")
+        resp.raise_for_status()
+        data = resp.json()
+
+        # Normalize the nested JSON response
+        df = pd.json_normalize(
+            data,
+            record_path=['values']
+        )
+
+        df['employee_id'] = employee_id
+        valid_data, invalid_data = Functions.validate_data(df=df, schema=self.schema, debug=True)
+
+        return valid_data, invalid_data
+
+    def get_metadata(self) -> tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Get metadata for all custom tables
+
+        Returns:
+            A tuple of (valid_data, invalid_data) as pandas DataFrames containing table and column metadata
+        """
+        url = f"{self.bob.base_url}people/custom-tables/metadata"
+        resp = self.bob.session.get(url=url)
+        resp.raise_for_status()
+        data = resp.json()
+
+        # Flatten the nested structure - create one row per column with table info repeated
+        rows = []
+        for table in data.get('tables', []):
+            table_info = {
+                'table_id': table.get('id'),
+                'table_name': table.get('name'),
+                'table_category': table.get('category'),
+                'table_description': table.get('description')
+            }
+
+            for column in table.get('columns', []):
+                row = {
+                    **table_info,
+                    'column_id': column.get('id'),
+                    'column_name': column.get('name'),
+                    'column_description': column.get('description'),
+                    'column_mandatory': column.get('mandatory'),
+                    'column_type': column.get('type')
+                }
+                rows.append(row)
+
+        df = pd.DataFrame(rows)
+
+        # Validate against the metadata schema
+        valid_data, invalid_data = Functions.validate_data(df=df, schema=CustomTableMetadataSchema, debug=True)
+
+        return valid_data, invalid_data

brynq_sdk_bob/documents.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+from io import BytesIO
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+
+class CustomDocuments:
+    def __init__(self, bob):
+        self.bob = bob
+        # self.headers_upload = self.bob.headers.copy()
+        # self.headers_upload['Content-Type'] = 'multipart/form-data'
+        # self.headers_upload['Accept'] = 'application/json'
+
+    def get(self, person_id: datetime) -> pd.DataFrame:
+        resp = self.bob.session.get(url=f"{self.bob.base_url}docs/people/{person_id}", timeout=self.bob.timeout)
+        resp.raise_for_status()
+        data = resp.json()['documents']
+        df = pd.DataFrame(data)
+        # data = self.bob.get_paginated_result(request)
+        # df = pd.json_normalize(
+        #     data,
+        #     record_path='changes',
+        #     meta=['employeeId']
+        # )
+        df = self.bob.rename_camel_columns_to_snake_case(df)
+        # valid_documents, invalid_documents = Functions.validate_data(df=df, schema=DocumentsSchema, debug=True)
+
+        return df
+
+    def get_folders(self) -> dict:
+        resp = self.bob.session.get(url=f"{self.bob.base_url}docs/folders/metadata", timeout=self.bob.timeout)
+        resp.raise_for_status()
+        data = resp.json()
+
+        return data
+
+    def create(self,
+               person_id: datetime,
+               folder_id: str,
+               file_name: str,
+               file_object: BytesIO):
+        files = {"file": (file_name, file_object, "application/pdf")}
+        resp = self.bob.session.post(url=f"{self.bob.base_url}docs/people/{person_id}/folders/{folder_id}/upload",
+                                     files=files,
+                                     timeout=self.bob.timeout)
+        resp.raise_for_status()

brynq_sdk_bob/employment.py

@@ -0,0 +1,25 @@
+import pandas as pd
+import requests
+
+from brynq_sdk_functions import Functions
+
+from .schemas.employment import EmploymentSchema
+
+
+class Employment:
+    def __init__(self, bob):
+        self.bob = bob
+        self.schema = EmploymentSchema
+
+    def get(self) -> (pd.DataFrame, pd.DataFrame):
+        request = requests.Request(method='GET',
+                                   url=f"{self.bob.base_url}bulk/people/employment")
+        data = self.bob.get_paginated_result(request)
+        df = pd.json_normalize(
+            data,
+            record_path='values',
+            meta=['employeeId']
+        )
+        valid_contracts, invalid_contracts = Functions.validate_data(df=df, schema=self.schema, debug=True)
+
+        return valid_contracts, invalid_contracts

brynq_sdk_bob/named_lists.py

@@ -0,0 +1,37 @@
+from datetime import datetime
+import pandas as pd
+from brynq_sdk_functions import Functions
+from .schemas.named_lists import NamedListSchema
+
+
+class NamedLists:
+    def __init__(self, bob):
+        self.bob = bob
+        self.schema = NamedListSchema
+
+    def get(self) -> (pd.DataFrame, pd.DataFrame):
+        """
+        Get custom table data for an employee
+
+        Args:
+            list_name: The list name
+
+        Returns:
+            A tuple of (valid_data, invalid_data) as pandas DataFrames
+        """
+        url = f"{self.bob.base_url}company/named-lists/"
+        resp = self.bob.session.get(url=url)
+        resp.raise_for_status()
+        data = resp.json()
+
+        df = pd.DataFrame([
+            {**item, "type": key}
+            for key, group in data.items()
+            for item in group["values"]
+        ])
+
+        # Normalize the nested JSON response
+        # df = pd.DataFrame(data.get('values'))
+        valid_data, invalid_data = Functions.validate_data(df=df, schema=NamedListSchema, debug=True)
+
+        return valid_data, invalid_data

brynq_sdk_bob/payments.py

@@ -0,0 +1,161 @@
+import pandas as pd
+from typing import Optional, List
+from brynq_sdk_functions import Functions
+from .schemas.payments import VariablePaymentSchema, ActualPaymentsSchema
+
+import time
+from tqdm import tqdm
+
+
+class Payments:
+    def __init__(self, bob):
+        self.bob = bob
+        self.schema = VariablePaymentSchema
+
+    def _apply_named_list_mappings(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Apply named list ID-to-value mappings to dataframe columns."""
+        if df.empty:
+            return df
+
+        # Fetch named lists from Bob API
+        resp_named_lists = self.bob.session.get(
+            url=f"{self.bob.base_url}company/named-lists",
+            timeout=self.bob.timeout,
+            headers=self.bob.headers
+        )
+        named_lists = resp_named_lists.json()
+
+        # Transform named_lists to create id-to-value mappings for each field
+        named_lists = {
+            key.split('.')[-1]: {item['id']: item['value'] for item in value['values']}
+            for key, value in named_lists.items()
+        }
+
+        for field in df.columns:
+            # Fields in the response and in the named-list have different building blocks
+            # but they both end with the same last block
+            field_df = field.split('.')[-1].split('work_')[-1]
+            if field_df in named_lists.keys() and field_df not in ['site']:
+                mapping = named_lists[field_df]
+                df[field] = df[field].apply(
+                    lambda v: [mapping.get(x, x) for x in v] if isinstance(v, list) else mapping.get(v, v)
+                )
+
+        return df
+
+    def get(self, person_ids: List[str]) -> (pd.DataFrame, pd.DataFrame):
+        df = pd.DataFrame()
+        for person_id in tqdm(person_ids, desc="Fetching variable payments"):
+            resp = self.bob.session.get(url=f"{self.bob.base_url}people/{person_id}/variable", timeout=self.bob.timeout)
+            resp.raise_for_status()
+            data = resp.json()
+            df = pd.concat([df, pd.json_normalize(
+                data,
+                record_path='values'
+            )])
+            df['employee_id'] = person_id
+
+            # Rate limit is 50 per minute
+            time.sleep(1.3)
+
+        df = df.reset_index(drop=True)
+
+        # Apply named list mappings
+        df = self._apply_named_list_mappings(df)
+
+        valid_payments, invalid_payments = Functions.validate_data(df=df, schema=self.schema, debug=True)
+        return valid_payments, invalid_payments
+
+    def get_actual_payments(
+        self,
+        limit: int = 200,
+        employee_ids: Optional[List[str]] = None,
+        pay_date_from: Optional[str] = None,
+        pay_date_to: Optional[str] = None
+    ) -> (pd.DataFrame, pd.DataFrame):
+        """
+        Search for actual payments with optional employee and pay date filters.
+        This method auto-paginates until all results are fetched.
+
+        See Bob API: https://apidocs.hibob.com/reference/post_people-actual-payments-search
+        See Pagination: https://apidocs.hibob.com/docs/pagination
+
+        Args:
+            limit (int): Number of records per page (default: 50, max: 200).
+            employee_ids (Optional[List[str]]): Filter by employee IDs.
+            pay_date_from (Optional[str]): Inclusive start date filter (YYYY-MM-DD).
+            pay_date_to (Optional[str]): Inclusive end date filter (YYYY-MM-DD).
+
+        Returns:
+            tuple: (valid_payments DataFrame, invalid_payments DataFrame)
+        """
+        base_payload = {
+            "pagination": {
+                "limit": limit
+            }
+        }
+
+        filters = []
+        if employee_ids:
+            filters.append({
+                "fieldPath": "employeeId",
+                "operator": "equals",
+                "values": employee_ids
+            })
+        if pay_date_from:
+            filters.append({
+                "fieldPath": "payDate",
+                "operator": "greaterThanOrEquals",
+                "value": pay_date_from
+            })
+        if pay_date_to:
+            filters.append({
+                "fieldPath": "payDate",
+                "operator": "lessThanOrEquals",
+                "value": pay_date_to
+            })
+
+        if filters:
+            base_payload["filters"] = filters
+
+        all_results = []
+        next_cursor = None
+
+        while True:
+            payload = dict(base_payload)
+            payload["pagination"] = dict(base_payload["pagination"])
+            if next_cursor:
+                payload["pagination"]["cursor"] = next_cursor
+
+            resp = self.bob.session.post(
+                url=f"{self.bob.base_url}people/actual-payments/search",
+                json=payload,
+                timeout=self.bob.timeout
+            )
+            resp.raise_for_status()
+            data = resp.json()
+
+            page_results = data.get('results') or []
+            if page_results:
+                all_results.extend(page_results)
+
+            next_cursor = (data.get('response_metadata') or {}).get('next_cursor')
+            if not next_cursor:
+                break
+
+        if not all_results:
+            empty_df = pd.DataFrame()
+            return empty_df, empty_df
+
+        df = pd.json_normalize(all_results)
+
+        # Apply named list mappings
+        df = self._apply_named_list_mappings(df)
+
+        valid_payments, invalid_payments = Functions.validate_data(
+            df=df,
+            schema=ActualPaymentsSchema,
+            debug=True
+        )
+
+        return valid_payments, invalid_payments

brynq_sdk_bob/payroll_history.py

@@ -0,0 +1,71 @@
+import pandas as pd
+from brynq_sdk_functions import Functions
+from .schemas.people import PeopleSchema
+
+class History:
+    def __init__(self, bob):
+        self.bob = bob
+        self.schema = PeopleSchema
+        self.field_name_in_body, self.field_name_in_response, self.endpoint_to_response = self._init_fields()
+
+    def get(self, additional_fields: list[str] = [], field_selection: list[str] = []) -> tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Get people from Bob
+
+        Args:
+            additional_fields (list[str]): Additional fields to get (not defined in the schema)
+            field_selection (list[str]): Fields to get (defined in the schema), if not provided, all fields are returned
+        """
+        #resp = self.bob.session.get(url=f"{self.bob.base_url}profiles", timeout=self.bob.timeout)
+        body_fields = list(set(self.field_name_in_body + additional_fields))
+        response_fields = list(set(self.field_name_in_response + additional_fields))
+
+        if field_selection:
+            body_fields = [field for field in body_fields if field in field_selection]
+            response_fields = [self.endpoint_to_response.get(field) for field in field_selection if field in self.endpoint_to_response]
+
+        # Bob sucks with default fields so you need to do a search call to retrieve additional fields.
+        resp_additional_fields = self.bob.session.post(url=f"{self.bob.base_url}people/search",
+                                                       json={
+                                                           "fields": body_fields,
+                                                           "filters": []
+                                                       },
+                                                       timeout=self.bob.timeout)
+        json_response = resp_additional_fields.json()
+        df = pd.json_normalize(resp_additional_fields.json()['employees'])
+        df = df[[col for col in response_fields if col in df.columns]]
+        # Get the valid column names from PeopleSchema
+        valid_people, invalid_people = Functions.validate_data(df=df, schema=PeopleSchema, debug=True)
+        return valid_people, invalid_people
+
+
+    def _init_fields(self) -> tuple[list[str], list[str], dict[str, str]]:
+        resp_fields = self.bob.session.get(
+            url=f"{self.bob.base_url}company/people/fields",
+            timeout=self.bob.timeout,
+            headers=self.bob.headers
+        )
+        fields = resp_fields.json()
+        field_name_in_body = [field.get('id') for field in fields]
+        field_name_in_response = [field['jsonPath'] for field in fields]
+        endpoint_to_response = {field['id']: field['jsonPath'] for field in fields}
+        return field_name_in_body, field_name_in_response, endpoint_to_response
+
+    def _get_employee_id_to_person_id_mapping(self) -> tuple[pd.DataFrame, pd.DataFrame]:
+        employee_id_in_company = "work.employeeIdInCompany"
+        person_id = "root.id"
+
+        body_fields = [employee_id_in_company, person_id]
+        response_fields = [self.endpoint_to_response.get(field) for field in body_fields if field in self.endpoint_to_response]
+
+        resp_additional_fields = self.bob.session.post(url=f"{self.bob.base_url}people/search",
+                                                       json={
+                                                           "fields": body_fields,
+                                                           "filters": []
+                                                       },
+                                                       timeout=self.bob.timeout)
+        df = pd.json_normalize(resp_additional_fields.json()['employees'])
+        df = df[[col for col in response_fields if col in df.columns]]
+        # Get the valid column names from PeopleSchema
+        valid_people, invalid_people = Functions.validate_data(df=df, schema=PeopleSchema, debug=True)
+        return valid_people, invalid_people

brynq_sdk_bob/people.py

@@ -0,0 +1,104 @@
+import pandas as pd
+from typing import Optional, List
+from brynq_sdk_functions import Functions
+from brynq_sdk_functions import BrynQPanderaDataFrameModel
+from .bank import Bank
+from .employment import Employment
+from .salaries import Salaries
+from .schemas.people import PeopleSchema
+from .work import Work
+from .custom_tables import CustomTables
+
+
+class People:
+    def __init__(self, bob):
+        self.bob = bob
+        self.salaries = Salaries(bob)
+        self.employment = Employment(bob)
+        self.bank = Bank(bob)
+        self.work = Work(bob)
+        self.custom_tables = CustomTables(bob)
+        self.schema = PeopleSchema
+
+
+        # Build API fields using column metadata if present (api_field), otherwise use the column (alias) name
+    def __build_api_fields(self, schema_model: BrynQPanderaDataFrameModel) -> list[str]:
+        schema = schema_model.to_schema()
+        return [
+            ((getattr(col, "metadata", None) or {}).get("api_field")) or col_name
+            for col_name, col in schema.columns.items()
+        ]
+
+    def get(self, schema_custom_fields: Optional[BrynQPanderaDataFrameModel] = None, employee_ids: Optional[List[str]] = None, show_inactive: bool = False) -> pd.DataFrame:
+        core_fields = self.__build_api_fields(PeopleSchema)
+        custom_fields = self.__build_api_fields(schema_custom_fields) if schema_custom_fields is not None else []
+        fields = core_fields + custom_fields
+
+        # Build filters based on employee_ids if provided
+        filters = []
+        if employee_ids is not None:
+            filters = [
+                {
+                    "fieldPath": "root.id",
+                    "operator": "equals",
+                    "values": employee_ids
+                }
+            ]
+
+        resp = self.bob.session.post(url=f"{self.bob.base_url}people/search",
+                                      json={
+                                          "fields": fields,
+                                          "filters": filters,
+                                          "showInactive": show_inactive,
+                                          #"humanReadable": "REPLACE"
+                                      },
+                                      timeout=self.bob.timeout)
+        resp.raise_for_status()
+        df = pd.json_normalize(resp.json()['employees'])
+        if df.empty and employee_ids is not None and resp.status_code == 200:
+            raise Exception(f"No employees found in HiBob for employee_ids: {employee_ids}")
+
+        df = df.loc[:, ~df.columns.str.contains('value')]
+
+        # Normalize separators in incoming data: convert '/' to '.' to match schema aliases
+        df.columns = df.columns.str.replace('/', '.', regex=False)
+
+        # A lot of fields from Bob are returned with only ID's. Those fields should be mapped to names. Therefore, we need to get the mapping from the named-lists endpoint.
+        resp_named_lists = self.bob.session.get(url=f"{self.bob.base_url}company/named-lists", timeout=self.bob.timeout, headers=self.bob.headers)
+        named_lists = resp_named_lists.json()
+        # save json to file
+        # import json
+        # with open('named_lists.json', 'w') as f:
+        #     json.dump(named_lists, f, indent=4)
+
+        # Transform named_lists to create id-to-value mappings for each field
+        named_lists = {key.split('.')[-1]: {item['id']: item['value'] for item in value['values']} for key, value in named_lists.items()}
+
+        deviating_named_list_cols_mapping = {
+            'payroll.employment.type': 'payrollEmploymentType',
+            'home.familyStatus': 'familystatus',
+            'personal.nationality': 'nationalities',
+        }
+
+        for field in df.columns:
+            # Fields in the response and in the named-list does have different building blocks (e.g. people.payroll.entitlement. or people.entitlement.). But they both end with the same last block
+            field_df = field.split('.')[-1].split('work_')[-1]
+
+            # Check if this field has a deviating mapping
+            named_list_key = deviating_named_list_cols_mapping.get(field, field_df)
+
+            if named_list_key in named_lists.keys() and named_list_key not in ['site']:
+                mapping = named_lists[named_list_key]
+                df[field] = df[field].apply(
+                    lambda v: [mapping.get(x, x) for x in v] if isinstance(v, list) else mapping.get(v, v)
+                )
+
+        if schema_custom_fields is not None:
+            valid_people, invalid_people_custom = Functions.validate_data(df=df, schema=schema_custom_fields, debug=True)
+        else:
+            valid_people = df
+            invalid_people_custom = pd.DataFrame()
+
+        valid_people, invalid_people = Functions.validate_data(df=valid_people, schema=PeopleSchema, debug=True)
+
+        return valid_people, pd.concat([invalid_people, invalid_people_custom])