Przewodnik dla partnerów dotyczący tworzenia integracji z HackerRank
Ten dokument jest przeznaczony dla partnerów, którzy chcą opracować integrację z HackerRank for Work. Nieustannie współpracujemy z dostawcami ATS, aby opracować integracje zapewniające lepsze doświadczenia użytkownika. Dokument ten dostarczy Ci wszystkich informacji potrzebnych do samodzielnego opracowania integracji.
Tło
Jedna liczba naszych klientów korporacyjnych - tj. tych, którzy używają HackerRank do testów i rozmów kwalifikacyjnych w fazie oceny, również korzysta z innych systemów informatycznych do zarządzania całym procesem rekrutacji. Systemy te mogą być zarówno gotowymi rozwiązaniami komercyjnymi (COTS), takimi jak Oracle Taleo, Jobvite, Greenhouse, Lever, Kenexa, RecruiterBox itp., jak i dedykowanymi, własnoręcznie rozwiniętymi systemami. Będziemy odnosić się do tych aplikacji łącznie jako Systemy Śledzenia Kandydatów (ATS).
Takich klientów często proszą o integrację ich systemu ATS z HackerRank for Work, aby rutynowe czynności związane z zarządzaniem kandydatami mogły być wykonywane w ramach przepływu pracy ATS. Przykłady takich rutynowych działań obejmują (a) zaproszenie wyselekcjonowanego kandydata do przystąpienia do testu HackerRank for Work, (b) przeglądanie wyników testu dla takich kandydatów w ich ATS, (c) zaplanowanie sesji wywiadu HackerRank pomiędzy inżynierem a wybranym kandydatem, (d) przeglądanie raportów z wywiadów w interfejsie ATS, itp. Dlatego najczęściej zgłaszane punkty integracji dotyczą pobierania danych z istniejącego konta HackerRank for Work i wykonywania konkretnych działań z poziomu interfejsu ATS. Mamy wywołania API, które pomogą wdrożyć te działania z poziomu interfejsu ATS.
Ogólny przepływ pracy
Integracja zazwyczaj polega na dodaniu funkcjonalności do ATS za pomocą wtyczki lub dostosowania przy użyciu API HackerRank for Work. Najlepiej wyjaśnić to wizualnie przy użyciu następujących diagramów.
Konwencje używane w poniższych przepływach pracy:
Ustawienia integracji – jednorazowa czynność
Uwaga: Każda oficjalna integracja ATS będzie posiadała sekcję w HackerRank for Work, w której administrator konta każdej firmy będzie mógł wygenerować klucz. Twój ATS pojawi się w następującej lokalizacji: https://www.hackerrank.com/work/settings/api
Ogólny przebieg testu
Ogólny przepływ CodePair (Interviews API)
Proces integracji
Zarejestruj się na bezpłatny okres próbny
Przejdź do https://www.hackerrank.com/work/signup aby zarejestrować się na darmowy 14‑dniowy okres próbny naszego produktu. To konto będzie wymagane, aby móc przetestować nasze API (patrz poniżej) i przetestować twoją integrację.
Poznaj nasze API
Mamy prosty interfejs RESTful API, który będzie podstawą integracji. Powinieneś rozpocząć naukę o naszym API tutaj:
https://www.hackerrank.com/work/apidocs
Uwaga: Powyższa dokumentacja została napisana z myślą o naszych końcowych klientach. Powinieneś zapoznać się z API na swoim koncie testowym jako końcowy klient. Jeśli masz jakiekolwiek pytania dotyczące API, skontaktuj się ze swoim punktem kontaktowym w HackerRank lub zgłoś prośbę o wsparcie, pisząc na support@hackerrank.com.
Zarejestruj swoją integrację
Po zapoznaniu się z API i opracowaniu przepływów, które chcesz obsłużyć, skontaktuj się ze swoim punktem kontaktowym w HackerRank lub wyślij e‑mail na support@hackerrank.com aby poprosić o klucz partnera. HackerRank również wydaje klucz API dla całej firmy, który możesz używać w swojej integracji.
Zmień mechanizm uwierzytelniania w kodzie integracji
Wprowadź następujące zmiany w swojej integracji:
Dodaj nagłówek autoryzacji partnera: Dołącz następujący niestandardowy nagłówek w każdym żądaniu:
X-HRW-Partner-Authorization: abcdZastąp
abcdpodanym kluczem partnera.Dodaj nagłówek e‑mail użytkownika: Dołącz następujący niestandardowy nagłówek:
HRW-User-Email: user@email.comZastąp
user@email.comadresem e‑mail użytkownika, który inicjuje żądanie z Twojej aplikacji.
Ten e‑mail musi odpowiadać istniejącemu użytkownikowi w koncie HackerRank for Work klienta.Użyj klucza API obowiązującego w całej firmie zamiast tokenu dostępu osobistego, którego używałeś, eksplorując API w swoim koncie.
Przy każdym wywołaniu, które wykonujesz, możesz również wybrać, aby dołączyć dodatkowe metadane w swoim ładunku, jeśli istnieją metadane, które chcesz, aby HackerRank zapisał. Niektóre powszechnie spotykane pola obejmują
user_email powinien identyfikować użytkownika inicjującego żądanie. Powinien odpowiadać istniejącemu użytkownikowi w koncie HRW klienta.
candidateId może być unikalnym identyfikatorem tego kandydata w Twoim systemie. Niektóre wywołania API nie są specyficzne dla kandydata i w takich przypadkach możesz zignorować to pole.
applicationId może być użyte, jeśli kandydat może aplikować do więcej niż jednego żądania. To może być inne pole i identyfikować konkretną aplikację. Niektóre wywołania API nie są specyficzne dla kandydata i w takich przypadkach możesz zignorować to pole.
{
...
"metadata": {
"candidateId": "16651587",
"applicationId": "25145412",
"user_email": "abcd@example.com"
}
}
Używanie tokenu autoryzacji Partnera oraz kluczy per‑firma jest ważne, ponieważ mamy inny zestaw zasad i limitów szybkości. Pomaga to także łatwiej rozwiązywać problemy klientów pochodzące od Ciebie, co prowadzi do lepszego doświadczenia użytkownika.
Walidacja integracji
Gdy zmodyfikujesz integrację, aby używać powyższej autoryzacji partnera, oceniamy integrację pod kątem poprawnych ścieżek oraz niektórych znanych przypadków brzegowych, z którymi spotkaliśmy się w przeszłości przy integracjach.
Przegląd dokumentacji użytkownika końcowego będzie ważną częścią ćwiczenia walidacyjnego.
Ogólna dostępność
Po zakończeniu walidacji dodamy wpis na stronie integracji ATS, który pokaże wszystkie obsługiwane integracje. Korzystając z tego interfejsu, zwykli klienci będą mogli samodzielnie włączać lub wyłączać Twoją integrację.
Twoja integracja będzie dostępna jako opcja na naszej stronie Ustawień Integracji: https://www.hackerrank.com/work/settings/api
Najlepsze praktyki integracji
Scenariusze błędów
Z naszego doświadczenia z systemami ATS niektóre typowe scenariusze, które prowadzą do błędów przy zapraszaniu kandydatów, to:
Klucz API nie jest ważny dla Twojego konta HackerRank for Work. (Musi być kluczem firmowym, a autoryzacja partnera powinna działać prawidłowo)
Adres e‑mail rekrutera dla konta ATS (wysłany w metadanych) różni się od e‑maila używanego w HackerRank for Work (np. używanie sriram.karra@hackerrank.com w koncie ATS i sriram@hackerrank.com w Twoich kontach HRW). Nie ma znaczenia, który z nich naprawisz, pod warunkiem że będą takie same.
Adres e‑mail kandydata jest brakujący lub nieprawidłowy
Kandydat z tym adresem e‑mail został już zaproszony.
Rekruter nie ma „Miejsca rekrutacji” w HackerRank, a więc nie ma uprawnienia do zapraszania kandydatów
Rekruter nie ma uprawnień do dostępu do określonego testu
Konto HackerRank rekrutera nie jest aktywowane.
Zalecamy, aby przetestować swoją integrację we wszystkich powyższych scenariuszach i zapewnić, że zachowanie aplikacji jest płynne.
Obsługa błędów
Testy API
Dla testowego API zwracamy błędy w dwóch różnych formatach – należy obsłużyć oba formaty odpowiedzi i wyświetlić właściwy typ komunikatu użytkownikowi końcowemu.
Przypadek 1: Błąd jest lokalny dla kandydata, na przykład ponowne zaproszenie kandydata. Ma on następujący format:
{
"data": {
"username": “error@hackerrank.com",
"password": "96d3efe9",
"test_link": “link",
"status": false,
"error": 1002,
"error_message": "Kandydat został już zaproszony do przystąpienia do tego samego testu. Jeśli chcesz ponownie zaprosić, najpierw anuluj zaproszenie w swoim koncie HackerRank for Work."
},
"message": "Brak zaproszonych kandydatów.",
}
Pogrubione pola wskazują, że wystąpił błąd. Jeśli wystąpią nieprzechwycone błędy podczas tworzenia kandydata, są one również wyświetlane w tym formacie.
Przypadek 2: Jeśli w samej konfiguracji rekrutera wystąpi błąd (zazwyczaj w wyniku złej konfiguracji lub nieprawidłowego formatu), zostaje on zwrócony w następującym formacie:
{
"data": {},
"status": false,
"message": "Nie istnieje taki test",
}
Działania wywołujące ten błąd obejmują nieprawidłowe konto rekrutera, nieprawidłowe e-maile, nieprawidłowy identyfikator testu itp.
Udane żądania zostaną zwrócone z kodami odpowiedzi 200.
Nieprawidłowy token dostępu: Oprócz tych dwóch scenariuszy błędów, jeśli użytkownik skonfigurował integrację z nieprawidłowym kodem dostępu, zwrócimy błąd w następującym formacie z kodem odpowiedzi 401:
{
"model": {},
"message": "Nieprawidłowy token dostępu"
}
CodePair API (API wywiadów)
Nieprawidłowy token dostępu: Jeśli token dostępu zawarty w żądaniu jest nieprawidłowy, zwrócimy pustą odpowiedź z kodem statusu 403.
Nieprawidłowe informacje: W przypadku, gdy żądanie zawiera jeden lub więcej błędów innych niż błąd tokena dostępu, zwrócimy listę wszystkich błędów w polu errors z kodem statusu żądania 422. Na przykład:
{
"errors": [
"tytuł jest wymaganym polem",
"zakres czasu wywiadu jest nieprawidłowy",
"......."
]
}
