Delen via

Dayforce HCM (preview)

Maakt verbinding met de Dayforce HCM-API om persoonlijke gegevens van werknemers (contactpersonen, adressen, namen) op te halen op basis van referentiecode voor werknemers. Bedoeld voor HR-beheerders en ontwikkelaars met weinig code. Vereist een Dayforce-tenant, API-referenties (Basic Auth) en de juiste machtigingen. Alleen-lezen; ongeldige referentiecodes retourneren fouten.

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 clientnaamruimte voor uw Dayforce-omgeving.
    • Deze waarde wordt weergegeven als het naamruimtesegment in uw Dayforce API-URL's, bijvoorbeeld:
      https://{environmentHost}/{clientNamespace}/V1/...

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 voor uw clientnaamruimte 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

    • Gebruikersnaam : de dayforce-API-gebruikersnaam.
    • Wachtwoord: het Dayforce API-wachtwoord.
    • Clientnaamruimte : de naamruimtewaarde die wordt gebruikt in de URL's van de Dayforce-API.
      • Dit is vaak een korte id voor uw organisatie of omgeving, bijvoorbeeld het segment dat wordt weergegeven in URL's zoals:
        https://{environmentHost}/{clientNamespace}/V1/Employees/....

  3. Gebruik deze waarden bij het maken van een connectorverbinding

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

Als u niet zeker weet wat uw clientnaamruimte 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:
    • Gebruikersnaam – Dayforce API-gebruikersnaam.
    • Wachtwoord : Dayforce API-gebruikerswachtwoord.
    • Clientnaamruimte : uw Dayforce-clientnaamruimte.
  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
    Het API-definitie- en routeringsbeleid verwacht een geldige Dayforce-omgeving en clientnaamruimte. Als deze niet overeenkomen met uw werkelijke Dayforce-omgevingsconfiguratie, mislukken aanroepen met verbindings- of routeringsfouten.

  • 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 Clientnaamruimte gebruikt?
De clientnaamruimte identificeert uw Dayforce-tenant binnen de URL van de Dayforce-API. De connector gebruikt deze om aanvragen naar de juiste naamruimte van de klant te routeren, bijvoorbeeld:
https://{environmentHost}/{clientNamespace}/V1/Employees/{xRefCode}
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 uw Dayforce-referenties en clientnaamruimte.
  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

We zijn van plan dat deze connector een niet-deelbaar verbindingsmodel volgt: wanneer een Power App- of Copilot Studio-agent die deze connector gebruikt, wordt alleen de definitie van de connector gedeeld en moet elke afzonderlijke gebruiker expliciet een eigen Dayforce-verbinding maken met zijn eigen referenties voor het eerste gebruik. De connector mag het delen van verbindingen niet toestaan op een manier waarmee de Dayforce-machtigingen van de ene gebruiker opnieuw kunnen worden gebruikt door een andere gebruiker (dus geen scenario waarin een app of agent wordt uitgevoerd onder de Dayforce-identiteit van de eigenaar van de app of de verbindingseigenaar). Als onderdeel van certificering moet u ervoor zorgen dat alle verificatietypen voor deze connector zijn geconfigureerd als Niet deelbaar, zodat het delen van verbindingen wordt geblokkeerd op platformniveau en elke gebruiker altijd is vereist om een eigen Dayforce-verbinding tot stand te brengen.

Neem deze disclaimer op: 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.

Zodra de Dayforce HCM-connector is gecertificeerd en gepubliceerd door Microsoft, is deze beschikbaar als een gecertificeerde connector en hoeft u doorgaans alleen een verbinding te maken (er is geen CLI-implementatie vereist voor eindgebruikers).

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

Bewerkings-id:
Get_Employee_Personal_Info

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

Parameters

Name Sleutel Vereist Type Description
Referentiecode werknemer
 xRefCode True string

De unieke id (externe referentiecode) van de werknemer die moet worden opgehaald. De opgegeven waarde moet de exacte overeenkomst zijn voor een werknemer; anders wordt een fout met een ongeldige aanvraag (400) geretourneerd.

Retouren

Body
Payload_Employee

Definities

ProcessResult

Name Pad Type Description
Code
 Code string
Context
 Context string
Niveau
 Level string
Bericht
 Message string

Werknemer

Name Pad Type Description
Werknemers-ID
 EmployeeId integer
Contacten
 Contacts PersonContactCollection
Addresses
 Addresses PersonAddressCollection
GlobalPersonId
 GlobalPersonId string
XRefCode
 XRefCode string
NewXRefCode
 NewXRefCode string
AlgemeneNaam
 CommonName string
Schermnaam
 DisplayName string
FirstName
 FirstName string
Achternaam
 LastName string
Initialen
 Initials string
MaidenName
 MaidenName string
Middelste naam
 MiddleName string
Titel
 Title string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

PersonContactCollection

Name Pad Type Description
Artikelen
 Items array of PersonContact

PersonAddressCollection

Name Pad Type Description
Artikelen
 Items array of PersonAddress

PersonContact

Name Pad Type Description
PersonContactId
 PersonContactId integer
ContactInformationType
 ContactInformationType ContactInformationType
ContactNumber
 ContactNumber string
Land
 Country Country
EffectiveEnd
 EffectiveEnd date-time
EffectiveStart
 EffectiveStart date-time
ElectronicAddress
 ElectronicAddress string
Extension
 Extension string
IsForSystemCommunications
 IsForSystemCommunications boolean
IsPreferredContactMethod
 IsPreferredContactMethod boolean
IsUnlistedNumber
 IsUnlistedNumber boolean
FormattedNumber
 FormattedNumber string
IsVerified
 IsVerified boolean
IsRejected
 IsRejected boolean
ShowRejectedWarning
 ShowRejectedWarning boolean
NumberOfVerificationRequests
 NumberOfVerificationRequests integer
LastModifiedTimestamp
 LastModifiedTimestamp date-time

PersonAddress

Name Pad Type Description
PersonAddressId
 PersonAddressId integer
Adres1
 Address1 string
Adres2
 Address2 string
Adres3
 Address3 string
Adres4
 Address4 string
Adres5
 Address5 string
Adres6
 Address6 string
City
 City string
Postcode
 PostalCode string
Land
 Country Country
State
 State State
ContactInformationType
 ContactInformationType ContactInformationType
IsPayrollMailing
 IsPayrollMailing boolean
DisplayOnTaxForm
 DisplayOnTaxForm boolean
DisplayOnEarningStatement
 DisplayOnEarningStatement boolean
EffectiveStart
 EffectiveStart date-time
EffectiveEnd
 EffectiveEnd date-time
Graafschap
 County string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

Land

Name Pad Type Description
Naam
 Name string
XRefCode
 XRefCode string
KorteNaam
 ShortName string
LongName
 LongName string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

ContactInformationType

Name Pad Type Description
ContactInformationTypeGroup
 ContactInformationTypeGroup ContactInformationTypeGroup
XRefCode
 XRefCode string
KorteNaam
 ShortName string
LongName
 LongName string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

State

Name Pad Type Description
Naam
 Name string
XRefCode
 XRefCode string
KorteNaam
 ShortName string
LongName
 LongName string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

ContactInformationTypeGroup

Name Pad Type Description
XRefCode
 XRefCode string
KorteNaam
 ShortName string
LongName
 LongName string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

Payload_Employee

Name Pad Type Description
Gegevens
 Data Employee
ProcessResults
 ProcessResults array of ProcessResult