Frappe Client Java

Simple Java wrapper for Frappe REST API

Requirements

• Java 11 or higher
• Maven 3.6 or higher

Install

git clone https://github.com/neox-d/frappe-client-java.git
cd frappe-client-java
mvn install

Quick Start

Initialize with Username and Password

import com.frappeclient.FrappeClient;

FrappeClient client = new FrappeClient("https://example.com");
client.login("user@example.com", "password");

Initialize with API Key

import com.frappeclient.FrappeClient;

FrappeClient client = new FrappeClient("https://example.com");
client.authenticate("api_key", "api_secret");

For demonstration purposes only! Never hardcode credentials in your source code! Use environment variables or configuration files.

Usage

Create

// Insert a new document to the server
Map<String, Object> todo = new HashMap<>();
todo.put("doctype", "ToDo");
todo.put("description", "Example ToDo");

JsonObject result = client.insert(todo);

Read

// Get a specific document 
JsonObject doc = client.getDoc("ToDo", "413nbpio3p");
System.out.println(doc.get("priority").getAsString());

// Get document with specific fields
List<String> fields = Arrays.asList("name", "status", "priority");
JsonObject docWithFields = client.getDoc("ToDo", "413nbpio3p", fields);

Update

// Update entire document
Map<String, Object> updates = new HashMap<>();
updates.put("doctype", "Customer");
updates.put("name", "CUST-001");
updates.put("customer_name", "Updated Name");

JsonObject updated = client.update(updates);

// Update single field
JsonObject result = client.setValue("ToDo", "413nbpio3p", "status", "Cancelled");

Delete

client.delete("ToDo", "413nbpio3p");

List

// Get all documents
JsonArray allCustomers = client.getList("ToDo");

// With filters
Map<String, Object> filters = new HashMap<>();
filters.put("status", "Open");
filters.put("priority", "High");

JsonArray filtered = client.getList("ToDo", null, filters, null, null, null, null, null);

// With pagination and ordering
List<String> fields = Arrays.asList("status", "priority", "description", "allocated_to");
JsonArray paginated = client.getList(
    "ToDo",           // doctype
    fields,               // fields to return
    filters,              // filters
    "creation desc",      // order by
    0,                    // limit_start
    20,                   // limit_page_length
    null,                 // parent
    false                 // debug
);

Advanced Filtering

// Array-based filters (like Python)
List<List<Object>> arrayFilters = new ArrayList<>();
arrayFilters.add(Arrays.asList("status", "=", "Open"));
arrayFilters.add(Arrays.asList("creation", ">", "2024-01-01"));

JsonArray results = client.getList("ToDo", null, arrayFilters, 
    null, null, null, null, null);

Get Count

Map<String, Object> filters = new HashMap<>();
filters.put("status", "Open");

int count = client.getCount("ToDo", filters);

Get Value

Map<String, Object> filters = new HashMap<>();
filters.put("website", "example.net");

JsonElement value = client.getValue("Customer", "name", filters);

Bulk Insert

List<Map<String, Object>> notes = new ArrayList<>();
for (int i = 1; i <= 5; i++) {
    Map<String, Object> note = new HashMap<>();
    note.put("doctype", "Note");
    note.put("title", "Note " + i);
    note.put("public", true);
    notes.add(note);
}

JsonArray inserted = client.insertMany(notes);

Run Whitelisted Method

// Run server-side method
Map<String, Object> params = new HashMap<>();
params.put("param1", "value1");
params.put("param2", "value2");

JsonElement result = client.runMethod("custom_app.api.my_method", params);

Run Document Methods

// Run method on a specific document
JsonObject result = client.runDocMethod("Sales Invoice", "INV-001", "submit");

// With parameters
Map<String, Object> params = new HashMap<>();
params.put("reason", "Duplicate");

JsonObject cancelled = client.runDocMethod("Sales Invoice", "INV-001", "cancel", params);

Submit and Cancel Documents

Map<String, Object> invoice = new HashMap<>();
invoice.put("doctype", "Sales Invoice");
invoice.put("name", "INV-001");

// Submit
JsonObject submitted = client.submit(invoice);

// Cancel
JsonObject cancelled = client.cancel(invoice);

Logout

client.logout();

Example

See Example.java for more info

Testing

The library includes unit tests using JUnit 5 and MockWebServer:

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=FrappeClientTest

# Run with coverage
mvn clean test jacoco:report

Dependencies

• OkHttp 5.3.2 - HTTP client
• Gson 2.13.2 - JSON serialization/deserialization
• JUnit 6.1.0-M1 - Testing framework
• Mockito 5.21.0 - Mocking framework
• MockWebServer 4.12.0 - HTTP mocking for tests

License

MIT

Support

• Issues: Report bugs via GitHub Issues
• Documentation: Frappe Framework documentation at https://frappeframework.com
• Python Client: Original library at https://github.com/frappe/frappe-client

Changelog

Version 1.0.0

• Initial release

Acknowledgments

• Frappe Technologies Pvt. Ltd. for the original Python client
• Claude AI