Get and Update the Recipient

Let's make a handy reusuable class to do the housework for us, including authentication and executing requests to the GraphQL API. If you're following along then copy the following class into your project... and if you want to skip to the final construction then there is a github project supplied at the end so that you can try out the code.

CLIUpdateRecipient.cs

using System.Text.Json.Nodes;
using CLILegalesignExamples;
using System.Text.Json;

namespace CLILegalesignExamples
{
    // These classes are intentionally empty for the purpose of this example. They are simply marker classes for the purpose of demonstration, contain no properties, and serve no other purpose.
    class CLIUpdateRecipient
    {
        static async Task Main(string[] args)
        {
            Console.WriteLine("Legalesign C# Update Recipient Tool");

            // First we need a valid security token
            string token = await GraphQLLegalesign.GetCredsAsync(args[0], args[1]);

            Console.WriteLine($"Fetching recipients for document {args[2]}.");
            var data = await GraphQLLegalesign.QueryAsync(@"query getDocument($documentId:ID) {
                document(id: $documentId) {
                    id
                    recipients {
                        id
                        email
                        firstName
                        lastName
                    }
                }
                }", new { documentId = args[2] }, token);   

            Console.WriteLine(data);

            if (data == null) return;
        
            QLResponse? d = JsonSerializer.Deserialize<QLResponse>(data);
            QLRecipient? oldRecipient = d.data.document.recipients.Find(r => r.email == args[3]);

            if (oldRecipient != null)
            {
                dynamic newRecipient = new
                {
                    recipientId = oldRecipient.id,
                    email = args[4],
                    expiryDate = "2026-10-10T00:00:00.000Z",
                    firstName = args[5],
                    lastName = args[6]
                };

                // Got one! Let's update it.
                await UpdateRecipientAsync(oldRecipient, newRecipient, token);

            }
            else
            {
                Console.WriteLine($"WARNING::Unable to find recipient {args[3]} on document {args[2]}.");
            }

            async Task UpdateRecipientAsync(dynamic oldRecipient, dynamic newRecipient, string token)
            {
                // Note we are using the variables parameter -- but you can code values into your query/mutation string
                // We also set it not to inform the previous recipient by email - you may want this option.
                var data = await GraphQLLegalesign.QueryAsync(@"mutation ChangeRecipient(
                    $recipientId: ID!,
                    $email: String,
                    $expiryDate: AWSDateTime,
                    $firstName: String,
                    $lastName: String
                    ) {
                    updateRecipient(
                        input: {
                    recipientId: $recipientId, 
                                        email: $email, 
                                        emailPreviousIfReplaced: false, 
                                        expiryDate: $expiryDate, 
                                        firstName: $firstName, 
                                        lastName: $lastName
                                    }
                            )
                        }
                ", newRecipient, token);

                // Let's check that it worked!
                QLMutation mut = JsonSerializer.Deserialize<QLMutation>(data);

                // Check for device locked witness etc.
                if(mut.errors != null) Console.WriteLine("ERROR::" + mut.errors[0].message);
                else Console.WriteLine("Recipient updated.");
            }
        }
    }
}

As you can see we fetch all the recipients for our document and then find the lucky one with the email address supplied. If we don't find the email address we issue a warning in the console. For brevity we've make some simple classes to help Deserialize our JSON. You can manually create your own, use a tool to reverse engineer them like this or use one of the libraries that will attempt to generate classes from the schema of the API.

Here are the classes.

using System.Globalization;
using System.Text.Json;
using System.Text.Json.Serialization;


namespace CLILegalesignExamples
{
    public class QLRecipient
    {
        public string? id { get; set; }
        public string? firstName { get; set; }
        public string? lastName { get; set; }
        public string? email { get; set; }
    }

    public class QLDocument
    {
        public string? id { get; set; }
        public List<QLRecipient>? recipients { get; set; }
    }

    public class QLData
    {
        public QLDocument? document { get; set; }      
    }

    public class QLResponse
    {
        public QLData? data { get; set; }      
    }

       public class Data
    {
        public object updateRecipient { get; set; }
    }

    public class Error
    {
        public List<string> path { get; set; }
        public object data { get; set; }
        public string errorType { get; set; }
        public object errorInfo { get; set; }
        public List<Location> locations { get; set; }
        public string message { get; set; }
    }

    public class Location
    {
        public int line { get; set; }
        public int column { get; set; }
        public object sourceName { get; set; }
    }

    public class QLMutation
    {
        public Data data { get; set; }
        public List<Error>? errors { get; set; }
    }
}

You can find all this in our example projects. Here (https://github.com/legalesign/CsharpGraphQLExamples)!

Though we've move the token fetcher and API calling code into a reusable class GraphQLLegalesign, if there's interest in an SDK version of this then we'll produce a library with far more exception handling and useful classes - this version is provided to show as clearly and simply what is happening.

warning

Note the error checking after the update has been executed. The API will sometimes warn you when business rules are being broken. Some recipients cannot be updated for example if the settings demand that they must witness on the same device as the signed (device locked).