Como adicionar eventos de escala (como PTO) via CommunityWebAPI a partir de um sistema externo. O uso das funções da API RESTful requer que o leitor entenda como criar solicitações HTTP e como consumir dados formatados em JSON.
Integração de Eventos da Comunidade
O Community suporta uma função de API exposta pelo serviço RESTful CommunityWebAPI. As informações abaixo devem permitir que você adicione eventos com sucesso via o serviço RESTful programaticamente.
Esta interface descreve a criação de "eventos recorrentes", que podem ser eventos de um único dia (férias, doença, etc.) ou eventos que se repetem por um longo período de tempo, mas apenas em dias específicos (por exemplo, entre 1º de janeiro e 31 de março, tenho uma consulta médica recorrente toda sexta-feira entre 9:00 e 11:00).
Nos casos em que o evento é de um único dia, basta fornecer as mesmas datas e horários de e até, mas certifique-se de que as bandeiras d? estejam todas definidas como verdadeiras.
No exemplo mais complexo, o valor da data de início seria "2017/01/01"; o valor da data de término seria "2017/03/31"; o valor do horário de início seria "09:00:00"; o valor do horário de término seria "11:00:00"; e as bandeiras d? seriam (assumindo que o dia de início da semana é segunda-feira) d1=false d2=false d3=false d4=false d5=true d6=false d7=false.
Interface da API
O verbo é POST e o ponto de entrada é http://<servername>/CommunityWebApi/api/SingleRecurringEvent
A execução da chamada retorna um objeto WebApiResult padrão do WFMSG (em formato JSON) que inclui os seguintes membros:
Success – booleano que indica que a operação foi bem-sucedida.
Data – se bem-sucedido, contém o objeto RecurringEvent recém-criado (descrito abaixo). Se não for bem-sucedido, este membro é NULL.
Message – se não for bem-sucedido, contém a exceção lançada; caso contrário, este membro está vazio.
ExceptionResult – se uma exceção for lançada, este é o corpo completo da exceção; caso contrário, este membro é NULL.
*Note que o Community suporta o uso de implantações simultâneas do CommunityWebAPI para integração dentro de uma arquitetura segura, bem como implantação em DMZ ou em appliance dedicado para interfaces externas.
Cabeçalho de Autenticação Necessário
A versão 4.3 e superior da Community Web API requer um token de autenticação para cada ponto de entrada passado como um valor de cabeçalho personalizado. Aplicações cliente podem recuperar o token de autenticação inicial da chamada POST AuthenticateEx (descrita em outro documento) em uma variável membro chamada “authToken.” As aplicações cliente então passam este valor no cabeçalho personalizado “WFMSGAPIKEY” em chamadas subsequentes. Note que o token de autenticação expirará após 20 minutos.
Além disso, as aplicações cliente podem recuperar a versão “atualizada” do token em cada chamada lendo o valor do cabeçalho personalizado com o mesmo nome (“WFMSGAPIKEY”).
Pares Nome/Valor
A tabela a seguir contém os pares nome/valor que devem ser incluídos no envio do formulário para a chamada RESTful. Note que para inserir novos agentes no banco de dados, o valor transactionFlagId deve ser definido como 1.
| Membro da Classe | Tipo | Obrigatório? | Descrição |
| transactionFlagId | Int | Sim |
Indica o tipo de transação POST a ser realizada. Os valores válidos são: 1: Inserir |
| agentId | Int | Sim | Sa_agent_id a ser atribuído ao(s) novo(s) evento(s) criado(s). |
| eventTypeId | Int | Sim | Sa_exception_type_id dos eventos. |
| startTime | DateTime | Sim |
Um par de data/hora no formato AAAA/MM/DD HH:MM (relógio de 24 horas) que indica a hora de início do evento. Note que, para este membro, o aplicativo ignora a parte da data. Exemplo: iniciar um evento às 8:00 AM 1900-01-01 08:00:00 |
| endTime | DateTime | Sim |
Um par de data/hora no formato AAAA/MM/DD HH:MM (relógio de 24 horas) que indica a hora de término do evento. Note que, para este membro, o aplicativo ignora a parte da data.
Exemplo: terminar um evento às 5:00 PM 1900-01-01 17:00:00 |
| description | String | Não | Fornece o campo de descrição no evento |
| location | String | Não | Fornece o campo de localização no evento |
| scheduleId | Int | Não | Se for NULL, então este evento é colocado na escala publicada. Se não for NULL, então este evento é colocado na escala de trabalho onde sa_schedule_id = este valor. |
| startDate | DateTime | Sim |
Um valor de data no formato AAAA/MM/DD que indica a data de início do evento. Note que, para este membro, o aplicativo ignora a parte do tempo (se fornecida). Exemplo: iniciar o evento em 1º de maio de 2017 2017/05/01 |
| endDate | DateTime | Sim |
Um valor de data no formato AAAA/MM/DD que indica a data de término do evento. Note que, para este membro, o aplicativo ignora a parte do tempo (se fornecida). Exemplo: terminar o evento em 4 de maio de 2017 2017/05/04 |
| d1 | Bool | Sim | Um valor booleano que indica se este evento deve ocorrer no primeiro dia da semana (tipicamente segunda-feira). |
| d2 | Bool | Sim | Um valor booleano que indica se este evento deve ocorrer no segundo dia da semana. |
| d3 | Bool | Sim | Um valor booleano que indica se este evento deve ocorrer no terceiro dia da semana. |
| d4 | Bool | Sim | Um valor booleano que indica se este evento deve ocorrer no quarto dia da semana. |
| d5 | Bool | Sim | Um valor booleano que indica se este evento deve ocorrer no quinto dia da semana. |
| d6 | Bool | Sim | Um valor booleano que indica se este evento deve ocorrer no sexto dia da semana. |
| d7 | Bool | Sim | Um valor booleano que indica se este evento deve ocorrer no sétimo dia da semana. |
| timeZoneId | Int | Não | O fuso horário do evento; normalmente, será o horário local do agente, mas se for NULL, o aplicativo usará o fuso horário corporativo por padrão. |
| responsibleUserId | Int | Sim | O sa_agent_id do usuário com privilégio suficiente para fazer alterações na escala deste agente. |
Declaração de classe de exemplo para os pares nome/valor
(conforme descrito na tabela acima)
public class SingleRecurringEventPostParams
{
/// <summary>
/// transactionFlagId dita como o evento será modificado.
/// </summary>
public int transactionFlagId { get; set; }
/// <summary>
/// agentId
/// </summary>
public int agentId { get; set; }
/// <summary>
/// eventTypeId
/// </summary>
public int eventTypeId { get; set; }
/// <summary>
/// startTime
/// </summary>
public DateTime startTime { get; set; }
/// <summary>
/// endTime
/// </summary>
public DateTime endTime { get; set; }
/// <summary>
/// description
/// </summary>
public string description { get; set; }
/// <summary>
/// location
/// </summary>
public string location { get; set; }
/// <summary>
/// scheduleId
/// </summary>
public int? scheduleId { get; set; }
/// <summary>
/// startDate
/// </summary>
public DateTime startDate { get; set; }
/// <summary>
/// endDate
/// </summary>
public DateTime endDate { get; set; }
/// <summary>
/// d1
/// </summary>
public bool d1 { get; set; }
/// <summary>
/// d2
/// </summary>
public bool d2 { get; set; }
/// <summary>
/// d3
/// </summary>
public bool d3 { get; set; }
/// <summary>
/// d4
/// </summary>
public bool d4 { get; set; }
/// <summary>
/// d5
/// </summary>
public bool d5 { get; set; }
/// <summary>
/// d6
/// </summary>
public bool d6 { get; set; }
/// <summary>
/// d7
/// </summary>
public bool d7 { get; set; }
/// <summary>
/// timeZoneId
/// </summary>
public int? timeZoneId { get; set; }
/// <summary>
/// ID do usuário responsável - usado para fins de auditoria.
/// </summary>
public int? responsibleUserId { get; set; }
}
A definição da classe RecurringEvent
(membro WebApiResult.Data do verbo POST com os parâmetros acima)
#region Membros da Classe
[DataMember]
/// <summary>
/// Do Procedimento Get, parâmetro @StartTime [6] [Não é uma Chave]
/// </summary>
public DateTime? StartTime { get; set; }
[DataMember]
/// <summary>
/// Do Procedimento Get, parâmetro @CreateDate [18] [Não é uma Chave]
/// </summary>
public DateTime? CreateDate { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @AssignmentType [20] [Não é uma chave]
/// </summary>
public RecurringEventAssignmentTypes AssignmentType { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @RecurringEventId [0] [Não é uma chave]
/// </summary>
public int? RecurringEventId { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @EndDate [8] [Não é uma chave]
/// </summary>
public DateTime? EndDate { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @AllDay [9] [Não é uma chave]
/// </summary>
public bool? AllDay { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @TimeZoneId [0] [Não é uma chave]
/// </summary>
public int? TimeZoneId { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @ScheduleId [1] [Não é uma chave]
/// </summary>
public int? ScheduleId { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @ProcessAgentId [23] [Não é uma chave]
/// </summary>
public int? ProcessAgentId { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @ProcessDate [22] [Não é uma chave]
/// </summary>
public DateTime? ProcessDate { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @Description [5] [Não é uma chave]
/// </summary>
public string Description { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @StartDate [7] [Não é uma chave]
/// </summary>
public DateTime? StartDate { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @ExceptionTypeId [2] [Não é uma chave]
/// </summary>
public int? ExceptionTypeId { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @BaseDate [17] [Não é uma chave]
/// </summary>
public DateTime? BaseDate { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @IncludeDayOfWeek4 [13] [Não é uma chave]
/// </summary>
public bool? IncludeDayOfWeek4 { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @IncludeDayOfWeek5 [14] [Não é uma chave]
/// </summary>
public bool? IncludeDayOfWeek5 { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @IncludeDayOfWeek6 [15] [Não é uma chave]
/// </summary>
public bool? IncludeDayOfWeek6 { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @IncludeDayOfWeek7 [16] [Não é uma chave]
/// </summary>
public bool? IncludeDayOfWeek7 { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @Location [4] [Não é uma chave]
/// </summary>
public string Location { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @IncludeDayOfWeek1 [10] [Não é uma chave]
/// </summary>
public bool? IncludeDayOfWeek1 { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @IncludeDayOfWeek2 [11] [Não é uma chave]
/// </summary>
public bool? IncludeDayOfWeek2 { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @IncludeDayOfWeek3 [12] [Não é uma chave]
/// </summary>
public bool? IncludeDayOfWeek3 { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @LastUpdate [19] [Não é uma chave]
/// </summary>
public DateTime? LastUpdate { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @Duration [3] [Não é uma chave]
/// </summary>
public double? Duration { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @ProcessAgentName [24] [Não é uma chave]
/// </summary>
public string ProcessAgentName { get; set; }
[DataMember]
/// <summary>
/// Do procedimento Get, parâmetro @Processed [21] [Não é uma chave]
/// </summary>
public bool? Processed { get; set; }
public DataTable ValidationResults { get; set; }
public DataTable AdjustedEvents { get; set; }
public DataTable CreatedEvents { get; set; }
/// <summary>
/// Cria uma chave dinâmica para uso em serviços de auditoria.
/// </summary>
private dynamic key = new System.Dynamic.ExpandoObject();
#endregion