Tutorial - Use Case Logistics

DocDigitizer WorldObjects Tutorial

Use Case

Requirements

For this tutorial, we will be showcasing simple logistics scenarios where we have to manage 2 types of documents

  • Shipping Guide
  • Transport Guide

These 2 types of documents and their information will be transposed to the following object diagram:

34343434

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

Tutorial

Here is a video version of this tutorial:

Let's begin!

Creating Objects

Let's start by creating the first object (Shipping Item).
Open your Visual Code and login.

Create object "ShippingItem"

Add "New Folder" with the name "Logistics" in your workspace.
Add "New Object" with the name "ShippingItem" in the “Logistics” folder.
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"

Then save the file.

Create object "ShippingGuide"

Add "New Object" with the name "ShippingGuide" in the "Logistics" folder.
Then add the following 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 to the nth degree Shipping Items.
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, you will see the following error in the terminal because we don't have the build defined yet :
Member 'currency' using 'Logistics.ShippingItem': object is not included on build definition

Then save the file.

Create object "Currency"

As you can see in the diagram above, the "ShippingGuide" has a reference to an object called "Currency."
We also specify that the object "Currency" is reference data, which is to say that this object will have a Catalog associate.
Let's first create the object and reference, then later add the Catalog.

On the 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

Then save the 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 

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

Create object "TransportGuide"

Add "New Object" with the name "TransportGuide" in the "Logistics" folder.
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

Then save the file.

After creating these objects, your workspace should look like this:

624624

Create a Build

Let's now create the build.

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

// 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

Add 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 check the log of the build for any errors.
A 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 a Catalog

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

Add Catalog

Open the "Currency" object 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, then check the build log for any errors.
A 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 & catalogs ready to be used.

First we have to download a NuGet package with our objects.

Download Nuget Packages

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

On the directory where you have download the files, you will find 2 NuGet Packages

  • 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 written.

Setup Visual Studio Project

Open your Visual Studio.
Create a "Console application" project with the name "Tutorial - Logistics."
*Note: for this tutorial, the "Console application" project is sufficient, but you can use the NuGet package to provide DocDigitizer WorldObjects in other types of projects, considering the requirements for each case.

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

533533

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 a console list of all currencies that you have in the catalog.

Let’s list all the values that you have in the Country catalog.

If you have to install the NuGets again, execute the following command before installing:
dotnet nuget locals all --clear

513513
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

Let’s instantiate the objects that you created with values and add the necessary references.

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 should look like this:

{
  "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?