One moment please...
 
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

  1. Open Microsoft Visual Studio 2008.

  2. Create a new project with the following information:

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

  1. 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

  1. 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.

     

  1. 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)

            Next

 

            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))

                  Next

            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)

                  Next

            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)

                  Next

            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

 

            Next

 

            SetMessage("Validation Passed")

      End Sub

  1. 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

            Next

      End If

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

End Sub

Try

Catch fe As FaultException

      ShowError(fe)

End Try

:

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: 19.061.061
 Assortment: Exact Synergy Enterprise  Date: 01-07-2009
 Release:  Attachment:
 Disclaimer

Attachments
FinancialTransactionDemo.zip 450.0 KB Download