Modifying and Handling Data

Congratulations! You've set up a secure connection and got information back from the platform. Sure it may not seem like much but actually you've don't almost all the hard work required for making complex integrations with the Legalesign platform. In the next steps we'll take a more complex task and break down how to action it by altering the code we already have.

Update a Recipient

Suppose we've sent out lots of documents to be signed by customers. Frustratingly, the occasional document bounces off an old employees email address or the client gets in touch to tell us that a different person is the signer for your document. We need to update the recipient for some of our documents - can we build a tool to take care of this?

We'll stick with a command line version that takes several arguments (although you may be integrating this into a CRM page or plugin, you'll need roughly the same arguments):

• the document id (it looks like a base64 string key, all API IDs will look like this)
• the old recipient email
• the new user email
• the new user first name
• the new user last name
• the api username
• the api password

Finding the Recipient ID

We could insist that the user of our utility passes the correct recipient ID - Legalesign allows multiple signers and witnesses on a single document - but let's be more flexible. If the user passes a documentId we'll look up the recipient by email address. This may not cover your use-case but it will give you enough knowledge to see how many other scenarios could be handled.

Get Recipients for a Document

Here's the query which we'll use to get all the document details. Notice how graphQL is letting you return tree structured data with just the fields you're interested in - this is what makes it a better choice than REST for hierarchical data.

An easy way to get a sample documentId from Console is to go to the Document Details page from the dashboard. Get the document ID from the URL after the /details/ section, so in https://console.legalesign.com/group/Z3JwbGVnYWxlc2lnbxRldg==/details/ZG9jMWVmMjdkYWYtMGJlMS0LWJiYjUtMDZlNDc2YTA3NTY5 you'd copy ZG9jMWVmMjdkYWYtMGJlMS0LWJiYjUtMDZlNDc2YTA3NTY5 as the documentId to test with.

{
  document(id: "ZG9jMWVmMjdkYWYtMGJlMS0xMWYwLWJiDVCXMDZlNDc2YTA3NTY5") {
    id
    recipients {
      id
      email
      firstName
      lastName
    }
  }
}

You can take your queries (or mutations) and test them in the GraphIQL Explorer before trying to write code around them. This tends to eliminate one potential source of errors early from our code. If you run the above query without changing anything you should get the NOSUCHID warning (DON'T PANIC):

{
  "data": {
    "document": null
  },
  "errors": [
    {
      "path": [
        "document"
      ],
      "data": {
        "id": "ZG9jMWVmMjdkYWYtMGJlMS0LWJiYjUtMDZlNDc2YTA3NTY5",
        "recipients": null
      },
      "errorType": "WARNING",
      "errorInfo": null,
      "locations": [
        {
          "line": 2,
          "column": 5,
          "sourceName": null
        }
      ],
      "message": "NOSUCHID"
    }
  ]
}```

But if you swap the ID for a valid one from your team you should see something like
the following:

```json
{
  "data": {
    "document": {
      "id": "ZG9jMWVmMjdkYWYtMGJlMS0xMWYwLWJiYjUtMDZlNDc2YTA3NTY5",
      "recipients": [
        {
          "id": "cmVjMjEwMzE4MjUtMGJlMS0xMWYwLWJiYjUtMDZlNDc2YTA3NTY5",
          "email": "alex.Test@legalesign.com",
          "firstName": "Alex",
          "lastName": "Test"
        },
        {
          "id": "cmVjMjFhMzYyMjUtMGJlMS0xMWYwLWJiYjUtMDZlNDc2YTA3NTY5",
          "email": "test+1@legalesign.com",
          "firstName": "Alex",
          "lastName": "Test"
        },
        {
          "id": "cmVjMjA0ZDE1ZjUtMGJlMS0xMWYwLWJiYjUtMDZlNDc2YTA3NTY5",
          "email": "alex.test@legalesign.com",
          "firstName": "Alex",
          "lastName": "Test"
        },
        {
          "id": "cmVjMjEwYTcyY2MtMGJlMS0xMWYwLWJiYjUtMDZlNDc2YTA3NTY5",
          "email": "alex.test+2@legalesign.com",
          "firstName": "Alex",
          "lastName": "Test"
        },
        {
          "id": "cmVjMjBlZWI3NDYtMGJlMS0xMWYwLWJiYjUtMDZlNDc2YTA3NTY5",
          "email": "alex.Test@legalesign.com",
          "firstName": "Alex",
          "lastName": "Test"
        }
      ]
    }
  }
}

Your document may not have quite that many recipients, but it illustrates our point that we may well need to choose someone other than the first recipient.

info

Most email servers allow the +x after your name in the email address. You can use this for testing multiple recipients where the Template knows that in real life a signer and her witness should be different people, with different email addresses.

Okay, let's get this overly thought out logic into some code!