Webservices para Uso en la Plataforma 4biz
Este documento está destinado a proporcionar orientaciones sobre los Servicios Web que están disponibles para la integración con la Gestión de Servicio de 4biz.
Los Servicios Web se crearon en 4biz para la inclusión, actualización, consulta y cancelación de solicitudes de servicio (incidentes y solicitudes).
Antes de empezar
- Antes de utilizar cualquier operación REST de 4biz, es necesario que el usuario esté autenticado..
- La autenticación se realiza a través de la operación REST login en la URL /services/login, que recibe un objeto CtLogin que contiene los atributos userName, password y platform.
- El atributo platform debe contener la identificación del sitio que está solicitando el servicio.
- La operación de inicio de sesión devuelve un valor alfanumérico en el atributo SessionID. Este mismo SessionID debe ser utilizado en las otras llamadas REST. El objeto devuelto contiene el código y la descripción del error en caso de problemas en la ejecución de la operación de inicio de sesión.
- El usuario autentificado constituye la clave para la sincronización de datos, cuando el atributo synchronize tiene el valor true.
- Los servicios de inclusión y actualización de solicitudes tienen el atributo synchronize. Cuando este atributo es true, el registro de usuarios y el catálogo de servicios serán creados o actualizados automáticamente en 4biz basándose en la información enviada en la solicitud del Servicio Web.
✅ Regla: Todos los servicios REST creados en 4biz reciben un objeto de entrada y devuelven un objeto. En caso de error, el objeto de retorno contiene el código y la descripción del error. Cuando no hay error, además de los atributos definidos para cada servicio, el objeto de retorno contiene la fecha y hora de ejecución y el id de la operación. 4biz garantiza que cada solicitud se registra en su base de datos y se devuelve un ID de operación al solicitante, incluso en caso de error.
Acciones
Crear un ticket (request_create)
- Condiciones previas: configurar los contratos, grupos, flujos y permisos.
🖊 Nota: Para ver el título, el parámetro 301 - Mostrar título en la solicitud de servicio debe estar activado.
El webservice que se muestra a continuación crea un ticket para un usuario que está registrado en el sistema.
Creación de una Solicitud/Incidente:
/webmvc/servicerequestincident/createModificación de la Información de un Ticket (create)
Modificación de la Información de la Solicitud/Incidente:
/services/request/createModificación del estado de un Ticket (updateStatus)
Modificación del estado de un Incidente/Solicitud:
/services/request/updateStatusConsultar Tickets del Solicitante (getByUser)
Consulta de Incidentes y Solicitudes del Solicitante:
/services/request/getByUserDetalles del Ticket de un Solicitante (getById)
Detalles de la Solicitud/Incidente:
number - número de la solicitud en 4biz ITSM. Obligatorio cuando no se indica el atributo numberOrigin.
numberOrigin - número de la solicitud en el sistema de origen. Obligatorio cuando no se indica el número de atributo.Incluir la Ocurrencia en el Ticket (createOccurrence)
Incluir una ocurrencia en una solicitud:
/services/request/createOccurrenceConsultar las Ocurrencias del Ticket (listOccurrences)
Consultar información de las solicitudes/incidentes:
/services/request/listOccurrencesListar Tickets para el Servicio
Este webservice se debe utilizar para listar los usuarios que pueden ser solicitantes al abrir un ticket.
- Condiciones previas: El solicitante debe estar vinculado a un grupo que tenga permiso para crear en un flujo de trabajo.
Listar las solicitudes/incidentes para el servicio:
/services/request/createOccurrence
/webmvc/servicerequestincident/searchTickets {
"status": "SUCCESS",
"code": "200",
"message": "Request processed successfully",
"payload": [
{
"id": 904,
"name": "Lucas Novais",
"email": "[email protected]",
"unit": {
"id": 1,
"name": "Default",
"places": [
{
"id": 1,
"name": "Brasilia"
}
]
},
"phone": "(676) 76868-7687"
}
]
}Guardar ticket en el servicio
Este webservice se debe utilizar para devolver los tickets a los analistas.
- Condiciones previas: Tener acceso al sistema y permiso para ejecutar en el flujo de trabajo.
Para guardar sólo el ticket: webmvc/servicerequestincident/save
Para guardar y continuar el ticket: webmvc/servicerequestincident/nextRecibir Unidades
Este webservice se debe utilizar para devolver las unidades activas existentes en el sistema para su selección al crear un ticket.
- Condiciones previas: Este servicio web cambia los resultados si el parámetro 61 - Vincula los contratos a la unidad (Ej.: S o N) está activo.
La documentación de desarrollo está en Swagger.
Para leer esta documentación, es necesario estar conectado a la aplicación, y esa aplicación tiene que estar en la versión que tiene estos servicios web.
• token de autenticación: atributo obligatorio que recibe el token de autenticación
o Pasar el token de autenticación en el encabezado;
• employeeId: Atributo obligatorio que recibe el código del usuario que solicita el ticket:
o Pasar el atributo como parámetro;
• Límite: Atributo que devuelve el número de unidades a devolver en la búsqueda;
o Pasar el atributo como parámetro;
• unitQuery: Atributo no obligatorio que permite buscar por parte del nombre de la unidad;
o Pasar el atributo como parámetro;
Ejemplo de entrada de servicio web
{
No se aplica ya que la URL pasará todos los atributos requeridos
}Recibir justificación de suspensión
Este webservice debe ser utilizado para devolver las justificaciones de suspensión registradas y activas en el sistema.
- Condiciones previas: el usuario que se pasa en el servicio web debe tener permiso de suspensión en el flujo de trabajo;
La documentación de desarrollo está en Swagger.
Para leer esta documentación, el usuario debe iniciar sesión en la aplicación, y esta aplicación debe estar en la versión que tiene estos servicios web.
webmvc/v1/boleto/justificación Método: OBTENER Posibles códigos de retorno
200 - Solicitud realizada con éxito
401 - Token de autenticación no válido o usuario sin acceso al recurso
404 - Justificación no encontradaListar tickets para servicio
Este webservice debe usarse para devolver las opciones permitidas en el flujo en un grupo dado.
- Condiciones previas: el usuario que se pasa en el servicio web debe tener acceso al sistema. El usuario que se pasa en el servicio web debe tener permiso en el flujo de trabajo;
La documentación de desarrollo está en Swagger.
Para leer esta documentación, el usuario debe iniciar sesión en la aplicación, y esta aplicación debe estar en la versión que tiene estos servicios web.
/webmvc/v1/ticket/{ticketId}/permisos Método: OBTENER Posibles códigos de retorno
200 - Solicitud realizada con éxito
401 - Token de autenticación no válido o usuario sin acceso al recurso
404 – Ticket no encontradoRecibir acciones de usuario en un ticket
Este servicio web debe usarse para devolver las acciones del usuario dibujadas en un flujo de trabajo.
Condiciones previas: el usuario que se pasa en el servicio web debe tener acceso al sistema. El usuario que se pasa en el servicio web debe tener permiso de ejecución en el flujo de trabajo;
La documentación de desarrollo está en Swagger.
Para leer esta documentación, el usuario debe iniciar sesión en la aplicación, y esta aplicación debe estar en la versión que tiene estos servicios web.
webmvc/v1/ticket/{ticketId}/flow-actions Método: OBTENER Posibles códigos de retorno
200 - Solicitud realizada con éxito
401 - Token de autenticación no válido o usuario sin acceso al recurso
404 – Boleto no encontrado Condición posterior:
Para enviar la respuesta seleccionada en la acción del usuario,
utilice el servicio web Guardar y reenviar
(webmvc/servicerequestincident/next)
Atributos: "acción de flujo":
"razónFlujoAcción":Listar archivos adjuntos de los tickets
Este servicio web debe usarse para devolver la lista de archivos adjuntos a un ticket para que los analistas asistan.
Condiciones previas: el usuario que se pasa en el servicio web debe tener acceso al sistema.
La documentación de desarrollo está en Swagger.
Para leer esta documentación, el usuario debe iniciar sesión en la aplicación, y esta aplicación debe estar en la versión que tiene estos servicios web.
Nota: Este documento contiene todos los servicios web necesarios para adjuntar, que incluyen:
- Listar adjuntos de un ticket;
- Descargar el archivo adjunto;
- Adjuntar documento al ticket (cargar);
- Eliminar archivo adjunto de ticket
/webmvc/servicerequestincident/{serviceRequestIncidentId}/archivos
adjuntos Tipo de método: OBTENER Posibles códigos de retorno
200 - Solicitud realizada con éxito
401 - Token de autenticación no válido o usuario sin acceso al recurso
404 - Ticket no encontradoDescargar archivos adjuntos de un ticket
webmvc/servicerequestincident/{serviceRequestIncidentId}/attachments/{documentId}
Tipo de método: OBTENER Posibles códigos de retorno
200 - Solicitud realizada con éxito
401 - Token de autenticación no válido o usuario sin acceso al recurso
404 - Documento o ticket no encontradoCargar los archivos adjuntos de un ticket
/webmvc/services/request/addAttachments Método tipo: POST
Pre Condición:
1. Verifique los parámetros:
2. 44 - Cargue el directorio de la ruta del repositorio (Ej.: Windows - C:/temp)
3. 278: tamaño máximo de archivo, en bytes, para cargar. Predeterminado[1073741824] = 1GB
4. 318 - Lista de extensiones de archivos que no se pueden adjuntar
(Para más de una extensión, sepárelas por punto y coma)
5. 446 - ¿Enviar archivos adjuntos en el correo electrónico de notificación del ticket?
(Ej.: S o N - Predeterminado: 'N') Posibles códigos de retorno
200 - Solicitud realizada con éxito
500 - Campos obligatorios no informadosEliminar archivos adjuntos de un ticket
/webmvc/v1/ticket/{ticketId}/attachments/{documentId} Método de tipo:
ELIMINAR Posibles códigos de retorno
200 - Solicitud realizada con éxito
401 - Token de autenticación no válido o usuario sin acceso al recurso
404 - Ticket no encontrado