business entity recognition - sap help portal

PUBLIC2022-06-29

Business Entity Recognition

© 2

022

SAP

SE o

r an

SAP affi

liate

com

pany

. All r

ight

s re

serv

ed.

THE BEST RUN

Content

1 What Is Business Entity Recognition?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 What's New for Business Entity Recognition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1 2021 What's New for Business Entity Recognition (Archive). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2 2020 What's New for Business Entity Recognition (Archive). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 Service Plans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Metering and Pricing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6 Supported Languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

7 Initial Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227.1 Tutorials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

8 API Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248.1 Get Access Token. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248.2 Datasets API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Training Data Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Inference Data Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Get Datasets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Post Dataset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Get Dataset Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Delete Dataset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32Post Training Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Get Documents in Dataset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Get Document Details from Dataset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Delete Document from Dataset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8.3 Training API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Get All Training Jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Post Training Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Get Training Job Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Delete Training Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41Training Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

8.4 Models API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Get Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Get Model Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

2 PUBLICBusiness Entity Recognition

Content

Delete Model Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Get Model Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8.5 Deployments API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Get Deployments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49Post Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Get Deployment Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51Delete Deployed Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Deployments Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

8.6 Inference API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Post Inference Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Get Inference Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Get Inference File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65Inference Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

8.7 Common Status and Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .668.8 Technical Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Free Tier Option Technical Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68

9 Consuming the Service via AI API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69

10 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7710.1 User Administration, Authentication and Authorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7710.2 Data Protection and Privacy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7810.3 Auditing and Logging Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8010.4 Front-End Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

11 Monitoring and Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

Business Entity RecognitionContent PUBLIC 3

1 What Is Business Entity Recognition?

Detect and highlight entities in unstructured text using machine learning.

Business Entity Recognition helps you to detect and highlight any type of business entity in unstructured text. You can use the service, for example, to automatically extract the context from incoming emails with invoice inquiries, automating recurring tasks associated with answering queries about the status and payment of invoices. Business Entity Recognition is part of the SAP AI Business Services portfolio.

With Business Entity Recognition you can:

● Handle a higher amount of text documents more efficiently and faster● Increase quality and compliance of your text documents handling processes● Reduce manual and repetitive work, allowing the members of your organization to focus on more relevant

tasks that are in their field of expertise

Features

Extract Text Entity - Pre-trained Model

Use pre-trained machine learning models to detect and highlight, in unstructured text, business entities that belong to predefined categories.

Extract Text Entity - Custom Model

Create your own custom machine learning models to detect and highlight any type of business entity in unstructured text.

Environment

This service is available in the Cloud Foundry environment.

Prerequisites

See Initial Setup [page 22].

Technical Constraints

For information on technical limits, see Technical Constraints [page 67].


What Is Business Entity Recognition?

Regional AvailabilityGet an overview on the availability of Business Entity Recognition according to region, infrastructure provider, and release status in the Pricing tab of the SAP Discovery Center .

Business Entity RecognitionWhat Is Business Entity Recognition? PUBLIC 5

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdiscovery-center.cloud.sap%2F%23%2FserviceCatalog%2Fbusiness-entity-recognition

2 What's New for Business Entity Recognition

Technical Component

Environment Title Description

Action

Lifecycle Type

Line of Business

Modular Business Process

Available as of


Cloud Foundry

Technical Improvements

There have been several infrastructure improvements.

Info only

General Availability

Changed

Technology

Not applicable

2022-05-30


Cloud Foundry

Global Accounts

You can now move subaccounts between your global accounts.


Info only


New Technology

Not applicable

2022-04-05


Cloud Foundry

New Version of the sap_address_entity Pre-trained Model

An improved version of the sap_address_entity pre-trained model is now available.

See sap_address_entity [page 58].

Info only


Changed

Technology

Not applicable

2022-04-05


Cloud Foundry

Overall Improvements

There have been several code and stability improvements.

Info only


Changed

Technology

Not applicable

2022-04-05

2.1 2021 What's New for Business Entity Recognition (Archive)


What's New for Business Entity Recognition

Technical Component

Capability

Environment Title Description Action Type

Available as of


Extension Suite - Development Efficiency

Cloud Foundry

New Pre-trained Model

The sap_address_entity pre-trained model is now available.

See Supported Languages [page 20], Post Inference Data [page 56] and Extracted Entities by Pre-trained Model [page 58].

Info only

New 2021-12-14



Cloud Foundry


There have been several code and stability improvements. Info only

Changed

2021-12-14



Cloud Foundry

New Pre-trained Model

The sap_generic_entities pre-trained model is now available.

See Supported Languages [page 20], Post Inference Data [page 56] and Extracted Entities by Pre-trained Model [page 58].

Info only

New 2021-12-06



Cloud Foundry

Trial Account

Business Entity Recognition is now available in the AWS region US East (VA) on SAP BTP Trial.

You can now also use the Set up account for Business Entity Recognition booster to automate the onboarding steps on the SAP BTP Trial Cockpit, and quickly try out the service.

Info only

New 2021-12-06

Business Entity RecognitionWhat's New for Business Entity Recognition PUBLIC 7

Technical Component

Capability


Available as of



Cloud Foundry

AI API You can now use the AI API from SAP AI Core to consume Business Entity Recognition.

See Consuming the Service via AI API [page 69].

Info only

New 2021-12-06



Cloud Foundry



Changed

2021-10-11



Cloud Foundry

Free Service Plan

The Free service plan is now available for Business Entity Recognition.

See Service Plans [page 16] and Free Tier Option Technical Constraints [page 68].

Info only

New 2021-10-11



Cloud Foundry



Changed

2021-07-02



Technical Component

Capability


Available as of



Cloud Foundry

New AWS Regions

Business Entity Recognition is now available in the following AWS regions:

● Europe (Frankfurt) EU-ONLY (access from Europe only)● Japan (Tokyo)● US East (VA)

Info only

New 2021-07-02



Cloud Foundry

Python Client Library

A Python client library is now available for Business Entity Recognition. It provides easy access to the REST API and facilitates the service onboarding process.

See Python Client Library .

Info only

New 2021-07-02



Cloud Foundry

Security Guide

Auditing and logging information is now available in the Security [page 77].

Info only

New 2021-07-02



Cloud Foundry

API Reference

With the latest API improvements, you can now:

● List all recently submitted training jobs. See Get All Training Jobs [page 38].

● Use datasets for inference. See Inference Data Format [page 28], Post Dataset [page 29] and Post Inference Data [page 56].

● Get the inference results in a file containing the extracted entities and confidence score. See Get Inference File [page 65].

Info only

New 2021-05-24


http://help.sap.com/disclaimer?site=https%3A%2F%2Fgithub.com%2FSAP%2Fbusiness-entity-recognition-client-library

Technical Component

Capability


Available as of



Cloud Foundry

Technical Constraints

Observe the following new Technical Constraints [page 67] for:

● Total number of documents per training dataset● Total number of documents per inference dataset

Info only

New 2021-05-24



Cloud Foundry

Supported Languages

Supported Languages [page 20] documentation is now available.

See also the sample code response examples in:

● Get Training Job Status [page 40]● Get Model Details [page 45]● Get Model Version [page 47]

Info only

New 2021-02-08



Cloud Foundry

Trial Account

The following Free Tier Option Technical Constraints [page 68] have been updated:

● Total number of inference requests per month● Total number of inference characters per month

Info only

Changed

2021-01-27



Cloud Foundry


There have been several code improvements. Info only

Changed

2021-01-18

2.2 2020 What's New for Business Entity Recognition (Archive)



Technical Component

Capability

Environment Title Description Type

Available as of



Cloud Foundry

Interactive and Lifecycle Graphics

The end-to-end process of the following APIs is now available in interactive graphics:

● Datasets API [page 25]● Training API [page 37]● Deployments API [page 48]● Inference API [page 54]

See the statuses at the different stages of the Training Lifecycle [page 42], Deployments Lifecycle [page 53] and Inference Lifecycle [page 65].

New 2020-12-21



Cloud Foundry

Tutorials

A new tutorial group is now available for Business Entity Recognition.

See Use Custom Machine Learning Models to Process Unstructured Text .

New 2020-12-21



Cloud Foundry

New SAP Cloud Platform Cockpit Booster

You can now use the Set up account for Business Entity Recognition booster to automate the onboarding steps on the SAP Cloud Platform cockpit, and quickly consume the service.


New 2020-12-21



Cloud Foundry

Trial Account

You can now try out the Business Entity Recognition Training APIs on SAP Cloud Platform Trial.

Changed

2020-11-03



Cloud Foundry

Feature Scope Description

The Feature Scope Description for Business Entity Recognition has been updated.

Changed

2020-11-03


http://help.sap.com/disclaimer?site=https%3A%2F%2Fdevelopers.sap.com%2Fgroup.cp-aibus-business-entity-custom.html


https://help.sap.com/doc/2df6cb90c5a44c8781400f4f58363448/SHIP/en-US/loio89d72d94c20c4b01b71a1243b00e0b24.pdf

Technical Component

Capability


Available as of



Cloud Foundry

SAP API Business Hub

Business Entity Recognition is now available in the SAP API Business Hub.

See Business Entity Recognition .

New 2020-10-19



Cloud Foundry

Swagger UI

The Swagger UI documentation has been updated. It now includes response structure of APIs.

See API Reference [page 24] to find out how to access comprehensive specification of the Business Entity Recognition APIs in Swagger UI.

Changed

2020-10-19



Cloud Foundry

Pre-trained Models

A new enhanced version of the sap_email_business_entity pre-trained model is now available.

The list of entities you can extract with the sap_invoice_header pre-trained model has been updated.

See Extracted Entities by Pre-trained Model [page 58].

Changed

2020-10-05



Cloud Foundry

Training API

The Delete Training Job [page 41] endpoint is now available. New 2020-10-05



Cloud Foundry

Metering and Pricing

Metering and Pricing [page 17] documentation is now available for Business Entity Recognition.

New 2020-10-05



http://help.sap.com/disclaimer?site=https%3A%2F%2Fapi.sap.com%2Fapi%2Fbusiness_entity_recognition_api%2Fresource

Technical Component

Capability


Available as of



Cloud Foundry

Tutorials

A new tutorial group is now available for Business Entity Recognition.

See Use Pre-trained Machine Learning Models to Process Unstructured Text .

New 2020-08-20



Cloud Foundry

Trial Account

You can now try out Business Entity Recognition on SAP Cloud Platform Trial.

New 2020-07-20



Cloud Foundry

Custom Models

You can now create your own Business Entity Recognition machine learning model trained with data from your text documents. See Datasets API [page 25], Training API [page 37], Models API [page 43], Deployments API [page 48]and Technical Constraints [page 67].

New 2020-06-30



Cloud Foundry

Pre-trained Models

The names of the Business Entity Recognition pre-trained models have changed and now the model sap_invoice_header supports French.

See Extracted Entities by Pre-trained Model [page 58].

Changed

2020-06-30



Cloud Foundry

Security Guide

The Security [page 77] has been updated. Changed

2020-06-30


http://help.sap.com/disclaimer?site=https%3A%2F%2Fdevelopers.sap.com%2Fgroup.cp-aibus-business-entity-detect.html


Technical Component

Capability


Available as of



Cloud Foundry

New Service

A new artificial intelligence pre-trained business service is now available. Use Business Entity Recognition to detect and highlight any given type of named entity in unstructured text into pre-defined categories. See Business Entity Recognition documentation.

Announcement

2020-04-21



https://help.sap.com/ber

3 Concepts

See a glossary of definitions for artificial intelligence (AI) and machine learning (ML), and Business Entity Recognition concepts in AI & ML Glossary. In the third column Filter, select Business Entity Recognition.

Business Entity RecognitionConcepts PUBLIC 15

https://help.sap.com/viewer/204887c82baf42cc929c3d8b2286b44e/1.0/en-US

4 Service Plans

Learn more about the different types of service plans for Business Entity Recognition.

Business Entity Recognition provides different types of service plans. The type you choose determines pricing, conditions of use, resources, available services, and hosts.

It depends on your use case whether you choose a free or a paid service plan. If you plan to use your global account in productive mode, you must purchase a paid enterprise account. It's important that you're aware of the differences when you're planning and setting up your account model. See Initial Setup [page 22].

There are two service plans available:

● Free● Standard

For more details about the service plans, see the following table:

Service Plan Details Account Type

Free ● Service plan intended for development and try-out purposes on your enterprise account.

● You can get up to 120,000 character predictions per month.

See Free Tier Option Technical Constraints [page 68] and the tutorial Get an Account on SAP BTP to Try Out Free Tier Service Plans .

Enterprise

Standard ● Business Entity Recognition default service plan.

● Service plan intended for productive usage.

● Inference requests in blocks of 10,000 characters.

See Metering and Pricing [page 17] and Technical Constraints [page 67].

Enterprise

Remember● If you first activated the Free service plan, you can update the same service instance to switch to

Standard for enterprise accounts.● Both metadata and transaction data, including trained models, are transferred to Standard for

enterprise accounts when you switch from Free to Standard.● If you don't want Free and Standard data to be combined together, you can split them by subscribing to

the service plans in separate subaccounts.


Service Plans

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdevelopers.sap.com%2Ftutorials%2Fbtp-free-tier-account.html



5 Metering and Pricing

TipThe metering and pricing details listed here are relevant only to users of the Standard service plan for enterprise accounts. See Service Plans [page 16].

Usage Metric

Business Entity Recognition is metered based on a predefined usage metric consisting of characters and models:

● Characters: number of characters processed by the cloud service each month. Characters with multiple bytes are counted as a single character.

● Models: trained machine learning models that are available as an engine for prediction and classification via the corresponding API endpoint.

Metric Size

● Inference (per block and month): blocks of 10,000 characters.● Custom models (flat fee): number of hours.

Basic Service

CautionThe price rates listed below might be outdated. Find updated price rates in the Pricing tab of the SAP Discovery Center.

The two pre-trained models (see Extracted Entities by Pre-trained Model [page 58]) can be used without extra model-costs. Only inference requests are charged.

Metric Tiers Unit Price per Month

Blocks of 10,000 characters Minimum consumption: 50 blocks EUR 0.21

50 to 5,000 blocks

5,001 to 15,000 blocks EUR 0.13

Business Entity RecognitionMetering and Pricing PUBLIC 17

Metric Tiers Unit Price per Month

More than 15,000 blocks EUR 0.09

Example

Cost for 50 blocks = 50 * EUR 0.21 = EUR 10.50.

Cost for 15,600 blocks = 15,600 * EUR 0.09 = EUR 1,404.

Extended Service: Additional Models (Retraining)

Deployed custom models (online and that may be used for inference) are charged EUR 1.034 per hour.

Example

Cost for 2 custom models that were deployed for 4 hours = 2 * 4 * EUR 1.034 = EUR 8.272.

Total Charge = Deployed model hours charge + Inference requests in blocks of 10,000 characters.

4,500 Blocks are used (unit price/month = EUR 0.21) = 4,500 * EUR 0.21 = EUR 945.00.

In total: EUR 28.435 + EUR 945.00 = EUR 973.435.

Tip

Use the pricing estimator tool .


Metering and Pricing

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdiscovery-center.cloud.sap%2Festimator%2F

Related Information

SAP Discovery CenterSAP Business Technology Platform Service Description Guide

Business Entity RecognitionMetering and Pricing PUBLIC 19

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdiscovery-center.cloud.sap%2FserviceCatalog%2Fbusiness-entity-recognition

http://help.sap.com/disclaimer?site=https%3A%2F%2Fwww.sap.com%2Fabout%2Ftrust-center%2Fagreements%2Fcloud%2Fcloud-services.html%3Fsort%3Dlatest_desc%26search%3DSAP%2520Business%2520Technology%2520Platform%2520Service%2520Description%2520Guide

6 Supported Languages

Business Entity Recognition supports the following languages per machine learning model type:

Model Supported Languages

sap_address_entity ● Czech● Danish● Dutch● English● Finnish● French● German● Italian● Norwegian● Polish● Portuguese● Slovak● Slovenian● Spanish● Swedish

sap_email_business_entity ● English● German

sap_generic_entities ● English● French● German● Spanish

sap_invoice_header ● English● French● German


Supported Languages

Model Supported Languages

Custom ● Czech● Danish● Dutch● English● Finnish● French● German● Hungarian● Italian● Norwegian● Polish● Portuguese● Romanian● Russian● Spanish● Swedish

NoteFor custom models, the supported languages depend on the language of the training documents. You can choose to upload training documents of any language to create a custom model, and use it for inference. However, if the language is different from the supported languages listed above, the model accuracy can be lower.

Related Information

Extracted Entities by Pre-trained Model [page 58]Datasets API [page 25]

Business Entity RecognitionSupported Languages PUBLIC 21

7 Initial Setup

To be able to use Business Entity Recognition for productive purposes, you must complete some steps in the SAP BTP cockpit.

TipSee Tutorials [page 23] to find out how to use free tier option for Business Entity Recognition to try out the service.

Prerequisites

● You have an enterprise global account on SAP BTP. See Enterprise Accounts.● You are entitled to use the service.

TipYou can also use the Set up account for Business Entity Recognition booster to automate the steps described below on the SAP BTP cockpit. See Boosters and the blog post How to use Boosters for SAP AI Business Services .

1. Create a Subaccount in the Cloud Foundry Environment.

To be able to use Business Entity Recognition for productive purposes, you need to create a subaccount in your global account using the SAP BTP cockpit.

TipSee Create a Subaccount in the Cloud Foundry Environment.

NoteBusiness Entity Recognition allows you to move subaccounts between your global accounts. For more information, see Relationship Between Global Accounts, Subaccounts, and Directories [Feature Set B].

2. Enable the Business Entity Recognition Service.

To enable Business Entity Recognition in the service catalog, using the SAP BTP cockpit, perform the following steps:


Initial Setup

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/171511cc425c4e079d0684936486eee6.html

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/fb1b56148f834749a2bf51127421610b.html

http://help.sap.com/disclaimer?site=https%3A%2F%2Fblogs.sap.com%2F2020%2F12%2F18%2Fhow-to-use-boosters-for-sap-ai-business-services%2F

http://help.sap.com/disclaimer?site=https%3A%2F%2Fblogs.sap.com%2F2020%2F12%2F18%2Fhow-to-use-boosters-for-sap-ai-business-services%2F

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/05280a123d3044ae97457a25b3013918.html

https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/8ed4a705efa0431b910056c0acdbf377.html?version=Cloud#relationship-between-global-accounts%2C-subaccounts%2C-and-directories-%5Bfeature-set-b%5D

1. Configure Entitlements and Quotas.2. Create Space.3. Create Service Instance.

NoteIn the New Instance wizard, enter only the Basic Info details, and leave the Parameters details empty, instance parameters are not mandatory for this service.

4. Create Service Key.

TipSee Using Services in the Cloud Foundry Environment.

7.1 Tutorials

Follow a tutorial to get familiar with the Business Entity Recognition APIs and functionalities.

Tutorial Group Description

Use Pre-trained Machine Learning Models to Process Unstructured Text

Detect and highlight entities from unstructured text with pre-trained models.

Use Custom Machine Learning Models to Process Unstructured Text

Detect and highlight entities from unstructured text with custom models.

Related Information

Tutorial Navigator

Business Entity RecognitionInitial Setup PUBLIC 23

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/5ba357b4fa1e4de4b9fcc4ae771609da.html

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/2f6ed22ccf424dae84345f4500c2d8ea.html

https://help.sap.com/viewer/09cc82baadc542a688176dce601398de/Cloud/en-US/6d6846def3c443aa9f83d127353147ce.html

https://help.sap.com/viewer/09cc82baadc542a688176dce601398de/Cloud/en-US/6fcac08409db4b0f9ad55a6acd4d31c5.html

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/f22029f0e7404448ab65f71ff5b0804d.html





http://help.sap.com/disclaimer?site=https%3A%2F%2Fdevelopers.sap.com%2Ftutorial-navigator.html%3Ftag%3Dsoftware-product%3Atechnology-platform%2Fsap-ai-business-services%2Fbusiness-entity-recognition

8 API Reference

Explore the Business Entity Recognition APIs.

Before using the Business Entity Recognition APIs, you need to retrieve your OAuth access token as described in Get Access Token [page 24].

The training endpoints for creating a new Business Entity Recognition custom model are grouped as follows:

● Datasets API [page 25]● Training API [page 37]● Models API [page 43]● Deployments API [page 48]

Use the Inference API [page 54] endpoints to extract entities from text documents automatically using your own custom model or the available pre-trained models (see Extracted Entities by Pre-trained Model [page 58]).

The endpoints for each of these API groups are listed in the order in which they are to be used.

To display the comprehensive specification of the Business Entity Recognition APIs in Swagger UI, add the URL path extension /api/v1 to the Business Entity Recognition base URL (that is, the url value from outside the uaa section of your service key).

Related Information

Common Status and Error Codes [page 66]Technical Constraints [page 67]

8.1 Get Access Token

Retrieve your OAuth access token, which will grant you access to the Business Entity Recognition APIs.

NoteThe token is valid for 12 hours. After that, you need to generate a new one.

Request

Base URL: url value from inside the uaa section of the service key


API Reference

URL Path: /oauth/token

HTTP Method: POST

Request Headers

Header Required Values

Content-Type Yes <application/x-www-form-urlencoded>

Request Parameters

Parameter Required Data Type Description

client_id Yes String The clientid value from the service key.

client_secret Yes String The clientsecret value from the service key.

grant_type Yes String Token grant type. Set it to client_credentials.

response_type Yes String Token response type. Set it to token.

Response

The response is given as a status (200 or 401). See Common Status and Error Codes [page 66].

Response Example200 “Success”

{ "access_token": "<< your access token >>", "token_type": "bearer", "expires_in": 43199, "scope": "uaa.resource", "jti": "8d00c157058949daab714a44c04c416b" }

TipAlternatively, you can follow the steps in this tutorial to Get OAuth Access Token for Business Entity Recognition via Web Browser .

8.2 Datasets API

Use the Datasets API endpoints to create datasets and upload documents to be used to train a custom model or for inference.

To find out more about the endpoints of the Datasets API, choose the links in the following image.

Business Entity RecognitionAPI Reference PUBLIC 25

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdevelopers.sap.com%2Ftutorials%2Fcp-aibus-ber-web-oauth-token.html

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdevelopers.sap.com%2Ftutorials%2Fcp-aibus-ber-web-oauth-token.html

● Get Datasets [page 28]● Delete Dataset [page 32]● Post Dataset [page 29]● Get Dataset Details [page 31]● Delete Document from Dataset [page 36]● Post Training Document [page 33]● Get Document Details from Dataset [page 35]

NoteYou can also Get Documents in Dataset [page 34].

Related Information

Training Data Format [page 26]Inference Data Format [page 28]

8.2.1 Training Data Format

Deep learning is a class of machine learning algorithms that uses multiple layers to progressively extract higher-level features from the raw input.

Text input is preprocessed and converted into the encodings so that machine learning can understand it. This preprocessed data is fed into neural network algorithms to train the model. Models generated during the training are nondeterministic and can therefore differ in accuracy even if you use the same input for training.

Based on the input dataset, the Business Entity Recognition service generates multiple deep learning models internally and chooses the best one based on the f1 score. The Business Entity Recognition service performs


API Reference

statistical analyses on the number of unique labels and their occurrences in the datasets to identify the optimal hyper parameters. These analyses help increase the accuracy of model.

Training depends on the dataset size and the number of labels: the larger the dataset, the fewer times the model must be trained; and the smaller the dataset, the more times the model must be trained to achieve optimal performance. Generated models can be used for the inference.

Business Entity Recognition requires a specific data format to train a model. The data format prerequisites are:

● File format: JSONL● File extension: JSON● File size: maximum of 10 MB● File does not contain malicious data.● File does not contain blank lines at the end.● Every line in the file has one JSON object, which has the following mandatory fields:

○ ID (Number): used to represent the unique record ID and the ID should be unique throughout the dataset

○ Text (String): contains the data on which model must be trained (double quotes in the text are not supported)

○ Labels (Array): contain the annotation details, with the text as an array of characters that starts with the index 0. Each label is in the following format:○ startIndex (Number): starting char index of the phrase○ endIndex (Number): ending char index of the phrase○ Annotation (String): annotation (class label) name

Data File Example

Sample Code

{ "id": 1, "text": "Hi John, Please provide the details of invoice AB12345. Regards, Mike", "labels": [ [48, 55, "InvoiceID"] ]} { "id": 2, "text": "Hi Kay, Vendor DE029876 has requested invoice AB13145 details, kindly process the request ASAP. Regards, John", "labels": [ [16, 24, "VendorID"], [47, 54, "InvoiceID"] ] }


Every JSON object in the file is a record. If a record doesn’t have any annotations, then that record is discarded. There should be a minimum of 50 references per annotation. If the number of references is lower than 50, that annotation is discarded. There should be at least one annotation in the dataset to trigger the training.

8.2.2 Inference Data Format

Business Entity Recognition supports inference batch processing. To perform processing of this kind, create a dataset that contains inference documents and then use the dataset ID to trigger an inference request. See also Post Inference Data [page 56].

The data format prerequisites are:

● File format: JSONL● File extension: JSON● File size: maximum of 10 MB● File does not contain malicious data.● File does not contain blank lines at the end.● Every line in the file should have one JSON object, which has the following mandatory fields:

○ ID (UUID): used to represent the unique record ID○ Text (String): contains the data on which inference must be performed

Data File Example

Sample Code

[{ "id": "2542fce8-0f83-4f09-b903-43ef36dca23c", "text": "Hello, I would like to know the status of the invoice 456789. Regards, John" }, { "id": "0708dd75-81e7-4d8e-abdf-37fd3cea7479", "text": "Hello, I would like to know the status of the invoice 123456. Regards, John" } ]

8.2.3 Get Datasets

Get information about all created datasets.

Request

Base URL: url value from outside the uaa section of the service key


API Reference

URL Path Extension: /api/v1

URL Endpoint Path: /datasets

HTTP Method: GET

Response

The response is given as a status (200, 401, 405, or 500). See Common Status and Error Codes [page 66].

Response Example

200 “Datasets have been retrieved successfully”

{ "data": { "count": 1, "datasets": [ { "datasetId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "datasetType": "training", "description": "SAP BER default dataset description", "documentCount": 2, "createdAt": "2020-10-05T12:27:30", "modifiedAt": "2020-10-05T12:27:30" } ] } }

8.2.4 Post Dataset

Create a new training/inference dataset entry.

Request



URL Endpoint Path: /datasets

HTTP Method: POST


Request Parameters


datasetType No String Type of dataset to be created

NoteThis parameter is optional. If you don’t specify it, the datasetType "training" is used as default.

description Yes String JSON dictionary with input parameters for dataset creation

Request Example

{ "datasetType": "training", "description": "SAP BER default dataset description"}

NoteTo upload an inference dataset, use "inference" as datasetType in the request.

Response

The response is given as a status (201, 400, 401, 405, 429, or 500). See Common Status and Error Codes [page 66].

Response Example201 “Dataset has been created successfully”

{ "data": { "datasetId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "datasetType": "training", "message": "Dataset has been created successfully" } }


API Reference

8.2.5 Get Dataset Details

Get details of specific dataset.

Request



URL Endpoint Path: /datasets/{datasetId}

HTTP Method: GET

Request Parameters


datasetId Yes UUID Dataset ID received in Post Dataset [page 29]

Request Example

/datasets/16ecf3f0-8574-4a98-9210-d287f67fb79d

Response

The response is given as a status (200, 401, 404, 405, or 500). See Common Status and Error Codes [page 66].

Response Example

200 “Dataset has been retrieved successfully”

{ "data": { "datasetId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "datasetType": "training", "description": "SAP BER default dataset description", "documentCount": 2, "createdAt": "2020-10-05T12:27:30", "modifiedAt": "2020-10-05T12:27:30" } }


8.2.6 Delete Dataset

Delete a specific dataset along with its documents.

Request



URL Endpoint Path: /datasets/{datasetId}

HTTP Method: DELETE

Request Parameters


datasetId Yes UUID ID of the dataset to be deleted

Request Example

/datasets/16ecf3f0-8574-4a98-9210-d287f67fb79d

Response


Response Example

200 “Dataset has been deleted successfully”

{ "data": { "datasetId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "message": "Dataset has been deleted successfully" }}


API Reference

8.2.7 Post Training Document

Upload a training document to a specific dataset.

Request



URL Endpoint Path: /datasets/{datasetId}/documents

HTTP Method: POST

Request Parameters


document Yes File Training document to be uploaded

datasetID Yes String ID of dataset to which document is to be uploaded

Request Example

/datasets/16ecf3f0-8574-4a98-9210-d287f67fb79d/documents

Response

The response is given as a status (201, 400, 401, 404, 405, 413, 415, 429, or 500). See Common Status and Error Codes [page 66].

Response Example

201 “Document has been created successfully”

{ "data": { "datasetId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "documentId": "4966ed56-f52d-4f95-9512-62cea13d899d", "message": "Document has been created successfully" } }


8.2.8 Get Documents in Dataset

Get documents present in a dataset.

Request



URL Endpoint Path: /datasets/{datasetId}/documents

HTTP Method: GET

Request Parameters


datasetId Yes UUID ID of dataset from which document details are to be retrieved

Request Example/datasets/4966ed56-f52d-4f95-9512-62cea13d899d

Response


Response Example200 “Documents have been retrieved successfully”

{ "data": { "datasetId": "4966ed56-f52d-4f95-9512-62cea13d899d", "datasetType": "training", "description": "SAP BER default dataset description", "documentCount": 1, "createdAt": "2020-10-05T12:27:30", "modifiedAt": "2020-10-05T12:27:30", "documents": [ { "documentId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "documentSize": 19025, "createdAt": "2020-10-05T12:27:30" } ] } }


API Reference

8.2.9 Get Document Details from Dataset

Get information about a specific document in a dataset.

Request



URL Endpoint Path: /datasets/{datasetId}/documents/{documentId}

HTTP Method: GET

Request Parameters


datasetId Yes UUID ID of dataset in which document is present

documentId Yes UUID ID of document for which details are to be retrieved

Request Example

/datasets/18384723-3a6f-42c6-94d5-1db4c74633a3/documents/16ecf3f0-8574-4a98-9210-d287f67fb79d

Response


Response Example

200 “Document has been retrieved successfully”

{ "data": { "documentId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "documentSize": 19025, "createdAt": "2020-10-05T12:27:30" } }


8.2.10 Delete Document from Dataset

Delete a specific training document within a dataset.

Request



URL Endpoint Path: /datasets/{datasetId}/documents/{documentId}

HTTP Method: DELETE

Request Parameters


datasetId Yes UUID ID of dataset in which the document is present

documentId Yes UUID ID of document to be deleted

Request Example

/datasets/16ecf3f0-8574-4a98-9210-d287f67fb79d/documents/4966ed56-f52d-4f95-9512-62cea13d899d

Response


Response Example

200 “Document has been deleted successfully”

{ "data": { "datasetId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "documentId": "4966ed56-f52d-4f95-9512-62cea13d899d", "message": "Document has been deleted successfully" }}


API Reference

8.3 Training API

Use the Training API endpoints to train a new custom model.

To find out more about the endpoints of the Training API, choose the links in the following image.

● Post Training Job [page 38]● Get Training Job Status [page 40]● Training Lifecycle [page 42]● Delete Training Job [page 41]


Related Information

Get All Training Jobs [page 38]

8.3.1 Get All Training Jobs

Get all recently submitted training jobs.

Request



URL Endpoint Path: /training/jobs

HTTP Method: GET

Response


Response Example200 “OK”

{ "count": 1, "jobs": [{ "jobId": "44db8da5-4fb9-4f85-9d0a-90ccd8534a64", "datasetId": "5fc8dcca-4889-4e96-92be-986833c7d896", "modelName": "sample_model", "createdAt": "2021-05-03T08:20:19Z" }] }

8.3.2 Post Training Job

Submit a training job for the specified dataset.

NoteTraining time depends on the size of the training dataset, but for Business Entity Recognition it should take at least 4 hours to complete (with training job status “SUCCEDED”). In the meantime, the status is


API Reference

“RUNNING”. Before 4 hours, the status should not change to “SUCCEDED”, but it can change from “RUNNING” to “FAILED” if the training job submission fails and you need to trigger it once again with the Post Training Job endpoint.

Request



URL Endpoint Path: /training/jobs

HTTP Method: POST

Request Parameters


modelName Yes String Name of the resulting trained model

datasetId Yes UUID Dataset ID to be used for training

NotemodelName should adhere to the following conventions:

● Can’t have the same name as a Business Entity Recognition pre-trained model (see Extracted Entities by Pre-trained Model [page 58])

● Can’t have "sap_" as a prefix● Starts with an alphanumeric character● May include the special characters "-" and "_"● Can have a maximum of 64 characters

Request Example

{ "modelName": "test_model", "datasetId": "5fc8dcca-4889-4e96-92be-986833c7d896" }

Response



Response Example202 “Training job has been submitted successfully”

{ "data": { "jobId": "f5e1b1e8-a8b6-4ce7-ba84-1dd36eab4bc0", "datasetId": "5fc8dcca-4889-4e96-92be-986833c7d896", "status": "PENDING", "message": "Training job has been submitted successfully" } }

8.3.3 Get Training Job Status

Get the status of a training job.

Request



URL Endpoint Path: /training/jobs/{jobId}

HTTP Method: GET

Request Parameters


jobId Yes UUID Job ID received in Post Training Job [page 38]

Request Example/training/jobs/44db8da5-4fb9-4f85-9d0a-90ccd8534a64

Response


Response Example200 “Model trained successfully”

{ "data": { "jobId": "44db8da5-4fb9-4f85-9d0a-90ccd8534a64",


API Reference

"datasetId": "3cf6afeb-4cd7-45b5-baba-0eff39223a23", "createdAt": "2021-04-23T11:27:06.446Z", "modifiedAt": "2021-04-23T11:27:06.446Z", "status": "SUCCEEDED", "message": "Model Trained Successfully", "modelName": "test_model", "modelVersion": 1, "capabilities": [ "Amount", "Payment Due date", "Invoice Reference No", "Account No" ], "supportedLanguages": [ "EN", "DE" ], "accuracy": 0.9739 } }

Related Information

Supported Languages [page 20]

8.3.4 Delete Training Job

Delete a training job.

Request



URL Endpoint Path: /training/jobs/{jobId}

HTTP Method: DELETE

Request Parameters


jobId Yes UUID Job ID received in Post Training Job [page 38]

Request Example/training/jobs/dcb8fcf2-b72c-4f66-8f08-86020cd71958


Response


Response Example202 “Training job deletion request has been submitted successfully”

{ "data":{ "jobId":"dcb8fcf2-b72c-4f66-8f08-86020cd71958", "message":"Training job deletion request has been submitted successfully" } }

8.3.5 Training Lifecycle

See the statuses at the different stages of the training lifecycle for the Business Entity Recognition service.

Status Description

PENDING The training job has been enqueued for processing, but training hasn’t started yet.

RUNNING The model is being trained.

SUCCEEDED The model has been successfully trained.

FAILED An error occurred during training or the training process was canceled.


API Reference

8.4 Models API

Use the Models API endpoints to query the available custom and pre-trained models.

● Get Models [page 44]● Get Model Details [page 45]● Delete Model Version [page 46]● Get Model Version [page 47]


8.4.1 Get Models

Get information about all models.

Request



URL Endpoint Path: /models

HTTP Method: GET

Response


Response Example200 “Model details retrieved successfully”

{ "data": { "sapModels": { "count": 1, "models": [ { "modelName": "sap_email_business_entity", "versions": [ { "modelVersion": 1 } ] } ] }, "customModels": { "count": 1, "models": [ { "modelName": "custom_model", "versions": [ { "modelVersion": 1, "createdAt": "2020-09-04T16:50:01.379Z", "updatedAt": "2020-09-04T16:50:22.746Z" } ] } ] } } }


API Reference

8.4.2 Get Model Details

Get specific model details.

Request



URL Endpoint Path: /models/{modelName}/versions

HTTP Method: GET

Request Parameters


modelName Yes String Name of the model for which details are to be retrieved

Request Example/models/test_model/versions

Response


Response Example200 “Model details retrieved successfully”

{ "data": { "modelName": "sap_email_business_entity", "modelType": "sapModel", "count": 1, "versions": [ { "modelVersion": 1, "metadata": { "supportedLanguages": [ "EN", "DE" ], "capabilities": [ { "entity": "invoiceReferenceNumber" }, {


"entity": "vendorId" } ] } } ] } }

NoteThe optional response field "truncated": "True" is added to the response only if the capabilities field exceeds the length prescribed in the model repo. When this happens, all the capabilities of the model are not listed in the response.

Related Information


8.4.3 Delete Model Version

Delete specific version of a model.

Request



URL Endpoint Path: /models/{modelName}/versions/{modelVersion}

HTTP Method: DELETE

Request Parameters


modelName Yes String Name of the model to be deleted

modelVersion Yes String Version of the model to be deleted

NoteYou can’t delete Business Entity Recognition models.


API Reference

Request Example/models/test_model/versions/1

Response


Response Example

200 “Model version has been deleted successfully”

{ "data": { "message": "Model custom_model version 1 deleted successfully" } }

8.4.4 Get Model Version

Get details of a model’s specific version.

Request



URL Endpoint Path: /models/{modelName}/versions/{modelVersion}

HTTP Method: GET

Request Parameters


modelName Yes String Name of the model for which details are to be retrieved

modelVersion Yes String Version of the specified model for which details are to be retrieved

Request Example/models/test_model/versions/1


Response


Response Example

200 “Model details retrieved successfully”

{ "data": { "modelName": "sap_email_business_entity", "modelVersion": 1, "modelType": "sapModel", "metadata": { "supportedLanguages": [ "EN", "DE" ], "capabilities": [ { "entity": "invoiceReferenceNumber" }, { "entity": "vendorId" } ] } } }

NoteThe optional response field "truncated": "True" is added to the response only if the capabilities field exceeds the length prescribed in the model repo. When this happens, all the capabilities of the model are not listed in the response.

Related Information


8.5 Deployments API

Use the Deployments API endpoints to deploy or undeploy custom trained models.

To find out more about the endpoints of the Deployments API, choose the links in the following image.


API Reference

● Get Deployments [page 49]● Post Deployment [page 50]● Get Deployment Status [page 51]● Delete Deployed Model [page 52]● Deployments Lifecycle [page 53]

Note● Inference can be performed using a custom model only if the model is deployed.● Business Entity Recognition pre-trained models can't be deployed. They can be used for inference

directly.

8.5.1 Get Deployments

Get information about all deployed models.

Request



URL Endpoint Path: /deployments

HTTP Method: GET


Request ExampleNo parameters required.

Response


Response Example200 “Deployment details have been retrieved successfully”

{ "data": { "count": 1, "deployments": [ { "deploymentId": "f5e1b1e8-a8b6-4ce7-ba84-1dd36eab4bc0", "modelName": "test_model", "modelVersion": 1, "deploymentStatus": "STARTED", "deployedAt": "2020-07-16 09:58:21.878000" } ] }}

8.5.2 Post Deployment

Deploy a new model.

Request



URL Endpoint Path: /deployments

HTTP Method: POST

Request Parameters


modelName Yes String Name of the model to be deployed

modelVersion Yes Number Version of the model to be deployed


API Reference

Request Example

{ "modelName": "test_model", "modelVersion": 1}

Response


Response Example

202 “Model deployment has been submitted successfully”

{{ "data": { "deploymentId": "f5e1b1e8-a8b6-4ce7-ba84-1dd36eab4bc0", "message": "Model deployment request has been submitted successfully", "modelName": "test_model", "modelVersion": 1, "deploymentStatus": "STARTED" }}

8.5.3 Get Deployment Status

Get status of a deployment request or information of a deployed model.

Request



URL Endpoint Path: /deployments/{deploymentId}

HTTP Method: GET

Request Parameters


deploymentId Yes UUID Deployment ID received in Post Deployment [page 50]


Request Example/deployments/f5e1b1e8-a8b6-4ce7-ba84-1dd36eab4bc0

Response


Response Example

202 “Deployment details have been retrieved successfully”

{ "data": { "deploymentId": "f5e1b1e8-a8b6-4ce7-ba84-1dd36eab4bc0", "modelName": "test_model", "modelVersion": 1, "deploymentStatus": "STARTED", "deployedAt": "2020-07-16 09:58:21.878000" } }

8.5.4 Delete Deployed Model

Undeploy a successfully deployed model.

Request



URL Endpoint Path: /deployments/{deploymentId}

HTTP Method: DELETE

Request Parameters


deploymentId Yes UUID Deployment ID to be deleted

Request Example/deployments/1c3ca641-b4af-42a3-b9cf-5c37de67f254


API Reference

Response


Response Example202 “Deployment details have been retrieved successfully”

{ "data": { "deploymentId": "f5e1b1e8-a8b6-4ce7-ba84-1dd36eab4bc0", "message": "Model test_model version 1 has been undeployed successfully", "modelName": "test_model", "modelVersion": 1, "deploymentStatus": "STARTED" }}

8.5.5 Deployments Lifecycle

See the statuses at the different stages of the deployments lifecycle for the Business Entity Recognition service.

Status Description

STARTED Model deployment is in process.

RUNNING The model has been deployed.

FAILED An error occurred during model deployment.


8.6 Inference API

Use the Inference API endpoints to extract entities from text automatically.

To find out more about the endpoints of the Inference API, choose the links in the following image.


API Reference

● Post Inference Data [page 56]● Get Inference Text [page 64]● Inference Lifecycle [page 65]● Get Inference File [page 65]


8.6.1 Post Inference Data

Provide the text to be extracted and choose the machine learning model (pre-trained or custom) you want to use to extract entities from the text.

Request



URL Endpoint Path: /inference/jobs

HTTP Method: POST

Request Parameters


text Yes String Text sample, for example: "Hello I would like to know the status of invoice 123456 of vendor 7891, regards, John".

datasetId Yes String ID of dataset in which the document is present.

NoteYou can use either the text or datasetId parameter, but you can’t use both in the same request.

modelName Yes String 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_address_entity● sap_email_business_entity● sap_generic_entities● sap_invoice_header

See the list of extracted entities by pre-trained model in Extracted Entities by Pre-trained Model [page 58].


API Reference


modelVersion No Integer The version of the model to be used for inference.

RememberThe modelVersion parameter is required if you use custom trained models.

TipUse the Get Model Details [page 45] endpoint to see the list of available model versions by modelName.

Request Example

You can use text in the requested parameters, as shown in the first example:

{ "text": "Hello, I would like to know the status of the invoice 456789. Regards, John", "modelName": "sap_email_business_entity", "modelVersion": 1 }

Alternatively, you can use datasetId, as shown in the second example:

{ "datasetId": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "modelName": "sap_email_business_entity", "modelVersion": 1 }

Response


Response Example

202 “Inference job submitted”

{ "data": { "id": "16ecf3f0-8574-4a98-9210-d287f67fb79d", "status": "PENDING", "message": "Inference job has been submitted", "modelName": "sap_email_business_entity", "modelVersion": 1 } }


Related Information

Extracted Entities by Pre-trained Model [page 58]

8.6.1.1 Extracted Entities by Pre-trained Model

Explore the Business Entity Recognition pre-trained models.

NoteIf the input text for a pre-trained model is provided in an unsupported language, the request is still processed, but the result may not be accurate. See Supported Languages [page 20].

See Post Inference Data [page 56] payload samples, and the list of entities that can be extracted by the following Business Entity Recognition pre-trained models:

Related Information

sap_address_entity [page 58]sap_email_business_entity [page 59]sap_generic_entities [page 60]sap_invoice_header [page 62]

8.6.1.1.1 sap_address_entity

See the list of entities that can be extracted by the sap_address_entity pre-trained model.

Entity Description

country Name of the country/region in the address.

customerName Name of the sender (usually the sending company).

district Name of the district in the address.

email Email address.

extraName Other name details.

fax Fax phone number.

houseNumber Number of the house in the address.


API Reference

Entity Description

stateProvince Name of the state or province in the address.

street Name of the street in the address.

telephone Telephone number.

zip Postal code of the address.

Example: Post Inference Data Payload:

{ "text":"Warehouse 02 (UK) Ltd c/o Excel Logistics Waindyke Way WF6 1TF. West Yorkshire United Kingdom.", "modelName":"sap_address_entity", "modelVersion":2 }

{ "text":"STAG GmbH Beriiner Chaussee 29, 39307 Genthin Logistik / Einkauf Tel.: 039 33/821 - 223 Fax: 039 33/ 821 - 259.", "modelName":"sap_address_entity", "modelVersion":2 }

8.6.1.1.2 sap_email_business_entity

See the list of entities that can be extracted by the sap_email_business_entity pre-trained model.

Entity Description

invoiceReferenceNumber Invoice number.

vendorId Vendor identification number.


{ "text":"11577210 - FAGOR EDERLAN MEXICO § Dear colleagues, there any way to identify which procurement division has transmitted 1339846 this payment to ABC Ltd. as there is no identification number. Are you able to help? Thank you: Doe, Jane <[email protected]>: 15 May 2019 15:25 To: Doe, John <[email protected]>Cc: Smith, John <[email protected]>: /432216153 328,439.24 Thanks and best Jane. Doe, Jane. Accountant, Procurement Department, Doe Company, S. L. P.Phone+52 444 880 2300. 1114 Doe Company<doe-company.com>",


"modelName":"sap_email_business_entity", "modelVersion":2 }

{ "text":"Von: lena nova <[email protected]> Gesendet: Montag, 21. Januar 2019, 19:13 Uhr An: canu, ana <[email protected]>; [email protected] Betreff: RE: M & B EOOD 2639710315 Sehr geehrter Kunde, ich sende Ihnen Informationen für unsere Zahlung. Proforma 198305906 ist ein Teil der Rechnung 4830476570 / 11.01.2019. Rechnungsdatum Betrag in EUR 4830473772 14.12.2018 9,28 € 4830474632 21.12.2018 29,16 € 4830475244 28.12.2018 46,19 € 4830475919 4.1.2019 9,28 € 198305906 10.1.2019 9,29 € 103,20 € 4830476570 11.1.2019 37,13 198305906 10.1.2019 -9,29 € 27,84 Einen schönen Tag noch! Mit freundlichen Grüßen, lena lena nova Verkaufsleiterin M & B EOOD-Computer Center 11, Angel Kanchev Str; 1000, Sofia, Bulgarien Tel.: + 359 2 981 58 57; Mobil: + 359 889 61 13 21 E-Mail: [email protected] Besuchen Sie uns unter: www.computercenter.bg", "modelName":"sap_email_business_entity", "modelVersion":2 }

8.6.1.1.3 sap_generic_entities

See the list of entities that can be extracted by the sap_generic_entities pre-trained model.

Entity Description

address A place where a person or organization may be communicated with. For example: Amalie-Klemm-Platz 0/9, 48581, Geithain.

cardinal One of the compass points. For example: north, south, east, west, southeast and northwest.

color Visual perception that enables one to differentiate otherwise identical objects. For example: blue, red, orange, dark blue, light green.

dateTime The period of time to which something belongs or takes place. For example: next Friday, today, September 7 2018, 12/12/1992, this evening, mid-November.

distance An extent of space or area. For example: 20 meters, seven miles, ten km, 156 centimeters, 0.8 feet.

duration The time during which something exists or lasts. For example: five days, one year, 27 seconds, two days and 3 hours, 72 weeks.

job A specific duty, role, or function. For example: CTO, farmer, financial accountant, chief operator, actress.

language The system of words or signs that people use to express thoughts and feelings to each other. For example: Chinese, English, Spanish.

location A position or site. For example: San Francisco, Paris, East London, 123 Abbey Road.


API Reference

Entity Description

mass How much something or someone weights. For example: 45 pounds, twenty-one grams, thirty seven kgs, 0.98 mg, 23 kilograms.

money Amount of money in a specific currency. For example: 3.14 euros, eight millions dollars, $6, 56, seventy-eight pesos.

nationality National status. For example: French, Spanish, Australian.

number A character used to represent a mathematical value. For example: one thousand, 3, 9.000, seven million.

ordinal Of a specified order or rank in a series. For example: 3rd, 158th, last, seventh.

organization A company name. For example: Lehman Brothers, NASA, Apple.

percent One part in a hundred. For example: 99%, 2 percent, seventy-seven percent, 12 permyriad.

person The name of a person. For example Michael Adams, Julie D. Armstrong, John.

phone The phone number of a person or a company. For example: +91-22-265 9000, 64 4 437-4746, 0682753582, (123) 123 1234.

pronoun A word that is used instead of a noun or noun phrase. For example: I, we, it, you, us.

set The frequency of an event. For example: every Sunday, each day, monthly, every 2 weeks.

sort Character or qualities of something or someone. For example: most valuable, best, least affordable, cheapest.

speed Rate of movement or performance. For example: 7 mph, 10 km/h, seven meters per second.

temperature Degree of hotness or coldness measured on a definite scale. For example: 25 degrees Celsius, 70°F, seven degC, 5 rankines.

volume A considerable amount. For example: 30 liters, two barrels, 1/2 tbsp.


{ "text":"In 1988, 31.6% of blacks lived in poverty, compared with 10.1% for whites and 26.8% for Hispanics.", "modelName":"sap_generic_entities", "modelVersion":1 }

{


"text":"Sie liegt sechs Kilometer nordöstlich des Stadtzentrums von Pardubice und gehört zum Okres Pardubice.", "modelName":"sap_generic_entities", "modelVersion":1 }

8.6.1.1.4 sap_invoice_header

See the list of entities that can be extracted by the sap_invoice_header pre-trained model.

Entity Description

buyerAddress The address of the buyer.

buyerName The name of the buyer.

currency Currency of the invoice in ISO-3 format. For example: USD for U.S. dollar, EUR for euro and AUD for Australian dollar.

deliveryDate Date of the delivery in extended ISO 8601 format (YYYY-MM-DD).

deliveryNoteNo Unique identification on the invoice following the goods.

dueDate Date of the delivery in extended ISO 8601 format (YYYY-MM-DD).

employeeName Name of the person the invoice was sent to. Often referred to as “Attention to: ABC” or “Attn: ABC”.

invoiceNo The number identifying the invoice.

paymentTerms It indicates when payments should be made and how.

purchaseOrderNo Number of the buyer’s purchase order, if mentioned.

shippingAmount The shipping or handling amount.

shipToAddress Address of the receiver: only one box for the street, city, and country/region of the receiver.

subtotalAmount Amount without taxes and shipping/handling costs.

tax1Amount Primary tax applied to the invoice (usually a federal tax).

tax2Amount Secondary tax applied to the invoice.

tax3Amount Tertiary tax applied to the invoice.

tax1Description Description of primary tax.

tax2Description Description of secondary tax.


API Reference

Entity Description

tax3Description Description of tertiary tax.

tax1Rate Primary tax rate applied to the invoice.

tax2Rate Secondary tax rate applied to the invoice.

tax3Rate Tertiary tax rate applied to the invoice.

totalAmount Sum of subtotal, taxes, special handling charges, and shipping charges, without discounts, or total amount due and payable.

vendorAddress Address of the vendor: only one box for the street, city, and country/region of the vendor.

vendorBankAccountNo Bank account number of the vendor.

vendorName Name of the vendor of the invoice (usually the sending company). For example, SAP SE.

vendorTaxId Tax identifier of the vendor’s business entity (unique to each vendor).


{ "text":"-----Original Message----- From: Duma Trunchi, Regina <[email protected]> Sent: Thursday, December 20, 2018 4:33 PM To: Dubey, Ashish <[email protected]> Cc: Grc, Sony <[email protected]> Subject: CLEARING//226.530,63eur//phoxdistri Hi Ashish, Please do the clearing as per the attachment. Thank you, Duma-Trunchi Regina Accounts Receivable Finance company Pvt Ltd F&A services operated by AKAI Pvt Ltd Registered office: The Heights, 116 Glenurquhart Road, BALLAUGH, Surrey. KT27 0XW. UK Registered Company Number: 2522874", "modelName":"sap_invoice_header", "modelVersion":1 }

{ "text":"Order number 12345678 Order type Sales Force Order abcdef Date 01/01/2001 Customer number 9876543 Customer service 123/ 456 6789 E-mail [email protected] Your Reference: Order receipt confirmation Customer address 508 W. St Margarets St. Brooklyn, NY 11228 Billing address 508 W. St Margarets St. Brooklyn, NY 11228 Ordered by Fenton Moon Shipping type: UPS 2nd Day Air PM Terms of payment: 30 Days Net due Your message: Item Material Description Qty. Price per Unit Net steel gray / Length 12 mm / 1 35.00 35.00 Gross Amount USD 35.00 Freight/ packaging USD 15.00 Tax 2 % USD 1 Tax 4 % USD 2 Total amount USD 53", "modelName":"sap_invoice_header", "modelVersion":1 }


8.6.2 Get Inference Text

See the text extraction results and the confidence level of the machine learning model.

Request



URL Endpoint Path: /inference/jobs/{id}

HTTP Method: GET

Request Parameters


jobId Yes UUID Job ID received in Post Inference Data [page 56]

Response


Response Example

200 “OK”

{ "data": { "id": "f5e1b1e8-a8b6-4ce7-ba84-1dd36eab4bc0", "status": "SUCCESS", "result": [{ "vendorId": [{ "value": "67456890", "confidence": 0.93 }], "invoiceReferenceNumber": [{ "value": "456789", "confidence": 0.85 }] }] } }


API Reference

8.6.3 Get Inference File

Get the inference results file containing the extracted entities and confidence.

Request



URL Endpoint Path: /inference/jobs/{jobId}/document

HTTP Method: GET

Request Parameters


jobId Yes UUID Job ID received in Post Inference Data [page 56]

Response


Response Example200 “OK”

NoteIf the response code is 200, the response body contains a link that allows you to download the file.

8.6.4 Inference Lifecycle

See the statuses at the different stages of the inference lifecycle for the Business Entity Recognition service.

Status Description

PENDING Inference is in progress.

SUCCESSFUL The entities have been successfully predicted.

FAILED An error occurred during entity prediction.


8.7 Common Status and Error Codes

Code Reason

200 OK

201 Request was created

202 Request was accepted

400 Bad request

401 Unauthorized (for example, no token or bad token)

403 Forbidden

404 Not found


API Reference

Code Reason

405 Not allowed

413 Request entity is too large

415 Unsupported media type

429 Too many requests

500 Internal server error

8.8 Technical Constraints

All Business Entity Recognition endpoints exposed to the end user have strict technical limits. See details in the following table.

NoteThe technical limits listed here are relevant only to users of the Standard service plan for enterprise accounts. See Service Plans [page 16].

Variable Maximum Limit

Total number of datasets per tenant 10

Dataset size 200 MB

Total number of documents per training dataset 20

Total number of documents per inference dataset 5

Document size 10 MB

Total number of trained models per tenant 10

Total number of deployments per tenant 10

Concurrent trainings allowed per tenant 1

Note● If you exceed any technical limit, the API request fails.● Use the following endpoints to make sure the APIs are not blocked:

○ DELETE /models/{modelName}/versions/{modelVersion}○ DELETE /datasets/{datasetId}○ DELETE /datasets/{datasetId}/documents/{documentId}


○ DELETE /deployments/{deploymentId}

Related Information

Free Tier Option Technical Constraints [page 68]

8.8.1 Free Tier Option Technical Constraints

When using the free tier option for Business Entity Recognition, be aware of the following technical limits:

NoteThe technical limits listed here are relevant only to users of the free tier option for Business Entity Recognition. See Service Plans [page 16].

Variable Maximum Limit

Total number of datasets 1

Total number of documents per dataset 10

Document file size 10 MB

Total number of trainings

NoteOnly successfully completed trainings are considered.

1

Total number of custom models

NoteDeletion of custom models is not allowed.

1

Total number of inference requests per month 30

Total number of inference characters per month 120,000


API Reference

9 Consuming the Service via AI API

Find out how to consume Business Entity Recognition using the AI API from SAP AI Core.

Prerequisites

You have a service instance and service key for Business Entity Recognition. See tutorial Use Free Tier to Set Up Account for Business Entity Recognition and Get Service Key .

TipThe booster Set up account for Business Entity Recognition is available both for the free tier option, and the standard service plan.

See in the table below the main operations you can call to consume Business Entity Recognition via AI API. For more information, see AI API Concepts and About the AI API.

NoteFor now, the integration between Business Entity Recognition and the AI API is only available for enterprise accounts using either the Free or the Standard service plans. See Service Plans [page 16].

You can use Postman, curl or any other REST client to make calls to the AI API and Business Entity Recognition APIs. If you choose Postman, get ahead by using the Business Entity Recognition and AI API Postman Environment and Collection JSON files.

Business Entity RecognitionConsuming the Service via AI API PUBLIC 69

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdevelopers.sap.com%2Ftutorials%2Fcp-aibus-ber-booster-free-key.html

http://help.sap.com/disclaimer?site=https%3A%2F%2Fdevelopers.sap.com%2Ftutorials%2Fcp-aibus-ber-booster-free-key.html

https://help.sap.com/viewer/2d6c5984063c40a59eda62f4a9135bee/CLOUD/en-US/05f41ee00e634e958cddd5e38e31569f.html

https://help.sap.com/viewer/2d6c5984063c40a59eda62f4a9135bee/CLOUD/en-US/716d4c38e3054c93a9d481b51cc66298.html

https://help.sap.com/doc/e4de5c42e09d4c7a8178699ebaec588b/SHIP/en-US/AI_API.zip

https://help.sap.com/doc/e4de5c42e09d4c7a8178699ebaec588b/SHIP/en-US/AI_API.zip

Operation HTTP Method URL Additional information

Get XSUAA OAuth Token GET {{auth_url}}/oauth/token?grant_type=client_credentials

Before sending this request, edit Postman environment to add values from your Business Entity Recognition service key in the following environment variables:

● auth_url: to be filled from the uaa.url section of the service key

● client_id: to be filled from the uaa.clientid section of the service key

● client_secret: to be filled from the uaa.clientsecret section of the service key

● url: to be filled from the url section of the service key

The {{access_token}} is valid for 12 hours. After that, you need to generate a new one. To do so, send this request once again.

When sending the next request after this one, List Scenarios, for example, set Type to Bearer Token on the Authorization tab and enter {{access_token}} in Token. Always repeat this step after creating a new {{access_token}}.

List Scenarios GET {{url}}/v2/lm/scenarios

Business Entity Recognition supports the scenario BusinessEntityRecognition.

Get Scenario Details GET {{url}}/v2/lm/scenarios/{{scenario_id}}

Before sending this request, enter your scenario_id in the Postman environment variable scenario_id.


Consuming the Service via AI API


Get Scenario Versions GET {{url}}/v2/lm/scenarios/{{scenario_id}}/versions

List Executables GET {{url}}/v2/lm/scenarios/{{scenario_id}}/executables

Business Entity Recognition supports the following executables:

● TrainingExecutable● InferenceExecutable● ModelActivationExecut

able

Based on the response from this request, enter the following values in the Postman environment:

● training_executable_id

● inference_executable_id

● model_activation_executable_id

Get Executable Details GET {{url}}/v2/lm/scenarios/{{scenario_id}}/executables/{{training_executable_id}}

List Datasets GET {{url}}/api/v1/datasets

Create Dataset POST {{url}}/api/v1/datasets

Before sending this request, in Body raw, enter a description for your training dataset

After sending this request, your dataset_id is added automatically in the Postman environment variable dataset_id.

Delete Dataset DELETE {{url}}/api/v1/datasets/{{dataset_id}}



Get Dataset Details GET {{url}}/api/v1/datasets/{{dataset_id}}

Upload Document POST {{url}}/api/v1/datasets/{{dataset_id}}/documents

Before sending this request, in Body form-data, upload your training dataset documents.

After sending this request, enter your document_id in the Postman environment variable document_id.

List Documents GET {{url}}/api/v1/datasets/{{dataset_id}}/documents

Delete Document DELETE {{url}}/api/v1/datasets/{{dataset_id}}/documents/{{document_id}}

Create Dataset Artifact POST {{url}}/v2/lm/artifacts

In Body raw, enter the following:

{ "labels": [], "description": "<description>", "kind": "dataset", "name": "<dataset name>", "url": "minio://{{dataset_id}}", "scenarioId": "{{scenario_id}}" }

After sending this request, your dataset_artifact_id is added automatically in the Postman environment variable dataset_artifact_id.




Create Training Configuration POST {{url}}/v2/lm/configurations


{ "executableId": "{{training_executable_id}}", "name": "training", "inputArtifactBindings": [{ "key":"dataset", "artifactId":"{{dataset_artifact_id}}" }], "parameterBindings": [{ "key":"modelName", "value":"test_model" }], "scenarioId": "{{scenario_id}}" }

After sending this request, your training_configuration_id is added automatically in the Postman environment variable training_configuration_id.

Create Training Execution POST {{url}}/v2/lm/executions

After sending this request, your training_execution_id is added automatically in the Postman environment variable training_execution_id.



Get Training Execution Details

GET {{url}}/v2/lm/executions/{{training_execution_id}}

Patch Training Execution PATCH {{url}}/v2/lm/executions/{{training_execution_id}}

Before deleting a running training, you need to stop it. To stop the training, send this PATCH request. After that, the training execution status changes to “STOPPED”. You can now delete the training using the DELETE request.

Delete Training Execution DELETE {{url}}/v2/lm/executions/{{training_execution_id}}

Get Metric Details GET {{{url}}/v2/lm/metrics?executionIds={{training_execution_id}}




Create Model Activation Configuration

POST {{url}}/v2/lm/configurations

Before sending this request, enter your model_artifact_id in the Postman environment variable model_artifact_id.


{ "executableId": "{{model_activation_executable_id}}", "name": "model_activation", "inputArtifactBindings": [{ "key":"model", "artifactId":"{{model_artifact_id}}" }], "parameterBindings": [], "scenarioId": "{{scenario_id}}" }

Deploy Model POST {{url}}/v2/lm/deployments

Before sending this request, enter your model_activation_configuration_id in the Postman environment variable model_activation_configuration_id.

Get Deployment Details GET {{url}}/v2/lm/deployments/{{deployment_id}}

Before sending this request, enter your deployment_id in the Postman environment variable deployment_id.

Patch Deployment PATCH {{url}}/v2/lm/deployments/{{deployment_id}}



Create Inference Configuration

POST {{url}}/v2/lm/configurations


{ "executableId": "{{inference_executable_id}}", "name": "inference", "inputArtifactBindings": [{ "key":"model", "artifactId":"{{model_artifact_id}}" }], "parameterBindings": [], "scenarioId": "{{scenario_id}}" }

Create Inference Execution POST {{url}}/v2/lm/executions

Before sending this request, enter your inference_configuration_id in the Postman environment variable inference_configuration_id.

Get Inference Execution Details

GET {{url}}/v2/lm/executions/{{inference_execution_id}}

Before sending this request, enter your inference_execution_id in the Postman environment variable inference_execution_id.



10 Security

Get an overview on the security information that applies to Business Entity Recognition. Learn about the main security aspects of the service and its components.

General Information

Business Entity Recognition provides a set of RESTful application programming interfaces (APIs) over which client applications can directly communicate with the service, in order to extract entities from text documents automatically. All communication to the APIs is secured via the HTTPS protocol. Business Entity Recognition is a pure API-based service and provides no graphical user interface and has no dedicated frontend.

Related Information

User Administration, Authentication and Authorization [page 77]Data Protection and Privacy [page 78]Auditing and Logging Information [page 80]Front-End Security [page 82]

10.1 User Administration, Authentication and Authorization

Introduction

Cloud Foundry

For Business Entity Recognition, the standard user authentication and authorization mechanisms provided by SAP Business Technology Platform (SAP BTP) for Cloud Foundry is used. Following the standard mechanism of Cloud Foundry, the service consumer can create an instance of the Business Entity Recognition service and then generate credentials to communicate with the service instance (see Using Services in the Cloud Foundry Environment in the SAP BTP documentation for details on this process).

The credentials enable the user to retrieve a JSON Web Token (JWT), which is necessary for the secure communication between any client and the service. Overall, the communication with the service is secured by the OAuth 2.0 protocol. For more information on this topic, see Security in the SAP BTP documentation.

Business Entity RecognitionSecurity PUBLIC 77



https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/e129aa20c78c4a9fb379b9803b02e5f6.html

User Administration and Provisioning

The application does not manage or provision users.

10.2 Data Protection and Privacy

Introduction

Data protection is associated with numerous legal requirements and privacy concerns. In addition to compliance with general data privacy acts, it is necessary to consider compliance with industryspecific legislation in different countries or regions. This section describes the specific features and functions that SAP provides to support compliance with the relevant legal requirements and data privacy.

This section and any other sections in this Security Guide do not give any advice on whether these features and functions are the best method to support company, industry, regional or country/regionspecific requirements. Furthermore, this guide does not give any advice or recommendations with regard to additional features that would be required in a particular environment; decisions related to data protection must be made on a case-by-case basis and under consideration of the given system landscape and the applicable legal requirements.

NoteSAP software supports data protection by providing security features and specific data protection-relevant functions such as functions for the simplified blocking and deletion of personal data. SAP does not provide legal advice in any form. The definitions and other terms used in this document are not taken from any given legal source.

Business Entity Recognition generally requires the following type of data:

Data Purpose

Text data for inference

Consists of a single phrase of text, which is submitted by a user in order to receive machine learning predictions. Data is stored for 24 hours until the machine learning predictions have been generated, and is automatically deleted afterwards.

Data for training Consists of one more JSON files containing texts and userdefined annotations (ground truth) that are used in the deep learning training process to create a model that can predict the userdefined words from the inference text.

Read Access Logging

The data used by Business Entity Recognition is controlled and managed by the consuming application or customer that calls the service APIs. However, the service does not have any means to verify whether the data


Security

uploaded to the service contains any personal information. Therefore, Business Entity Recognition does not support logging of read access to (sensitive) personal data.

Information Report

The data used by the Business Entity Recognition service to extract entities from text documents automatically is controlled and managed by the consuming application or customer that calls the service APIs. Business Entity Recognition does not have any means to verify whether the data uploaded to the service contains any personal information. Therefore, the service does not provide any means to retrieve personal data of specific individuals. It is recommended that the consuming application or customer, that uses the service, provides personal data reports to its users about the data being stored and transferred to Business Entity Recognition for processing.

Deletion of Personal Data

Business Entity Recognition does not explicitly process any personal data. The service does not have any means to verify whether the data uploaded to the service contains any personal information. Therefore, no dedicated functionality for the deletion of personal data is available. See the table below for more details on the deletion of inference and training data.

Data Deletion

Data for inference Inference data is processed immediately, it is not stored temporarily anywhere.

Data for training Training data is stored in the cloud storage. When using the Business Entity Recognition service, you can delete the datasets or specific files. When you delete the Business Entity Recognition service instance, all the uploaded data is deleted.

Change Log

The data used by Business Entity Recognition is controlled and managed by the consuming application or customer that calls the service APIs. The service itself does not allow any change to the content of the uploaded data. Therefore, Business Entity Recognition does not support logging of data change.

Consent

According to Personal Data Processing Agreement for SAP Cloud Services, SAP acts as data processor. Thus, customers are responsible for obtaining relevant consent to process personal data, including when applicable approval by controllers to use SAP as a processor.


10.3 Auditing and Logging Information

Here you can find a list of the security events that are logged by the Business Entity Recognition service.

Security events written in audit logs

Event grouping What events are loggedHow to identify related log events Additional information

Dataset and training related events

Successful dataset creation "create_dataset" and ID consisting of: targetTenant {tenant_id}

Attribute "old_value" is "does_not_exist" and "new_value" is "created"

In the log events, {tenant_id} is the ID of the tenant used to access the service.

Successful dataset deletion "delete_dataset" and ID consisting of: targetTenant {tenant_id}

Attribute "old_value" is "existed" and "new_value" is "deleted"

Successful document upload "upload_document" and ID consisting of: targetTenant {tenant_id}

Attribute "old_value" is "does_not_exist" and "new_value" is "uploaded"

Successful document deletion

"delete_document" and ID consisting of: targetTenant {tenant_id}


Successful training job submission

"training_job_submission" and ID consisting of: targetTenant {tenant_id}

Attribute "old_value" is "existed" and "new_value" is "submitted"

Malware detection in document upload and dataset creation

"data\":\"Unexpected Error [ACTION : create_dataset, STATE : Malware detected]\"


Security


Model related events Successful model deployment

"model_deploy" and ID consisting of: targetTenant {tenant_id}

Attribute "old_value" is "does_not_exist" and "new_value" is "deployed"

Successful model undeployment

"Model Undeployment" and ID consisting of: targetTenant {tenant_id}

Attribute "old_value" is "deployed" and "new_value" is "undeployed"

Successful model deletion "delete_model" and ID consisting of: targetTenant {tenant_id}


Tenant related events Tenant successful provisioning

"Tenant Provision" and ID consisting of: targetTenant {tenant_id}

Attribute "old_value" is "does_not_exist" and "new_value" is "OnBoarded successfully"

Tenant successful de-provisioning

"Tenant De-Provision" and ID consisting of: targetTenant {tenant_id}

Attribute "old_value" is "existed" and "new_value" is "OffBoarded successfully"

Tenant provisioning failure "data\":\"Unexpected Error [ACTION : Tenant Provision, STATE : OnBoarding failed]\"

Tenant de-provisioning failure

"data\":\"Unexpected Error [ACTION : Tenant De-Provision, STATE : OffBoarding failed]\"



Unauthorized "data\":\"Unexpected Error [ACTION : Authorization, STATE : Unauthorized]\"

Related Information

Audit Logging in the Cloud Foundry Environment

10.4 Front-End Security

Business Entity Recognition does not have any user interface component. All functionalities are delivered via web services, JSON over HTTPS.

The service is a backend-only service component and not designed to be invoked by a web browser. Additionally, outputs returned by the service depend on the data submitted to it. Therefore, a consumer of the service should sanitize the data submitted to the service and returned by it to avoid script injection attack.


Security

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/f92c86ab11f6474ea5579d839051c334.html

11 Monitoring and Troubleshooting

Find out how to get support.

Getting Support

If you encounter an issue with this service, we recommend to follow the procedure below.

Check Platform StatusCheck the availability of the platform at SAP Trust Center .

For more information about selected platform incidents, see Root Cause Analyses.

Check Guided AnswersIn the SAP Support Portal, check the Guided Answers section for SAP Business Technology Platform. You can find solutions for general platform issues as well as for specific services there.

Contact SAP SupportYou can report an incident or error through the SAP Support Portal. For more information, see Getting Support.

Please use the following component for your incident:

Component Name Component Description

CA-ML-BER Business Entity Recognition

When submitting the incident, we recommend including the following information:

● Region information (Canary, EU10, US10, for example)● Subaccount technical name● The URL of the page where the incident or error occurs● The steps or clicks used to replicate the error● Screenshots, videos, or the code entered

Business Entity RecognitionMonitoring and Troubleshooting PUBLIC 83

http://help.sap.com/disclaimer?site=https%3A%2F%2Fwww.sap.com%2Fabout%2Ftrust-center%2Fcloud-service-status.html

https://help.sap.com/viewer/product/SCP_RCA/Latest/en-US

http://help.sap.com/disclaimer?site=https%3A%2F%2Fga.support.sap.com%2Fdtp%2Fviewer%2Findex.html%23%2Ftree%2F2065%2Factions%2F26547

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/5dd739823b824b539eee47b7860a00be.html

Important Disclaimers and Legal Information

HyperlinksSome links are classified by an icon and/or a mouseover text. These links provide additional information.About the icons:

● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this:

● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any

damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.

Videos Hosted on External PlatformsSome videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the control or responsibility of SAP.

Beta and Other Experimental FeaturesExperimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up.The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example CodeAny software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Bias-Free LanguageSAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities, genders, and abilities.


Important Disclaimers and Legal Information

Business Entity RecognitionImportant Disclaimers and Legal Information PUBLIC 85

www.sap.com/contactsap

© 2022 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.

Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.

Please see https://www.sap.com/about/legal/trademark.html for additional trademark information and notices.

THE BEST RUN

https://www.sap.com/about/legal/trademark.html