diff --git a/doc/src/technical/guia-integracion-terceiros/costcategories.png b/doc/src/technical/guia-integracion-terceiros/costcategories.png new file mode 100644 index 000000000..18e2f0255 Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/costcategories.png differ diff --git a/doc/src/technical/guia-integracion-terceiros/criterions.png b/doc/src/technical/guia-integracion-terceiros/criterions.png new file mode 100644 index 000000000..7297c4646 Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/criterions.png differ diff --git a/doc/src/technical/guia-integracion-terceiros/guia-integracion-terceiros.rst b/doc/src/technical/guia-integracion-terceiros/guia-integracion-terceiros.rst new file mode 100644 index 000000000..e73a3d98c --- /dev/null +++ b/doc/src/technical/guia-integracion-terceiros/guia-integracion-terceiros.rst @@ -0,0 +1,1251 @@ +NavalPlan: Guía de integración +============================== + +A guía de integración de NavalPlan detalla as posibilidades existentes para a integración entre aplicacións co software NavalPlan. + +As funcionalidades de integración da ferramenta para a Xestión da Producción permitirán a compartición de datos entre as distintas ferramentas existentes en cada empresa. NavalPlan define unha serie de formatos de intercambio de información empregando a sintaxe XML. A descrición das interfaces e formatos de intercambio son totalmente abertos e está dispoñible a súa implementación para incorporar novas posibilidades de integración se fose necesario. + +Visión Global +============= + +NavalPlan é unha aplicación que ten coma núcleo de funcionalidades a xestión da planificación e control dunha empresa. NavalPlan traballa cun conxunto de datos enfocado a xestión de recursos para a realización de tarefas permitindo a súa planificación e control. Aínda que NavalPlan permite xestionar o proceso de forma autónoma é necesario provelo de mecanismos de intercambio que permitan a incorporación de información recollida por outras aplicacións xa existentes nas empresas usuarias de NavalPlan. + +As empresas que teñen unha certa implantación de sistemas de xestión deberían permitir incorporar a información dos mesmos para facer máis rico e sinxelo o traballo co planificador. As entidades que teñen unha utilidade fóra do planificador son: + + * Os *recursos* que soen ser utilizados nas aplicacións de xestión de persoal e nóminas. + * Os *pedidos* que son empregados nas ferramentas de presupostación e xestión de ventas. + * Os *partes de traballo* que recollen o traballo feito polos traballadores e que son empregados para o control dos mesmos e a elaboración das súas nóminas. + +Estes elementos son empregados directamente no planificador, xa que os pedidos organízanse en tarefas, que son asignadas a recursos e logo a súa execución é controlada a través dos partes de traballo e a súa vez faise un análise de custos. + +NavalPlan permite a integración en dous escenarios: + + * Integración con outras aplicacións: permitindo a incorporación de datos de programas desenvoltos por terceiros. Isto será posible empregando as Interfaces Públicas da Aplicación (API) dispoñibles. A API de NavalPlan permite a interacción coas seguintes entidades propias: recursos, pedidos e partes de traballo, aínda que incorporan outras entidades de interese coma materiais, etiquetas, criterios, categorías de custo e tipos de horas. + * Integración con outras instancias de NavalPlan: permitindo operacións que deixen compartir información entre distintas empresas centrándose no proceso de subcontratación e reporte de avances do subcontratista. + + +Integración con outras aplicacións da propia empresa +---------------------------------------------------- + +NavalPlan permite a integración con outras aplicacións, NavalPlan poderá incorporar información procedente de outras aplicacións empregando un formato de intercambio común que será recibido por un servizo web que permitirá realizar actualizacións de datos ao longo do tempo. + +Esta integración deberá ser configurada mediante a habilitación dun usuario que terá permiso de acceso para cada un dos servizos que é de interese integrar, as aplicacións poderán chamar aos servizos empregando o nome de usuario e contrasinal e NavalPlan procesará a incorporación dos datos enviados. En caso de que ocorran erros na incorporación de datos na resposta da petición incorporarase a información dispoñible sobre o erro. + +A integración dentro da empresa permite unha integración forte con distintas aplicacións que poderán chamar en calquera momento aos servizos web para a actualización de datos. + + +Integración entre aplicacións NavalPlan de distintas empresas +------------------------------------------------------------- + +NavalPlan ten sido concibido coma un software que permita a realación con distintas empresas que empreguen a aplicación. O escenario principal de colaboración entre empresas é a contratación entre as mesmas, dentro do proceso de planificación é normal a situación que varias empresas colaboren nun mesmo proxecto sendo unha a contratista principal e outras subcontratistas desta. + +NavalPlan ten desenvolto un sistema de intercambio de información que permite remitir a información das tarefas a subcontratar a outras empresas e recibir os reportes de avance dos proxectos subcontratados. + +Esta integración a nivel aplicación precisa da existencia de usuarios cruzados entre as empresas subcontratante e subcontratista. Esta configuración permitirá que as aplicacións se poidan comunicar a información en tempo real. + +Nota: esta integración tamén será posible con outras aplicacións sempre e cando estas empreguen o mesmo formato de intercambio e as aplicacións implementen os servizos de intercambio necesarios. + + +Fundamentos técnicos +==================== + +Servizos WEB +------------ + +Un *servizo web* defínese como un mecanismo de comunicación que se establece entre dous programas a través dunha rede utilizando como protocolo de transporte das mensaxes *HTTP*. Na comunicación que se establece os dous programas que se comunican desempeñan ambos papeis: + + * Un dos programas leva a cabo o papel de *cliente*. É cliente o programa que inicia a comunicación e pide que o programa invocado execute unha determinada operación. + * O outro desempeña o papel de *servidor*. É o programa que ofrece unha serie de operacións aos clientes. Espera a recepción de peticións de operacións e cando lle chegan execútaas proporcionándolle ao programa cliente unha resposta sobre a operación. + +As razóns que levaron á elección de servizos web como vehículo de comunicación para levar a cabo a integración son as seguintes: + + * Por unha banda, os servizos web utilizan o protocolo HTTP como transporte, que é o que usa a WWW. Debido a que practicamente en todas as redes de ordenadores está permitido o acceso á WWW, os firewalls das corporacións non filtran o porto no que se serve a web, e de forma transparente a integración de NavalPlan con outra instalación do programa en outra empresa ou con outras aplicacións dentro da compañía funcionaría. + * Permiten a definición de mensaxes estruturados en XML - non son protocolos binarios de comunicación - de forma que é sinxelo entender as mensaxes de intercambio se o XML se define de forma acorde ao *modelo de dominio*. + * É unha tecnoloxía amplamente probada. + * É independente da linguaxe de programación. Isto permite que aínda que NavalPlan está desenvolvido utilizando a plataforma Java póidanse realizar clientes en distintas tecnoloxías como .NET, C, C++ maximizando as capacidades de integración e facilitándoa. + +Dentro dos servizos web existen dous grandes subtipos: Os servizos web baseados en *SOAP* e os servizos web *REST*. + +A grandes trazos os servizos web baseados en *SOAP* utilizan como corpo das mensaxes que se intercambias mensaxes *XML* que seguen o estándar *SOAP*. Ademais de *SOAP* son servizos que usan outra serie de estándares relacionados coñecidos como a pila WS (WS-Security, WS-Notification, WSDL). + +Os servizos web REST (REpresentational State Transfer) usan as operacións do protocolo HTTP (POST, PUT, DELETE e GET) para especificar parte das operacións e non poñen restricións acerca do corpo das mensaxes. Poden ser XML ou non e, se son XML, non teñen que cinguirse ao estándar *SOAP*. + +En NavalPlan os servizos web nos que se baseará a integración serán servizos *REST*. As razóns da elección de servizos REST son as seguintes: + + * Son máis sinxelos de implementar que os servizos *SOAP*. Isto facilita aos usuarios que queiran integrarse con NavalPlan o proceso, xa que o desenvolvemento e a depuración é máis sinxela. + * Unicamente son máis directos de implementar os servizos web *SOAP* se se utilizan ferramentas automáticas (que existen en linguaxes como Java ou .NET) que a partir da descrición dos servizos (WSDL) son capaces de xerar os clientes. Agora ben, esta vantaxe descartouse para a elección do tipo de servizos web a implementar porque se quere que, no caso de que non exista integración automática e os XML de intercambio de datos se xeren a man ou ben a partir dunha base de datos pero sen ter que programarse o cliente *SOAP*, esta integración siga sendo posible. + +Invocar un servizo web REST de NavalPlan será tan sinxelo como cun cliente HTTP (como pode ser simplemente o navegador para algunhas operacións) invocar unha URL. + +Seguridade +---------- + +Os servizos web REST de que constará NavalPlan para a integración contemplan un soporte de seguridade. A seguridade trátase en 3 dimensións: + + * Seguridade da comunicación. + * Autenticación do cliente. + * Autorización do cliente con respecto á operación invocada. + + +Seguridade da comunicación +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A seguridade da comunicación refírese a garantir que as mensaxes que se intercambian entre unha instalación de NavalPlan e os seus clientes (que pode ser outra aplicación ou outra instalación de NavalPlan realizada noutra compañía) sexan confidencias entre os dous extremos da comunicación. Quere dicir isto que, como pode que atravesen redes públicas - integración a través de Internet -, están suxeitas a poder ser examinados por todas as persoas ou axentes que teñan acceso ao medio. Para evitar, por tanto, que ao examinar o medio se obteña información privada das empresas que manteñen a comunicación con NavalPlan este proporciona un mecanismo de seguridade. + +A seguridade consiste na posibilidade de servir cifrados os datos e a elección feita para realizar o cifrado é servir os servizos web por HTTPS (HTTP Secure) en lugar de por HTTP. HTTPS é a combinación de HTTP con SSL. Con SSL conséguese por una parte garantir a identidade do servidor NavalPlan e, por outra banda, cifrar a comunicación entre o servidor e o cliente. + +Servir os servizos web con HTTPS pódese facer tanto dende o contedor de Servlets necesario para servir a aplicación (Apache Tomcat, Jetty) como se se serve detrás dun proxy que realice o cifrado por HTTPS (por exemplo detrás dun servidor web Apache). En calquera caso, será necesario que a empresa posúa un *certificado público* que permita servir por HTTPS os servizos web e/ou a aplicación. + + +Autenticación do cliente +~~~~~~~~~~~~~~~~~~~~~~~~ + +O proceso de autenticación consiste en determinar quen é a persoa ou entidade que quere efectuar unha operación ofrecida por un servizo web. + +A aplicación NavalPlan conta con autenticación a través da súa interface web. Está desenvolvido un módulo de usuarios que permite a alta, baixa de usuarios e a configuración dos permisos que poden posuír. Existe un conxunto predefinido de roles e estes roles se poden outorgar/denegar aos diferentes usuarios. Un rol permite realizar un determinado conxunto de operacións. + +Para a autenticación nos servizos web proponse reutilizar o sistema de usuarios de forma que para que o servidor vaia a proporcionar unha resposta haberá un paso de autenticar ao peticionario. Por tanto as aplicacións que se desexen integrar con NavalPlan terán que ter creadas na aplicación un usuario coas credencias adecuadas para invocar as operacións desexadas. + +Para identificar o peticionario vaise usar a autenticación Basic Access Authentication HTTP. Con este método de autenticación pode pasarse un usuario/contrasinal ao servidor web. Pásase cunha cabeceira na mensaxe HTTP. O formato é o seguinte: + + * Authentication: Basic [usuario:contrasinal codificados en base64] + +A codificación base64 unicamente é para ocultar o usuario:contrasinal da vista do usuario, pero non ten por obxecto evitar a súa lectura, xa que a súa conversión a formato lexible por humano é directa algoritmicamente. Á pregunta de como se garante, polo tanto, que o usuario:contrasinal sexan interceptados por un terceiro na rede de comunicación a resposta é a través da seguridade da comunicación. O protocolo HTTPS establece un medio cifrado entre o servidor e o cliente de forma que as mensaxes HTTP completas van cifradas (incluíndo as cabeceiras). + + +Autorización do cliente respecto á operación invocada +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unha vez se é capaz de identificar o peticionario da operación do servizo web, é necesario autorizalo ou denegarlle o acceso. Na aplicación web que forma parte de NavalPlan a autorización faise utilizando o framework *Spring Security*. A través deste framework é posible de forma declarativa esixir a posesión de un rol para acceder a unha determinada operación. + +Os servizos web se identifican por URL e método HTTP. Exemplos diso son: + + * */ws/rest/orderelements* Method GET + * */ws/rest/criteriontypes* Method POST + +Con Spring Security é posible esixir que para que un usuario teña acceso a unha URL ou outra estea autenticado e teña o rol requirido. Exemplos: + +:: + + + + + +Desta maneira garántese que o usuario peticionario do servizo ten as credencias adecuadas para a súa invocación. + + +Conceptos xerais e políticas globais +==================================== + +Nesta sección detállase unha serie de asuncións e requisitos que se deberán cumprir para ter unha boa integración con NavalPlan. Nesta sección se tratarán as seguintes temáticas: + + * Codificación das entidades + * Comportamentos das altas e actualizacións + * Control de erros e recuperación + + +Codificación das entidades +-------------------------- + +En todos os fluxos de integración de entidades, cada un dos obxectos que se transmiten dunha aplicación a outra terán unha codificación. Desta forma un obxecto terá un identificador alfanumérico que o identifique tanto na aplicación de NavalPlan coma no resto das aplicacións que se integren. + +As entidades que participan na integración terán un atributo *code*, no que se gardará a codificación. A existencia deste código e o seu mantemento é necesario para a correcta integración. O código debe ser único por entidade. Aínda que as entidades suxeitas a integración con outras aplicacións teñen este atributo *code* único dentro de NavalPlan para todas as entidades utilizarase un identificador subrogado autoxerado polo framework de persistencia. + +NavalPlan á hora de comunicarse con outras aplicacións recibirá os obxectos e cotexará a existencia dentro do sistema de obxectos de NavalPlan. Se se recibe un obxecto cunha codificación existente entendese que é unha actualización do mesmo, se o obxecto que se recibe non existe no sistema NavalPlan darao de alta. + +No caso de que se incorporen entidades con referencias a outras entidades entón na importación comprobarase se existe esta entidade referenciada e se non existe darase un erro. Un exemplo disto sería cando se realice a importación dun traballador e se fai referencia ao calendario que se lle quere asignar. Se non existe, indicarase que non se atopa a instancia. + +A incorporación mediante ficheiro XML supón a introdución dunha secuencia de _ítems_ que se van a ir procesando secuencialmente. Esta secuencia de ítems estará formada polas entidades que se incorporan a aplicación. Para identificar as entidades que se transmiten NavalPlan empregará unha codificación baseada en dous parámetros: + + * A posición da instancia no XML. Chamarase *num_item* + * A codificación baseada no código. Chamarase *code* + * O tipo de entidade da instancia. Chamarase *entity-type* + +No caso de que unha instancia referencie a unha terceira da cal non se dispón do código dado de alta no sistema, NavalPlan reportará un erro de importación indicando o num_item e a codificación da entidade que produciu o erro de importación. + +Resumo da codificación da identificación das instancias: + + * *instance-id*: identificación da instancia, estará formada por: *num_item*, *code* e *entity-type*. + * *num_item*: identifica cun número a posición da entidade dentro do ficheiro XML de importación. Ten a utilidade de permitir localizar a instancia que provocou un erro. + * *code*: será unha codificación alfanumérica con características de unicidade dentro das instancias dunha mesma entidade (*entity-type*). Este código será común as aplicacións que se estean a integrar. + * *entity-type*: será posible identificar que tipo de entidade representa unha instancia mediante o seu *entity-type*. Exemplo: resource, work-report, label. + +Espazo de nomes e codificación na relación con terceiras empresas +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No caso de integración de servizos dentro da mesma empresa partimos da existencia e control dunha unicidade de código dentro da organización. Iso non se pode presupoñer cando nos referimos á situación de relación entre dúas empresas. Nese caso NavalPlan manterá unha referencia dobre sobre as instancias de entidades que son compartidas entre dúas organizacións. + +NavalPlan respectará a codificación das entidades da empresa subcontratante e será a empresa subcontratista a que manteña ao longo de todas as comunicacións a referencia ás entidades reportadas pola empresa subcontratante. Esta relación manterase no caso das entidades relacionadas cos pedidos como é o caso de Order e OrderElement. Nesas entidades incorporarase un novo atributo *external-code* que fará referencia ao atributo *code* da entidade contratante. + +Internamente a empresa subcontratista traballará coa súa codificación propia no atributo *code* que será empregada na interacción coas outras aplicacións da propia empresa. + +Comportamentos das altas e actualizacións +----------------------------------------- + +A aplicación NavalPlan permitirá realizar unha alta a través de bloques de entidades. A semántica que se adoptará nestas incorporación de conxuntos de entidades será a seguinte. Realmente a operación non é unha alta senón que vai a ser unha alta ou modificación. Isto significa que cando se leva a cabo a incorporación se segue o seguinte algoritmo: + + 1. Compróbase se existe a entidade do bloque a inserir. + #. Se non existe a entidade, entón procédese a levar a cabo a alta. + #. Se existe a entidade, entón procédese a levar a cabo unha modificación da mesma. + +Unha vez que procede a levar a cabo a alta ou modificación, realízase outro proceso, detallado polos seguintes pasos: + + 1. Inténtase construír a entidade a dar de alta ou modificar a través da procura das entidades referenciadas. + #. Se non se pode construír a entidade por problemas en si mesma ou ben nas entidades referenciadas darase un erro indicando cal é o problema. + #. Se se consegue construír a entidade, entón procédese a pasar as validacións - regras de negocio - que os datos das entidades deben verificar. Se se producen un ou varios non cumprimentos repórtanse. + #. Se non se produce ningunha violación lévase a cabo a inserción ou modificación. + +Para estas operacións de alta ou modificación vaise a utilizar un servizo web identificado a través dunha URL e o método de HTTP POST. + +Con respecto a operación de borrado, non se vai a contemplar a súa existencia de maneira xeral. A razón é que o borrado de datos de planificador dunha entidade en xeral ten efectos en cascada sobre múltiples datos das planificacións levadas a cabo nel. Por tanto, a estratexia xeral de nunca borrar fisicamente os datos é a axeitada. Isto non impide que para algunhas entidades teña sentido operacións como a súa desactivación. Isto faría que non se borrara fisicamente a entidade da base de datos senón que deixara de terse en conta a partir dese momento para as novas operacións de planificación nas que estea involucrada. + +Control de erros +---------------- + +Uso dos códigos de estado HTTP nas respostas +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As mensaxes de resposta HTTP conteñen unha liña que se coñece como liña de estado. O formato da liña de estado é a seguinte: + +:: + + Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF + +Como se pode apreciar existe un campo que é o código de estado, *Status-Code*. O código de estado é un numero de 3 díxitos que se usa para indicar como foi satisfeita a petición por parte do servidor web. Existen un conxunto de estados predefinidos que indican causas comúns que poden acontecer cando se invoca unha URL por parte dun cliente. + +NavalPlan vai a facer o seguinte uso dos códigos de estado das respostas HTTP: + + 1. *200 OK*. Se a petición é servida correctamente. Os erros lóxicos froito dos datos de entrada do servizo tamén se reportarán mediante este código. Xa que o cliente poderá procesalos para analizar as causas dos erros. + #. *404 Not Found*. Este código de estado non se vai a devolver por parte de ningún servizo web de NavalPlan. Será devolto unicamente polo contedor de servlets se o cliente invoca unha URL que non se corresponde con ningún dos servizos publicados. + #. *403 Access is denied*. Este código de estado será devolto por NavalPlan cando a autenticación do usuario é correcta no sistema de usuarios da aplicación pero non ten permiso para executar o servizo que se está solicitando. + #. *401 Bad credentials*. É utilizado na resposta por NavalPlan para indicar que a autenticación é incorrecta. Quere dicir o anterior que non existe un usuario/contrasinal válido. + #. *500 Internal Server Error*. Devólvese este código de estado sempre que se produce algún erro provocado por unha excepción que provoque a finalización do fío de execución (thread) no servidor que atende a petición do servizo. + #. *400 Bad Request*. Darase este erro cando a validación do corpo da petición XML por parte do servizo web de NavalPlan non sexa correcta por non axustarse ao esquema XML que describe o servizo. + + +Erros que provocan a finalización do fío de execución (thread) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Se existe un erro de programación que xorde froito da invocación dun servizo neste caso devólvese, como se dixo no apartado precedente, un código de erro HTTP 500 e no corpo da mensaxe HTTP darase o seguinte: + +:: + + + + + + + +Dentro de ** irá a pila de execución de chamadas do programa ata chegar a función que desencadeou o problema. + +Cando se produce un erro deste tipo a entidade que estea realizando a integración podería crear unha incidencia no sistema de xestión de erros describindo a situación que levou a aparición do erro e incluíndo o stack-trace devolto polo servizo web para facilitar a solución do erro pola comunidade de NavalPlan. + +Erros lóxicos +~~~~~~~~~~~~~ + +Os erros lóxicos son erros que non son debidos a un defecto na aplicación NavalPlan senón que son debidos a dúas posibles causas: + + * Os datos que se teñen na base de datos de NavalPlan non son compatibles cos datos de entrada da petición. + * Os datos de entrada para a operación solicitada no servizo web non son correctos. + +Cando se producen erros lóxicos van a ser catalogados polo equipo de desenvolvemento de NavalPlan en dous posibles tipos: + + 1. Erros recuperables. Os erros recuperables son aqueles para os que os desenvolvedores da integración do cliente poden decidir intentar realizar unha recuperación automática do erro. + #. Erros non recuperables. Os erros non recuperables son aqueles para os que non se pode implementar ningún mecanismo automático de solución do problema e o único camiño e a intervención humana para a solución dos problemas detectados. + +No corpo da resposta HTTP cando se produce un erro ou varios erros lóxicos será a seguinte: + +:: + + + + + + + + + + + + + + +Cada erro recuperable indícase a través da etiqueta ** e cada erro non recuperable informarase coa etiqueta **. + +A descrición dun ** é a seguinte: + + * Atributo *error-code*. No atributo *error-code* irá un código de erro interno definido en NavalPlan. Será un número e existirá unha táboa de códigos de erros recuperables en NavalPlan que permitirán aos integradores implementar unha solución recuperable adecuada a cada código de erro. + * Atributo *message*. Aquí indicarase unha descrición do erro. + * Etiqueta **. Pode haber varias etiquetas deste tipo que son usadas para proporcionar datos que poden ser necesarios con dous atributos cada unha: + + * *name*. Nome da propiedade. + * *value*. Valor da propiedade. + +Pola súa banda cada ** ten un atributo *message* no cal se indicará a causa do erro de validación. + +Validacións contra esquema +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +O framework que se utiliza para a implementación dos servizos web é Apache CXF. Con este framework xerase e pódese consultar o XML Schema para cada servizo. Cando aquí se menciona que se poden consultar significa que son servidos polo servlet utilizado por CXF para implementar os servizos web. Por exemplo, a URL para consultar o esquema XML dun servizo é a seguinte: + +:: + + ?_wadl&_type=xml + + +Os documentos XML Schema son un estándar da W3C que permite especificar a estrutura e formato dos documentos XML. Poden ser utilizados para validar se un determinado XML se axusta a un determinado esquema e así determinar se hai algún erro. + +Xa que para os servizos web de NavalPlan van estar dispoñibles os XML Schema dos mesmos, estes poderán ser utilizados polos integradores de aplicacións con NavalPlan para validar que xeran os XML de intercambio correctos. + +Tamén se implementará a través de CXF unha validación do XML entrante no corpo das mensaxes HTTP de invocación dos servizos web por parte dos clientes. Por tanto, se validará se o XML contra o esquema XML e se non é correcto mandarase unha mensaxe de resposta HTTP con código de estado 400 e corpo baleiro. + +Fluxos de integración +===================== + +Os fluxos de integración detallan a secuencia que ten que facer unha aplicación cliente para integrarse coa aplicación NavalPlan e en que secuencia poderá realizar as chamadas aos servizos web dispoñibles. + +Os servizos web atópanse dispoñibles a partir da URL_BASE da aplicación en /ws/rest/: + + * URL Base de Servizos: URL_BASE_NAVALPLANNER_WEBAPP/ws/rest + * Exemplo: https://naval.igalia.com/navalplanner-webapp/ws/rest + +A partir deste intre denominase a esta URL de servizos coma *BASE_SERVICES_URL*. + + +Fluxos de importación con outras aplicacións +-------------------------------------------- + +Incorporación de Materiais +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Descrición + * A incorporación de materiais permitirá a importación da información das categorías e materíais de interese na aplicación dende outras aplicacións. + * A incorporación de materiais permitirá asociar materiais a necesidades para o inicio de tarefas no planificador. + +Roles + * Cliente: proporciona nova información sobre os materiais ao servidor NavalPlan. + * Servidor: procesa a petición do cliente incorporando a nova información dos materiais. + +Precondicións + * Tódolos materiais pertencerán a unha categoría. + * Mantense un código único por material e por categoría. + +Postcondicións + * Os novos materiais e categorías de materiais serán incorporadas ao sistema. + * As instancias que existían previamente no sistema: + + * os seus campos propios serán actualizados coa nova información. + * se un material cambia de categoría modificarase a categoría a que pertence o material. + +Clases involucradas en NavalPlan + .. image:: materials.png + :width: 300 + :alt: Diagrama de Clases do dominio de Materiais en NavalPlan + +Descrición do fluxo + 1. A aplicación cliente que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a alta de novos materiais e categorías e actualiza os datos dos materiais e categorías existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + +Exemplo de ficheiro de importación + :: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Incorporación de Etiquetas +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Descrición + * A incorporación de etiquetas permitirá a importación da información dos tipos de etiquetas e etiquetas de interese na aplicación dende outras aplicacións. + * As etiquetas permitirán a catalogación e filtrado dos elementos do pedido. + * Exemplos de etiquetas: Zonas do Buque, Prioridades, Centros de Coste, etc... + +Roles + * Cliente: proporciona nova información sobre as etiquetas ao servidor NavalPlan. + * Servidor: procesa a petición do cliente incorporando a nova información das etiquetas. + +Precondicións + * Tódalas etiquetas pertencen a un tipo de etiqueta. + * Mantense un código único por etiquetas e por tipo de etiqueta. + * O nome das etiquetas é unico dentro dun tipo de étiqueta. + * Unha etiqueta previamente existente non pode cambiar de tipo. + +Postcondicións + * As novas etiquetas e tipos de etiqueta serán incorporadas ao sistema. + * As instancias que existían previamente no sistema: + + * os seus campos propios serán actualizados coa nova información. + +Clases involucradas en NavalPlan + .. image:: labels.png + :width: 200 + :alt: Diagrama de Clases do dominio de Etiquetas en NavalPlan + +Descrición do fluxo + 1. A aplicación cliente que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a alta de novas etiquetas e tipos de etiquetas e actualiza os datos das etiquetas e tipos de etiquetas existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + +Exemplo de ficheiro de importación + :: + + + + + + + + + + + + + +Incorporación de Tipos de Criterios e Criterios +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de criterios permitirá incorporar nova información de criterios á aplicación co obxectivo de unificar a codificación con aplicacións externas. + * Os criterios incorporaranse en base á relación de criterios que pertencen a un tipo de criterio. + * Os criterios poderán ter unha estrutura xerárquica na súa importación. + * Exemplos de criterios serían: + + * Tipo de Criterio: Gremio + + * Criterio: Soldador + * Criterio: Electricista + * Criterio: Tubeiro + +Roles + * Cliente: proporciona nova información sobre os criterios e tipos de criterio ao servidor NavalPlan. + * Servidor: procesa a petición do cliente incorporando a nova información dos criterios e tipos de criterio. + +Precondicións + * O código de todos os criterios debe de ser único. + * Os criterios que pertencen a un tipo de criterio non xerárquico non poderán ter nodos fillos. + +Postcondicións + * As novas instancias serán incorporadas ao sistema unha vez se comprobe se non existían previamente. + * As instancias que existían previamente no sistema: + + * os seus campos propios serán actualizados coa nova información. + * non se poderá cambiar unha entidade que estivera definida como xerárquica e tiña unha estrutura de criterios a non xerárquica. + * se un criterio non aparece nunha nova importación non se realizará ningún cambio xa que non se realizan borrados. So se realizan actualizacións e marcados coma non activados. + +Clases involucradas en NavalPlan + .. image:: criterions.png + :width: 350 + :alt: Diagrama de Clases do dominio de Criterios en NavalPlan + + +Descrición do fluxo + 1. A aplicación cliente que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a alta de novos criterios e tipos de criterios e actualiza os datos dos criterios existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + +Información de realización da chamada + * *URL Servizo*: BASE_SERVICE_URL/criteriontypes + * *Exemplo URL*: https://naval.igalia.com/navalplanner-webapp/ws/rest/services/criteriontypes + * *Método POST* + +Descrición do formato do ficheiro XML + * Nodo criterion-type-list: raíz da importación de tipos de criterios. Pode conter un ou varios nodos do tipo criterion-type. + + * Nodo criterion-type: representa un tipo de criterio. + + * Atributo code (String): código único compartido entre NavalPlan e outras aplicacións que referencia ao tipo de criterio. + * Atributo name (String): nome que identifica o tipo de criterio. + * Atributo description (String): describe ao criterio. + * Atributo allow-hierarchy (boolean): indica se os criterios deste tipo de criterio teñen unha xerarquía de criterios. + * Atributo allow-simultaneous-criterions-per-resource (boolean): indica que os recursos poden cumprir simultaneamente no tempo máis de un criterio deste tipo. + * Atributo enabled (boolean): indica que este tipo de criterio está activo. Se non estivera activo non serán asignables novos criterios a este tipo de criterio. + * Atributo resource (Enumeration): indica para que tipo de recursos é aplicable este criterio, os posibles valores serán (RESOURCE, MACHINE e WORKER). + * Nodo criterion-list: inclúe a lista de criterios que pertencen ao tipo de criterio. Pode conter un ou varios nodos do tipo criterion. + + * Nodo criterion: representa a unha instancia da entidade criterio. + + * Atributo code (String): código único compartido entre NavalPlan e outras aplicacións que referencia a un criterio. + * Atributo name (String): nome descritivo do criterio. + * Atributo active (boolean): indica se este criterio está activo. Se non estivera activo este criterio non sería aplicable a outras entidades no futuro. + * Nodo children: indica que un criterio ten fillos na xerarquía, polo cal todos os fillos cumpren o criterio do nodo pai. + + * Nodo criterion: mantén a mesma estrutura que o nodo criterion descrito previamente. E permite describir a estrutura dos fillos. + +Exemplo de ficheiro de importación +:: + + + + + + + + + + + + + + + + + + + + + + + +Incorporación de Tipos de Horas de Traballo +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de tipos de horas de traballo permitirá a importación da información dos tipos de horas de traballo de interese na aplicación dende outras aplicacións. + * Os tipos de horas terán coma atributos base o código, un nome do tipo de hora, se está habilitada e un precio por hora por defecto a aplicar. + * Exemplos de tipos de hora son: ordinaria, extra, nocturna, extra-noctura, etc... + * Estes tipos de horas empregaranse na incorporación dos partes de traballo. + +Roles + * Cliente: proporciona nova información sobre os tipos de horas ao servidor NavalPlan. + * Servidor: procesa a petición do cliente incorporando a nova información dos tipos de horas. + +Precondicións + * Mantense un código único por tipo de hora. + * O nome do tipo de hora de traballo e único. + +Postcondicións + * Os novos tipos de horas de traballo serán incorporadas ao sistema. + * As instancias que existían previamente no sistema verán actualizada a súa información. + +Clases involucradas en NavalPlan + .. image:: typeofworkhours.png + :width: 150 + :alt: Diagrama de Clases do dominio de Tipos de Horas en NavalPlan + + +Descrición do fluxo + 1. A aplicación cliente que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a alta de novos tipos de horas de traballo e actualiza os datos dos xa existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + +Exemplo de ficheiro de importación + :: + + + + + + + + +Incorporación de Categorías de Custo +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de categorías de custo permitirá a importación da información das categorías de custo dende outras aplicacións. + * As categorías de custo incorporan a información dos custos de precio por hora du tipo de recurso segundo o tipo de hora de traballo que realice. + * As categorías de custo teñen un precio por hora distinto ao longo do tempo. + * Exemplo: Categorías de custo: Oficial de primeira. Ten un precio asociado de hora extra de 20€ a hora durante o ano 2010. + +Roles + * Cliente: proporciona nova información sobre as categorías de custo ao servidor NavalPlan. + * Servidor: procesa a petición do cliente incorporando a nova información das categorías de custo. + +Precondicións + * Os códigos das categorías de custo son únicos. + * No existen dúas categorías de custo co mesmo nome. + * Nun periodo de tempo unha categoría de custo so pode ter un custo/hora para un tipo de hora simultaneamente. + * Por categoría de coste só ó último intervalo de tempo pode carecer de data de fin. + +Postcondicións + * As novas categorías de custo serán incorporadas ao sistema. + * As instancias que xa existían previamente no sistema verán actualizada a súa información. + +Clases involucradas en NavalPlan + .. image:: costcategories.png + :width: 150 + :alt: Diagrama de Clases do dominio de Categorías de Coste en NavalPlan + + +Descrición do fluxo + 1. A aplicación cliente que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a alta de novas categorías de custo e actualiza os datos das xa existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + + +Exemplo de ficheiro de importación + :: + + + + + + + + + + + + + + + + + + + + +Incorporación de Recursos +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de recursos permitirá a importación da información dos recursos humanos de interese na aplicación dende outras aplicacións. + * Os recursos que se incorporarán serán de tipo máquina ou traballador. + * A importación permitirá incorporar a información referente aos criterios que cumpre o recurso e a información sobre a súa categoría de custo. + * A incorporación dos recursos poderá facer referencia ao calendario laboral existente. + +Roles + * Cliente: proporciona nova información sobre os recursos ao servidor NavalPlan. + * Servidor: procesa a petición do cliente incorporando a nova información dos recursos. + +Precondicións + * É necesario que as referencias aos criterios que cumpren os recursos estean dispoñibles na aplicación. + * Débense cumprir as restricións temporais da aplicación dos criterios nos casos dos criterios que só poden ter un único valor no mesmo instante do tempo. + * É necesario que as categorías de custo ás que pertencen os recursos xa foran importadas previamente en NavalPlan. + * Un recurso só pode pertencer a unha categoría de custo nun momento do tempo. + * Se se incorpora un calendario de traballo para o recurso, este deberá estar dado de alta na aplicación no momento da importación. + +Postcondicións + * As novas instancias serán incorporadas ao sistema coa información dos seus criterios e categorías de custo. Se se indicou un calendario do recurso crearase un calendario de recurso derivado do indicado no XML, noutro caso crearase un calendario derivado do calendario por defecto da empresa. + * As instancias que existían previamente no sistema: + + * os seus campos propios serán actualizados coa nova información. + * as relacións con novos criterios e categorías de custo serán incorporadas. Nunca se borrarán categorías nin criterios se non son incorporados na aplicación xa que poden ter sido dados de alta a través da interface web de NavalPlan. En caso de incoherencia nunca se borrará a información de NavalPlan e reportarase a existencia de inconsistencias para que sexan emendadas. + +Clases involucradas en NavalPlan + .. image:: resources.png + :width: 350 + :alt: Diagrama de Clases do dominio de Recursos en NavalPlan + + +Descrición do fluxo + 1. A aplicación cliente que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a alta de novos recursos e actualiza os datos dos recursos existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + +Información de realización da chamada + * *URL Servizo*: BASE_SERVICE_URL/resources + * *Exemplo URL*: https://naval.igalia.com/navalplanner-webapp/ws/rest/services/resources + * *Método POST* + +Descrición do formato do ficheiro XML + * Nodo resource-list: raíz da importación de recursos. Poder conter un ou varios nodos de tipo machine ou worker. + + * Nodo machine: representa un recurso máquina. + + * Atributo code (String): código único compartido entre NavalPlan e outras aplicacións que referencia a unha máquina. + * Atributo name (String): nome que identifica a máquina. + * Atributo description (String): describe a máquina. + * Nodo criterion-satisfaction-list: inclúe a lista de satisfacción de criterios. Pode conter un ou varios nodos de tipo criterion-satisfaction. + + * Nodo criterion-satisfaction: representa que un recurso cumpre un criterio nun momento do tempo. + + * Atributo code (String): código único compartido entre NavalPlan e outras aplicacións que referencia a un criterio. + * Atributo criterion-type-name (String): nome descritivo do tipo de criterio ao que pertence o criterio en cuestión. + * Atributo criterion-name (String): nome descritivo do criterio que se aplica neste nodo criterion-satisfaction. + * Atributo start-date (String): data de inicio do cumprimento do criterio polo recurso en formato ISO 8601 (YYYY-MM-DD). + * Atributo end-date (String): date de finalización do cumprimento do criterio polo recurso en formato ISO 8601 (YYYY-MM-DD). + + * Nodo resource-cost-category-assignment-list: inclúe a lista de categorías de custo ás que pertence o recurso ao longo do tempo. Pode conter un ou varios nodos de tipo resources-cost-category-assignment. + + * Nodo resources-cost-category-assignment: representa que un recurso pertence a unha categoría de custo nun momento do tempo. + + * Atributo code (String): código único compartido entre NavalPlan e outras aplicacións que referencia a unha categoría de custo. + * Atributo cost-category-name (String): nome descritivo da categoría de custo a que pertence o recurso. + * Atributo start-date (String): data de inicio da pertenza á categoría de custo en formato ISO 8601 (YYYY-MM-DD). + * Atributo end-date (String): data de finalización da pertenza á categoría de custo en formato ISO 8601 (YYYY-MM-DD). + + * Nodo worker: representa un recurso humano. + + * Atributo code (String): código único compartido entre NavalPlan e outras aplicacións que referencia a un traballador. + * Atributo first-name (String): nome do traballador. + * Atributo surname (String): apelidos do traballador. + * Atributo nif (String): nif do traballador. + * Nodo criterion-satisfaction-list: seguindo o formato detallado para as máquinas. + * Nodo resources-cost-category-assignment-list: seguindo o formato detallado para as máquinas. + +Exemplo de ficheiro de importación + :: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Incorporación de Partes de Traballo +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de partes de traballo permitirá a importación da información dos partes de traballo dende outras aplicacións. + * Os partes de traballo reflexan que un recurso dedicou nunha data un número de horas dun tipo traballando nun elemento do pedido. + * Os partes de traballo incorporan un código de parte, un código do recurso, o código do traballo, o código do tipo de horas, a data de realización, o número de horas e opcionalmente unha hora de inicio e unha hora de fin. + * Exemplo: O operario Xavier dedicou 3 horas extras o 2 de xaneiro de 2010 na orde de traballo C5232. + +Roles + * Cliente: proporciona nova información sobre os partes de traballo ao servidor NavalPlan. + * Servidor: procesa a petición do cliente incorporando a nova información dos partes de traballo. + +Precondicións + * Os partes de traballo farán referencia a entidades recurso, código do elemento do pedido e código de tipo de horas existentes previamente na aplicación. + * A codificación dos partes de traballo e única. + +Postcondicións + * Os novos partes de traballo serán incorporados ao sistema. + * Os partes xa existentes verán actualizada a súa información. + +Clases involucradas en NavalPlan + .. image:: workreports.png + :width: 400 + :alt: Diagrama de Clases do dominio de Partes de Traballo en NavalPlan + +Descrición do fluxo + 1. A aplicación cliente que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a alta de partes de traballo e actualiza os datos dos xa existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + + + + +Exemplo de ficheiro de importación: + :: + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + + + +Incorporación de Pedidos +~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de pedidos permitirá a importación da información dos pedidos dende outras aplicacións. + * Os pedidos reflexan unha estructura do traballo que e preciso realizar dunha forma xerarquica. + * Os cada elemento do pedido está codificado, e estes códigos serán os empregados para referenciar aos partes de traballo. + * Os elementos do pedido poderán incorporar información referente a criterios necesarios para a realización dos traballos. + * Os elementos do pedido poderán incorporar etiquetas que poderán ser empregadas para a realización de filtrados. + * Os elementos do pedido poderán incorporar necesidades de materiais que poderán ser empregadas no planificador. + * A estructura de traballo pode incorporar a información do número de horas de traballo presupuestadas para cada elemento. Esta etimación será realizada nos nodos folla. + +Roles + * Cliente: proporciona nova información sobre os pedidos ao servidor NavalPlan. + * Servidor: procesa a petición do cliente incorporando a nova información dos pedidos. + +Precondicións + * Os pedidos e os elementos do pedido terán unha codificación unica dentro da empresa. + * Os materiais, etiquetas e criterios referenciados deberán ter sido previamente importados a NavalPlan. + * Un pedido previamente importado permitirá a incorporación de novos nodos sempre e cando non se modifique a estructura dos nodos existentes previamente. + + +Postcondicións + * Os novos pedidos serán incorporados ao sistema. + * Os pedidos xa existentes verán actualizada a súa información. + + * Non se eliminarán referencias a materiais, etiquetas ou criterios no proceso de actualización, xa que estas poideron ser creadas dentro de NavalPlan. + * Actualizarase a información dos elementos do pedido. + +Clases involucradas en NavalPlan + .. image:: orders.png + :width: 350 + :alt: Diagrama de Clases do dominio de Pedidos en NavalPlan + + +Descrición do fluxo + 1. A aplicación cliente que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a alta de pedidos e actualiza os datos dos xa existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + +Exemplo de ficheiro de importación + :: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ..... + + + +Exportación de Horas Traballadas por Recursos +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de partes de traballo ou a introducción dos mesmos a través da aplicación permite obter a dedicación dos recursos. + * O servizo de exportación por horas permitiranos consultar o total de horas de traballo desenvoltos polos recursos nun periodo de tempo. + * O servizo permitirá unha consulta global que mostrará a información de horas traballadas desglosada en tódolos recursos que traballaron no periodo de tempo. + * O servizo permitirá unha consulta particular que mostrará a información do recursos particular nun periodo de tempo. + +Roles + * Cliente: pide a aplicación NavalPlan indicando un periodo de tempo, e opcionalmente o código dun recurso, o dato de horas traballadas. + * Servidor: procesa a petición do cliente xerando un ficheiro XML coa información das horas traballadas por cada un dos recursos da empresa ou dun recurso particular. + +Precondicións + * No caso de consultas particulares o código do recurso consultado existe na aplicación. + +Postcondicións + * Obtense o sumatorio para cada recurso do número de horas traballadas nun periodo de tempo. + * Se a consulta é particular, obtense únicamente o número de horas traballadas por ese recurso. + +Clases involucradas en NavalPlan + .. image:: workedhours.png + :width: 150 + :alt: Diagrama de Clases do dominio de Recursos en NavalPlan + +Descrición do fluxo + 1. A aplicación cliente que se integra fara unha petición ao servizo indicando o periodo de tempo e opcionalmente o código do recurso. + #. A aplicación cliente realiza a chamada ao servizo web cos datos de autorización. + #. O servizo web procesa a petición, e xera un ficheiro XML coa información de hotras traballadas polos recursos no periodo. + #. O servizo web devolve o XML ou a saida de erros se a execución do servizo non foi correcta. + #. A aplicación cliente procesa a saída XML do servizo e incorpora os datos sobre horas traballadas ou procesa os erros detectados polo servizo. + + +Exemplo de ficheiro de importación: + :: + + + + + + + + + +Fluxos con outras instancias de NavalPlan +----------------------------------------- + +Exportación-importación de Pedidos entre empresas Cliente-Proveedor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de pedidos permitirá a importación da información dos pedidos dende a aplicación navalplan dunha empresa subcontratante. + * Os pedidos reflexan unha estructura do traballo que e preciso realizar dunha forma xerarquica. + * Os cada elemento do pedido está codificado, e estes códigos serán os empregados para reportar os avances a empresa subcontratante. + * Os elementos do pedido poderán incorporar etiquetas que poderán ser empregadas para a realización de filtrados. + * Os elementos do pedido poderán incorporar necesidades de materiais que poderán ser empregadas no planificador. + * A estructura de traballo pode incorporar a información do número de horas de traballo presupuestadas para cada elemento. Esta estimación será realizada nos nodos folla. + +Roles + * Cliente: aplicación NavalPlan que remite un novo pedido a outra empresa cunha instalación de NavalPlan. + * Servidor: procesa a petición do cliente incorporando o novo pedido + +Precondicións + * Os pedidos e os elementos do pedido terán unha codificación única dentro da empresa que xera a subcontratación. Non se poden mezclar codificacións dunha mesma empresa. + * Os materiais, etiquetas e criterios referenciados deberán ter un código na incorporación que será referenciado coma código externo. + * Un pedido previamente importado permitirá a incorporación de novos nodos sempre e cando non se modifique a estructura dos nodos existentes previamente. + +Postcondicións + * O novo pedido será incorporados ao sistema. + * Se o pedido xa estaba no sistema actualizaránse os datos. + * Non se eliminarán referencias a materiais ou etiquetas no proceso de actualización, xa que estas poideron ser creadas dentro de NavalPlan. + * Actualizarase a información dos elementos do pedido. + +Descrición do fluxo + 1. A aplicación NavalPlan cliente (a empresa subcontratante) que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web (da empresa subcontratista) cos datos de autorización. + #. O servizo web procesa a alta de pedidos e actualiza os datos dos xa existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + +Exemplo de ficheiro de importación + :: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Exportación-importación de Avances entre empresas Proveedor-Cliente +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Descrición + * A incorporación de avances de pedidos permitirá a comunicación dos avances dos pedidos incorporados mediante o módulo de xestión de subcontratas. + * A incorporación de avances respetará a estructura xerarquica do pedido. Ao estar codificados os elementos do pedido, as medidas de avances estarán asociadas aos nodos do pedido. + * O avance remitido será o que teña a empresa subcontratista de tipo *subcontractor*. Este avance sempre terá tipo porcentual. + +Roles + * Cliente: aplicación NavalPlan que remite as medicións de avances dun pedido comunicado previamente por outra empresa usuaria de NavalPlan. + * Servidor: procesa a petición do cliente incorporando as novas medicións de avance. + +Precondicións + * O pedido fora comunicado mediante o módulo de xestión de subcontratas. + * Os pedidos e os elementos do pedido terán unha codificación única dentro da empresa que xera a subcontratación e están sincronizados nas dúas empresas. + * Non se poden mezclar codificacións dunha mesma empresa. + * A empresa que xera a subcontratación non pode modificar a organización nen codificación dos elementos codificados. + +Postcondicións + * A empresa subcontratante incorpora as medicións de avance proporciondas pola emrpesa subcontratista. + +Descrición do fluxo + 1. A aplicación NavalPlan cliente (a empresa subcontratista) que se integra xerará un ficheiro seguindo o formato detallado. + #. A aplicación cliente realiza a chamada ao servizo web (da empresa subcontratante) cos datos de autorización. + #. O servizo web procesa as medicións de avances e actualiza os datos dos xa existentes. + #. O servizo web devolve nun XML a saída de erros ou a correcta execución do servizo. + #. A aplicación cliente procesa a saída XML do servizo e reporta o éxito ou os erros detectados polo servizo. + +Exemplo de ficheiro de importación de avances. + :: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Desenvolvemento dun cliente +=========================== + +Nesta sección mostrase o código de exemplo de dous scripts shell que permiten unha operación de importación de recursos e outra de exportación de criterios. + +Código de exemplo +----------------- + +O seguinte script permite interactuar co servizo de importación de recursos empregando unha sinxela petición HTTP e enviando o XML mediante POST. + +:: + + #!/bin/sh + + DEVELOPMENT_BASE_SERVICE_URL=http://localhost:8080/navalplanner-webapp/ws/rest + PRODUCTION_BASE_SERVICE_URL=https://naval.igalia.com/navalplanner-webapp/ws/rest + + DEVELOPMENT_CERTIFICATE="" + PRODUCTION_CERTIFICATE=-k + + printf "Login name: " + read loginName + printf "Password: " + read password + + baseServiceURL=$DEVELOPMENT_BASE_SERVICE_URL + certificate=$DEVELOPMENT_CERTIFICATE + + for i in "$@" + do + if [ "$i" = "--prod" ]; then + baseServiceURL=$PRODUCTION_BASE_SERVICE_URL + certificate=$PRODUCTION_CERTIFICATE + else + file=$i + fi + done + + if [ "$file" = "" ]; then + printf "Missing file\n" 1>&2 + exit 1 + fi + + authorization=`./base64.sh $loginName:$password` + + curl -sv -X POST $certificate -d @$file \ + --header "Content-type: application/xml" \ + --header "Authorization: Basic $authorization" \ + $baseServiceURL/resources | tidy -xml -i -q -utf8 + + +O seguinte código de exemplo fai unha petición por GET que nos devolve o listado de tipos de criterios e criterios que están dados de alta na aplicación nun XML que segue o formato definido. + +:: + + #!/bin/sh + + DEVELOPMENT_BASE_SERVICE_URL=http://localhost:8080/navalplanner-webapp/ws/rest + PRODUCTION_BASE_SERVICE_URL=https://naval.igalia.com/navalplanner-webapp/ws/rest + + DEVELOPMENT_CERTIFICATE="" + PRODUCTION_CERTIFICATE=-k + + + printf "Login name: " + read loginName + printf "Password: " + read password + + if [ "$1" = "--prod" ]; then + baseServiceURL=$PRODUCTION_BASE_SERVICE_URL + certificate=$PRODUCTION_CERTIFICATE + else + baseServiceURL=$DEVELOPMENT_BASE_SERVICE_URL + certificate=$DEVELOPMENT_CERTIFICATE + fi + + authorization=`./base64.sh $loginName:$password` + + curl -sv -X GET $certificate --header "Authorization: Basic $authorization" \ + $baseServiceURL/criteriontypes | tidy -xml -i -q -utf8 diff --git a/doc/src/technical/guia-integracion-terceiros/labels.png b/doc/src/technical/guia-integracion-terceiros/labels.png new file mode 100644 index 000000000..aa65c23d1 Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/labels.png differ diff --git a/doc/src/technical/guia-integracion-terceiros/materials.png b/doc/src/technical/guia-integracion-terceiros/materials.png new file mode 100644 index 000000000..7543677d1 Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/materials.png differ diff --git a/doc/src/technical/guia-integracion-terceiros/orders.png b/doc/src/technical/guia-integracion-terceiros/orders.png new file mode 100644 index 000000000..8c19e7454 Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/orders.png differ diff --git a/doc/src/technical/guia-integracion-terceiros/resources.png b/doc/src/technical/guia-integracion-terceiros/resources.png new file mode 100644 index 000000000..b5274caf8 Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/resources.png differ diff --git a/doc/src/technical/guia-integracion-terceiros/typeofworkhours.png b/doc/src/technical/guia-integracion-terceiros/typeofworkhours.png new file mode 100644 index 000000000..b427062db Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/typeofworkhours.png differ diff --git a/doc/src/technical/guia-integracion-terceiros/workedhours.png b/doc/src/technical/guia-integracion-terceiros/workedhours.png new file mode 100644 index 000000000..d633ffa6e Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/workedhours.png differ diff --git a/doc/src/technical/guia-integracion-terceiros/workreports.png b/doc/src/technical/guia-integracion-terceiros/workreports.png new file mode 100644 index 000000000..b504c748c Binary files /dev/null and b/doc/src/technical/guia-integracion-terceiros/workreports.png differ