En este apartado se describe cómo implementar los principales casos de uso que se pueden dar en la integración con CCSV
CU_001: Creación de un documento
A continuación se detallan los pasos que se han de realizar para la creación de un documento:
1.- Inicializar un documento
Es necesario iniciar el documento que posteriormente se mandara almacenar a CCSV, a continuación se detallan los pasos:
Detalle
Document document = new Document();
document.setCsv(csvdoc); // donde csvdoc contiene un CSV válido
document.setApplicationCode(applicationCode);
document.setApplicationName(applicationName); // no es obligatorio
document.setType(DocumentumConstants.TipoDocumental.DEA);
document.setName("Nombre Ejemplo");
document.setExtension("pdf");
document.setFormat(DocumentumConstants.Formato.PDF_A);
ParamInitializeDocumentMetadata paramInitializeDocumentMetadata = new ParamInitializeDocumentMetadata();
paramInitializeDocumentMetadata.setDocument(document);
paramInitializeDocumentMetadata.setDocumentType(DocumentumConstants.TipoDocumento.ACTA);
ResultInitializeDocumentMetadata resul = ccsvClient.initializeDocumentMetadata(paramInitializeDocumentMetadata);
if(resul.getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}else{
document = resul.getDocument();
Línea 02, asigna el Código Seguro de Verificación (CSV) este código debe generarse previamente con la última versión de la librería de generación de CSVs que se encuentra en el apartado Versiones y descargas de cliente CCSV de este manual, la siguiente llamada creará un código CSV:
ICSVGenerator generator = new CSVGenerator();
generator.generateCSV(codigo_aplicacion, a); // a =”00” si el codigo_aplicacion es de 3 caracteres y “0” si es de 4
Líneas 03 y 04, asocian el código y nombre de aplicación que se han definido previamente en CCSV para el control de acceso al servicio web.
Línea 05, el tipo documental indicado en la propiedad type del document ha de ser dga_paega_doc_dea cuyo valor está definido en la constante que se indica en el código (DocumentumConstants.TipoDocumental.DEA)
Línea 11, el tipo de documento (no confundir con tipo documental). Este puede tomar una serie de valores predeterminados. En el caso de querer un tipo de documento EXPEDIENTE, este se dará de alta mediante el método openAdministrativeFile del WS AdministrativeFileService ya que desde createDocument no está permitido. De igual modo si se requiere un documento de tipo INDICE_EXPEDIENTE este ha de ser generado a partir de un Expediente mediante el método regenerateAdministrativeFileIndex del WS AdministrativeFileService. Para conocer el listado de tipos de documentos actualmente activos debe consultarse el método getDocumentTypeList().
No vamos a meter en la propiedad content del document el contenido del fichero, ya que no se necesita para inicializar los metadatos.
Partimos del resultado de inicializar del apartado anterior.
Detalle
HashMap<String, Object> properties = resul.getDocument().getMetadata();
properties.put(DocumentumConstants.NombreMetadatos.PAEGA_IDENT_CSV,document.getCsv());
java.util.Calendar calendario = GregorianCalendar.getInstance();
java.util.Date fecha = calendario.getTime();
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss");
String date=sdf.format(fecha);
properties.put(DocumentumConstants.NombreMetadatos.PAEGA_IDENT_FECHA_CAPTURA, date);
properties.put(DocumentumConstants.NombreMetadatos.PAEGA_IDENT_ORIGEN,DocumentumConstants.Origen.ADMINISTRACION);
properties.put(DocumentumConstants.NombreMetadatos.PAEGA_DESC_ESTADO,DocumentumConstants.Estado.BORRADOR);
properties.put(DocumentumConstants.NombreMetadatos.PAEGA_DESC_TIPO_DOCUMENTO,DocumentumConstants.TipoDocumento.DECLARACION );
properties.put(DocumentumConstants.NombreMetadatos.PAEGA_VERIFICACION_RESUMEN, BASE64Encoder.encode(hash).toString());
document.setMetadata(properties);
Object[] relations = (Object[]) properties.get(DocumentumConstants.NombreMetadatos.PAEGA_RELACION);
for(Object ob :relations){
Document documentRelation = (Document) ob;
if (documentRelation.getMetadata().get(DocumentumConstants.NombreMetadatos.PAEGA_RELACION_ROL).equals(DocumentumConstants.RolRelacion.APORTADOR)){
Document documentAportador = (Document)
documentRelation.getMetadata().get(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE);
documentAportador.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_NTI_TIPO_ENTIDAD,DocumentumConstants.TipoEntidad.AGENTE);
documentAportador.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_NTI_TIPO_CATEGORIA,DocumentumConstants.CategoriaAgente.CIUDADANO);
documentAportador.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_IDENTIFICACION_TIPO_IDENTIFICACION,DocumentumConstants.TipoIdentificacion.NIF);
documentAportador.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_IDENTIFICACION_IDENTIFICACION,"44444444A");
documentAportador.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_DESCRIPCION_NOMBRE,"Mariano Lopez");
}else if(documentRelation.getMetadata().get(DocumentumConstants.NombreMetadatos.PAEGA_RELACION_ROL).equals(DocumentumConstants.RolRelacion.ORGANISMO_PRODUCTOR)){
Document documentOrganismo = (Document)documentRelation.getMetadata().get(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE);
documentOrganismo.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_NTI_TIPO_CATEGORIA,DocumentumConstants.CategoriaAgente.ORGANISMO);
documentOrganismo.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_IDENTIFICACION_TIPO_IDENTIFICACION,DocumentumConstants.TipoIdentificacion.CODIGO_ORGANISMO_SIU);
documentOrganismo.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_IDENTIFICACION_IDENTIFICACION,"44444444A");
documentOrganismo.getMetadata().put(DocumentumConstants.NombreMetadatos.PAEGA_AGENTE_DESCRIPCION_NOMBRE,"Desconocido");
}
}
Línea 02 , si al inicializar hemos pasado el document con la propiedad csv con valor, ya tendrá valor este metadato y no será necesaria esta línea.
Línea 07, los metadatos de tipo fecha tendrán que seguir el formato: "yyyy-MM-dd'T'HH:mm:ss".
Línea 09, existen 3 casos posibles:
Si no informamos de ningún “firmante propuesto” lo dejaremos como BORRADOR DocumentumConstants.Estado.BORRADOR
Si informamos de algún “firmante propuesto” para que el documento sea firmado desde PFI el estado será PENDIENTE_DE_FIRMA constante: DocumentumConstants.Estado.PENDIENTE_DE_FIRMA
Si vamos a adjuntar la firma lo dejaremos como ORIGINAL o COPIA constantes: DocumentumConstants.Estado.ORIGINAL o DocumentumConstants.Estado.COPIA
Línea 11, El hash “SHA1” del documento lo calculamos:
try{
MessageDigest md = MessageDigest.getInstance("SHA1");
}catch (NoSuchAlgorithmException e){
// tratar error
}
try{
byte[] byteDocument = IOUtils.toByteArray(dataHandler.getInputStream());// dataHandler contiene el documento
byte[] hash = md.digest(byteDocument);
}catch (Exception e)
// tratar error
}
Por defecto el metadato: DocumentumConstants.NombreMetadatos.PAEGA_VERIFICACION_ALGORITMO se inicializa con el valor de SHA-1, si se usa otro algoritmo habrá que modificar también ese metadato
Línea 14, recorremos las relaciones para dar valor a los metadatos no inicializados de éstas.
3.A- Archivar documento con firma
Se inicializa el documento tal como se indica en el apartado 1.- Inicializar un documento. Seguidamente rellenaremos los metadatos como se indica en el apartado 2.-Rellenar metadatos, teniendo en
cuenta que el metadato estado puede ser original o copia al crearse el documento a la vez que la firma.
Detalle
Ejemplo de creación de documento con una firma en cades A detached
ParamCreateAndVerifySignature paramCreateAndVerifySignature= new ParamCreateAndVerifySignature();
paramCreateAndVerifySignature.setDocument(document);
paramCreateAndVerifySignature.setSignatureType((int)com.tbsolutions.asf.util.Constants.CADES_FORMAT);
paramCreateAndVerifySignature.setCreateDocument(true);
paramCreateAndVerifySignature.setAttachedSignature(false); // no es necesaria esta línea ya que por defecto es false
paramCreateAndVerifySignature.setInitFormat(com.tbsolutions.asf.signatureserver.util.Constants.CADES_A);
paramCreateAndVerifySignature.setSignature(signature); // firma en dataHandler, en el caso de firma attached este
// parámetro iría vacío, la firma iría junto al documento dentro de la propiedad content del document.
ResultCreateAndVerifySignature resultCreateAndVerifySignature = ccsvClient.createAndVerifySignature(paramCreateAndVerifySignature);
if (resultCreateAndVerifySignature.getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}
Línea 03 , tendremos que indicar el formato de la firma.
Línea 04 , como estamos creando el documento tendremos que indicar true.
Línea 05 , si estuviésemos creando una firma attached esta propiedad tendría que ser true.
Línea 06 , tendremos que indicar el subformato de la firma. En el caso de firmas Xades y Cades el subformato mínimo será T .
Línea 07 , indicamos firma en dataHandler, en el caso de firma attached este parámetro iría vacío, ya que la firma iría junto al documento dentro de la propiedad content del document.
Este método puede elevar la firma y almacenarla elevada. Cuando queramos elevar la firma bastará con informar la propiedad finalFormat con el subformato deseado. El valor por defecto es 0 que es no elevarla.
En el caso de que el proceso de firma falle en algún momento ya sea por error de firma, porque no coincida la firma con el documento firmado, o porque los metadatos del documento no son correctos; no es necesario hacer rollback ya que el documento no se llegará a crear ni como firmado ni como borrador.
3.B.- Archivar documento y posteriormente su firma
Se inicializa el documento tal como se indica en el apartado 1.- Inicializar un documento. Seguidamente rellenaremos los metadatos como se indica en el apartado 2.-Rellenar metadatos teniendo en
cuenta que el metadato estado no puede ser original o copia al no crearse a la vez que la firma. Y será después de crear la firma cuando le cambiemos el estado con el método changeState.
Detalle
En primer lugar creamos el documento
ParamCreateDocument paramCreateDocument = new ParamCreateDocument();
paramCreateDocument.setDocument(document);
ResultCreateDocument resultCreateDocument = ccsvClient.createDocument(paramCreateDocument);
if (resultCreateDocument.getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}
Cuando ya esté creado el documento se le ha de aportar la firma:
String documentId = resultCreateDocument.getId();
// Creamos una firma Cades A detached asociada al anterior documento
ParamCreateAndVerifySignature paramCreateAndVerifySignature= new ParamCreateAndVerifySignature();
paramCreateAndVerifySignature.setSignatureType((int)com.tbsolutions.asf.util.Constants.CADES_FORMAT);
paramCreateAndVerifySignature.setCreateDocument(false); // esta línea no es necesaria, por defecto no crea el documento
paramCreateAndVerifySignature.setAttachedSignature(false);// esta línea no es necesaria, por defecto es detached
paramCreateAndVerifySignature.setInitFormat(com.tbsolutions.asf.signatureserver.util.Constants.CADES_A);
paramCreateAndVerifySignature.setSignature(signature); // firma en dataHandler
ResultCreateAndVerifySignature resultCreateAndVerifySignature =ccsvClient.createAndVerifySignature(paramCreateAndVerifySignature);
if (resultCreateAndVerifySignature.getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}
Línea 4 , tendremos que indicar el formato de la firma.
Línea 5 , como no estamos creando el documento no es necesaria esta línea al ser el valor false por defecto.
Línea 6 , si estuviésemos creando una firma attached esta propiedad tendría que ser true, en cuyo caso no tendríamos que generar firma ni hacer el set de la firma (línea 13).
Línea 7 , tendremos que indicar el subformato de la firma. En el caso de firmas Xades y Cades el subformato mínimo será T .
Modificamos el estado del documento
ParamChangeState paramChangeState= new ParamChangeState();
paramChangeState.setCsv(docPapiro.getCsv());
paramChangeState.setState(DocumentumConstants.Estado.ORIGINAL);
ResultChangeState resultChangeState=ccsvClient .changeState(paramChangeState);
if (resultChangeState .getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}
CU_002: Eliminar documento en estado borrador
En ocasiones puede darse el caso que deseemos borrar un documento que se ha quedado en estado Borrador. No siempre se querrá realizar esto ya que puede que al firmar nos hayamos equivocado de firma, un error en algún metadato, o simplemente que queremos dejarlo en ese estado por algún otro motivo.
Para ello lanzaremos el siguiente código:
Detalle
String documentId = resultCreateDocument.getId();
ParamDeleteDocument paramDeleteDocument = new ParamDeleteDocument();
paramDeleteDocument.setId = documentId;
ResultDeleteDocument resultDeleteDocument = ccsvClient.deleteDocument(paramDeleteDocument);
if (resultDeleteDocument.getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}
CU_003: Creación de un expediente
Para abrir un Expediente primero lo inicializaremos, seguidamente crearemos su relación con rol “aportador” y por último abriremos el expediente:
1.- Inicializar Expediente
Detalle
AdministrativeFile adminFile;
ParamInitializeAdministrativeFileMetadata paramInitializeAdminFileMetadata = new ParamInitializeAdministrativeFileMetadata();
paramInitializeAdminFileMetadata.setApplicationCode(applicationCode);
paramInitializeAdminFileMetadata.setApplicationName(applicationName);
paramInitializeAdminFileMetadata.setDescription("Descripcion Expediente");
paramInitializeAdminFileMetadata.setName("Nombre Expediente");
paramInitializeAdminFileMetadata.setNumber("num Exp");
paramInitializeAdminFileMetadata.setType("tipo expediente");
paramInitializeAdminFileMetadata.setDate(new Date());
ResultInitializeAdministrativeFileMetadata resul = ccsvClient.initializeAdministrativeFileMetadata(paramInitializeAdminFileMetadata);
if (resul .getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}else{
adminFile = resul.getAdministrativeFile();
}
Líneas 3 y 4, se indican el código y nombre de aplicación que se han definido previamente en CCSV para el control de acceso al servicio web.
Línea 14, el objeto que devuelve tendrá todos los metadatos inicializados necesarios para crear el expediente excepto la relación de aportador. El Gestor de Expedientes ya le ha generado un CSV y se lo ha asignado.
En principio como hemos inicializado el expediente ya tenemos todos los metadatos obligatorios excepto la relación aportador:
Detalle
Crear relación aportador
AgentRelationship agentRelationship= new AgentRelationship();
Agent agent= new Agent();
agent.setCategory(DocumentumConstants.CategoriaAgente.CIUDADANO);
agent.setEntityType(DocumentumConstants.TipoEntidad.AGENTE);
agent.setIdentificationNumber("23000000T");
agent.setIdentificationType(DocumentumConstants.TipoIdentificacion.NIF);
agent.setName("el nombre del aportador");
agentRelationship.setAgent(agent);
agentRelationship.setCategory(DocumentumConstants.Categoria.RELACION_AGENTE);
agentRelationship.setEntityType(DocumentumConstants.TipoEntidad.RELACION);
agentRelationship.setRole(DocumentumConstants.RolRelacion.APORTADOR);
adminFile.setMetadata(AgentRelationshipUtils.addAgentRelationship(adminFile.getMetadata(), agentRelationship));
Línea 01 y 02, en las propiedades de las clases AgentRelationship y Agent indicamos los metadatos de estas estructuras de las relaciones y agentes que luego con la ayuda de AgentRelationshipUtils en la línea 12, transformamos a la estructura normal de metadatos con objetos HashMap y Document.
Línea 12, metemos la relación de aportador a los metadatos ya inicializados del objeto adminFile.
3.- Abrir Expediente
Para abrir un expediente lo óptimo es crear previamente un documento con su firma (CU_001 de este manual). Una vez creado llamaremos al openAdministrativeFile. No se puede abrir un expediente con un documento que no tenga el estado como original o copia.
Detalle
ParamOpenAdministrativeFile paramOpenAdministrativeFile = new ParamOpenAdministrativeFile();
paramOpenAdministrativeFile.setAdminFile(adminFile);
paramOpenAdministrativeFile.setAdminFileContentCsv(csv);
paramOpenAdministrativeFile.setFolderId(folderId)
paramOpenAdministrativeFile.setAclName(aclName);
ResultOpenAdministrativeFile result = ccsvClient.openAdministrativeFile(paramOpenAdministrativeFile);
if (resul .getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}
Línea 03, se indica el Código Seguro de Verificación (CSV) del Documento contenido en el expediente.
Línea 04, se indica el id de la carpeta del gestor documental donde queremos que cree el expediente.
Línea 05, se indica el nombre de las acl (lista de control de acceso).
CU_004: Añadir documentos a un expediente
Añadir un documento
Añadir un documento a un expediente
Detalle
ParamAddDocumentToAdminFile paramAddDocumentToAdminFile = new ParamAddDocumentToAdminFile();
paramAddDocumentToAdminFile.setCsv(adminFile.getCsv());
paramAddDocumentToAdminFile.setContentCsv(csv);
ResultAddDocumentToAdminFile result = ccsvClient..addDocumentToAdminFile(paramAddDocumentToAdminFile);
if (resul .getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}
Línea 02, se indica el Código Seguro de Verificación (CSV) del expediente creado previamente.
Línea 03, se indica el Código Seguro de Verificación (CSV) del documento que queremos que contenga el expediente ya creado en CCSV.
Añadir varios documentos
Añade varios documentos a la vez a un expediente
Detalle
ParamAddDocumentsToAdminFile paramAddDocumentsToAdminFile = new ParamAddDocumentsToAdminFile();
paramAddDocumentsToAdminFile.setCsv(adminFile.getCsv());
String[] contentsCsv= new String[numDocs];
contentsCsv[0] = csv0;
contentsCsv[1] = csv1; // ... El número de documentos que deseemos añadir
paramAddDocumentsToAdminFile.setContentsCsv(contentsCsv);
ResultAddDocumentsToAdminFile result = ccsvClient..addDocumentsToAdminFile(paramAddDocumentsToAdminFile);
if (resul .getReturnCode().equals(ReturnCode.ERROR)){
// tratar el error
}
Línea 02, se indica el Código Seguro de Verificación (CSV) del expediente creado previamente.
Línea 03, se crea un objeto array de String con los Códigos Seguros de Verificación (CSV) de los documentos que queremos que contenga el expediente, todos ellos ya creados en CCSV.
CU_005: Anular un documento
Anular un documento
Para anular un documento se debe cambiar el estado del documento a “A” a través del método changeState
Detalle
ParamChangeState param = new ParamChangeState();
param.setApplicationId("CCSV");
param.setNif("00000000T");
param.setCsv(CSV00000000000CCSV);
param.setState("A");
ResultChangeState result = documentMetadataSignatureWS.changeState(param);
Una vez anulado el documento, se dejara de mostrar en los expedientes que estuviera asociado y un proceso nocturno se encargara de sacarlo de los mismos.
Un documento anulado no podrá volver ser a consultado ni modificado
En caso de consultar el documento anulado se devolverá error:
Código | Mensaje |
|---|
732 | No se puede recuperar un documento anulado |
CU_006: Sustituir un documento anulado
Sustituir un documento
Para sustituir un documento se debe cambiar el estado del documento que se va a anular a “A” a través del método changeState y después se debe crear la relación SUSTITUYE entre el documento anulado y el documento que lo sustituye:
Detalle
Anulamos el documento
ParamChangeState param = new ParamChangeState();
param.setApplicationId("CCSV");
param.setNif("00000000T");
param.setCsv(CSV00000000000CCSV);
param.setState("A");
ResultChangeState result = documentMetadataSignatureWS.changeState(param);
Una vez anulado el documento, se debe crear la relación SUSTITUYE con el documento sustituto:
ParamCreateRelationship param;
ResultCreateRelationship result;
DocumentRelation relationship;
HashMap<String, Object> metadata;
param = new ParamCreateRelationship();
param.setApplicationId("CCSV");
param.setNif("00000000T");
param.setCsvChild("CSV0000000000000CCSV"); //Documento que se anula
param.setCsvParent("CSV1111000000000CCSV""); //Documento que prevalece
relationship = new DocumentRelation();
relationship.setRole(DocumentumConstants.RolRelacionDoc.SUSTITUYE);
relationship.setDateStart("2020/09/25T15:0000");
param.setRelationship(relationship);
result = documentMetadataSignatureWS.createRelationship(param);
Una vez realizada la sustitución se dejara de mostrar el documento anulado en los expedientes y, un proceso nocturno se encargara de sacar de los expedientes los documentos anulados y asociar el documento que los sustituye.
En caso de consultar un documento anulado que ha sido sustituido se mostrara el error:
Código | Mensaje |
|---|
733 | El documento ha sido anulado y sustituido por el documento: CSVD56NYVC89Z1B0BENT |
Obtener el CSV del documento sustituto
Para obtener el CSV del documento que sustituye a un documento anulado, podemos hacerlo a través del método getSubstituteDocument:
Detalle
Código | Mensaje |
|---|
148 | [CCSV] No se han encontrado documentos relacionados para el documento seleccionado |
