HR-REST-API

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 4 Minuten Lesedauer

    • Die HR-REST Die API stellt Endpunkte bereit, die Informationen zu Mitarbeitern zurückgeben, die in den USA arbeiten oder leben.

    Für den Zugriff auf diese API müssen die Rolle „sn_hr_core.usa_employee_only“ und das Plugin „bereichsbezogene App für Human Resources: Core“ (com_sn_hr_core) aktiviert sein.

    HR-REST – GET /get_usa_employee_profile

    Gibt Mitarbeiterprofilinformationen für Mitarbeiter mit Sitz in den USA zurück.

    Die zurückgegebenen Informationen können entweder:
    • Mitarbeiterprofilinformationen für eine angegebene Mitarbeiter-ID.
    • Informationen für Mitarbeiter, die am oder nach einem bestimmten Datum hinzugefügt wurden oder deren Informationen aktualisiert wurden.
    Hinweis:
    Mitarbeiter müssen entweder ihr Arbeits- oder Heimatland als USA angegeben haben, damit dieser Endpunkt sie in die Rückgabeergebnisse einbezieht.
    Darüber hinaus sendet der Endpunkt die folgenden Parameter an die integrierte CIC Plus-Anwendung (Beschreibungen finden Sie im Abschnitt „Rückgaben“):
    • Mitarbeiter-Bezeichner
    • Vorname
    • Mittelname
    • Nachname
    • E-Mail
    • Arbeitsadresse
    • Arbeitsstadt
    • Arbeitsstatus
    • Postleitzahl des Arbeitsbereichs
    • Arbeitsland
    • Privatadresse
    • Heimatstadt
    • Heimatland
    • HomePostleitzahl
    • Homecountry
    • Geburtsdatum
    • Einstellungsdatum

    URL-Format

    Standard-URL: /api/sn_HR_Core/HR_Rest_api/get_usa_employee_profile

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfad-Parameter
    Name Beschreibung
    Keine
    Tabelle : 2. Abfrageparameter
    Parameter Beschreibung
    Employee_Identifier Eindeutiger Bezeichner eines Mitarbeiters. Das aufrufende System generiert diesen Wert und kann in einem beliebigen Format vorliegen, das mit seinem System konsistent ist. Um diesen Wert zu erhalten, rufen Sie zuerst den Endpunkt mit auf updated_afterParameter.
    Hinweis:
    Dieser Parameter schließt sich gegenseitig mit aus updated_afterParameter. Dieser Parameter definiert einen eindeutigen Mitarbeiter, während updated_afterGibt eine Gruppe von Mitarbeitern zurück, die nach einem angegebenen Datum erstellt/aktualisiert wurden.

    Datentyp: Zeichenfolge
    Sysparm_limit Maximale Anzahl zurückzugebender Datensätze. Für Anforderungen, die diese Anzahl von Datensätzen überschreiten, verwenden Sie sysparm_offsetParameter zum Paginieren des Datensatzabrufs.

    Datentyp: Zahl

    Standard: 1000
    Sysparm_Offset Startdatensatzindex, für den mit dem Abrufen von Datensätzen begonnen werden soll. Verwenden Sie diesen Wert, um den Datensatzabruf zu paginieren. Diese Funktionalität ermöglicht den Abruf aller Datensätze, unabhängig von der Anzahl der Datensätze, in kleinen verwaltbaren Blöcken.

    Beispiel: Wenn Sie diesen Endpunkt zum ersten Mal aufrufen, sysparm_offsetIst auf „0“ festgelegt. Um einfach alle verfügbaren Datensätze durchzublättern, verwenden Sie Sysparm_Offset=sysparm_Offset+sysparm_limit , Bis Sie das Ende aller Datensätze erreichen.
    Updated_After Datum, das zur Bestimmung der zurückzugebenden Mitarbeiterdaten verwendet werden soll. Alle Mitarbeiter mit Sitz in den USA (Arbeit oder Privatadresse), die Ihrer Instanz hinzugefügt wurden oder deren Informationen am oder nach diesem Datum aktualisiert wurden, werden in die Rückgabeergebnisse aufgenommen.
    Hinweis:
    Dieser Parameter schließt sich gegenseitig mit aus employee_identifierParameter.

    Datentyp: Zeichenfolge

    Format: JJJJ-MM-TT HH:MM:SS oder JJJJ-MM-TT (Zeit standardmäßig 00:00:00)
    Tabelle : 3. Anforderungstext-Parameter (XML oder JSON)
    Name Beschreibung
    Keine

    Header

    Die folgenden Anforderungs- und Antwort-Header gelten nur für diese HTTP-Aktion oder werden auf diese Aktion in einer bestimmten Weise angewendet. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header .

    Tabelle : 4. Anforderungskopfzeilen.
    Header Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/jsonOder application/xml.

    Standard: application/json
    Tabelle : 5. Antwort-Header
    Header Beschreibung
    Nächste Seite Kennzeichnung, die angibt, ob bei einem nachfolgenden Anruf zusätzliche Daten abgerufen werden sollen. Wenn beispielsweise insgesamt 120 Mitarbeiterdatensätze vorhanden sind, die den Suchkriterien entsprechen, und „sysparm_limit“ auf 100 festgelegt ist, dann Next-PageIst „wahr“. Wenn keine zusätzlichen Ergebnisse verfügbar sind, Next-PageIst falsch.
    Gültige Werte:
    • Wahr: Zusätzliche Daten sind verfügbar. Ein weiterer Anruf muss getätigt werden, um den nächsten Datenblock abzurufen.
    • Falsch: Keine zusätzlichen Daten.

    Statuscodes

    Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST-API verwendet werden, finden Sie unter REST-API-HTTP-Antwortcodes .

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    401 Nicht autorisiert Die Anwenderanmeldeinformationen sind falsch oder wurden nicht übergeben.
    404 Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Die Antwort enthält zusätzliche Informationen zum Fehler.

    Antworttext-Parameter (JSON oder XML)

    Element Beschreibung
    Geburtsdatum Geburtsdatum des Mitarbeiters.

    Datentyp: Zeichenfolge
    Unternehmen Unternehmensname.

    Datentyp: Zeichenfolge
    E-Mail E-Mail-Adresse des Mitarbeiters.

    Datentyp: Zeichenfolge
    Mitarbeiter-Bezeichner Eindeutiger Mitarbeiterbezeichner.

    Datentyp: Zeichenfolge
    Vorname Vorname des Mitarbeiters.

    Datentyp: Zeichenfolge
    Einstellungsdatum Datum, an dem der Mitarbeiter eingestellt wurde.

    Datentyp: Zeichenfolge
    Nachname Nachname des Mitarbeiters.

    Datentyp: Zeichenfolge
    Mittelname Zweiter Vorname des Mitarbeiters.

    Datentyp: Zeichenfolge
    Erneut einstellen Zur zukünftigen Verwendung.

    Datentyp: Zeichenfolge
    Wohnsitzadresse Privatadresse des Mitarbeiters.

    Datentyp: Zeichenfolge
    Wohnsitzstadt Privatstadt des Mitarbeiters.

    Datentyp: Zeichenfolge
    Wohnsitzland Heimatland des Mitarbeiters.

    Datentyp: Zeichenfolge
    Postleitzahl des Wohnsitzes Private Postleitzahl des Mitarbeiters.

    Datentyp: Zeichenfolge
    Wohnsitzstatus Privatstatus des Mitarbeiters.

    Datentyp: Zeichenfolge
    Suffix Suffix des Mitarbeiters, z. B. Herr, Frau oder Dr.

    Datentyp: Zeichenfolge
    Arbeitsadresse Straße und Hausnummer des Mitarbeiters.

    Datentyp: Zeichenfolge
    Arbeitsstadt Arbeitsort des Mitarbeiters

    Datentyp: Zeichenfolge
    Arbeitsland Arbeitsland des Mitarbeiters.

    Datentyp: Zeichenfolge
    Postleitzahl des Arbeitsbereichs Postleitzahl der Arbeit des Mitarbeiters.

    Datentyp: Zeichenfolge
    Arbeitsstatus Arbeitsstatus des Mitarbeiters.

    Datentyp: Zeichenfolge

    Beispiel für eine Curl-Anforderung für die Informationen eines bestimmten Mitarbeiters

    curl -X GET "https://instance.servicenow.com/api/sn_hr_core/V1/hr_rest_api/get_usa_employee_profile?employee_identifier=231"
-H "accept: application/json" \
-u "username":"password"
    {"result": [
 {
  "EmployeeIdentifier": "231",
  "FirstName": "Harold",
  "MiddleName": "William",
  "LastName": "Lewis",
  "Suffix": "Mr.",
  "Email": "Howard.Lewis@example.com",
  "BirthDate": "",
  "HireDate": "2021-02-18",
  "Company": "ServiceNow Inc",
  "ResidenceAddress": "",
  "ResidenceCity": "SD",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "2617 South Robinson Avenue, Oklahoma City",
  "WorkCity": "Oklahoma",
  "WorkState": "OK",
  "WorkPostalCode": "73109",
  "WorkCountry": "USA",
  "ReHire": ""
 }
]}

    Beispiel für eine Curl-Anforderung für eine Liste der Mitarbeiter, die am oder nach dem 18/2019 hinzugefügt/aktualisiert wurden

    curl -X GET "https://instance.servicenow.com/api/sn_hr_core/V1/hr_rest_api/get_usa_employee_profile?update_after=2019-05-18"
-H "accept: application/json" \
-u "username":"password"
    {"result": [
 {
  "EmployeeIdentifier": "2345",
  "FirstName": "Cheryl",
  "MiddleName": "Lynn",
  "LastName": "Smith",
  "Suffix": "Mrs.",
  "Email": "Cheryl.Smith@example.com",
  "BirthDate": "",
  "HireDate": "2019-06-18",
  "Company": "ServiceNow Inc",
  "ResidenceAddress": "",
  "ResidenceCity": "SD",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "2617 South Robinson Avenue, Oklahoma City",
  "WorkCity": "Oklahoma",
  "WorkState": "OK",
  "WorkPostalCode": "73109",
  "WorkCountry": "USA",
  "ReHire": ""
  },
  {
  "EmployeeIdentifier": "1111",
  "FirstName": "Thomas",
  "MiddleName": "",
  "LastName": "Doe",
  "Suffix": "Mr.",
  "Email": "Thomas.Doe@example.com",
  "BirthDate": "1978-05-22",
  "HireDate": "2019-08-14",
  "Company": "",
  "ResidenceAddress": "",
  "ResidenceCity": "San Jose",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "13308 Midland Road, Poway",
  "WorkCity": "Poway",
  "WorkState": "CA",
  "WorkPostalCode": "",
  "WorkCountry": "USA",
  "ReHire": ""
  }
]}