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:
-
Create the first line without specifying the TransactionKey property. Store the TransactionKey contained in the results set.
-
Create all subsequent lines using the TransactionKey from the first line.
-
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: |
Exact Globe+
|
Date: |
26-09-2022 |
Release: |
|
Attachment: |
|
Disclaimer |