examples/[Training] tracking_data_upload.ipynb

{
  "cells": [
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Open this notebook in Google Colab : [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Riminder/hrflow-cookbook/blob/main/examples/%5BTraining%5D%20tracking_data_upload.ipynb)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "AZdfdAQSt7hZ"
      },
      "source": [
        "##### Copyright 2023 HrFlow's AI Research Department\n",
        "\n",
        "Licensed under the Apache License, Version 2.0 (the \"License\");"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "QNgz5iA-uD4E"
      },
      "outputs": [],
      "source": [
        "# Copyright 2023 HrFlow's AI Research Department. All Rights Reserved.\n",
        "#\n",
        "# Licensed under the Apache License, Version 2.0 (the \"License\");\n",
        "# you may not use this file except in compliance with the License.\n",
        "# You may obtain a copy of the License at\n",
        "#\n",
        "#     http://www.apache.org/licenses/LICENSE-2.0\n",
        "#\n",
        "# Unless required by applicable law or agreed to in writing, software\n",
        "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
        "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
        "# See the License for the specific language governing permissions and\n",
        "# limitations under the License.\n",
        "# =============================================================================="
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "PfFOG5klschh"
      },
      "source": [
        "Welcome to this Google Colaboratory tutorial for developers. **In only 3 steps**, we'll help you **upload your job, profile and tracking data to HrFlow.ai**. This will enable you to test the powerful **HrFlow.ai Retraining feature**.\n",
        "\n",
        "Before we proceed, please ensure that you have created a source and a board in HrFlow.ai to store your data. You can find detailed instructions on how to create them through the following links:\n",
        "- **Create your board**: [Connectors Board Documentation](https://developers.hrflow.ai/docs/connectors-board)\n",
        "- **Create your source**: [Connectors Source Documentation](https://developers.hrflow.ai/docs/connectors-source)\n",
        "\n",
        "Now, let's take a quick look at how this notebook is organized:\n",
        "1. **🛠 Uploading Job Data**: Create and upload job details.\n",
        "2. **👷 Uploading Profile Data**: Build and upload candidate profile information.\n",
        "3. **🛤 Uploading Tracking Data**: Monitor candidate progress by uploading tracking data.\n",
        "\n",
        "Let's get started and harness the capabilities of HrFlow.ai!"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Y6_c0izEXfLX"
      },
      "source": [
        "# Getting Started"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "2_3diMbMYgaA"
      },
      "outputs": [],
      "source": [
        "!pip install --quiet hrflow"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "GG8ZjRi2Ygdg"
      },
      "outputs": [],
      "source": [
        "from functools import wraps\n",
        "from getpass import getpass\n",
        "from hrflow import Hrflow\n",
        "from time import time, sleep\n",
        "from tqdm.notebook import tqdm\n",
        "\n",
        "\n",
        "API_SECRET = getpass(\"YOUR_API_SECRET\")\n",
        "API_USER = getpass(\"USER@EMAIL.DOMAIN\")\n",
        "SOURCE_KEY = getpass(\"YOUR_SOURCE_KEY\")\n",
        "BOARD_KEY = getpass(\"YOUR_BOARD_KEY\")\n",
        "\n",
        "\n",
        "def rate_limiter(\n",
        "    max_requests_per_minute=30,\n",
        "    min_sleep_per_request=1.0\n",
        "  ):\n",
        "  \"\"\"\n",
        "  Decorator that applies rate limiting to a function.\n",
        "\n",
        "  Args:\n",
        "      max_requests_per_minute (int): The maximum number of requests allowed per minute.\n",
        "      min_sleep_per_request (float): The minimum time to sleep between consecutive requests.\n",
        "  \"\"\"\n",
        "  def decorator(func):\n",
        "    requests_per_minute = 0\n",
        "    last_reset_time = time()\n",
        "\n",
        "    @wraps(func)\n",
        "    def wrapper(*args, **kwargs):\n",
        "      nonlocal requests_per_minute, last_reset_time\n",
        "\n",
        "      current_time = time()\n",
        "      elapsed_time = current_time - last_reset_time\n",
        "\n",
        "      if elapsed_time < 60:\n",
        "        requests_per_minute += 1\n",
        "        if requests_per_minute >= max_requests_per_minute:\n",
        "          sleep(60 - elapsed_time)\n",
        "          requests_per_minute = 0\n",
        "          last_reset_time = time()\n",
        "      else:\n",
        "        requests_per_minute = 0\n",
        "        last_reset_time = current_time\n",
        "\n",
        "      sleep(min_sleep_per_request)\n",
        "      return func(*args, **kwargs)\n",
        "\n",
        "    return wrapper\n",
        "\n",
        "  return decorator\n",
        "\n",
        "\n",
        "client = Hrflow(api_secret=API_SECRET, api_user=API_USER)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# 1. 🛠 Uploading Job Data (Optional)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "**Please use the code 'jobs = load_jobs()' in the following cell to load all your jobs.**\n",
        "\n",
        "To provide you with a better understanding of how this notebook works, we have included a Dummy JOB as an example in the second cell. This will help you familiarize yourself with the structure and format of the data.\n",
        "\n",
        "Please refer to the HrFlow.ai Job object documentation for detailed information: https://developers.hrflow.ai/reference/the-job-object\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "def load_jobs():\n",
        "  \"\"\"\n",
        "  Loads and formats your job data into an HrFlow.ai Job object.\n",
        "\n",
        "  Note: You need to implement the mapping between your data and the HrFlow.ai Job object.\n",
        "\n",
        "  Please refer to the HrFlow.ai Job object documentation for detailed information:\n",
        "  https://developers.hrflow.ai/reference/the-job-object\n",
        "\n",
        "  Returns:\n",
        "      List[Dict]: The formatted Job object.\n",
        "\n",
        "  Raises:\n",
        "      NotImplementedError: This function is not implemented yet.\n",
        "  \"\"\"\n",
        "  raise NotImplementedError(\"You need to implement this function and do the mapping between your data and the HrFlow.ai Job object.\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "jobs = [\n",
        "  {\n",
        "    \"reference\": \"DUMMY_JOB\",\n",
        "    \"name\": \"DUMMY_JOB\",\n",
        "    \"url\": \"https://hrflow.ai/careers/\",\n",
        "    \"picture\": None,\n",
        "    \"summary\": \"Forged by HrFlow.ai\",\n",
        "    \"location\": {\n",
        "      \"text\": \"Los Angeles, USA\",\n",
        "      \"lat\": 34.05358,\n",
        "      \"lng\": -118.24546,\n",
        "      \"gmaps\": \"https://goo.gl/maps/FnPKCisdwBBfLNTt5\",\n",
        "      \"fields\": []\n",
        "    },\n",
        "    \"created_at\": \"2023-01-01T00:00:00+0000\",\n",
        "    \"sections\": [\n",
        "      {\n",
        "        \"name\": \"SECTION NAME\",\n",
        "        \"title\": \"SECTION TITLE\",\n",
        "        \"description\": \"SECTION DESCRIPTION\"\n",
        "      }\n",
        "    ],\n",
        "    \"culture\": \"ABOUT THE COMPANY'S CULTURE\",\n",
        "    \"responsibilities\": \"ABOUT THE TASKS AND ROLES\",\n",
        "    \"requirements\": \"ABOUT THE TECHNICAL BACKGROUND\",\n",
        "    \"benefits\": \"ABOUT THE COMPENSATION PACKAGE\",\n",
        "    \"interviews\": \"ABOUT THE RECRUITMENT PROCESS\",\n",
        "    \"skills\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY SKILL\",\n",
        "        \"type\": \"hard\",\n",
        "        \"value\": None\n",
        "      }\n",
        "    ],\n",
        "    \"languages\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY LANGUAGE\",\n",
        "        \"value\": None\n",
        "      }\n",
        "    ],\n",
        "    \"certifications\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY CERTIFICATION\",\n",
        "        \"value\": None\n",
        "      }\n",
        "    ],\n",
        "    \"courses\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY COURSE\",\n",
        "        \"value\": None\n",
        "      }\n",
        "    ],\n",
        "    \"tasks\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY TASK\",\n",
        "        \"value\": None\n",
        "      }\n",
        "    ],\n",
        "    \"tags\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY NAME\",\n",
        "        \"value\": \"DUMMY VALUE\"\n",
        "      }\n",
        "    ],\n",
        "    \"metadatas\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY NAME\",\n",
        "        \"value\": \"DUMMY VALUE\"\n",
        "      }\n",
        "    ],\n",
        "    \"ranges_float\": [\n",
        "      {\n",
        "        \"name\": \"Salary\",\n",
        "        \"value_min\": 100000,\n",
        "        \"value_max\": None,\n",
        "        \"unit\": \"EUR\"\n",
        "      }\n",
        "    ],\n",
        "    \"ranges_date\": [\n",
        "      {\n",
        "        \"name\": \"date_start\",\n",
        "        \"value_min\": \"1970-01-01T00:00:00+0000\",\n",
        "        \"value_max\": None\n",
        "      }\n",
        "    ]\n",
        "  }\n",
        "]\n",
        "\n",
        "upload_job = rate_limiter()(client.job.storing.add_json)\n",
        "for job in tqdm(jobs):\n",
        "  response = upload_job(BOARD_KEY, job)\n",
        "print(response)\n"
      ]
    },
    {
      "attachments": {},
      "cell_type": "markdown",
      "metadata": {
        "id": "LwG57WibXovP"
      },
      "source": [
        "# 2. 👷 Uploading Profile Data (Optional)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "S_ggn2lNqCeN"
      },
      "source": [
        "**Please use the code 'profiles = load_profiles()' in this cell to load all your profiles.**\n",
        "\n",
        "To provide you with a better understanding of how this notebook works, we have included a Dummy Profile as an example in the second cell. This will help you familiarize yourself with the structure and format of the data.\n",
        "\n",
        "Please refer to the HrFlow.ai Profile object documentation for detailed information: https://developers.hrflow.ai/reference/the-profile-object"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "7f_t1ulTYZ-N"
      },
      "outputs": [],
      "source": [
        "def load_profiles():\n",
        "  \"\"\"\n",
        "  Loads and formats your profile data into an HrFlow.ai Profile object.\n",
        "\n",
        "  Note: You need to implement the mapping between your data and the HrFlow.ai Profile object.\n",
        "\n",
        "  Please refer to the HrFlow.ai Profile object documentation for detailed information:\n",
        "  https://developers.hrflow.ai/reference/the-profile-object\n",
        "\n",
        "  Returns:\n",
        "      List[Dict]: The formatted Profile object.\n",
        "\n",
        "  Raises:\n",
        "      NotImplementedError: This function is not implemented yet.\n",
        "  \"\"\"\n",
        "  raise NotImplementedError(\"You need to implement this function and do the mapping between your data and the HrFlow.ai Profile object.\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "DnRByXbOZcRM"
      },
      "outputs": [],
      "source": [
        "profiles = [\n",
        "  {\n",
        "    \"reference\": \"DUMMY_PROFILE\",\n",
        "    \"created_at\": \"2023-01-01T00:00:00+0000\",\n",
        "    \"info\": {\n",
        "      \"full_name\": \"DUMMY PROFILE\",\n",
        "      \"first_name\": \"DUMMY\",\n",
        "      \"last_name\": \"PROFILE\",\n",
        "      \"email\": \"dummy_profile@hrflow.ai\",\n",
        "      \"phone\": \"+16506815000\",\n",
        "      \"date_birth\": \"1970-01-01T00:00:00+0000\",\n",
        "      \"location\": {\n",
        "        \"text\": \"Los Angeles, USA\",\n",
        "        \"lat\": 34.05358,\n",
        "        \"lng\": -118.24546,\n",
        "        \"gmaps\": \"https://goo.gl/maps/FnPKCisdwBBfLNTt5\",\n",
        "        \"fields\": []\n",
        "      },\n",
        "      \"urls\": \"https://hrflow.ai/\",\n",
        "      \"picture\": None,\n",
        "      \"gender\": \"male\",\n",
        "      \"summary\": \"Forged by HrFlow.ai...\"\n",
        "    },\n",
        "    \"text_language\": \"en\",\n",
        "    \"text\": \"DUMMY PROFILE\\nForged by HrFlow.ai...\",\n",
        "    \"experiences_duration\": 0.0,\n",
        "    \"educations_duration\": 0.0,\n",
        "    \"experiences\":[\n",
        "      {\n",
        "        \"key\": \"DUMMY_KEY\",\n",
        "        \"title\": \"DUMMY_TITLE\",\n",
        "        \"description\": \"DUMMY_DESCRIPTION\",\n",
        "        \"location\": {\n",
        "          \"text\": \"Los Angeles, USA\",\n",
        "          \"lat\": 34.05358,\n",
        "          \"lng\": -118.24546,\n",
        "          \"gmaps\": \"https://goo.gl/maps/FnPKCisdwBBfLNTt5\",\n",
        "          \"fields\": []\n",
        "        },\n",
        "        \"date_start\": \"1970-01-01T00:00:00+0000\",\n",
        "        \"date_end\": \"1970-01-01T00:00:00+0000\",\n",
        "        \"skills\": [],\n",
        "        \"certifications\": [],\n",
        "        \"courses\": [],\n",
        "        \"tasks\": [],\n",
        "        \"company\": \"HrFlow.ai\"\n",
        "      }\n",
        "    ],\n",
        "    \"educations\":[\n",
        "      {\n",
        "        \"key\": \"DUMMY_KEY\",\n",
        "        \"title\": \"DUMMY_TITLE\",\n",
        "        \"description\": \"DUMMY_DESCRIPTION\",\n",
        "        \"location\": {\n",
        "          \"text\": \"Los Angeles, USA\",\n",
        "          \"lat\": 34.05358,\n",
        "          \"lng\": -118.24546,\n",
        "          \"gmaps\": \"https://goo.gl/maps/FnPKCisdwBBfLNTt5\",\n",
        "          \"fields\": []\n",
        "        },\n",
        "        \"date_start\": \"1970-01-01T00:00:00+0000\",\n",
        "        \"date_end\": \"1970-01-01T00:00:00+0000\",\n",
        "        \"skills\": [],\n",
        "        \"certifications\": [],\n",
        "        \"courses\": [],\n",
        "        \"tasks\": [],\n",
        "        \"school\": \"HrFlow.ai\"\n",
        "      }\n",
        "    ],\n",
        "    \"attachments\": [],\n",
        "    \"skills\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY_SKILL\",\n",
        "        \"type\": \"hard\",\n",
        "        \"value\": \"DUMMY_VALUE\"\n",
        "      }\n",
        "    ],\n",
        "    \"languages\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY_LANGUAGE\",\n",
        "        \"value\": \"DUMMY_VALUE\"\n",
        "      }\n",
        "    ],\n",
        "    \"certifications\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY_CERTIFICATION\",\n",
        "        \"value\": \"DUMMY_VALUE\"\n",
        "      }\n",
        "    ],\n",
        "    \"courses\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY_COURSE\",\n",
        "        \"value\": \"DUMMY_VALUE\"\n",
        "        }\n",
        "    ],\n",
        "    \"tasks\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY_TASK\",\n",
        "        \"value\": \"DUMMY_VALUE\"\n",
        "      }\n",
        "    ],\n",
        "    \"interests\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY_INTEREST\",\n",
        "        \"value\": \"DUMMY_VALUE\"\n",
        "      }\n",
        "    ],\n",
        "    \"tags\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY_NAME\",\n",
        "        \"value\": \"DUMMY_VALUE\"\n",
        "      }\n",
        "    ],\n",
        "    \"metadatas\": [\n",
        "      {\n",
        "        \"name\": \"DUMMY_NAME\",\n",
        "        \"value\": \"DUMMY_VALUE\"\n",
        "      }\n",
        "    ],\n",
        "  }\n",
        "]\n",
        "\n",
        "upload_profile = rate_limiter()(client.profile.storing.add_json)\n",
        "for profile in tqdm(profiles):\n",
        "  response = upload_profile(SOURCE_KEY, profile)\n",
        "print(response)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "SgDchHxfX4S9"
      },
      "source": [
        "# 3. 🛤 Uploading Tracking Data"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2esAte8ysDuQ"
      },
      "source": [
        "Please use the code 'trackings = load_trackings()' in this cell to load all your trackings.\n",
        "\n",
        "To provide you with a better understanding of how this notebook operates, we have included a dummy tracking example. This will help you grasp the structure and format of the data.\n",
        "\n",
        "Please note that the 'profile_reference' and 'job_reference' fields are being used to upload your profiles and jobs, respectively. This information is crucial for constructing the tracking objects accurately.\n",
        "\n",
        "The 'created_at' field follows ISO 8601 format, please provide the creation date in the source ATS."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "Ec_dTOthYbjv"
      },
      "outputs": [],
      "source": [
        "def load_trackings():\n",
        "    \"\"\"\n",
        "    Loads and formats your tracking data into an HrFlow.ai Tracking object.\n",
        "\n",
        "    Note: You need to implement the mapping between your data and the HrFlow.ai Tracking object.\n",
        "\n",
        "    The schema for the HrFlow.ai Tracking object is as follows:\n",
        "    Tracking = {\n",
        "        \"action\": [\"view\", \"apply\", \"hire\"],\n",
        "        \"role\": [\"recruiter\", \"candidate\", \"employee\", \"manager\"]\n",
        "        \"source_key\": str\n",
        "        \"profile_reference\": str,\n",
        "        \"board_key\": str\n",
        "        \"job_reference\": str\n",
        "        \"created_at\": str\n",
        "    }\n",
        "\n",
        "    Returns:\n",
        "        List[Tracking]: The formatted Tracking object.\n",
        "\n",
        "    Raises:\n",
        "        NotImplementedError: This function is not implemented yet.\n",
        "    \"\"\"\n",
        "    raise NotImplementedError(\"You need to implement this function and map your data to the HrFlow.ai Tracking object.\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "BYf6Ir6RZpmF"
      },
      "outputs": [],
      "source": [
        "trackings = [\n",
        "  {\n",
        "    \"action\": \"apply\",\n",
        "    \"role\": \"candidate\",\n",
        "    \"source_key\": SOURCE_KEY,\n",
        "    \"profile_reference\": \"DUMMY_PROFILE\",\n",
        "    \"board_key\": BOARD_KEY,\n",
        "    \"job_reference\": \"DUMMY_JOB\",\n",
        "    \"created_at\": \"2022-10-31T00:00:00+0000\"\n",
        "  }\n",
        "]\n",
        "\n",
        "upload_tracking = rate_limiter()(client.tracking.post)\n",
        "for tracking in tqdm(trackings):\n",
        "  response = upload_tracking(**tracking)\n",
        "print(response)"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "provenance": [],
      "toc_visible": true
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}