[ADD] docuseal_signing: request Docuseal signatures from Odoo #1

Open
mondot wants to merge 15 commits from docuseal_signing into 18.0
19 changed files with 1785 additions and 0 deletions

2
docuseal_signing/.gitignore vendored Normal file
View File

@@ -0,0 +1,2 @@
*.*~
*pyc

109
docuseal_signing/README.md Normal file
View File

@@ -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
Review

À renommer en "Additional developers features" + respecter structure README oca.

Puis ok pour merger

À renommer en "Additional developers features" + respecter structure README oca. Puis ok pour merger
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(<template_record_id>)._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 <quentin@elabore.coop>
- **Maintainer**: [Elabore](https://elabore.coop)

View File

@@ -0,0 +1 @@
from . import models

View File

@@ -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,
}

382
docuseal_signing/i18n/fr.po Normal file
View File

@@ -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."

View File

@@ -0,0 +1,4 @@
from . import docuseal_template
from . import docuseal_template_field
from . import docuseal_template_role
from . import res_config_settings

View File

@@ -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

View File

@@ -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"]),
],
)

View File

@@ -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",
)

View File

@@ -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",
)

View File

@@ -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
1 id name model_id:id group_id:id perm_read perm_write perm_create perm_unlink
2 access_docuseal_template_system docuseal.template system model_docuseal_template base.group_system 1 1 1 1
3 access_docuseal_template_field_system docuseal.template.field system model_docuseal_template_field base.group_system 1 1 1 1
4 access_docuseal_template_role_system docuseal.template.role system model_docuseal_template_role base.group_system 1 1 1 1

View File

@@ -0,0 +1,4 @@
<svg height="45px" width="45px" class="" style="color: #e97a42" viewBox="0 0 180 180" xmlns="http://www.w3.org/2000/svg">
<path fill="currentColor" d="M 178.224 72.09 c -0.296 -1.463 -0.627 -2.919 -0.996 -4.364 -0.293 -1.151 -0.616 -2.293 -0.956 -3.433 -0.301 -1.008 -0.612 -2.014 -0.95 -3.012 -0.531 -1.578 -1.113 -3.142 -1.735 -4.694 -0.216 -0.54 -0.433 -1.082 -0.661 -1.618 -0.195 -0.462 -0.399 -0.917 -0.601 -1.375 -0.262 -0.591 -0.53 -1.177 -0.804 -1.762 -0.074 -0.159 -0.151 -0.315 -0.226 -0.474 -0.209 -0.441 -0.422 -0.881 -0.638 -1.318 -0.076 -0.154 -0.153 -0.306 -0.229 -0.459 -0.236 -0.471 -0.477 -0.939 -0.721 -1.406 -0.053 -0.101 -0.105 -0.201 -0.158 -0.302 -1.143 -2.16 -2.367 -4.269 -3.68 -6.322 -0.116 -0.181 -0.237 -0.359 -0.355 -0.539 -0.094 -0.144 -0.189 -0.288 -0.284 -0.432 -0.284 -0.431 -0.57 -0.861 -0.862 -1.287 -0.112 -0.164 -0.225 -0.326 -0.338 -0.489 -0.193 -0.279 -0.382 -0.56 -0.579 -0.836 -0.089 -0.125 -0.182 -0.249 -0.273 -0.374 -0.13 -0.182 -0.264 -0.362 -0.395 -0.542 -0.277 -0.38 -0.556 -0.76 -0.838 -1.135 -0.15 -0.199 -0.303 -0.395 -0.454 -0.593 -0.21 -0.274 -0.417 -0.552 -0.63 -0.823 -0.055 -0.069 -0.111 -0.136 -0.166 -0.205 -0.482 -0.61 -0.971 -1.216 -1.47 -1.814 -0.129 -0.155 -0.262 -0.306 -0.392 -0.461 -0.402 -0.476 -0.808 -0.95 -1.22 -1.417 -0.186 -0.212 -0.375 -0.422 -0.563 -0.631 -0.384 -0.428 -0.773 -0.854 -1.167 -1.276 -0.176 -0.189 -0.351 -0.379 -0.529 -0.567 -0.564 -0.595 -1.134 -1.186 -1.716 -1.768 -1.091 -1.091 -2.207 -2.15 -3.346 -3.178 -1.016 -0.919 -2.05 -1.815 -3.103 -2.684 -0.772 -0.636 -1.557 -1.255 -2.348 -1.864 -3.465 -2.67 -7.112 -5.075 -10.927 -7.209 -2.869 -1.604 -5.83 -3.06 -8.883 -4.351 -2.443 -1.033 -4.922 -1.948 -7.428 -2.756 -8.879 -2.863 -18.13 -4.318 -27.605 -4.318 -3.19 0 -6.354 0.169 -9.488 0.496 -4.036 0.421 -8.019 1.114 -11.94 2.073 -1.732 0.423 -3.452 0.892 -5.157 1.42 -2.856 0.883 -5.673 1.912 -8.447 3.085 -2.645 1.118 -5.222 2.357 -7.729 3.711 -2.574 1.39 -5.073 2.901 -7.494 4.533 -1.195 0.805 -2.37 1.64 -3.527 2.503 -1.156 0.864 -2.292 1.756 -3.408 2.676 -0.553 0.456 -1.1 0.919 -1.643 1.389 -1.649 1.427 -3.252 2.92 -4.806 4.473 -2.582 2.582 -4.991 5.299 -7.222 8.138 -0.892 1.135 -1.756 2.292 -2.59 3.467 -0.417 0.588 -0.827 1.18 -1.23 1.778 -0.403 0.597 -0.798 1.199 -1.186 1.806 -0.388 0.607 -0.769 1.218 -1.143 1.835 -2.241 3.697 -4.216 7.562 -5.916 11.582 -1.095 2.589 -2.059 5.217 -2.901 7.877 -0.153 0.482 -0.3 0.965 -0.444 1.449 -0.339 1.14 -0.663 2.282 -0.956 3.433 -0.369 1.446 -0.7 2.901 -0.996 4.364 -1.034 5.121 -1.618 10.343 -1.749 15.637 -0.018 0.757 -0.028 1.514 -0.028 2.274 0 1.123 0.02 2.244 0.062 3.361 0.285 7.82 1.568 15.475 3.825 22.879 0.044 0.147 0.088 0.295 0.133 0.441 0.877 2.823 1.894 5.608 3.054 8.35 0.85 2.009 1.769 3.98 2.755 5.912 0.539 1.057 1.105 2.099 1.685 3.132 4.013 7.142 8.98 13.698 14.846 19.564 7.713 7.713 16.611 13.878 26.477 18.352 0.705 0.32 1.415 0.632 2.131 0.935 2.081 0.88 4.185 1.679 6.313 2.396 9.217 3.106 18.85 4.677 28.719 4.677 8.031 0 15.902 -1.047 23.522 -3.107 0.633 -0.172 1.266 -0.35 1.895 -0.535 0.757 -0.222 1.509 -0.456 2.26 -0.698 0.717 -0.232 1.431 -0.474 2.145 -0.723 1.752 -0.616 3.49 -1.281 5.211 -2.009 0.755 -0.319 1.503 -0.651 2.247 -0.989 1.237 -0.563 2.459 -1.15 3.664 -1.766 0.644 -0.328 1.283 -0.665 1.917 -1.009 1.654 -0.896 3.274 -1.848 4.865 -2.844 5.736 -3.591 11.06 -7.827 15.912 -12.679 0.775 -0.775 1.534 -1.562 2.278 -2.36 5.204 -5.59 9.636 -11.754 13.246 -18.417 0.343 -0.634 0.68 -1.274 1.009 -1.917 0.482 -0.944 0.943 -1.9 1.392 -2.863 0.471 -1.007 0.928 -2.021 1.364 -3.049 1.22 -2.886 2.281 -5.82 3.187 -8.793 0.559 -1.833 1.056 -3.68 1.494 -5.542 0.108 -0.458 0.211 -0.916 0.312 -1.376 0.194 -0.883 0.373 -1.77 0.539 -2.659 1.02 -5.455 1.542 -11.02 1.542 -16.663 0 -6.074 -0.595 -12.058 -1.776 -17.911 z m -161.733 19.614 c -1.118 -56.662 44.604 -74.877 60.998 -67.647 2.187 0.965 4.732 2.431 7.042 2.96 5.295 1.213 13.432 -3.113 13.521 6.273 0.078 8.156 -3.389 13.108 -10.797 16.177 -7.539 3.124 -14.777 9.181 -19.95 15.493 -21.487 26.216 -31.231 68.556 -7.565 94.296 -13.679 -5.545 -42.418 -25.467 -43.248 -67.552 z m 91.109 72.619 c -0.053 0.008 -4.171 0.775 -4.171 0.775 0 0 -15.862 -22.957 -23.509 -21.719 11.291 16.04 12.649 22.625 12.649 22.625 -0.053 0.001 -0.107 0.001 -0.161 0.003 -51.831 2.131 -42.785 -64.026 -28.246 -86.502 -1.555 13.073 8.878 39.992 39.034 44.1 9.495 1.293 32.302 -3.275 41.015 -11.38 0.098 1.825 0.163 3.85 0.159 6.013 -0.046 23.538 -13.47 42.743 -36.77 46.085 z m 30.575 -15.708 c 9.647 -9.263 12.869 -27.779 9.103 -44.137 -4.608 -20.011 -28.861 -32.383 -40.744 -35.564 5.766 -8.089 27.908 -14.274 39.567 5.363 -5.172 -10.519 -13.556 -23.023 -1.732 -33.128 12.411 13.329 19.411 29.94 20.161 48.7 0.75 18.753 -6.64 41.768 -26.355 58.765 z"></path>
<circle fill="currentColor" cx="71.927" cy="32.004" r="2.829"></circle>
</svg>

After

Width:  |  Height:  |  Size: 4.7 KiB

View File

@@ -0,0 +1,3 @@
from . import test_fetch_fields
from . import test_server_action
from . import test_submissions

View File

@@ -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,
)

View File

@@ -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"))

View File

@@ -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)

View File

@@ -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"<html>Login</html>"
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())

View File

@@ -0,0 +1,89 @@
<?xml version="1.0" encoding="utf-8" ?>
<odoo>
<record id="docuseal_template_view_list" model="ir.ui.view">
<field name="name">docuseal.template.list</field>
<field name="model">docuseal.template</field>
<field name="arch" type="xml">
<list string="Docuseal templates">
<field name="name"/>
<field name="template_id"/>
<field name="submitter_role_id"/>
<field name="server_action_id"/>
</list>
</field>
</record>
<record id="docuseal_template_view_form" model="ir.ui.view">
<field name="name">docuseal.template.form</field>
<field name="model">docuseal.template</field>
<field name="arch" type="xml">
<form string="Docuseal template">
<header>
<button
name="action_create_server_action"
string="Create contextual action"
type="object"
class="btn-primary"
invisible="server_action_id"
/>
<button
name="action_delete_server_action"
string="Delete contextual action"
type="object"
class="btn-danger"
invisible="not server_action_id"
confirm="Delete the contextual action? It will no longer appear in the Action menu on contacts."
/>
</header>
<sheet>
<group>
<field name="name"/>
<!-- Roles only exist once fetched from Docuseal: from
then on, another template needs a new entry. -->
<field name="role_ids" invisible="1"/>
<field name="template_id" readonly="role_ids"/>
<button
colspan="2"
name="action_fetch_fields"
string="Fetch from Docuseal"
type="object"
class="btn btn-secondary mb8"
invisible="not template_id"
/>
<field
name="submitter_role_id"
options="{'no_create': True, 'no_open': True}"
placeholder="Fetch from Docuseal to list the roles"
/>
</group>
<field name="field_ids" string="Field mapping">
<!-- Lines come from Docuseal only: no manual creation. -->
<list editable="bottom" create="0">
<field name="sequence" widget="handle"/>
<field
name="docuseal_field_name"
readonly="1"
force_save="1"
/>
<field
name="partner_field_id"
domain="[('model', '=', 'res.partner'), ('ttype', 'not in', ['one2many', 'many2many', 'binary'])]"
/>
</list>
</field>
<group>
<field name="server_action_id" readonly="1"/>
</group>
</sheet>
</form>
</field>
</record>
<record id="docuseal_template_action" model="ir.actions.act_window">
<field name="name">Docuseal templates</field>
<field name="res_model">docuseal.template</field>
<field name="view_mode">list,form</field>
</record>
</odoo>

View File

@@ -0,0 +1,52 @@
<?xml version="1.0" encoding="utf-8" ?>
<odoo>
<record id="res_config_settings_view_form_docuseal" model="ir.ui.view">
<field name="name">res.config.settings.view.form.inherit.docuseal</field>
<field name="model">res.config.settings</field>
<field name="inherit_id" ref="base.res_config_settings_view_form"/>
<field name="arch" type="xml">
<xpath expr="//form" position="inside">
<app
data-string="Docuseal signing"
string="Docuseal signing"
name="docuseal_signing"
logo="/docuseal_signing/static/description/icon.svg"
>
<block title="Configuration" name="docuseal_config">
<setting
string="API URL"
help="Base URL of the Docuseal instance (e.g. https://sign.elabore.coop)"
id="docuseal_api_url_setting"
>
<field name="docuseal_api_url"/>
</setting>
<setting
string="API token"
help="Authentication token (X-Auth-Token header)"
id="docuseal_api_token_setting"
>
<field name="docuseal_api_token" password="True"/>
</setting>
</block>
<block title="Docuseal templates" name="docuseal_templates">
<setting
string="Configure templates"
help="Define field mappings and generate contextual actions on contacts"
id="docuseal_templates_setting"
>
<button
name="%(docuseal_signing.docuseal_template_action)d"
type="action"
string="Manage Docuseal templates"
class="btn-link"
icon="oi-arrow-right"
/>
</setting>
</block>
</app>
</xpath>
</field>
</record>
</odoo>