Dayforce HCM (preview)

Deze connector is beschikbaar in de volgende producten en regio's:

Dienst	klasse	Regions
Copilot Studio	Premium	Alle Power Automate-regio's , met uitzondering van het volgende:      - Amerikaanse overheid (GCC)      - Amerikaanse overheid (GCC High)      - China Cloud beheerd door 21Vianet      - Us Department of Defense (DoD)
Logic-apps	Standard	Alle Logic Apps-regio's , met uitzondering van het volgende:      - Azure Government-regio's      - Azure China-regio's      - Us Department of Defense (DoD)
Power Apps	Premium	Alle Power Apps-regio's , met uitzondering van het volgende:      - Amerikaanse overheid (GCC)      - Amerikaanse overheid (GCC High)      - China Cloud beheerd door 21Vianet      - Us Department of Defense (DoD)
Power Automate	Premium	Alle Power Automate-regio's , met uitzondering van het volgende:      - Amerikaanse overheid (GCC)      - Amerikaanse overheid (GCC High)      - China Cloud beheerd door 21Vianet      - Us Department of Defense (DoD)

contact opnemen met
Naam	Ondersteuning voor Dayforce
URL	https://www.dayforce.com/resources/help-center#support-for-employers
E-mailadres	MicrosoftPartnership@dayforce.com

Connectormetagegevens
Publisher	Dayforce AI
Website	https://www.dayforce.com/
Privacybeleid	https://www.dayforce.com/privacy
Categorieën	AI; Human Resources

Dayforce HCM

Dayforce HCM is een human capital management platform.
Met deze connector wordt een Dayforce API-bewerking weergegeven waarmee u de persoonlijke gegevens van een werknemer (naam, adressen en contactgegevens) kunt ophalen met behulp van hun externe referentiecode (XRefCode). U kunt deze gegevens gebruiken als hulpprogramma in Copilot Studio AI-agents, evenals in andere Power Platform-scenario's.

Uitgever: Dayforce

---

Vereiste voorwaarden

Als u deze connector wilt gebruiken, hebt u het volgende nodig:

• Een Microsoft Power Platform-omgeving (bijvoorbeeld om de connector in Copilot Studio te gebruiken).
• Een actieve Dayforce HCM-omgeving (QA, UAT of Productie).
• Een Dayforce API-gebruiker (serviceaccount) met toestemming om persoonlijke gegevens van werknemers te lezen.
• De API-URL voor uw Dayforce-omgeving, inclusief de clientnaamruimte.
  • Dit is de basis-URL die wordt gebruikt om de Dayforce-API voor uw tenant aan te roepen, bijvoorbeeld:
    https://{environmentHost}/{basePath}/api/{clientNamespace}
  • De exacte indeling is afhankelijk van de configuratie van uw Dayforce-omgeving. Neem contact op met uw Dayforce-beheerder als u niet zeker bent van de URL.

---

Ondersteunde bewerkingen

De connector maakt momenteel de volgende bewerking beschikbaar.

Persoonlijke gegevens van werknemers ophalen

Bewerkings-id:Get_Employee_Personal_Info
Methode:GET

Haalt een gefilterde, vereenvoudigde weergave van persoonlijke gegevens op voor één werknemer op basis van hun XRefCode.

Verzoek

• Padparameter
  • xRefCode (tekenreeks, vereist)
    De externe referentiecode van de werknemer die moet worden opgehaald. De waarde moet exact overeenkomen met de XRefCode van een bestaande werknemer; anders retourneert de service een 400 ongeldige aanvraag.

Intern stuurt de connector de aanroep naar het Dayforce Employees-eindpunt met behulp van de API-URL die is opgegeven tijdens het maken van de verbinding en breidt relevante persoonlijke gegevens uit, die vervolgens wordt getransformeerd door het script van de connector in een gestroomlijnd JSON-object.

Antwoord

Bij succes (HTTP 200) retourneert de connector niet de volledige nettolading van de Dayforce-werknemer.
In plaats daarvan retourneert het een getransformeerd object met deze structuur:

{
  "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"
    }
  ]
}

Specifieke opdrachten:

• velden op het hoogste niveau

  • firstName – Voornaam van werknemer.
  • lastName – Achternaam van werknemer.
  • addresses – Een lijst met gefilterde adresvermeldingen.
  • contacts – Een lijst met gefilterde vermeldingen van contactpersonen.

• Adresobject (addresses[])

  • address1 – Primaire adresregel.
  • address2 – Secundaire adresregel.
  • address3 – Extra adresregel.
  • city – Plaatsnaam.
  • postalCode – Postcode.
  • country – Landnaam (toegewezen uit de Dayforce Country-naam).
  • state – De naam van de staat of provincie (toegewezen uit de naam van de Dayforce-staat).
  • contactInformationType – Korte naam die het type adres beschrijft (bijvoorbeeld "Home", "Mailing"), op basis van het type contactgegevens van Dayforce.

• Contactobject (contacts[])

  • personContactId – Interne numerieke id voor de contactpersoonrecord.
  • contactInformationType – Korte naam die het type contactpersoon beschrijft (bijvoorbeeld 'Mobiel', 'Telefoon thuis', 'Zakelijke e-mail').
  • electronicAddress – Voor contactpersonen in de stijl 'onlineprofiel' (zoals e-mail of andere elektronische adressen).
  • contactNumber – Voor contactpersonen in telefoonstijl (bijvoorbeeld mobiele of vaste nummers).
  • country – Landwaarde gekoppeld aan de contactpersoon (indien van toepassing).
  • effectiveStart – Ingangsdatum van deze contactgegevens (indien beschikbaar).

Opmerking: het script van de connector filtert opzettelijk de onbewerkte Dayforce-nettolading.
Alleen de velden die hierboven worden weergegeven, worden weergegeven voor bellers van deze bewerking.

Bij een fout retourneert de API het volgende:

• 400 Ongeldige aanvraag : voor ongeldige aanvragen of ongeldig xRefCode.
• 500 Interne serverfout : voor onverwachte fouten aan de serverzijde.

Foutreacties bevatten diagnostische gegevens van de onderliggende Dayforce-API.

---

Referenties verkrijgen

Deze connector maakt gebruik van basisverificatie om verbinding te maken met de Dayforce-API.

De vereiste referenties verkrijgen:

1. Een API-gebruiker maken of identificeren in Dayforce

   • Werk samen met uw Dayforce-beheerder of implementatieteam.
   • Zorg ervoor dat de API-gebruiker leestoegang heeft tot persoonlijke gegevens van werknemers voor uw omgeving.

2. De volgende waarden verzamelen

   • API-URL : de basis-API-URL voor uw Dayforce-tenant, inclusief de clientnaamruimte. Dit is de URL die de connector gebruikt om aanvragen naar uw Dayforce-omgeving te routeren. Neem geen afsluitende slash op.

     • Voorbeeld:https://{environmentHost}/{basePath}/api/{clientNamespace}

     Belangrijk: Sommige Dayforce-omgevingen gebruiken een universele URL (bijvoorbeeld https://dayforcehcm.com/api/{clientNamespace}) die automatisch wordt omgeleid naar een omgevingsspecifieke URL (bijvoorbeeld https://us252-services.dayforcehcm.com/api/{clientNamespace}). Gebruik bij het configureren van de connector altijd de uiteindelijke, opgeloste URL in plaats van de universele URL. U kunt de uiteindelijke URL bepalen door naar de Swagger-documentatiepagina voor uw omgeving te navigeren (bijvoorbeeld https://dayforcehcm.com/api/{clientNamespace}/swagger/index.html) en de URL te noteren waarnaar uw browser wordt omgeleid.

   • Gebruikersnaam : de dayforce-API-gebruikersnaam.

   • Wachtwoord: het Dayforce API-wachtwoord.

3. Gebruik deze waarden bij het maken van een connectorverbinding

   • In het dialoogvenster Power Platform-verbinding:
     • Voer de API-URL in voor uw Dayforce-omgeving.
     • Voer de gebruikersnaam en het wachtwoord in voor de Dayforce API-gebruiker.
   • De connector gebruikt de API-URL om aanvragen te routeren naar de juiste Dayforce-tenant en de referenties om de aanroep te verifiëren.

Als u niet zeker weet wat uw API-URL of API-gebruikersgegevens zijn, neemt u contact op met de ondersteuning van Dayforce of uw interne Dayforce-beheerder.

---

Aan de slag komen

De aanbevolen manier om deze connector te testen en te gebruiken, is door deze toe te voegen als een hulpprogramma in een Copilot Studio AI-agent.

1. Een verbinding maken

Voordat u de connector in Copilot Studio gebruikt, moet u controleren of er een verbinding bestaat:

1. Ga in de Power Platform-beheerder of maker-ervaring naar Gegevensverbindingen>.
2. Selecteer + Nieuwe verbinding.
3. Zoek uw Dayforce HCM-connector (deze connector).
4. Geef het volgende op wanneer u hierom wordt gevraagd:
   • API-URL : de basis-API-URL voor uw Dayforce-tenant (inclusief de clientnaamruimte). Neem geen afsluitende slash op.
   • Gebruikersnaam – Dayforce API-gebruikersnaam.
   • Wachtwoord : Dayforce API-gebruikerswachtwoord.
5. Sla de verbinding op.

2. Maak een AI-agent in Copilot Studio en voeg de connector toe als een hulpprogramma

1. Open Copilot Studio.
2. Maak een nieuwe AI-agent (of open een bestaande agent waar u Dayforce-gegevens wilt gebruiken).
3. Ga naar de sectie Extra/Plugins (of Connectors) van de agent.
4. Voeg uw Dayforce HCM-connector toe als een hulpprogramma.
5. Zorg ervoor dat de connector gebruikmaakt van de verbinding die u eerder hebt gemaakt.

3. Roep de connector aan vanuit de AI-agent

1. In de ontwerpervaring van uw AI-agent:
   • Een onderwerp, actie of invoegtoepassingsoproep maken of bewerken waar u wilt dat de agent werknemersgegevens ophaalt.
2. Configureer een aanroep van een hulpprogramma dat gebruikmaakt van de bewerking Persoonlijke gegevens van werknemers ophalen :
   • Wijs gebruikersinvoer (bijvoorbeeld 'werknemerscode') toe aan de xRefCode parameter.
3. Gebruik de geretourneerde velden:
   • firstName en lastName kan worden gebruikt in de antwoorden van de AI-agent (bijvoorbeeld 'Hier is het adres en de contactgegevens voor John Smith.'
   • Gebruik addresses en contacts in de agentlogica om het adres en de contactgegevens van de werknemer weer te geven of te redeneren.

Met deze instelling kan uw AI-agent de Dayforce HCM-connector veilig aanroepen als een hulpprogramma, alleen de gefilterde velden ophalen en deze resultaten opnemen in reacties of besluitvorming.

---

Bekende problemen en beperkingen

• Alleen zoeken met één werknemer
  Met de bewerking worden gegevens opgehaald voor één werknemer tegelijk, op basis van de XRefCode. Bulkquery's of zoekopdrachten op andere kenmerken (zoals naam of e-mail) worden niet ondersteund door deze connectordefinitie.

• Exacte XRefCode-overeenkomst vereist
  De xRefCode parameter moet exact overeenkomen met de externe referentiecode van een bestaande werknemer. Als de waarde ongeldig is of niet bestaat, retourneert de service een antwoord van 400 ongeldige aanvragen.

• Alleen-lezenbewerkingen
  Deze versie van de connector heeft het kenmerk Alleen-lezen. Het biedt geen ondersteuning voor het maken, bijwerken of verwijderen van werknemersgegevens.

• Omgevingsspecifieke configuratie
  Voor de connector is een geldige Dayforce-API-URL vereist (opgegeven tijdens het maken van de verbinding). Als de URL niet overeenkomt met de werkelijke configuratie van uw Dayforce-omgeving, mislukken aanroepen met verbindings- of routeringsfouten. Neem geen afsluitende slash op in de API-URL.

• Gefilterde nettolading
  De onderliggende Dayforce-API retourneert veel meer velden dan hier wordt weergegeven. Het script van de connector filtert en hervormt deze gegevens alleen infirstName, lastNameaddresses[]en contacts[] alleen.

• De zichtbaarheid van gegevens is afhankelijk van de Dayforce-configuratie
  De velden en waarden die voor een werknemer worden geretourneerd, zijn afhankelijk van hoe uw Dayforce-omgeving is geconfigureerd (rollen, beveiliging en welke gegevenselementen zijn ingeschakeld of ingevuld).

---

Veelgestelde vragen

V1: Waarvoor wordt het veld API-URL gebruikt?
De API-URL is de basis-URL voor uw Dayforce-tenant, inclusief de clientnaamruimte. De connector gebruikt deze om alle API-aanvragen naar de juiste Dayforce-omgeving te routeren. De URL mag geen afsluitende slash bevatten.
Als u deze waarde niet weet, neemt u contact op met uw Dayforce-beheerder of implementatieteam.

V2: Wat gebeurt er als ik een ongeldige xRefCodeopgeeft?
Als deze xRefCode niet overeenkomt met een bestaande werknemer, retourneert de service een 400 ongeldige aanvraagreactie. De onderliggende Dayforce API-fout wordt weergegeven via de connector.

V3: Kan ik meerdere werknemers in één gesprek ophalen?
Niet met deze connectordefinitie. Met de huidige bewerking worden de persoonlijke gegevens van één werknemer per gesprek opgehaald, op basis van de opgegeven xRefCode.

---

Implementatie-instructies (CLI – paconn)

U kunt deze connector implementeren als een aangepaste connector met behulp van de CLI van Power Platform Connectors (paconn).

1. Connectorartefacten voorbereiden

Zorg ervoor dat u de volgende bestanden in een lokale map hebt (bijvoorbeeld ./dayforce-hcm-connector):

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

Deze moeten overeenkomen met de structuur die wordt verwacht door het framework voor aangepaste Power Platform-connectors.

2. De CLI installeren en configureren

1. Installeer de CLI van Power Platform-connectors (paconn) als u dit nog niet hebt gedaan.
2. Meld u aan bij uw doelomgeving/tenant met behulp van paconn de documentatie van Microsoft (bijvoorbeeld met behulp van paconn login).

3. De connector maken

Voer een opdracht uit die vergelijkbaar is met:

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

• Zorg ervoor dat u deze opdracht uitvoert in de map met de connectorbestanden of dat u volledige paden naar elk bestand opgeeft.
• Na het maken wordt de connector weergegeven als een aangepaste connector in uw doelomgeving.

4. Werk de connector bij (indien nodig)

Als u later wijzigingen aanbrengt in apiDefinition.swagger.json, apiProperties.jsonof script.csx, kunt u de bestaande connector bijwerken met:

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

Vervang door <your-connector-id> de id van de connector die is gemaakt.

5. Maak een verbinding en gebruik deze in Copilot Studio

Zodra de connector is geïmplementeerd:

1. Ga naar Gegevensverbindingen> en maak een nieuwe verbinding voor de Dayforce HCM-connector met behulp van de URL en referenties van de Dayforce-API.
2. Voeg in Copilot Studio deze connector toe als een hulpprogramma aan uw AI-agent en roep de bewerking Persoonlijke gegevens van werknemers ophalen aan, zoals beschreven in de sectie Aan de slag .

6. Beveiliging en delen van verbindingen

Deze connector maakt gebruik van een niet-deelbaar verbindingsmodel. Wanneer u een Power App of Copilot Studio-agent deelt die gebruikmaakt van deze connector, moet alleen de connector definition gedeeld. each-gebruiker moet voor het eerst een eigen Dayforce-verbinding maken met hun eigen referenties. Verbindingen kunnen niet worden gedeeld op een manier waarmee de Machtigingen van de ene gebruiker dayforce door een andere gebruiker opnieuw kunnen worden gebruikt. Alle verificatietypen zijn geconfigureerd als Niet deelbaar, dus het delen van verbindingen wordt geblokkeerd op platformniveau en elke gebruiker is altijd vereist om een eigen Dayforce-verbinding tot stand te brengen.

Een verbinding maken

De connector ondersteunt de volgende verificatietypen:

standaard	Parameters voor het maken van verbinding.	Alle regio's	Niet deelbaar

Verstek

Van toepassing: Alle regio's

Parameters voor het maken van verbinding.

Dit is geen deelbare verbinding. Als de power-app wordt gedeeld met een andere gebruiker, wordt een andere gebruiker gevraagd om expliciet een nieuwe verbinding te maken.

Naam	Typ	Beschrijving	Verplicht
username	beveiligde string	De gebruikersnaam voor deze API	Klopt
password	beveiligde string	Het wachtwoord voor deze API	Klopt
Verificatietype	tekenreeks	Verificatietype om verbinding te maken met uw API	Klopt
Clientnaamruimte	tekenreeks	clientnaamruimte	Klopt

Beperkingslimieten

Name	Aanroepen	Verlengingsperiode
API-aanroepen per verbinding	100	60 seconden

Acties

Persoonlijke gegevens van werknemers ophalen

Met deze bewerking worden gegevens opgehaald die betrekking hebben op een werknemer en zijn/haar persoonlijke gegevens (bijvoorbeeld naam, adressen en contactpersonen) door XRef Code

Persoonlijke gegevens van werknemers ophalen

Definities

ProcessResult

Werknemer

PersonContactCollection

PersonAddressCollection

PersonContact

PersonAddress

Land

ContactInformationType

State

ContactInformationTypeGroup

Payload_Employee