Dayforce HCM (Pré-visualização)

Este conector está disponível nos seguintes produtos e regiões:

Service	Classe	Regiões
Estúdio Copiloto	Premium	Todas as regiões do Power Automatic , exceto as seguintes:      - Governo dos EUA (CCG)      - Governo dos EUA (GCC High)      - China Cloud operado pela 21Vianet      - Departamento de Defesa dos EUA (DoD)
Aplicações Lógicas	Standard	Todas as regiões do Logic Apps , exceto as seguintes:      - Regiões do Azure Government      - Regiões do Azure China      - Departamento de Defesa dos EUA (DoD)
Power Apps	Premium	Todas as regiões do Power Apps , exceto as seguintes:      - Governo dos EUA (CCG)      - Governo dos EUA (GCC High)      - China Cloud operado pela 21Vianet      - Departamento de Defesa dos EUA (DoD)
Power Automate	Premium	Todas as regiões do Power Automatic , exceto as seguintes:      - Governo dos EUA (CCG)      - Governo dos EUA (GCC High)      - China Cloud operado pela 21Vianet      - Departamento de Defesa dos EUA (DoD)

Entrar em contato
Nome	Apoio de Força Diurna
URL	https://www.dayforce.com/resources/help-center#support-for-employers
Email	MicrosoftPartnership@dayforce.com

Metadados do conector
Editor	IA Dayforce
Sítio Web	https://www.dayforce.com/
Política de privacidade	https://www.dayforce.com/privacy
Categorias	IA; Recursos Humanos

Dayforce HCM

A Dayforce HCM é uma plataforma de gestão de capital humano.
Este conector expõe uma operação da API Dayforce que permite recuperar informações pessoais de um colaborador (nome, moradas e contactos de contactos) através do seu código de referência externo (XRefCode). Pode usar estes dados como ferramenta nos agentes de IA do Copilot Studio, bem como noutros cenários da Power Platform.

Editora: Dayforce

---

Pré-requisitos

Para usar esse conector, você precisa:

• Um ambiente Microsoft Power Platform (por exemplo, para usar o conector no Copilot Studio).
• Um ambiente ativo de Dayforce HCM (QA, UAT ou Produção).
• Um utilizador da API Dayforce (conta de serviço) com permissão para ler informações pessoais do funcionário.
• O URL da API para o seu ambiente Dayforce, incluindo o espaço de nomes do cliente.
  • Esta é a URL base usada para chamar a API Dayforce para o seu inquilino, por exemplo:
    https://{environmentHost}/{basePath}/api/{clientNamespace}
  • O formato exato depende da configuração do teu ambiente Dayforce. Contacte o administrador do seu Dayforce se não tiver a certeza da URL.

---

Operações suportadas

O conector expõe atualmente a seguinte operação.

Obter informações pessoais dos funcionários

ID da Operação:Get_Employee_Personal_Info
Método:GET

Recupera uma visão filtrada e simplificada da informação pessoal de um único colaborador com base no seu XRefCode.

Pedido

• Parâmetro de Caminho
  • xRefCode (corda, necessária)
    O código de referência externo do funcionário a ser recuperado. O valor deve corresponder exatamente ao XRefCode de um funcionário existente; caso contrário, o serviço devolve 400 Pedido Mau.

Internamente, o conector encaminha a chamada para o endpoint Dayforce Employees usando a URL da API fornecida no momento da criação da ligação, expandindo a informação pessoal relevante, que é depois transformada pelo script do conector num objeto JSON simplificado.

Resposta

Em caso de sucesso (HTTP 200), o conector não devolve a carga útil completa do empregado Dayforce.
Em vez disso, devolve um objeto transformado com esta estrutura:

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

Mais especificamente:

• Campos de nível superior

  • firstName – Primeiro nome do funcionário.
  • lastName – Apelido do funcionário.
  • addresses – Uma lista de entradas de endereços filtradas.
  • contacts – Uma lista de entradas de contacto filtradas.

• Objeto de endereçar (addresses[])

  • address1 – Linha de endereço principal.
  • address2 – Linha de endereço secundária.
  • address3 – Linha de morada adicional.
  • city – Nome da cidade.
  • postalCode – Código postal ou POSTAL.
  • country – Nome do país (mapeado a partir do nome do país Dayforce).
  • state – Nome do Estado ou da província (mapeado a partir do nome do Estado Dayforce).
  • contactInformationType – Nome curto que descreve o tipo de endereço (por exemplo, "Home", "Mailing"), baseado no tipo de contacto Dayforce.

• Objeto de contacto (contacts[])

  • personContactId – Identificador numérico interno para o registo de contacto.
  • contactInformationType – Nome curto que descreve o tipo de contacto (por exemplo, "Móvel", "Telefone Fixo", "Email de Trabalho").
  • electronicAddress – Para contactos do estilo "perfil online" (como email ou outros endereços eletrónicos).
  • contactNumber – Para contactos ao estilo telemóvel (por exemplo, números de telemóvel ou fixo).
  • country – Valor por país associado ao contacto (quando aplicável).
  • effectiveStart – Data de início efetiva desta informação de contacto (se disponível).

Nota: O script do conector filtra intencionalmente a carga útil bruta do Dayforce.
Apenas os campos mostrados acima estão expostos aos chamadores desta operação.

Em caso de erro, a API devolve:

• 400 Pedido Mau – Para pedidos mal formados ou inválidos xRefCode.
• Erro Interno do Servidor 500 – Para falhas inesperadas do lado do servidor.

As respostas ao erro incluem informação de diagnóstico da API Dayforce subjacente.

---

Obtenção de credenciais

Este conector utiliza autenticação básica para se ligar à API Dayforce.

Para obter as credenciais exigidas:

1. Criar ou identificar um utilizador de API no Dayforce

   • Trabalhe com o seu administrador ou equipa de implementação do Dayforce.
   • Assegure que o utilizador da API tem acesso de leitura às informações pessoais dos colaboradores para o seu ambiente.

2. Recolha os seguintes valores

   • URL da API – O URL base da API para o seu inquilino Dayforce, incluindo o namespace do cliente. Este é o URL que o conector usará para encaminhar pedidos para o seu ambiente Dayforce. Não inclua uma barra final.

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

     Importante: Alguns ambientes Dayforce utilizam uma URL universal (por exemplo, https://dayforcehcm.com/api/{clientNamespace}) que redireciona automaticamente para uma URL específica do ambiente (por exemplo, https://us252-services.dayforcehcm.com/api/{clientNamespace}). Ao configurar o conector, use sempre a URL final e resolvida em vez da URL universal. Pode determinar o URL final navegando até à página de documentação do Swagger para o seu ambiente (por exemplo, https://dayforcehcm.com/api/{clientNamespace}/swagger/index.html) e anotando o URL para onde o seu navegador é redirecionado.

   • Nome de utilizador – Nome de utilizador da API Dayforce.

   • Palavra-passe – A palavra-passe da API Dayforce.

3. Use estes valores ao criar uma ligação de ligação

   • No diálogo de ligação da Power Platform:
     • Introduza a URL da API para o seu ambiente Dayforce.
     • Introduza o nome de utilizador e a palavra-passe do utilizador da API Dayforce.
   • O conector utiliza a URL da API para encaminhar pedidos para o tenant Dayforce correto e as credenciais para autenticar a chamada.

Se não tiver a certeza da URL da sua API ou dos dados de utilizador da API, contacte o suporte do Dayforce ou o administrador interno do Dayforce.

---

Introdução

A forma recomendada de testar e usar este conector é adicioná-lo como uma ferramenta num agente de IA do Copilot Studio.

1. Criar uma ligação

Antes de usar o conector no Copilot Studio, certifique-se de que existe uma ligação:

1. Na experiência de administrador ou criador do Power Platform, vá a Conexões de Dados>.
2. Selecione + Nova ligação.
3. Procura o teu conector Dayforce HCM (este conector).
4. Quando solicitado, forneça:
   • URL da API – A URL base da API para o seu tenant Dayforce (incluindo o espaço de nomes do cliente). Não inclua uma barra final.
   • Nome de utilizador – Nome de utilizador da API Dayforce.
   • Palavra-passe – Palavra-passe de utilizador da API Dayforce.
5. Guarde a ligação.

2. Criar um agente de IA no Copilot Studio e adicionar o conector como ferramenta

1. Abra Copilot Studio.
2. Cria um novo agente de IA (ou abre um agente existente onde queiras usar os dados do Dayforce).
3. Vai à secção de Ferramentas/Plugins (ou Conectores) do agente.
4. Adiciona o teu conector Dayforce HCM como ferramenta.
5. Assegura-te de que o conector usa a ligação que criaste anteriormente.

3. Chamar o conector do agente de IA

1. Na sua experiência de autoria de agentes de IA:
   • Cria ou edita um tópico, ação ou chamada de plugin onde queres que o agente recupere a informação do funcionário.
2. Configure uma chamada de ferramenta que utilize a operação Obter Informação Pessoal do Colaborador :
   • Mapeie a entrada do utilizador (por exemplo, "código do empregado") para o xRefCode parâmetro.
3. Use os campos devolvidos:
   • firstName e lastName pode ser usado nas respostas do agente de IA (por exemplo, "Aqui está a morada e as informações de contacto de John Smith.").
   • Use addresses e contacts na lógica do agente para mostrar ou raciocinar sobre a morada e os dados de contacto do funcionário.

Esta configuração permite ao seu agente de IA chamar de forma segura o conector Dayforce HCM como uma ferramenta, recuperar apenas os campos filtrados e incorporar esses resultados nas respostas ou na tomada de decisões.

---

Problemas conhecidos e limitações

• Pesquisa apenas com um único empregado
  A operação recupera dados de um funcionário de cada vez, com base no XRefCode. Consultas em massa ou pesquisas por outros atributos (como nome ou email) não são suportadas por esta definição de conector.

• Correspondência exata do XRefCode necessária
  O xRefCode parâmetro deve corresponder exatamente ao código de referência externo de um funcionário existente. Se o valor for inválido ou não existir, o serviço devolve uma resposta 400 de Pedido Mau.

• Operações apenas de leitura
  Esta versão do conector é só de leitura. Não suporta a criação, atualização ou eliminação de informações dos colaboradores.

• Configuração específica do ambiente
  O conector requer uma URL válida da API Dayforce (fornecida no momento da criação da ligação). Se o URL não corresponder à configuração real do teu ambiente Dayforce, as chamadas falharão com erros de ligação ou de encaminhamento. Não inclua uma barra adicional na URL da API.

• Carga útil filtrada
  A API Dayforce subjacente devolve muito mais campos do que os expostos aqui. O script do conector filtra e remodela intencionalmente estes dados em firstName, lastName, addresses[], e contacts[] apenas.

• A visibilidade dos dados depende da configuração do Dayforce
  Os campos e valores devolvidos para um colaborador dependem de como o seu ambiente Dayforce está configurado (funções, segurança e quais os elementos de dados ativados ou preenchidos).

---

Perguntas Mais Frequentes

P1: Para que serve o campo "URL da API"?
A URL da API é a URL base para o seu inquilino Dayforce, incluindo o namespace do cliente. O conector usa-o para encaminhar todos os pedidos de API para o ambiente Dayforce correto. A URL não deve incluir uma barra final.
Se não conhece este valor, contacte o administrador do Dayforce ou a equipa de implementação.

P2: O que acontece se eu apresentar um inválido xRefCode?
Se não xRefCode corresponder a um funcionário existente, o serviço devolve uma resposta 400 de Pedido Mau. O erro subjacente da API Dayforce é manifestado através do conector.

P3: Posso reunir vários funcionários numa só chamada?
Não com esta definição de conector. A operação atual recupera a informação pessoal de um único funcionário por chamada, com base no .xRefCode

---

Instruções de Implementação (CLI – paconn)

Pode implementar este conector como um conector personalizado usando o Power Platform Connectors CLI (paconn).

1. Preparar artefactos do conector

Certifique-se de que tem os seguintes ficheiros numa pasta local (por exemplo, ./dayforce-hcm-connector):

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

Estes devem corresponder à estrutura esperada pelo framework de conectores personalizados da Power Platform.

2. Instalar e configurar a CLI

1. Instale a CLI dos Power Platform Connectors (paconn) caso ainda não o tenha feito.
2. Inicie sessão no seu ambiente/tenant de destino usando paconn a documentação da Microsoft (por exemplo, usando paconn login).

3. Criar o conector

Execute um comando semelhante a:

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

• Certifica-te de que executas este comando na pasta que contém os ficheiros de conector, ou fornece os caminhos completos para cada ficheiro.
• Após a criação, o conector aparecerá como um conector personalizado no ambiente de destino.

4. Atualizar o conector (se necessário)

Se mais tarde fizer alterações a apiDefinition.swagger.json, apiProperties.json, ou script.csx, pode atualizar o conector existente com:

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

Substitua <your-connector-id> pelo ID do conector que foi criado.

5. Criar uma ligação e usá-la no Copilot Studio

Uma vez que o conector está instalado:

1. Vai a Ligações de Dados> e cria uma nova ligação para o conector HCM Dayforce usando o URL e as credenciais da API Dayforce.
2. No Copilot Studio, adicione este conector como ferramenta ao seu agente de IA e ligue para a operação Obter Informações Pessoais do Colaborador , conforme descrito na secção Começo .

6. Segurança e partilha de ligação

Este conector utiliza um modelo de ligação não partilhável. Quando partilha um Power App ou um agente Copilot Studio que utiliza este conector, apenas o conector definição é partilhado — cada utilizador deve criar a sua própria ligação Dayforce com as suas próprias credenciais na primeira utilização. As ligações não podem ser partilhadas de forma a permitir que as permissões Dayforce de um utilizador sejam reutilizadas por outro. Todos os tipos de autenticação estão configurados como Não partilháveis, pelo que a partilha de ligação é bloqueada ao nível da plataforma e cada utilizador é sempre obrigado a estabelecer a sua própria ligação Dayforce.

Limites de Limitação

Name	Chamadas	Período de Renovação
Chamadas de API por conexão	100	60 segundos

Ações

Obter informações pessoais dos funcionários

Esta operação recupera dados relacionados com um colaborador e as suas informações pessoais (por exemplo, Nome, Moradas e Contactos) através do Código XRef

Obter informações pessoais dos funcionários

Definições

ProcessResult

Funcionário

PessoaContactoColeção

PessoaEndereçoColeção

PessoaContact

PessoaEndereço

País

ContactInformationType

Estado

ContactoInformaçãoTipoGroup

Payload_Employee