Tutorial - Use case Logistics

DocDigitizer WorldObjects Tutorial

Use case

Requirements

For this tutorial we will be crating simple logistics scenario where we have to managed 2 types of documents

  • Shipping Guide
  • Transport Guide

This 2 types of documents and their information will be transpose to the following object diagram:

The objects with orange frame are reference objects (with reference data), that will be configured as Catalogs
With blue frame are the main objects.
In the diagram there also relations (associations) between the objects.

Tutorial

Can watch video of this tutorial:

Let's begin with tutorial

Create Objects

Lets start creating the first object (Shipping Item)
Open your Visual Code and login.

Create object "ShippingItem"

Add "New folder" with name "Logistics" on your workspace
Add "New Object" with name "ShippingItem" on the folder "Logistics"
Add properties to the object

Property itemId        type Text    description "Item identification"
Property itemName  type Text    description "Item name"
Property amount      type Decimal    description "Item Amount"
Property vatAmount type Decimal    description "Item Vat Amount"

Save file

Create object "ShippingGuide"

Add "New Object" with name "ShippingGuide" on the folder "Logistics"
Add properties to the object

Property clientName            type Text    description "Client Name"
Property clientTaxId              type Text    description "Client Tax ID"
Property documentNumber type Text    description "Document Number"
Property emissionDate         type Date    description "Emission Date"
Property totalAmount           type Decimal    description "Total Amount"
Property vatAmount             type Decimal    description "Vat Amount"
Property vendorName          type Text    description "Vendor Name"
Property vendorTaxId           type Text    description "Vendor Tax ID"

Primary Indexer documentNumber //Property documentNumber must have unique values

Add reference "ShippingItem" to "ShippingGuide"

The "ShippingGuide" object can have 1..N "ShippingItem"
To add this reference add the following to the "ShippingGuide"

Collection items of ShippingItem objects //list (collection) of objects of type "ShippingItem"

note: when saving, in the terminal you will see the following error because we don't have yet the build defined:
Member 'currency' using 'Logistics.ShippingItem': object is not included on build definition

Save file

Create object "Currency"

As you can see on above diagram, the "ShippingGuide" have reference to a object "Currency".
We also specify that object "Currency" is reference data, that is, this object will have Catalog associate.
Lets create first the object and reference and later add Catalog.

On root of your workspace ("MyObjects") add "New Object" with name "Currency".
Add properties to the object

Object Currency
Version 1.0.0

Property Code
Property Description type Text

Primary Indexer Code //Property Code must have unique values

Save file

Add reference "Currency" to "ShippingGuide"

The "ShippingGuide" object can have 1..1 "Currency"
To add this reference add the following to the "ShippingGuide"

Reference currency to MyObjects.Currency 

Save file
note: when saving, in the terminal you will see the following error because we don't have yet the build defined:
Member 'currency' using 'MyObjects.Currency': object is not included on build definition

Create object "TransportGuide"

Add "New Object" with name "TransportGuide" on the folder "Logistics"
Add properties to the object

Property documentNumber type Text    description "Document Number"
Property transporterName    type Text    description "Transporter Name"
Property destinationAddress    type Text    description "Destination Address"
Reference destinationCountry    to Global.Country   
Property deliverDate    type Date    description "Deliver Date"

Collection shippingGuides of ShippingGuide objects

Primary Indexer documentNumber //Property documentNumber must have unique values

Save file

After creating this objects, your workspace should look like:

Create Build

Lets now create the build.

Go to your "BUILDS" workspace area and on "MyBuilds" add "New Build" with name "Logistics"
Note: by default when creating new build file the following objects are add to build file:

// Global
Include Global.Comment.1.0.0
Include Global.Country.1.0.1
Include Global.Language.1.0.0
Include Global.LanguageDialect.1.0.0
Include Global.OneOf.1.0.0
Include Global.Picture.1.0.0

Add Objects to Build

on the build "Logistics" and the objects created previously and the following lines to the file:

// MyObjects
Include MyObjects.Currency.1.0.0

// MyObjects.Logistics
Include MyObjects.Logistics.ShippingGuide.1.0.0
Include MyObjects.Logistics.ShippingItem.1.0.0
Include MyObjects.Logistics.TransportGuide.1.0.0

Save the file and perform the build
Check your terminal to see log of the build for any errors.
Clean log build for this case should like:

16:49:16: >>> Building MyObjects.Logistics.1.0.0:
16:49:16:     === Compiling build definition [MyBuilds.Logistics.1.0.0]:
16:49:16:         === Parsing ...
16:49:16:         === Validating ...
16:49:16:     === Building object [MyObjects.Currency.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [MyObjects.Logistics.ShippingGuide.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [MyObjects.Logistics.ShippingItem.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [MyObjects.Logistics.TransportGuide.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [Global.Comment.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [Global.Country.1.0.1]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [Global.Language.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [Global.LanguageDialect.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [Global.OneOf.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Building object [Global.Picture.1.0.0]
16:49:16:         === Compiling ...
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         === Building ...
16:49:16:             Build CSharp ...
16:49:16:             Build Protobuf ...
16:49:16:             Build Protobuf.CSharp ...
16:49:16:             Build CSharp.Reflection ...
16:49:16:     === Distributing ...
16:49:16:     === Adding Catalogs to .bc881f21-6cfe-4c76-95a0-7d69287c4765.Logistics.1.0.0
16:49:16:         === Compiling build definition[.bc881f21-6cfe-4c76-95a0-7d69287c4765.Logistics.1.0.0]:
16:49:16:             === Parsing ...
16:49:16:             === Validating ...
16:49:16:         No catalog defined for .bc881f21-6cfe-4c76-95a0-7d69287c4765.Currency.1.0.0
16:49:16:         No catalog defined for .bc881f21-6cfe-4c76-95a0-7d69287c4765.Logistics.ShippingGuide.1.0.0
16:49:16:         No catalog defined for .bc881f21-6cfe-4c76-95a0-7d69287c4765.Logistics.ShippingItem.1.0.0
16:49:16:         No catalog defined for .bc881f21-6cfe-4c76-95a0-7d69287c4765.Logistics.TransportGuide.1.0.0
16:49:16:         No catalog defined for Global.Comment.1.0.0
16:49:16:         Adding Country.1.0.1.catalog
16:49:16:         Adding Language.1.0.0.catalog
16:49:16:         Adding LanguageDialect.1.0.0.catalog
16:49:16:         No catalog defined for Global.OneOf.1.0.0
16:49:16:         No catalog defined for Global.Picture.1.0.0
16:49:16: 
16:49:16: >>> Running /property:Configuration=Release /t:restore;UpdateGeneratedFiles:
16:49:16: Microsoft (R) Build Engine version 16.11.0+0538acc04 for .NET Framework
16:49:16: Copyright (C) Microsoft Corporation. All rights reserved.
16:49:16: 
16:49:18: 
16:49:18: 
16:49:18: +++ Done.
16:49:18: 
16:49:18: >>> Running /property:Configuration=Release:
16:49:19: Microsoft (R) Build Engine version 16.11.0+0538acc04 for .NET Framework
16:49:19: Copyright (C) Microsoft Corporation. All rights reserved.
16:49:19: 
16:49:22: 
16:49:22: 
16:49:22: +++ Done.
16:49:22: ⎸

Create Catalog

For the object "Currency" now will add catalog.
For this case we will create "Local Catalog", with simplified list of currencies (in the next tutorial we will recreate this catalog in accordance with standard/ISO and with reference for Country).

Add Catalog

Open the object "Currency" and add the following lines:

Catalog

    Code  |   Description
    //--------------------------------------
    EUR   |   "Euro"
    USD   |   "United States dollar"
    GBP   |   "British pound"
    JPN   |   "Japanese yen"

End Catalog

Save and perform the Build and check build log for any errors.
Clean log build for this case should like:

13:33:55: >>> Building MyObjects.Logistics.1.0.0:
13:33:55:     === Compiling build definition [MyBuilds.Logistics.1.0.0]:
13:33:55:         === Parsing ...
13:33:55:         === Validating ...
13:33:55:     === Building object [MyObjects.Currency.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [MyObjects.Logistics.ShippingGuide.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [MyObjects.Logistics.ShippingItem.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [MyObjects.Logistics.TransportGuide.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [Global.Comment.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [Global.Country.1.0.1]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [Global.Language.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [Global.LanguageDialect.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [Global.OneOf.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Building object [Global.Picture.1.0.0]
13:33:55:         === Compiling ...
13:33:55:             === Parsing ...
13:33:55:             === Validating ...
13:33:55:         === Building ...
13:33:55:             Build CSharp ...
13:33:55:             Build Protobuf ...
13:33:55:             Build Protobuf.CSharp ...
13:33:55:             Build CSharp.Reflection ...
13:33:55:     === Distributing ...
13:33:55: 
13:33:55: >>> Running /property:Configuration=Release /t:restore;UpdateGeneratedFiles:
13:33:55: Microsoft (R) Build Engine version 16.11.0+0538acc04 for .NET Framework
13:33:55: Copyright (C) Microsoft Corporation. All rights reserved.
13:33:55: 
13:33:57: 
13:33:57: 
13:33:57: +++ Done.
13:33:57: 
13:33:57: >>> Running /property:Configuration=Release:
13:33:58: Microsoft (R) Build Engine version 16.11.0+0538acc04 for .NET Framework
13:33:58: Copyright (C) Microsoft Corporation. All rights reserved.
13:33:58: 
13:34:03: 
13:34:03: 
13:34:03: +++ Done.
13:34:03: 
13:34:03:     === Adding Model Catalogs to MyBuilds.Logistics.1.0.0
13:34:03:         Loading catalog: MyObjects.Currency
13:34:03:     === Adding Catalogs to MyBuilds.Logistics.1.0.0
13:34:03:         === Compiling build definition[MyBuilds.Logistics.1.0.0]:
13:34:03:             === Parsing ...
13:34:03:             === Validating ...
13:34:03:         No catalog defined for MyObjects.Currency.1.0.0
13:34:03:         No catalog defined for MyObjects.Logistics.ShippingGuide.1.0.0
13:34:03:         No catalog defined for MyObjects.Logistics.ShippingItem.1.0.0
13:34:03:         No catalog defined for MyObjects.Logistics.TransportGuide.1.0.0
13:34:03:         No catalog defined for Global.Comment.1.0.0
13:34:03:         Adding Country.1.0.1.catalog
13:34:03:         Adding Language.1.0.0.catalog
13:34:03:         Adding LanguageDialect.1.0.0.catalog
13:34:03:         No catalog defined for Global.OneOf.1.0.0
13:34:03:         No catalog defined for Global.Picture.1.0.0
13:34:03: 
13:34:03: >>> Running /property:Configuration=Release:
13:34:04: Microsoft (R) Build Engine version 16.11.0+0538acc04 for .NET Framework
13:34:04: Copyright (C) Microsoft Corporation. All rights reserved.
13:34:04: 
13:34:06: 
13:34:06: 
13:34:06: +++ Done.

Visual Studio & Nuget

At this point we have objects & catalog ready to be use.

At this stage, first we have download NuGet package that have our objects

Download Nuget packages

On build file ("Logistics") select "Download" (choosing directory where you want to download the files)

On the directory were you have download the files, you will find 2 NuGet Package

  • DocDigitizer.WorldObjects.MyObjects.Logistics.1.0.0
  • DocDigitizer.ServiceAPI.1.0.4.nupkg => this contains functionalities that handles with the of DocDigitizer WorldObjects core services
    note: DocDigitizer.ServiceAPI.1.0.4.nupkg is the version at the time that this tutorial was made

Setup Visual Studio project

Open your Visual Studio
Create "Console application" project with name "Tutorial - Logistics"
*note: for this tutorial demonstration, "Console application" project is enough, but you can use NuGet package provide DocDigitizer WorldObjects in other type of projects, considering requirements of each case.

Install the 2 Nuget packages on your Visual Studio project that you have created

Test catalogs

Open file "Program.cs", and the following code to the this class:

static void ShowCatalogCurrency()
{
  Currency[] currencies = Catalog<Currency>.GetAll();
  for(int i=0; i<currencies.Length; i++)
    Console.WriteLine($"Currency from Local catalog: {currencies[i].Code} | {currencies[i].Description}");
}

static void Main(string[] args)
{
  ShowCatalogCurrency();
}

This will write console list of all currencies that you have on the catalog.

Lets list all values that you have on Country catalog.

If you have to install again the NuGet's, execute bellow command before installing:
dotnet nuget locals all --clear

static void ShowCatalogCountry()
{
  Country[] countries = Catalog<Country>.GetAll();
  for (int i = 0; i < countries.Length; i++)
    Console.WriteLine($"Currency from Local catalog: {countries[i].ISO2} | {countries[i].Name}");
}

static void Main(string[] args)
{
  //ShowCatalogCurrency();
  ShowCatalogCountry();
}

Test objects

Lets instantiate the objects that you created with values and add the references needed.

private static TransportGuide transport;
  
static void CreateTransportGuide()
{
  ShippingItem item1 = new();
  item1.itemId = "item11";
  item1.itemName = "Item Name11";
  item1.amount = 100;
  item1.vatAmount = 21;

  ShippingItem item2 = new();
  item2.itemId = "item12";
  item2.itemName = "Item Name12";
  item2.amount = 200;
  item2.vatAmount = 42;

  ShippingGuide guide1 = new();
  guide1.clientName = "Client1";
  guide1.clientTaxId = "clientTax1";
  guide1.documentNumber = "guide1";
  guide1.emissionDate = DateTimeOffset.UtcNow;
  guide1.totalAmount = 300;
  guide1.vatAmount = 63;
  guide1.vendorName = "Vendor1";
  guide1.vendorTaxId = "vendorTax1";
  guide1.currency = Currency.CatalogReference(Currency.Constants.USD);
  guide1.items.Add(item1);
  guide1.items.Add(item2);

  transport = new();
  transport.documentNumber = "transpor1";
  transport.transporterName = "transporter1";
  transport.destinationAddress = "Street 1, building 1";
  transport.destinationCountry = Catalog<Country>.Get(Country.Constants.PT);
  transport.deliverDate = DateTimeOffset.UtcNow.AddDays(2);
  transport.shippingGuides.Add(guide1);

  Console.WriteLine(guide1.ToJson());
  guide1.Serialize.ToFile("Guide1.txt");
}

static void Main(string[] args)
{
  //ShowCatalogCurrency();
  //ShowCatalogCountry();
  CreateTransportGuide();
}

JSON of the objects printer looks like:

{
  "InstanceId": { "contentId": "34703025-ea18-424d-ba95-f1c8bd07aece" },
  "ClassName": { "value": "DocDigitizer.WorldObjects.MyObjects.Logistics.ShippingGuide" },
  "ClassVersion": { "value": "1.0.0" },
  "clientName": { "value": "Client1" },
  "clientTaxId": { "value": "clientTax1" },
  "currency": {
    "InstanceId": { "contentId": "a13536af-1ba2-49c3-bdb8-caabd14a0da1" },
    "LinkedToCatalog": { "value": "USD" }
  },
  "documentNumber": { "value": "guide1" },
  "emissionDate": {
    "value": {
      "utc": "2021-11-08T17:15:14.289514200Z",
      "offset": "0s"
    }
  },
  "items": [
    {
      "InstanceId": { "contentId": "68043178-955c-47f6-a27a-bc7c587e5217" },
      "ClassName": { "value": "DocDigitizer.WorldObjects.MyObjects.Logistics.ShippingItem" },
      "ClassVersion": { "value": "1.0.0" },
      "amount": {
        "value": { "units": "100" }
      },
      "itemId": { "value": "item11" },
      "itemName": { "value": "Item Name11" },
      "vatAmount": {
        "value": { "units": "21" }
      }
    }, {
      "InstanceId": { "contentId": "0c0101a8-1765-4128-b915-6e560ac7a1e4" },
      "ClassName": { "value": "DocDigitizer.WorldObjects.MyObjects.Logistics.ShippingItem" },
      "ClassVersion": { "value": "1.0.0" },
      "amount": {
        "value": { "units": "200" }
      },
      "itemId": { "value": "item12" },
      "itemName": { "value": "Item Name12" },
      "vatAmount": {
        "value": { "units": "42" }
      }
    }
  ],
  "totalAmount": {
    "value": { "units": "300" }
  },
  "vatAmount": {
    "value": { "units": "63" }
  },
  "vendorName": { "value": "Vendor1" },
  "vendorTaxId": { "value": "vendorTax1" }
}

The solution is available:
Source


Did this page help you?