Introduction

Business Entity Recognition locates, classifies, and extracts named entities from unstructured text. Any given type of named entities can be detected and classified into categories. You can use pre-trained machine learning models to detect and highlight business entities that belong to predefined categories. Additionally, own custom machine learning models can be created to detect and highlight any business entity in unstructured texts.  

Often, our customers receive notifications such as payment advises via emails. As the next step towards automatic document processing, SAP now offers an integration package via SAP Cloud Integration to automatically receive and process text from emails: 

Figure 01: Use Case 

• The email body is extracted as free text and sent to Business Entity Recognition​ 
• Business Entity Recognition extracts business entities 
• An email with the extracted data is sent back to the original sender​

This blog post shows, how you can integrate your email account into this pre-defined integration flow for automatically process messages in Business Entity Recognition, thus automatically receive the structured payload for an end-to-end service or business-process integration. 

Setting up Business Entity Recognition

To be able to use Business Entity Recognition for productive purposes, you must create a service instance and a service key.

You can use the Set up account for Business Entity Recognition booster to create the Business Entity Recognition instance and its service key quickly in just a few steps. How to use Boosters for SAP AI Business Services is described in the following blog post: Link.

The Business Entity Recognition service key JSON file is required (see Figure 05).

Integrate Business Entity Recognition using the predefined Integration Flow available on SAP API Business Hub

If you want to integrate the Business Entity Recognition Service with your e-mail server, you can use the Integration Flow available on SAP API Business Hub. This integration flow can be consumed on an SAP Cloud Integration tenant.

In addition, you need to deploy a User Credentials artifact on SAP Cloud Integration that contains the user name and password used to authenticate at the e-mail account (see SAP Help Portal).

OAuth2 Client Credentials Setup

In this step, open the tile Manage Security Material within the Monitoring view on SAP Cloud Integration to create a new OAuth2 Client Credentials for the Business Entity Recognition Service integration.

1. Go to the Manage Security Material section of SAP Cloud Integration.

Figure 02: Manage Security Material

2. Click Create and select OAuth2 Client Credentials

Figure 03: Create OAuth2 Client Credentials

3. Add OAuth2 Client Credentials with the following settings and click Deploy

Property	Description
Name	Enter a name
Token Service URL	Enter the <url> from the Business Entity Recognition service key JSON file. Add /oauth/token at the end (see Figures 04 and 05).
Client ID	Enter the <clientid> from the Business Entity Recognition service key JSON file (see Figure 05).
Client Secret	Enter the <clientsecret> from the Business Entity Recognition service key JSON file (see Figure 05).

Figure 04: OAuth2 Client Credentials

Figure 05: Business Entity Recognition service key

Copy the Integration Package

To use the integration flow available on SAP API Business Hub, you need to copy the integration package into your SAP Cloud Integration tenant.

1. Go to the “Discover” section of your SAP Cloud Integration tenant. Enter “SAP AI Business Services – Business Entity Recognition Integration with Email Server” in the search bar.

Figure 06: Discover Integration Package

2. Open the package by clicking on the entry. To copy the integration package, click on the “Copy” button in the upper right corner.

Figure 07: Copy Integration Package

3. Go to the “Design” section of your SAP Cloud Integration Tenant. You will see the copied integration package.

Figure 08: Integration Package is copied and available within the Design section

4. Open your integration package and switch to the artifacts tab. There is one integration flow available. To configure the integration flow, click on the button in the “Actions” column and choose Configure.

 

Figure 09: Configure the integration flow

 

Integration Flow Configuration

In this step, we will configure the integration flow using the Business Entity Recognition service and the email settings.

1. In the Sender section, configure the setting of your e-mail box where the e-mails arrive

Property	Description                                                   Source: SAP Help Portal
Address	Specifies the hostname or address of the IMAP server
Proxy Type	The type of proxy that you’re using to connect to the target system. Default: Internet
Protection	Specifies the method to use to establish an encrypted (secure) connection. Default: IMAPS
Authentication	Specifies which mechanism is used to protect user name and password combination. Default: Encrypted User/Password
Credential Name	Specifies the name of the User Credentials artifact that contains the user name and password (used to authenticate at the e-mail account).
Folder	Specify the folder containing the emails to be read.

Figure 10: Sender Configuration

2. In the Receiver section, configure one of the Receivers FinalStatusEmail, POSTProcessFailedMail, and GETProcessFailedMail (configurations will be copied)

Figure 11: Receivers

Property	Description                                                               Source: SAP Help Portal
Address	Specifies the hostname and (optionally) a port number of the SMTP server.
Proxy Type	The type of proxy that you’re using to connect to the target system. Default: Internet
Protection	Defines whether encryption is used. Default: STARTTLS Mandatory
Authentication	Specifies which mechanism is used to authenticate against the server with a user name and password combination. Default: Plain User/Password
Credential Name	Specifies the name of a deployed credential to use for authentication.
From	The E-mail address that the response message comes from.

Figure 12: Receiver Configuration

3. In the More section, configure the following parameters

Property	Description
Business Entity Recognition Client Credentials	The credential name of the OAuth2 Client Credentials created above
Business Entity Recognition Model Name	The model to be used for inference. It can be either a pre-trained model or a custom model. The possible values for a pre-trained model are as follows: sap_email_business_entity sap_invoice_header
Business Entity Recognition Model Version	The version of the model to be used for inference
Business Entity Recognition Service Url	The url from the Business Entity Recognition service key JSON file. Add /api/v1/inference/jobs at the end

Figure 13: Business Entity Recognition Configuration

4. Save and Deploy the Integration Flow.

Figure 14: Save and deploy the configurations

Test the integration flow

After the integration flow is deployed successfully, you can send an email to the configured email inbox maintained in the sender adapter. An example mail could look like the following:

Figure 15: Invoice E-Mail

After the processing on SAP Cloud Integration was successful, you will receive the extracted results via mail:

Figure 16: Extracted results

 

Conclusion

In this blog post, you have seen how to configure the integration flow, enabling easy integration of the Business Entity Recognition service with your mail account. It allows to automatically process incoming emails to detect and return any type of business entities in an unstructured text.

 

Feel free to also take a look at the following blog post written by Nina Simeonova, which describes how to Integrate your enterprise email inbox with Document Information Extraction Service via SAP Cloud Integration.

 

Special thanks to Tim Nusch and Kevin Naef who helped me in this project and blog post!