Add workflow recipients and auto place their fields
===================================================

Add anchors tag to your document
--------------------------------

For YumiSign to be able to auto place the fields on your document you need to add an anchor for each field on your original document.
The anchors need to have a specific format. Anchors can also be the same color as the document background color. This way it will not be visible on the original document.

Anchor tag format
-----------------

To be able to have a unique anchor format for YumiSign and to avoid adding fields just from document text,
the anchor should have this format: **yumisign_{field_type}_{recipient_tag}** .

Field types
-----------

The ``field_type`` is case-sensitive, and must contain one of the following field types:

* date

* email

* signature

* initials

* title

* company

* fullName

* address

Recipient tags
--------------

The recipient tag, is a tag that you will attach to each recipient, to be able to know which anchor tag from the document is for which recipient. It can contain any string you want to give to identify your recipient.

For example, if you have a selling car contract, you can use seller and buyer tags, so when you add your recipients, you need to define the right tag for the right recipient in the field ``anchorTag``

Best practices
--------------

For better results, you can define the documents and pages where you have added the anchors in your recipient ``anchorTag``.
For example if you have a document with 10 pages, and you have added the tags to the only last two pages,
it is better to add the document id/page number to the tag when attaching it to the recipient.
If the anchors where for both seller and buyer, the tags should have this format for example: seller-1_9,1_10 and buyer-1_9,1_10
where we have ``tag-documentId_pageNumber, documentId_pageNumber, etc..``
You should make sure that you either define all the pages or do not define them at all.
You cannot define some of the pages and expect YumiSign to define the other ones.

Route
-----

You are going to use the same route as adding the recipients, just with passing ``anchorAutoPlace`` with value true, and add the ``anchorTag`` to the recipients.

+--------+---------------------------------------------------------------+
| Method | Path                                                          |
+========+===============================================================+
| PUT    | /api/v1/workspaces/{workspaceId}/workflows/{workflowId}/roles |
+--------+---------------------------------------------------------------+

.. warning::

    Add workflow recipients using ``/api/v1/workflows/{id}/roles`` is deprecated.
    You need to pass the workspace id on the path.

Parameters
----------

* ``anchorAutoPlace`` bool | optional

The flag that will determine if you want YumiSign to check the document for anchors and auto place fields.

* ``recipients`` array | required

The list of recipients for your workflow. It must contain at least one item.

* ``recipients[0].id`` string | optional

The optional recipient id to use in updating context.

* ``recipients[0].name`` string | required

The recipient name.

* ``recipients[0].email`` string | required

The recipient email address.

* ``recipients[0].anchorTag`` string | optional

The anchor tag that you have added so YumiSign can link the anchor with this recipient.

* ``recipients[0].roles`` array | required

An array of roles for your recipient.

* ``recipients[0].roles[0].type`` enum | required

+--------+--------------------------------------+
| Value  | Description                          |
+========+======================================+
| sign   | A recipient must sign the document   |
+--------+--------------------------------------+
| review | A recipient must review the document |
+--------+--------------------------------------+

* ``recipients[0].roles[0].color`` string | required

A hexadecimal color representing your recipient role.

Example
"""""""

In this image you can see the format of the anchors that has been already added to the document.

.. image:: images/black_anchor.png
   :width: 600
   :align: center

In this image you cannot see the anchors, because their color is the same as the background, but they are still there.

.. image:: images/white_anchor.png
   :width: 600
   :align: center

In this picture you can see the result after auto placing the fields with YumiSign.

.. image:: images/anchor_fields.png
   :width: 600
   :align: center

.. code-block:: bash

    curl --request PUT 'https://app.yumisign.com/api/v1/workspaces/1/workflows/1/roles' \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "anchorAutoPlace": true,
            "recipients": [
                {
                    "name": "Johnny Depp",
                    "email": "recipient1@email.com",
                    "anchorTag": "seller"
                    "roles": [
                        {
                            "id":1,
                            "type": "sign",
                            "color": "#EE8320"
                        }
                    ]
                },
                {
                    "name": "Amber Heard",
                    "email": "recipient2@email.com",
                    "anchorTag": "buyer"
                    "roles": [
                        {
                            "id":1,
                            "type": "sign",
                            "color": "#EE8320"
                        }
                    ]
                }
            ]
        }'

.. code-block:: json

    [
        {
            "picture": null,
            "roles": [
                {
                    "type": "sign",
                    "color": "#EE8320",
                    "id": 24
                }
            ],
            "email": "recipient1@email.com",
            "id": 24,
            "name": "Johnny Depp"
        },
        {
            "picture": null,
            "roles": [
                {
                    "type": "sign",
                    "color": "#EE8320",
                    "id": 25
                }
            ],
            "email": "recipient2@email.com",
            "id": 25,
            "name": "Amber Heard"
        }
    ]