diff --git a/docuseal_signing/.gitignore b/docuseal_signing/.gitignore new file mode 100644 index 0000000..df8a896 --- /dev/null +++ b/docuseal_signing/.gitignore @@ -0,0 +1,2 @@ +*.*~ +*pyc \ No newline at end of file diff --git a/docuseal_signing/README.md b/docuseal_signing/README.md new file mode 100644 index 0000000..b2621ae --- /dev/null +++ b/docuseal_signing/README.md @@ -0,0 +1,109 @@ +# Docuseal Signing + +Electronic signature integration between Odoo and a +[Docuseal](https://www.docuseal.com/) instance: configure signature +templates in Odoo, pre-fill them with contact data and request +signatures from partners in a few clicks. + +## Features + +- **Template registry** (`docuseal.template`): reference Docuseal + templates by their ID; the *Fetch from Docuseal* button loads their + submitter roles and fields from the Docuseal API. The submitter role + is picked from a dropdown listing only the roles of the template + (`docuseal.template.role`); the first one is selected by default. +- **Field mapping** (`docuseal.template.field`): map each Docuseal + field of the selected role to a `res.partner` field. Fetching again + keeps the existing mappings; changing the role loads the fields of + the new role from Docuseal with an empty mapping (with a warning in + the form). Once fetched, the template ID is read-only: another + Docuseal template needs a new entry. Fields are kept in + the order returned by the Docuseal API (reorderable with drag & + drop). Values are + pre-filled at submission time and locked so the signer cannot change + them (empty mappings stay editable by the signer). +- **One-click signature request**: generate a server action bound to + `res.partner` (contextual *Action* menu entry) that creates a Docuseal + submission for the selected contact and emails them the signature + request. It is reserved to administrators (`base.group_system`, who + manage the Docuseal templates), and only runs on a + single contact so that a failure never leaves some contacts already + emailed. A draft mode (`_create_draft_submissions`) creates the + pre-filled submission without sending the email, so it can be sent + from Docuseal. +- **Settings**: configure the Docuseal API URL and API token in + *Settings → General Settings* (system parameters + `docuseal.api_url` and `docuseal.api_token`). + +## Installation + +- Requires Odoo 18.0. +- Depends only on `base` and `base_setup`; no extra Python package + (API calls use the standard library). +- A reachable Docuseal instance with an API token is needed at runtime. + +## Technical usage + +The module adds two methods for developers and server actions. + +### Request a signature from code + +```python +template = self.env["docuseal.template"].search( + [("template_id", "=", 12345)], limit=1 +) +partners = self.env["res.partner"].browse([42, 43]) + +# Create a submission per partner and let Docuseal email the +# signature request: +results = template._create_submissions(partners) + +# Or create pre-filled drafts without sending the email: the +# submission must then be sent from Docuseal. +template._create_draft_submissions(partners) +``` + +Behavior of both calls: + +- One Docuseal submission is created per partner, using the template's + Docuseal `template_id` and `submitter_role_id`; the partner's `name` + and `email` identify the submitter. When the request is emailed, every + partner must have an email address: otherwise nothing is sent. +- Each mapped Docuseal field is pre-filled from the partner field set + in `docuseal.template.field`. Non-empty values are locked + (`readonly=True`) so the signer cannot change them; empty values + stay editable. +- Date values are formatted as `%d/%m/%Y`, many2one/many2many values + as a comma-joined list of display names, and selection values as + their human-readable label. +- Both methods return the list of Docuseal API responses (one dict per + submission). A missing API token or a Docuseal error (with the + explanation sent by Docuseal), an invalid API URL or an unreachable + instance raises a `UserError`; with several + partners, the submissions created before the error are not rolled + back in Docuseal. + +### From a server action + +The generated contextual action calls `_action_request_signature`, +which refuses a selection of several contacts, then `_create_submissions` +and shows a confirmation notification: + +```python +action = env['docuseal.template'].browse()._action_request_signature(records) +``` + +### Configuration + +Both methods read the API credentials from system parameters +(`ir.config_parameter`): + +- `docuseal.api_token` — the Docuseal API token (required), set in + *Settings → General Settings*. +- `docuseal.api_url` — the Docuseal instance base URL, defaulting to + `https://sign.elabore.coop`. + +## Credits + +- **Contributors**: Quentin Mondot +- **Maintainer**: [Elabore](https://elabore.coop) diff --git a/docuseal_signing/__init__.py b/docuseal_signing/__init__.py new file mode 100644 index 0000000..0650744 --- /dev/null +++ b/docuseal_signing/__init__.py @@ -0,0 +1 @@ +from . import models diff --git a/docuseal_signing/__manifest__.py b/docuseal_signing/__manifest__.py new file mode 100644 index 0000000..a58a1cb --- /dev/null +++ b/docuseal_signing/__manifest__.py @@ -0,0 +1,29 @@ +# Copyright 2026 Elabore () +# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl). + +{ + "name": "docuseal_signing", + "version": "18.0.1.0.0", + "author": "Elabore", + "website": "https://elabore.coop", + "maintainer": "Quentin Mondot", + "license": "AGPL-3", + "category": "", + "summary": "Electronic signature integration via Docuseal", + "description": "Electronic signature integration between Odoo and a " + "Docuseal instance: configure signature templates in Odoo, pre-fill " + "them with contact data and request signatures from partners in a " + "few clicks.", + "depends": [ + "base", + "base_setup", + ], + "data": [ + "security/ir.model.access.csv", + "views/docuseal_template_views.xml", + "views/res_config_settings_views.xml", + ], + "installable": True, + "auto_install": False, + "application": False, +} diff --git a/docuseal_signing/i18n/fr.po b/docuseal_signing/i18n/fr.po new file mode 100644 index 0000000..d334994 --- /dev/null +++ b/docuseal_signing/i18n/fr.po @@ -0,0 +1,382 @@ +# Translation of Odoo Server. +# This file contains the translation of the following modules: +# * docuseal_signing +# +msgid "" +msgstr "" +"Project-Id-Version: Odoo Server 18.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-11-03 16:13+0000\n" +"PO-Revision-Date: 2026-11-03 16:13+0000\n" +"Last-Translator: \n" +"Language-Team: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: \n" +"Plural-Forms: \n" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "API URL" +msgstr "URL de l'API" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "API token" +msgstr "Token API" + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "Action created" +msgstr "Action créée" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "Authentication token (X-Auth-Token header)" +msgstr "Token d'authentification (en-tête X-Auth-Token)" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "Base URL of the Docuseal instance (e.g. https://sign.elabore.coop)" +msgstr "URL de base de l'instance Docuseal (ex : https://sign.elabore.coop)" + +#. module: docuseal_signing +#: model:ir.model,name:docuseal_signing.model_res_config_settings +msgid "Config Settings" +msgstr "Paramètres de configuration" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "Configuration" +msgstr "Configuration" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "Configure templates" +msgstr "Configurer les templates" + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "Contextual action created on res.partner." +msgstr "Action contextuelle créée sur les contacts." + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.docuseal_template_view_form +msgid "Create contextual action" +msgstr "Créer l'action contextuelle" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__create_uid +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__create_uid +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__create_uid +msgid "Created by" +msgstr "Créé par" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__create_date +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__create_date +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__create_date +msgid "Created on" +msgstr "Créé le" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "Define field mappings and generate contextual actions on contacts" +msgstr "" +"Définir les correspondances de champs et générer les actions contextuelles " +"sur les contacts" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.docuseal_template_view_form +msgid "Delete contextual action" +msgstr "Supprimer l'action contextuelle" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.docuseal_template_view_form +msgid "" +"Delete the contextual action? It will no longer appear in the Action menu on" +" contacts." +msgstr "" +"Supprimer l'action contextuelle ? Elle n'apparaîtra plus dans le menu Action" +" des contacts." + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__display_name +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__display_name +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__display_name +msgid "Display Name" +msgstr "Nom affiché" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_res_config_settings__docuseal_api_url +msgid "Docuseal API URL" +msgstr "URL de l'API Docuseal" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_res_config_settings__docuseal_api_token +msgid "Docuseal API token" +msgstr "Token API Docuseal" + +#. module: docuseal_signing +#: model:ir.model,name:docuseal_signing.model_docuseal_template +msgid "Docuseal Template" +msgstr "Template Docuseal" + +#. module: docuseal_signing +#: model:ir.model,name:docuseal_signing.model_docuseal_template_field +msgid "Docuseal Template Field" +msgstr "Champ de template Docuseal" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__docuseal_field_name +msgid "Docuseal field" +msgstr "Champ Docuseal" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "Docuseal signing" +msgstr "Signature Docuseal" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.docuseal_template_view_form +msgid "Docuseal template" +msgstr "Template Docuseal" + +#. module: docuseal_signing +#: model:ir.actions.act_window,name:docuseal_signing.docuseal_template_action +#: model_terms:ir.ui.view,arch_db:docuseal_signing.docuseal_template_view_list +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "Docuseal templates" +msgstr "Templates Docuseal" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.docuseal_template_view_form +msgid "Fetch from Docuseal" +msgstr "Rapatrier depuis Docuseal" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.docuseal_template_view_form +msgid "Field mapping" +msgstr "Correspondance des champs" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__field_ids +msgid "Fields" +msgstr "Champs" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__id +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__id +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__id +msgid "ID" +msgstr "ID" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__write_uid +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__write_uid +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__write_uid +msgid "Last Updated by" +msgstr "Dernière mise à jour par" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__write_date +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__write_date +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__write_date +msgid "Last Updated on" +msgstr "Dernière mise à jour le" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.res_config_settings_view_form_docuseal +msgid "Manage Docuseal templates" +msgstr "Gérer les templates Docuseal" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__name +msgid "Name" +msgstr "Nom" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__sequence +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__sequence +msgid "Sequence" +msgstr "Séquence" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__server_action_id +msgid "Server action" +msgstr "Action serveur" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__smart_search +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__smart_search +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__smart_search +#: model:ir.model.fields,field_description:docuseal_signing.field_res_config_settings__smart_search +msgid "Smart Search" +msgstr "Recherche intelligente" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__submitter_role_id +msgid "Submitter role" +msgstr "Rôle du signataire" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__template_id +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__template_id +msgid "Template" +msgstr "Template" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__template_id +msgid "Template ID" +msgstr "ID du template" + +#. module: docuseal_signing +#: model:ir.model.fields,help:docuseal_signing.field_docuseal_template__template_id +msgid "" +"You can find the template id in the URL when you have selected the " +"template in Docuseal. It cannot be changed once fetched from Docuseal: to " +"use another template, create a new entry." +msgstr "" +"Vous trouverez l'identifiant du template dans l'URL après avoir sélectionné " +"le template dans Docuseal. Il ne peut plus être modifié une fois rapatrié " +"depuis Docuseal : pour utiliser un autre template, veuillez créer une " +"nouvelle entrée." + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_field__partner_field_id +msgid "res.partner field" +msgstr "Champ res.partner" + +#. module: docuseal_signing +#: model:ir.model,name:docuseal_signing.model_docuseal_template_role +msgid "Docuseal Template Submitter Role" +msgstr "Rôle de signataire du template Docuseal" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__uuid +msgid "Docuseal UUID" +msgstr "UUID Docuseal" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template_role__name +msgid "Role" +msgstr "Rôle" + +#. module: docuseal_signing +#: model:ir.model.fields,field_description:docuseal_signing.field_docuseal_template__role_ids +msgid "Submitter roles" +msgstr "Rôles des signataires" + +#. module: docuseal_signing +#: model_terms:ir.ui.view,arch_db:docuseal_signing.docuseal_template_view_form +msgid "Fetch from Docuseal to list the roles" +msgstr "Rapatrier depuis Docuseal pour lister les rôles" + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "Set the Docuseal API token in the General Settings first." +msgstr "Renseignez d'abord le token API Docuseal dans les Paramètres généraux." + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "Docuseal returned an error %(code)s: %(detail)s" +msgstr "Docuseal a renvoyé une erreur %(code)s : %(detail)s" + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "Docuseal could not be reached at %(url)s: %(error)s" +msgstr "Docuseal est injoignable à l'adresse %(url)s : %(error)s" + +#. module: docuseal_signing +#: model:ir.model.fields,help:docuseal_signing.field_docuseal_template__submitter_role_id +msgid "" +"Submitter role of the Docuseal template that the contact signs as. The " +"available roles are fetched from Docuseal." +msgstr "" +"Rôle du template Docuseal sous lequel le contact signe. Les rôles " +"disponibles sont rapatriés depuis Docuseal." + +#. module: docuseal_signing +#: model:ir.model.fields,help:docuseal_signing.field_docuseal_template_role__uuid +msgid "" +"UUID of the submitter in the Docuseal template, used to find the template " +"fields of this role." +msgstr "" +"UUID du signataire dans le template Docuseal, utilisé pour retrouver les " +"champs du template propres à ce rôle." + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "Field mapping reset" +msgstr "Correspondance des champs réinitialisée" + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "" +"The fields of the new role are loaded with an empty mapping. If you save, " +"the current field mapping will be lost. Discard the changes to keep it." +msgstr "" +"Les champs du nouveau rôle sont chargés sans correspondance. Si vous " +"enregistrez, la correspondance actuelle des champs sera perdue. Ignorez tous " +"les changements pour la conserver." + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "Select a single contact to request a signature." +msgstr "Sélectionnez un seul contact pour demander une signature." + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "Signature requested" +msgstr "Signature demandée" + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "The signature request has been sent to %(partner)s." +msgstr "La demande de signature a été envoyée à %(partner)s." + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "The Docuseal API URL %(url)s is invalid: %(error)s" +msgstr "L'URL de l'API Docuseal %(url)s est invalide : %(error)s" + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "" +"Docuseal returned an unexpected response from %(url)s. " +"Check the Docuseal API URL in the General Settings." +msgstr "" +"Docuseal a renvoyé une réponse inattendue depuis %(url)s. Vérifiez " +"l'URL de l'API Docuseal dans les Paramètres généraux." + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "" +"The signature request cannot be emailed to contacts " +"without a valid email address: %(partners)s" +msgstr "" +"La demande de signature ne peut pas être envoyée par e-mail aux contacts " +"sans adresse e-mail valide : %(partners)s" + +#. module: docuseal_signing +#. odoo-python +#: code:addons/docuseal_signing/models/docuseal_template.py:0 +msgid "" +"The request to Docuseal could not be sent: %(error)s. " +"Check the Docuseal API token in the General Settings." +msgstr "" +"La requête vers Docuseal n'a pas pu être envoyée : %(error)s. " +"Vérifiez le token API Docuseal dans les Paramètres généraux." diff --git a/docuseal_signing/models/__init__.py b/docuseal_signing/models/__init__.py new file mode 100644 index 0000000..2b528ae --- /dev/null +++ b/docuseal_signing/models/__init__.py @@ -0,0 +1,4 @@ +from . import docuseal_template +from . import docuseal_template_field +from . import docuseal_template_role +from . import res_config_settings diff --git a/docuseal_signing/models/docuseal_template.py b/docuseal_signing/models/docuseal_template.py new file mode 100644 index 0000000..9050dee --- /dev/null +++ b/docuseal_signing/models/docuseal_template.py @@ -0,0 +1,394 @@ +import http.client +import json +import logging +import urllib.error +import urllib.request + +from odoo import Command, _, api, fields, models +from odoo.exceptions import UserError +from odoo.tools.mail import email_normalize + +_logger = logging.getLogger(__name__) + +DEFAULT_API_URL = "https://sign.elabore.coop" + + +class DocusealTemplate(models.Model): + _name = "docuseal.template" + _description = "Docuseal Template" + + name = fields.Char(string="Name") + template_id = fields.Integer( + string="Template ID", + help="You can find the template id in the URL when you have selected " + "the template in Docuseal. It cannot be changed once fetched from " + "Docuseal: to use another template, create a new entry.", + required=True, + ) + role_ids = fields.One2many( + comodel_name="docuseal.template.role", + inverse_name="template_id", + string="Submitter roles", + ) + submitter_role_id = fields.Many2one( + comodel_name="docuseal.template.role", + string="Submitter role", + domain="[('template_id', '=', id)]", + # Roles belong to their template and are not copied with it. + copy=False, + help="Submitter role of the Docuseal template that the contact " + "signs as. The available roles are fetched from Docuseal.", + ) + field_ids = fields.One2many( + comodel_name="docuseal.template.field", + inverse_name="template_id", + string="Fields", + ) + server_action_id = fields.Many2one( + comodel_name="ir.actions.server", + string="Server action", + readonly=True, + ondelete="set null", + # A copy sharing the action would rewrite or delete the original's. + copy=False, + ) + + def _docuseal_request(self, path, payload=None): + """Call the Docuseal API and return the decoded JSON response. + + ``payload``, when given, is sent as a JSON POST body. Configuration + and API errors are raised as UserError with a readable message. + """ + IrParam = self.env["ir.config_parameter"].sudo() + api_token = IrParam.get_param("docuseal.api_token") + api_url = ( + IrParam.get_param("docuseal.api_url") or DEFAULT_API_URL + ).rstrip("/") + if not api_token: + raise UserError( + _("Set the Docuseal API token in the General Settings first.") + ) + + headers = {"X-Auth-Token": api_token} + data = None + if payload is not None: + data = json.dumps(payload).encode() + headers["Content-Type"] = "application/json" + try: + req = urllib.request.Request( + f"{api_url}{path}", data=data, headers=headers + ) + except ValueError as err: + # Raised by urllib for a URL without scheme or host. + raise UserError( + _( + "The Docuseal API URL %(url)s is invalid: %(error)s", + url=api_url, + error=err, + ) + ) from err + try: + with urllib.request.urlopen(req, timeout=10) as resp: + body = resp.read() + except urllib.error.HTTPError as err: + raise UserError( + _( + "Docuseal returned an error %(code)s: %(detail)s", + code=err.code, + detail=self._docuseal_error_detail(err), + ) + ) from err + except ValueError as err: + # Raised by http.client for an invalid header value, such as an + # API token pasted with a line break or a non-latin-1 character. + raise UserError( + _( + "The request to Docuseal could not be sent: %(error)s. " + "Check the Docuseal API token in the General Settings.", + error=err, + ) + ) from err + except (OSError, http.client.HTTPException) as err: + # URLError, timeouts and connections dropped mid-response. + raise UserError( + _( + "Docuseal could not be reached at %(url)s: %(error)s", + url=api_url, + error=str(getattr(err, "reason", err)) or type(err).__name__, + ) + ) from err + try: + return json.loads(body.decode()) + except ValueError as err: + raise UserError( + _( + "Docuseal returned an unexpected response from %(url)s. " + "Check the Docuseal API URL in the General Settings.", + url=api_url, + ) + ) from err + + @staticmethod + def _docuseal_error_detail(err): + """Explanation sent by Docuseal with an HTTP error, if any.""" + try: + body = err.read().decode(errors="replace").strip() + except (OSError, AttributeError, ValueError): + # No readable body: the HTTP reason is enough. + body = "" + try: + detail = json.loads(body).get("error") + except (ValueError, AttributeError): + detail = body[:500] + return detail or err.reason + + def _fetch_docuseal_template(self): + """Return the template definition from the Docuseal API.""" + self.ensure_one() + return self._docuseal_request(f"/api/templates/{self.template_id}") + + @staticmethod + def _role_field_names(data, role): + """Names of the Docuseal fields of ``role``, in the API order. + + Each Docuseal field belongs to a submitter (``submitter_uuid``); + fields without a submitter are kept for every role. + """ + names = [] + for docuseal_field in data.get("fields", []): + name = docuseal_field.get("name") + submitter_uuid = docuseal_field.get("submitter_uuid") + if not name or name in names: + continue + if submitter_uuid and role.uuid and submitter_uuid != role.uuid: + continue + names.append(name) + return names + + def action_fetch_fields(self): + self.ensure_one() + data = self._fetch_docuseal_template() + + if data.get("name") and not self.name: + self.name = data["name"] + self._sync_roles(data.get("submitters", [])) + + # Reconcile the field mapping of the selected role with the Docuseal + # template instead of wiping it: existing mappings keep their + # res.partner field and the sequence follows the field order + # returned by the Docuseal API. + docuseal_names = self._role_field_names(data, self.submitter_role_id) + existing = { + field.docuseal_field_name: field for field in self.field_ids + } + for index, name in enumerate(docuseal_names): + field = existing.get(name) + if field: + field.sequence = index + else: + self.env["docuseal.template.field"].create({ + "template_id": self.id, + "docuseal_field_name": name, + "sequence": index, + }) + self.field_ids.filtered( + lambda field: field.docuseal_field_name not in docuseal_names + ).unlink() + + @api.onchange("submitter_role_id") + def _onchange_submitter_role_id(self): + """Load the fields of the new role from Docuseal, without mapping.""" + if not self.submitter_role_id or not self.template_id: + return + data = self._fetch_docuseal_template() + names = self._role_field_names(data, self.submitter_role_id) + had_mapping = bool(self.field_ids.partner_field_id) + self.field_ids = [Command.clear()] + [ + Command.create({"docuseal_field_name": name, "sequence": index}) + for index, name in enumerate(names) + ] + if had_mapping: + return { + "warning": { + "title": _("Field mapping reset"), + "message": _( + "The fields of the new role are loaded with an empty " + "mapping. If you save, the current field mapping will " + "be lost. Discard the changes to keep it." + ), + } + } + + def _sync_roles(self, submitters): + """Reconcile the submitter roles with the Docuseal template. + + Existing roles are matched by Docuseal UUID, then by name, so the + selected role survives a re-fetch or a rename in Docuseal. Roles + removed from Docuseal are dropped and the order follows the Docuseal + API. The first role is selected when none is set anymore. + """ + self.ensure_one() + Role = self.env["docuseal.template.role"] + by_uuid = {role.uuid: role for role in self.role_ids if role.uuid} + by_name = {role.name: role for role in self.role_ids} + kept = Role + for submitter in submitters: + name = submitter.get("name") + if not name: + continue + uuid = submitter.get("uuid") or False + role = (uuid and by_uuid.get(uuid)) or by_name.get(name) or Role + vals = {"name": name, "uuid": uuid, "sequence": len(kept)} + if role and role not in kept: + role.write(vals) + else: + role = Role.create(dict(vals, template_id=self.id)) + kept |= role + (self.role_ids - kept).unlink() + if not self.submitter_role_id and kept: + self.submitter_role_id = kept[0] + + def action_create_server_action(self): + self.ensure_one() + partner_model = self.env["ir.model"].search( + [("model", "=", "res.partner")], limit=1 + ) + code = ( + f"action = env['docuseal.template'].browse({self.id})" + f"._action_request_signature(records)" + ) + vals = { + "name": f"Request signature ({self.name or self.template_id})", + "model_id": partner_model.id, + "state": "code", + "code": code, + "binding_model_id": partner_model.id, + "binding_type": "action", + # Docuseal templates are managed by administrators only: hide + # the action from the other users instead of letting them hit + # an access error. + "groups_id": [Command.set(self.env.ref("base.group_system").ids)], + } + if self.server_action_id: + self.server_action_id.write(vals) + else: + self.server_action_id = self.env["ir.actions.server"].create(vals) + + return { + "type": "ir.actions.client", + "tag": "display_notification", + "params": { + "title": _("Action created"), + "message": _("Contextual action created on res.partner."), + "type": "success", + }, + } + + def action_delete_server_action(self): + self.ensure_one() + if self.server_action_id: + self.server_action_id.unlink() + self.server_action_id = False + + def unlink(self): + # Remove the generated contextual action: an action left behind + # would browse a deleted template at runtime. + self.mapped("server_action_id").unlink() + return super().unlink() + + def _action_request_signature(self, partners): + """Entry point of the contextual action: request the signature of a + single contact, so that a failure cannot leave some contacts + already emailed while the action reports an error.""" + self.ensure_one() + if len(partners) != 1: + raise UserError( + _("Select a single contact to request a signature.") + ) + self._create_submissions(partners) + return { + "type": "ir.actions.client", + "tag": "display_notification", + "params": { + "title": _("Signature requested"), + "message": _( + "The signature request has been sent to %(partner)s.", + partner=partners.display_name, + ), + "type": "success", + }, + } + + def _create_draft_submissions(self, partners): + """Create pre-filled submissions without sending the signature request + email: the submission must then be sent from Docuseal.""" + return self._create_submissions(partners, send_email=False) + + def _create_submissions(self, partners, send_email=True): + self.ensure_one() + if send_email: + # Check every partner before the first call, so that no request + # is sent when one of them cannot receive it. + # email_normalize refuses empty, malformed and multiple addresses. + without_email = partners.filtered( + lambda partner: not email_normalize(partner.email) + ) + if without_email: + raise UserError( + _( + "The signature request cannot be emailed to contacts " + "without a valid email address: %(partners)s", + partners=", ".join(without_email.mapped("display_name")), + ) + ) + + results = [] + for partner in partners: + submitter_fields = [] + for field_map in self.field_ids: + if not field_map.partner_field_id: + continue + field_name = field_map.partner_field_id.name + value = partner[field_name] + if hasattr(value, "strftime"): + value = value.strftime("%d/%m/%Y") + elif isinstance(value, models.BaseModel): + value = ", ".join(value.mapped("display_name")) + elif value is False or value is None: + value = "" + elif partner._fields[field_name].type == "selection": + selection = partner._fields[field_name]._description_selection( + partner.env + ) + value = str(dict(selection).get(value, value)) + else: + value = str(value) + # Lock pre-filled values so the signer cannot change them; + # empty values stay editable for the signer to fill in. + submitter_fields.append({ + "name": field_map.docuseal_field_name, + "default_value": value, + "readonly": bool(value), + }) + + payload = { + "template_id": self.template_id, + "send_email": send_email, + "submitters": [{ + "name": partner.name, + "role": self.submitter_role_id.name or "", + "email": email_normalize(partner.email) or partner.email or "", + "fields": submitter_fields, + }], + } + # Do not log the field values (personal data) nor the response: + # it contains the signing links of the submitters. + _logger.info( + "Docuseal: creating submission for res.partner %s with " + "template %s (send_email=%s)", + partner.id, + self.template_id, + send_email, + ) + results.append(self._docuseal_request("/api/submissions", payload)) + return results diff --git a/docuseal_signing/models/docuseal_template_field.py b/docuseal_signing/models/docuseal_template_field.py new file mode 100644 index 0000000..031ab79 --- /dev/null +++ b/docuseal_signing/models/docuseal_template_field.py @@ -0,0 +1,25 @@ +from odoo import fields, models + + +class DocusealTemplateField(models.Model): + _name = "docuseal.template.field" + _description = "Docuseal Template Field" + _order = "sequence, id" + + sequence = fields.Integer(default=10) + + template_id = fields.Many2one( + comodel_name="docuseal.template", + string="Template", + required=True, + ondelete="cascade", + ) + docuseal_field_name = fields.Char(string="Docuseal field", readonly=True) + partner_field_id = fields.Many2one( + comodel_name="ir.model.fields", + string="res.partner field", + domain=[ + ("model", "=", "res.partner"), + ("ttype", "not in", ["one2many", "many2many", "binary"]), + ], + ) diff --git a/docuseal_signing/models/docuseal_template_role.py b/docuseal_signing/models/docuseal_template_role.py new file mode 100644 index 0000000..4059123 --- /dev/null +++ b/docuseal_signing/models/docuseal_template_role.py @@ -0,0 +1,22 @@ +from odoo import fields, models + + +class DocusealTemplateRole(models.Model): + _name = "docuseal.template.role" + _description = "Docuseal Template Submitter Role" + _order = "sequence, id" + + sequence = fields.Integer(default=10) + name = fields.Char(string="Role", required=True, readonly=True) + uuid = fields.Char( + string="Docuseal UUID", + readonly=True, + help="UUID of the submitter in the Docuseal template, used to find " + "the template fields of this role.", + ) + template_id = fields.Many2one( + comodel_name="docuseal.template", + string="Template", + required=True, + ondelete="cascade", + ) diff --git a/docuseal_signing/models/res_config_settings.py b/docuseal_signing/models/res_config_settings.py new file mode 100644 index 0000000..b16e550 --- /dev/null +++ b/docuseal_signing/models/res_config_settings.py @@ -0,0 +1,14 @@ +from odoo import fields, models + + +class ResConfigSettings(models.TransientModel): + _inherit = "res.config.settings" + + docuseal_api_token = fields.Char( + string="Docuseal API token", + config_parameter="docuseal.api_token", + ) + docuseal_api_url = fields.Char( + string="Docuseal API URL", + config_parameter="docuseal.api_url", + ) diff --git a/docuseal_signing/security/ir.model.access.csv b/docuseal_signing/security/ir.model.access.csv new file mode 100644 index 0000000..5dea2ca --- /dev/null +++ b/docuseal_signing/security/ir.model.access.csv @@ -0,0 +1,4 @@ +id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink +access_docuseal_template_system,docuseal.template system,model_docuseal_template,base.group_system,1,1,1,1 +access_docuseal_template_field_system,docuseal.template.field system,model_docuseal_template_field,base.group_system,1,1,1,1 +access_docuseal_template_role_system,docuseal.template.role system,model_docuseal_template_role,base.group_system,1,1,1,1 diff --git a/docuseal_signing/static/description/icon.svg b/docuseal_signing/static/description/icon.svg new file mode 100644 index 0000000..33315dd --- /dev/null +++ b/docuseal_signing/static/description/icon.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docuseal_signing/tests/__init__.py b/docuseal_signing/tests/__init__.py new file mode 100644 index 0000000..0a41525 --- /dev/null +++ b/docuseal_signing/tests/__init__.py @@ -0,0 +1,3 @@ +from . import test_fetch_fields +from . import test_server_action +from . import test_submissions diff --git a/docuseal_signing/tests/common.py b/docuseal_signing/tests/common.py new file mode 100644 index 0000000..d219306 --- /dev/null +++ b/docuseal_signing/tests/common.py @@ -0,0 +1,42 @@ +import json +from unittest import mock + +from odoo.addons.docuseal_signing.models import ( + docuseal_template as docuseal_template_module, +) + + +class DocusealApiMockMixin: + """Mock the Docuseal HTTP API, capturing every request made. + + ``_mock_api(response)`` returns a patcher for ``urlopen``; each + request lands in ``self.requests`` as a dict with ``url``, + ``payload`` (decoded JSON body) and ``headers``. + """ + + def _set_api_config(self, api_url="https://sign.example.com"): + params = self.env["ir.config_parameter"].sudo() + params.set_param("docuseal.api_token", "test-token") + params.set_param("docuseal.api_url", api_url) + + def _mock_api(self, response): + self.requests = [] + + def fake_urlopen(req, timeout=None): + self.requests.append({ + "url": req.full_url, + "payload": json.loads(req.data.decode()) if req.data else None, + "headers": dict(req.header_items()), + }) + resp = mock.MagicMock() + resp.read.return_value = json.dumps(response).encode() + context = mock.MagicMock() + context.__enter__.return_value = resp + context.__exit__.return_value = False + return context + + return mock.patch.object( + docuseal_template_module.urllib.request, + "urlopen", + side_effect=fake_urlopen, + ) diff --git a/docuseal_signing/tests/test_fetch_fields.py b/docuseal_signing/tests/test_fetch_fields.py new file mode 100644 index 0000000..99d4433 --- /dev/null +++ b/docuseal_signing/tests/test_fetch_fields.py @@ -0,0 +1,237 @@ +import urllib.error +from unittest import mock + +from odoo.exceptions import UserError +from odoo.tests import Form, TransactionCase + +from odoo.addons.docuseal_signing.models import ( + docuseal_template as docuseal_template_module, +) + +from .common import DocusealApiMockMixin + + +class TestFetchFields(DocusealApiMockMixin, TransactionCase): + """Roles and field mapping fetched from the Docuseal API.""" + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.phone_field = cls.env["ir.model.fields"].search( + [("model", "=", "res.partner"), ("name", "=", "phone")], limit=1 + ) + cls.template = cls.env["docuseal.template"].create({ + "name": "Old name", + "template_id": 999, + }) + cls.template.submitter_role_id = cls.env["docuseal.template.role"].create({ + "template_id": cls.template.id, + "name": "Signer", + "uuid": "uuid-signer", + }) + cls.env["docuseal.template.field"].create({ + "template_id": cls.template.id, + "docuseal_field_name": "phone", + "partner_field_id": cls.phone_field.id, + }) + cls.env["docuseal.template.field"].create({ + "template_id": cls.template.id, + "docuseal_field_name": "obsolete", + }) + + def setUp(self): + super().setUp() + self._set_api_config() + + def _field_names(self): + self.template.invalidate_recordset(["field_ids", "role_ids"]) + return self.template.field_ids.mapped("docuseal_field_name") + + def test_fetch_fields_reconciles_mapping(self): + """Existing mappings keep their partner field; removed Docuseal + fields are dropped and new ones are added, in the order returned + by the Docuseal API.""" + payload = { + "name": "Contract", + "submitters": [{"name": "Signer", "uuid": "uuid-signer"}], + "fields": [{"name": "phone"}, {"name": "extra"}, {"name": ""}], + } + with self._mock_api(payload): + self.template.action_fetch_fields() + + self.assertEqual( + self.requests[0]["url"], "https://sign.example.com/api/templates/999" + ) + self.assertEqual(self._field_names(), ["phone", "extra"]) + phone_mapping = self.template.field_ids.filtered( + lambda field: field.docuseal_field_name == "phone" + ) + self.assertEqual(phone_mapping.partner_field_id, self.phone_field) + + # Name is only filled when still empty; the selected role is kept. + self.assertEqual(self.template.name, "Old name") + self.assertEqual(self.template.submitter_role_id.name, "Signer") + + def test_fetch_fields_fills_empty_name_and_role(self): + """Name and submitter role are set from the API when missing; + roles removed from Docuseal are dropped.""" + self.template.name = False + self.template.submitter_role_id = False + payload = { + "name": "Contract", + "submitters": [{"name": "Counterparty", "uuid": "uuid-cp"}], + "fields": [], + } + with self._mock_api(payload): + self.template.action_fetch_fields() + + self.assertEqual(self.template.name, "Contract") + self.assertEqual(self.template.submitter_role_id.name, "Counterparty") + self.assertEqual(self.template.role_ids.mapped("name"), ["Counterparty"]) + self.assertFalse(self._field_names()) + + def test_fetch_fields_keeps_only_selected_role_fields(self): + """Only the fields of the selected role are mapped.""" + payload = { + "submitters": [ + {"name": "Signer", "uuid": "uuid-signer"}, + {"name": "Witness", "uuid": "uuid-witness"}, + ], + "fields": [ + {"name": "phone", "submitter_uuid": "uuid-signer"}, + {"name": "witness_name", "submitter_uuid": "uuid-witness"}, + {"name": "city", "submitter_uuid": "uuid-signer"}, + ], + } + with self._mock_api(payload): + self.template.action_fetch_fields() + + self.assertEqual(self._field_names(), ["phone", "city"]) + self.assertEqual( + self.template.role_ids.mapped("name"), ["Signer", "Witness"] + ) + + def test_fetch_fields_syncs_roles(self): + """Roles follow the Docuseal order, are matched by UUID (a rename + keeps the selection) and the selection falls back to the first + role when the selected one is removed.""" + payload = { + "submitters": [ + {"name": "Witness", "uuid": "uuid-witness"}, + {"name": "Main signer", "uuid": "uuid-signer"}, + {"name": ""}, + ], + "fields": [], + } + with self._mock_api(payload): + self.template.action_fetch_fields() + self.template.invalidate_recordset(["role_ids"]) + self.assertEqual( + self.template.role_ids.mapped("name"), ["Witness", "Main signer"] + ) + self.assertEqual(self.template.submitter_role_id.uuid, "uuid-signer") + + # The selected role is removed from the Docuseal template. + payload["submitters"] = [ + {"name": "Witness", "uuid": "uuid-witness"}, + {"name": "Buyer", "uuid": "uuid-buyer"}, + ] + with self._mock_api(payload): + self.template.action_fetch_fields() + self.template.invalidate_recordset(["role_ids"]) + self.assertEqual( + self.template.role_ids.mapped("name"), ["Witness", "Buyer"] + ) + self.assertEqual(self.template.submitter_role_id.name, "Witness") + + def test_change_role_loads_its_fields_without_mapping(self): + """Changing the role in the form fetches the fields of that role + from Docuseal and clears the mapping.""" + witness = self.env["docuseal.template.role"].create({ + "template_id": self.template.id, + "name": "Witness", + "uuid": "uuid-witness", + }) + payload = { + "submitters": [ + {"name": "Signer", "uuid": "uuid-signer"}, + {"name": "Witness", "uuid": "uuid-witness"}, + ], + "fields": [ + {"name": "phone", "submitter_uuid": "uuid-signer"}, + {"name": "witness_name", "submitter_uuid": "uuid-witness"}, + {"name": "witness_city", "submitter_uuid": "uuid-witness"}, + ], + } + # The phone mapping of the current role is lost: warn the user. + with self._mock_api(payload), self.assertLogs( + "odoo.tests.form.onchange", level="WARNING" + ) as logs: + with Form(self.template) as form: + form.submitter_role_id = witness + self.assertIn("Field mapping reset", logs.output[0]) + + self.assertEqual(self.template.submitter_role_id, witness) + self.assertEqual(self._field_names(), ["witness_name", "witness_city"]) + self.assertFalse(self.template.field_ids.partner_field_id) + + def test_change_role_without_mapping_does_not_warn(self): + """No warning when there is no mapping to lose.""" + self.template.field_ids.partner_field_id = False + witness = self.env["docuseal.template.role"].create({ + "template_id": self.template.id, + "name": "Witness", + "uuid": "uuid-witness", + }) + payload = {"submitters": [], "fields": [{"name": "witness_name"}]} + with self._mock_api(payload), self.assertNoLogs( + "odoo.tests.form.onchange", level="WARNING" + ): + with Form(self.template) as form: + form.submitter_role_id = witness + self.assertEqual(self._field_names(), ["witness_name"]) + + def test_fetch_fields_restores_order_after_manual_delete(self): + """Deleting the first mapped field then re-fetching from the + Docuseal API re-establishes the original field order.""" + payload = { + "submitters": [{"name": "Signer", "uuid": "uuid-signer"}], + "fields": [{"name": "a"}, {"name": "b"}, {"name": "c"}], + } + with self._mock_api(payload): + self.template.action_fetch_fields() + self.assertEqual(self._field_names(), ["a", "b", "c"]) + + # The user deletes the first mapping line. + self.template.field_ids[0].unlink() + + with self._mock_api(payload): + self.template.action_fetch_fields() + self.assertEqual(self._field_names(), ["a", "b", "c"]) + + def test_fetch_errors_raise_user_error(self): + """A missing token or a Docuseal error is reported to the user.""" + with mock.patch.object( + docuseal_template_module.urllib.request, + "urlopen", + side_effect=urllib.error.HTTPError( + "https://sign.example.com", 401, "Unauthorized", {}, None + ), + ), self.assertRaisesRegex(UserError, "401"): + self.template.action_fetch_fields() + + self.env["ir.config_parameter"].sudo().set_param("docuseal.api_token", "") + with self.assertRaises(UserError): + self.template.action_fetch_fields() + + def test_template_id_is_readonly_once_fetched(self): + """The template ID can be set on a new entry, and becomes read-only + once roles have been fetched from Docuseal.""" + form = Form(self.env["docuseal.template"]) + form.template_id = 1000 + new_template = form.save() + + with Form(new_template) as form: + self.assertFalse(form._get_modifier("template_id", "readonly")) + with Form(self.template) as form: + self.assertTrue(form._get_modifier("template_id", "readonly")) diff --git a/docuseal_signing/tests/test_server_action.py b/docuseal_signing/tests/test_server_action.py new file mode 100644 index 0000000..d00c10c --- /dev/null +++ b/docuseal_signing/tests/test_server_action.py @@ -0,0 +1,122 @@ +from odoo.exceptions import AccessError, UserError +from odoo.tests import TransactionCase, new_test_user + +from .common import DocusealApiMockMixin + + +class TestServerAction(DocusealApiMockMixin, TransactionCase): + """Lifecycle and execution of the generated contextual server action.""" + + def test_unlink_removes_server_action(self): + """Deleting a template removes its generated server action, + instead of leaving an orphaned action browsing a dead record.""" + template = self.env["docuseal.template"].create({ + "name": "Contract", + "template_id": 123, + }) + template.action_create_server_action() + action = template.server_action_id + self.assertTrue(action.exists()) + + template.unlink() + self.assertFalse(action.exists()) + + def test_create_server_action_is_idempotent(self): + """Creating the contextual action twice updates the existing + action instead of generating a duplicate.""" + template = self.env["docuseal.template"].create({ + "name": "Contract", + "template_id": 456, + }) + template.action_create_server_action() + first_action = template.server_action_id + template.action_create_server_action() + + self.assertEqual(template.server_action_id, first_action) + self.assertEqual( + self.env["ir.actions.server"].search_count([ + ("name", "=", "Request signature (Contract)"), + ]), + 1, + ) + + def _run_action(self, template, partners, user): + return template.server_action_id.with_user(user).with_context( + active_model="res.partner", + active_ids=partners.ids, + active_id=partners[:1].id, + ).run() + + def test_request_signature_is_restricted_to_administrators(self): + """The contextual action is reserved to administrators, who can + read the Docuseal templates; other users neither see nor run it.""" + self._set_api_config() + template = self.env["docuseal.template"].create({ + "name": "Contract", + "template_id": 789, + }) + template.action_create_server_action() + self.assertEqual( + template.server_action_id.groups_id, + self.env.ref("base.group_system"), + ) + partner = self.env["res.partner"].create({ + "name": "Camille Dupont", + "email": "camille@example.com", + }) + user = new_test_user( + self.env, + login="docuseal_user", + groups="base.group_user,base.group_partner_manager", + ) + + with self._mock_api({"id": 60}), self.assertRaises(AccessError): + self._run_action(template, partner, user) + self.assertFalse(self.requests) + + with self._mock_api({"id": 60}): + result = self._run_action(template, partner, self.env.user) + self.assertEqual(len(self.requests), 1) + self.assertEqual(self.requests[0]["payload"]["template_id"], 789) + self.assertEqual(result["params"]["type"], "success") + + def test_request_signature_requires_a_single_contact(self): + """Selecting several contacts is refused before any API call, so + that no contact is emailed when the action fails.""" + self._set_api_config() + template = self.env["docuseal.template"].create({ + "name": "Contract", + "template_id": 790, + }) + template.action_create_server_action() + partners = self.env["res.partner"].create([ + {"name": "Camille Dupont"}, {"name": "Alex Martin"}, + ]) + + with self._mock_api({"id": 61}), self.assertRaisesRegex( + UserError, "single contact" + ): + self._run_action(template, partners, self.env.user) + self.assertFalse(self.requests) + + def test_copy_does_not_share_action_or_role(self): + """A duplicated template gets neither the contextual action nor + the role of the original, so it cannot rewrite or delete them.""" + template = self.env["docuseal.template"].create({ + "name": "Contract", + "template_id": 791, + }) + template.submitter_role_id = self.env["docuseal.template.role"].create({ + "template_id": template.id, + "name": "Signer", + }) + template.action_create_server_action() + action = template.server_action_id + + duplicate = template.copy() + self.assertFalse(duplicate.server_action_id) + self.assertFalse(duplicate.submitter_role_id) + + duplicate.unlink() + self.assertTrue(action.exists()) + self.assertEqual(template.server_action_id, action) diff --git a/docuseal_signing/tests/test_submissions.py b/docuseal_signing/tests/test_submissions.py new file mode 100644 index 0000000..0292264 --- /dev/null +++ b/docuseal_signing/tests/test_submissions.py @@ -0,0 +1,250 @@ +import http.client +import io +import json +import urllib.error +from unittest import mock + +from odoo.exceptions import UserError +from odoo.tests import TransactionCase + +from odoo.addons.docuseal_signing.models import ( + docuseal_template as docuseal_template_module, +) + +from .common import DocusealApiMockMixin + + +class TestCreateSubmissions(DocusealApiMockMixin, TransactionCase): + """Payload sent to the Docuseal API by _create_submissions.""" + + @classmethod + def setUpClass(cls): + super().setUpClass() + + def partner_field(fname): + return cls.env["ir.model.fields"].search([ + ("model", "=", "res.partner"), ("name", "=", fname), + ], limit=1) + + cls.template = cls.env["docuseal.template"].create({ + "name": "Onboarding", + "template_id": 777, + }) + cls.template.submitter_role_id = cls.env["docuseal.template.role"].create({ + "template_id": cls.template.id, + "name": "Signer", + }) + for docuseal_name, fname in [ + ("full_name", "name"), + ("email", "email"), + ("company_type", "company_type"), + ("birth_date", "create_date"), + ("country", "country_id"), + ("categories", "category_id"), + ("phone", "phone"), + ]: + cls.env["docuseal.template.field"].create({ + "template_id": cls.template.id, + "docuseal_field_name": docuseal_name, + "partner_field_id": partner_field(fname).id, + }) + + cls.country = cls.env["res.country"].search([], limit=1) + cls.categories = cls.env["res.partner.category"].create([ + {"name": "Gold"}, {"name": "Silver"}, + ]) + cls.partner = cls.env["res.partner"].create({ + "name": "Camille Dupont", + "email": "camille@example.com", + "phone": False, + "country_id": cls.country.id, + "category_id": cls.categories.ids, + }) + + def test_submission_payload_conversion(self): + """Field values are converted per type and locked when set.""" + self._set_api_config() + with self._mock_api({"id": 55}): + results = self.template._create_submissions(self.partner) + + self.assertEqual(results, [{"id": 55}]) + request = self.requests[0] + self.assertEqual( + request["url"], "https://sign.example.com/api/submissions" + ) + self.assertIn("test-token", request["headers"].values()) + + payload = request["payload"] + self.assertEqual(payload["template_id"], 777) + self.assertTrue(payload["send_email"]) + self.assertEqual(len(payload["submitters"]), 1) + + submitter = payload["submitters"][0] + self.assertEqual(submitter["name"], "Camille Dupont") + self.assertEqual(submitter["email"], "camille@example.com") + self.assertEqual(submitter["role"], "Signer") + + fields = {field["name"]: field for field in submitter["fields"]} + self.assertEqual( + fields["full_name"]["default_value"], "Camille Dupont" + ) + self.assertTrue(fields["full_name"]["readonly"]) + # selection: human-readable label, not the raw key + self.assertEqual(fields["company_type"]["default_value"], "Individual") + self.assertTrue(fields["company_type"]["readonly"]) + # many2one / many2many: display names joined with ", " + self.assertEqual( + fields["country"]["default_value"], self.country.display_name + ) + self.assertEqual( + fields["categories"]["default_value"], + ", ".join(self.categories.mapped("display_name")), + ) + # datetime: dd/mm/yyyy + self.assertEqual( + fields["birth_date"]["default_value"], + self.partner.create_date.strftime("%d/%m/%Y"), + ) + # empty value: sent as "" and left editable for the signer + self.assertEqual(fields["phone"]["default_value"], "") + self.assertFalse(fields["phone"]["readonly"]) + + def test_draft_submissions_do_not_send_email(self): + """_create_draft_submissions creates pre-filled submissions + without asking Docuseal to email the signers.""" + self._set_api_config() + with self._mock_api({"id": 56}): + self.template._create_draft_submissions(self.partner) + self.assertFalse(self.requests[0]["payload"]["send_email"]) + + def test_one_submission_per_partner(self): + """Each partner gets its own submission with a single submitter.""" + self._set_api_config() + partner2 = self.env["res.partner"].create({ + "name": "Alex Martin", + "email": "alex@example.com", + }) + with self._mock_api({"id": 57}): + self.template._create_submissions(self.partner | partner2) + + self.assertEqual(len(self.requests), 2) + for request in self.requests: + self.assertEqual(len(request["payload"]["submitters"]), 1) + self.assertEqual( + self.requests[1]["payload"]["submitters"][0]["name"], + "Alex Martin", + ) + + def test_api_url_trailing_slash(self): + """A configured API URL with a trailing slash does not produce + a double slash in the request URL.""" + self._set_api_config(api_url="https://sign.example.com/") + with self._mock_api({"id": 58}): + self.template._create_submissions(self.partner) + self.assertEqual( + self.requests[0]["url"], + "https://sign.example.com/api/submissions", + ) + + def test_missing_token_raises_user_error(self): + """Without API token, the user is told to configure it instead of + getting a technical error.""" + self._set_api_config() + self.env["ir.config_parameter"].sudo().set_param("docuseal.api_token", "") + with self._mock_api({"id": 59}), self.assertRaisesRegex( + UserError, "API token" + ): + self.template._create_submissions(self.partner) + self.assertFalse(self.requests) + + def test_docuseal_error_raises_user_error_with_detail(self): + """A Docuseal rejection is reported with the explanation it sent.""" + self._set_api_config() + error = urllib.error.HTTPError( + "https://sign.example.com/api/submissions", + 422, + "Unprocessable Entity", + {}, + io.BytesIO(json.dumps({"error": "Role not found"}).encode()), + ) + with mock.patch.object( + docuseal_template_module.urllib.request, + "urlopen", + side_effect=error, + ), self.assertRaisesRegex(UserError, "422: Role not found"): + self.template._create_submissions(self.partner) + + def test_partner_without_email_is_refused(self): + """No request is sent when a contact cannot receive the email, + even if the other contacts can.""" + self._set_api_config() + no_email = self.env["res.partner"].create({"name": "Sam Leroy"}) + with self._mock_api({"id": 62}), self.assertRaisesRegex( + UserError, "Sam Leroy" + ): + self.template._create_submissions(self.partner | no_email) + self.assertFalse(self.requests) + + # A draft is not emailed: no email address is required. + with self._mock_api({"id": 63}): + self.template._create_draft_submissions(no_email) + self.assertEqual(len(self.requests), 1) + + def _assert_user_error(self, regex, **urlopen_patch): + with mock.patch.object( + docuseal_template_module.urllib.request, "urlopen", **urlopen_patch + ), self.assertRaisesRegex(UserError, regex): + self.template._create_submissions(self.partner) + + def test_invalid_api_url_raises_user_error(self): + """An API URL without scheme is reported, not a traceback.""" + self._set_api_config(api_url="sign.example.com") + with self.assertRaisesRegex(UserError, "is invalid"): + self.template._create_submissions(self.partner) + + def test_unexpected_response_raises_user_error(self): + """A non-JSON response (proxy, login page) is reported.""" + self._set_api_config() + resp = mock.MagicMock() + resp.read.return_value = b"Login" + context = mock.MagicMock() + context.__enter__.return_value = resp + self._assert_user_error("unexpected response", return_value=context) + + def test_dropped_connection_raises_user_error(self): + """A connection dropped mid-response is reported.""" + self._set_api_config() + self._assert_user_error( + "could not be reached", + side_effect=http.client.RemoteDisconnected("closed"), + ) + self._assert_user_error( + "could not be reached", + side_effect=http.client.IncompleteRead(b""), + ) + + def test_malformed_email_is_refused(self): + """Malformed and multiple email addresses are refused too.""" + self._set_api_config() + for email in (" ", "not-an-email", "a@example.com; b@example.com"): + self.partner.email = email + with self._mock_api({"id": 64}), self.assertRaisesRegex( + UserError, "valid email" + ): + self.template._create_submissions(self.partner) + self.assertFalse(self.requests) + + def test_invalid_token_raises_user_error(self): + """A token pasted with a line break is reported as a token problem, + not as an invalid URL.""" + self._set_api_config() + self.env["ir.config_parameter"].sudo().set_param( + "docuseal.api_token", "abc\ndef" + ) + with self.assertRaisesRegex(UserError, "API token"): + self.template._create_submissions(self.partner) + + def test_error_without_message_names_the_exception(self): + """An exception without message still explains what happened.""" + self._set_api_config() + self._assert_user_error("TimeoutError", side_effect=TimeoutError()) diff --git a/docuseal_signing/views/docuseal_template_views.xml b/docuseal_signing/views/docuseal_template_views.xml new file mode 100644 index 0000000..9e36f22 --- /dev/null +++ b/docuseal_signing/views/docuseal_template_views.xml @@ -0,0 +1,89 @@ + + + + + docuseal.template.list + docuseal.template + + + + + + + + + + + + docuseal.template.form + docuseal.template + +
+
+
+ + + + + + +