Business Integration Solutions Documentation

How To: Create a Code Event

A Code Event is triggered from a Dynamics Business central Object and starts a pipeline for one or more records.

Usage

Use this task when you want to start a BIS Connection for a certain record from a specific object.

The Code Event is executed in a synchronious manner unless the property Post with Job Queue is enabled. It is recommended to use the Job Queue for processing BIS connections since this will offload processing to a new background session

Changes between OnPremise and SaaS

The CodeEvent is rewritten to support similar functionality, while handling the loss of metadata access during a call. In the OnPremise version of BIS, the code-event was bound to a specific object, which was easy to access, since the calling object type and ID were available. This metadata is no longer available in SaaS.

The upside to this, is that the new code-event will have more flexibility. By using a unique ID, you can have multiple triggers in one object, all potentially triggering different connections at various stages in your code.

To avoid confusion on which CodeEvent is used, the differences are made in the function names.

  • Onpremise "Calling object awareness" has RegisterEvent()
  • SaaS has RaiseEvent()

The new method of raising an event will find it's way to OnPremise in future releases.

Prerequisites

The following prerequisites are required

  • Experience in developing in Business Central AL
  • Familiarity with the concept of Event based programming
  • Understanding of Business Integration Solutions and the role of Events in the pipeline
  • A valid developer license
  • An environment with STAEDEAN-Common and STAEDEAN-BIS installed.

Steps for a CodeEvent in SaaS

For setting up a CodeEvent in OnPremise, the references and procedures are different. See Below

  1. Open your app in VSCode
  2. Open the object where you would like to trigger the code-event from
  3. Create a dependency on STAEDEAN-BIS, which should be similar to this:
    "dependencies":  [
        {
            "id": "9b0fdadc-3c4a-4dc4-82bf-6ac1c4bd5d71",
            "name": "TI-BIS",
            "publisher": "To-Increase B.V.",
            "version": "20.0.0.0"
        }
    ],
  1. Declare the following local variables:
Name Datatype Subtype
BISCodeEventAPI codeunit "BISAPI Code Event"
MyRecordRef RecordRef
  1. Add one of the 3 events in your code to trigger the connection For a Single Record
RaiseEventForRecord(EventId: Code[50]; RecRef: RecordRef)

For a RecordID (as an alternative to the RecordReference)

RaiseEventForRecord(EventId: Code[50]; "RecordId": RecordId)

For a recordSet

RaiseEventForRecordSet(EventId: Code[50]; RecRef: RecordRef)

For a recordset, but with separate messages per record

RaiseEvent(EventId: Code[50]; RecRef: RecordRef)

Steps for a CodeEvent in OnPremise

  1. Open your app in VSCode
  2. Open the object where you would like to trigger the code-event from
  3. Create a dependency on STAEDEAN-BIS, which should be similar to this:
    "dependencies":  [
        {
            "id": "9b0fdadc-3c4a-4dc4-82bf-6ac1c4bd5d71",
            "name": "TI-BIS",
            "publisher": "To-Increase B.V.",
            "version": "20.0.0.0"
        }
    ],
  1. Declare the following local variables:
Name Datatype Subtype
BISCodeEventAPI codeunit "BIS Register Pipeline Event"
MyRecordRef RecordRef
  1. Add one of the 3 events in your code to trigger the connection
RegisterEventForRecord(RecRef: RecordRef)

RegisterEvent(RecRef: RecordRef)

RegisterEventForRecordSet(SenderObjectType: Text; SenderObjectId: Integer; RecRef: RecordRef)

This last one is more flexible, since you can set the objecttype and ID yourself.

Breaking change in OnPremise

Since the March 2023 release, to align the objects handling the CodeEvent in On-Premise and SaaS, we had to renumber the OnPremise API Pipeline Event Handler from codeunit 11070278 "BIS Pipeline Event Handler" to codeunit 11070678 "BIS Pipeline Event Handler"

If the code-event is triggered from the API, we highly recommend using the steps from On-Premise, using the BIS Register Pipeline Event, in case you're using the API Pipeline Event Handler, please update your app with the following details

Set the minimum version of BIS in your app to 20.0.84711.0

    "dependencies":  [
        {
            "id": "9b0fdadc-3c4a-4dc4-82bf-6ac1c4bd5d71",
            "name": "TI-BIS",
            "publisher": "To-Increase B.V.",
            "version": "20.0.84711.0"
        }
    ],

Download dependency symbols and recompile your app. If the API Pipeline Event Handler references the codeunit by integer, it will have to be manually adjusted.