Dayforce HCM (Vorschau)

Dieser Connector ist in den folgenden Produkten und Regionen verfügbar:

Service	Klasse	Regions
Copilot Studio	Premium	Alle Power Automate-Regionen mit Ausnahme der folgenden Bereiche:      - US Government (GCC)      - US Government (GCC High)      - China Cloud betrieben von 21Vianet      - US Department of Defense (DoD)
Logik-Apps	Standard	Alle Logik-Apps-Regionen mit Ausnahme der folgenden Bereiche:      – Azure Government-Regionen      - Azure China-Regionen      - US Department of Defense (DoD)
Power Apps	Premium	Alle Power Apps-Regionen mit Ausnahme der folgenden:      - US Government (GCC)      - US Government (GCC High)      - China Cloud betrieben von 21Vianet      - US Department of Defense (DoD)
Power Automate	Premium	Alle Power Automate-Regionen mit Ausnahme der folgenden Bereiche:      - US Government (GCC)      - US Government (GCC High)      - China Cloud betrieben von 21Vianet      - US Department of Defense (DoD)

Kontakt
Name	Dayforce Support
URL	https://www.dayforce.com/resources/help-center#support-for-employers
E‑Mail	MicrosoftPartnership@dayforce.com

Connectormetadaten
Herausgeber	Dayforce AI
Website	https://www.dayforce.com/
Datenschutzrichtlinie	https://www.dayforce.com/privacy
Kategorien	AI; Personalwesen

Dayforce HCM

Dayforce HCM ist eine Humankapital-Management-Plattform.
Dieser Connector macht einen Dayforce-API-Vorgang verfügbar, mit dem Sie die persönlichen Informationen (Name, Adressen und Kontaktdetails) eines Mitarbeiters anhand seines externen Referenzcodes (XRefCode) abrufen können. Sie können diese Daten als Tool in Copilot Studio AI-Agents sowie in anderen Power Platform-Szenarien verwenden.

Herausgeber: Dayforce

---

Voraussetzungen

Um diesen Connector zu verwenden, benötigen Sie Folgendes:

• Eine Microsoft Power Platform-Umgebung (z. B. zum Verwenden des Connectors in Copilot Studio).
• Eine aktive Dayforce HCM-Umgebung (QA, UAT oder Produktion).
• Ein Dayforce-API-Benutzer (Dienstkonto) mit der Berechtigung zum Lesen persönlicher Informationen von Mitarbeitern.
• Der Clientnamespace für Ihre Dayforce-Umgebung.
  • Dieser Wert wird als Namespacesegment in Ihren Dayforce-API-URLs angezeigt, z. B.:
    https://{environmentHost}/{clientNamespace}/V1/...

---

Unterstützte Vorgänge

Der Connector macht derzeit den folgenden Vorgang verfügbar.

Persönliche Mitarbeiterinformationen abrufen

Vorgangs-ID:Get_Employee_Personal_Info
Methode:GET

Ruft eine gefilterte, vereinfachte Ansicht persönlicher Informationen für einen einzelnen Mitarbeiter basierend auf ihrem XRefCode ab.

Anforderung

• Path-Parameter
  • xRefCode (Zeichenfolge, erforderlich)
    Der externe Referenzcode des abzurufenden Mitarbeiters. Der Wert muss exakt mit dem XRefCode eines vorhandenen Mitarbeiters übereinstimmen. andernfalls gibt der Dienst eine 400 Ungültige Anforderung zurück.

Intern leitet der Connector den Aufruf an den Dayforce Employees-Endpunkt für Ihren Clientnamespace weiter und erweitert relevante persönliche Informationen, die dann vom Skript des Connectors in ein optimiertes JSON-Objekt umgewandelt werden.

Antwort

Bei Erfolg (HTTP 200) gibt der Connector nicht die vollständige Dayforce-Mitarbeiternutzlast zurück.
Stattdessen wird ein transformiertes Objekt mit dieser Struktur zurückgegeben:

{
  "firstName": "string",
  "lastName": "string",
  "addresses": [
    {
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "city": "string",
      "postalCode": "string",
      "country": "string",
      "state": "string",
      "contactInformationType": "string"
    }
  ],
  "contacts": [
    {
      "personContactId": 0,
      "contactInformationType": "string",
      "electronicAddress": "string",
      "contactNumber": "string",
      "country": "string",
      "effectiveStart": "2024-01-01T00:00:00Z"
    }
  ]
}

Dies gilt insbesondere in folgenden Fällen:

• Felder auf oberster Ebene

  • firstName – Vorname des Mitarbeiters.
  • lastName – Nachname des Mitarbeiters.
  • addresses – Eine Liste gefilterter Adresseinträge.
  • contacts – Eine Liste gefilterter Kontakteinträge.

• Address-Objekt (addresses[])

  • address1 – Primäre Adresszeile.
  • address2 – Sekundäre Adresszeile.
  • address3 – Zusätzliche Adresszeile.
  • city – Ortsname.
  • postalCode – Postleitzahl oder PLZ.
  • country – Name des Landes (zugeordnet aus dem Dayforce Country-Namen).
  • state – Name des Staates oder der Provinz (zugeordnet aus dem Namen des Dayforce-Staates).
  • contactInformationType – Kurzname, der den Typ der Adresse beschreibt (z. B. "Home", "Mailing"), basierend auf dem Dayforce-Kontaktinformationstyp.

• Contact-Objekt (contacts[])

  • personContactId – Interner numerischer Bezeichner für den Kontaktdatensatz.
  • contactInformationType – Kurzname, der den Typ des Kontakts beschreibt (z. B. "Mobil", "Privattelefon", "Geschäftliche E-Mail").
  • electronicAddress – Für Kontakte im Format "Onlineprofil" (z. B. E-Mail oder andere elektronische Adressen).
  • contactNumber – Für Kontakte im Telefonstil (z. B. Mobil- oder Festnetznummern).
  • country – Dem Kontakt zugeordneter Länderwert (sofern zutreffend).
  • effectiveStart – Effektives Startdatum dieser Kontaktinformationen (sofern verfügbar).

Hinweis: Das Skript des Connectors filtert absichtlich die unformatierte Dayforce-Nutzlast.
Nur die oben gezeigten Felder sind für Aufrufer dieses Vorgangs verfügbar.

Bei Fehler gibt die API Folgendes zurück:

• 400 Ungültige Anforderung – Für falsch formatierte Anforderungen oder ungültig xRefCode.
• 500 Interner Serverfehler – Bei unerwarteten serverseitigen Fehlern.

Fehlerantworten umfassen Diagnoseinformationen aus der zugrunde liegenden Dayforce-API.

---

Abrufen von Anmeldeinformationen

Dieser Connector verwendet die Standardauthentifizierung , um eine Verbindung mit der Dayforce-API herzustellen.

So rufen Sie die erforderlichen Anmeldeinformationen ab:

1. Erstellen oder Identifizieren eines API-Benutzers in Dayforce

   • Arbeiten Sie mit Ihrem Dayforce-Administrator oder Implementierungsteam zusammen.
   • Stellen Sie sicher, dass der API-Benutzer Lesezugriff auf persönliche Informationen für Mitarbeiter für Ihre Umgebung hat.

2. Sammeln der folgenden Werte

   • Benutzername – Der Dayforce-API-Benutzername.
   • Kennwort – Das Dayforce-API-Kennwort.
   • Clientnamespace – Der Namespacewert, der in Ihren Dayforce-API-URLs verwendet wird.
     • Dies ist häufig ein kurzer Bezeichner für Ihre Organisation oder Umgebung, z. B. das Segment, das in URLs angezeigt wird, z. B.:
       https://{environmentHost}/{clientNamespace}/V1/Employees/....

3. Verwenden Sie diese Werte beim Erstellen einer Verbinderverbindung.

   • Im Dialogfeld "Power Platform-Verbindung" folgendes:
     • Geben Sie den Benutzernamen und das Kennwort für den Dayforce-API-Benutzer ein.
     • Geben Sie Ihren Dayforce-Clientnamespace in das Feld "Clientnamespace" ein.
   • Der Connector verwendet diese Werte, um Anforderungen an den richtigen Dayforce-Mandanten weiterzuleiten und den Anruf zu authentifizieren.

Wenn Sie sich nicht sicher sind, ob Sie ihre Clientnamespace- oder API-Benutzerdetails kennen, wenden Sie sich an den Dayforce-Support oder Ihren internen Dayforce-Administrator.

---

Erste Schritte

Die empfohlene Methode zum Testen und Verwenden dieses Connectors besteht darin, ihn als Tool in einem Copilot Studio AI-Agent hinzuzufügen.

1. Erstellen einer Verbindung

Stellen Sie vor der Verwendung des Connectors in Copilot Studio sicher, dass eine Verbindung vorhanden ist:

1. Wechseln Sie im Power Platform-Administrator oder -Hersteller zu "Datenverbindungen>".
2. Wählen Sie + Neue Verbindung aus.
3. Suchen Sie nach Ihrem Dayforce HCM-Connector (diesem Connector).
4. Wenn Sie dazu aufgefordert werden, geben Sie Folgendes an:
   • Benutzername – Dayforce-API-Benutzername.
   • Kennwort – Dayforce-API-Benutzerkennwort.
   • Clientnamespace – Ihr Dayforce-Clientnamespace .
5. Speichern Sie die Verbindung.

2. Erstellen Sie einen KI-Agent in Copilot Studio, und fügen Sie den Connector als Tool hinzu.

1. Öffnen Sie Copilot Studio.
2. Erstellen Sie einen neuen KI-Agent (oder öffnen Sie einen vorhandenen Agent, in dem Sie Dayforce-Daten verwenden möchten).
3. Wechseln Sie zum Abschnitt Tools/Plugins (oder Connectors) des Agents.
4. Fügen Sie Ihren Dayforce HCM-Connector als Tool hinzu.
5. Stellen Sie sicher, dass der Verbinder die zuvor erstellte Verbindung verwendet.

3. Rufen Sie den Connector vom KI-Agent auf

1. In Ihrer KI-Agent-Erstellungserfahrung:
   • Erstellen oder bearbeiten Sie ein Thema, eine Aktion oder einen Plug-In-Anruf , in dem der Agent Mitarbeiterinformationen abrufen soll.
2. Konfigurieren Sie einen Toolaufruf, der den Vorgang " Persönliche Informationen abrufen" verwendet:
   • Ordnen Sie benutzereingaben (z. B. "Mitarbeitercode") dem xRefCode Parameter zu.
3. Verwenden Sie die zurückgegebenen Felder:
   • firstName und lastName kann in den Antworten des KI-Agents verwendet werden (z. B. "Hier ist die Adresse und Kontaktinformationen für John Smith.").
   • Verwenden addresses Sie und contacts in der Agentlogik, um die Adresse und die Kontaktdaten des Mitarbeiters anzuzeigen oder zu begründen.

Mit diesem Setup kann Ihr KI-Agent den Dayforce HCM-Connector sicher als Tool aufrufen, nur die gefilterten Felder abrufen und diese Ergebnisse in Antworten oder Entscheidungsfindung integrieren.

---

Bekannte Probleme und Einschränkungen

• Nur Einzelmitarbeiter-Nachschlagevorgang
  Der Vorgang ruft Daten für einen Mitarbeiter gleichzeitig basierend auf dem XRefCode ab. Massenabfragen oder Suchvorgänge nach anderen Attributen (z. B. Name oder E-Mail) werden von dieser Connectordefinition nicht unterstützt.

• Genaue XRefCode-Übereinstimmung erforderlich
  Der xRefCode Parameter muss exakt mit dem externen Referenzcode eines vorhandenen Mitarbeiters übereinstimmen. Wenn der Wert ungültig ist oder nicht vorhanden ist, gibt der Dienst eine Antwort vom Typ 400 Ungültige Anforderung zurück.

• Schreibgeschützte Vorgänge
  Diese Version des Connectors ist schreibgeschützt. Es wird nicht unterstützt, Mitarbeiterinformationen zu erstellen, zu aktualisieren oder zu löschen.

• Umgebungsspezifische Konfiguration
  Die API-Definition und Routingrichtlinie erwarten eine gültige Dayforce-Umgebung und einen Clientnamespace. Wenn diese nicht mit Ihrer tatsächlichen Dayforce-Umgebungskonfiguration übereinstimmen, treten Anrufe mit Verbindungs- oder Routingfehlern auf.

• Gefilterte Nutzlast
  Die zugrunde liegende Dayforce-API gibt viele weitere Felder zurück, als hier verfügbar gemacht werden. Das Skript des Connectors filtert und gestaltet diese Daten absichtlich in firstName, lastName, , addresses[]und contacts[] nur neu.

• Die Datensicht hängt von der Dayforce-Konfiguration ab.
  Die Felder und Werte, die für einen Mitarbeiter zurückgegeben werden, hängen davon ab, wie Ihre Dayforce-Umgebung konfiguriert ist (Rollen, Sicherheit und welche Datenelemente aktiviert oder ausgefüllt sind).

---

Häufig gestellte Fragen

F1: Wofür wird das Feld "Clientnamespace" verwendet?
Der Clientnamespace identifiziert Ihren Dayforce-Mandanten innerhalb der Dayforce-API-URL. Der Connector verwendet ihn, um Anforderungen an den richtigen Kundennamespace weiterzuleiten, z. B.:
https://{environmentHost}/{clientNamespace}/V1/Employees/{xRefCode}
Wenn Sie diesen Wert nicht kennen, wenden Sie sich an Ihren Dayforce-Administrator oder das Implementierungsteam.

F2: Was geschieht, wenn ich eine ungültige xRefCodeAngabe gebe?
Wenn der xRefCode Mitarbeiter nicht mit einem vorhandenen Mitarbeiter übereinstimmt, gibt der Dienst eine Antwort vom Typ 400 Ungültige Anforderung zurück. Der zugrunde liegende Dayforce-API-Fehler wird über den Connector angezeigt.

F3: Kann ich mehrere Mitarbeiter in einem Anruf abrufen?
Nicht mit dieser Connectordefinition. Der aktuelle Vorgang ruft die persönlichen Informationen eines einzelnen Mitarbeiters pro Anruf basierend auf dem bereitgestellten xRefCodeAbruf ab.

---

Bereitstellungsanweisungen (CLI – paconn)

Sie können diesen Connector mithilfe der Power Platform Connectors CLI (paconn)als benutzerdefinierten Connector bereitstellen.

1. Vorbereiten von Verbinderartefakten

Stellen Sie sicher, ./dayforce-hcm-connectordass Sie über die folgenden Dateien in einem lokalen Ordner verfügen (z. B. ):

• apiDefinition.swagger.json
• apiProperties.json
• script.csx

Diese sollten mit der Struktur übereinstimmen, die vom benutzerdefinierten Power Platform-Connectorframework erwartet wird.

2. Installieren und Konfigurieren der CLI

1. Installieren Sie die Power Platform Connectors CLI (paconn), falls noch nicht geschehen.
2. Melden Sie sich gemäß der Dokumentation von Microsoft bei Ihrer Zielumgebung/Ihrem Mandanten an paconn (z. B. unter Verwendung paconn login).

3. Erstellen des Verbinders

Führen Sie einen Befehl wie die folgenden aus:

paconn create   --api-def apiDefinition.swagger.json   --api-prop apiProperties.json --icon icon.png   --script script.csx

• Stellen Sie sicher, dass Sie diesen Befehl im Ordner ausführen, der die Connectordateien enthält, oder stellen Sie vollständige Pfade zu jeder Datei bereit.
• Nach der Erstellung wird der Connector als benutzerdefinierter Connector in Ihrer Zielumgebung angezeigt.

4. Aktualisieren des Connectors (falls erforderlich)

Wenn Sie später Änderungen an apiDefinition.swagger.json, apiProperties.jsonoder script.csx, können Sie den vorhandenen Connector aktualisieren mit:

paconn update   --api-def apiDefinition.swagger.json   --api-prop apiProperties.json   --script script.csx   --connector-id <your-connector-id>

Ersetzen Sie durch <your-connector-id> die ID des erstellten Connectors.

5. Erstellen Sie eine Verbindung, und verwenden Sie sie in Copilot Studio

Sobald der Connector bereitgestellt wurde:

1. Wechseln Sie zu Data>Connections , und erstellen Sie eine neue Verbindung für den Dayforce HCM-Connector mit Ihren Dayforce-Anmeldeinformationen und dem Clientnamespace.
2. Fügen Sie in Copilot Studio diesen Connector als Tool zu Ihrem KI-Agent hinzu, und rufen Sie den Vorgang " Mitarbeiterdaten abrufen" auf, wie im Abschnitt "Erste Schritte " beschrieben.

6. Sicherheits- und Verbindungsfreigabe

Wir beabsichtigen, dass dieser Connector einem nicht gemeinsam nutzbaren Verbindungsmodell folgt: Wenn ein Power App- oder Copilot Studio-Agent, der diesen Connector verwendet, freigegeben wird, wird nur die Connectordefinition freigegeben, und jeder einzelne Benutzer muss explizit eine eigene Dayforce-Verbindung mit ihren eigenen Anmeldeinformationen bei der ersten Verwendung erstellen. Der Connector darf die Freigabe von Verbindungen nicht zulassen, sodass die Dayforce-Berechtigungen eines Benutzers von einem anderen wiederverwendet werden können (d. h. kein Szenario, in dem eine App oder ein Agent unter der Dayforce-Identität des App- oder Verbindungsbesitzers ausgeführt wird). Stellen Sie als Teil der Zertifizierung sicher, dass alle Authentifizierungstypen für diesen Connector als nicht freigegeben konfiguriert sind, sodass die Verbindungsfreigabe auf Plattformebene blockiert wird und jeder Benutzer immer eine eigene Dayforce-Verbindung herstellen muss.

Schließen Sie diesen Haftungsausschluss ein: Dies ist keine freigabefähige Verbindung. Wenn die Power-App für einen anderen Benutzer freigegeben wird, wird ein anderer Benutzer aufgefordert, eine neue Verbindung explizit zu erstellen.

Nach der Zertifizierung und Veröffentlichung von Microsoft ist der Dayforce HCM-Connector als zertifizierter Connector verfügbar, und Normalerweise müssen Sie nur eine Verbindung erstellen (keine CLI-Bereitstellung für Endbenutzer erforderlich).

Eine Verbindung wird erstellt

Der Connector unterstützt die folgenden Authentifizierungstypen:

Vorgabe	Parameter zum Erstellen einer Verbindung.	Alle Regionen	Nicht teilbar

Vorgabe

Anwendbar: Alle Regionen

Parameter zum Erstellen einer Verbindung.

Dies ist keine freigabefähige Verbindung. Wenn die Power-App für einen anderen Benutzer freigegeben wird, wird ein anderer Benutzer aufgefordert, eine neue Verbindung explizit zu erstellen.

Name	Typ	Beschreibung	Erforderlich
username	securestring	Der Benutzername für diese API	Richtig
Passwort	securestring	Das Kennwort für diese API	Richtig
Authentifizierungstyp	Schnur	Authentifizierungstyp zum Herstellen einer Verbindung mit Ihrer API	Richtig
Clientnamespace	Schnur	Clientnamespace	Richtig

Drosselungsgrenzwerte

Name	Aufrufe	Verlängerungszeitraum
API-Aufrufe pro Verbindung	100	60 Sekunden

Aktionen

Persönliche Mitarbeiterinformationen abrufen

Dieser Vorgang ruft Daten im Zusammenhang mit einem Mitarbeiter und seinen persönlichen Informationen (z. B. Name, Adressen und Kontakte) von XRef Code ab.

Persönliche Mitarbeiterinformationen abrufen

Definitionen

ProcessResult

Mitarbeiter

PersonContactCollection

PersonAddressCollection

PersonContact

PersonAddress

Staat

ContactInformationType

State

ContactInformationTypeGroup

Payload_Employee