6 Data Workbench APIs
6.3 Data Workbench Import API
Use this API to import data into SAP Cloud for Customer.
Note
This API allows only import of data. The API can’t be used to import attachments.
This API creates a migration project, a collection of import tasks, in Data Workbench.
Authentication: The API uses the token received from the Authentication API.
Authorization: You must be a key user and have the Data Workbench work center view assigned. Also, you must also have the work center view of the relevant object assigned.
Request URL: <tenant_host_name>/api/v1/import?token=<token>
HTTP Method: POST Request Query Parameters:
Parameter Name Description Sample Value
token Value for this parameter is provided by
the Data Workbench Authentication API.
Property Name Description Sample Value
projectName The name of the migration project. It represents the collection of tasks sub
mitted by the API.
Lead_Migration_01
taskType Use this code to state the type of task;
for example, Complete Business Object Import. Valid Values:
operation Use this code to state the operation to
be performed on the data such as in
sert/upsert.
Property Name Description Sample Value ignoreBlankValues A boolean value to determine whether
blank columns in the file are considered or ignored during import.
Valid Values: true/false
true
simulation A boolean value to identify whether the task is in simulation mode. In simula
tion mode, data isn’t saved.
Valid Values: true/false
false
initialLoad A boolean value to identify whether the migration mode is on or off for the task.
Valid Values: true/false
true
serviceName The OData Service that must be used
for the import. See Services Available in Data Workbench.
customer
customService A boolean value to identify whether the OData Service to be used is a custom or standard service.
Valid Values: true/false
false
rootEntitySetName Applicable for import of Complete Business Object: Name of the root en
tity set () to which the data is to be up
loaded.
Note
Entity type of standard services can be seen here: SAP Cloud for Customer OData 2.0 Reference
CorporateAccountCollection
entitySetName Applicable for import of Individual Business Object.
Name of the entity set to which the data is to be uploaded.
Note
Entity type of standard services can be seen here: SAP Cloud for Customer OData 2.0 Reference
sequence You can provide the numeric value to
define the sequence of execution of tasks in a project. This field is a manda
tory one.
1
Property Name Description Sample Value
lastTask A boolean value to indicate whether the
current task is the last of the project. If it is, Data Workbench starts processing.
Valid Values: true/false
true
errorThreshold This numeric value defines the percent
age of error after which the execution of other tasks in the sequence is stopped for the project, the tasks in sequence is also stopped.
30
dataFile This field contains the binary form of
the zip file that must be uploaded for the import.
fileName Applicable for import of Individual
Business Object.
Enter the file name in this field. If no name is given, the tool generates it in the following format:
<EntityName_sequence>
Response:
Status Code Response Description
200 {"taskName":"<taskName>"} The name of the import task. It’s seen under the project in Monitor.
401 Unauthorized The token is invalid.
400 Error. Verify service name, entity
nameisCustom, and retry.
Error. Verify 'type' and 'operation' and retry.
OData Service details provided are in
correct.
The operation isn’t support by the ob
ject.
500 Task limit reached. Retry after some
time.
Internal error; create an SAP incident.
Maximum of 10 tasks can be submitted.
Retry after some time.
Some unknown exception has occur
red. Create an SAP incident.
404 Service Unavailable Check the URL and the HTTP method.
If unresolved, create an SAP incident.
6.4 Monitor
Check the status of your migration project with Monitor.
To check status, go to Data Workbench Monitor .
Note
You can add Project Name using Adapt.
When you create a project and click the project name in Monitor, the system opens a model dialogue box with the list of all the tasks that belong to the project.
You can also monitor the submitted task using the following OData endpoint:
https://<Your_C4C_Tenant>/sap/c4c/odata/v1/dwbmonitor/ScenarioCollection?
$filter=ScenarioName%20eq%20%27<Task_Name>%27
Note
Use your SAP Cloud for Customer tenant credentials to sign in to the endpoint.
Life Cycle of Migration project:
● When you submit a task to the API with the required details, the system creates a migration project entry with the Project Name as provided.
● When the project is created, its status is Inactive. All the tasks are created with the In Queue status.
● After the system receives lastTask marked as true, the first task in the sequence is processed, and the project is set to In Process. Note that the first task is processed as soon as the Data Workbench is available.
● When all the tasks of the project are completed, the project is set to Finished.
● If the system crosses the error threshold for one of the tasks, the next task in the sequence is not picked for processing, and the project is set to Pending. In such a case, follow these steps:
1. Correct the errors and upload the corrected data via the Data Workbench UI.
2. Resume the project by selecting the project and clicking the Resume button from the action menu.
The project is set to In Process and the system picks up the next task in sequence for processing.
● You can stop the project from the action menu. This means that the task in process is stopped, and other tasks are not picked up for processing.
● You can stop a task of the project by selecting the task and clicking Stop. After the task stops, the next task in sequence is processed.
● When you delete an inactive process from the action menu, all the related tasks are also deleted.
Note
● The API must be called sequentially. Parallel calling of the API may result in unpredictable behavior.
● At a time, only one task is to be executed.
● A maximum of 10 tasks can be submitted via the API across the projects. The next task is accepted only when the previous task is finished.
Important Disclaimers and Legal Information
Hyperlinks
Some 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 Platforms
Some 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 Features
Experimental 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 Code
Any 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.
Gender-Related Language
We try not to use gender-specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders.
www.sap.com/contactsap
© 2021 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.