Dayforce HCM (préversion)

Ce connecteur est disponible dans les produits et régions suivants :

Service	Classe	Régions
Copilot Studio	Premium	Toutes les régions Power Automate à l’exception des éléments suivants :      - Us Government (GCC)      - Us Government (GCC High)      - China Cloud géré par 21Vianet      - Us Department of Defense (DoD)
Applications logiques	Norme	Toutes les régions Logic Apps , à l’exception des suivantes :      - Régions Azure Government      - Régions Azure Chine      - Us Department of Defense (DoD)
Power Apps	Premium	Toutes les régions Power Apps à l’exception des éléments suivants :      - Us Government (GCC)      - Us Government (GCC High)      - China Cloud géré par 21Vianet      - Us Department of Defense (DoD)
Power Automate	Premium	Toutes les régions Power Automate à l’exception des éléments suivants :      - Us Government (GCC)      - Us Government (GCC High)      - China Cloud géré par 21Vianet      - Us Department of Defense (DoD)

Contact
Nom	Prise en charge de Dayforce
URL	https://www.dayforce.com/resources/help-center#support-for-employers
Courrier électronique	MicrosoftPartnership@dayforce.com

Métadonnées du connecteur
Éditeur	IA Dayforce
Website	https://www.dayforce.com/
Politique de confidentialité	https://www.dayforce.com/privacy
Catégories	IA ; Ressources humaines

Dayforce HCM

Dayforce HCM est une plateforme de gestion des capitaux humains.
Ce connecteur expose une opération d’API Dayforce qui vous permet de récupérer les informations personnelles d’un employé (nom, adresses et coordonnées) par son code de référence externe (XRefCode). Vous pouvez utiliser ces données en tant qu’outil dans les agents Copilot Studio AI, ainsi que dans d’autres scénarios Power Platform.

Éditeur : Dayforce

---

Prerequisites

Pour utiliser ce connecteur, vous avez besoin des éléments suivants :

• Un environnement Microsoft Power Platform (par exemple, pour utiliser le connecteur dans Copilot Studio).
• Un environnement Dayforce HCM actif (QA, UAT ou Production).
• Un utilisateur d’API Dayforce (compte de service) avec l’autorisation de lire les informations personnelles des employés.
• URL de l’API pour votre environnement Dayforce, y compris l’espace de noms client.
  • Il s’agit de l’URL de base utilisée pour appeler l’API Dayforce pour votre locataire, par exemple :
    https://{environmentHost}/{basePath}/api/{clientNamespace}
  • Le format exact dépend de la configuration de votre environnement Dayforce. Contactez votre administrateur Dayforce si vous n’êtes pas sûr de l’URL.

---

Opérations prises en charge

Le connecteur expose actuellement l’opération suivante.

Obtenir des informations personnelles sur les employés

ID d’opération :Get_Employee_Personal_Info
Méthode:GET

Récupère une vue filtrée et simplifiée des informations personnelles d’un seul employé en fonction de son XRefCode.

Requête

• Paramètre de chemin d’accès
  • xRefCode (chaîne, obligatoire)
    Code de référence externe de l’employé à récupérer. La valeur doit correspondre exactement au XRefCode d’un employé existant ; sinon, le service retourne une requête incorrecte 400.

En interne, le connecteur achemine l’appel vers le point de terminaison Dayforce Employees à l’aide de l’URL de l’API fournie au moment de la création de la connexion et développe les informations personnelles pertinentes, qui sont ensuite transformées par le script du connecteur en objet JSON simplifié.

Réponse

En cas de réussite (HTTP 200), le connecteur ne retourne pas la charge utile complète de l’employé Dayforce.
Au lieu de cela, elle retourne un objet transformé avec cette structure :

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

Plus précisément :

• champs de niveau supérieur

  • firstName – Prénom de l’employé.
  • lastName – Nom de l’employé.
  • addresses : liste des entrées d’adresse filtrées.
  • contacts : liste des entrées de contact filtrées.

• Objet Address (addresses[])

  • address1 – Ligne d’adresse principale.
  • address2 – Ligne d’adresse secondaire.
  • address3 – Ligne d’adresse supplémentaire.
  • city – Nom de la ville.
  • postalCode – Code postal ou postal.
  • country – Nom du pays (mappé à partir du nom du pays Dayforce).
  • state – Nom de l’état ou de la province (mappé à partir du nom de l’état Dayforce).
  • contactInformationType : nom court décrivant le type d’adresse (par exemple, « Accueil », « Publipostage »), basé sur le type d’informations de contact Dayforce.

• Objet Contact (contacts[])

  • personContactId – Identificateur numérique interne de l’enregistrement de contact.
  • contactInformationType – Nom court décrivant le type de contact (par exemple, « Mobile », « Téléphone personnel », « Adresse e-mail professionnelle »).
  • electronicAddress – Pour les contacts de style « profil en ligne » (tels que l’e-mail ou d’autres adresses électroniques).
  • contactNumber – Pour les contacts de style téléphone (par exemple, les numéros mobiles ou fixes).
  • country – Valeur de pays associée au contact (le cas échéant).
  • effectiveStart – Date de début effective de ces informations de contact (le cas échéant).

Remarque : le script du connecteur filtre intentionnellement la charge utile Dayforce brute.
Seuls les champs indiqués ci-dessus sont exposés aux appelants de cette opération.

En cas d’erreur, l’API retourne :

• 400 Demande incorrecte : pour les demandes incorrectes ou non valides xRefCode.
• Erreur de serveur interne 500 : pour les échecs inattendus côté serveur.

Les réponses aux erreurs incluent les informations de diagnostic de l’API Dayforce sous-jacente.

---

Obtention des informations d’identification

Ce connecteur utilise l’authentification de base pour se connecter à l’API Dayforce.

Pour obtenir les informations d’identification requises :

1. Créer ou identifier un utilisateur d’API dans Dayforce

   • Collaborez avec votre administrateur Dayforce ou votre équipe d’implémentation.
   • Vérifiez que l’utilisateur de l’API a accès en lecture aux informations personnelles des employés pour votre environnement.

2. Collecter les valeurs suivantes

   • URL de l’API : URL de l’API de base de votre locataire Dayforce, y compris l’espace de noms du client. Il s’agit de l’URL que le connecteur utilisera pour acheminer les requêtes vers votre environnement Dayforce. N’incluez pas de barre oblique de fin.

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

     Important: Certains environnements Dayforce utilisent une URL universelle (par exemple) https://dayforcehcm.com/api/{clientNamespace}qui redirige automatiquement vers une URL spécifique à l’environnement (par exemple). https://us252-services.dayforcehcm.com/api/{clientNamespace} Lors de la configuration du connecteur, utilisez toujours l’URL finale résolue plutôt que l’URL universelle. Vous pouvez déterminer l’URL finale en accédant à la page de documentation Swagger de votre environnement (par exemple https://dayforcehcm.com/api/{clientNamespace}/swagger/index.html) et en notant l’URL vers laquelle votre navigateur est redirigé.

   • Nom d’utilisateur : nom d’utilisateur de l’API Dayforce.

   • Mot de passe : mot de passe de l’API Dayforce.

3. Utilisez ces valeurs lors de la création d’une connexion de connecteur

   • Dans la boîte de dialogue de connexion Power Platform :
     • Entrez l’URL de l’API pour votre environnement Dayforce.
     • Entrez le nom d’utilisateur et le mot de passe de l’utilisateur de l’API Dayforce.
   • Le connecteur utilise l’URL de l’API pour router les demandes vers le locataire Dayforce correct et les informations d’identification pour authentifier l’appel.

Si vous n’êtes pas sûr de l’URL de votre API ou des détails de l’utilisateur de l’API, contactez le support Dayforce ou votre administrateur Dayforce interne.

---

Getting Started

La méthode recommandée pour tester et utiliser ce connecteur consiste à l’ajouter en tant qu’outil dans un agent IA Copilot Studio.

1. Créer une connexion

Avant d’utiliser le connecteur dans Copilot Studio, vérifiez qu’une connexion existe :

1. Dans l’expérience administrateur ou créateur Power Platform, accédez àConnexions de >.
2. Cliquez sur + Nouvelle connexion.
3. Recherchez votre connecteur Dayforce HCM (ce connecteur).
4. Lorsque vous y êtes invité, indiquez :
   • URL de l’API : URL de l’API de base de votre locataire Dayforce (y compris l’espace de noms du client). N’incluez pas de barre oblique de fin.
   • Nom d’utilisateur – Nom d’utilisateur de l’API Dayforce.
   • Mot de passe : mot de passe utilisateur de l’API Dayforce.
5. Enregistrez la connexion.

2. Créer un agent IA dans Copilot Studio et ajouter le connecteur en tant qu’outil

1. Ouvrez Copilot Studio.
2. Créez un agent IA (ou ouvrez un agent existant dans lequel vous souhaitez utiliser des données Dayforce).
3. Accédez à la section Outils/Plug-ins (ou connecteurs) de l’agent.
4. Ajoutez votre connecteur Dayforce HCM en tant qu’outil.
5. Vérifiez que le connecteur utilise la connexion que vous avez créée précédemment.

3. Appeler le connecteur à partir de l’agent IA

1. Dans votre expérience de création d’agent IA :
   • Créez ou modifiez un appel de rubrique, d’action ou de plug-in dans lequel vous souhaitez que l’agent récupère les informations des employés.
2. Configurez un appel d’outil qui utilise l’opération Obtenir les informations personnelles des employés :
   • Mappez l’entrée utilisateur (par exemple, « code employé ») au xRefCode paramètre.
3. Utilisez les champs retournés :
   • firstName et lastName peut être utilisé dans les réponses de l’agent IA (par exemple, « Voici l’adresse et les coordonnées de John Smith. »).
   • Utilisez addresses et contacts dans la logique de l’agent pour afficher ou raisonner sur l’adresse et les coordonnées de l’employé.

Cette configuration permet à votre agent IA d’appeler en toute sécurité le connecteur Dayforce HCM en tant qu’outil, de récupérer uniquement les champs filtrés et d’incorporer ces résultats dans les réponses ou la prise de décision.

---

Problèmes connus et limitations

• Recherche à un seul employé uniquement
  L’opération récupère les données d’un employé à la fois, en fonction du XRefCode. Les requêtes en bloc ou les recherches par d’autres attributs (tels que le nom ou l’e-mail) ne sont pas prises en charge par cette définition de connecteur.

• Correspondance XRefCode exacte requise
  Le xRefCode paramètre doit correspondre exactement au code de référence externe d’un employé existant. Si la valeur n’est pas valide ou n’existe pas, le service retourne une réponse de requête incorrecte 400.

• Opérations en lecture seule
  Cette version du connecteur est en lecture seule. Elle ne prend pas en charge la création, la mise à jour ou la suppression d’informations sur les employés.

• Configuration spécifique à l’environnement
  Le connecteur nécessite une URL d’API Dayforce valide (fournie au moment de la création de la connexion). Si l’URL ne correspond pas à votre configuration d’environnement Dayforce réelle, les appels échouent avec des erreurs de connexion ou de routage. N’incluez pas de barre oblique de fin dans l’URL de l’API.

• Charge utile filtrée
  L’API Dayforce sous-jacente retourne beaucoup plus de champs que ceux qui sont exposés ici. Le script du connecteur filtre intentionnellement et transforme ces données en firstName, lastNameet addresses[]contacts[] uniquement.

• La visibilité des données dépend de la configuration dayforce
  Les champs et valeurs retournés pour un employé dépendent de la façon dont votre environnement Dayforce est configuré (rôles, sécurité et éléments de données activés ou renseignés).

---

Questions fréquentes

Q1 : Quel est le champ « URL de l’API » utilisé pour ?
L’URL de l’API est l’URL de base de votre locataire Dayforce, y compris l’espace de noms du client. Le connecteur l’utilise pour acheminer toutes les requêtes d’API vers l’environnement Dayforce approprié. L’URL ne doit pas inclure de barre oblique de fin.
Si vous ne connaissez pas cette valeur, contactez votre administrateur Dayforce ou votre équipe d’implémentation.

Q2 : Que se passe-t-il si je fournit un non valide xRefCode?
Si le xRefCode serveur ne correspond pas à un employé existant, le service retourne une réponse de demande incorrecte 400. L’erreur d’API Dayforce sous-jacente est exposée via le connecteur.

Q3 : Puis-je récupérer plusieurs employés en un seul appel ?
Pas avec cette définition de connecteur. L’opération actuelle récupère les informations personnelles d’un seul employé par appel, en fonction de l’élément fourni xRefCode.

---

Instructions de déploiement (CLI – paconn)

Vous pouvez déployer ce connecteur en tant que connecteur personnalisé à l’aide de l’interface CLI Power Platform Connectors (paconn).

1. Préparer les artefacts du connecteur

Vérifiez que vous disposez des fichiers suivants dans un dossier local (par exemple, ./dayforce-hcm-connector) :

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

Celles-ci doivent correspondre à la structure attendue par l’infrastructure du connecteur personnalisé Power Platform.

2. Installer et configurer l’interface CLI

1. Installez l’interface CLI Power Platform Connectors (paconn) si vous ne l’avez pas déjà fait.
2. Connectez-vous à votre environnement/locataire cible à l’aide paconn de la documentation de Microsoft (par exemple, à l’aide paconn loginde ).

3. Créer le connecteur

Exécutez une commande similaire à :

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

• Veillez à exécuter cette commande dans le dossier contenant les fichiers du connecteur, ou fournissez des chemins complets pour chaque fichier.
• Après la création, le connecteur apparaît en tant que connecteur personnalisé dans votre environnement cible.

4. Mettez à jour le connecteur (si nécessaire)

Si vous apportez ultérieurement des modifications à apiDefinition.swagger.json, apiProperties.jsonou script.csxsi vous pouvez mettre à jour le connecteur existant avec :

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

Remplacez <your-connector-id> par l’ID du connecteur qui a été créé.

5. Créer une connexion et l’utiliser dans Copilot Studio

Une fois le connecteur déployé :

1. Accédez àConnexions de données> et créez une connexion pour le connecteur Dayforce HCM à l’aide de l’URL et des informations d’identification de votre API Dayforce.
2. Dans Copilot Studio, ajoutez ce connecteur en tant qu’outil à votre agent IA et appelez l’opération Obtenir les informations personnelles des employés , comme décrit dans la section Prise en main .

6. Partage de sécurité et de connexion

Ce connecteur utilise un modèle de connexion non partageable. Lorsque vous partagez un agent Power App ou Copilot Studio qui utilise ce connecteur, seul le connecteur definition est partagé . each doit créer sa propre connexion Dayforce avec ses propres informations d’identification lors de la première utilisation. Les connexions ne peuvent pas être partagées d’une manière qui permet aux autorisations Dayforce d’un utilisateur d’être réutilisées par un autre. Tous les types d’authentification sont configurés comme non partageables. Par conséquent, le partage de connexion est bloqué au niveau de la plateforme et chaque utilisateur est toujours tenu d’établir sa propre connexion Dayforce.

Création d’une connexion

Le connecteur prend en charge les types d’authentification suivants :

Par défaut	Paramètres de création de connexion.	Toutes les régions	Non partageable

Faire défaut

Applicable : Toutes les régions

Paramètres de création de connexion.

Cette connexion n’est pas partageable. Si l’application power est partagée avec un autre utilisateur, un autre utilisateur est invité à créer une connexion explicitement.

Nom	Catégorie	Description	Obligatoire
nom d'utilisateur	securestring	Nom d’utilisateur de cette API	Vrai
mot de passe	securestring	Mot de passe de cette API	Vrai
Type d’authentification	ficelle	Type d’authentification pour vous connecter à votre API	Vrai
Espace de noms client	ficelle	espace de noms client	Vrai

Limitations

Nom	Appels	Période de renouvellement
Appels d’API par connexion	100	60 secondes

Actions

Obtenir des informations personnelles sur les employés

Cette opération récupère les données relatives à un employé et à ses informations personnelles (par exemple, nom, adresses et contacts) par XRef Code

Obtenir des informations personnelles sur les employés

Définitions

ProcessResult

Employé

PersonContactCollection

PersonAddressCollection

PersonContact

PersonAddress

Pays

ContactInformationType

State

ContactInformationTypeGroup

Payload_Employee