IBM Developer

Tutorial

Extract structured data from messy documents with Docling for IBM watsonx and IBM Bob

Build a purchase order processing application using spec-driven development to convert unstructured documents into actionable insights

By Ahmed Azraq

On this page

Organizations struggle to extract structured data from documents like purchase orders that frequently exist in a variety of formats (for example, PDFs, images, emails, or scanned documents).

In this tutorial, you learn how to convert unstructured documents ("messy" documents) into structured data using Docling for IBM watsonx and IBM Bob through a spec-driven development approach.

Architecture overview

This tutorial shows how to implement a purchase order processing application that extracts multiple purchase order (PO) PDFs and consolidates them into actionable procurement insights using Docling for watsonx.

Users (procurement teams, inventory managers, finance teams, and supply chain coordinators) upload multiple PO PDFs. The system extracts PO details and generates three consolidated views: line items, vendor summaries, and product summaries, with CSV export capability.

Bob creates a Python Flask web application with a user interface built using the Carbon Design System.

  1. Users upload PDFs through the browser to the Flask application.
  2. The Flask app sends the PDFs to Docling for watsonx.
  3. Docling returns extracted data to the Flask app.
  4. The Flask app displays the results in the web interface.

Purchase order processing architecture diagram showing Flask app, Docling API, and user workflow

Prerequisites

Step 1. Get the API key for Docling for IBM watsonx

In this step, you get the credentials for Docling for IBM watsonx, which you need in the next steps to configure access from the application to Docling.

  1. Log in to the IBM SaaS console. Open Docling for IBM watsonx.

    Docling for IBM watsonx dashboard in IBM SaaS console

  2. Click API keys, and then click Generate key. Give the key a name and click Generate key. Copy the key securely.

  3. Click back to the Welcome screen, and then click Integrate. Copy the Service URL. The API Integration screen also includes sample code on how to integrate code with curl, Python, and Java.

    Docling API integration screen showing service URL and sample code

Step 2. Set up the Bob workspace with requirements and sample PDFs

In this step, you create a new workspace in Bob and include the requirements intent specification and a sample PDF.

The requirements-intent.md file defines what the application should do (process PO PDFs and generate consolidated analytics), the intended users(procurement and finance teams), including the expected inputs (multiple PDF uploads), outputs (three consolidated table views and CSV export), and key technical constraints (Docling for IBM watsonx SaaS, Python Flask, and IBM Carbon Design). It also includes the sample integration code with Docling from the API integration step above.

The PO_10001_Acme.pdf serves as a test file to verify that Docling correctly extracts purchase order data and to validate the application's functionality before processing real documents.

  1. Open Bob IDE.

  2. Click File > Open Folder.

  3. Click New Folder, name the folder docling-saas-purchase-order, and then click Open.

  4. Download the requirements-intent.md file to the workspace.

  5. Create a new folder named "sample."

  6. Download the PO_10001_Acme.pdf file to the sample folder.

    Bob IDE workspace with requirements-intent.md and sample PDF files

Step 3. Create a technical specification document

In this step, you use the Plan mode in Bob and ask Bob to create a technical specification document through spec-driven development. You provide Bob with the requirements-intent.md file. Bob translates that intent into a TECHNICAL_SPEC.md file that contains detailed technical specifications, including system architecture diagrams, tech stack versions, API endpoint definitions, data models, file structure, configuration requirements, and implementation guidelines. This technical specification helps Bob develop the code by providing a clear blueprint that aligns with the original intent, ensuring all components work together correctly to fulfill the requirements.

  1. Review the requirements-intent.md file to understand the intent.

    Requirements intent document open in Bob IDE editor

  2. Make sure you are in Plan mode. Then, in the chat ask Bob in natural language to create the technical specification document.

     Create only a concise technical specification for Purchase Order Consolidator based on @requirements-intent.md using Spec-Driven Development (SDD) methodology.

 Include implementation essentials only: architecture mermaid diagram, tech stack, core data models, API endpoints, and directory structure.

    Bob Plan mode chat interface with technical specification prompt

  3. Bob asks any clarification questions and then creates a todo list with the actions that Bob will complete. Click Approve.

    Bob generated todo list for technical specification creation

  4. Bob might ask additional clarification questions. For this tutorial, use the default option to proceed with a simple implementation. The exact questions and options might vary from what is shown in the screenshots.

    Bob clarification questions with implementation options

  5. Bob creates the technical specification document. Click Save.

    Bob completing technical specification document creation

  6. Right-click on the TECHNICAL_SPEC.md file, and click Open Preview. Review the architecture.

    Technical specification architecture diagram in preview mode

Step 4. Build the Flask application with Docling integration

In this step, you ask Bob to build the application based on your intent and technical specification documents, which Bob uses to generate all the necessary code files.

The code files include the Flask backend with services for Docling for watsonx integration, PDF parsing, and data aggregation, a user interface built using the IBM Carbon Design System with upload and results pages, configuration files, and integration tests to validate the Docling API connection using the sample PDF.

  1. In the chat interface, click Start New Task. It is a best practice to regularly start a new task to manage the context and use Bobcoins efficiently.

  2. Switch to Code mode so that Bob can write code.

  3. Instruct Bob to build the application based on the intent requirements and technical specification document.

     Build the application based on @/requirements-intent.md and @/TECHNICAL_SPEC.md .

    Bob Code mode prompt to build application from specifications

  4. Bob creates a todo list that breaks down the application development into several tasks, including project structure setup, backend services (Docling integration, PDF parsing, data aggregation), API routes, Carbon Design UI pages, frontend JavaScript, documentation, and tests. Review the task list and click Approve.

    Although you can enable auto-approval, consider the security risks before doing so.

    Bob generated todo list breaking down application development tasks

  5. Bob creates the application code including the integration with Docling for watsonx. Click Save and proceed until the code creation is completed.

    Bob generating Docling for watsonx integration code

  6. After Bob completes the code implementation, Bob pauses and asks you to provide your Docling for watsonx credentials and the intended port for Flask so that Bob can proceed in the testing activities. Replace the values in the .env file with the Docling credentials you obtained earlier. Then, in the chat, prompt Bob that you provided the necessary credentials.

     Added my Docling credentials, please proceed in the testing

    Environment file with Docling API credentials configuration

    Bob starts the unit testing and integration testing, and automatically fixes the code to solve any issues that occur during testing.

    Bob automatically fixing code errors during testing

    Bob completes the design, coding, unit testing and integration testing with Docling.

    Bob validation completed message showing successful tests

Step 5. Run and test the application

In this step, you start the application and test it with purchase orders.

  1. In Bob IDE, from the Terminal menu select New Terminal. Then, run the following command to activate a Python virtual environment, install the dependencies, and start the application.

    
 python3 -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt
 python run.py

    Terminal showing Flask application starting with virtual environment

  2. If you run into any issue, copy the terminal output into the chat and Bob will solve it.

  3. Wait for the application to start and access it in the browser using the link shown in the log.

    Flask application running with localhost URL in terminal

  4. Download all the PDFs in the sample purchase order PDFs folder. These PDFs represent sample purchase orders. Drag and drop the PDFs into the application, and then click Process Files. Notice that the application follows IBM Carbon design language, as noted in our intent and technical specifications documents.

    Carbon Design upload interface with drag and drop PDF area

  5. Docling for IBM watsonx extracts all the purchase order details. Notice that you can also export the results into an Excel file, and view the purchase orders grouped by vendor or products.

    Purchase order results showing line items, vendor summaries, and export options

Summary and next steps

In this tutorial, you learned a spec-driven development approach to build applications powered by Docling for IBM watsonx SaaS. You learned how to integrate Docling's AI-powered PDF processing by providing IBM Bob with the intent and letting Bob generate the complete application with Docling API integration, markdown parsing logic, and IBM Carbon Design UI. You also learned how Bob creates both the backend services for document processing and the frontend interface with Carbon Design components.

You can also explore how Bob helps creating MCP tools and watsonx Orchestrate agents in this tutorial: "Using IBM Bob to build watsonx Orchestrate agents and MCP tools."

Acknowledgments

This tutorial was produced as part of IBM Open Innovation Community initiative: Bob Tutorials.

The author Ahmed Azraq deeply appreciates the support of Michele Dolfi and Lauren McHugh for the guidance on reviewing and their contributions to this tutorial.