Extensibility Guide for SAP Business Partner Screening

Transcription

1 USER GUIDE PUBLIC Extensibility Guide for SAP Business Partner Screening SAP SE or an SAP affiliate company. All rights reserved. Run Simple

2 Content 1 SAP Business Partner Screening Extensibility Guide Business Transaction Screening Enabling Screening of Business Transactions Business Transaction Screening: Data Model Business Transaction Screening: Process Flow Implementing Business Transaction Screening Implementing the Interface for Business Partner Master Data Screening Enabling Screening of Business Partner Master Data RFC Function Groups, Function Modules, and Parameters Business Partner Screening: Implementation with RFC Version Management of Business Partner Master Data: Implementation with RFC Business Partner Screening: Implementation with Web Service Adding Customer Fields to Screening APIs Adding Customer Fields to the RFC APIs and Internal Structures Adding Customer Fields to the Web Service for Business Transaction Screening Message Translation and Localized Formatting Enhancing the User Interface Creating Additional Apps and Tiles for the SAP Fiori Launchpad Extending the Manage Alerts App Adding Customer Fields to Alerts in Manage Alerts Migrating ThingInspector Facets to the Manage Alerts App Adding Fields to the Manage Alerts App Updating the SAPUI5 Application Index Extending the Network Analysis Generic Content: Network Analysis Using Microsoft Excel for Analytics P U B L I C Content

3 1 SAP Business Partner Screening Extensibility Guide SAP Business Partner Screening is a generic application. It makes it possible for you to use the speed and power of SAP HANA for screening business partners against lists of persons and organizations published by governments and institutions across the world. Note This document is for consultants and developers who plan to extend SAP Business Partner Screening. This guide is provided only in English. This document explains how to extend this solution in the following ways: Enabling screening of business transactions Implementing screening of business partners who appear in business transactions against screening lists. See Business Transaction Screening [page 4] Enabling business partner master data screening Implementing real-time screening of business partner master data. See Implementing the Interface for Business Partner Master Data Screening [page 15] Making your own extensions to SAP Business Partner Screening You may wish to add data fields to data structures. See Adding Customer-Defined Fields to Business Objects [page 40], Adding Data to Alerts [page 42], and Adding Customer Fields to Screening APIs [page 27] Enhancing the user interface You can enhance the UI by: Adding a SAP Fiori section to the Manage Alerts You can add sections, for example, to display data that you have added to alerts or the data (replicated data) of the investigation object to which the alert belongs. See Extending the Manage Alerts App [page 38] Creating additional tiles for the home screen See Creating Additional Apps and Tiles for the SAP Fiori Launchpad [page 38] More Information SAP Business Partner Screening Extensibility Guide P U BL IC 3

4 2 Business Transaction Screening SAP Business Partner Screening offers an RFC and web service programming interface (API) for screening business partners who appear in business transactions against screening lists. This API makes it possible for you to use the real-time address screening features of the software for anti-corruption compliance and risk avoidance in business transactions from SAP Systems and non-sap systems. Function Groups and Function Modules of the API The API is held in package BPCM_RFC, which you can access with the ABAP Workbench, transaction SE80 or with the Eclipse-based ABAP Development Tools. You will find online documentation on the function modules and parameters in your system. Function Group Function Module Use BPCM_ADDRESS_CHECK Function group for checking business partners and business transactions against screening lists. BPCM_BUSINESS_TRANSACTION_CHK Enhanced Business Transaction Address Check Use this function module to check business partners who appear in business transactions against screening lists. The function module returns hits in screening lists to the source business system. The function module also saves the business transaction data in SAP Business Partner Screening so that delta address screening can be applied to it. In delta address screening, changes in screening lists are used for renewed screening of business partners. BPCM_ALERT_DECISION_CHANGE Use the function module in this function group to communicate decisions on address screening hits from the calling system to SAP Business Partner Screening. 4 P U B L I C Business Transaction Screening

5 Function Group Function Module Use BPCM_ALERT_DECISION_CHANGE Enhanced Partner Screening Alert Decision Change Propagate your decision on a business partner screening hit to SAP Business Partner Screening. The function module closes any alerts created because of the screening hit and sets the decision information for each alert item in the alerts. If you accept a hit, then the relevant alert is closed as "Confirmed". If you reject a hit, then the alert is closed with "False Alarm". Enterprise Web Service of the API Business transaction screening is also offered by way of the enterprise service: BusinessTransactionCheck_Request_Sync_In. This Web service uses the same data structures and offers the same functionality as the RFC interface. Key Features of the API The main features of the API are as follows: Access to address screening of business partners in business transactions in real time. The speed of SAP HANA makes it possible to integrate business transaction screening directly into your business processes. It is not necessary to screen transactions asynchronously. Delta address screening. Business transaction data is retained at the SAP Business Partner Screening system. As screening lists are updated, business partners in transactions can be checked against the changed information in the lists. (Alerts are not propagated automatically to your business system in this case). Simple integration in your business systems. You can implement address screening (which comes with automatic inclusion of business partners in delta address screening) for business transactions with only one or two RFC function module calls, depending on the options that you use. Compatibility: Access to address screening via an RFC interface or web service from SAP business systems or via web services from non-sap systems. Business Transaction Screening P U BL IC 5

6 2.1 Enabling Screening of Business Transactions Before you can use the web service or RFC API for business transaction screening, you must ensure that configuration and customizing tasks have been done in SAP Business Partner Screening. The following tasks must be done: The address screening feature must be enabled. Business transaction screening uses address screening. You can also find information about address screening in the application help at bps_s4. Customizing tasks must also be done to enable business partner screening. In particular, you can add investigation and detection object types if the standard Sales Order and Purchase Order types are not suitable. Also, you may wish to add customer fields to your investigation and detection object types in order to enrich the information in alerts or refine the selection of detection strategies for screening. Additionally, you must define a default investigation reason for alerts. If your business system is an SAP system, then you can set up an RFC destination to the SAP Business Partner Screening system for calling the RFC API. Otherwise, you can use the BusinessTransactionCheck_Request_Sync_In enterprise web service to call business transaction screening. You will also find information about specific customizing requirements in the online documentation of the RFC function modules in package BCPM_RFC in the SAP Business Partner Screening system. Assign authorizations to RFC or web users in SAP Business Partner Screening. Such users must have the SAP_BPCM_SYS_COM role. 2.2 Business Transaction Screening: Data Model Business transaction screening in SAP Business Partner Screening uses a simplified model of a business transaction. This requires you to map from the data model of a business transaction in an ERP system to the simplified BPS model. This section briefly describes the data models and the mapping between them. Generalized Data Model of a Business Transaction The following diagram shows the logical data model of business transactions in source business systems. It is a generalized model for all types of business transactions sales orders, purchase orders, and so on. The model depicts only the aspects of a business transaction that are relevant for address screening. 6 P U B L I C Business Transaction Screening

7 Figure 1: Generalized Data Model of a Business Transaction. A business transaction consists of a header and one or more items. One or more business partners can appear in both the header and in the items of a transaction. The role of a partner in a transaction is documented by assignment to a partner function in the transaction, such as the sold-to, bill-to, payer, and ship-to parties. An address in the header is also valid for all items of the business transaction. The diagram therefore shows an n..m relation between a header address and items. However, if at the item level an address is assigned for a partner function, then this address is valid for a particular item instead of the header address of same partner function. Most addresses in business transactions are addresses of master data objects that are assigned to business transactions. These addresses are stored as business partners, vendors, customers and so on. Such addresses have a master data identification that can be supplied with a call to the business transaction screening interface for inclusion in alerts for documentation purposes. However some addresses can also be added to a business transaction manually by entering the names and postal data. Data Model of a Transaction in Business Transaction Screening As the diagram below shows, business transaction screening reduces the transaction data model shown above to the elements essential for address screening. Business Transaction Screening P U BL IC 7

8 Figure 2: Transaction Data Model in Business Transaction Screening. As the diagram shows, the data model is reduced to the business transaction header - the identification of the business transaction - and the business partner addresses that it contains. Investigation and Detection Object Types As the diagram also shows, the business transaction header corresponds to an investigation object type in SAP Business Partner Screening. An investigation object type represents the entity to investigate, in this case, a business transaction. For each type of business transaction, you can define a separate investigation object type. SAP delivers, for example, investigation object types for sales orders and for purchase orders, and you can define additional investigation object types. You associate business transactions with investigation object types by way of a business transaction type. You define the business transaction types in Customizing and specify the type as part of the key of a business transaction. The typing concept and separate investigation object types for each transaction type let you tailor detection to the transaction type. You can add a different set of customer fields to the API for each type of business transaction. Such fields can be added to alerts as enrichment fields. Or they can be used as selection fields for choosing the detection strategy with which to screen the business partners of a transaction. You can also define a separate navigation for each transaction type. For example, you can navigate to a sales transaction for sales orders, a purchasing transaction for purchase orders. The business partner addresses in a business transaction correspond to detection object types. In SAP BPS, these are the entities to examine for problems during screening against watch lists. In business transaction screening, there is a 1 to n relation between an investigation object type and a detection object type. The detection object type represents both "person" and "organization" business partners. Detailed Data Model The following diagram shows the screening data model in more detail. See the online documentation in the system for the BPCM_BUSINESS_TRANSACTION_CHK function module and related objects for details. 8 P U B L I C Business Transaction Screening

9 Figure 3: Detailed Data Model for Screening. Notes on the API: Transaction header and items: In reducing the transaction data model to fit the ACS data model, the transaction screening API loses the distinction between business partner addresses appearing in the transaction header and those appearing in transaction items. You simply provide all addresses to the BPS system for screening. If the association of an address to the header or items is important to you, then you must manage that information in the calling system. Customer-added fields: May be added only at the business-transaction level of the data model. It is not possible to add extension include fields to business partner entries. Your fields may serve as enrichment fields, which are added as details to alerts. Or your fields can be selection fields, which help select the detection strategies to use. Selection of detection strategies: In addition to selection fields that you add, SAP Business Partner Screening uses the business system, the risk level, the country derived from the organizational unit, and the country from a business partner address to select detection strategies to run. Compliance and risk management requirements vary by country; these standard selection parameters let you match the selected detection strategies to the requirements that you have to meet. You can, for example, screen for risky countries more intensively than low-risk countries. Organizational unit and country of reference: You can specify only a single organizational unit for the business transaction and the business partners it contains. It is the organizational unit that is responsible for the business transaction. Business Transaction Screening P U BL IC 9

10 The organizational unit identifies the country whose regulations for compliance and risk avoidance apply, and this country is one of the selection criteria for the detection strategy to use. Optionally, you can omit organizational units. In this case, you must define a default mapping entry for the current business system in Map Organizational Unit in Customizing. This default entry then applies to all business transactions from the business system. Risk level: An optional value, defined in BPS Customizing, that indicates the severity of the compliance risk posed by a business transaction. A sales order for military hardware has much greater importance and risk, and needs to be more carefully screened, than a sales order for office supplies. More careful screening translates in practice to more potential hits, so that no possible match is missed. The risk level is also used as a selection parameter for choosing detection strategies. Partner functions: If a business partner appears in a transaction more than once and with different partner functions, then you supply the partner functions in a table associated with the business partner in the screening API. You must supply at least one partner function for a business partner. In Customizing, these external partner functions are mapped to internal partner functions. In the event of a watch list hit and an alert, then the descriptive text from each relevant internal partner function is added to the alert. Partner ID and master data identification: You can supply identification information for a business partner, as well as the ID of the partner in master data management. However, this information is for documentary purposes. In business transaction screening, each transaction and address are treated as "new". The API does not read data from master data management, nor does it access a business transaction that has already been submitted for screening and persisted. If a transaction is presented a second time, the new data simply overwrites the old transaction data and addresses in the BPS storage. Always resubmit a complete transaction, not just the deltas in the transaction. This design allows you to respond flexibly with your detection strategies to the attributes of a business transaction. Business partners in a more important business transaction can be subjected to more intensive screening, for example, even if the partners have been seen and cleared before. The model does not allow for assumptions that a certain business partner is already cleared, simply because the partner has already been screened in the context of another transaction. Access group: Lets you specify authorizations for accessing alerts. If an alert belongs to an access group (the name of which you specified in your screening request), then only investigators who have an authorization for the group can access the alert. 2.3 Business Transaction Screening: Process Flow The diagram below shows the processing flow in business transaction processing. The business transaction screening API offers all of the functionality shown in the "BPCM" frame. You must implement the call from the "Source System" frame to request business transaction screening. And you must implement the reaction to the results of screening in the "Source System". 10 P U B L I C Business Transaction Screening

11 A request for business transaction screening should come at the end of the process of creating the transaction. At the earliest, the request should come when the ID of the transaction has been finalized. You can transmit a screening request to SAP Business Partner Screening via RFC (function module BPCM_BUSINESS_TRANSACTION_CHK Enhanced Business Transaction Address Check in function group BPCM_ADDRESS_CHECK) or enterprise web service provider (BusinessTransactionCheck_Request_Sync_In Check Business Transaction). You can transmit single or multiple transactions with a request. The business partners who appear in a transaction are subjected to address screening in SAP Business Partner Screening. The system selects detection strategies for screening according to selection parameters. These include the detection object type, the risk level, the country in an address, and the country of the organizational unit. Any selection parameters that you add are also used in selecting strategies. If there are hits in watch lists, then an alert is created and each hit is recorded as an alert item. The information in an alert item includes the address that was screened, the matches from a watch list, the partner function, and other information, including any enrichment fields that you add to the investigation object type. In addition to address screening in real time, the system persists a business transaction with all of its business partners. This persisted transaction is subjected to delta address screening, as changes to watch lists become available. If you re-submit a business transaction, then it overwrites the persisted business transaction. There is no change management or versioning of persisted transactions, and transactions should always be resubmitted in full, not just as new or changed information. Alerts arising from delta screening are not Business Transaction Screening P U BL IC 11

12 automatically propagated to your business system. Rather, your business experts should check periodically in the SAP BPS system for new and changed alerts. The results of screening are returned to your calling system synchronously. If you have cleared the EV_INVESTIGATION_IN_BPCM parameter in function module BPCM_BUSINESS_TRANSACTION_CHK, then you can communicate the decision on each alert with function module BPCM_ALERT_DECISION_CHANGE to the SAP BPS system. Otherwise, investigation of an alert and the setting of the decision must be done in the BPS system. In the source system, you can take any required action as a result of screening alerts. You can, for example, block the transaction until an investigation has been completed and an decision on alerts has been made. 2.4 Implementing Business Transaction Screening This section briefly shows how to implement the RFC and web service interfaces for business transaction screening in SAP Business Partner Screening (BPS). RFC Implementation To implement business transaction checking with the RFC interface, you need only implement function module BPCM_BUSINESS_TRANSACTION_CHK (Enhanced Business Transaction Address Check) in your business transaction process. Add this function module to the process at the earliest when the ID of the business transaction has been finalized. (If you need screening earlier in the process, then submit the business transaction (with a temporary ID) in simulation mode. You receive screening results, but no alerts are created, nor is the business transaction saved in the SAP BPS system.) To implement business transaction screening, do the following: 1. Map your business transaction data to the BPCM_T_OD_BT table structure used in parameter IT_BUSINESS_TRANSACTIONS in function module BPCM_BUSINESS_TRANSACTION_CHK. 2. Call the function module at SAP BPS from your business system. If you are integrating an SAP business process, you can use RFC. In this case, you must define an RFC destination in your system that points to the SAP BPS system. Users who call the function module must have role SAP_BPCM_SYS_COM in the SAP BPS system. Since SAP BPS screens in real time, you can call the ABAP function module synchronously. If you are calling the function from a non-sap system or a non-abap system, then you can call the enterprise web service (see below). 3. You can now present the results to your business users at the calling system. Users can decide whether a hit the discovery of a business partner in a watch list is valid or should be ignored. 4. When the user has finished with step 3, you can set alert decisions in SAP BPS with the RFC function module BPCM_ALERT_DECISION_CHANGE, if you have cleared parameter IV_INVESTIGATION_IN_BPCM. For more information, see Sample Code and Usage Notes: BPCM_ALERT_DECISION_CHANGE Function Module in Implementing the Interface for Business Partner Master Data Screening [page 15]. 12 P U B L I C Business Transaction Screening

13 Sample Code and Usage Notes Here is sample code showing a call to BPCM_BUSINESS_TRANSACTION_CHK. Notes follow the example. * Do business transaction screening DATA: simulation_indicator TYPE fra_simulation_indicator VALUE ' ', investigation_in_bpcm TYPE bpcm_od_investigation_in_bpcm VALUE 'X', transactions TYPE bpcm_t_od_bt, check_results TYPE bpcm_t_od_bt_check_result, messages TYPE bpcm_s_od_message. CALL FUNCTION 'BPCM_BUSINESS_TRANSACTION_CHECK' DESTINATION 'SAP_BPS_SYSTEM' EXPORTING iv_simulation_indicator = simulation_indicator iv_investigation_in_bpcm = '' it_business_transaction = transactions IMPORTING ev_simulation_indicator = simulation_indicator ev_investigation_in_bpcm = investigation_in_bpcm et_person_check_result = check_results es_message = messages. Simulation Indicator IV_SIMULATION_INDICATOR By default, alerts are created in SAP Business Partner Screening if a business partner is found in a watch list. By setting the simulation indicator to 'X', you can suppress the creation of alerts. The function module still returns hits to you if alerts are suppressed. Simulation is recommended only for test and development operation. An exception: You can use simulated mode to test screen a transaction before it has received its final ID number. Investigation in BPCM IV_INVESTIGATION_IN_BPCM By default, alerts can be closed by users in SAP Business Partner Screening (IV_INVESTIGATION_IN_BPCM = 'X'). Clearing this parameter prevents manual change of alert status in SAP Business Partner Screening. In this case, you must report the results of the user decision on hits to the SAP Business Partner Screening system in order to close any alerts that have been created (BPCM_ALERT_DECISION_CHANGE). Mapping Business Partner Data to IT_BUSINESS_TRANSACTION Fill this table parameter with the data of the business transactions. There are separate substructures for business partners that are persons and for those that are organizations. For information about the data models and mapping, see Business Transaction Screening: Data Model [page 6]. ACCESS_GROUP Authorizations Optionally, you can use the ACCESS_GROUP parameter to restrict access to any alerts created by a BPCM_PARTNER_CHECK call. A user at SAP Business Partner Screening must be authorized for the ACCESS_GROUP value that you specify to access an alert. Results The ET_BUSINESS_TRANS_CHECK_RESULT export table returns any "hits", entries from watch lists that matched to a screened person or organization. The tables contain entries only for addresses of business partners for whom there were hits. The ALERT_INDICATOR field is also set if alerts were generated. An empty table means that the screened persons or organizations in a business transaction were not found in the watch lists that were applied. Messages Business Transaction Screening P U BL IC 13

14 Messages are returned from message class BPCM_ONL_DETECTION (transaction SE91). Business transactions that produce errors are not processed or persisted. Invalid transactions do not affect the processing of other, valid transactions in the same call. Web Service Provider Implementation As an alternative to the RFC interface, you can call the BusinessTransactionCheck_Request_Sync_In enterprise web service in package BPCM_SERVICE at the SAP BPS system. Point to point communication is enabled, so that no Process Integration (PI) system is needed as a hub. Input and output structures of the service are similar to those of the RFC API. Execution of address screening of business partners is identical to that of the RFC API, with the exception of internal web service specialties, such as the mapping of web parameters to internal data structures. For: Inbound mapping of the enterprise service repository input to the data structures used by the API (as described with respect to the RFC interface); and Outbound mapping from internal data structures to the ESR output the web service uses Business Add-In BPCM_BADI_SE_BT_DETECTION in enhancement spot BPCM_BADI_SE_DETECTION. For more information, see Creating and Configuring Service Providers and Service Consumers. 14 P U B L I C Business Transaction Screening

15 3 Implementing the Interface for Business Partner Master Data Screening SAP Business Partner Screening offers a programming interface (API) for performing business partner screening. This API makes it possible for you to use real-time address screening features for anti-corruption compliance and risk avoidance in SAP systems and non-sap systems. You can implement the interface using RFC function modules or an enterprise web services. The RFC API is used in SAP s own implementation of business partner screening for SAP Master Data Governance release 8.0 and 9.0 (). Alternatively, you can request screening of master data with the BusinessPartnerCheck_Request_In enterprise web service. This section provides help for both RFC and web service implementations of the API. Key Features of the API Business partner master data screening is used to check addresses of persons and organizations against screening lists and has these features: Access to address screening of business partners in real time. The speed of SAP HANA makes it possible to integrate business partner screening directly into your business processes. It is not necessary to screen business partners asynchronously. Delta address screening. Business partner data is retained at the address screening system. As screening lists are updated, business partner data can be checked against the changed information in the lists. (Alerts are not propagated automatically to your business system in this case). Two integration models for the API. At its simplest, you can implement only address screening (which comes with automatic inclusion of business partners in delta address screening). You need implement only one or two RFC function module calls, depending on the options that you use. If you wish to, you can also implement a more sophisticated integration model that adds management of business partner data in draft and active versions. This version management lets you mirror master data change and approval processes in your business system. Business partner data that is being created or edited is held as "draft" data in the address screening system. When the business partner data is approved or the change is cancelled in your business system, then you can propagate this action to this system. The data is saved as "active" data at approval or is deleted if a data change is cancelled. Compatibility: Access to address screening via an RFC interface or web services from SAP Business systems or via web services from non-sap systems. Usage Notes Business partner master data screening uses pre-configured sets of detection and investigation object types, one set each for screening persons and organizations. Persons and organizations submitted online for screening are persisted (permanently saved) in the system. This feature allows delta screening of business partners as screening lists change. Implementing the Interface for Business Partner Master Data Screening P U BL IC 15

16 The detection strategy used for the screening is determined by the system based on the data given in input to the service interface. (The parameters that derive the strategy are: ADDRESS_COUNTRY, ORG_UNIT_COUNTRY, BUSINESS_SYSTEM, and RISK_LEVEL). With business partner master data screening, an external application calls the address screening system via a remote function call (RFC). The caller of this function module can choose whether an alert investigation takes place in their calling system or in the system where the address screening is performed (default). In the former case, the alert cannot be changed in the address screening system but must be investigated and decided on in the calling system. Note Screening lists must be imported into the system before an address screening can take place. Comprehensive screening lists can be obtained from external providers. Address Screening Details Address screening is performed after the input data of the persons and organizations has been stored. The results of the screening are hits where the addresses of the input data match the entities of screening lists. Entities on screening lists can also be persons and organizations. A hit contains information about names and addresses of a screening lists entities, which matches a particular name and address of the input data. The hit contains a search score and the information, which indicates why a hit has been found, is highlighted. A hit also comprises references of the screening list entity to screening lists as well as a higher level list classification. If requested, the system will create an alert for the persons and organizations that have address screening hits. In this case the alert IDs are returned to the calling system. 3.1 Enabling Screening of Business Partner Master Data Before you can use the RFC API for business partner screening, you must ensure that configuration and customizing tasks have been done in SAP Business Partner Screening. The following tasks must be done: The address screening feature of SAP Business Partner Screening must be enabled. Business partner screening uses address screening. You can find information about enabling address screening in the Installation Guide of SAP Assurance and Compliance Software for SAP S/4HANA at bps_s4. You can also find information about address screening in the application help in the Help Portal. Customizing tasks must also be performed specifically for business partner screening in SAP Business Partner Screening. If your business system is an SAP system, then you can set up an RFC destination to the SAP Business Partner Screening system for calling the RFC API. You will also find information about specific customizing requirements in the online documentation of the RFC function modules in package BCPM_RFC in the SAP BPS system. Otherwise, you can use the BusinessPartnerCheck_Request_Sync_In enterprise web service to request screening of business partner master data. 16 P U B L I C Implementing the Interface for Business Partner Master Data Screening

17 Assign authorizations to RFC users in SAP Business Partner Screening. Such users must have the SAP_BPCM_SYS_COM role. 3.2 RFC Function Groups, Function Modules, and Parameters Function Modules The RFC version of the API is held in package BPCM_RFC, which you can access with the ABAP Workbench, transaction SE80, or with the Eclipse-based ABAP Development Tools. You will find online documentation on the function modules and parameters in your system. Function Group Function Module Use BPCM_ADDRESS_CHECK Function group for checking business partner master data. Optionally, you can also propagate final status changes in master data of business partners from the source business system to this system. BPCM_PARTNER_CHECK Enhanced Partner Address Check Use this function module to check business partner data against screening lists in SAP Business Partner Screening. The function module returns hits in screening lists to the source business system. The function module also saves the business partner data in your system so that delta address screening can be applied to it. In delta address screening, changes in screening lists are used for renewed screening of business partners. BPCM_PARTNER_CR_ACTIVATE Activate Business Partner Change Request Optionally, propagate the approval of creation or change of master data for a business partner from your source system to this system. The function module saves a "draft" version of the data as the "active" version in this system. Implementing the Interface for Business Partner Master Data Screening P U BL IC 17

18 Function Group Function Module Use BPCM_PARTNER_CR_ROLLBACK Roll Back Business Partner Change Request Optionally, propagate the cancellation of creation or change of master data for a business partner from the source system to this system. The function module deletes a draft version of the data in your address screening system. BPCM_ALERT_DECISION_CHANGE Use the function module in this function group to communicate decisions on address screening hits from the calling system to this system. BPCM_ALERT_DECISION_CHANGE Enhanced Partner Screening Alert Decision Change Propagate your decision on a business partner screening hit from the source system to this system. The function module closes any alerts created because of the screening hit and sets the decision information for each alert item in the alerts. If you accept a hit, then the relevant alert is closed as Confirmed. If you reject a hit, then the alert is closed with False Alarm. Parameters For business partner master data screening, the following parameters are used in the function module BPCM_PARTNER_CHECK: Technical Name Parameter Type Description IV_SIMULATION_INDICATOR Import (Optional) A simulation indicator that specifies if an alert is to be created in case of address hit. If set, then you receive messages on potential hits, but no alerts are created. The results of the screening are not persisted. 18 P U B L I C Implementing the Interface for Business Partner Master Data Screening

19 Technical Name Parameter Type Description IV_INVESTIGATION_IN_BPCM Import (Optional) A flag that specifies if the alert investigation is to take place in the calling system or in the system where the address screening takes place. If set, then you set the final status of alerts (confirmed or false alert, for example) in the SAP Business Partner Screening system. If not set, then you set the final status of alerts in the calling system. You should then communicate the alert decisions to the business partner screening system. IT_PERSON Import (Optional) Provides the person data for the address check. For detailed information, see the function module documentation (call transaction SE37 and enter BPCM_PARTNER_CHECK in the field Function Module. IT_ORGANIZATION Import (Optional) Provides the organization data for the address check. For detailed information, see the function module documentation (call transaction SE37 and enter BPCM_PARTNER_CHECK in the field Function Module. EV_SIMULATION_INDICATOR Export A copy of import parameter IV_SIMULATION_INDICATOR specifying whether an alert has been created in the case of an address hit. EV_INVESTIGATION_IN_BPCM Export A copy of import parameter IV_INVESTIGATION_IN_BPCM specifying if the alert investigation shall take place in the calling system or in the system where the address screening takes place. ET_PERSON_CHECK_RESULT Export Provides the results for the persons that have a hit in a screening list. For detailed information, see the function module documentation (call transaction SE37 and enter BPCM_PARTNER_CHECK in the field Function Module. Implementing the Interface for Business Partner Master Data Screening P U BL IC 19

20 Technical Name Parameter Type Description ET_ORGANIZATION_CHECK_RESULT Export Provides the results for the organizations that have a hit in a screening list. For detailed information, see the function module documentation (call transaction SE37 and enter BPCM_PARTNER_CHECK in the field Function Module. ES_MESSAGE Export This parameter returns three tables of messages, which represent errors, warnings, or information messages that are important for the caller of this RFC. For detailed information, see the function module documentation (call transaction SE37 and enter BPCM_PARTNER_CHECK in the field Function Module 3.3 Business Partner Screening: Implementation with RFC The RFC API for business partner master data screening offers two levels of implementation. This section describes the basic option: Submitting business partner data to SAP Business Partner Screening for screening Receiving information from SAP Business Partner Screening on whether any hits were found in watch lists Setting the final status of alerts as confirmed or rejected To implement this level of integration, you need to call only two RFC function modules from your application: BPCM_PARTNER_CHECK submits business partner data for screening against watch lists at SAP Business Partner Screening. BPCM_ALERT_DECISION_CHANGE communicates user decisions on hits against watch lists to SAP Business Partner Screening, so that alerts can be closed according to whether the hit is valid or is a false alarm. This section explains how to use these function modules; for details, see the online documentation of the function modules in your system. Implementing calls to these function modules enables not only synchronous name and address screening in real time in your application, it also enables delta address screening. The business partner data that you submit with BPCM_PARTNER_CHECK is persisted in SAP Business Partner Screening. As relevant watch lists are updated, the business partner is automatically included in delta address screening. In delta address screening, the changes in a relevant list are used to look for new hits against business partners. New alerts from delta screening are not automatically reported to your business system. 20 P U B L I C Implementing the Interface for Business Partner Master Data Screening

21 Doing Screening and Returning Decisions on Screening Hits: Overview Here in overview is the process for using the BPCM_PARTNER_CHECK and BPCM_ALERT_DECISION_CHANGE function modules to do business partner screening, present results to the requesting user, and return the user's decisions to SAP Business Partner Screening: 1. Map your business partner data to the person or organization structures required by SAP Business Partner Screening and exposed in function module BPCM_PARTNER_CHECK. 2. Call the function module at SAP Business Partner Screening. If you are integrating an SAP business process, you can use RFC. In this case, you must define an RFC destination in your system that points to the SAP Business Partner Screening system. Users who call the function module must have role SAP_BPCM_SYS_COM in the SAP Business Partner Screening system. If you are calling the function from a non-sap system or a non-abap system, then you can, for example, expose the BPCM_RFC function modules as enterprise web services at the SAP Business Partner Screening system. For more information, search for example for ABAP Web Service Wizard. 3. Present the results to your business users at the calling system. Users must decide whether a hit the discovery of a business partner in a watch list is valid or should be ignored. 4. When the user has finished with step 3, you must report the decisions to SAP Business Partner Screening with the RFC function module BPCM_ALERT_DECISION_CHANGE, unless you have suppressed alert generation with the IV_SIMULATION_INDICATOR parameter. Sample Code and Usage Notes: BPCM_PARTNER_CHECK Function Module Here is sample code showing a call to BPCM_PARTNER_CHECK. Notes follow the example. * Do business partner screening DATA: simulation_indicator TYPE fra_simulation_indicator VALUE ' ', investigation_in_bpcm TYPE bpcm_od_investigation_in_bpcm VALUE 'X', persons TYPE bpcm_t_od_person, person_check_result TYPE bpcm_t_od_person_check_result, organizations TYPE bpcm_t_od_organization, organization_check_result TYPE bpcm_t_od_org_check_result, change_request TYPE bpcm_change_request, messages TYPE bpcm_s_od_message. CALL FUNCTION 'BPCM_PARTNER_CHECK' DESTINATION 'SAP_BPS_SYSTEM' EXPORTING iv_simulation_indicator = simulation_indicator iv_investigation_in_bpcm = 'X' it_person = persons it_organization = organizations iv_change_request = change_request IMPORTING ev_simulation_indicator = simulation_indicator ev_investigation_in_bpcm = investigation_in_bpcm et_person_check_result = person_check_result et_organization_check_result = organization_check_result es_message = messages. Simulation Indicator IV_SIMULATION_INDICATOR By default, alerts are created in SAP Business Partner Screening if a business partner is found in a watch list. By setting the simulation indicator to 'X', you can suppress the creation of alerts. The function module still returns hits to you if alerts are suppressed. Simulation is recommended only for test and development operation. Implementing the Interface for Business Partner Master Data Screening P U BL IC 21

22 Investigation in BPCM IV_INVESTIGATION_IN_BPCM By default, alerts can be closed by users in SAP Business Partner Screening (IV_INVESTIGATION_IN_BPCM = 'X'). Clearing this parameter prevents manual change of alert status in SAP Business Partner Screening. In any case, you must report the results of the user decision on hits to the SAP Business Partner Screening system in order to close any alerts that have been created (BPCM_ALERT_DECISION_CHANGE). Mapping Business Partner Data to IT_PERSON or IT_ORGANIZATION Fill these tables with the data of the business partners that are to be screened. Please note the following: SAP Business Partner Screening distinguishes between business partners who are persons and those that are organizations. You can supply more than one person and/or organization per call with the function module. A person or organization may also have more than one address supplied in field ADDRESS in the IT_PERSON or IT_ORGANIZATION parameter. If there is more than one address, then the person or organization is presented for screening multiple times, once for each individual address. A person is identified by the key fields BUSINESS_SYSTEM, PERSON_TYPE, and PERSON (ID number). See the online help for parameter IT_PERSON for more information. An organization is identified by the key fields BUSINESS_SYSTEM, ORGANIZATION_TYPE, and ORGANIZATION (ID number). See the online help for parameter IT_ORGANIZATION for more information. An address of a person or organization is identified by the key fields ADDRESS_ID, ADDRESS_VARIANT, and VALID_FROM, where ADDRESS_VARIANT is a type of address from the calling system, such as "place of birth" or "current residence". ADDRESS_ID, like the PERSON and ORGANIZATION ID fields, must be filled with leading zeroes if the ID value does not fill the field. The VALID_FROM field constrains the validity only of the address with which it is associated, as it is not possible to construct from-to durations across different address variants and ranges within variants are not created. Specifications for Detection Strategy Selection The address screening feature of SAP Business Partner Screening determines automatically which detection strategies should be applied to a screening request from BPCM_PARTNER_CHECK. In order to select detection strategies, you must supply SAP Business Partner Screening with a BUSINESS_SYSTEM and a COUNTRY_ISO in the ADDRESS entry. Optionally, you can also supply a RISK_LEVEL from the Customizing in SAP Business Partner Screening, and one or more organizational unit specifications in the ORGUNIT table parameter. The ORGUNIT values also must be customized in SAP Business Partner Screening. If you provide an ORGUNIT, then both fields must be filled. IV_CHANGE_REQUEST, PARTNER_GUID, and Version Management The IV_CHANGE_REQUEST field is for the ID number of a change request for creating or changing the master data of a business partner. Leave this field empty if you simply want to screen a business partner and do not use any master data management functions in your source system. If you supply a value for the IV_CHANGE_REQUEST parameter, then SAP Business Partner Screening saves your business partner data in draft form. The system assumes that you will separately report the final status of the change request when it is approved or cancelled. The draft information will then be either saved in status "active" or is deleted. For more information, see Version Management of Business Partner Master Data: Implementation with RFC [page 24]. ACCESS_GROUP Authorizations 22 P U B L I C Implementing the Interface for Business Partner Master Data Screening

23 Optionally, you can use the ACCESS_GROUP parameter to restrict access to any alerts created by a BPCM_PARTNER_CHECK call. A user at SAP Business Partner Screening must be authorized for the ACCESS_GROUP value that you specify to access an alert. Results The ET_PERSON_CHECK_RESULT and ET_ORGANIZATION_CHECK_RESULT export tables return any "hits", entries from watch lists that matched to a screened person or organization. The tables contain entries only for business partners for whom there were hits. An empty table means that the screened persons or organizations were not found in the watch lists that were applied. Business partners are screened separately for each address that they may have. If a business partner has more than one address, then there may be more than one entry for the business partner in the results table. The entry is identified by the PERSON or ORGANIZATION ID number. The address is identified by the address key fields, ADDRESS_ID, ADDRESS_VARIANT, and VALID_FROM. To present a hit with the business partner's name and the address that triggered the hit, you must read these values from the input parameter tables using the key fields that have been returned. For more information, see the online documentation of the *_CHECK_RESULT tables. Messages Messages are returned from message class BPCM_ONL_DETECTION (transaction SE91). Sample Code and Usage Notes: BPCM_ALERT_DECISION_CHANGE Function Module Here is sample code showing a call to BPCM_ALERT_DECISION_CHANGE. Notes follow the example. * Present screening results to users and collect decisions... * Return user decisions on hits from screening results to * SAP Business Partner Screening to close alerts DATA: alert_decision TYPE bpcm_t_alert_decision, result TYPE bpcm_s_alert_decision_result. CALL FUNCTION 'BPCM_ALERT_DECISION_CHANGE' DESTINATION 'SAP_FRA_SYSTEM' EXPORTING it_alert_decision = alert_decision IMPORTING es_result = result. Closing Alerts: IT_ALERT_DECISION To close alerts, you need the ALERT_ID and ALERT_ITEM_ID fields from the *_CHECK_RESULT tables returned by the BPCM_PARTNER_CHECK function module, above. ALERT_ID is found in the ALERT_DETAILS structure. ALERT_ITEM_ID is found in the ALERT_ITEM_DETAILS structure in the *_CHECK_RESULT tables. Insert the contents of these fields in the IT_ALERT_DECISION parameter of BPCM_ALERT_DECISION_CHANGE. Note the ALERT_ITEM_ID field from *_CHECK_RESULT maps to the ALERT_ITEM_NUMBER field in IT_ALERT_DECISION. Fill the ALERT_CLOSE_REASON_CODE, ALERT_DECISION_SUMMARY, and ALERT_COMPLETION_STATUS_CODE fields according to the decision made by the user. For more information about these fields, see the online help of the data elements of the fields. Only the ALERT_COMPLETION_STATUS_CODE field must be filled. The Implementing the Interface for Business Partner Master Data Screening P U BL IC 23

24 ALERT_CLOSE_REASON_CODE is read from the Customizing activity Define Default Reasons for Closing Alerts (transaction SPRO) if no value is provided. A text in the ALERT_DECISION_SUMMARY field is required. Alert Closure Results: ES_RESULT The ES_RESULT structure reports on the closure of the alerts in SAP Business Partner Screening, including error messages, such as missing ACCESS_GROUP or other authorizations. 3.4 Version Management of Business Partner Master Data: Implementation with RFC The RFC API for business partner master data screening offers two levels of implementation. This section describes the supplemental option: Propagating changes in the final status of the master data of business partners to SAP Business Partner Screening. You need to implement this part of the API only if you are creating, changing and managing the master data of your business partners in your business system. This part of the API is not needed if you just want to screen business partners (see also Implementing the Interface for Business Partner Master Data Screening [page 15]). To implement this level of integration, you need to add calls to two additional RFC function modules to your implementation of business partner screening. These are as follows: BPCM_PARTNER_CR_ACTIVATE (Activate Business Partner Change Request) propagates approval of a change request for master data to SAP Business Partner Screening. BPCM_PARTNER_CR_ROLLBACK BPCM (Rollback Business Partner Change Request) propagates cancellation of a change request to SAP Business Partner Screening. This section explains how to use these function modules; for details, see the online documentation of the function modules in your system. Calls to these function modules should be implemented synchronously. There is no need to communicate decisions on change requests for business partner master data to SAP Business Partner Screening asynchronously. Version Management Process At screening, business partner data is saved in the SAP Business Partner Screening system so that it can be included in delta address screening. In simple business partner screening, business partner data is saved in status active. The API extension described in this section lets you control a versioning system for the business partner data in SAP Business Partner Screening. If you supply a change request when you submit a business partner for screening, then the API assumes that you wish to use the version management part of the API. In this case, the business partner data is stored at SAP Business Partner Screening in status draft. The draft version does not affect an active version of the business partner data that may already have been saved in the SAP Business Partner Screening system. (However, the draft version uses the active version as a starting point and updates the data from the active version. This ensures that the business partner data is complete if not all of the data is provided with a change request.) Synchronous screening is performed against the draft version of the business partner data; any resulting alerts can be found by way of the change request ID that you submitted. 24 P U B L I C Implementing the Interface for Business Partner Master Data Screening

25 When a final decision has been made on the change request for the business partner data, then you use the function modules of this part of the API to communicate the decision to SAP Business Partner Screening: If the change to the master data of the business partner has been approved, then you call BPCM_PARTNER_CR_ACTIVATE. At the SAP Business Partner Screening system, the function module changes the status of the business partner data from draft to active. Any active version that was already present is overwritten. Any alerts remain in their current state and continue to be associated with the business partner. Especially for the SAP integration of SAP Master Data Governance with SAP Business Partner Screening, the final PARTNER_ID of the master data also is recorded in the data in SAP Business Partner Screening. Supplying the parameter for this operation, IT_PARTNER_IDS, is optional. You do not need to use this part of the API if it does not apply to you. If you need to use this feature, then you must provide a PARTNER_GUID with the call to BPCM_PARTNER_CHECK. The partner GUID is required for finding the business partner data in SAP Business Partner Screening after the change from a temporary to a permanent partner ID. If the change to the master data of the business partner has been cancelled (the final status is completely withdrawn ), then you call BPCM_PARTNER_CR_ROLLBACK. At the SAP Business Partner Screening system, the function module deletes the draft version of the business partner data. Any alerts generated for the draft version of the data are closed automatically. Any active version of the data is unaffected. This part of the RFC API lets you keep the business partner data in SAP Business Partner Screening up to date with the final status of the data in your business system. It also ensures that alerts are closed, if they were created for business partner data that has been withdrawn. Sample Code and Usage Notes: * Communicate the final status of master data change requests * for business partner data to SAP Business Partner Screening DATA: activated_persons TYPE bpcm_t_od_person_keys, rolledback_persons TYPE bpcm_t_od_person_keys, activated_organizations TYPE bpcm_t_od_organization_keys, rolledback_organizations TYPE bpcm_t_od_organization_keys, partner_ids TYPE bpcm_t_partner_id_with_addr, business_system TYPE fra_business_system VALUE 'BUS', change_request_final_status TYPE c VALUE 'A'. IF change_request_final_status = 'A'. "Accepted CALL FUNCTION 'BPCM_PARTNER_CR_ACTIVATE' DESTINATION 'SAP_FRA_SYSTEM' EXPORTING iv_business_system = business_system iv_change_request = change_request it_partner_ids = partner_ids IMPORTING et_activated_persons = activated_persons et_activated_organizations = activated_organizations es_message = messages. ELSEIF change_request_final_status = 'C'. "Cancelled CALL FUNCTION 'BPCM_PARTNER_CR_ROLLBACK' DESTINATION 'SAP_BPS_SYSTEM' EXPORTING iv_business_system = business_system iv_change_request = change_request IMPORTING et_rolledback_persons = rolledback_persons et_rolledback_organizations = rolledback_organizations es_message = messages. ENDIF. Implementing the Interface for Business Partner Master Data Screening P U BL IC 25

26 Identifying the Business Partner To identify the business partner master data in the SAP Business Partner Screening system, you must provide the name of your source system in SAP Business Partner Screening Customizing, in IV_BUSINESS_SYSTEM. You must also provide the change request ID that you submitted with BPCM_PARTNER_CHECK. The activation affects all t business partner names and addresses that were submitted with the change request ID. All are saved as "active" information. Optionally, you can provide final partner IDs in IT_PARTNER_ID. This is required only if you must adjust the final ID, as is the case in the integration of SAP Master Data Governance with SAP Business Partner Screening for business partner screening. Results The API returns the business partner data that was affected by the change approval or cancellation. BPCM_PARTNER_CR_ROLLBACK closes all alerts associated with the change request ID. The final status of the alerts is not investigated. 3.5 Business Partner Screening: Implementation with Web Service As an alternative to the RFC interface, you can request business partner screening by calling the BusinessPartnerCheck_Request_Sync_In enterprise web service at the SAP Business Partner Screening system. Point to point communication is enabled, so that no Process Integration (PI) system is needed as a hub. You can find the service in package BPCM_SERVICE. Input and output structures of the service are similar to those of the RFC API (for more information, see RFC Function Groups, Function Modules, and Parameters [page 17]). Execution of address screening of business partners is identical to that of the RFC API, with the exception of internal web service specialties, such as the mapping of web parameters to internal data structures. For: Inbound mapping of the enterprise service repository input to the data structures used by the API (as described with respect to the RFC interface); and Outbound mapping from internal data structures to the ESR output the web service uses Business Add-In BPCM_BADI_SE_BP_DETECTION in enhancement spot BPCM_BADI_SE_DETECTION. Since mapping is installation specific, there are no standard implementations for the BAdI. For more information, see Creating and Configuring Service Providers and Service Consumers. 26 P U B L I C Implementing the Interface for Business Partner Master Data Screening

27 4 Adding Customer Fields to Screening APIs SAP Business Partner Screening offers easy-to-use support for adding customer fields to the programming APIs for business partner screening (see Implementing the Interface for Business Partner Master Data Screening [page 15]) and for business transaction screening (see Business Transaction Screening [page 4]). You can add fields to both the RFC programming interfaces and the counterpart of business transaction screening in enterprise services. The first step in any case is to add customer fields to the RFC programming interfaces; this is a prerequisite for adding fields to web messages. Adding fields to the RFC APIs modifies the internal structures of the APIs. Adding fields to the messages modifies the external message formats and requires mapping to the internal structures. The procedures for adding fields to the RFC programming interface and to enterprise service interfaces are different and are described separately in the following sections. Adding Customer Fields to the RFC APIs To add customer fields to the RFC APIs, you need only do the following customizing tasks: Add the fields to the field catalog in the Customizing of SAP Business Partner Screening. Identify the fields as enrichment fields or selection fields in the Customizing for SAP Business Partner Screening. SAP Business Partner Screening automatically takes care of adding your fields to the internal data structure and generating the necessary local SAP HANA views. For instructions, see Adding Customer Fields to the RFC APIs and Internal Structures [page 28]. Adding Customer Fields to the Enterprise Web Service for Business Transaction Screening To add customer fields to a web message, you must first add corresponding fields to the RFC API for business transaction screening, as described above. Then you must do the following tasks: Enhance the standard web service provider BusinessTransactionCheck_Request_Sync_In in package BPCM_SERVICE with your new fields in the Enterprise Service Repository and Enterprise Service Builder (transaction SPROXY). Generate proxy objects for the enhanced structure with transaction SPROXY. Map the new fields in the web message to the internal RFC data structures by implementing the BAdI in customizing activity BAdI: Enhance Detection Service for Business Transaction Screening in the Customizing of SAP Business Partner Screening. Adding Customer Fields to Screening APIs P U BL IC 27

28 For instructions, see Adding Customer Fields to the Web Service for Business Transaction Screening [page 32]. 4.1 Adding Customer Fields to the RFC APIs and Internal Structures This section explains how to add your own fields to the internal data structures and RFC interfaces of these screening interfaces: Business partner screening (see Implementing the Interface for Business Partner Master Data Screening [page 15]) Business transaction screening (see Business Transaction Screening [page 4]) Adding fields to this RFC API is a prerequisite for adding fields to the web service API for business transaction screening (see Adding Customer Fields to the Web Service for Business Transaction Screening [page 32].) Adding Your Own Field and Assigning It to an Object Type Do the following: 1. In your SAP Business Partner Screening system and client, start customizing activity Define Source Domains for Screening. Figure 4: Customizing Activities for Adding Your Own Fields. 2. Mark a source domain such as the standard domain BPCM. Then double click Customer Fields to add your new fields to the field catalog of SAP Business Partner Screening. 28 P U B L I C Adding Customer Fields to Screening APIs

29 Figure 5: Opening the Customer Fields List. Note that you should use only a single Source Domain for all SAP and Customer fields in the field catalog. We recommend using the standard BPCM source domain. 3. For each field that you wish to add, click New Entries and fill out the New Entries dialog. Only the Field, Description, and Data Type fields are required. You can add fields of any data type. Figure 6: Dialog for Defining a New Field. 4. Now assign your new fields to investigation and detection object types. Start the Define Investigation and Detection Object Types for Screening customizing activity (shown above in step 1). You can define a field as an enrichment field by assigning it to an investigation object type. An enrichment field is automatically added to the information available in a screening alert, so you can use your field to extend an alert. Defining a field as an enrichment field adds it to the top-level enhancement include in the APIs, either the data structure belonging to BPCM_PERSON, include BPCM_INCL_EEW_PERSON, or BPCM_ORG (business partner screening), include BPCM_INCL_EEW_ORG, or the top-level data structure of a transaction type, such as BPCM_PO (business transaction screening), include BPCM_INCL_EEW_BT. You can define a field as a selection field by assigning it to a detection object type. A selection field can be used to help choose the detection strategies to run against a particular business partner or business transaction, so you can use your fields to influence how strategies are selected. In business partner screening, defining a field as a selection field adds it to the enhancement includes in the subordinate address data structures of the partner checking API, either the data structure belonging to BPCM_PERSA or that of BPCM_ORGA. In business transaction checking, all fields are added to an enhancement include in the top-level data structure. But all fields may be used as selection or enrichment fields. To make the field assignment, double click Investigation Object Type or Detection Object Type, select your object, and double click Customer Enrichment Fields or Customer Selection Fields. For more help, see the online customizing documentation of the activity. Adding Customer Fields to Screening APIs P U BL IC 29

30 Figure 7: Defining a Field as an Enrichment or Selection Field. Result: Your new fields are ready for use in RFC requests for screening. The system automatically adds the fields to the extend structures for customer use. The change becomes effective (the field is actually added) the next time that the affected object type is used. The system also automatically generates the local SAP HANA objects needed for using the fields. Review the changes that you have made and verify that all objects have been generated successfully by using the monitor transaction that is described in the next section. If you are extending the web service interface for business transaction screening, you can now add your new fields to the service. See Adding Customer Fields to the Web Service for Business Transaction Screening [page 32]. Viewing SAP and Customer Fields Assignments SAP Business Partner Screening automatically does the activation necessary for you to use your new fields. But transaction BPCM_GM_BO offers a fast and convenient way for you to see SAP and customer enrichment and selection field assignments and the status of generation. You can also generate changes to enhancement include structures and SAP HANA views manually, as a supplement to the automatic system generation. 30 P U B L I C Adding Customer Fields to Screening APIs

31 Figure 8: Menu Path to Transaction BPCM_GM_BO in SAP Menu. The panels in the transaction screen offer the following information: Panel Information Customer Fields System Status and message log Offers lists of all enrichment and selection fields, respectively, that have been defined for investigation and detection objects of SAP Business Partner Screening. Shows the current status of generation of investigation and detection object types. Open an object to see the complete sets of SAP and customer enrichment and selection fields. A double-click on an object displays the message log of the most recent generation of the object. Adding Customer Fields to Screening APIs P U BL IC 31

32 Deleting Fields If you delete a field after you have added it, then it is removed automatically from SAP HANA objects, but it is not deleted from the extension includes to which it has been added. Deleting a customer field from the extension includes is a manual task. Caution Fields cannot be deleted from the includes automatically because of the risk of data loss. If you have been storing data that uses the field that is to be deleted, then deleting the field will make the data unusable. 4.2 Adding Customer Fields to the Web Service for Business Transaction Screening This section explains how to add your own fields to the web service interface for business transaction screening. For more information about this API, see see Business Transaction Screening [page 4]. Prerequisite: You must add your new fields to the internal data structures used by business transaction screening, as shown in Adding Customer Fields to the RFC APIs and Internal Structures [page 28]. The procedure for adding fields to the enterprise service interface consists of two main tasks: 1. Enhancement of the enterprise service provider with your new fields and generation of the required proxy objects. 2. Implementation of a BAdI (Business Add-In) for mapping from the web service message to internal data structures. After you have completed these tasks, then your enhanced web service is ready to use. 1. Adding your own fields as an enhancement to the standard service for business transaction screening: BusinessTransactionCheck_Request_Sync_In in package BPCM_SERVICE. 2. Generating proxy objects for the enhanced service in transaction SPROXY. 3. Implementing the BAdI BPCM_BADI_SE_BT_DETECTION of enhancement spot BPCM_BADI_SE_DETECTION. This BAdI maps from the fields in the web service message to the corresponding fields in the internal data structures. (You added fields to the internal data structures as a prerequisite to enhancing the web service). You can maintain the BAdI in the customizing activity BAdI: Enhance Detection Service for Business Transaction Screening. Extending the Web Service Provider and Generating Proxy Objects The implementation work that you need to do in the Enterprise Services Repository and Enterprise Services Builder breaks down into these two tasks: 1. Adding your own fields as an enhancement to the standard service for business transaction screening: BusinessTransactionCheck_Request_Sync_In in package BPCM_SERVICE. 32 P U B L I C Adding Customer Fields to Screening APIs

33 You can add fields both to the inbound and outbound messages of the service. Note You will have to fill new fields in the outbound message yourself. Since the output structure of the internal API used by the service cannot be extended, you must fill any new output fields from the standard output of the API, for example, by calculating with the standard output. 2. Generating proxy objects for the enhanced service in transaction SPROXY. You can find how-to instructions for doing these tasks in the Enterprise Services Enhancement Guide. You can find this guide on the SAP Community at uuid/c0bb b2-2a10-ed8f-c9af69942e5d?quicklink=index&overridelayout=true& Implementing the Mapping BAdI Implementing the BAdI BPCM_BADI_SE_BT_DETECTION of enhancement spot BPCM_BADI_SE_DETECTION. This BAdI maps from the fields in the web service message to the corresponding fields in the internal data structures. (You added fields to the internal data structures as a prerequisite to enhancing the web service). You can maintain the BAdI in the customizing activity BAdI: Enhance Detection Service for Business Transaction Screening. In the BAdI, you need only implement the INBOUND_PROCESSING method, as customer fields are not returned. Figure 9: Implementing the BAdI INBOUND_PROCESSING Method. The INBOUND_PROCESSING method receives the inbound message fields in input/output parameter IS_BT_CHECK_REQUEST. You need to map your new fields in IS_BT_CHECK_REQUEST to the new internal fields that you have defined in CS_API_INPUT. Adding Customer Fields to Screening APIs P U BL IC 33

34 If no conversion is needed, then the mapping can be as simple as this sample code, which would map only the first business transaction: Figure 10: Sample Code for the INBOUND_PROCESSING Method. 34 P U B L I C Adding Customer Fields to Screening APIs

35 5 Message Translation and Localized Formatting The application provides capabilities for globalizing message texts. That is, you can output message texts in the language of the current user. And you can apply localized formats appropriate for the current user to message variables that contain information such as numbers, amounts, or dates and times. The messages that can profit from these globalization capabilities include the following: Message texts created in the Execution or Additional Information procedures of SQLScript detection methods. These messages explain detection results and are displayed to users in alert details. Using the message globalization capability in detection methods requires that you provide additional values for fields in the ET_TEXT output parameter. Both the Execution and Additional Information procedures can provide messages. Generally, however, messages are issued only from the Additional Information procedure, in which case setting messages from the Execution procedure is optional. Functional Overview The application provides for translatability of the messages listed above by allowing detection methods to identify a T100 message for each type of message that is to be returned. The central infrastructure in AS ABAP sees to it that the referenced T100 messages are displayed to each user in the language of the user, provided that a translation of the message in the required language is available in the system. Otherwise, standard AS ABAP fallback mechanisms for message display come into play. Localized formatting of amounts, dates and times, and numbers is provided by allowing you to reference a field defined in Customizing activity Define Source Domain and Field Settings as the template for formatting. The Execution and Additional Information procedures of a detection method specify T100 messages and field settings as formatting templates in their ET_TEXT output parameters. In SAP Business Integrity Screening the Procedures Wizard and the Test Procedure for Mass Detection transactions automatically include the message parameters in ET_TEXT. During the generation of detection method wrappers and strategy procedures the signatures of the rule procedures are read. If the new fields are not included in the output parameter ET_TEXT, then the detection method wrapper adds them. So in the end all generated wrappers have the same interface and can be used in one and the same strategy. Regeneration of methods is automatically provided as part of the Upgrade procedure. You can continue simply to provide a fixed text to ET_TEXT-TEXT instead of using globalized messages, so that you do not need to change the implementation of existing views and procedures. Example A detection method that uses the new translation and localization capabilities specifies the T100 message and fields for formatting in new fields in the ET_TEXT output parameter. Assume that the ET_TEXT output looks like this: MSGID = 'MY_MSG_CLASS' MSGNO = '001' MSGV1 = '1500' MSGV1_FC = 'CURRENCY_VALUE' Message Translation and Localized Formatting P U BL IC 35

36 MSGV1_SD = 'SOURCE_DOMAIN_1' MSGV2 = 'EUR' MSGV2_FC = 'CURRENCY' MSGV2_SD = 'SOURCE_DOMAIN_1' The MSGID and MSGNO parameters identify the T100 message that will be presented to users. (For more information, see transaction SE91). The T100 message definition includes two named variables, for which the values 1500 and EUR are provided. These values will be formatted for insertion into the message according to the properties of the fields CURRENCY_VALUE and CURRENCY in the Customizing for source domain SOURCE_DOMAIN_1. More Information 36 P U B L I C Message Translation and Localized Formatting

37 6 Enhancing the User Interface You can enhance the user interfaces of your application in several ways. You can add new apps and tiles to your application. You can extend some of the standard SAP Fiori apps. And you can tailor the Network Analysis section of the Manage Alerts app for displaying the data with which you want to work. Adding SAP Fiori Apps and Tiles to SAP Fiori Launchpad SAP Fiori apps are displayed on the home screen as tiles. You can add apps and expose them as tiles to provide your users with new functions. For more information, see Creating Additional Apps and Tiles for the SAP Fiori Launchpad [page 38]. Note SAP Fiori extensibility resources: The All Things SAP Fiori landing page at this URL in the SAP Community Network (SCN): scn.sap.com/docs/doc Extending UI at SAP Fiori Extensibility collaborative document in SCN: DOC and View Extension in the documentation of User Interface Add-On for SAP NetWeaver on the SAP Help Portal ( 40/3c050da4ae4566b6aafec2bc590389/content.htm ) Extending OData at the SAP Fiori - OData/Gateway collaborative document in SCN: scn.sap.com/docs/doc Extending the Manage Alerts App You can extend Manage Alerts, the new workplace for investigating and closing alerts, with new fields and new tools. For more information, see Extending the Manage Alerts App [page 38]. Tailoring the Network Analysis Tool The network analysis tool is a powerful way to analyze relationships between entities through visual display. For example, you could display the network of business partners and orders involved in a set of questionable purchases. For more information about equipping the tool for the network displays that you need, see Extending the Network Analysis [page 49]. Enhancing the User Interface P U BL IC 37

38 6.1 Creating Additional Apps and Tiles for the SAP Fiori Launchpad You can add your own tiles and apps to the SAP Fiori launchpad. To do so, open the SAP Fiori Launchpad Designer, and do the following: 1. In your back-end system, log on to the client of your solution and open the Customizing by entering transaction FRA_IMG. 2. Open Customizing activity SAP Fiori Launchpad Designer (Current Client). The SAP Fiori Launchpad Designer opens to the catalogs and groups that are available. You can add new tiles and apps that you create to the catalogs and groups. See the documentation cited in the next paragraphs. To create a new SAP Fiori app, use the SAP Web IDE. For more information, see for example Getting Started with SAP Web IDE. To add an app to the SAP Fiori launchpad as a new tile, use the SAP Fiori Launchpad Designer. For more information, see Using the Launchpad Designer. As you add apps and tiles to the SAP Fiori Launchpad, we recommend that you follow the best practices described in Best Practices for Setting Up Content in User Interface Add-On 2.0 for SAP NetWeaver. 6.2 Extending the Manage Alerts App The Manage Alerts app is intended to be the workplace for investigators. With this app, investigators can track and document their work on alerts. This section explains how you can extend Manage Apps: Adding alert fields You can provide additional information to your investigators by enhancing alerts in the Manage Alerts app. For more information, see Adding Customer Fields to Alerts in Manage Alerts [page 39]. Adding UI fields You can add fields to the user interface of Managed Alerts and Alert Details. For more information, see Adding Fields to the Manage Alerts App [page 46]. Adding new sections A SAP Fiori section is a tool or workspace for alert investigators in the alert details section of Manage Alerts. You can add SAP Fiori sections to the Alert Details in Manage Alerts to provide your users with specialized tools for investigating and closing alerts. For more information, see Adding SAPUI5 Component-Based Sections to Manage Alerts [page 42]. Plugging in and executing your own code in Manage Alerts with the controller hook The Manage Alerts controller offers a controller hook. This lets you override a fixed function with your own code, executed at "edit alert". Practical uses might include adding attributes to the alert details, or hiding SAP standard alert attributes that you do not wish to use. See. 38 P U B L I C Enhancing the User Interface

39 6.2.1 Adding Customer Fields to Alerts in Manage Alerts This section explains how to add your own fields to the Manage Alerts app. Adding Customer Fields to the FRA_ALERT Business Object The first step in adding a customer field to alerts in Manage Alerts is to extend the FRA_ALERT business object. If you are migrating fields that you have already added, you can skip this step; it is already done. Do the following: 1. Start transaction BOBF and open the FRA_ALERT business process object. 2. Open the ROOT node structure and double-click to navigate to the edit screen of the Extension Include, INCL_EEW_FRA_BO_ALERT_ROOT. Add the new field to this structure, save, and activate. Adding a field to the FRA_ALERT object extends the FRA_D_ALERT_ROOT table. For more information, see also Adding Customer-Defined Fields to Business Objects [page 40]. Extending CDS Views for Alerts Once your new field has been added to the FRA_D_ALERT_ROOT table, you can modify the CDS views that read alerts. You do this by modifying two special CDS views that extend the operational views. Use ABAP Development Tools to modify two extension views in the sequence shown below. Add only the new fields to the extension views, no other code. FRA_CV_AlertRoot_ExtensionIncl FRA_CV_AlertRoot Code for FRA_CV_AlertRootExtensionIncl Sample code for adding a field called zzextension_field to the first extension view looks like this: Figure 11: Code for FRA_CV_AlertRootExtensionIncl. RootExtension is required. The field name is determined by your addition to the extension include of the FRA_ALERT business object. The sqlviewappendname is again yours to choose. Code for FRA_CV_AlertRoot Enhancing the User Interface P U BL IC 39

40 Sample code for adding a field called zzextension_field to the second extension view looks like this: Figure 12: Code for FRA_CV_AlertRoot. RootExtension is required. The field name is determined by your addition to the extension include of the FRA_ALERT business object. The sqlviewappendname is again yours to choose. Flushing the OData Cache and Displaying the New Field After the two views shown above have been activated, you must clear the OData cache. You do this by running the following customizing activity: SAP NetWeaver SAP Gateway OData Channel Administration Cache Settings Metadata Clear Cache. Once the cache has been flushed, the field that you have added is automatically made available in the OData representation of the Alert Root. Your users can include the field in the alert list by selecting the new field in the alert personalization. The display might look something like this, where Checkpoint Med is the name of the new field. Users can access personalization services by way of the button highlighted in yellow. The figure below shows a new field, Checkpoint Med, in the list of alerts. Users must select the field for display in the personalization services, which are accessible by way of the button marked in yellow. Figure 13: New Alert Field Displayed Adding Customer-Defined Fields to Business Objects The data models of business objects are predefined. However, you can extend the data models of the business objects by using predefined extension includes. You can add customer-defined fields to alerts, detection methods, personal settings, and detection strategies. 40 P U B L I C Enhancing the User Interface