Add support for v2/jobs/get-errors API (#819)

Author: kailash-b

Examples.md

@@ -260,6 +260,7 @@ public async Task LoginWithClientCredentialsAndMonitorClientQuota()
     - [2.1. Update Default Token Quota at Tenant level](#21-update-default-token-quota-at-tenant-level)
     - [2.2 Update Token Quota at Client level](#22-update-token-quota-at-client-level)
     - [2.2 Update Token Quota at Organisation level](#23-update-token-quota-at-organisation-level)
+- [3. Get Job Error Details](#3-get-job-error-details)
 
 ## 1. Management Client Initialization
 
@@ -368,3 +369,36 @@ Assuming you have an access token available with the required scopes.
 
 ```
 ⬆️ [Go to Top](#)
+
+## 3. Get Job Error Details
+
+When a job fails, you can get the error details using the `GetErrorDetailsAsync` method.
+The response (of type `JobError`) will either contain `JobImportErrorDetails[]` or `JobErrorDetails` depending on the type of job.
+
+Assuming you have an access token available with the required scopes and the `apiClient` is initialized as shown in the previous sections.
+```csharp
+
+public async void GetJobErrorDetails(string jobId) {
+    
+    var jobId = "your_job_id";    
+    var jobError = await apiClient.Jobs.GetErrorDetailsAsync(jobId);
+    
+    Console.WriteLine($"Job ID: {jobId}");
+    Console.WriteLine($"Job Type: {jobError.JobErrorDetails.Type}");
+    Console.WriteLine($"Job Status: {jobError.JobErrorDetails.Status}");
+    Console.WriteLine($"Job Id: {jobError.JobErrorDetails.Id}");
+    Console.WriteLine($"Job Connection: {jobError.JobErrorDetails.Connection}");
+    Console.WriteLine($"Job Connection Id: {jobError.JobErrorDetails.ConnectionId}");
+    Console.WriteLine($"Job Created At: {jobError.JobErrorDetails.CreatedAt}");
+    Console.WriteLine($"Job Status Details: {jobError.JobErrorDetails.StatusDetails}");
+
+    // OR 
+    Console.WriteLine($"Job User object: {jobError.JobImportErrorDetails[0].User}");
+    Console.WriteLine($"Job Error Code: {jobError.JobImportErrorDetails[0].Errors[0].Code}");
+    Console.WriteLine($"Job Error Code: {jobError.JobImportErrorDetails[0].Errors[0].Message}");
+    Console.WriteLine($"Job Error Code: {jobError.JobImportErrorDetails[0].Errors[0].Path}");
+}
+
+
+```
+⬆️ [Go to Top](#)

src/Auth0.ManagementApi/Clients/IJobsClient.cs

@@ -52,5 +52,13 @@ public interface IJobsClient
     /// <param name="cancellationToken">The cancellation token to cancel operation.</param>
     /// <returns>A <see cref="Job"/> instance containing the information about the job.</returns>
     Task<Job> SendVerificationEmailAsync(VerifyEmailJobRequest request, CancellationToken cancellationToken = default);
+    
+    /// <summary>
+    /// Retrieve error details of a failed job.
+    /// </summary>
+    /// <param name="id">The ID of the job.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to cancel operation.</param>
+    /// <returns><see cref="JobError"/></returns>
+    Task<JobError> GetErrorDetailsAsync(string id, CancellationToken cancellationToken = default);
   }
 }

src/Auth0.ManagementApi/Clients/JobsClient.cs

@@ -5,6 +5,7 @@
 using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
+using Newtonsoft.Json;
 
 namespace Auth0.ManagementApi.Clients
 {
@@ -35,7 +36,8 @@ public JobsClient(IManagementConnection connection, Uri baseUri, IDictionary<str
         /// <returns>A <see cref="Job"/> instance containing the information about the job.</returns>
         public Task<Job> GetAsync(string id, CancellationToken cancellationToken = default)
         {
-            return Connection.GetAsync<Job>(BuildUri($"jobs/{EncodePath(id)}"), DefaultHeaders, cancellationToken: cancellationToken);
+            return Connection.GetAsync<Job>(BuildUri($"jobs/{EncodePath(id)}"), DefaultHeaders,
+                cancellationToken: cancellationToken);
         }
 
         /// <summary>
@@ -52,7 +54,8 @@ public Task<Job> GetAsync(string id, CancellationToken cancellationToken = defau
         /// <param name="sendCompletionEmail">Whether to send the user an email on import completion (true) or not (false).</param>
         /// <param name="cancellationToken">The cancellation token to cancel operation.</param>
         /// <returns>A <see cref="Job"/> instance containing the information about the job.</returns>
-        public Task<Job> ImportUsersAsync(string connectionId, string fileName, Stream file, bool? upsert = null, string externalId = null, bool? sendCompletionEmail = null, CancellationToken cancellationToken = default)
+        public Task<Job> ImportUsersAsync(string connectionId, string fileName, Stream file, bool? upsert = null,
+            string externalId = null, bool? sendCompletionEmail = null, CancellationToken cancellationToken = default)
         {
             if (file == null)
                 throw new ArgumentNullException(nameof(file));
@@ -75,7 +78,8 @@ public Task<Job> ImportUsersAsync(string connectionId, string fileName, Stream f
                 }
             };
 
-            return Connection.SendAsync<Job>(HttpMethod.Post, BuildUri("jobs/users-imports"), parameters, DefaultHeaders, files: fileParameters, cancellationToken: cancellationToken);
+            return Connection.SendAsync<Job>(HttpMethod.Post, BuildUri("jobs/users-imports"), parameters,
+                DefaultHeaders, files: fileParameters, cancellationToken: cancellationToken);
         }
 
         /// <summary>
@@ -89,7 +93,8 @@ public Task<Job> ImportUsersAsync(string connectionId, string fileName, Stream f
         /// <returns>A <see cref="Job"/> instance containing the information about the job.</returns>
         public Task<Job> ExportUsersAsync(UsersExportsJobRequest request, CancellationToken cancellationToken = default)
         {
-            return Connection.SendAsync<Job>(HttpMethod.Post, BuildUri("jobs/users-exports"), request, DefaultHeaders, cancellationToken: cancellationToken);
+            return Connection.SendAsync<Job>(HttpMethod.Post, BuildUri("jobs/users-exports"), request, DefaultHeaders,
+                cancellationToken: cancellationToken);
         }
 
         /// <summary>
@@ -98,9 +103,48 @@ public Task<Job> ExportUsersAsync(UsersExportsJobRequest request, CancellationTo
         /// <param name="request">The <see cref="VerifyEmailJobRequest"/> containing the information of the user whose email you want verified.</param>
         /// <param name="cancellationToken">The cancellation token to cancel operation.</param>
         /// <returns>A <see cref="Job"/> instance containing the information about the job.</returns>
-        public Task<Job> SendVerificationEmailAsync(VerifyEmailJobRequest request, CancellationToken cancellationToken = default)
+        public Task<Job> SendVerificationEmailAsync(VerifyEmailJobRequest request,
+            CancellationToken cancellationToken = default)
         {
-            return Connection.SendAsync<Job>(HttpMethod.Post, BuildUri("jobs/verification-email"), request, DefaultHeaders, cancellationToken: cancellationToken);
+            return Connection.SendAsync<Job>(HttpMethod.Post, BuildUri("jobs/verification-email"), request,
+                DefaultHeaders, cancellationToken: cancellationToken);
+        }
+
+        /// <inheritdoc cref="IJobsClient.GetErrorDetailsAsync"/>>
+        public Task<JobError> GetErrorDetailsAsync(string id, CancellationToken cancellationToken = default)
+        {
+            var rawResponse = 
+                Connection.GetAsync<string>(
+                    BuildUri($"jobs/{EncodePath(id)}/errors"), DefaultHeaders, cancellationToken: cancellationToken).Result;
+
+            if (string.IsNullOrEmpty(rawResponse)) return null;
+
+            try
+            {
+                var jobImportErrorDetails = JsonConvert.DeserializeObject<JobImportErrorDetails[]>(rawResponse);
+                if (jobImportErrorDetails?.Length > 0)
+                {
+                    return Task.FromResult(new JobError
+                    {
+                        JobImportErrorDetails = jobImportErrorDetails
+                    });
+                }
+            }
+            catch (JsonSerializationException ex)
+            {
+                // ignoring the exception to try to serialize to JobErrorDetails.     
+            }
+
+            var jobErrorDetails = JsonConvert.DeserializeObject<JobErrorDetails>(rawResponse);
+            if (jobErrorDetails != null)
+            {
+                return Task.FromResult(new JobError
+                {
+                    JobErrorDetails = jobErrorDetails
+                });
+            }
+
+            return null;
         }
     }
-}
+}

src/Auth0.ManagementApi/Models/Job.cs renamed to src/Auth0.ManagementApi/Models/Jobs/Job.cs

@@ -0,0 +1,69 @@
+using Newtonsoft.Json;
+
+namespace Auth0.ManagementApi.Models
+{
+ 
+    /// <summary>
+    /// Contains information about the Jobs error status.
+    /// </summary>
+    public class JobError
+    {
+        /// <inheritdoc cref="JobImportErrorDetails"/>
+        public JobImportErrorDetails[] JobImportErrorDetails { get; set; }
+        
+        /// <inheritdoc cref="JobErrorDetails"/>
+        public JobErrorDetails JobErrorDetails { get; set; }
+    }
+
+    /// <summary>
+    /// Contains details of the Job including the status and failure reason
+    /// </summary>
+    public class JobErrorDetails : Job
+    {
+        /// <summary>
+        /// Status details.
+        /// </summary>
+        [JsonProperty("status_details")]
+        public string StatusDetails { get; set; }
+    }
+    
+    /// <summary>
+    /// Contains information of the error that failed the job
+    /// </summary>
+    public class JobImportErrorDetails
+    {
+        /// <summary>
+        /// User, as provided in the import file
+        /// </summary>
+        [JsonProperty("user")]
+        public object User { get; set; }
+        
+        /// <inheritdoc cref="Error"/>
+        [JsonProperty("errors")]
+        public Error[] Errors { get; set; }
+    }
+
+    /// <summary>
+    /// Errors importing the user.
+    /// </summary>
+    public class Error
+    {
+        /// <summary>
+        /// Error code.
+        /// </summary>
+        [JsonProperty("code")]
+        public string Code { get; set; }
+        
+        /// <summary>
+        /// Error message.
+        /// </summary>
+        [JsonProperty("message")]
+        public string Message { get; set; }
+        
+        /// <summary>
+        /// Error field.
+        /// </summary>
+        [JsonProperty("path")]
+        public string Path { get; set; }
+    }
+}

src/Auth0.ManagementApi/Models/Jobs/JobErrorDetails.cs

@@ -30,9 +30,16 @@
   </ItemGroup>
 
   <ItemGroup>
+    <EmbeddedResource Include="Data\UsersImportInvalidFile.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </EmbeddedResource>
     <EmbeddedResource Include="user-import-test.json">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </EmbeddedResource>
+    <None Remove="Data\UsersImportInvalid.json" />
+    <EmbeddedResource Include="Data\UsersImportInvalid.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </EmbeddedResource>
   </ItemGroup>
 
   <ItemGroup>

src/Auth0.ManagementApi/Models/JobSummary.cs renamed to src/Auth0.ManagementApi/Models/Jobs/JobSummary.cs

@@ -0,0 +1,18 @@
+[
+  {
+    "email": "john.doe1@nonexistingdomain",
+    "email_verified": true,
+    "app_metadata": {
+    },
+    "user_metadata": {
+    }
+  },
+  {
+    "email": "john.doe2@nonexistingdomain",
+    "email_verified": true,
+    "app_metadata": {
+    },
+    "user_metadata": {
+    }
+  }  
+]

src/Auth0.ManagementApi/Models/UsersExportsJobField.cs renamed to src/Auth0.ManagementApi/Models/Jobs/UsersExportsJobField.cs

@@ -0,0 +1,10 @@
+[
+  {
+    "email": "[email protected]",
+    "email_verified": tre,
+    "app_metadata": {
+    },
+    "user_metadata": {
+    }
+  }
+]