Article Details
Id:22547
Product:finPOWER Connect
Type:NEW
Version:6.00.04
Opened:28/04/2026
Closed:11/06/2026
Released:16/07/2026
Job: J036835

Custom Service; new built-in service for script-driven HTTP integrations

A new "Custom Service" has been added to allow scripts to issue custom HTTP requests and have them integrated into the standard Service Log infrastructure.

Previously, scripts that needed to call a third-party HTTP endpoint had to use ISHttpClient, for example, directly and either bypass the Service Log entirely or save the details elsewhere. The Custom Service provides a single route that produces Service Logs identical to the current integrated interfaces and integrates with the existing Service Log form, Data Retention, and Summary Page implementations.

Service identifiers:

  • ServiceType: CreditBureau
  • ProductClass: CustomService
  • ServiceId: CustomService
  • ProductId: CustomRequest

The Custom Service is registered globally — there is no cost-centre configuration to complete. It is always available regardless of country or licensed add-ons.

Two adoption paths are supported, with overloads to create linked logs to Clients, Accounts etc.

  • The "full pattern" - call CreateRequest then the Execute or ExecuteWithLog method. The service performs the HTTP call and writes the Service Log (Pending to Completed/Failed) automatically.
  • The "migration pattern" - for scripts that already have working HTTP plumbing and only need the audit trail. Call the CreateServiceLog or CreateServiceLogWithLog method to insert a pending Service Log, perform your own HTTP call, then call UpdateServiceLog to update it to Completed or Failed.

Both paths produce identical Service Logs.

As the Service Log is in the database, developers can access the data directly.

Input validation and error handling

ExecuteWithLog and CreateServiceLogWithLog validate the supplied entity reference before any HTTP call is made or Service Log is created. If the Client, Account or Account Application Id does not exist - or the Applicant Pk does not belong to the supplied Account Application - the method returns False with a clear error and performs no work, so no HTTP call is made and no Service Log is created.

UpdateServiceLog returns False if the target Service Log row could not be updated, for example because the supplied Service Log Pk does not exist or the row is no longer Pending.

Data Retention

A single Data Retention rule is registered for ServiceId "CustomService", ProductId "CustomRequest", under the "CustomService" display category. PurgeAction defaults to None so retention is governed entirely by the configured rule, not by a hard-coded purge.

Code Snippets

The below code snippets illustrate how to use this new functionality. There are 6 examples:

  • Execute with generic source linkage (sourceType / sourcePk)
  • CreateServiceLog with generic source linkage (migration path)
  • ExecuteWithLog : auto-creates a Client Log
  • ExecuteWithLog : auto-creates an Account Log
  • ExecuteWithLog : auto-creates an Account Application Log
  • CreateServiceLogWithLog : migration path and auto Account Log
' (c) Copyright Intersoft Systems Limited, 2026. All rights reserved.
' #################################################################
' Custom Service Code Snippets
'
' Reference examples showing how to use the Custom Service business
' layer (finBL.CustomService) from a script. Each function is a
' standalone, copy-pasteable example demonstrating one pattern.
'
' Patterns covered:
'   1. Execute with generic source linkage (sourceType / sourcePk)
'   2. CreateServiceLog with generic source linkage (migration path)
'   3. ExecuteWithLog — auto-creates a Client Log
'   4. ExecuteWithLog — auto-creates an Account Log
'   5. ExecuteWithLog — auto-creates an Account Application Log
'   6. CreateServiceLogWithLog — migration path + auto Account Log
'
' Current Version: 1.00 (30/04/2026)
'
' Usage: Reference only — copy the relevant function into a real
' script and adapt the entity Ids, URL, payload, and error handling.
' #################################################################

' ------------------------------------------------------------------
' Snippet 1: Execute with generic source linkage
'
' Use the simple sourceType / sourcePk parameters on Execute() when
' you want the Service Log to point at a parent record but you do
' NOT want a Client / Account / Account Application Log row created
' for it. Good for ad-hoc service calls where the script handles
' any extra logging itself.
' ------------------------------------------------------------------
Public Function Snippet1_ExecuteWithSourceLink() As Boolean

  Dim Account As finAccount
  Dim Request As ISCustomRequest_CustomRequest
  Dim Response As ISCustomResponse_CustomRequest
  Dim ServiceLogPk As Integer
  Dim Success As Boolean

  ' Assume Success
  Success = True

  ' Load Account
  If Success Then
    Account = finBL.CreateAccount()
    Success = Account.Load("ACCT00001")
  End If

  ' Build Request
  If Success Then
    Request = finBL.CustomService.CreateRequest()
    With Request
      .RequestUrl = "https://api.example.com/balance/" & Account.AccountId
      .Method = iseWebServiceMethod.Get
      .EnquiryReference = "Balance check for " & Account.AccountId
    End With
  End If

  ' Execute — link the Service Log to the Account
  If Success Then
    Success = finBL.CustomService.Execute(Request, Response, "Account", Account.Pk, ServiceLogPk)
  End If

  ' Use Response
  If Success Then
    finBL.DebugPrint("Service Log Pk: " & CStr(ServiceLogPk))
    finBL.DebugPrint("Response: " & Response.ResponseString)
  End If

  ' Return Success
  Return Success

End Function

' ------------------------------------------------------------------
' Snippet 2: CreateServiceLog with generic source linkage
'
' The migration pattern — for scripts that already have working HTTP
' plumbing and only need Service Log auditing. Use sourceType /
' sourcePk to point the Pending Service Log at a parent record
' before the script makes its own HTTP call.
' ------------------------------------------------------------------
Public Function Snippet2_CreateServiceLogWithSourceLink() As Boolean

  Dim Client As finClient
  Dim Headers As ISKeyValueList
  Dim ResponseBody As String
  Dim ServiceLogPk As Integer
  Dim Success As Boolean

  ' Assume Success
  Success = True

  ' Load Client
  If Success Then
    Client = finBL.CreateClient()
    Success = Client.Load("CLIENT001")
  End If

  ' Build request headers
  If Success Then
    Headers = finBL.CreateKeyValueList()
    Headers.SetString("Authorization", "Bearer " & Client.ClientId)
    Headers.SetString("Accept", "application/json")
  End If

  ' Step 1: log Pending and link the Service Log to the Client
  If Success Then
    Success = finBL.CustomService.CreateServiceLog("Lookup " & Client.ClientId,
                                                    "https://api.example.com/clients/" & Client.ClientId,
                                                    iseWebServiceMethod.Get,
                                                    "",
                                                    Headers,
                                                    Nothing,
                                                    ServiceLogPk,
                                                    "Client",
                                                    Client.Pk)
  End If

  ' Step 2: script's own HTTP call goes here (omitted) — populate ResponseBody on success
  If Success Then
    ResponseBody = "{""client"":""" & Client.ClientId & """,""status"":""ok""}"
  End If

  ' Step 3: log Completed
  If Success Then
    Success = finBL.CustomService.UpdateServiceLog(ServiceLogPk, True, ResponseBody, Nothing, "")
  End If

  ' Return Success
  Return Success

End Function

' ------------------------------------------------------------------
' Snippet 3: ExecuteWithLog — auto-creates a Client Log
'
' Pass the Client Id only. The wrapper makes the HTTP call, creates
' the Service Log, then creates a finClientLog row that links back
' to the Service Log. The Service Log shows up in the Client's
' activity stream automatically.
' ------------------------------------------------------------------
Public Function Snippet3_ExecuteWithLog_Client() As Boolean

  Dim AccountAppLogPk As Integer
  Dim AccountLogPk As Integer
  Dim ClientLogPk As Integer
  Dim Request As ISCustomRequest_CustomRequest
  Dim Response As ISCustomResponse_CustomRequest
  Dim ServiceLogPk As Integer
  Dim Success As Boolean

  ' Assume Success
  Success = True

  ' Build Request
  Request = finBL.CustomService.CreateRequest()
  With Request
    .RequestUrl = "https://api.example.com/credit-score"
    .Method = iseWebServiceMethod.Get
    .EnquiryReference = "Credit score for CLIENT001"
  End With

  ' Execute and auto-create the Client Log
  Success = finBL.CustomService.ExecuteWithLog(Request, Response,
                                                subject:="Credit score lookup",
                                                clientId:="CLIENT001",
                                                serviceLogPk:=ServiceLogPk,
                                                accountAppLogPk:=AccountAppLogPk,
                                                accountLogPk:=AccountLogPk,
                                                clientLogPk:=ClientLogPk)

  If Success Then
    finBL.DebugPrint("Service Log Pk: " & CStr(ServiceLogPk))
    finBL.DebugPrint("Client Log Pk:  " & CStr(ClientLogPk))
  End If

  ' Return Success
  Return Success

End Function

' ------------------------------------------------------------------
' Snippet 4: ExecuteWithLog — auto-creates an Account Log
'
' Same pattern as Snippet 3 but pointed at an Account. Use this for
' service calls related to a specific loan / facility.
' ------------------------------------------------------------------
Public Function Snippet4_ExecuteWithLog_Account() As Boolean

  Dim AccountAppLogPk As Integer
  Dim AccountLogPk As Integer
  Dim ClientLogPk As Integer
  Dim Request As ISCustomRequest_CustomRequest
  Dim Response As ISCustomResponse_CustomRequest
  Dim ServiceLogPk As Integer
  Dim Success As Boolean

  ' Assume Success
  Success = True

  ' Build Request
  Request = finBL.CustomService.CreateRequest()
  With Request
    .RequestUrl = "https://api.example.com/payments/ACCT00001"
    .Method = iseWebServiceMethod.Post
    .ContentType = "application/json"
    .Payload = "{""amount"":250.00,""currency"":""NZD""}"
    .EnquiryReference = "Payment dispatch for ACCT00001"
  End With

  ' Execute and auto-create the Account Log
  Success = finBL.CustomService.ExecuteWithLog(Request, Response,
                                                subject:="Payment dispatched",
                                                accountId:="ACCT00001",
                                                serviceLogPk:=ServiceLogPk,
                                                accountAppLogPk:=AccountAppLogPk,
                                                accountLogPk:=AccountLogPk,
                                                clientLogPk:=ClientLogPk)

  If Success Then
    finBL.DebugPrint("Service Log Pk: " & CStr(ServiceLogPk))
    finBL.DebugPrint("Account Log Pk: " & CStr(AccountLogPk))
  End If

  ' Return Success
  Return Success

End Function

' ------------------------------------------------------------------
' Snippet 5: ExecuteWithLog — auto-creates an Account Application Log
'
' Use accountAppApplicantPk together with accountAppId when the call
' relates to a specific applicant within the application. Pass 0 for
' applicantPk if the call is for the application as a whole.
' ------------------------------------------------------------------
Public Function Snippet5_ExecuteWithLog_AccountApp() As Boolean

  Dim AccountAppLogPk As Integer
  Dim AccountLogPk As Integer
  Dim ClientLogPk As Integer
  Dim Request As ISCustomRequest_CustomRequest
  Dim Response As ISCustomResponse_CustomRequest
  Dim ServiceLogPk As Integer
  Dim Success As Boolean

  ' Assume Success
  Success = True

  ' Build Request
  Request = finBL.CustomService.CreateRequest()
  With Request
    .RequestUrl = "https://api.example.com/identity/verify"
    .Method = iseWebServiceMethod.Post
    .ContentType = "application/json"
    .Payload = "{""applicantPk"":42}"
    .EnquiryReference = "Identity verification"
  End With

  ' Execute and auto-create the Account Application Log
  Success = finBL.CustomService.ExecuteWithLog(Request, Response,
                                                subject:="Identity verification",
                                                accountAppId:="AAPP00001",
                                                accountAppApplicantPk:=42,
                                                serviceLogPk:=ServiceLogPk,
                                                accountAppLogPk:=AccountAppLogPk,
                                                accountLogPk:=AccountLogPk,
                                                clientLogPk:=ClientLogPk)

  If Success Then
    finBL.DebugPrint("Service Log Pk:                 " & CStr(ServiceLogPk))
    finBL.DebugPrint("Account Application Log Pk:     " & CStr(AccountAppLogPk))
  End If

  ' Return Success
  Return Success

End Function

' ------------------------------------------------------------------
' Snippet 6: CreateServiceLogWithLog — migration path with auto Log
'
' Migration pattern (script makes its own HTTP call) but with the
' entity Log row auto-created up front. After the script's HTTP call
' completes, call UpdateServiceLog to flip the row to Completed or
' Failed.
' ------------------------------------------------------------------
Public Function Snippet6_CreateServiceLogWithLog_Account() As Boolean

  Dim AccountAppLogPk As Integer
  Dim AccountLogPk As Integer
  Dim ClientLogPk As Integer
  Dim HttpCallSucceeded As Boolean
  Dim ResponseBody As String
  Dim ServiceLogPk As Integer
  Dim Success As Boolean

  ' Assume Success
  Success = True

  ' Step 1: log Pending and create the Account Log alongside it
  If Success Then
    Success = finBL.CustomService.CreateServiceLogWithLog("Statement export ACCT00001",
                                                           "https://api.example.com/statements/ACCT00001",
                                                           iseWebServiceMethod.Get,
                                                           "",
                                                           Nothing,
                                                           Nothing,
                                                           ServiceLogPk,
                                                           subject:="Statement export",
                                                           accountId:="ACCT00001",
                                                           accountAppLogPk:=AccountAppLogPk,
                                                           accountLogPk:=AccountLogPk,
                                                           clientLogPk:=ClientLogPk)
  End If

  ' Step 2: script's own HTTP call goes here (omitted)
  '          On success, populate ResponseBody and set HttpCallSucceeded = True
  '          On failure, leave ResponseBody empty and HttpCallSucceeded = False
  If Success Then
    HttpCallSucceeded = True
    ResponseBody = "{""statement"":""...""}"
  End If

  ' Step 3: flip the Service Log to Completed or Failed based on the script's HTTP result
  If Success Then
    If HttpCallSucceeded Then
      Success = finBL.CustomService.UpdateServiceLog(ServiceLogPk, True, ResponseBody, Nothing, "")
    Else
      Success = finBL.CustomService.UpdateServiceLog(ServiceLogPk, False, "", Nothing, "Statement export failed.")
    End If
  End If

  If Success Then
    finBL.DebugPrint("Service Log Pk: " & CStr(ServiceLogPk))
    finBL.DebugPrint("Account Log Pk: " & CStr(AccountLogPk))
  End If

  ' Return Success
  Return Success

End Function

The following built-in Summary Page has been added:

  • SummaryPage2_CustomServiceEnquiryReport_Custom
    • Version: 1.00 (29/04/2026)