Using DDV2 Client nugget

Version 1.0.9

Overview

The DDV2 Client Nugget provides a simple and Streamlined way to interact with DocDigitizer API by incorporating it in any DotNet project.
Used together with the WorldObjects Nugget makes possible to quickly and efficiently setup a consumer of DocDigitizer services with a Strongly Typed interface

The asynchronous approach allows it to be used in services or unattended integrations where a callback method can be provided for further

Installation

The Nugget is publicly available from DocDigitizer github:
https://github.com/orgs/DocDigitizer/packages/nuget/package/DocDigitizer.ClientNuggets.DDV2

Normal nugget installation procedures apply.

Configuration

Before usage, the DDV2Driver must be setup. To do so one must invoke the Startup method of the DDV2Driver class within the Nugget.
Commonly the following code is used:

Sample Program.cs snippet with DDV2Driver Startup

builder.ConfigureServices((hostContext, services) =>
{
    services.AddLogging(logging =>
    {
        logging.ClearProviders();
        logging.AddConsole();
        logging.AddFile(options => { hostContext.Configuration.GetSection("Logging:File").Bind(options); }); //Requires nuget NetEscapades.Extensions.Logging.RollingFile
    });

    services.AddSingleton<List<DDV2ClientConfigurationSettings>>((options) =>
    {
        var ddv2ClientConfigurationSettings = new List<DDV2ClientConfigurationSettings>();
        hostContext.Configuration.GetSection("DDV2Client").Bind(ddv2ClientConfigurationSettings);
        return ddv2ClientConfigurationSettings;
    });

});

(...)

DDLogger.Startup(logger);
DDV2Driver.Startup(host.Services.GetRequiredService<List<DDV2ClientConfigurationSettings>>(), TestCallbacksHandler.OnDDV2DocumentSubmitted);

In the code above, note that there is a dependency for the DDLogger that will provide logging capabilities to the DDV2 Client Nugget module. Also note the second parameter of the startup, it is an optional method that will be invoked every time a document is submitted to DocDigitizer.

In order for the example startup code to work a valid configuration must be setup in the appsettings.json file (or equivalent) a common configuration example follows:

Sample appsettings.json snippet with DDV2Client configuration

Note that the entry contains an array, thus allowing nugget clients to use the same driver for different API Keys or different callbacks

"DDV2Client": [{
  "Identifier": "TestDDV2Client",
  "AuthBaseUrl": "https://auth.docdigitizer.com",
  "AgwBaseUrl": "https://assetgw.docdigitizer.com",
  "ApiKey": "00000000-0000-0000-0000-000000000000",
  "SemanticObjectCallbacks": [
    {
      "SemanticObjectUUID": "3b710fcb-1c28-40ed-ab35-77f8e51d20ee",
      "SemanticObjectLabel": "FinancialDocument",
      "OnSemanticObjectAssembly": "TestDDV2Client",
      "OnSemanticObjectClass": "TestDDV2Client.TestCallbacksHandler",
      "OnSemanticObjectMethod": "OnFinancialDocumentReady"
    },
    {
      "SemanticObjectUUID": "a90faac1-0e2e-405a-a64c-1eccc2e96f74",
      "SemanticObjectLabel": "Payslip",
      "OnSemanticObjectAssembly": "TestDDV2Client",
      "OnSemanticObjectClass": "TestDDV2Client.TestCallbacksHandler",
      "OnSemanticObjectMethod": "OnPayslipReady"
    }
  ]
},
(...)
]

Usage

There are three ways to use the DDV2 Client and obtain extraction data from uploaded documents

1. Response managed by the customer
   In this scenario, the nugget integrator will invoke teh Upload document method that is not associated to any generic type and returns a DocDigitizer Response.
   Aftewards, the integrator can use the id contained in that response and the GetDocumentState method to pool DocDigitizer while waiting for the annotation to be concluded.
   Alternativelly, one can provide a callback back method on the optional callbackV3WhenReady parameter. This method will be invoked as soon as DocDigitizer has the annotation ready, this way the pooling mechanism is made by the DDV2 Client nugget.

Sample code for submitting an Invoice and obtaining the first get state from DocDigitizer

Console.WriteLine("Submitting an invoice");
var test1DDV2ResponseV3 = DDV2Driver.UploadDocument(invoiceFilePath, null, null, withHuman: false, withSync: false, documentClass: "financialdocument", pipeline: "llm01");
Console.WriteLine("Invoice submitted");
Console.WriteLine($"Getting doc {test1DDV2ResponseV3.Id} state");
var test1DDV2ResponseV3_2 = DDV2Driver.GetDocumentStateV3(test1DDV2ResponseV3.Id);
Console.WriteLine($"Doc {test1DDV2ResponseV3.Id} state is {test1DDV2ResponseV3_2.StateText}");

2. Known Semantic Object handled by the library
   If the customer is using DocDigitizer's WorldObjects library, he can use a strong typed approach to DocDigitizer integration. One can submit the document stating the type of the semantic object that is expected to be returned, the driver will handle all synchronization issues and parsing so that the integrator can only worry with his own code.
   Again two ways of operation are possible, one where a callback method is passed, making the call asynchronous and the other without the callback method that will lock execution until a response is obtained from DocDigitizer

Sample code for submitting an Invoice, continuing execution as callback will be invoked when ready

Console.WriteLine("Submitting an invoice");
DDV2Driver.UploadDocument<FinancialDocumentV002>(invoiceFilePath, TestCallbacksHandler.OnFinancialDocumentReady, withHuman: false, withSync: false, documentClass: "financialdocument", pipeline: "llm01");
Console.WriteLine($"Invoice submitted callback will be invoked when ready");

3. Known Semantic object with pre configured callbacks
   The last form is an evolution from the second one. The integrator use WorldObjects as well but the callbacks are defined on Startup from the mappings found in the appsettings.json

Sample code for submitting a Paystup, continuing execution as callback will be invoked when ready

Console.WriteLine("Submitting a paystup");  
DDV2Driver.UploadDocument(payslipFilePath, withHuman: false, withSync: false, documentClass: "payslip", pipeline: "llm01");  
Console.WriteLine($"Paystub submitted callback will be invoked when ready");