Dela via

Dayforce HCM (förhandsversion)

Ansluter till Dayforce HCM-API:et för att hämta personlig information om anställda (kontakter, adresser, namn) efter anställdas referenskod. Avsedd för HR-administratörer och utvecklare med låg kod. Kräver en Dayforce-klientorganisation, API-autentiseringsuppgifter (Grundläggande autentisering) och lämpliga behörigheter. Skrivskyddad; ogiltiga referenskoder returnerar fel.

Den här anslutningsappen är tillgänglig i följande produkter och regioner:

Service Class Regioner
Copilot Studio Premium Alla Power Automate-regioner utom följande:
     - Amerikanska myndigheter (GCC)
     - Amerikanska myndigheter (GCC High)
     – China Cloud drivs av 21Vianet
     - US Department of Defense (DoD)
Logiska appar Standard Alla Logic Apps-regioner utom följande:
     – Azure Government-regioner
     – Regioner i Azure Kina
     - US Department of Defense (DoD)
Power Apps Premium Alla Power Apps-regioner utom följande:
     - Amerikanska myndigheter (GCC)
     - Amerikanska myndigheter (GCC High)
     – China Cloud drivs av 21Vianet
     - US Department of Defense (DoD)
Power Automate Premium Alla Power Automate-regioner utom följande:
     - Amerikanska myndigheter (GCC)
     - Amerikanska myndigheter (GCC High)
     – China Cloud drivs av 21Vianet
     - US Department of Defense (DoD)
Kontakt
Namn Dayforce-support
URL https://www.dayforce.com/resources/help-center#support-for-employers
E-postmeddelande MicrosoftPartnership@dayforce.com
Metadata för anslutningsprogram
Publisher Dayforce AI
Webbplats https://www.dayforce.com/
Sekretesspolicy https://www.dayforce.com/privacy
Kategorier AI; Personal

Dayforce HCM

Dayforce HCM är en plattform för hantering av humankapital.
Den här anslutningsappen exponerar en Dayforce API-åtgärd som gör att du kan hämta en anställds personliga information (namn, adresser och kontaktuppgifter) med deras externa referenskod (XRefCode). Du kan använda dessa data som ett verktyg i Copilot Studio AI-agenter samt i andra Power Platform-scenarier.

Utgivare: Dayforce

Förutsättningar

Om du vill använda den här anslutningsappen behöver du:

  • En Microsoft Power Platform-miljö (till exempel för att använda anslutningsappen i Copilot Studio).
  • En aktiv Dayforce HCM-miljö (QA, UAT eller Produktion).
  • En Dayforce API-användare (tjänstkonto) med behörighet att läsa personalinformation för anställda.
  • Klientnamnområdet för din Dayforce-miljö.
    • Det här värdet visas som namnområdessegmentet i dina Dayforce API-URL:er, till exempel:
      https://{environmentHost}/{clientNamespace}/V1/...

Åtgärder som stöds

Anslutningsappen exponerar för närvarande följande åtgärd.

Hämta personalinformation för medarbetare

Åtgärds-ID:Get_Employee_Personal_Info
Metod:GET

Hämtar en filtrerad, förenklad vy av personlig information för en enskild anställd baserat på deras XRefCode.

Förfrågan

  • Sökvägsparameter
    • xRefCode (sträng, krävs)
      Den externa referenskoden för den medarbetare som ska hämtas. Värdet måste exakt matcha en befintlig medarbetares XRefCode. annars returnerar tjänsten en 400 felaktig begäran.

Internt dirigerar anslutningsappen anropet till Dayforce Employees-slutpunkten för klientnamnområdet och expanderar relevant personlig information, som sedan omvandlas av anslutningsappens skript till ett effektiviserat JSON-objekt.

Svar

Vid lyckat resultat (HTTP 200) returnerar anslutningsappen inte hela Dayforce-medarbetarens nyttolast.
I stället returneras ett transformerat objekt med den här strukturen:

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

Mer specifikt:

  • Fält på den översta nivån

    • firstName – Medarbetarens förnamn.
    • lastName – Medarbetarens efternamn.
    • addresses – En lista över filtrerade adressposter.
    • contacts – En lista över filtrerade kontaktposter.

  • Adressobjekt (addresses[])

    • address1 – Primär adressrad.
    • address2 – Sekundär adressrad.
    • address3 – Ytterligare adressrad.
    • city – Ortnamn.
    • postalCode – Postnummer eller postnummer.
    • country – Landsnamn (mappat från Dayforce Country-namnet).
    • state – Namn på delstat eller provins (mappat från Dayforce State-namnet).
    • contactInformationType – Kort namn som beskriver typen av adress (till exempel "Home", "Mailing"), baserat på dayforce-kontaktinformationstypen.

  • Kontaktobjekt (contacts[])

    • personContactId – Intern numerisk identifierare för kontaktposten.
    • contactInformationType – Kort namn som beskriver typen av kontakt (till exempel "Mobile", "Home Phone", "Work Email").
    • electronicAddress – För "onlineprofil" stil kontakter (till exempel e-post eller andra elektroniska adresser).
    • contactNumber – För telefonliknande kontakter (till exempel mobilnummer eller fasta nummer).
    • country – Landvärde som är associerat med kontakten (i förekommande fall).
    • effectiveStart – Gällande startdatum för denna kontaktinformation (om tillgängligt).

Obs! Anslutningsappens skript filtrerar avsiktligt den råa Dayforce-nyttolasten.
Endast fälten som visas ovan exponeras för anropare av den här åtgärden.

Vid fel returnerar API:et:

  • 400 Felaktig begäran – för felaktiga begäranden eller ogiltig .xRefCode
  • 500 Internt serverfel – För oväntade fel på serversidan.

Felsvar inkluderar diagnostikinformation från det underliggande Dayforce-API:et.

Hämta autentiseringsuppgifter

Den här anslutningsappen använder grundläggande autentisering för att ansluta till Dayforce-API:et.

Så här hämtar du de nödvändiga autentiseringsuppgifterna:

  1. Skapa eller identifiera en API-användare i Dayforce

    • Arbeta med din Dayforce-administratör eller implementeringsteam.
    • Kontrollera att API-användaren har läsbehörighet till personalinformation för din miljö.

  2. Samla in följande värden

    • Användarnamn – Användarnamn för Dayforce API.
    • Lösenord – Dayforce API-lösenordet.
    • Klientnamnområde – det namnområdesvärde som används i dina Dayforce API-URL:er.
      • Detta är ofta en kort identifierare för din organisation eller miljö, till exempel segmentet som visas i URL:er som:
        https://{environmentHost}/{clientNamespace}/V1/Employees/....

  3. Använd dessa värden när du skapar en anslutningsanslutning

    • I dialogrutan Power Platform-anslutning:
      • Ange användarnamnet och lösenordet för Dayforce API-användaren.
      • Ange dayforce-klientnamnområdet i fältet "Klientnamnområde".
    • Anslutningsappen använder dessa värden för att dirigera begäranden till rätt Dayforce-klientorganisation och autentisera anropet.

Om du är osäker på din klientnamnrymd eller API-användarinformation kontaktar du Dayforce-supporten eller din interna Dayforce-administratör.

Komma igång

Det rekommenderade sättet att testa och använda den här anslutningsappen är att lägga till den som ett verktyg i en Copilot Studio AI-agent.

1. Skapa en anslutning

Innan du använder anslutningsappen i Copilot Studio kontrollerar du att det finns en anslutning:

  1. Gå tillDataanslutningar> i Power Platform-administratörs- eller maker-upplevelsen.
  2. Välj + Ny anslutning.
  3. Sök efter din Dayforce HCM-anslutning (den här anslutningsappen).
  4. När du uppmanas till det anger du:
    • Användarnamn – Dayforce API-användarnamn.
    • Lösenord – Dayforce API-användarlösenord.
    • Klientnamnområde – Ditt Dayforce-klientnamnområde.
  5. Spara anslutningen.

2. Skapa en AI-agent i Copilot Studio och lägg till anslutningsappen som ett verktyg

  1. Öppna Copilot Studio.
  2. Skapa en ny AI-agent (eller öppna en befintlig agent där du vill använda Dayforce-data).
  3. Gå till avsnittet Verktyg/plugin-program (eller anslutningsappar) i agenten.
  4. Lägg till dayforce HCM-anslutningsappen som ett verktyg.
  5. Kontrollera att anslutningsappen använder den anslutning som du skapade tidigare.

3. Anropa anslutningsappen från AI-agenten

  1. I ai-agentens redigeringsupplevelse:
    • Skapa eller redigera ett ämne, en åtgärd eller ett plugin-anrop där du vill att agenten ska hämta information om anställda.
  2. Konfigurera ett verktygsanrop som använder åtgärden Hämta personalinformation för medarbetare :
    • Mappa användarindata (till exempel "medarbetarkod") till parametern xRefCode .
  3. Använd de returnerade fälten:
    • firstName och lastName kan användas i AI-agentens svar (till exempel "Här är adressen och kontaktinformationen för John Smith.").
    • Använd addresses och contacts i agentlogik för att visa eller resonera över medarbetarens adress och kontaktuppgifter.

Med den här konfigurationen kan AI-agenten på ett säkert sätt anropa Dayforce HCM-anslutningstjänsten som ett verktyg, hämta endast de filtrerade fälten och införliva dessa resultat i svar eller beslutsfattande.

Kända problem och begränsningar

  • Sökning med en anställd
    Åtgärden hämtar data för en anställd i taget, baserat på XRefCode. Massfrågor eller sökningar med andra attribut (till exempel namn eller e-post) stöds inte av den här anslutningsdefinitionen.

  • Exakt XRefCode-matchning krävs
    Parametern xRefCode måste matcha en befintlig medarbetares externa referenskod exakt. Om värdet är ogiltigt eller inte finns returnerar tjänsten ett svar på 400 Felaktig begäran.

  • Skrivskyddade åtgärder
    Den här versionen av anslutningsappen är skrivskyddad. Den har inte stöd för att skapa, uppdatera eller ta bort information om anställda.

  • Miljöspecifik konfiguration
    API-definitionen och routningsprincipen förväntar sig en giltig Dayforce-miljö och ett klientnamnområde. Om dessa inte matchar din faktiska Dayforce-miljökonfiguration misslyckas anropen med anslutnings- eller routningsfel.

  • Filtrerad nyttolast
    Det underliggande Dayforce-API:et returnerar många fler fält än vad som exponeras här. Anslutningsappens skript filtrerar och omformar avsiktligt dessa data till firstName, lastName, addresses[]och contacts[] endast.

  • Datasynlighet beror på Dayforce-konfiguration
    De fält och värden som returneras för en anställd beror på hur din Dayforce-miljö har konfigurerats (roller, säkerhet och vilka dataelement som är aktiverade eller ifyllda).

Vanliga frågor och svar

F1: Vad används fältet "Klientnamnområde" för?
Klientnamnområdet identifierar din Dayforce-klientorganisation i Dayforce API-URL:en. Anslutningsappen använder den för att dirigera begäranden till rätt kundnamnområde, till exempel:
https://{environmentHost}/{clientNamespace}/V1/Employees/{xRefCode}
Om du inte känner till det här värdet kontaktar du Dayforce-administratören eller implementeringsteamet.

F2: Vad händer om jag anger ett ogiltigt?xRefCode
Om inte xRefCode matchar en befintlig medarbetare returnerar tjänsten ett svar på 400 felaktig begäran. Det underliggande Dayforce API-felet visas via anslutningsappen.

F3: Kan jag hämta flera anställda i ett samtal?
Inte med den här anslutningsdefinitionen. Den aktuella åtgärden hämtar en enskild medarbetares personliga information per anrop, baserat på den angivna xRefCode.

Distributionsinstruktioner (CLI – paconn)

Du kan distribuera den här anslutningsappen som en anpassad anslutningsapp med hjälp av Power Platform Connectors CLI (paconn).

1. Förbereda anslutningsartefakter

Kontrollera att du har följande filer i en lokal mapp (till exempel ./dayforce-hcm-connector):

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

Dessa bör matcha den struktur som förväntas av power platform-ramverket för anpassade anslutningsappar.

2. Installera och konfigurera CLI

  1. Installera Power Platform Connectors CLI (paconn) om du inte redan har gjort det.
  2. Logga in på målmiljön/klientorganisationen med hjälp av paconn enligt Microsofts dokumentation (till exempel med ).paconn login

3. Skapa anslutningsappen

Kör ett kommando som liknar:

paconn create   --api-def apiDefinition.swagger.json   --api-prop apiProperties.json --icon icon.png   --script script.csx
  • Kontrollera att du kör det här kommandot i mappen som innehåller anslutningsfilerna eller ange fullständiga sökvägar till varje fil.
  • När anslutningen har skapats visas den som en anpassad anslutningsapp i målmiljön.

4. Uppdatera anslutningsappen (om det behövs)

Om du senare gör ändringar apiDefinition.swagger.jsoni , apiProperties.jsoneller script.csx, kan du uppdatera den befintliga anslutningsappen med:

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

Ersätt <your-connector-id> med ID:t för anslutningsappen som skapades.

5. Skapa en anslutning och använd den i Copilot Studio

När anslutningsappen har distribuerats:

  1. Gå tillDataanslutningar> och skapa en ny anslutning för Dayforce HCM-anslutningsappen med dina Dayforce-autentiseringsuppgifter och klientnamnområde.
  2. I Copilot Studio lägger du till den här anslutningsappen som ett verktyg i AI-agenten och anropar åtgärden Hämta personalinformation för medarbetare enligt beskrivningen i avsnittet Komma igång .

6. Säkerhets- och anslutningsdelning

Vi har för avsikt att den här anslutningsappen ska följa en icke-delningsbar anslutningsmodell: när en Power App- eller Copilot Studio-agent som använder den här anslutningsappen delas delas endast anslutningsdefinitionen och varje enskild användare måste uttryckligen skapa en egen Dayforce-anslutning med sina egna autentiseringsuppgifter vid första användningen. Anslutningsappen får inte tillåta delning av anslutningar på ett sätt som gör att en användares Dayforce-behörigheter kan återanvändas av en annan (dvs. inget scenario där en app eller agent körs under appägarens eller anslutningsägarens Dayforce-identitet). Som en del av certifieringen kontrollerar du att alla autentiseringstyper för den här anslutningsappen är konfigurerade som Ej delningsbara, så att anslutningsdelning blockeras på plattformsnivå och att varje användare alltid måste upprätta sin egen Dayforce-anslutning.

Inkludera den här ansvarsfriskrivningen: Det här är inte delningsbar anslutning. Om power-appen delas med en annan användare uppmanas en annan användare att skapa en ny anslutning explicit.

När dayforce HCM-anslutningen har certifierats och publicerats av Microsoft kommer den att vara tillgänglig som en certifierad anslutningsapp och du behöver vanligtvis bara skapa en anslutning (ingen CLI-distribution krävs för slutanvändarna).

Skapa en anslutning

Anslutningsappen stöder följande autentiseringstyper:
Standardinställning Parametrar för att skapa anslutning. Alla regioner Går inte att dela

Standard

Tillämpligt: Alla regioner

Parametrar för att skapa anslutning.

Det här är inte delningsbar anslutning. Om power-appen delas med en annan användare uppmanas en annan användare att skapa en ny anslutning explicit.

Namn Type Beskrivning Obligatoriskt
användarnamn securestring Användarnamnet för det här API:et Sann
lösenord securestring Lösenordet för det här API:et Sann
Autentiseringstyp snöre Autentiseringstyp för att ansluta till ditt API Sann
Klientnamnområde snöre klientnamnområde Sann

Begränsningsgränser

Name Anrop Förnyelseperiod
API-anrop per anslutning 100 60 sekunder

Åtgärder

Hämta personalinformation för medarbetare

Den här åtgärden hämtar data som rör en anställd och hans/hennes personliga information (t.ex. namn, adresser och kontakter) via XRef Code

Hämta personalinformation för medarbetare

Åtgärds-ID:
Get_Employee_Personal_Info

Den här åtgärden hämtar data som rör en anställd och hans/hennes personliga information (t.ex. namn, adresser och kontakter) via XRef Code

Parametrar

Name Nyckel Obligatorisk Typ Description
Referenskod för medarbetare
 xRefCode True string

Den unika identifieraren (extern referenskod) för den medarbetare som ska hämtas. Det angivna värdet måste vara den exakta matchningen för en medarbetare. Annars returneras ett fel med felaktig begäran (400).

Returer

Body
Payload_Employee

Definitioner

ProcessResult

Name Sökväg Typ Description
Kod
 Code string
Context
 Context string
Nivå
 Level string
Message
 Message string

Medarbetare

Name Sökväg Typ Description
AnställningsId
 EmployeeId integer
Kontakter
 Contacts PersonContactCollection
Addresses
 Addresses PersonAddressCollection
GlobalPersonId
 GlobalPersonId string
XRefCode
 XRefCode string
NewXRefCode
 NewXRefCode string
Allmänt Namn
 CommonName string
visningsnamn
 DisplayName string
FirstName
 FirstName string
Efternamn
 LastName string
Initialer
 Initials string
MaidenName
 MaidenName string
Mellannamn
 MiddleName string
Titel
 Title string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

PersonContactCollection

Name Sökväg Typ Description
Artiklar
 Items array of PersonContact

PersonAddressCollection

Name Sökväg Typ Description
Artiklar
 Items array of PersonAddress

PersonContact

Name Sökväg Typ Description
PersonContactId
 PersonContactId integer
ContactInformationType
 ContactInformationType ContactInformationType
ContactNumber
 ContactNumber string
Land
 Country Country
EffectiveEnd
 EffectiveEnd date-time
EffectiveStart
 EffectiveStart date-time
ElectronicAddress
 ElectronicAddress string
Förlängning
 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 Sökväg Typ Description
PersonAddressId
 PersonAddressId integer
Adress 1
 Address1 string
Adress 2
 Address2 string
Adress 3
 Address3 string
Adress 4
 Address4 string
Adress 5
 Address5 string
Adress 6
 Address6 string
Ort
 City string
Postnummer
 PostalCode string
Land
 Country Country
Tillstånd
 State State
ContactInformationType
 ContactInformationType ContactInformationType
IsPayrollMailing
 IsPayrollMailing boolean
DisplayOnTaxForm
 DisplayOnTaxForm boolean
DisplayOnEarningStatement
 DisplayOnEarningStatement boolean
EffectiveStart
 EffectiveStart date-time
EffectiveEnd
 EffectiveEnd date-time
Län
 County string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

Land

Name Sökväg Typ Description
Namn
 Name string
XRefCode
 XRefCode string
ShortName
 ShortName string
LongName
 LongName string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

ContactInformationType

Name Sökväg Typ Description
ContactInformationTypeGroup
 ContactInformationTypeGroup ContactInformationTypeGroup
XRefCode
 XRefCode string
ShortName
 ShortName string
LongName
 LongName string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

Tillstånd

Name Sökväg Typ Description
Namn
 Name string
XRefCode
 XRefCode string
ShortName
 ShortName string
LongName
 LongName string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

ContactInformationTypeGroup

Name Sökväg Typ Description
XRefCode
 XRefCode string
ShortName
 ShortName string
LongName
 LongName string
LastModifiedTimestamp
 LastModifiedTimestamp date-time

Payload_Employee

Name Sökväg Typ Description
data
 Data Employee
ProcessResults
 ProcessResults array of ProcessResult