Skip to main content

UBC Business objects (UBC.bo)

Intro​

UBC.bo and its Object defintion is the basis and cross-link to ensure access to the SAP standard or custom objects. General customizing is available through SAP Reference IMG -> Cross Application Components -> Unified Backend Connector (UBC) or – as a shortcut – transaction /UBC/CUSTOMIZING.

Business Object​

The so called "business object" within UBC is the nexus for all areas. All logics will be defined at the business object level. A business object itself is customizable and can be defined completely free. To do so, go to section Business object configuration. Object definition in customizing

  • Object type First, the type of object can be defined completely free. It has to be unique within the system/client, normally depending on the object and mirroring the use case it is applied for.
  • Version Object types can be versioned, but this is rather for internal reasons. This mechanism is needed for structural changes, e.g., type change from IDOC ORDERS03 -> ORDERS05. In UBC, always the last versions are considered for the determination of object types by some attributes (like IDOCs basic type, extension, message type), but it ensures to have previous versions still available and active!
  • Category Choose the object category wether it is a freestlye own or has own "determination" by some attributes, like IDOC for message type/basic type/extension. If not needed, choose "freestyle"
  • Handler An Object is assigned to a handler implementation which controls all the integration aspects (like type definition, standard handling for outbound/inbound). Every handler class must at least implement interface /UBC/IF_BO and can extend /UBC/CL_BO (generic, abstract superclass).
  • IDOC Basic type / extension If the object is an IDOC (see UBC.idoc), you can specify the IDOC related fields.
    warning

    make sure your handler implements /UBC/IF_BO_IDOC

  • Object type and Path to ID If the object type corresponds to an SAP standard object, the object type has to be specified. It is required in order to attach the workflows/messages to the SAP standard object via GOS (Generic Object Services). (see UBC.flow) For getting all the started workflows for a specific Id, the mapping path to object id within payload of the object itself is to be specified by using dot notation adding possibilities for substring extraction. Example: header.id extracts the content out of field id within structure header in payload and uses it as an Object Id to fetch business objects with the specified type and id. Please also refer to the field mapping of UBC.io, as all the mapping possibilities, like substring, tablea access, can used here too.

Attributes​

New attributes can be defined in Business object attribute configuration. Then, newly defined attributes can be applied to a custom business object in view cluster of Obect configuration Attributes. It can be seen as a freely definable list of "key-value" pairs for a specific business object to apply logic for. E.g. for custom determination of an object type based on specific attributes or further configuring the object without changing implementation. You can make use of services from /UBC/CL_CONFIGURATION to read object attributes within your object implementation.

IDOC message types​

Assign IDOC message types in combination to IDOC basic type and extension on business object level. It is needed for determination of the UBC business object type from a IDOC as a basis.

Implementation​

A business object has its own model and implements inbound/outbound logic. All methods needed for a valid implementation of a business object are abstract. As described, e.g. an IDOC business object inherits from /UBC/CL_BO_IDOC, all mandatory logic is already implemented in a generic way. For "freestyle" business objects, inherit from /UBC/CL_BO and implement the following:

  • Define the object structure by implementing the method CREATE_TYPE. It can be a reference to DDIC/class type/... Make sure to create a new one and do not use a reference to a local variable as it will be automatically garbage collected. Example: rr_data = new mara( ).
  • Implement PROCESS_INBOUND_BO if you are using Inbound process and process the given payload. If any object was created or changed, specify ET_RESULT-OBJECT_KEY and ET_RESULT-OBJECT_TYPE with the info about the standard objects. This is needed to save an object connection ID, show the workflow in GOS for the specific objects and offer jumping routines. Since the outbound process is always triggered by an external caller (custom program, IDOC Port function), there is no need to implement any custom logic for transmitting object data.

Mapping of Data​

While triggering in-/outbound process, it is often necessary to map business object data from its source values to a specific target. On a UBC business object, there is a single point to define mapping for in-/and outbound specific to a business object. Methods like CREATE_MAPPER_INBOUND or CREATE_MAPPER_OUTBOUND can be implemented on subclasses of /UBC/CL_BO and will be called when its time to map the data (see also workflow). By returning an implementation for /UBC/IF_BO_MAPPING which usually inherits from /UBC/CL_BO_MAPPING you can implement custom mapping logic in defined abstract methods which is perfectly integrated in UBC.io and UBC.flow.

The mapping will be applied for your process and used for the follow-up steps. The applied mapping and original data will be visible in UBC.io for good traceability. Hint: any mapping in inbound processing or even before triggering outbound process is to be avoided. The reason is simple – the monitoring/traceability will be lost.

Proxy​

Another central object in within UBC is the concept about Proxies. A Proxy is a representation of a collection of outbound-services reachable at a specific domain. Including all the information about, which Authorization has to be used, RFC destination, other metadata about which person to notify on errors, ... A process in UBC always is connected to a Proxy, which of course can also be UBC itself but necessarily not need to. The key of a Proxy is an organization-id (char36) which can be freely defined. Each "proxy" representation has a type which points to a Proxy implementation. See Proxy type configuration in Customizing. We offer some default implementation for a set of proxies (Azure Data Storage, Unibright.ONE, BTP Document Extraction, Office 365 Mail, S1SEVEN, ...), own proxy types can of course be added. Usually each use case has its own "setup" task list specifiying the other attributes for a proxy, so please refer to the dedicated use case. It will generate Organization Id, the type of authorization, credentials, RFC destination, ... A Proxy can be instantiated by calling methods of /UBC/CL_PROXY_FACTORY, giving the organization Id. A proxy can be linked to a specific SAP company code in the client. This linkage can be used for authorization checks (see UBC documentation) and/or proper routing of documents to solely one of many proxies.

Standard I/O interfaces​

Delivering standard REST services with our UBC.rest component making use in standard object implementations /UBC/CL_BO.

Inbound – UBC_IN​

This is the interface regarding all inbound messages for any business object (as implemented in /UBC/CL_BO), for example triggered by UBC.rest, or any other process in SAP calling /UBC/CL_BO_FACTORY=>GET_INSTANCE( )->CREATE( )->LOG_INBOUND( )... The interface itself triggers a new inbound workflow where the actual process is built, see Inbound workflow.

Outbound – UBC_OUT​

This is the interface regarding all outbound messages for any business object (as implemented in /UBC/CL_BO), for example triggered by UBC.idoc, or any other process in SAP calling /UBC/CL_BO_FACTORY=>GET_INSTANCE( )->CREATE( )->LOG_OUTBOUND( )... The interface itself triggers a new outbound workflow where the actual process is built like transmitting data to other systems, see Outbound workflow.

Inbound Message Status – UBC_MSG_ST​

This is the interface regarding the status update for previously sent business objects. The interface can be triggered by a rest service or by methods /UBC/IF_BO->LOG_INBOUND_RESULT_STATUS( ). It shows whether the processing of a proxy was successful or not. If it was successful, an object connection ID then will be linked to the previously sent object (table /UBC/BOC) and the outbound workflow will be completed. This is only applicable, if your proxy supports "status" messages by implementing method /ubc/if_proxy_bo~is_sending_bo_status.

info

Most of the time not needed!

Outbound Message Status – UBC_STATUS_OUT​

This is the interface regarding the status update for previously received business objects. The interface is triggered by the inbound process when a posting of a business object was successful or not and activates the transmission of this information to the connected proxy. This is only applicable, if your Proxy implementation specifies a resource in method get_resource_bo_status.

info

Most of the time not needed!

Standard Workflows​

Delivering standard REST services with our UBC.flow component making use in standard object implementations /UBC/CL_BO.

It is to emphasize that every step modelled within the standard delivery workflows does not require any user interaction/approval. If this should be required, please refer to the documentation of UBC.flow. You are free to change the standard workflows as well as defining new ones.

Inbound​

This is the workflow triggered by an inbound message, see Inbound - UBC_IN, the workflow definition is 80000.

Inbound workflow

This is just a highl-level overview of its steps:

  • Mapping of inbound message, call of implementation /UBC/CL_BO->CREATE_MAPPER_INBOUND. If implemented, the mapping will be applied to data and visualized in UBC.io.
  • Posting of data, Implementation /UBC/CL_BO->PROCESS_INBOUND_BO will be called. (to be redefined)
  • Error handling steps: workflow will be stuck at this point, until a restart is executed within UBC.io. You are free to add error notifications, see UBC.flow documentation.

Outbound​

This is the workflow triggered by outbound message, see Outbound – UBC_OUT, the workflow definition is `80001.

Outbound workflow

This is just a highl-level overview of its steps:

  • Mapping of outbound message, call of implementation /UBC/CL_BO->CREATE_MAPPER_OUTBOUND. If implemented, mapping will be applied to data and visualized in UBC.io.
  • Posting of data, standard implementation in /UBC/CL_BO transmits the message to target proxy, method /UBC/IF_PROXY_BO->DISPATCH_BUSINESS_OBJECT( )
  • Waiting for status update if configured. The step will automatically be approved or declined (depending on success or error coming back).
  • Error handling steps: workflow will be stuck at this point, until a restart is executed within UBC.io.

Standard REST interfaces​

Delivering standard REST services with our UBC.rest component making use of standard object implementations /UBC/CL_BO.

Proxy configuration /ubc/proxies​

Available methods: POST, GET Configuration for outbound “proxy” which can receive and send objects from a UBC point of view. Some technical information will be set, such as hostname, authorization, RFC destination etc. This is just a REST webservice for configuring a proxy, normally it is done by some system setup task (see the project details) For GET a list of proxies will be returned. For POST a proxy configuration can be just changed/adapted. It is just some kind of "service" interface, normally not needed.

Business Objects Model /ubc/business_object_models/{type}/{type_version}​

Every "UBC" Business Object is defined by customizing and its structure has to be modelled. This can, for example, be based on an IDOC basic type/extension or completely freestyle in a custom implementation. This method ist for getting the Business Object Model schema definition by giving Object Type and Version Available methods: GET Parameters:

  • type (as it is modelled within UBC customizing Business object configuration)
  • type_version (as it is modelled within UBC customizing Business object configuration) Respose: Open API Schema for the specified object as it was modelled within UBC

Business objects /ubc/business_objects​

Posting of "UBC" business objects incl. monitoring, framework, mapping, etc. This resource is rather generic and acts by logic configured for a specific object type (payload mapping, data handling such as IDOC, etc.) within UBC customizing. (see Business object configuration) It can further handle all business objects configured within UBC. Therefore, payload depends highly on the business object itself because it has to match the business object structure. See also Business objects model REST service Available methods: POST Parameters:

  • type type of modelled object
  • type_version version of modelled object
  • organization_id registered system/proxy to be able to do some sender-specific mapping/routing, see also Proxy configuration
  • id object id
  • object_connection_id external ID to which object corresponds and to which circuit was triggered - optional
  • payload payload as given by business object implementation Returns: Status Code 200 if everything was OK Messages table in response of SAP-type bapiret2

Data Archiving​

UBC comes with a dedicated Archiving Object /UBC/BOC, used to archive all the data which was persisted to monitor and control the workflow of objects. As in most SAP standard applications the archive runs are scheduled within transaction SARA. The write step offers multiple options to select the messages. Please note that only data will be archived which are produced by our Addon and are in a completed state. The write step does not trigger data archiving of a connected business object or IDOC. The data archiving can also be included in customer archiving routines. All what is needed is to call methods of /UBC/IF_ARC_BOC_SERVICE in custom write programs.