One moment please...
 
 
Exact Globe+   
 

How-to: Creating header and line data through entity services

Introduction

Header and line data, such as sales order, invoice, and financial entries consist of multiple records. These records are, for example, one header record and one line record or more containing the details for a particular entry. To tie all these records together, the entity service uses a meta identifier, or the transaction key, which uniquely identifies all records belonging to a single header and line entry.

This key is returned in the data set during the creation of the first line record and should be supplied for all other records. The entry is validated and created after the header record is created. The process for creating an entry is as follows:

  1. Create the first line without specifying the TransactionKey property. Store the TransactionKey contained in the results set.
  2. Create all subsequent lines using the TransactionKey from the first line.
  3. Create the header using the TransactionKey from the lines. This will validate and create the entry.

Note: Currently, only the Create and Delete actions are supported. Reading of header and line entries can be done through the Retrieve set service.

 

Description

This document describes how to create header and line data through entity services in the following topics:

Return to top

 

Preparation

The process uses Exact.Services.Client.dll, which takes care of the binding and serialization towards the actual entity service. To do this, include a reference to the following:

  • Exact.Services.Client.dll,
  • the standard System.ServiceModel, and
  • the System.Runtime.Serialization libraries.

It is advisable to turn off Copy local for the Exact assembly because the solution will most likely be built to either run from an existing Exact Globe Next installation, or be self-contained. With the self-contained solutions, it is best to include a copy of the Exact assembly for which you have built the solution against, in your deployment set.

The only global declare needed is the EntityClientEG instance, which you should reuse for all Create actions on the same database. The actual lifespan of the data object depends on what has been done before and after the creation, and as such, can be done either globally or locally, as shown in the following example:

Private entityClient As Exact.Services.Client.Entity.EntityClientEG

Private entityData As Exact.Services.Client.Data.EntityData

When instancing the entityClient, make sure to only point to the services folder on the server. The actual endpoint will be filled in by the class itself. Instancing the client class is unlikely to throw an exception. Any issues with the service endpoint or the database will not be reported until a method within the class is used. This is because the service is only accessed when an actual action has to be performed, for example:

entityClient = New Exact.Services.Client.Entity.EntityClientEG("http://localhost:8010/services", ".\sql2008r2", "102")

Return to top

 

Creating the first line data

The following example shows the creation of the first line data. After creating the first line, make sure that you retrieve the TransactionKey. This will be a GUID, although it is occasionally returned as a GUID formatted string.

Dim transactionKey As Guid

entityData = New Exact.Services.Client.Data.EntityData()

EntityData.EntityName = "FinancialLine"

With entityData.Properties

 propertyData = New Exact.Services.Client.Data.PropertyData("GLAccount", "2300")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("Amount", 100.0)

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("VATCode", "2")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("ItemCode", "BEK0001")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("Quantity", "5")

 .Add(propertyData)

End With

Try

 entityData = entityClient.Create(entityData)

Catch ex As Exact.Services.Client.Exceptions.EntityFunctionalException

 Dim fe As System.ServiceModel.FaultException(Of Exact.Services.Client.Data.EntityFault)

 fe = CType(ex.InnerException, System.ServiceModel.FaultException(Of Exact.Services.Client.Data.EntityFault))

 MessageBox.Show("Validation error: " & ParseValidationError(fe.Detail))

 Return False

Catch ex As Exception

 MessageBox.Show("Exception occurred trying to create first line: " & ex.Message)

 Return False

End Try

transactionKey = New Guid(entityData.Properties("TransactionKey").Value.ToString())

Return to top

 

Creating the subsequent lines data

All subsequent lines should be created using the same transaction key (TransactionKey), as shown in the following example:

entityData = New Exact.Services.Client.Data.EntityData()

entityData.EntityName = "FinancialLine"

With entityData.Properties

 propertyData = New Exact.Services.Client.Data.PropertyData("GLAccount", "2300")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("Amount", 50.0)

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("VATCode", "2")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("ItemCode", "BEK0002")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("Quantity", "3")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("TransactionKey", transactionKey)

 .Add(propertyData)

End With

Try

 entityData = entityClient.Create(entityData)

Catch
ex As Exact.Services.Client.Exceptions.EntityFunctionalException

 Dim fe As System.ServiceModel.FaultException(Of Exact.Services.Client.Data.EntityFault)

 fe = CType(ex.InnerException, System.ServiceModel.FaultException(Of Exact.Services.Client.Data.EntityFault))

 MessageBox.Show("Validation error: " & ParseValidationError(fe.Detail))

 Return False

Catch
ex As Exception

 MessageBox.Show("Exception occurred trying to create second line: " & ex.Message)

 Return False

End Try

Return to top

 

Creating the header data

Upon creating the header data, as shown in the following example, the entry will be validated and created. This step is therefore most likely to throw an Exception.

entityData = New Exact.Services.Client.Data.EntityData

entityData.EntityName = "FinancialHeader"

With
entityData.Properties

propertyData = New Exact.Services.Client.Data.PropertyData("Journal", "70")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("DebtorNumber", 60089)

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("EntryDate", DateTime.Now.Date)

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("YourReference", "ESTA0001")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("Description", "Test entity services A0001")

 .Add(propertyData)

 propertyData = New Exact.Services.Client.Data.PropertyData("TransactionKey", transactionKey)

 .Add(propertyData)

End With

Try

 entityData = entityClient.Create(entityData)

Catch
ex As Exact.Services.Client.Exceptions.EntityFunctionalException

 Dim fe As System.ServiceModel.FaultException(Of Exact.Services.Client.Data.EntityFault)

 fe = CType(ex.InnerException, System.ServiceModel.FaultException(Of Exact.Services.Client.Data.EntityFault))

 MessageBox.Show("Validation error: " & ParseValidationError(fe.Detail))

 Return False

Catch
ex As Exception

 MessageBox.Show("Exception occurred trying to create header: " & ex.Message)

 Return False

End Try

Return True


Return to top

 

Validating errors


Validation errors will be passed back as an instance of Exact.Services.Client.Exceptions.EntityFunctionalException. Within this Exception will be a Fault object containing a collection of each property or error combination, as shown in the following example:

Private Function ParseValidationError(ByVal entityFault As Exact.Services.Client.Data.EntityFault) As String

 Dim sb As New System.Text.StringBuilder()

 If entityFault.Exceptions.Count = 0 Then

 Return entityFault.Message

 End If

 For Each
propFault As Exact.Services.Client.Data.WSExceptionInfo In entityFault.Exceptions

 sb.AppendFormat("Property:{0} Message:{1}", propFault.PropertyName, propFault.Message)

 sb.AppendLine()

 Next

 Return
sb.ToString()

End Function

 

Return to top

 

Related document

 

     
 Main Category: Support Product Know How  Document Type: Online help main
 Category: On-line help files  Security  level: All - 0
 Sub category: General  Document ID: 24.063.896
 Assortment:  Date: 26-09-2022
 Release:  Attachment:
 Disclaimer

Attachments
EGN_PU406_Howto_Creating header and line data through entity services_ver1.docx 38.7 KB View Download