中文|English

2BizBox ERP

API Development Tutorial

Content


Introduction

  • What is 2BizBox API
  • Where 2BizBox API located in 2BizBox system?
  • What 2BizBox API can do?
  • Why API? Not source code?
  • Target Audience

Development Practices

  • Preparation
  • Create environment to run 2BizBox
  • Build Development environment
  • Create Project

Advanced Development

  • Swing Program Integration Example
  • Web Program integration example

Learn More
—————————————————

Introduction

What is 2BizBox API?
2BizBox, as a free ERP software, it is also an open platform for ERP. It provides a full second-develop-interface API for developers to do integration and secondary development for 2BizBox. 2BizBox API covers all the functions of 2BizBox.With 2BizBox API, developers, system integrators, service providers etc can have a deep understanding of function and mechanism of 2BizBox, and can integrate with other software systems seamlessly, meeting the practical needs of enterprise. Typical scenarios are like integration and data exchange with other manufacturers ERP systems such as OA, CRM, PDF etc.

Take a simple example: a company has successfully implemented CRM system and 2BizBox ERP system. Generally, there is no real-time product cost and BOM information in CRM. When quotation happens, the enterprise hopes to get current inventory of goods, cost and BOM information directly in CRM by 2BizBox to have a quick response. Meanwhile, we hope sales order can be directly generated in 2BizBox after sales agreement achieved. How? Here it will become simple and easy once you mastered the2BizBox API development skills.

Where 2BizBox API located in 2BizBox system?
2BizBox API is a definition for system’s backstage functions and data structure which is used for various external program calling, including GUI desktop terminal of 2BizBox, different module terminal based on Web, like PDA, mobile and so on. Similarly, if you mastered 2BizBox API development approach, you can also create your own terminal applications based on 2BizBox or to integrate and data linkage with 2BizBox.
The following picture shows where 2BizBox API located in 2BizBox system and what exactly roles it plays.

What 2BizBox API can do?

2BizBox API contains all functions and data structures of 2BizBox system. So, in theory, you can do anything by 2BizBox API, like create documents, query data, modify the order etc. You can even develop a new client GUI program by 2BizBox API, of course, it will be a huge work. Mostly, we complete the work like system integration, data query and second development by using specific features of 2BizBox API.
At present, 2BizBox API Java version is available. In other words, you can use 2BizBox API with Java language and integrate into your Java system. 2BizBox can be applied in desktop Java programs (such as Swing, SWT etc.) and also in Java environment based Web (like Servlet, JSP etc.).

Why API? Not source code?

We claimed that 2BizBox software is free but not open source code. 2BizBox software source code doesn’t open to public. Therefore, to provide a complete API is the best way to integrate with the2BizBox and do secondary development.
API has much more advantages comparing to the source code. It is not easy for any individual to understand over 2 million lines of source code of 2BizBox, not to mention modify and customize it. In addition, modifying the source code directly will also bring about many bugs and even safety risks, like leading to the2BizBox system instability.
As more developers modify the source code, system integration and development will become more difficult, and perhaps even have the risk of splitting, it will do harm to the end-user and 2BizBox in the long run. While through a unified, consistent, simple, open API interface, developers do not need worry about the internal operation mechanism of 2BizBox, and don’t need understand such a lot of source codes.
As long as API interface maintains its consistent and compatibility, 2BizBox will assist majority of developers building more powerful 2BizBox.
Therefore, we believe that API is far better than source code. 2BizBox will continue to enrich and open high-quality API, together with majority of developers to participate in the development of 2BizBox.

Target Audience

The tutorial is for 2BizBox API developers, 2BizBox development partners, 2BizBox system integrators. If you are software vendor, if you provide BI, CAD, PLM, PDM, CRM, MES, OA, SCM, Call Center, financial systems, warehouse systems etc., you can integrate with 2BizBox to build an enterprise application ecosystem through mastering 2BizBox API development methods.

Note:

  • CS=Contract Management
  • QS=Quotation System
  • DS=Distribution System
  • FS=Finance System
  • BS=Budget System

The end users of 2BizBox don’t need know the knowledge of 2BizBox API and 2BizBox secondary development.

In addition, now 2BizBox API only support Java version, so you need to know basic Java development technologies.

Development Practices

Preparation
2BizBox API is based on Java. So you need to prepare the following:

  • JDK 6 or higher edition
  • IDE, such as Eclipse or NetBeans etc. The tutorial will take NetBeans as example;
  • Install 2BizBox ERP, ensure it can run and login. Create some sample data for testing;

Of course, you need to own basic knowledge of Java programming. For example, write a class, add a main function, compile and run, debugging adjust and so on. Well, we can begin if we are ready.

Create environment to run 2BizBox
First, download 2BizBox ERP software from official website or some download sites freely (Note download All-in-One version, which includes client and server software program). Double-click the installation file, follow the prompts to install. When installation finished, 2BizBox ERP server and client will run automatically. Note that you can login client after the server starts about a minute, log on to the system’s “test” the company.

In system, you can firstly create a few parts. You also can watch online video to learn how to add a part. The added parts can be used to test the following API procedures. The screen shot is part of the data:

Build Development environment
To use the 2BizBox API, you need the following jar package:

  • Third-party packages:
  • commons-lang-2.4.jar, Apache’s Commons Lang Package, a standard Java enhancement kit ;
  • 2BizBox running package:
  • common.jar, 2BizBox data structure definition package, including POJO definitions of all business data which 2BizBox involved;
  • server.jar, 2BizBox backstage business module API functions encapsulated package, covered all 2BizBox Business API;

All above running package can be downloaded in on the below of page.

Create Project
The tutorial uses NetBeans IDE to introduce. For readers who are familiar with the Eclipse, it should be not much difficulty, as the operation is almost similar,
Step One: Create project create a new Java project in NetBeans, as shown below.

Name the new project as BBApiTest, and set the project directory.

Thus, we created a new, empty Java project.
Step two: Add Jar package as mentioned above, the project will use 3 jar packages. Right-click the project’s Libraries directory, add 3 prepared jar package.

Once added, jar package list as below

So far, engineering and engineering environment was built. Next, we can write code!

Step Three: create Java class Click menu, generate a normal Java class.

Named the Java class as ApiTest, and set the package as test.

Step Four: type the code
Type following code in the new created Java class :

package test;

import com.serva.bb2.common.BizBoxServer;
import com.serva.bb2.gui.server.EngServerActionManager;
import com.serva.bb2.gui.server.ServerActionUtil;

public class ApiTest {

    public static void main(String[] args) throws Exception {
        BizBoxServer server = new BizBoxServer("localhost", "80", "test", "username", "password", "zh");
        ServerActionUtil.setTargetServer(server);

        EngServerActionManager eng = EngServerActionManager.getInstance();
        int count = eng.getAllPartsCount();
        System.out.println("2BizBox ERP Total BOM in System:" + count);
    }
}

It is a quite simple Java code, a normal Java class, a main function. Create a 2BizBox target server in function, and set IP address, port, company, user name, password, connection language. Then, get the engineering module API’s Manager, call the function getAllPartsCount and connect the total number of all materials in 2BizBox system

Step five: Press F6 key and execute the file. In the author’s created environment the output results are as below:

run:
2BizBox ERP Total BOM in System:87042
BUILD SUCCESSFUL (total time: 1 second)

Here, congratulations! You have successfully created the first 2BizBox API program.

Advanced Development

The above example simply demonstrated how to connect 2BizBox back stage server to get data via 2BizBox API. This section continues to demonstrate how to integrate with existing 2BizBox system in a desktop program or a Web program by 2BizBox API.

Swing Program Integration Example

We assume that you already have a complex desktop applications based on Java Swing, and need exchange data with 2BizBox. Or you already have a desktop-based OA system that can handle approval for a variety of documents, and after that can go to 2BizBox ERP to create documents automatically (i.e. purchase order). At this point, 2BizBox API can play a huge role.

We here create and simulate a very simple desktop applications based on Java Swing and through 2BizBox API to get data from 2BizBox server. We take “Fuzzy query parts and list their names” as example, describe how to do operations and communications for 2BizBox server in a Java Swing program.

This example assumes that you are familiar with Java and Swing technology.
Re-create a new Java class, named ApiTestSearchPartUI and inherited from JFrame. In this window, put several input box on its top, respectively used for inputting server’s IP address, company, user name, password, and keyword of some parts to be checked. In middle of window, put a large text box to display the results returned.

The following lines of code are used to initialize the window. Including the size, close action, title, etc.:

this.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
this.setTitle("2BizBox API Test");
this.setSize(750, 500);
this.setLocation(300, 300);

Next, put the created Swing components in a Panel, and placed it in the top of the window:

JPanel settingPane = new JPanel(new FlowLayout(FlowLayout.LEADING, 5, 0));
settingPane.setBorder(BorderFactory.createEmptyBorder(10, 10, 10, 10));
settingPane.add(new JLabel("Server:"));
settingPane.add(this.txtServer);
settingPane.add(new JLabel("Company:"));
settingPane.add(this.txtCompany);
settingPane.add(new JLabel("User:"));
settingPane.add(this.txtUser);
settingPane.add(new JLabel("Password:"));
settingPane.add(this.txtPassword);
settingPane.add(new JLabel("Search:"));
settingPane.add(this.txtSearch);
settingPane.add(btnConnect);

In the back, place a button. When you click the button, based on typed content to connect server, and according to search criteria, search the parts from the backstage:

this.btnConnect.addActionListener(new ActionListener() {

    public void actionPerformed(ActionEvent e) {
        try {
            initServer();
            findPartsByDescriptionInside();
        } catch (Exception ex) {
            ExceptionWorker worker = new ExceptionWorker(ex);
            String message = worker.getMessage();
            JOptionPane.showMessageDialog(ApiTestSearchPartUI.this, message);
        }
    }
});

For code, an exception may occur while calling backstage. So, once it happened, it has to be processed. Here, analyze and process exception using ExceptionWorker provided by 2BizBox API, and translate the result and elaborate, return by getMessage ()function. We display the detailed description of exception by text box directly.
While calling backstage, firstly initialize the server via following code. The default port is 80, the default logon language is English.

private void initServer() {
    String server = this.txtServer.getText().trim();
    String port = "80";
    String company = this.txtCompany.getText().trim();
    String user = this.txtUser.getText().trim();
    String password = new String(this.txtPassword.getPassword());
    String language = "en";
    BizBoxServer targetServer = new BizBoxServer(server, port, company, user, password, language);
    ServerActionUtil.setTargetServer(targetServer);
}

Then it is actual code calling. First, get the engineering module interface—- EngineeringBox , then call its findPartsByDescriptionInside function to search parts via fuzzy look up. Several parameters explained as follows:

  • The first parameter: part number. If the part number is not limited, input an empty string “” directly;
  • The second parameter: part type. If the part type is not limited, input an empty string “” directly;
  • The third parameter: part description. We use part description to filter parts, used for user inputting on system interface;
  • The fourth parameter: the starting cursor of returning collection. That is return to the position where the result record is suitable;
  • The fifth parameter: the length of returning collection. That is what max number of returned eligible records, be careful not too much, otherwise it will cause the server heavy too much. Here we set 100
private void findPartsByDescriptionInside() throws Exception {
    EngineeringBox eng = EngServerActionManager.getInstance();
    String search = this.txtSearch.getText().trim();
    Collection parts = eng.findPartsByDescriptionInside("", "", search, 0, 100);
    String result = "";
    if (parts != null) {
        Iterator it = parts.iterator();
        while (it.hasNext()) {
            PartBasicInfo part = it.next();
            result += part.getPartPk().getPartNumber();
            result += "\t";
            result += part.getDescription();
            result += "\n";
        }
    }
    this.txtResult.setText(result);
}

Returned results set is collection of objects PartBasicInfo. PartBasicInfo object contains brief information of part object. Travers the returned result set, output the part number and description to text box to display.
The whole procedures as the following:

package test;

import com.serva.bb2.common.BizBoxServer;
import com.serva.bb2.common.PartBasicInfo;
import com.serva.bb2.common.box.EngineeringBox;
import com.serva.bb2.gui.server.EngServerActionManager;
import com.serva.bb2.gui.server.ServerActionUtil;
import com.serva.bb2.gui.swing.ExceptionWorker;
import java.awt.BorderLayout;
import java.awt.FlowLayout;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.util.Collection;
import java.util.Iterator;
import javax.swing.BorderFactory;
import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;
import javax.swing.JOptionPane;
import javax.swing.JPanel;
import javax.swing.JPasswordField;
import javax.swing.JScrollPane;
import javax.swing.JTextArea;
import javax.swing.JTextField;

public class ApiTestSearchPartUI extends JFrame {

    private JTextField txtServer = new JTextField("192.168.1.121", 8);
    private JTextField txtCompany = new JTextField("test", 4);
    private JTextField txtUser = new JTextField("admin", 4);
    private JPasswordField txtPassword = new JPasswordField("password", 4);
    private JTextField txtSearch = new JTextField(8);
    private JTextArea txtResult = new JTextArea();
    private JButton btnConnect = new JButton("Connect");

    public ApiTestSearchPartUI() {
        this.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        this.setTitle("2BizBox API Test");
        this.setSize(750, 500);
        this.setLocation(300, 300);

        JPanel settingPane = new JPanel(new FlowLayout(FlowLayout.LEADING, 5, 0));
        settingPane.setBorder(BorderFactory.createEmptyBorder(10, 10, 10, 10));
        settingPane.add(new JLabel("Server:"));
        settingPane.add(this.txtServer);
        settingPane.add(new JLabel("Company:"));
        settingPane.add(this.txtCompany);
        settingPane.add(new JLabel("User:"));
        settingPane.add(this.txtUser);
        settingPane.add(new JLabel("Password:"));
        settingPane.add(this.txtPassword);
        settingPane.add(new JLabel("Search:"));
        settingPane.add(this.txtSearch);
        settingPane.add(btnConnect);

        this.add(settingPane, BorderLayout.NORTH);
        JPanel resultPane = new JPanel(new BorderLayout());
        resultPane.setBorder(BorderFactory.createEmptyBorder(0, 10, 10, 10));
        resultPane.add(new JScrollPane(txtResult), BorderLayout.CENTER);
        this.add(resultPane, BorderLayout.CENTER);

        this.btnConnect.addActionListener(new ActionListener() {

            public void actionPerformed(ActionEvent e) {
                try {
                    initServer();
                    findPartsByDescriptionInside();
                } catch (Exception ex) {
                    ExceptionWorker worker = new ExceptionWorker(ex);
                    String message = worker.getMessage();
                    JOptionPane.showMessageDialog(ApiTestSearchPartUI.this, message);
                }
            }
        });
    }

    private void initServer() {
        String server = this.txtServer.getText().trim();
        String port = "80";
        String company = this.txtCompany.getText().trim();
        String user = this.txtUser.getText().trim();
        String password = new String(this.txtPassword.getPassword());
        String language = "en";
        BizBoxServer targetServer = new BizBoxServer(server, port, company, user, password, language);
        ServerActionUtil.setTargetServer(targetServer);
    }

    private void findPartsByDescriptionInside() throws Exception {
        EngineeringBox eng = EngServerActionManager.getInstance();
        String search = this.txtSearch.getText().trim();
        Collection parts = eng.findPartsByDescriptionInside("", "", search, 0, 100);
        String result = "";
        if (parts != null) {
            Iterator it = parts.iterator();
            while (it.hasNext()) {
                PartBasicInfo part = it.next();
                result += part.getPartPk().getPartNumber();
                result += "\t";
                result += part.getDescription();
                result += "\n";
            }
        }
        this.txtResult.setText(result);
    }

    public static void main(String[] args) throws Exception {
        ApiTestSearchPartUI ui = new ApiTestSearchPartUI();
        ui.setVisible(true);
    }
}

Operated results as below:

In the example, we entered the correct login information, and take Chinese character “machine” as keyword of part description, query data in the 2BizBox server to be connected, find a large number of eligible records, and shown in the text box as below. Readers can modify the query filed while looking up. You can look up data in 2BizBox freely, reflecting the fun of”Control 2BizBox on your own”!

Example above is a very simple and typical Swing program, but it can successfully connect to any 2BizBox server, as long as you have the correct login information , and you can query and search for parts information. Just a little renovation, you can put the above code embedded in your own Swing application, and link with 2BizBox ERP or do data integration.

Web Program integration example

It is also quite easy to integrate 2BizBox API in Web development environment. This example uses a very simple JSP to illustrate how to call remote 2BizBox server in the JSP via 2BizBox API to get data and output it in browser. In actual Web development, you can do communication and data exchange with 2BizBox server in this way, and integrate with your existing Web systems.
Firstly prepare for the tomcat. You can go to tomcat official website to install free installation zip file. After downloading, extract the zip file. Go to the bin directory, double-click startup.bat file to ensure that tomcat can be started normally. If it doesn’t work, you may have not install Java environment or not correctly set JAVA_HOME environment variable.

Next, we manually create a very simple JSP. In the webapps directory, create a 2bizbox directory as a test project. There to create WEB-INF sub-directory, and create a WEB-INF web.xml file to define the Web project information. In which we just put a simple configuration file is ok, as follows:

 





Then, create lib file in WEB-INF, put in several jar package required by 2BizBox API in, common.jar, commons-lang-2.4.jar, server.jar. Okay, here an empty Web environment was built successfully.
Next, create a JSP test file. In 2bizbox directory, create a test.jsp file with WordPad. And enter the following code:

 
<%@ page import="java.util.*, com.serva.bb2.common.*, com.serva.bb2.common.box.*, com.serva.bb2.gui.server.*, com.serva.bb2.gui.swing.*" %>

<%
BizBoxServer server = new BizBoxServer("localhost", "80", "test", "admin", "password", "en");
ServerActionUtil.setTargetServer(server);

EngineeringBox eng = EngServerActionManager.getInstance();
String search = "TEST";
Collection parts = eng.findPartsByDescriptionInside("", "", search, 0, 100);
String result = "";
if (parts != null) {
    Iterator it = parts.iterator();
    while (it.hasNext()) {
        PartBasicInfo part = it.next();
        result += part.getPartPk().getPartNumber();
        result += "********";
        result += part.getDescription();
        result += "
"; } } out.write(result); %>

The code is very simple, firstly create 2BizBox target server address and login information, and make connections. Then, calls findPartsByDescriptionInside method in the engineering module and do query which is up to 100 string parts containing “TEST”. Finally, show the part number and description by string to the internet page.
In the author’s environment, the output result as below:

If do a further simple change, you can increase form on this page, freely enter the criteria like server address, user name, password, query, etc., and submit the page for dynamic queries, then real part query achieved.

Learn more

Through the above steps, you can see that the secondary development and system integration based on 2BizBox API is very easy and simple. For developers who are familiar with Java, just taking a few minutes will complete this tutorial. So how about try it by yourself now?

You can download detailed 2BizBox API JavaDoc as below.

http://www.2bizbox.com/downloads/javadoc-en.zip

You can download the latest version of 2BizBox API running package as below.

http://www.2bizbox.com/downloads/2bizbox-api-v3.1.0.zip

Lastly, sincerely hope you can learn more from the tutorial and have fun!

© 2BizBox 沪ICP备10200962号-6