Apache OFBiz Resource REST Reference

18 mai 2021

1. Introduction to OFBiz

Welcome to Apache OFBiz! A powerful top level Apache software project. OFBiz is an Enterprise Resource Planning (ERP) System written in Java and houses a large set of libraries, entities, services and features to run all aspects of your business.

This manual will describe all resources (on a REST point of view) available to manage business object.

Currently ofbiz REST requests return for a resource:

  • data about it

  • AND, most of time, user presentation data

Resource is not entity (even if most of time it’s the same), Resource is a functional view.

Most of the OFBiz GUI is design by assembling some screenlet for one page.
One of the configuration / personalisation task could be to choose its own assemblage.

If you need to understand the process and bussiness object for the core application of this framework like the Party Manager, Order Manager, Accounting system, and others you should read the "Apache OFBiz User Manual".

If you wish to contribute to OFBiz and help make it better, you may wish to read the "Apache OFBiz Developer Manual" for a deeper understanding of the architectural concepts of the framework.

2. REST uri structure

All REST uri follow the model {webapp}/control/{ResourceName}/{cover}/{Pkvalue: .*}

The first letter of ResourceName is uppercase.

Classic cover are:

cover

method to use

Goal

find

get

find form to select options for list

list

get (via post)

Resource list,
⇒ with a get (so without parameters) all the resource rows
⇒ with a post (parameters and _method="GET") resources selected by options

create

get

create form

edit/{Pkvalue: .*}

get

edit form and data for the id sent

show/{Pkvalue: .*}

get

show form and data for the id sent

summary/{Pkvalue: .*}

get

summary form and data for the id sent

data/{Pkvalue: .*}

get

just data for the id sent

change

post

create a resource

change/{Pkvalue: .*}

put (via post)

update example with the correspondig Id

change/{Pkvalue: .*}

delete

delete example with the correspondig Id

In this documentation, for each ResourceName, the webapp mentioned is the one for which the REST interface has been created for the first time.

3. Core Business Applications

Most businesses share universal needs. They require accounting functionality, managing customers, placing orders, book-keeping, invoicing and so on.

OFBiz is designed so that such basic universal business needs are available through a set of core business applications. These applications all share a unified data-model with a set of unified services to implement this functionality.

Each core business application contain a group of resources, this documentation will help you to find and understand which one do what

All ResourceName are organize by Category, so there is one chapter by category.

3.1. Party

3.1.1. Category Party_Profile.

This category is for Party component with a focus on all detail for a Party.

Party Information.

This screenlet show a information summary for a Party. With the edit button you can change information and see the details.

Summary and detail are adapted for Person or Party Group

screenlet parameters

  • Standard show screenlet menu

  • Standard show edit menu : if value = N "edit button" not appears

Security rules

  • nothing at the screenlet level, only at the update service level (and component rules)

Contact Mechanism

This screenlet displays the Contact Mechism (adress, telephone, mail, …​.) of a business object: actor, facility, order, …​

Depending on the Contact Mechism (postal address, email, phone, …​), the display and entry differs. In all cases, it is possible to clarify the purpose of the Contact Mechism (billing address, and / or delivery, and / or …​)

A Contact Mechism may be associated with one or more business object, for example, postal delivery address of a client will also associated with its various orders or quotes. It is therefore very rare to delete a Contact Mech., it is by cons, possible invalidate it, because each Contact Mech. possesses the expiry date (from date .. thru date ..)

By default only valid Contact Mechism are displayed and there is a button to display the history

Screenlet parameters

  • Setting the field Telephone: This field can be detailed by three additional subfield (pay, region, ext), each may or may not be used.

  • It is possible to show or not each of the menu options to add

  • It is possible, for each type of addition to give a purpose which will be used when creating

Security rules

  • nothing at the screenlet level, only at the update service level (and component rules)

Technical remarks

This portlet displays the Contact Mechism if it receive a partyId, or a facilityId or a orderId or a workEffortId

Party roles list (and management)

This screenlet list the roles for the party, all or only thus which are part of a role group, the role group description is displayed in the title of the screenlet, it depends on the setting of the screenlet on this page.

If there is no role group set, when adding a role, you can start by selecting a parent role and after one child.

If there is a group of role set, when adding a role, it will be possible to choose among the roles that group.

Limitations or futures functionalities

  • Currently, role are group by using parent role, so its not possible for a role to be in multiple "group".

Screenlet parameters

  • Show edit Standard: if set to N then the buttons "Add" and "suppression does not appear.

  • Role Group : Indicates the group from which the role will be selectable in the add screen. In this case Party roles list is contain only role which are in the group

Security rules

  • PORTAL_ADMIN is needed to edit portlet attributes

User login list for a Party.

This screenlet list all user login associated to a Party. Most of time a party has only one, but when party is a company, sometime it’s useful to give multiple user login, if you don’t want create a party for each company’s employee.

A user login is used to connect to ofbiz application.
Security Group give which screens he can view and which functions he can execute.

This screenlet can be use to manage (create, modify delete) userLogin and securityGroup associated

Limitations or futurs fonctionnalities

  • Only the first 5 user login are show

Screenlet parameters

  • Standard show screenlet menu

  • Standard show edit menu : if value = N "add user login button" not appears

  • security Group Id : if a securityGroupId is put, the 'add user login button' will automatically add this securityGroupId to the userLogin just after creating it

Security rules

  • SECURITY_VIEW is needed to view Security Group List

  • PARTYMGR_CREATE is needed to have the "add user login button", and SECURITY_CREATE when a security group is automatically add (cf security group parameters)

  • PARTYMGR_UPDATE and SECURITY_ADMIN are needed to be able to edit user login security information (enable or not user login, new password, …​) and to manage security group list for a login

  • When a user use this screenlet for him (with its own user login), he can change its password

Associated parties management

This screenlet displays the parties associated with the selected Party. The display and behavior depend on its setting.

To characterize the relationship between two parties, we must specify the "relationship type", the more fluently this screenlet is used for a specific relationship Type, eg

  • "Contact", ie list all the contacts of a sales reps or a customer;

  • "Employee", ie list all employees of a company;

  • "Team Member", ie list all team members or service members;

  • ...

For a relationship between Party, it is also possible to specify the role of the party associated, for example in the case of Relationship Type "employee", the role will detail the role of the employee in the company.
In most cases this field does not appear because it is not necessary.

A relationship between Party possesses validity date (from date .. thru date ..), it is possible to keep a history. Depending on the setting it is also possible to delete a relationship in which case the history will not be retained.

Screenlet parameters

  • Screenlet Title: You must include a "UiLabel" (a code according to a language that give wording), it allows you to customize the screenlet Title, this is useful when the screenlet is used several times in the same page. Ask a technical consultant to find the UILabel corresponding to your needs, or to define a new one.

  • Role From Type: If this field is filled, the list displayed will be filter (only this role) and in editing (add or change) this value will be used, the role field will not be shown to the user. Usually, this parameter is left blank.

  • Role Group : If the field Role From is empty, indicates the group from which the role will be selectable in the edit screen (add - change). The field "original role" will be displayed in the list

  • Party Relationship Type Id : indicate the RelationshipType to use to filter relationships to display, or leave it blank to display all and therefore this field.

  • Party associated Role (Role Type To): If this field is filled, the list displayed will be filter (only this role) and in editing (add or change) this value will be used, field "role to" will not be displayed to the user.

  • Role To Group: If the field RoleTo is empty, indicates the group from which the user will select a role in the edit screen (add - change). The field "destination role" will be displayed in the list.

  • Show edit menu Standard: if set to N then the buttons "Add", "edit" and "suppression does not appear.

  • History management (show history button): if set to N then the buttons "invalidate" and "view history" not appear

  • delete button (Show Delete button): if set to N then the buttons "delete" does not appear, often only used to force the use of archiving.

Security rules

  • nothing at the screenlet level, only at the update service level (and component rules)

Technical remarks

This screenlet list only entity PartyRelationship with partyIdFrom == partyId selected. A other screenlet exist for partyIdTo = partyId

When Role From and/or To are not define (field by the user or in parameters), NA is used.

Party Lists to which it is associated

This screenlet displays the parties to which it is associated to the selected Party. The display and behavior depend on its setting.

To characterize the relationship between two parties, we must specify the "relationship type", the more fluently this screenlet is used for a specific relationship Type, eg

  • "Contact", ie list all sales reps or customer, to which he is a contact;

  • "Employee", ie list all company where a person is employed;

  • "Team Member", ie list all team or group to which person is member;

  • ...

For a relationship between Party, it is also possible to specify the role of the party associated, for example in the case of Relationship Type "employee", the role will detail the role of the employee in the company.
In most cases this field does not appear because it is not necessary.

A relationship between Party possesses validity date (from date .. thru date ..), it is possible to keep a history. Depending on the setting it is also possible to delete a relationship in which case the history will not be retained.

Screenlet parameters

  • Screenlet Title: You must include a "UiLabel" (a code according to a language that give wording), it allows you to customize the screenlet Title this is useful when the portlet is used several times in the same page. Ask a technical consultant to find the UILabel corresponding to your needs, or to define a new one.

  • Role From Type: If this field is filled, the list displayed will be filter (only this role) and in editing (add or change) this value will be used, the role field will not be shown to the user. Usually, this parameter is left blank.

  • Role Group : If the field Role From is empty, indicates the group from which the role will be selectable in the edit screen (add - change). The field "original role" will be displayed in the list

  • Party Relationship Type Id : indicate the RelationshipType to use to filter relationships to display, or leave it blank to display all and therefore this field.

  • Party associated Role (Role Type To): If this field is filled, the list displayed will be filter (only this role) and in editing (add or change) this value will be used, field "role to" will not be displayed to the user.

  • Role To Group: If the field RoleTo is empty, indicates the group from which the user will select a role in the edit screen (add - change). The field "destination role" will be displayed in the list.

  • Show edit menu Standard: if set to N then the buttons "Add", "edit" and "suppression does not appear.

  • History management (show history button): if set to N then the buttons "invalidate" and "view history" not appear

  • delete button (Show Delete button): if set to N then the buttons "delete" does not appear, often only used to force the use of archiving.

Security rules

  • nothing at the screenlet level, only at the update service level (and component rules)

Technical remarks

This screenlet list only entity PartyRelationship with partyIdTo == partyId selected. A other screenlet exist for partyIdFrom = partyId

When Role From and/or To are not define (field by the user or in parameters), NA is used.

Select a Party.

This screenlet is used to select one Party to do a current page update.

Screenlet parameters

  • uri for lookup: default value is lookupParty, this parameters is useful when Portal Page which used this portlet is only for a "group" of party, filter on Party Type, Role Type, …​. Ask to a technical consultant to know the existing lookup or to define a new one.

Security rules

  • nothing (component rules only)

3.2. Example

3.2.1. Category Example.

This category is for Example component. There is only one category for Example component.

Find Examples

It’s the standard search criteria form to be able to show a example list print.
This screenlet update watcherName listExample.

Screenlet parameters

  • no

Security rules

  • nothing (component rules only)

Example List

List all examples according to the search criteria provided in watcherName ListExample

In the list, exampleId is a link to select the example for all portlet watching watcherName showExample
(the link update watcherName showExample)
Click on link collapse the list. It’s possible to un-collapse without doing a new search.

Screenlet parameters

GenericRecapPageParam to give

  • recapPageId : give id to use as link to go to recap page for one example.

Security rules

  • nothing (component rules only)

DetailMenu for one example

For one example (exampleId is in the parameterized watcherName in the portal page) Show a summary, a link to the recap page and a menu to choose what detail to show for this example in the ExampleDetail container.

This screenlet is completely empty if there is no exampleId in watcherName.

Screenlet parameters

  • no

Security rules

  • nothing (component rules only)

Example Detail

Container used to show one detail about one example, one detail means a associated entity with example (ex: show exampleFeature associated to the example or show exampleItems associated to the example or …​)

This screenlet store which screenlet to show each time it’s call, and will be updated each time the exampleId value in the parameterized watcherName in the portal page is updated.

This screenlet is used to define where show the detail.

Screenlet parameters

  • no

Security rules

  • nothing (component rules only)

Show Example

Show all example field for one example.

It’s possible to edit the example. When some modification is validated in this screenlet, watcherName exampleStatus is update. So if screenlet ExampleStatus is in the same page and watch this watcherName a new call to the server is done for it.

Screenlet parameters

  • no

Security rules

  • nothing (component rules only)

Example Items

Lists items for one example and manage them, create new one, edit existing or delete it.

This screenlet is completely empty if it is call with no exampleId.

Screenlet parameters

GenericEditEditOrShowParam is used for parameters form so,

  • showEditButton : Y or N, show or not the edit button in items list for each item

  • showScreenletMenu : Y or N, show or not edit menu in the screenlet bar, in this case the Add item button.

Security rules

  • nothing (component rules only)

Example status History

List all status change for the current example.

This screenlet is completely empty if it is call with no exampleId.

Screenlet parameters

  • no

Security rules

  • nothing (component rules only)

Example Feature associated to a example

Lists ExampleFeatures associated for one example and manage association, create new one, edit existing or delete it.

This screenlet contain a link to Create a new ExampleFeature out of this screenlet.

This screenlet is completely empty if it is call with no exampleId

Screenlet parameters

GenericEditEditOrShowParam is used for parameters form so,

  • showEditButton : Y or N, show or not the edit button in features list for each feature

  • showScreenletMenu : Y or N, show or not edit menu in the screenlet bar, in this case the Add a new feature association.

Security rules

  • nothing (component rules only)