HR-REST-API

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 4 Minuten Lesedauer

    • Die HR-REST -API stellt Endpunkte bereit, die Informationen über Mitarbeiter 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 „Human Resources Scoped App: Core“ (com_sn_hr_core) aktiviert sein.

    HR REST – GET /get_usa_employee_profile

    Gibt Mitarbeiterprofilinformationen für Mitarbeiter zurück, die in den USA ansässig sind.

    Die zurückgegebenen Informationen können wie folgt lauten:
    • Mitarbeiterprofilinformationen für eine angegebene Mitarbeiter-ID.
    • Informationen für Mitarbeiter, die an oder nach einem bestimmten Datum hinzugefügt wurden oder deren Informationen aktualisiert wurden.
    Hinweis:
    Mitarbeiter müssen entweder als Arbeits- oder Heimatland für diesen Endpunkt angegeben sein, um sie in die Rückgabeergebnisse einzubeziehen.
    Darüber hinaus sendet der Endpunkt die folgenden Parameter an die integrierte CIC Plus-Anwendung (Beschreibungen finden Sie im Abschnitt „Rückgaben“):
    • Mitarbeiterbezeichner
    • Vorname
    • MiddleName
    • Nachname
    • E-Mail
    • Arbeitsadresse
    • Arbeitsplatz
    • Arbeitsstatus
    • WorkPostalCode
    • WorkCountry
    • Privatadresse
    • Heimatstadt
    • Heimatstatus
    • HomePostalCode
    • HeimatLand
    • Geburtsdatum
    • Einstellungsdatum

    URL-Format

    Standard-URL: /api/sn_hr_core/hr_rest_api/get_usa_employee_profile

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    Keine
    Tabelle : 2. Abfrageparameter
    Parameter Beschreibung
    employee_identifier Eindeutiger Bezeichner eines Mitarbeiters. Das aufrufende System generiert diesen Wert und kann ein beliebiges Format annehmen, das mit seinem System konsistent ist. Um diesen Wert zu erhalten, rufen Sie zuerst den Endpunkt mit dem Parameter updated_after auf.
    Hinweis:
    Dieser Parameter und der Parameter updated_after schließen sich gegenseitig aus. Dieser Parameter definiert einen eindeutigen Mitarbeiter, während updated_after eine Gruppe von Mitarbeitern zurückgibt, die nach einem bestimmten Datum erstellt/aktualisiert wurden.

    Datentyp: Zeichenfolge
    sysparm_limit Maximale Anzahl der zurückzugebenden Datensätze. Verwenden Sie für Anforderungen, die diese Anzahl von Datensätzen überschreiten, den Parameter sysparm_offset, um den Datensatzabruf zu paginieren.

    Datentyp: Zahl

    Standard: 1000
    sysparm_offset Startdatensatzindex, für den der Datensatz abgerufen werden soll. Verwenden Sie diesen Wert, um den Datensatzabruf zu paginieren. Diese Funktion ermöglicht das Abrufen aller Datensätze in kleinen, verwaltbaren Abschnitten, unabhängig von der Anzahl der Datensätze.

    Wenn zum Beispiel dieser Endpunkt zum ersten Mal aufgerufen wird, ist sysparm_offset auf „0“ eingestellt. Verwenden Sie sysparm_offset=sysparm_offset+sysparm_limit zum einfachen Durchblättern aller verfügbaren Datensätze, bis das Ende aller Datensätze erreicht ist.
    updated_after Datum, das zur Bestimmung der zurückzugebenden Mitarbeiterdaten verwendet werden soll. Alle in den USA ansässigen Mitarbeiter (beruflich oder privat), die Ihrer Instanz hinzugefügt wurden oder deren Informationen an oder nach diesem Datum aktualisiert wurden, sind in den zurückgegebenen Ergebnissen enthalten.
    Hinweis:
    Dieser Parameter und der Parameter employee_identifier schließen sich gegenseitig aus.

    Datentyp: Zeichenfolge

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

    Kopfzeilen

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

    Tabelle : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Tabelle : 5. Antwortkopfzeilen
    Kopfzeile Beschreibung
    Nächste Seite Kennzeichnung, die angibt, ob zusätzliche Daten in einem nachfolgenden Aufruf abzurufen sind. Wenn beispielsweise insgesamt 120 Mitarbeiterdatensätze den Suchkriterien entsprechen und sysparm_limit auf 100 festgelegt ist, ist Next-Page true. Wenn keine zusätzlichen Ergebnisse verfügbar sind, ist Next-Page „ false“.
    Gültige Werte:
    • true: Zusätzliche Daten sind verfügbar, ein weiterer Aufruf muss erfolgen, um den nächsten Datenblock zu erhalten.
    • false: 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 HTTP-Antwortcodesder REST-API.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    401 Nicht autorisiert. Die Anmeldeinformationen 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. Der Antworttext enthält Informationen zum Fehler.

    Antworttextparameter (JSON oder XML)

    Element Beschreibung
    Geburtsdatum Geburtsdatum des Mitarbeiters.

    Datentyp: Zeichenfolge
    Unternehmen Unternehmensname.

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

    Datentyp: Zeichenfolge
    Mitarbeiterbezeichner Eindeutiger Bezeichner des Mitarbeiters.

    Datentyp: Zeichenfolge
    Vorname Vorname des Mitarbeiters

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

    Datentyp: Zeichenfolge
    Nachname Nachname des Mitarbeiters

    Datentyp: Zeichenfolge
    MiddleName Zweiter Vorname des Mitarbeiters.

    Datentyp: Zeichenfolge
    Erneut einstellen Zur späteren Verwendung.

    Datentyp: Zeichenfolge
    WohnsitzAdresse Privatadresse des Mitarbeiters.

    Datentyp: Zeichenfolge
    WohnortStadt Heimatort des Mitarbeiters.

    Datentyp: Zeichenfolge
    WohnsitzLand Heimatland des Mitarbeiters.

    Datentyp: Zeichenfolge
    WohnsitzPostleitzahl Privat-Postleitzahl des Mitarbeiters.

    Datentyp: Zeichenfolge
    Wohnsitzstatus Privatstatus des Mitarbeiters.

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

    Datentyp: Zeichenfolge
    Arbeitsadresse Büroadresse des Mitarbeiters.

    Datentyp: Zeichenfolge
    Arbeitsplatz Arbeitsort des Mitarbeiters

    Datentyp: Zeichenfolge
    WorkCountry Arbeitsland des Mitarbeiters.

    Datentyp: Zeichenfolge
    WorkPostalCode Arbeits-Postleitzahl 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 von Mitarbeitern, die am oder nach dem 18.05.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": ""
  }
]}