Siebel Object Interfaces Reference > Siebel Object Interfaces Reference > Object Interfaces Reference >

Business Component Events

This topic describes business component events. It includes the following topics:

• Monitoring Modifications That the User Makes to a Multivalue Field
• BusComp_Associate Event
• BusComp_ChangeRecord Event
• BusComp_CopyRecord Event
• BusComp_DeleteRecord Event
• BusComp_InvokeMethod Event
• BusComp_NewRecord Event
• BusComp_PreAssociate Event
• BusComp_PreCopyRecord Event
• BusComp_PreDeleteRecord Event
• BusComp_PreGetFieldValue Event
• BusComp_PreInvokeMethod Event
• BusComp_PreNewRecord Event
• BusComp_PreQuery Event
• BusComp_PreSetFieldValue Event
• BusComp_PreWriteRecord Event
• BusComp_Query Event
• BusComp_SetFieldValue Event
• BusComp_WriteRecord Event

You can use these events only on the Siebel Server, except for the PreSetFieldValue event, which you can use only on the browser.

You can call an event from a data operation on a business component. You define these events for each business component. You can call an event before or after Siebel CRM performs the predefined behavior.

Monitoring Modifications That the User Makes to a Multivalue Field

To monitor modifications the user makes to a multivalue field, you must use the multivalue group business component.

If the user uses the multivalue group applet to modify a value in a multivalue field, then Siebel CRM calls the PreSetFieldValue event and the SetFieldValue event for the field. It does not call any event on the parent business component.

If the user does not use the multivalue group applet to modify a value in a multivalue field, then Siebel CRM does not start the PreSetFieldValue event or the SetFieldValue event for the field. The only time Siebel CRM starts these events is if the user updates the field in the multivalue group applet.

BusComp_Associate Event

If the user adds a business component record to create an association, then Siebel CRM calls the BusComp_Associate event. This method does not return any information.

Format

BusComp_Associate

No arguments are available.

Usage

The usage for the BusComp_Associate event is the same as the usage for the BusComp_NewRecord event. For more information, see BusComp_NewRecord Event.

Used With

Server Script

BusComp_ChangeRecord Event

If a business component record becomes the current record, then Siebel CRM calls the BusComp_ChangeRecord event. This method does not return any information.

Format

BusComp_ChangeRecord

No arguments are available.

Usage

Siebel CRM runs code in the ChangeRecord event handler each time the active record changes. To allow smooth scrolling in a list applet, you must avoid lengthy operations in this event handler.

Used With

Server Script

Examples

The Siebel VB example in this topic uses subprograms in the declarations section of the general section to set up an audit trail for service requests. This example uses the ChangeRecord event handler to initialize the values from the service record so that Siebel CRM can compare them with current values:

(general)
(declarations)
Option Explicit
Dim OldClosedDate, OldCreated, OldOwner, OldOwnerGroup
Dim OldSeverity, OldSource, OldStatus
Declare Sub CreateAuditRecord
Declare Sub InitializeOldValues

Sub CreateAuditRecord (FieldName As String, NewValue As String, OldValue As String, ChangedText As String)

   Dim ActionBC As BusComp
   Dim CurrentBO As BusObject
   Dim theSRNumber

   Set CurrentBO = TheApplication.GetBusObject("Service Request")
   Set ActionBC = CurrentBO.GetBusComp("Action")
   theSRNumber = GetFieldValue("SR Number")

   With ActionBC
      .ActivateField "Activity SR Id"
      .ActivateField "Description"
      .ActivateField "Private"
      .ActivateField "Service request id"
      .ActivateField "Type"
      .NewRecord NewAfter

      .SetFieldValue "Activity SR Id",      theSRNumber
      .SetFieldValue "Description",         ChangedText
      .SetFieldValue "Private",               "Y"
      .SetFieldValue "Type",                "Administration"
      .WriteRecord
   End With
End Sub

Sub InitializeOldValues
   OldClosedDate = GetFieldValue("Closed Date")
   OldOwner = GetFieldValue("Owner")
   OldSeverity = GetFieldValue("Severity")
   If GetFieldValue("Severity") <> OldSeverity Then
      NewValue = GetFieldValue("Severity")
      ChangedText = "Changed Priority from " + OldSeverity + _
         " to " + NewValue
      CreateAuditRecord "Severity", NewValue, OldSeverity, _
         ChangedText
   End If
End Sub

Sub BusComp_ChangeRecord
   InitializeOldValues
End Sub

BusComp_CopyRecord Event

If the user copies a business component record, and if the user makes this record the active record, then Siebel CRM calls the BusComp_CopyRecord event. This method does not return any information.

Format

BusComp_CopyRecord

No arguments are available.

Usage

If a new record is created in one of the following ways, then Siebel CRM calls the BusComp_CopyRecord method instead of the BusComp_NewRecord method:

• Siebel CRM creates a new record through one of the following:
  • BusComp.NewRecord NewAfterCopy
  • BusComp.NewRecord NewBeforeCopy
• A user uses a copy record feature in the Siebel Client. For example, if the user chooses the Copy Record menu item from the Edit menu, or presses CTRL+B.

Used With

Server Script

BusComp_DeleteRecord Event

If the user deletes a business component record, then Siebel CRM calls the BusComp_DeleteRecord event. The fields of the deleted record are no longer available. This method does not return any information.

Format

BusComp_DeleteRecord

No arguments are available.

Usage for the BusComp_DeleteRecord Event

Siebel CRM does not start the BusComp_PreDeleteRecord event or the BusComp_DeleteRecord event for a child record that it deletes according to the Cascade Delete property on a link. For performance reasons, Siebel CRM performs these deletes directly in the data layer. Siebel CRM calls script events from the object layer, so it does not run them.

Used With

Server Script

BusComp_InvokeMethod Event

If Siebel CRM calls the InvokeMethod method on a business component, then it also calls the BusComp_InvokeMethod event. This method does not return any information.

Format

BusComp_InvokeMethod(methodName)

The arguments you can use with this format are the same as the arguments described in Table 26.

Usage

If you call a specialized method on a business component, or if you call the InvokeMethod method explicitly on a business component, then Siebel CRM calls the BusComp_InvokeMethod event. For more information, see About Specialized and Custom Methods.

Used With

Server Script

BusComp_NewRecord Event

If the user creates a business component record, and if the user makes this record the active record, then Siebel CRM calls the BusComp_NewRecord event. You can use this event to set up default values for a field. This method does not return any information.

Format

BusComp_NewRecord

No arguments are available.

Usage

If a new record is created in one of the following ways, then Siebel CRM calls the BusComp_CopyRecord method instead of the BusComp_NewRecord method:

• Siebel CRM creates a new record using one of the following formats:
  • BusComp.NewRecord NewAfterCopy
  • BusComp.NewRecord NewBeforeCopy
• A user uses a copy record feature in the Siebel client. For example, the user chooses the Copy Record menu item from the Edit menu, or presses CTRL+B.

Used With

Server Script

Examples

For an example, see Pick Method for a Business Component.

BusComp_PreAssociate Event

If Siebel CRM detects that the user is about to add a business component record to create an association, then it calls the BusComp_PreAssociate event before it adds the record. This method returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreAssociate

No arguments are available.The format is the same as for BusComp_PreNewRecord event. For more information, see BusComp_PreNewRecord Event.

Used With

Server Script

BusComp_PreCopyRecord Event

If Siebel CRM detects that the user is about to copy a business component record, then it calls the BusComp_PreCopyRecord event before it copies the record. You can use this event to perform precopy validation. This method returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreNewRecord

No arguments are available.

Used With

Server Script

BusComp_PreDeleteRecord Event

If Siebel CRM detects that the user is about to delete a business component record, then it calls the BusComp_PreDeleteRecord event. You can use this event to prevent the deletion or to perform any actions before Siebel CRM deletes the record.This method returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreDeleteRecord

No arguments are available.

Usage

Usage for the BusComp_PreDeleteRecord event is the same as usage for the BusComp_DeleteRecord event. For more information, see Usage for the BusComp_DeleteRecord Event.

Used With

Server Script

Examples

The following Siebel VB example prevents the deletion of an account that includes associated opportunities:

(general)
(declarations)
Option Explicit

Function BusComp_PreDeleteRecord As Integer
   Dim oBC as BusComp
   Dim oBO as BusObject
   Dim sAcctRowId as string

   sAcctRowId = me.GetFieldValue("Id")
   set oBO = TheApplication.GetBusObject("Opportunity")
   set oBC = oBO.GetBusComp("Opportunity")

   With oBC
      .SetViewMode AllView
      .ClearToQuery
      .SetSearchSpec "Account Id", sAcctRowId
      .ExecuteQuery ForwardOnly
      If (.FirstRecord = 1) Then
         RaiseErrorText("Opportunities exist for the Account - _
            Delete is not allowed")
      End If
   End With

   BusComp_PreDeleteRecord = ContinueOperation

   Set oBC = Nothing
   Set oBO = Nothing

End Function

BusComp_PreGetFieldValue Event

If a user accesses a business component field, then Siebel CRM calls the BusComp_PreGetFieldValue event. This method returns the field name and field value that exists before Siebel CRM displays the field. It also returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreGetFieldValue(FieldName, FieldValue)

Table 81 describes the arguments for the BusComp_PreGetFieldValue event.

Usage

Siebel CRM calls the BusComp_PreGetFieldValue event in the following situations:

• At least one time for each user interface element that displays the value for a business component field
• Every time it updates the Siebel client
• As a result of other internal uses

Improving Performance when Calling the BusComp_PreGetFieldValue Method

Siebel CRM runs any script that is attached to this event very frequently. It even calls empty scripts. These calls might cause a Siebel application appear to be unresponsive.

To improve performance when calling the BusComp_PreGetFieldValue method

• Remove scripts from the BusComp_PreInvokeMethod event that you do not require:
  1. In Siebel Tools, open a script you do not require.
  2. Delete the entire contents of the script, including the following content:
     • In Siebel VB, delete the Function statement and the End Function statement.
     • In Siebel eScript, delete the function () statement and the {} function statement.
  3. Repeat Step a for all other scripts you do not require.

Used With

Server Script

BusComp_PreInvokeMethod Event

If Siebel CRM calls a specialized method on a business component, then it calls the BusComp_PreInvokeMethod event before it calls this specialized method. The BusComp_PreInvokeMethod event returns ContinueOperation or CancelOperation. For more information, see About Specialized and Custom Methods, and Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreInvokeMethod(methodName)

The arguments you can use with this format are the same as the arguments described in Table 26.

Used With

Server Script

BusComp_PreNewRecord Event

If Siebel CRM detects that the user is about to create a new business component record, then it calls the BusComp_PreNewRecord event before it creates the record. You can use this event to perform preinsert validation. This method returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreNewRecord

No arguments are available.

Used With

Server Script

BusComp_PreQuery Event

Siebel CRM calls the BusComp_PreQuery event before it runs a query. This method returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreQuery

No arguments are available.

Usage

To modify the search criteria or to restrict Siebel CRM from running certain queries, you can use the BusComp_PreQuery event.

Used With

Server Script

Examples

The following example is in Siebel VB:

Function BusComp_PreQuery() As Integer
   Dim strPosition As String
   Dim strSearchSpec As String
   Dim intReturn As Integer
   intReturn = ContinueOperation
   strPosition = TheApplication.PositionName
   strSearchSpec = Me.GetSearchSpec("Owned By")
   If strPosition <> "System Administrator" Then
      if Len(strSearchSpec) = 0 or InStr(strSearchSpec,
         strPosition) = 0 Then
         Me.SetSearchSpec "Owned By", strPosition
      end if
   End if
   BusComp_PreQuery = intReturn
End Function

BusComp_PreSetFieldValue Event

Siebel CRM calls the BusComp_PreSetFieldValue event in the following situations:

• After the user modifies a field value in the Siebel client and then attempts to leave the field
• A call to the SetFieldValue method occurs, but before it performs any field-level validation

This event allows you to use custom validation before Siebel CRM applies predefined validation. This method returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreSetFieldValue(FieldName, FieldValue)

The arguments you can use with this format are the same as the argument described in Table 24.

Usage

If your script returns CancelOperation for a field, then Siebel CRM does not enter data for this field. However, Siebel CRM still starts BusComp_PreSetFieldValue for the other fields that the picklist uses to enter data. For more information, see Caution About Using the Cancel Operation Event Handler.

If a user uses a picklist to enter data for multiple fields, then it starts the BusComp_PreSetFieldValue method for each field that the user uses to enter data. For example, in an applet that the user accesses to enter data for the Last Name, First Name, and Contact ID. In this example, Siebel CRM starts the BusComp_PreSetFieldValue method three times, one time for each field.

Siebel CRM does not call the BusComp_PreSetFieldValue event on a picklist or multivalue field.

Usage With Roundtrips

Siebel CRM does the following during a roundtrip to the Siebel Server:

• In Browser Script, if the Immediate Post Changes property of the business component field is set to TRUE, then it calls the BusComp_PreSetFieldValue method after the round trip to the Siebel Server completes.
• In Server Script, it calls the BusComp_PreSetFieldValue method as the first event in the Siebel Server round trip.

To prevent infinite recursions, if the BusComp_PreSetFieldValue event is running, then Siebel CRM does not run it again for the same business component instance, even if Siebel CRM uses it on a different field in the business component.

Used With

Browser Script, Server Script

Examples

The following Siebel VB example uses the PreSetFieldValue event to determine if a quote discount is greater than 20 percent, and to take the appropriate action if it is. For other examples of BusComp_PreSetFieldValue, see LoginId Method for an Application, and ExecuteQuery Method for a Business Component:

Function BusComp_PreSetFieldValue (FieldName As String,
               FieldValue As String) As Integer
'code to check if a quote discount>20%
'if it is, notify user and cancel operation
Dim value as Integer
Dim msgtext as String
   If FieldName = "Discount" then
      value = Val(FieldValue)
      If value > 20 then
          msgtext = "Discounts greater than 20% must be approved"
         RaiseError msgtext
         BusComp_PreSetFieldValue = CancelOperation
      Else
         BusComp_PreSetFieldValue = ContinueOperation
       End if
End If
End Function

The following is the equivalent example in Siebel eScript:

function BusComp_PreSetFieldValue (FieldName, FieldValue)
{
   var msgtext = "Discounts greater than 20% must be approved";
   if (FieldName == "Discount")
   {
      if (FieldValue > 20)
      {
         TheApplication().RaiseErrorText(msgtext);
      }
      else
      {
         return (ContinueOperation);
      }
   }
   else
   {
      return (ContinueOperation);
   }
}

BusComp_PreWriteRecord Event

Siebel CRM calls the BusComp_PreWriteRecord event before it writes a record to the Siebel database. This method returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

BusComp_PreWriteRecord

No arguments are available.

Usage

For important caution information, see Caution for Using an Error Method with a Write Record Event.

You can use this event to perform any final validation before Siebel CRM performs any predefined internal record-level validation.

Siebel CRM starts the BusComp_PreWriteRecord event only if the user modifies or inserts a field value, or if the user deletes a record. If the user deletes a record, then Siebel CRM calls the BusComp_PreWriteRecord method to delete the implied join that joins any records to the initial record.

Using a Write Record Event with a Multivalue Group

If Siebel CRM associates a multivalue group record that uses a many to many relationship with the business component that calls the association, then it starts the BusComp_PreWriteRecord event and the BusComp_WriteRecord event. It starts these events even if the association does not update any fields in the multivalue group business component or in the calling business component. It runs the BusComp_PreWriteRecord event and the BusComp_WriteRecord event to acknowledge the update to the intersection table.

Used With

Server Script

Examples

The following example calls the BusComp_PreWriteRecord event:

Function BusComp_PreWriteRecord As Integer

   ' This code resets the probability before the write
   ' if necessary

   if Me.GetFieldValue("Sales Stage") LIKE "07*" then
      ' Resets the Probability to 75 if less than 75
      if Val(Me.GetFieldValue("Rep %")) < 75 then
         Me.SetFieldValue "Rep %", "75"
      end If
   end if

   BusComp_PreWriteRecord = ContinueOperation
End Function

BusComp_Query Event

Siebel CRM calls the BusComp_Query event after it completes a query but before it displays the query results. This event does not return any information.

Format

BusComp_Query

No arguments are available.

Used With

Server Script

Examples

In the following Siebel VB example, the Action business component uses a special activity type. If the user starts an account query, then this code determines if important information is available. If it is available, then Siebel CRM displays it in a message box:

Sub BusComp_Query

   Dim oBusObj As BusObject, oCurrFinAct As BusComp,
   Dim oActivities as BusComp, oAppl as Applet
   Dim sName as String, sDescription as String

   On error goto leave

   set oBusObj = TheApplication.ActiveBusObject
   Set oCurrFinAct = TheApplication.ActiveBusComp

   If oCurrFinAct.FirstRecord <> 0 then
      sName = oCurrFinAct.GetFieldValue("Name")
      Set oActivities = oBusObj.GetBusComp("Finance _
         Important Info Activity")
      With oActivities
         .ActivateField("Description")
         .ClearToQuery
         .SetSearchSpec "Account Name", sName
         .SetSearchSpec "Type", "Important Info"
         .ExecuteQuery ForwardOnly
         If .FirstRecord <> 0 then
            sDescription = .GetFieldValue("Description")
            TheApplication.Trace("Important Information: " + sDescription)
            do while .NextRecord <> 0
               sDescription = .GetFieldValue("Description")
               TheApplication.Trace("Important Information: " + sDescription)
            loop
         End If
      End With
   End If

leave:

   Set oCurrFinAct = Nothing
   set oBusObj = Nothing

End Sub

BusComp_SetFieldValue Event

If Siebel CRM sends a value to a business component from the Siebel client or through a call to the SetFieldValue method, then it calls the BusComp_SetFieldValue event. It does not call this event for a predefaulted field or for a calculated field. This event does not return any information.

Format

BusComp_SetFieldValue(FieldName)

The arguments you can use in this format are the same as the arguments that are described in Table 56.

Used With

Server Script

Examples

In the following Siebel VB example, if Siebel CRM calls the SetFieldValue event, then it calls methods on an existing business component:

Sub BusComp_SetFieldValue (FieldName As String)
Dim desc As String
Dim newDesc As String
If FieldName = "Type" Then
   newDesc = [can be any valid string that contains the new description]
   desc = GetFieldValue("Description")
   SetFieldValue "Description", newDesc
End If
End Sub

The following is the equivalent example in Siebel eScript:

function BusComp_SetFieldValue (FieldName)
{
   if (FieldName == "Type" && GetFieldValue(FieldName) == "Account")
   {
      SetFieldValue("Description", "Record is of Type 'Account'." );
   }
}

BusComp_WriteRecord Event

Siebel CRM starts the BusComp_WriteRecord event after it saves the record to the Siebel database. This event does not return any information.

Format

BusComp_WriteRecord

No arguments are available.

Usage

Do not use the BusComp_SetFieldValue event in a BusComp_WriteRecord event. If you must use the BusComp_SetFieldValue event, then use it in the BusComp_PreWriteRecord event. For more information, see BusComp_PreWriteRecord Event.

For information about using the BusComp_WriteRecord event with a multivalue group, see Using a Write Record Event with a Multivalue Group.

Caution for Using an Error Method with a Write Record Event

CAUTION:  Be careful if you use the RaiseError method or the RaiseErrorText method in the BusComp_WriteRecord event or in the BusComp_PreWriteRecord event. For example, if you use the RaiseErrorText method in the BusComp_PreWriteRecord method, then the user or the code cannot step off the current record until the condition that causes Siebel CRM to call the RaiseErrorText method is addressed.

Used With

Server Script