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.
- Go to the Manage Security Material section of SAP Cloud Integration.
Figure 02: Manage Security Material
- Click Create and select OAuth2 Client Credentials
Figure 03: Create OAuth2 Client Credentials
- 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.
- 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
- 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
- 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
- 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.
- 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
- 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
- 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
- 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 Int....
Special thanks to tim.nusch and kevin_naef who helped me in this project and blog post!
- SAP Managed Tags:
