4.- Servicios de SCDE y casos de uso de ejemplo
- Servicios Digitales de Aragón
- Jesus Angel Garcia Magaldi
En este apartado se explicarán los servicios de SCDE y cómo inicializar su cliente java
ÍNDICE DEL CONTENIDO
- 1 Descripción funcional del servicio
- 2 Inicialización del cliente mediante CXF
- 3 Ejemplo de configuración de la librería con maven
- 4 Servicios
- 4.1.1 Servicios públicos
- 4.1.2 ServiciosPrivados
- 4.2 Servicios CertificateService
- 4.2.1 Elementos comunes
- 4.2.1.1 Códigos de estado
- 4.2.1.2 ParamBase
- 4.2.1.3 ResultGetStatus
- 4.2.1.4 Excepciones
- 4.2.2 Método ‘createCertificate’ (obsoleto)
- 4.2.3 Método ‘createCertificate1’
- 4.2.4 Método ‘getStatus’
- 4.2.5 Método ‘sendDocAuth’ (obsoleto)
- 4.2.6 Método ‘sendDocAuth1’
- 4.2.7 Método ‘signDocs’ (obsoleto)
- 4.2.8 Método ‘signDocs1’
- 4.2.9 Método ‘getDcmi’
- 4.2.10 Método ‘cancelOperation’
- 4.2.11 Método ‘signDocsWithExternalDocAuth’
- 4.2.12 Método ‘signDocsWithoutDocAuth’
- 4.2.13 Método ‘getDocByCSV’
- 4.2.14 Método ‘sendDocAuthByCSV’ (obsoleto)
- 4.2.1 Elementos comunes
Descripción funcional del servicio
El Servicio de Creación de Documentos Electrónicos (SCDE) está concebido para proporcionar varias herramientas relacionadas con la creación de documentos a partir de plantillas pdf y la firma de dichos documentos y, por otro lado con la gestión masiva de documentos y la firma de estos.
Cada grupo de funcionalidades es gestionado de forma independiente. La primera, la gestión de documentos individuales y su firma por parte de un empleado público se gestiona desde el módulo PRIV de la aplicación. Cuando se genera un documento se crea en el contexto de una categoría preexistente y a partir de una plantilla que previamente se haya aportado al servicio. El servicio se encargará de gestionar los datos y de aportar y/o solicitar la información necesaria para que se pueda delegar en otros servicios externos a la aplicación determinadas funcionalidades, como puede ser el archivo y gestión de los documentos firmados que se delega en CCSV.
El tratamiento de forma masiva de documentos se gestiona desde métodos especialmente diseñados para estas situaciones, como puede ser el establecimiento de estados y la realización de procesos en segundo plano o programados. Para realizar dichos procesos se han desarrollado las siguientes operaciones:
Crear documentos y, si es requerido, preparar un documento de autorización con el CSV de todos los documentos creados
Enviar la firma de un documento de autorización para que se realice la firma de los documentos creados según el punto anterior
Firmar documentos mediante el proceso de firma con sello de órgano
Consultar los valores rellenados en los campos de un fichero PDF.
Consultar el estado de una operación.
Cancelar una operación y anular los documentos asociados a ésta.
Inicialización del cliente mediante CXF
Mediante sintaxis xml podemos definir fácilmente la configuración del cliente CXF para que acceda a los servicios de SCDE. Inicialmente deberemos definir la referencia a la interfaz del servicio, que se encuentra dentro del cliente suministrado, así como a la dirección a la que apunta el wsdl levantado.
Se muestra a modo de ejemplo una configuración posible mediante archivos xml para conseguir una integración con SCDE.
<bean id="certificateClient" class="es.aragon.scde.core.ws.ICertificateService" factory-bean="certificateClientFactory"
factory-method="create" />
<bean id="certificateClientFactory" class="org.apache.cxf.frontend.ClientProxyFactoryBean">
<property name="serviceClass" value="es.aragon.scde.core.ws.ICertificateService" />
<property name="address" value="ENTORNO:PUERTO/scde_core/services/certificate_service" />
<property name="outInterceptors">
<ref bean="authorizeOutInterceptor" />
</property>
</bean> |
Como se puede observar en la definición XML del cliente CXF, se deberán configurar las urls donde se ubica el servicio CertificateService, para ello habrá que sustituir entorno y puerto por los valores correctos.
Las aplicaciones que se integran con SCDE deben proporcionar en todas las peticiones el código de aplicación.
En el ejemplo se ha optado por crearlo a través de una fáctory proporcionada por las librerías de CXF. Se puede consultar con la documentación CXF para obtener otras formas posibles de conectar con el servicio web.
Las aplicaciones que se integran con SCDE deben proporcionar en todas las peticiones el código de aplicación. Para ello, utilizando los denominados interceptores, es posible rellenar este valor automáticamente en todas las peticiones. Como se ve en la definición del cliente se ha definido un interceptor de salida que entra en funcionamiento en el momento de construir la petición SOAP y que inserta el valor del código de aplicación en los parámetros de todos los métodos de SCDE invocados.
Por comodidad en la integración se ha incluido en el cliente un interceptor con capacidad para introducir el identificador de la aplicación en todas las invocaciones a métodos del servicio.
<bean id="authorizeInterceptor" class="es.aragon.pfi.core.util.interceptors.AuthorizeOutInterceptor">
<property name="applicationId" value="[código aplicación llamante]"/>
</bean>
Ejemplo de configuración de la librería con maven
Si la aplicación a integrarse es gestionada con maven se deberá instalar la dependencia en el fichero pom.xml como tipo jar, según se muestra en el siguiente ejemplo:
<dependency>
<groupId>es.aragon.scde</groupId>
<artifactId>scde_client</artifactId>
<version>2.0</version>
<type>jar</type>
<scope>compile</scope>
</dependency> |
Servicios
A partir de la versión 2.0 de SCDE se han desarrollado servicios que incorporan funcionalidades a algunos ya existentes. Se recomienda la integración con los nuevos, en lugar de los anteriores. En el siguiente punto se indica cuáles son
Servicios públicos
SCDE tiene un único servicio público ICertificateService que ofrece los siguientes métodos:
cancelOperation: cancelación de operaciones realizadas a través de SCDE.
createCertificate: creación de documentos certificados firmados con sello de órgano (obsoleto, se recomienda el uso de createCertificate1).
createCertificate1: creación de documentos certificados firmados con sello de órgano (evolución del createCertificate).
getStatus: control del proceso de creación de los documentos.
sendDocAuth: envío de un documento de autorización firmado (obsoleto, se recomienda el uso de sendDocAuth1).
sendDocAuth1: envío de un documento de autorización firmado (evolución del sendDocAuth).
sendDocAuthByCSV (obsoleto)
getDocByCSV
signDocs: firma de documentos creados por otras aplicaciones (obsoleto, se recomienda el uso de signDocs1).
signDocs1: firma de documentos creados por otras aplicaciones (evolución del signDocs)
getDcmi: consulta los datos de los campos de un documento PDF.
cancelOperation: cancela una operación.
signDocsWithoutDocAuth: firma de documentos con sello de órgano sin documento de autorización.
signDocsWithExternalDocAuth: firma de documentos con sello de órgano a partir del CSV del documento de autorización.
La dirección para poder acceder al servicio es: http://scde_core/services/certificate_service
ServiciosPrivados
En el servicio público ICertificateService existen también dos servicios privados que son llamados desde la propia aplicación, en su módulo ADMIN:
listCertificateOperations ¿PÚBLICO?
downloadCertificateDocument
Servicios CertificateService
Antes de empezar a describir cada servicio, cabe destacar una serie de elementos comunes a los mismos.
Elementos comunes
Códigos de estado
Los códigos indicativos de los diferentes estados en los que puede estar la aplicación son:
Código | Descripción |
|---|---|
CREATING_DOCS | Creando documentos. |
WAITING_DOC_AUT | Se han creado y guardado en Documentum los documentos solicitados en el método createCertificate, y se está esperando recibir la firma del documento de autorización mediante el método sendDocAuth. |
SIGNING_DOCS | Firmando documentos y archivando en Documentum |
END_OPERATION | La operación de firma ha sido realizada con éxito. |
OPERATION_TIMEOUT | La operación ha excedido el tiempo previsto para ser realizada. |
ERROR_GENERAL | Se ha producido un error general no especificado. |
ERROR_ID_OPERATION | Se ha enviado un identificador de operación no válido. |
ERROR_CREATING_DOCS | Se ha producido un error al crear documentos. |
ERROR_DOC_AUT | Se ha producido un error al firmar el documento de autorización. |
ERROR_SIGN_DOCS | Error al firmar y/o almacenar los documentos que debían ser firmados. |
CANCELLING_OPERATION | La operación está siendo cancelada y los documentos relacionados están siendo anulados. |
OPERATION_CANCELED | Se ha terminado de cancelar una operación. |
ParamBase
En las llamadas a los distintos servicios forma parte fundamental el ParamBase ya que se utiliza como contenedor de algunos de los valores clave en la autorización necesaria para utilizar los servicios proporcionados por el CORE y en la autorización para la consulta o modificación de los distintos estados de la aplicación Por ello todos los servicios son llamados con un parámetro que extiende de un ParamBase o incluye dentro del prototipo dicho parámetro.
Nombre | Tipo | Descripción |
|---|---|---|
applicationId | String | Código de aplicación que invoca al servicio |
NIF | String | NIF del usuario invocador |
Salvo que se indique lo contrario en el campo applicationId deberá ir el identificador de aplicación que quiera utilizar los servicios y en el campo nif el identificador fiscal del empleado público que realiza la petición. Las particularidades de los parámetros y de los tipos de resultados se especificarán al describir los servicios web con sus correspondientes métodos.
ResultGetStatus
Todos los métodos del servicio (excepto getMetadata) devuelven un objeto de clase ResultGetStatus, que contiene los siguientes atributos:
Nombre | Tipo | Descripción |
|---|---|---|
idOperation | String | Código de operación |
statusCode | String | Código del estado de la operación |
statusDescription | String | Descripción del estado de la operación |
docAuthCsv | String | CSV del documento de autorización |
docResumeCsv | String | CSV del documento resumen |
docCancelCsv | String | CSV del documento de cancelación |
signedCsvList | String[] | Lista de CSVs de documentos firmados |
signedBeforeCsvList | String[] | Lista de CSVs de documentos firmados en una petición anterior |
noSignedCsvList | String[] | Lista de CSVs de documentos no firmados |
extraInfo | FieldType[] | Información extra |
docCancelCsv | String | CSV del documento autorizando la cancelación |
Excepciones
Todos los métodos están configurados para lanzar excepciones de clase ScdeCoreException, que tiene los siguientes atributos:
Nombre | Tipo | Descripción |
|---|---|---|
Code | Long | Código que describe el tipo de error |
Msg | String | Mensaje asociado al tipo de error indicado en el código |
ExtraInfo | String | Posible información extra que se haya considerado oportuno indicar para localizar la causa del error |
Añadir códigos de error
Método ‘createCertificate’ (obsoleto)
Se recomienda la integración con el método createCertificate1. Método del servicio que permite crear documentos certificados y firmarlos con el sello de órgano enviado, y también permite solicitar que se cree un documento certificado de autorización de los documentos anteriormente creados. Los documentos a crear pueden ser enviados agrupados, y se les puede añadir metadatos simples, tanto a nivel individual, como comunes al grupo en el que se hallen incluidos, además de incluir los datos de cada documento para rellenar la plantilla seleccionada. Los metadatos enviados deberán estar incluidos en los metadatos asociados a un documento electrónico cuando se almacena en el sistema de gestión documental corporativo del Gobierno de Aragón.
Pueden ser indicados el nombre de la lista de control de acceso y la carpeta donde se quieren almacenar los documentos. Devuelve el estado de la operación o una excepción si ha fallado.
Signatura ResultGetStatus createCertificate(ParamCreateCertificate paramCreateCertificate) throws ScdeCoreException; Parámetros de invocación Los parámetros de entrada al servicio se encapsulan en un objeto ParamCreateCertificate, que extiende ParamBase y tiene los siguientes atributos: TABLA Parámetros de respuesta Los datos de salida del servicio se encapsulan en el objeto ResultGetStatus Códigos error Las excepciones del servicio son de tipo ScdeCoreException. Ejemplos de invocación En este ejemplo vamos a utilizar el servicio enviando los datos de 2 documentos agrupados en dos grupos, con unos metadatos comunes para los dos grupos, la plantilla utilizada tiene 3 campos para el nombre y los dos apellidos. En los tres primeros documentos enviaremos metadatos individuales. Le indicaremos que es necesario generar el documento de autorización.
2.1. Datos documento 1 2.2. Metadatos documento 1 2.3. Datos documento 2 2.4. Metadatos documento 2 2.5. Metadatos comunes 2.6. Encapsulamos los documentos 3.1. Agrupamos los documentos y añadimos los metadatos especiales comunes en cada grupo 3.2. Agrupamos en un array los grupos creados en el punto anterior
Si por el contrario usamos una plantilla existente en documentum (se indica el CSV):
Si todo ha ido correcto, el valor de STATUS_CODE será CREATING_DOCS. |
Método ‘createCertificate1’
Ofrece la misma funcionalidad que el createCertificate, y además, permite informar el agente aportador y el organismo productor para cada uno de los documentos a firmar. También permite que el documento de resumen de la operación se firme con el sello de órgano informado (en lugar del que tiene configurado SCDE por defecto). Se recomienda su uso en lugar del createCertificate.
Signatura ResultGetStatus createCertificate1(ParamCreateCertificate1 paramCreateCertificate1) throws ScdeCoreException; Parámetros de invocación Los parámetros de entrada al servicio se encapsulan en un objeto ParamCreateCertificate1, que extiende ParamBase y tiene los siguientes atributos: TABLA Parámetros de respuesta Los datos de salida del servicio se encapsulan en el objeto ResultGetStatus Códigos error Las excepciones del servicio son de tipo ScdeCoreException. Ejemplos de invocación En este ejemplo vamos a utilizar el servicio enviando los datos de 2 documentos agrupados en dos grupos, con unos metadatos comunes para los dos grupos, la plantilla utilizada tiene 3 campos para el nombre y los dos apellidos. En los tres primeros documentos enviaremos metadatos individuales. Le indicaremos que es necesario generar el documento de autorización.
2.1. Datos documento 1 2.2. Metadatos documento 1 2.3. Datos documento 2 2.4. Metadatos documento 2 2.5. Metadatos comunes 2.6. Encapsulamos los documentos 3.1. Agrupamos los documentos y añadimos los metadatos especiales comunes en cada grupo 3.2. Agrupamos en un array los grupos creados en el punto anterior
Si por el contrario usamos una plantilla existente en documentum (se indica el CSV):
Si todo ha ido correcto, el valor de STATUS_CODE será CREATING_DOCS. |
Método ‘getStatus’
Método del servicio que permite consultar el estado de ejecución de una petición creada con los métodos createCertificate, signDocs, sendDocAuth o cancelOperation. Devuelve el estado de la operación o una excepción si ha fallado.
Signatura ResultGetStatus getStatus(ParamGetStatus paramGetStatus) throws ScdeCoreException; Parámetros de invocación El parámetro de entrada al servicio es de tipo ParamGetStatus que extiende ParamBase. Su único atributo es un String con el código de la operación a consultar. Parámetros de respuesta Los datos de salida del servicio se encapsulan en el objeto ResultGetStatus Códigos error Las excepciones del servicio son de tipo ScdeCoreException. Ejemplos de invocación
Los posibles valores de STATUS_CODE devueltos por la aplicación serán: ERROR_GENERAL CREATING_DOCS, ERROR_CREATING_DOCS, WAITING_DOC_AUT SIGNING_DOCS, ERROR_DOC_AUT ERROR_SIGN_DOCS, END_OPERATION, ERROR_ID_OPERATION, OPERATION_TIMEOUT, CANCELING_OPERATION, OPERATION_CANCELED |
Método ‘sendDocAuth’ (obsoleto)
Se recomienda la integración con el método sendDocAuth1. Método del servicio que permite enviar la firma del documento de autorización existente, perteneciente a una operación generada en el servicio createCertificate. Devuelve el estado de la operación o una excepción si ha fallado.
Signatura ResultGetStatus sendDocAuth(ParamSendDocAuth paramSendDocAuth) throws ScdeCoreException; Parámetros de invocación El parámetro de entrada al servicio es de tipo ParamSendDocAuth que extiende ParamBase y contiene los siguientes atributos: Parámetros de respuesta Los datos de salida del servicio se encapsulan en el objeto ResultGetStatus Códigos error Las excepciones del servicio son de tipo ScdeCoreException. Ejemplos de invocación Para este ejemplo es necesario haber recuperado de Documentum, por medio del CSV, el documento de autorización. Una vez recuperado hay que firmarlo y elevar la firma a CAdES-A. Encapsulamos el identificador de operación en la que se ha generado el documento de autorización, la firma del documento ya elevada a CAdES-A y el identificador de la aplicación en un objeto ParamSendDocAuth e invocamos el servicio: Si no se produce una excepción, el valor de STATUS_CODE será SIGNING_DOCS |
Método ‘sendDocAuth1’
Ofrece la misma funcionalidad que el sendDocAuth, no sólo para una operación generada en el servicio createCertificate sino también en el createCertificate1. También permite que el documento de resumen de la operación se firme con el sello de órgano informado (en lugar del que tiene configurado SCDE por defecto). Se recomienda su uso en lugar del sendDocAuth.
Signatura ResultGetStatus sendDocAuth1(ParamSendDocAuth1 paramSendDocAuth1) throws ScdeCoreException; Parámetros de invocación El parámetro de entrada al servicio es de tipo ParamSendDocAuth1 que extiende ParamBase y contiene los siguientes atributos: Parámetros de respuesta Los datos de salida del servicio se encapsulan en el objeto ResultGetStatus Códigos error Las excepciones del servicio son de tipo ScdeCoreException. Ejemplos de invocación Para este ejemplo es necesario haber recuperado de Documentum, por medio del CSV, el documento de autorización. Una vez recuperado hay que firmarlo y elevar la firma a CAdES-A. Encapsulamos el identificador de operación en la que se ha generado el documento de autorización, la firma del documento ya elevada a CAdES-A y el identificador de la aplicación en un objeto ParamSendDocAuth e invocamos el servicio: Si no se produce una excepción, el valor de STATUS_CODE será SIGNING_DOCS |
Método ‘signDocs’ (obsoleto)
Se recomienda la integración con el método signDocs1. Método del servicio que permite firmar documentos generados por una aplicación externa. Para ello se enviará el CSV de un documento de autorización, es decir, un documento firmado y almacenado en el gestor documental del Gobierno de Aragón que tiene una relación de padre respecto a los documentos a firmar. El rol de dicha relación es REQUIERE. Es necesario introducir los parámetros que configuran el sello de órgano con el que poder firmar los documentos, así como los datos del titular de dicho sello. Junto al CSV se puede introducir también un texto que se es