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:
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:
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.
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
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
Updated almost 2 years ago