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:
Expand |
---|
|
Code Block |
---|
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(paraminparamInitializeDocumentMetadata);
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:
Code Block |
---|
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) Linea 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 regeneratedAdministrativeFileIndex 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.
Expand |
---|
|
Code Block |
---|
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,25 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 además de algún “firmante propuesto” se adjunta 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:
Code Block |
---|
try{
MessageDigest md;
try{md = MessageDigest.getInstance("SHA1");
}catch (NoSuchAlgorithmException e){
// tratar error
}
try{
error } 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 metadado metadato estado puede ser original o copia al crearse el documento a la vez que la firma.
Expand |
---|
|
Ejemplo de creación de documento con una firma en cades A detached Code Block |
---|
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 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 metadado metadato estado no puede ser original o copia al no crearse a la vez que la firma.
Y será después de crearle crear la firma cuando le cambiemos el estado con el método changeState.
Expand |
---|
|
En primer lugar creamos el documento Code Block |
---|
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: Code Block |
---|
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 Code Block |
---|
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:
Expand |
---|
|
Code Block |
---|
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
Expand |
---|
|
Code Block |
---|
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.
|
2.- Rellenar metadatos obligatorios y agentes
En principio como hemos inicializado el expediente ya tenemos todos los metadatos obligatorios
excepto la relación aportador:
Expand |
---|
|
Crear relación aportador Code Block |
---|
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 a través del Gestor Documental(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.
Expand |
---|
|
Code Block |
---|
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
Expand |
---|
|
Code Block |
---|
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 el Gestor DocumentalCCSV.
|
Añadir varios documentos
Añade varios documentos a la vez a un expediente
Expand |
---|
|
Code Block |
---|
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 el Gestor DocumentalCCSV.
|
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
Expand |
---|
|
Code Block |
---|
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:
Expand |
---|
|
Anulamos el documento Code Block |
---|
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: Code Block |
---|
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:
...