Incoming ‘Request’ BODs

The following business object methods are needed for receiving request-type BODs in LN.

Incoming BOD Required Method Reply BODs
Process OnProcess Acknowledge or Confirm or none
Sync OnSync Confirm or none
Load OnLoad Confirm or none
Post OnPost Confirm or none
Update OnUpdate Confirm or none

For the OnProcess method the developer must make sure that:

  • The method returns a response (so not a result) if an Acknowledge BOD must be sent.
  • In the response, a controlling attribute ‘actionCode’ is available to indicate the ActionExpression.actionCode for the acknowledge BOD.
  • The method returns a result if and only if a Confirm BOD must be sent.

The actionCode must be set in a method hook for the OnProcess method using: 

ret.bool = setControlAttribute(“actionCode”, actionCodeValue)

Or, in case of a batch implementation for the OnProcess method: 

ret.bool = setControlAttributeInResponse(o.response, “actionCode”,
		actionCodeValue)

If these functions are invoked multiple times, only the last value is used. If it is unused, no acknowledge BOD will be sent.

The setControlAttribute or setControlAttributeInResponse can be used to include any control element (except complex XML structures).

Regarding the actionCode, note the following:

  • The actionCode for an Acknowledge BOD will be: ‘Accepted’, ‘Modified’ or ‘Rejected’. The value is used for the BOD as a whole, so it cannot be set per object instance. So the response cannot indicate that on order instance is ‘Modified’ and another one is ‘Accepted’. In that case the actionCode will simply be ‘Modified’.
  • If the actionCode is empty, then no Acknowledge BOD is sent. This is achieved by using setControlAttribute("actionCode", "") Reason: if a business object method has output arguments, then the standard business object runtime will always create a response. This means that it will be impossible for the application to send an Acknowledge in some cases, while not sending an Acknowledge (and not sending a Confirm either) in other cases. Therefore the application is allowed to use an empty actionCode to suppress the Acknowledge message, if needed.
  • In case of ‘Accepted’ or ‘Rejected’, the noun portion can be empty. However, this is unsupported in the standard business object runtime. If the noun must be empty, then the OnProcess implementation must make sure no data is included in the response. However, in practice data will be needed, because the receiving party must at least be able to identify the involved noun instance. The reason for that is that at this moment we are unable to link the received Acknowledge to a sent Process otherwise.Anyhow, the LN implementation can set the actionCode to ‘Modified’ if needed, for example if the value for one or more attributes is generated within LN, or if it is desirable to send an Acknowledge anyhow.
  • Additionally, in case of ‘Modified’ the noun must only include changed elements. However, this is not done automatically by the standard logic. By default, all output attributes are included. So if needed it must be programmed in the on execute hook for the OnProcess method (or an underlying protected method).
  • Regarding the distinction between an Acknowledge having actionCode ‘Rejected’ and a Confirm BOD: if a Process request resulted in a state change in LN, use Acknowledge, otherwise use Confirm. When receiving an Acknowledge having status 'rejected' on the requesting side, a user can ask 'Why has purchase order 1234 been rejected?' And the LN user can check the system, find the purchase order and explain the situation. In case of a Confirm, the database transaction was aborted. The instance is not stored at the system of record. Note that this matches the distinction between ‘response’ and ‘result’ in BDE terms: in case of a result, the transaction is aborted.

For other methods the developer must make sure that:

  • The method never returns any output in the response (except warnings in the information area).
  • The method contains one or more messages in the response information area if warnings must be logged, but no Confirm BOD must be sent.
  • The method returns a result if and only if a confirm BOD must be sent.

  • In the ‘On’ methods, the ActionExpression.actionCode from the incoming BOD can be retrieved in any BII hook using: 

    ret.bool = getControlAttribute(“actionCode”, actionCodeValue)

To summarize, the following picture shows the flow for two typical ‘from bus’ scenarios: the Process/Acknowledge cycle and the Sync handling.