This is a cache of https://developer.ibm.com/tutorials/automate-esg-reporting-envizi-watsonx-orchestrate/. It is a snapshot of the page as it appeared on 2025-12-16T02:28:28.139+0000.
Automate ESG reporting with watsonx Orchestrate and Envizi - IBM Developer
IBM Developer

Tutorial

Automate ESG reporting with watsonx Orchestrate and Envizi

A hands-on guide for integrating watsonx Orchestrate with the Envizi ESG platform to automatically retrieve, process, and deliver sustainability insights through intelligent workflows

By

Nikhil Thakkar,

Ashwini Nair

On this page

Integrate IBM watsonx Orchestrate with the IBM Envizi ESG platform to automate sustainability data management and streamline environmental, social and governance (ESG) reporting activities. IBM Envizi offers comprehensive capabilities for environmental, social, and governance (ESG) data collection, data analysis, and performance reporting. By combining Envizi’s ESG intelligence with watsonx Orchestrate automation capabilities, organizations can reduce manual effort and improve the accuracy and timeliness of sustainability insights.

The integrated architecture allows sustainability teams to:

  • Automate repetitive ESG reporting workflows.
  • Accelerate insight generation from environmental and operational datasets.
  • Ensure compliance with sustainability frameworks through consistent data retrieval.
  • Enhance cross-functional collaboration using intelligent digital workers.

Architecture of automated EGS reporting

The following figure shows how the ESG or Sustainability reports can be collected from the Envizi platform using watsonx Orchestrate.

Architecture

The solution uses watsonx Orchestrate as the central automation layer. The watsonx Orchestrate agent interprets user commands and triggers Python-based tools that interact directly with the Envizi API using a secured connection. When users request ESG metrics or operational data, the agent retrieves the relevant information from Envizi, aggregates the results, and presents them in a conversational or report-ready format.

Integration layer

A dedicated Python-based tool acts as the integration layer between watsonx Orchestrate and the Envizi ESG platform. This integration component uses the watsonx Orchestrate connection to securely manage Envizi API calls with the Envizi API Access Token. It enables watsonx Orchestrate digital workers to retrieve, process, and update ESG performance metrics within automated workflows.

Key capabilities of the integration layer

  • Automated ESG data access: watsonx Orchestrate uses Envizi APIs through registered Python tools to fetch ESG metrics, sustainability reports, and related insights.
  • Secure and direct integration: The Python tools use watsonx Orchestrate API connection and Envizi’s access token to establish secure communication with Envizi endpoints.
  • Tools design: The tools follow a clean, structured design aligned with watsonx Orchestrate connection framework, enabling maintainability and enterprise-grade extensibility.
  • Actionable sustainability insights: The combined automation and analytics capabilities streamline reporting, reduce manual workloads, and improve data quality and consistency across ESG processes.

Prerequisites

  • Access to a watsonx Orchestrate–enabled environment in either a cloud deployment or an on-premises deployment.

  • You can provision a free trial instance of watsonx Orchestrate on IBM Cloud or AWS:

  • A running instance of the Envizi platform with Administrator access.

  • The API Token Personal Role assigned to your Envizi user account to generate an API Access Token. For more information, see Assigning an API token role.
  • A running local environment of the watsonx Agent Development Kit (ADK). If you do not have an active ADK instance, review the getting started with ADK tutorial. This tutorial has been tested and validated with ADK version 2.0.
  • Clone the code base from our GitHub repo. Open the code in VSCode or an editor of your choice and then navigate to the envizi-agent directory. Set the envizi-agent directory as your current working directory.

Step 1. Set up IBM Envizi ESG Suite access token

  1. Log in to the Envizi platform.

  2. Click the user icon in the upper-right of the Envizi interface and select My API Access Tokens.

    EnviziMyAPIAccessToken

  3. In the Access Tokens page, click Create New, assign a descriptive token name, and click Save.

    EnviziCreateNewToken

  4. Select the newly created token record and click Actions > Generate Token.

    EnviziActionGenerateToken

  5. Copy the generated token, store it in a secure location, and retain it for later use. This token functions as a Bearer token in HTTP requests to Envizi API endpoints.

    EnviziCopyToken

Step 2. Verify access to IBM Envizi Instance via API

To confirm that your IBM Envizi ESG Suite access token is valid, retrieve the list of available ESG reports and fetch the detailed report for one report from the returned list. This tutorial demonstrates the report named _Envizi-RawDataExtract, but you can extend this tutorial to any report available in your Envizi instance.

Note: When invoking the API endpoints, include the following HTTP header:

Authorization: Bearer <your_envizi_token>

  1. Use Postman, curl, or your own code to validate that the Envizi API returns data successfully.

    a. Retrieve the list of available reports. Replace <token> with your Envizi API token.

    curl --request GET \
--url https://usapi.envizi.com/api/meta/reports \
--header 'authorization: Bearer <token>'

    Example response:

    [{"report_Id":1481,"name":"_Envizi-AccountItemsAndCostAudit"},
{"report_Id":1837,"name":"_EnviziAccountItemsAudit"},
{"report_Id":1521,"name":"_Envizi-AccountsDataVarianceExceptions"}]

    b. Retrieve details for a specific report. Replace <token> with your Envizi API token.

    curl --request GET \
--url https://usapi.envizi.com/api/meta/reports/_Envizi-DashboardUsageAudit \
--header 'authorization: Bearer <token>'

    Example response:

    [{"associateId":17000031,"params":[{"name":"Start_Period","defaultValue":"2025/10/27","availableValues":null},{"name":"End_Period","defaultValue":"2025/11/26","availableValues":null}]},
{"associateId":17000164,"params":[{"name":"Start_Period","defaultValue":"2025/10/27","availableValues":null},{"name":"End_Period","defaultValue":"2025/11/26","availableValues":null}]},
{"associateId":17000243,"params":[{"name":"Start_Period","defaultValue":"2025/10/27","availableValues":null},{"name":"End_Period","defaultValue":"2025/11/26","availableValues":null}]},
{"associateId":17000303,"params":[{"name":"Start_Period","defaultValue":"2025/10/27","availableValues":null},{"name":"End_Period","defaultValue":"2025/11/26","availableValues":null}]},
{"associateId":17000335,"params":[{"name":"Start_Period","defaultValue":"2025/10/27","availableValues":null},{"name":"End_Period","defaultValue":"2025/11/26","availableValues":null}]}]

Step 3. Create a Python virtual environment

Open the local terminal and run the following commands to create and activate a Python virtual environment named envizi_env.

python3.11 -m venv envizi_env
source envizi_env/bin/activate

Step 4. Configure watsonx Orchestrate to integrate with the Envizi API

Register the required connections, tools, and agents in the watsonx Orchestrate environment.

  1. Import the Envizi connection definition into the watsonx Orchestrate user interface by using the watsonx Orchestrate ADK command-line interface:

    orchestrate connections import -f connections/connections.yaml

  2. Add the Envizi Bearer token that you created in Step 1 to the Envizi API connection. Replace <ENVIZI_BEARER_TOKEN> with your actual Envizi Bearer token and then run the following command.

    orchestrate connections set-credentials -a envizi_api_connection \
 --env draft \
 --token <ENVIZI_BEARER_TOKEN>

  3. Verify that the imported connection with the Envizi Bearer token is shown in the watsonx Orchestrate Connections section.

    Connection-navigation

    Connection

  4. Import the Python-based Envizi tools by running the following commands. These commands register the tools and link them to the Envizi API connection.

    orchestrate tools import -k python -f tools/list_esg_reports.py -r requirements.txt --app-id envizi_api_connection
    orchestrate tools import -k python -f tools/report_details.py -r requirements.txt --app-id envizi_api_connection

  5. Import the Envizi reporting agent into watsonx Orchestrate.

    orchestrate agents import -f agents/envizi_reporting_agent.yaml

Step 5. Validate data handling and processing in the watsonx Orchestrate workflow

  1. Confirm that the Envizi reporting agent is visible in the watsonx Orchestrate Agent Builder page. Open the envizi_reporting_agent configuration to verify the agent details.

    RegisteredAgent

  2. Confirm that the imported Python tools are listed under the agent’s available tools. Ensure that both list_esg_reports and report_details tools are correctly linked to the Envizi API connection.

    RegisteredTools

  3. Test the agent by submitting a query. For example, Get the list of reports available in Envizi.

    GetReportList

  4. Test the agent with a specific report name to retrieve detailed report information. For example, Get the report details for the _Envizi-AccountItemsAudit report.

    You can view how the agent invokes the report_details tool to collect complete report metadata.

    GetReportDetails

Step 6. Deploy the Envizi reporting agent

Deploy the Envizi reporting agent in your watsonx Orchestrate environment. After deployment, you can integrate the agent into your sustainability platform to enable conversational actions such as requesting carbon metrics, generating ESG reports, validating compliance data, or initiating Envizi data refresh operations through simple chat commands.

Summary and next steps

In this tutorial, you integrated IBM watsonx Orchestrate and the Envizi ESG data platform to automate sustainability reporting and insights generation. Connected a Python-based tool securely to the Envizi API, enabling ESG metrics to be retrieved, processed, and delivered into watsonx Orchestrate workflows. Enabled Digital workers to request ESG data, generate reports, and present insights in natural language. Through this integration, manual sustainability reporting tasks have been transformed into automated, AI-driven workflows.

You can extend the solution by creating an email notification module to validate report details and establish an approval workflow for sustainability reports.

Acknowledgments

This tutorial was produced as part of the IBM Open Innovation Community initiative: Agentic AI (AI for Developers and Ecosystem).

The authors deeply appreciate the support of Ahmed Azraq and Bindu Umesh for reviewing and contributing to this tutorial.


11 December 2025

Legend