Cómo agregar eventos (como tiempo libre) a un horario mediante la ComunidadWebAPI desde un sistema externo. El uso de las funciones de la API RESTful requiere que el lector comprenda cómo crear solicitudes HTTP y cómo consumir datos en formato JSON.
Integración de eventos en CommunityWFM
Community admite una función de la API expuesta por el servicio RESTful de CommunityWebAPI. La información a continuación le permitirá agregar eventos mediante el servicio RESTful de forma programática.
Esta interfaz describe cómo crear "eventos recurrentes", que pueden ser eventos de un solo día (vacaciones, enfermedad, etc.) o eventos que se repiten durante un periodo largo, pero solo en días específicos (por ejemplo, entre el 1 de enero y el 31 de marzo, tengo una cita médica recurrente todos los viernes de 9:00 a 11:00).
En los casos en que el evento sea de un solo día, simplemente proporcione las mismas fechas y horas en los campos from y thru, pero asegúrese de que todos los indicadores d? estén configurados como true.
En un ejemplo más complejo, el valor de la fecha de inicio sería "2026/01/01"; el valor de la fecha de finalización sería "2026/03/31"; el valor de la hora de inicio sería "09:00:00"; el valor de la hora de finalización sería "11:00:00"; y los indicadores d? serían (asumiendo que el lunes es el primer día de la semana) d1=false d2=false d3=false d4=false d5=true d6=false d7=false.
Interfaz de la API
El verbo es POST y el punto de entrada es http://<servername>/CommunityWebApi/api/SingleRecurringEvent
La ejecución de la llamada devuelve un objeto WebApiResult estándar de WFMSG (en formato JSON) que incluye los siguientes miembros:
Success – booleano que indica si la operación fue exitosa.
Data – si la operación fue exitosa, contiene el objeto RecurringEvent recién creado (descrito más abajo). Si no fue exitosa, este miembro es NULL.
Message – si no fue exitosa, contiene la excepción generada; de lo contrario, este miembro está vacío.
ExceptionResult – si se genera una excepción, aquí se muestra el cuerpo completo de la excepción; de lo contrario, este miembro es NULL.
*Tome en cuenta que Community admite el uso de despliegues concurrentes de la ComunidadWebAPI para la integración dentro de una arquitectura segura, así como el despliegue en DMZ o en un dispositivo dedicado para interfaces externas.
Encabezado de autenticación requerido
La versión 4.3 y versiones posteriores de CommunityWebAPI requieren un token de autenticación para cada punto de entrada, el cual se pasa como un valor de encabezado personalizado. Las aplicaciones cliente pueden obtener el token de autenticación inicial de la llamada POST AuthenticateEx (descrita en otro documento) en una variable miembro llamada “authToken”. Luego, las aplicaciones cliente deben pasar este valor en el encabezado personalizado “WFMSGAPIKEY” en las llamadas posteriores. Tenga en cuenta que el token de autenticación caduca después de 20 minutos.
Además, las aplicaciones cliente pueden obtener la versión “actualizada” del token en cada llamada leyendo el valor del encabezado personalizado con el mismo nombre (“WFMSGAPIKEY”).
Pares nombre/valor
La siguiente tabla contiene los pares nombre/valor que deben incluirse en el envío del formulario para la llamada RESTful. Tenga en cuenta que, para insertar nuevos agentes en la base de datos, el valor de transactionFlagId debe establecerse en 1.
| Miembro de clase | Tipo | Req? | Descripción |
| transactionFlagId | Int | Sí |
Indica el tipo de transacción POST a realizar. Los valores válidos son: 1: Insertar |
| agentId | Int | Sí | Sa_agent_id que se asignará al/los evento(s) recién creado(s). |
| eventTypeId | Int | Sí | Sa_exception_type_id de los eventos. |
| startTime | DateTime | Sí |
Un par de fecha/hora en formato AAAA/MM/DD HH:MM (reloj de 24 horas) que indica la hora de inicio del evento. Tenga en cuenta que, para este miembro, la aplicación ignora la parte de la fecha. Ejemplo: iniciar un evento a las 8:00 AM 1900-01-01 08:00:00 |
| endTime | DateTime | Sí |
Un par de fecha/hora en formato AAAA/MM/DD HH:MM (reloj de 24 horas) que indica la hora de finalización del evento. Tenga en cuenta que, para este miembro, la aplicación ignora la parte de la fecha.
Ejemplo: finalizar un evento a las 5:00 PM 1900-01-01 17:00:00 |
| description | String | No | Proporciona el campo de descripción del evento |
| location | String | No | Proporciona el campo de ubicación del evento |
| scheduleId | Int | No | Si es NULL, este evento se coloca en el horario publicado. Si no es NULL, este evento se coloca en el horario provisional donde sa_schedule_id = este valor. |
| startDate | DateTime | Sí |
Un valor de fecha en formato AAAA/MM/DD que indica la fecha de inicio del evento. Tenga en cuenta que, para este miembro, la aplicación ignora la parte de la hora (si se proporciona). Ejemplo: iniciar el evento el 1 de mayo de 2027 2026/05/01 |
| endDate | DateTime | Sí |
Un valor de fecha en formato AAAA/MM/DD que indica la fecha de finalización del evento. Tenga en cuenta que, para este miembro, la aplicación ignora la parte de la hora (si se proporciona). Ejemplo: finalizar el evento el 4 de mayo de 2026 2026/05/04 |
| d1 | Bool | Sí | Un valor booleano que indica si este evento debe ocurrir el primer día de la semana (normalmente lunes). |
| d2 | Bool | Sí | Un valor booleano que indica si este evento debe ocurrir el segundo día de la semana. |
| d3 | Bool | Sí | Un valor booleano que indica si este evento debe ocurrir el tercer día de la semana. |
| d4 | Bool | Sí | Un valor booleano que indica si este evento debe ocurrir el cuarto día de la semana. |
| d5 | Bool | Sí | Un valor booleano que indica si este evento debe ocurrir el quinto día de la semana. |
| d6 | Bool | Sí | Un valor booleano que indica si este evento debe ocurrir el sexto día de la semana. |
| d7 | Bool | Sí | Un valor booleano que indica si este evento debe ocurrir el séptimo día de la semana. |
| timeZoneId | Int | No | La zona horaria del evento; normalmente será la hora local del agente, pero si es NULL la aplicación usará la zona horaria corporativa de forma predeterminada. |
| responsibleUserId | Int | Sí | El sa_agent_id del usuario con privilegios suficientes para hacer cambios en el horario de este agente. |
Ejemplo de declaración de clase para los pares nombre/valor
(como se describe en la tabla anterior)
public class SingleRecurringEventPostParams
{
/// <summary>
/// transactionFlagId indica cómo se modificará el evento.
/// </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 de usuario responsable - usado para fines de auditoría.
/// </summary>
public int? responsibleUserId { get; set; }
}
Definición de la clase RecurringEvent
(Miembro WebApiResult.Data del verbo POST con los parámetros anteriores)
#region Class Members
[DataMember]
/// <summary>
/// From Get Procedure, parameter @StartTime [6] [Not a Key]
/// </summary>
public DateTime? StartTime { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @CreateDate [18] [Not a Key]
/// </summary>
public DateTime? CreateDate { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @AssignmentType [20] [Not a Key]
/// </summary>
public RecurringEventAssignmentTypes AssignmentType { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @RecurringEventId [0] [Not a Key]
/// </summary>
public int? RecurringEventId { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @EndDate [8] [Not a Key]
/// </summary>
public DateTime? EndDate { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @AllDay [9] [Not a Key]
/// </summary>
public bool? AllDay { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @TimeZoneId [0] [Not a Key]
/// </summary>
public int? TimeZoneId { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @ScheduleId [1] [Not a Key]
/// </summary>
public int? ScheduleId { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @ProcessAgentId [23] [Not a Key]
/// </summary>
public int? ProcessAgentId { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @ProcessDate [22] [Not a Key]
/// </summary>
public DateTime? ProcessDate { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @Description [5] [Not a Key]
/// </summary>
public string Description { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @StartDate [7] [Not a Key]
/// </summary>
public DateTime? StartDate { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @ExceptionTypeId [2] [Not a Key]
/// </summary>
public int? ExceptionTypeId { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @BaseDate [17] [Not a Key]
/// </summary>
public DateTime? BaseDate { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @IncludeDayOfWeek4 [13] [Not a Key]
/// </summary>
public bool? IncludeDayOfWeek4 { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @IncludeDayOfWeek5 [14] [Not a Key]
/// </summary>
public bool? IncludeDayOfWeek5 { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @IncludeDayOfWeek6 [15] [Not a Key]
/// </summary>
public bool? IncludeDayOfWeek6 { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @IncludeDayOfWeek7 [16] [Not a Key]
/// </summary>
public bool? IncludeDayOfWeek7 { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @Location [4] [Not a Key]
/// </summary>
public string Location { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @IncludeDayOfWeek1 [10] [Not a Key]
/// </summary>
public bool? IncludeDayOfWeek1 { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @IncludeDayOfWeek2 [11] [Not a Key]
/// </summary>
public bool? IncludeDayOfWeek2 { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @IncludeDayOfWeek3 [12] [Not a Key]
/// </summary>
public bool? IncludeDayOfWeek3 { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @LastUpdate [19] [Not a Key]
/// </summary>
public DateTime? LastUpdate { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @Duration [3] [Not a Key]
/// </summary>
public double? Duration { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @ProcessAgentName [24] [Not a Key]
/// </summary>
public string ProcessAgentName { get; set; }
[DataMember]
/// <summary>
/// From Get Procedure, parameter @Processed [21] [Not a Key]
/// </summary>
public bool? Processed { get; set; }
public DataTable ValidationResults { get; set; }
public DataTable AdjustedEvents { get; set; }
public DataTable CreatedEvents { get; set; }
/// <summary>
/// Create a dynamic key for use in audit services.
/// </summary>
private dynamic key = new System.Dynamic.ExpandoObject();
#endregion