AI translation

This page was translated from German with AI. If in doubt, the German original applies.

BMU documents with the SDK¶

BMU consignment notes and acceptance notes with the SDK: create, set fields, sign, append layers and send to ZEDAL.

The background in business terms is described in the guide Consignment note and acceptance note.

`BmuDocumentHandler`¶

Flow per role with an end-to-end example: Consignment note by role.

The handler for BMU consignment notes and acceptance notes works against the stateless BmuDocumentApi. It holds the XML (DocXml) and the typed view (Document), sends the XML along with every call and then updates both properties.

Method	Purpose
`CreateFromTemplate(templateXml)`	Create a document from a ZEDAL template
`Create(document, vorlageLayer, xmlOptions)`	Create a document from data
`UpdateDocument(document, xmlOptions)`	Write fields of the current layer, only fields with `InLayer = true`
`AddLayer(layerType, xmlOptions)`	Append the next layer, consignment note only
`GetValidSignaturePositions()`	Open signature positions of the current layer
`Load(docXml)`	Load existing XML, for example after signing
`LoadTransportDocumentFromZedal(docIdentifier, value)`	Load a document from ZEDAL
`SubmitTransportDocumentToZedal(cancel, dekade, distribute)`	Send to ZEDAL; returns the `DocumentId`

xmlOptions is optional; if not specified, Create and UpdateDocument validate fully, and AddLayer does not validate the new layer. Flow with code: BMU guide.

Setup¶

using System;
using System.Linq;
using Google.Protobuf;
using Infotech.Signer.Sign.V1;          // DocumentInput, DocumentKind
using Infotech.Zedal.Bxa.Bmu.V1.Api;    // XmlOptions
using Infotech.Zedal.Core.V1.Api;       // TemplateId, DocumentId
using Infotech.Zedal.Documents.V1;      // Document, StringField, DoubleField, FieldMeta
using Infotech.Zedal.Documents.V1.Bmu;  // BGSDokument, UNSDokument, Befoerderer, LayerType, Rolle
using Zedal.Sdk.Apis.Signer;            // DocumentResults

var bmu = client.DocumentHandler.CreateBmuHandler();

Creating¶

From a ZEDAL template¶

byte[] templateXml = await client.CoreApi.Templates.ExportTransportTemplate(
    new TemplateId { Id = templateId });   // template_id from the list

await bmu.CreateFromTemplate(templateXml);

From data¶

var entwurf = new XmlOptions { Validation = XmlOptions.Types.Validation.None };

await bmu.Create(new Document
{
    Bgs = new BGSDokument
    {
        Abfallbezeichnung = new StringField { Value = "Altöl", Meta = new FieldMeta { InLayer = true } }
    }
}, vorlageLayer: false, entwurf);

Setting fields¶

await bmu.UpdateDocument(new Document
{
    Bgs = new BGSDokument
    {
        Menge = new DoubleField { Value = 12.5, Meta = new FieldMeta { InLayer = true } }   // metric tons
    }
}, entwurf);

Signing¶

The open signature positions in the current layer are returned by:

var positionen = await bmu.GetValidSignaturePositions();

Signing takes place via the WebSigner (infotech.signer.sign.v1): create a process with the current XML and submit it, show the signing_url to a person who signs there, wait for completion, retrieve the result. The result contains the complete signed XML. SignAsync handles this in one call:

var result = await client.SignerApi.SigningProcesses.SignAsync(
    new[]
    {
        new DocumentInput
        {
            DisplayName = "Begleitschein",
            Kind        = DocumentKind.BmuXml,
            Content     = ByteString.CopyFrom(bmu.DocXml)
        }
    },
    presentSigningUrl: url => Console.WriteLine($"Open to sign: {url}"));

var signed = result.Results.SingleOrDefault();
if (result.Completed && DocumentResults.IsUsable(signed))
{
    await bmu.Load(signed.Content.ToByteArray());   // take over the signed XML
}

Next layer¶

await bmu.AddLayer(LayerType.Befoerderer);

await bmu.UpdateDocument(new Document
{
    Bgs = new BGSDokument
    {
        Befoerderer1 = new Befoerderer
        {
            Kfz = new StringField { Value = "RE TK 61", Meta = new FieldMeta { InLayer = true } }
        }
    }
});

Reading¶

await bmu.Load(storedXml);
double? quantity = bmu.Document.Bgs.Menge?.Value;

Sending to ZEDAL¶

DocumentId id = await bmu.SubmitTransportDocumentToZedal(cancel: false, dekade: false, distribute: false);

Acceptance note¶

var uns = client.DocumentHandler.CreateBmuHandler();

await uns.Create(new Document
{
    Uns = new UNSDokument
    {
        Abfallbezeichnung = new StringField { Value = "Altöl", Meta = new FieldMeta { InLayer = true } }
    }
}, vorlageLayer: false,
   new XmlOptions { Validation = XmlOptions.Types.Validation.None, AtbRolle = Rolle.Erz });