Exact Synergy Enterprise

How to Consume Financial Transaction Web Services

How-to: Consuming the Binary and Document Attachment Web Services

Introduction

To consume Financial Transaction service, the software developers need to consume 4 entities; FinancialHeader, FinancialLine, FinancialBankStatement, FinancialPaymentTerms. All 4 entities make up the Financial Transaction service.

This document provides a step-by-step guide to do this using Microsoft Visual Studio 2008 as an example.

Button

Not applicable.

Description

Open Microsoft Visual Studio 2008.
Create a new project with the following information:

Project type: Expand Visual Basic, and then click Windows.
Templates: Windows Forms Application.
Name: TestApplication.

Add a service reference to the FinancialHeader service:

Right-click on the TestApplication project, and then click on Add Service Reference…
In the Address box, enter a valid service URL for Binary service.
For example: http://localhost/Synergy/Services/Exact.Entity. FinancialHeader.svc and then click Go.
In the Namespace box, type EntityFinancialHeader.
Repeat the process for:
- FinancialLine
  - Address: http://localhost/Synergy/Services/Exact.Entity. FinancialLine.svc
  - Namespace: EntityFinancialLine
- FinancialBankStatement
  - Address: http://localhost/Synergy/Services/Exact.Entity. FinancialBankStatement.svc
  - Namespace: EntityFinancialBankStatement
- FinancialPaymentTerm
  - Address: http://localhost/Synergy/Services/Exact.Entity. FinancialPaymentTerm.svc
Namespace: EntityFinancialPaymentTerm

Open the Form1 class in the Designer window.

In this example, extend Form1 by more buttons, labels, and text boxes,
2 radio buttons are added to indicate whether the operations are intended for Pending or Processed transactions.

Open the Form1 class in the Code Editor window and add the following code:

Declare variables that will hold the Entity Financial Transactions object

Private headerClient As New EntityFinancialHeader.FinancialHeaderClient

Private lineClient As New EntityFinancialLine.FinancialLineClient

Private bankClient As New EntityFinancialBankStatement.FinancialBankStatementClient

Private termClient As New EntityFinancialPaymentTerm.FinancialPaymentTermClient

Private headerData As EntityFinancialHeader.FinancialHeaderData

Private lineData As EntityFinancialLine.FinancialLineData

Private bankData As EntityFinancialBankStatement.FinancialBankStatementData

Private termData As EntityFinancialPaymentTerm.FinancialPaymentTermData

In this example, set client credential as Impersonation.

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

headerClient.ClientCredentials.Windows.AllowedImpersonationLevel = Security.Principal.TokenImpersonationLevel.Impersonation

lineClient.ClientCredentials.Windows.AllowedImpersonationLevel = Security.Principal.TokenImpersonationLevel.Impersonation

bankClient.ClientCredentials.Windows.AllowedImpersonationLevel = Security.Principal.TokenImpersonationLevel.Impersonation

termClient.ClientCredentials.Windows.AllowedImpersonationLevel = Security.Principal.TokenImpersonationLevel.Impersonation

End Sub

Alternate way of setting the credential is to pass a valid username, password and domain to network credential.

headerClient.ChannelFactory.Credentials.Windows.ClientCredential = New System.Net.NetworkCredential("username", "password", "exact-software")

lineClient.ChannelFactory.Credentials.Windows.ClientCredential = New System.Net.NetworkCredential("username", "password", "exact-software")

bankClient.ChannelFactory.Credentials.Windows.ClientCredential = New System.Net.NetworkCredential("username", "password", "exact-software")

lineClient.ChannelFactory.Credentials.Windows.ClientCredential = New System.Net.NetworkCredential("username", "password", "exact-software")

There are 3 important elements for each of the properties: Value, IsDirty, and IsNothing.
- Value is the value of the property.
- IsDirty is the flag that a property has been changed. All changed properties (including IsNothing=True) must set IsDirty to true.
- IsNothing is the flag to set a property to perceive data as NULL.
Financial Transaction Entities do not work like standard Entities; each entity that makes up the Financial Entity (FinancialLine, FinancialBankStatement, FinancialPaymentTerm must perform the operations first, before the FinancialHeader.
In other words, the FinancialHeader is the terminator; i.e. it tells the ECL that Financial Transaction Entities is complete, and the operations performed upon all preceeding entities make up one complete Financial Transaction Entity.
The TransactionKey property in each entity is used to tie all the entities together. A default TransactionKey will be generated by the server whenever an entity without TransactionKey performs and operation. The key must then be assigned to each other entity manually.
Create a Private Sub Function CreateEntity().

Private Sub CreateEntity(Optional ByVal UseSave As Boolean = False)

Dim transKey As Guid

Dim entryNo As String = ""

Dim isProcessed As Boolean = rdProcessed.Checked

'lineData 1

lineData = New EntityFinancialLine.FinancialLineData()

With lineData

.IsProcessed = New EntityFinancialLine.EntityBoolean With {.Value = isProcessed, .IsDirty = True}

.CompanyCode = New EntityFinancialLine.EntityString With {.Value = "001", .IsDirty = True}

.TransactionType = New EntityFinancialLine.EntityInteger With {.Value = 6, .IsDirty = True}

.ProcessLine = New EntityFinancialLine.EntityString With {.Value = " 1", .IsDirty = True}

.TransType = New EntityFinancialLine.EntityString With {.Value = "N", .IsDirty = True}

.TransactionSubType = New EntityFinancialLine.EntityString With {.Value = "Y", .IsDirty = True}

.ProcessLineCode = New EntityFinancialLine.EntityString With {.Value = "A", .IsDirty = True}

.TransactionDate = New EntityFinancialLine.EntityDateTime With {.Value = dtTransDate.Value, .IsDirty = True}

.Creditor = New EntityFinancialLine.EntityString With {.Value = "10004", .IsDirty = True}

.CompanyAccountCode = New EntityFinancialLine.EntityString With {.Value = "1100", .IsDirty = True}

.CurrencyCode = New EntityFinancialLine.EntityString With {.Value = "EUR", .IsDirty = True}

.ForeignCurrencyDebitAmount = New EntityFinancialLine.EntityInteger With {.Value = 0, .IsDirty = True}

.ForeignCurrencyCreditAmount = New EntityFinancialLine.EntityInteger With {.Value = 3800, .IsDirty = True}

.Rate = New EntityFinancialLine.EntityInteger With {.Value = 1, .IsDirty = True}

.OriginOfTransaction = New EntityFinancialLine.EntityString With {.Value = "A", .IsDirty = True}

.OriginOfEntry = New EntityFinancialLine.EntityString With {.Value = "N", .IsDirty = True}

.PaymentMethod = New EntityFinancialLine.EntityString With {.Value = "B", .IsDirty = True}

.ProcessNumber = New EntityFinancialLine.EntityInteger With {.Value = 1, .IsDirty = True}

.JournalPostingNumber = New EntityFinancialLine.EntityInteger With {.Value = 1, .IsDirty = True}

End With

Try

If UseSave Then

lineData = lineClient.Save(lineData)

Else

lineData = lineClient.Create(lineData)

End If

Catch ex As Exception

MessageBox.Show("Financial lineData Entity - Create failed: " & ex.Message)

End Try

transKey = lineData.TransactionKey.Value

'lineData 2

lineData = New EntityFinancialLine.FinancialLineData()

With lineData

.TransactionKey = New EntityFinancialLine.EntityGuid With {.Value = transKey, .IsDirty = True}

.IsProcessed = New EntityFinancialLine.EntityBoolean With {.Value = isProcessed, .IsDirty = True}

.CompanyCode = New EntityFinancialLine.EntityString With {.Value = "001", .IsDirty = True}

.TransactionType = New EntityFinancialLine.EntityInteger With {.Value = 6, .IsDirty = True}

.ProcessLine = New EntityFinancialLine.EntityString With {.Value = " 1", .IsDirty = True}

.TransType = New EntityFinancialLine.EntityString With {.Value = "N", .IsDirty = True}

.TransactionSubType = New EntityFinancialLine.EntityString With {.Value = "T", .IsDirty = True}

.ProcessLineCode = New EntityFinancialLine.EntityString With {.Value = "B", .IsDirty = True}

.TransactionDate = New EntityFinancialLine.EntityDateTime With {.Value = dtTransDate.Value, .IsDirty = True}

.Creditor = New EntityFinancialLine.EntityString With {.Value = "10004", .IsDirty = True}

.CompanyAccountCode = New EntityFinancialLine.EntityString With {.Value = "7000", .IsDirty = True}

.CurrencyCode = New EntityFinancialLine.EntityString With {.Value = "EUR", .IsDirty = True}

.ForeignCurrencyDebitAmount = New EntityFinancialLine.EntityInteger With {.Value = 3800, .IsDirty = True}

.ForeignCurrencyCreditAmount = New EntityFinancialLine.EntityInteger With {.Value = 0, .IsDirty = True}

.Rate = New EntityFinancialLine.EntityInteger With {.Value = 1, .IsDirty = True}

.OriginOfTransaction = New EntityFinancialLine.EntityString With {.Value = "A", .IsDirty = True}

.OriginOfEntry = New EntityFinancialLine.EntityString With {.Value = "N", .IsDirty = True}

.PaymentMethod = New EntityFinancialLine.EntityString With {.Value = "B", .IsDirty = True}

.ProcessNumber = New EntityFinancialLine.EntityInteger With {.Value = 1, .IsDirty = True}

.JournalPostingNumber = New EntityFinancialLine.EntityInteger With {.Value = 1, .IsDirty = True}

End With

Try

If UseSave Then

lineData = lineClient.Save(lineData)

Else

lineData = lineClient.Create(lineData)

End If

Catch ex As Exception

MessageBox.Show("Financial lineData Entity - Create failed: " & ex.Message)

End Try

'Create header

headerData = New EntityFinancialHeader.FinancialHeaderData

With headerData

.TransactionKey = New EntityFinancialHeader.EntityGuid With {.Value = transKey, .IsDirty = True}

.IsProcessed = New EntityFinancialHeader.EntityBoolean With {.Value = isProcessed, .IsDirty = True}

End With

Try

If UseSave Then

headerData = headerClient.Save(headerData)

Else

headerData = headerClient.Create(headerData)

End If

Catch ex As Exception

MessageBox.Show("Financial lineData Entity - Create failed: " & ex.Message)

End Try

End Sub

Add code in <Create> button using the above created standard function.:

Private Sub btnCreatePend_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnCreatePend.Click

If CreateEntity() Then

SetMessage("Financial Transaction Created")

Else

SetMessage("Financial Transaction Create: Failed", False)

End If

End Sub

Add code in <Save> button using the above created standard function.

If CreateEntity(True) Then

SetMessage("Financial Transaction Save: Success")

Else

SetMessage("Financial Transaction Save: Failed", False)

End If

Add code in <Update> button. We call the <Retrieve> operation first, before updating our data. Note that any entity that does not call the <Update> function is deleted
Since <Update> operation does not return anything, we have to manually generate a TransactionKey for the Entities.

Private Sub btnUpdatePend_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnUpdatePend.Click

Dim transKey As Guid = Guid.NewGuid

btnRetrievePend_Click(sender, e)

For Each line As EntityFinancialLine.FinancialLineData In lineDataArray

line.Description = New EntityFinancialLine.EntityString With {.Value = "update", .IsDirty = True}

line.TransactionKey = New EntityFinancialLine.EntityGuid With {.Value = transKey, .IsDirty = True}

line.EntryNumber = New EntityFinancialLine.EntityString With {.Value = txtEntryNumber.Text, .IsDirty = True}

line.FinancialYear = New EntityFinancialLine.EntityInteger With {.Value = CInt(txtFinYear.Text), .IsDirty = True}

line.FinancialPeriod = New EntityFinancialLine.EntityString With {.Value = txtFinPeriod.Text, .IsDirty = True}

lineClient.Update(line)

With headerData

.TransactionKey = New EntityFinancialHeader.EntityGuid With {.Value = transKey, .IsDirty = True}

.EntryNumber = New EntityFinancialHeader.EntityString With {.Value = txtEntryNumber.Text, .IsDirty = True}

.FinancialYear = New EntityFinancialHeader.EntityInteger With {.Value = CInt(txtFinYear.Text), .IsDirty = True}

.FinancialPeriod = New EntityFinancialHeader.EntityString With {.Value = txtFinPeriod.Text, .IsDirty = True}

End With

Try

headerClient.Update(headerData)

Catch ex As Exception

MessageBox.Show("Update Failed: " & ex.Message)

Return

End Try

SetMessage("Update Successfull", False)

End Sub

Add code in <Retrieve> button. <Retrieve> operation always begins with the FinancialHeader entity, and with the properties EntryNumber, FinancialYear, FinancialPeriod and IsProcessed defined. The retrieved FinancialHeader’s LineIDs property will contain IDs for each FinancialLine entity. The same goes with BankIDs (for FinancialBankStatement) and PaymentIDs (for FinancialPaymentTerm). The IDs are comma-separated.

Private Sub btnRetrievePend_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnRetrievePend.Click

Dim statusText As StringBuilder

If (Len(txtEntryNumber.Text) = 0) OrElse (Len(txtFinPeriod.Text) = 0) OrElse (Len(txtFinYear.Text) = 0) Then

SetMessage("EntryNumber, FinancialYear and FinancialPeriod are Mandatory", False)

Return

End If

headerData = New EntityFinancialHeader.FinancialHeaderData

With headerData

.IsProcessed = New EntityFinancialHeader.EntityBoolean With {.Value = rdProcessed.Checked, .IsDirty = True}

.EntryNumber = New EntityFinancialHeader.EntityString With {.Value = txtEntryNumber.Text, .IsDirty = True}

.FinancialYear = New EntityFinancialHeader.EntityInteger With {.Value = CInt(txtFinYear.Text), .IsDirty = True}

.FinancialPeriod = New EntityFinancialHeader.EntityString With {.Value = txtFinPeriod.Text, .IsDirty = True}

End With

Try

headerData = headerClient.Retrieve(headerData)

Catch ex As Exception

MessageBox.Show("Financial header Data Entity - Retrieve failed: " & ex.Message)

SetMessage("Unable to find data", False)

End Try

statusText = New StringBuilder

statusText.AppendLine("FinancialTransaction Entity Retrieved:-")

If (Not headerData.LineIDs.IsNothing) AndAlso (Len(headerData.LineIDs.Value) > 0) Then

Dim IDs() As String = headerData.LineIDs.Value.Split(",")

lineDataArray = New List(Of EntityFinancialLine.FinancialLineData)

For i As Integer = 0 To UBound(IDs)

lineDataArray.Add(New EntityFinancialLine.FinancialLineData)

lineDataArray(i).ID = New EntityFinancialLine.EntityInteger With {.Value = CInt(IDs(i)), .IsDirty = True}

lineDataArray(i).IsProcessed = New EntityFinancialLine.EntityBoolean With {.Value = rdProcessed.Checked, .IsDirty = True}

Try

lineDataArray(i) = lineClient.Retrieve(lineDataArray(i))

Catch ex As Exception

MessageBox.Show("Financial Line Entity - Retrieve failed: " & ex.Message)

Return

End Try

statusText.AppendLine("Financial Line, ID: " & IDs(i))

End If

If (Not headerData.BankIDs.IsNothing) AndAlso (Len(headerData.BankIDs.Value) > 0) Then

Dim IDs() As String = headerData.BankIDs.Value.Split(",")

For i As Integer = 0 To UBound(IDs)

bankData = New EntityFinancialBankStatement.FinancialBankStatementData

bankData.ID = New EntityFinancialBankStatement.EntityInteger With {.Value = CInt(IDs(i)), .IsDirty = True}

Try

bankData = bankClient.Retrieve(bankData)

Catch ex As Exception

MessageBox.Show("Financial Line Entity - Retrieve failed: " & ex.Message)

Return

End Try

statusText.AppendLine("Bank Statement, ID: " & bankData.ID.Value.ToString)

End If

If (Not headerData.PaymentIDs.IsNothing) AndAlso (Len(headerData.PaymentIDs.Value) > 0) Then

Dim IDs() As String = headerData.PaymentIDs.Value.Split(",")

For i As Integer = 0 To UBound(IDs)

termData = New EntityFinancialPaymentTerm.FinancialPaymentTermData

termData.ID = New EntityFinancialPaymentTerm.EntityInteger With {.Value = CInt(IDs(i)), .IsDirty = True}

Try

termData = termClient.Retrieve(termData)

Catch ex As Exception

MessageBox.Show("Financial Line Entity - Retrieve failed: " & ex.Message)

Return

End Try

statusText.AppendLine("Financial Line, EntryGuid: " & termData.ID.Value.ToString)

End If

SetMessage(statusText.ToString)

End Sub

Add code in <Delete> button. Like the <Retrieve> Operation, we will need the EntryNumber, FinancialYear, and FinancialPeriod defined. Unlike the former, this operation need only be called by the FinancialHeader entity for it to delete the entire Financial Transaction Entity:

Private Sub btnDeletePend_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnDeletePend.Click

If (Len(txtEntryNumber.Text) = 0) OrElse (Len(txtFinPeriod.Text) = 0) OrElse (Len(txtFinYear.Text) = 0) Then

SetMessage("EntryNumber, FinancialYear and FinancialPeriod are Mandatory", False)

Return

End If

headerData = New EntityFinancialHeader.FinancialHeaderData

With headerData

.IsProcessed = New EntityFinancialHeader.EntityBoolean With {.Value = rdProcessed.Checked, .IsDirty = True}

.EntryNumber = New EntityFinancialHeader.EntityString With {.Value = txtEntryNumber.Text, .IsDirty = True}

.FinancialYear = New EntityFinancialHeader.EntityInteger With {.Value = CInt(txtFinYear.Text), .IsDirty = True}

.FinancialPeriod = New EntityFinancialHeader.EntityString With {.Value = txtFinPeriod.Text, .IsDirty = True}

End With

Try

headerClient.Delete(headerData)

Catch ex As Exception

MessageBox.Show("Delete Failed: " & ex.Message)

Return

End Try

SetMessage("Entity Deleted", False)

End Sub

Add code in <OpenNew> button. Each entity can perform this operation independent of each other .

Private Sub btnOpenNewPend_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnOpenNewPend.Click

Dim statusText As New StringBuilder

headerData = New EntityFinancialHeader.FinancialHeaderData

lineData = New EntityFinancialLine.FinancialLineData

bankData = New EntityFinancialBankStatement.FinancialBankStatementData

termData = New EntityFinancialPaymentTerm.FinancialPaymentTermData

Try

headerData = headerClient.OpenNew(headerData)

Catch ex As Exception

MessageBox.Show("OpenNew Failed: " & ex.Message)

Return

End Try

statusText.AppendLine("Default values retrieved for FinancialHeader Entity.")

Try

lineData = lineClient.OpenNew(lineData)

Catch ex As Exception

MessageBox.Show("OpenNew Failed: " & ex.Message)

Return

End Try

statusText.AppendLine("Default values retrieved for FinancialLine Entity.")

Try

bankData = bankClient.OpenNew(bankData)

Catch ex As Exception

MessageBox.Show("OpenNew Failed: " & ex.Message)

Return

End Try

statusText.AppendLine("Default values retrieved for FinancialBankStatement Entity.")

Try

termData = termClient.OpenNew(termData)

Catch ex As Exception

MessageBox.Show("OpenNew Failed: " & ex.Message)

Return

End Try

statusText.AppendLine("Default values retrieved for FinancialPaymentTerm Entity.")

SetMessage(statusText.ToString)

End Sub

Add code in <Validate> button. Click button to create an item by including:

Private Sub btnValidatePend_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnValidatePend.Click

btnRetrievePend_Click(sender, e)

For Each line As EntityFinancialLine.FinancialLineData In lineDataArray

Try

line = lineClient.Validate(line)

Catch ex As Exception

MessageBox.Show("Validation Failed: " & ex.Message)

End Try

SetMessage("Validation Passed")

End Sub

You can also add a Try-Catch statement to catch the fault exception during the CRUDOVS operations.

Exception:

Try

Catch ex As Exception

MessageBox.Show("Error Occurred :" & ex.Message, "Entity Error", MessageBoxButtons.OK, MessageBoxIcon.Error)

End Try

Fault Exception:

In order to use fault exception, you need to import <System.ServiceModel> by adding the following line at the beginning of your code:
Imports System.ServiceModel

Create a standard fault exception handling function using the code as below:

Private Sub ShowError(ByVal exc As Object)

Dim fe As Object

Select Case True

Case InStr(exc.GetType.ToString, "EntityBinary")

fe = DirectCast(exc, FaultException(Of EntityBinary.EntityFault))

Case InStr(exc.GetType.ToString, "EntityDocumentAttachment")

fe = DirectCast(exc, FaultException(Of EntityDocumentAttachment.EntityFault))

End Select

Dim sb As New System.Text.StringBuilder

sb.AppendLine("An error has occured!")

sb.AppendLine("")

sb.AppendFormat("{0}: [{1}]" & vbCrLf, "Exception Type", fe.Code.Name)

sb.AppendFormat("{0}: [{1}]" & vbCrLf, "Exception Message", fe.Message)

sb.AppendLine("")

If Not IsNothing(fe.Detail.Exceptions) AndAlso UBound(fe.Detail.Exceptions) > -1 Then

For Each info In fe.Detail.Exceptions

With sb

.AppendFormat("{0}: [{1}]" & vbCrLf, "Property", info.PropertyName)

.AppendFormat("{0}: [{1}]" & vbCrLf, "Message", info.Message)

.AppendLine("")

End With

End If

MessageBox.Show(sb.ToString(), "Error", MessageBoxButtons.OK, MessageBoxIcon.Error)

End Sub

Try

Catch fe As FaultException

ShowError(fe)

End Try

How to Consume Financial Transaction Web Services

Introduction

Button

Description

Related document