SAP Build Apps - upload files to SAP Document Information Extraction (DOX) Service with camera

[mingkho]

Introduction

Uploading files is a common requirement in various business scenarios. As SAP Build Apps developer, we are often required to add file upload capability into our apps to fulfill business requirements and enhance user experience.

One of such use case is to upload documents to SAP Document Information Extraction (DOX) Service to process large business documents that have content in headers and tables. You can use the extracted information, for example, to automatically process payables, invoices, or payment notes and make sure that invoices and payables match.

Its Upload Document API requires you to sent a POST request with "multipart/form-data" payload.

In this blog, I will show how you can make use of the new "HTTP Destination Request" flow function along with "Take photo" flow function to achieve that.

By the end of this blog, you will learn how to:

1. Set up your DOX service destination to work with Build Apps.
2. Install your destination to be used in Build Apps and test the connection to your destination in Build Apps.
3. Use "Take photo" to let user to capture photo with device and pass the resulting image to "HTTP destination request"
4. Use "HTTP destination request" to upload the image to your DOX service API via the installed destination.

Pre-requisites

1. You must have SAP Build Apps already subscribed in your subaccount.
2. You must have SAP Document Information Extraction Service subscribed.
3. All required roles for SAP Builds Apps and Document Information Extraction Service are assigned accordingly to your user.

Setting up Destination for Document Information Extraction Service

If you already have a working destination to your DOX service, you can use it or clone it while referring to the steps below to make it compatible with the examples in this blog:

1. Go to SAP BTP cockpit and create a destination pointing to your DOX instance.
   • For this example, I recommend that the URL of the destination is pointing to the root of your DOX service instance:
     • Example: https://aiservices-dox.cfapps.eu10.hana.ondemand.com/document-information-extraction/v1/
     • We will append additional relative path to your destination later when using the "HTTP Destination Request" flow function.
   • For authentication related configurations, you can refers to your DOX instance's service key file. These configuration are inside the "uaa" section of the file.
     • TIPS: Token Service URL typically ends with /oauth/token. The UAA URL you copied from the service key usually doesn't contain that. So, you must append /oauth/token yourself when entering the URL to the Token Service URL field.
   • Add the required additional properties in the destination for Build Apps' usage:
     • HTML5.DynamicDestination: true
     • BuildApps.Enabled: true
     • BuildApps.ApiType: rest
     • MobileEnabled: true
   • These are the minimal properties required for Build Apps, you may add other properties for other purposes too. Example:
     
     Hint: "Check Connection" in the BTP Destination cockpit only tells you that the URL is reachable, it does not indicate that the authentication is set up correctly. So, you should not rely solely on it to tell you that your destination is configured correctly.

Install DOX Service Destination in Your Build Apps Project

1. Open your Build Apps project.
2. Go to “Integrations” tab.
1. Press on “Add Integration” button.
2. Press on the “BTP DESTINATIONS” button in the SAP Systems card.
3. Search for your DOX destination and select it. It should show a screen with “The destination was recognised as REST api” message.
   
   Note:
   • If you can't find your destination, do check that you have added the BuildApps.Enabled=true property in your destination.
   • If you don't see that message,do check that you have added the BuildApps.ApiType=rest property in your destination.
4. Press "INSTALL INTEGRATION" button to install the destination.
5. (Optional) Testing the connection to destination using Entity's list operation
   1. You can test the connection to your DOX destination by creating adding a REST API data entity and use it to call one of the GET API available in your service, assuming you have the right access. Otherwise, you can skip this steps or choose different API to test with.
   2. Press on the "Add REST API Data Entity" button. You should get a dialog pop up.
   3. In the dialog, enter the following information:
      • Name: Documents
      • Autogenerate configuration: enabled
      • Entity path within the API: /document/jobs
      • Enable Capabilities: enable "list" and uncheck the rest of them
      • Press "Add" button
        
   4. You should now see the DocumentJobs entity and its Fields and more.
      If you are seeing error here and it couldn't generate any Fields for you, then it's likely there's something wrong with your path, or destination configuration. Make sure to check your destination's URL and authentication configuration.
   5. You can use "Browse Real Data" button to check if you can see expected data entries and no errors.
      
      
   6. If you are not seeing any errors, it means the connection to your destination is good for usage.
6. You can now Exit this page.

Using HTTP Destination Request to Upload File

1. Go to “User Interface” tab.
2. Press on the button (or any other UI control) that you wish to use to trigger the file upload and then press on the "Add logic to <your control>" at the bottom of the screen. This should show the Logic Canvas.
3. Press the “Marketplace” button under the "Core" tab on the left panel.
1. Search for “HTTP destination request” flow function and install it.
   
2. After it is installed you should see it in the "INSTALLED" tab of the Logic Canvas.
   
4. You are now ready to use “HTTP destination request” to upload file:
   1. From the "CORE" tab, scroll down to the "Device" category and drag “Take Photos” flow function to the logic flow canvas.
      ℹ️ Note: "Take photo" flow function is currently only available when you run your app in mobile device. It will do nothing when triggered as web app.
   2. Link the button's “Event: Component tap” node to the “Take photo” node.
      
   3. Go to the "INSTALLED" tab and drag “HTTP destination request” to the logic flow canvas.
   4. Link “Take photo” node’s output port 1 to the “HTTP destination request” node, because we want to pass the photo taken by user to the “HTTP destination request” node.
      
   5. Click on the “HTTP destination request” node and on its property panel.
      1. In the Destination dropdown select your installed destination.
      2. Set the “HTTP method” as “POST”.
      3. Set the “Request body type” as “multipart/form-data”.
      4. Set the “Request body” and add entries for each part needed for the target API. In this case, we will be using the SAP Document Information Extraction Upload Document API which requires 2 properties:
         

         Key	Value
         options	Bind this value to formula using the following sample: ENCODE_JSON({"schemaName":"SAP_invoice_schema","clientId": "default","documentType":"invoice","receivedDate":"2024-12-01"}) Note: In real use cases, you can use variable to store these information instead, but you must always use ENCODE_JSON to convert them to JSON encoded text
         file	Bind this value to formula using the following sample: MERGE([outputs["Take photo"].photoFile,{"mimeType":"image/jpeg"}]) You will see some errors in the formula editor about unassignable object, you can safely ignore that. Note: This formula is needed due to an existing issue with missing mime-type in the Take photo output. Once the issue is fixed in the near future, you can simply bind this value to "Output of another node" > "Take photo / Photo file".

         
         Value for "options" key:
         
         Value for "file" key:
         
         Resulting list of key-values for the "Request body":
         
      5. Expand the Optional Inputs section of the "HTTP destination request":
         In "Path" set "/document/jobs" because that's the path to the API for uploading document to start an information extraction job. The path specified here will be appended to your destination in the final request.
      6. Your "HTTP destination request" is now ready.
   6. Drag and drop 1 "Toast" flow function to the Logic Canvas and link them to each of the output port 1 of the “HTTP destination request” flow function.
      For Toast linked to port 1 you can bind its message to formula with the following:

      "Result: " + outputs["HTTP destination request"].successStatusText

   7. Drag and drop 2 "Alert" flow function to the Logic Canvas and link them to each of the output ports of the “HTTP destination request” flow function.
      1. For the Alert linked to port 2, you can bind its message to formula with the following:

         "Error from backend: " + outputs["HTTP destination request"].failureStatusText

      2. For the Alert linked to port 3, you can bind its message to formula with the following:

         "Error: " + outputs["HTTP destination request"].error

   8. The logic canvas should looks like this:
      
   9. Save your project and you are ready to preview your app and test the file upload.

Preview and Trigger File Upload

"Take photo" currently only works in iOS or Android platform, therefore we will do the preview on your mobile devices.

• On your mobile device, install the "SAP Build Apps Preview" app from Apple App Store or Google Play Store.
• After the app is installed, launch the app on your mobile device and press the center card to create a login PIN code. You should see a temporary PIN code generated.
• Go back to your Build Apps project in the browser and press on the "Preview" button
• In the "Preview on your device" section, enter your temporary PIN code into the text box and press "Confirm pin". You should get "Mobile preview authenticated" message if it works.
• Go back to the"SAP Build Apps Preview" app on your mobile device, you should see list of your apps that can be previewed.
• Locate and open your app.
• When the app is loaded, press the file upload button:
  
• That should prompt you for permission to take photo (if this is the first time), approve it and take a photo of an invoice.
• Once the photo is taken the upload via "HTTP destination request" should happen and you should get a result soon.
• After successful upload you should get "Result: Created" toast:
  
• If you check the Document Information Extraction web app, you should see your photo is now uploaded and queued for extraction.
• Once the extraction is completed you should see be able to see it's result.
  

Summary

As summary, in this blog, you have learned how to set up your Build Apps project to make use of the "HTTP destination request" and "Take photo" to upload file using multipart/form-data payload.

If you are interested with uploading file to other services such as SAP Document Management Service using "Pick files" and "HTTP destination request" in SAP Build Apps, you can visit this blog: SAP Build Apps - upload files to SAP Document Management Service (DMS) repository with file picker

[tomasz_janasz]

Thank you for this blog. This is a great asset and an accelerator for our customers and partners explaining how to build apps for our Document Information Extraction service (DOX)! Looking forward to more posts around DOX.

[naimkhans_babi]

Thank you so much for the wonderful explanation, with your help I manage to complete the requirement.  Thank you once again and season's greetings.

Best Regards

Naim😊

[Amit86]

Thanks so much, this was very helpful! This is a textbook example of how a clear and concise blog should be written.