Manual: Uso de la API REST de OFSC para Crear Suscripciones

¿Como crear suscripciones a eventos en Oracle Field Services Cloud?

Introducción

La API REST de Oracle Field Service Cloud (OFSC) permite crear suscripciones para eventos específicos generados dentro de la plataforma. Este manual proporciona instrucciones detalladas para integrar y utilizar esta funcionalidad, incluyendo ejemplos de solicitudes y respuestas.

---

Endpoint

• POST /rest/ofscCore/v1/events/subscriptions

Este endpoint permite registrar eventos en los cuales deseas recibir notificaciones o realizar seguimientos, como activityCreated, activityUpdated, o inventoryInstalled.

---

Requisitos Previos

Antes de utilizar este endpoint, asegúrate de contar con:

1. Permisos de escritura para eventos de Core API en OFSC.
2. Credenciales de autenticación válidas.
3. Un entorno configurado para aceptar y gestionar solicitudes API.

---

Límites

1. Duración: Las suscripciones expiran tras 36 horas si no se utilizan con la operación “Get Events”.
2. Cantidad máxima: Solo se permiten hasta 100 suscripciones activas simultáneamente.
3. Errores comunes:
   • Intentar crear más de 100 suscripciones generará un error 503 Too many subscriptions registered. Found 100.
   • Si la suscripción ya existe, se reutilizará la existente.

---

Cuerpo de la Solicitud

El cuerpo de la solicitud define los eventos, filtros y campos asociados a la suscripción.

Estructura

{
    "subscriptionConfig": [
        {
            "events": ["activityUpdated"],
            "filterExpression": "(activityDetails.activityType in ['IN','TC','BR']) AND (user != 'my_integ') AND (activityDetails.customerName != '')",
            "monitorChanges": ["DISPATCHER_COMMENTS", "WO_COMMENTS"],
            "fields": [
                "WO_COMMENTS", "DISPATCHER_COMMENTS", "timeSlot", "apptNumber", 
                "resourceId", "resourceInternalId", "date", "status", 
                "customerName", "streetAddress", "language", "masterActivityId"
            ]
        }
    ],
    "subscriptionTitle": "My Subscription Title"
}

Parámetros Clave

• subscriptionConfig: Una lista de configuraciones de suscripción.
  • events: Lista de eventos para los cuales se desea la suscripción.
  • filterExpression: Expresión lógica para filtrar eventos específicos.
  • monitorChanges: Lista de campos cuyos cambios se monitorearán.
  • fields: Campos adicionales para incluir en los eventos retornados.
• subscriptionTitle (opcional): Título que identifica la suscripción. Debe tener entre 1 y 255 caracteres.

---

Ejemplo de Solicitud

Encabezados:

POST /rest/ofscCore/v1/events/subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Basic <credentials>
Host: <instance_name>.fs.ocs.oraclecloud.com

Cuerpo:

{
    "subscriptionConfig": [
        {
            "events": ["activityCompleted"],
            "filterExpression": "(activityDetails.activityType in ['IN','TC','BR'])",
            "fields": ["WO_COMMENTS", "DISPATCHER_COMMENTS", "apptNumber"]
        }
    ],
    "subscriptionTitle": "Activity Completion Tracker"
}

---

Respuesta

Formato

{
    "subscriptionId": "4bbc02c8637e961ac88b4b0b38bbaad0f4401e17",
    "nextPage": "170725-3,0",
    "links": [
        {
            "rel": "describedby",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/metadata-catalog/events"
        },
        {
            "rel": "canonical",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/events/subscriptions/4bbc02c8637e961ac88b4b0b38bbaad0f4401e17"
        }
    ]
}

Campos Clave

• subscriptionId: Identificador único de la suscripción.
• nextPage: Identificador para obtener la próxima serie de eventos.

---

Errores Comunes

1. 403 Forbidden: Falta de permisos de escritura para eventos.
2. 400 Bad Request: Faltan parámetros requeridos o valores inválidos en la solicitud.
3. 503 Service Unavailable: Exceso de suscripciones activas.

Cuerpo de Error:

{
    "type": "https://<instance_name>.fs.ocs.oraclecloud.com/error/403",
    "title": "Permission Denied",
    "status": "403",
    "detail": "User does not have write permission for Core API events."
}

---

Ejemplo Práctico

Este ejemplo demuestra cómo configurar una suscripción que supervise actualizaciones en actividades:

1. Define los eventos en subscriptionConfig.
2. Filtra actividades específicas utilizando filterExpression.
3. Envía la solicitud y verifica que el subscriptionId sea generado exitosamente.

---

Conclusión

Utilizar la API REST para crear suscripciones en OFSC facilita el seguimiento de eventos clave en tiempo real. Sigue este manual para implementar configuraciones personalizadas que se alineen con tus necesidades operativas.

---

Si tienes preguntas, deja un comentario en esta entrada o consulta la documentación oficial de Oracle Field Service.