API - Export Generic API

The generic export aims to facilitate the export of data from the database.

As for the generic api, It defines generic endpoints, so the API can survive future changes in the model without any upgrade of the API code.

Documentation need to update after API changes.

API Definition

• Method : POST

• URL : http://{host}/opencell/api/rest/v2/generic/export/{entityName}/{fileFormat}

Path parameters

• entityName name of JPA entity in Model (\opencell-core\opencell-model\src\main\java\org\meveo\model)

• fileFormat which specify the output file format. Three value are supported :

  • PDF

  • CSV

  • EXCEL

JSON Body

• genericFields Set of field desired for export

  • Using this collection of field, the order will not be respected

• genericFieldDetails List of field desired for export, with more possibilities :

  • name : Name of field

  • header : Header name of column

  • transformation : The applied transformation, two kind of supported transofrmation :

    • Number : such as ###0.00 or ###0.00 $

    • Date : supported Java date time format, such as dd/MM/yyyy or MM/dd/yyyy HH:mm

  • mappings : Used only for Enum type, this option provide a set of key/value, which :

    • Key : is the name() of Enum

    • Value : the desired converted value that will be displayed in exported column

• limit : Max row to export

• sortBy : Sorted column for fetched data

• sortOrder : ASCENDING or DESCENDING

Basic export

This is the basic use of generic export, that can fetch raw data without any specified header or format.

{
	"genericFields": [
		"openOrderNumber",
		"billingAccount.code",
		"billingAccount.customerAccount.code",
		"activationDate",
		"currency.currency",
		"initialAmount",
		"balance",
		"initialAmount-balance",
		"status"
	],
	"limit": 9999999,
	"offset": 0,
	"sortBy": "id",
	"sortOrder": "ASCENDING"
}

Exported result example :

Formated export

Using genericFieldDetails we can add more detail on export result, such as :

{
	"genericFieldDetails": [
		{
			"name": "openOrderNumber",
			"header": "Open order number",
			"transformation": ""
		},{
			"name": "billingAccount.code",
			"header": "Customer",
			"transformation": ""
		},{
			"name": "billingAccount.customerAccount.code",
			"header": "Consumer",
			"transformation": ""
		},{
			"name": "activationDate",
			"header": "Activation date",
			"transformation": "dd/MM/yyyy"
		},{
			"name": "currency.currency",
			"header": "Currency",
			"transformation": ""
		},{
			"name": "initialAmount",
			"header": "Initial amount",
			"transformation": "0.00"
		},{
			"name": "balance",
			"header": "Current balance",
			"transformation": "###0.00"
		},{
			"name": "initialAmount-balance",
			"header": "Invoiced",
			"transformation": "###0.00 $"
		},{
			"name": "status",
			"header": "Status",
			"transformation": "",
			"mappings": {
				"NEW":"New",
				"IN_USE":"In use",
				"EXPIRED":"Expired",
				"SOLD_OUT":"Sold out",
				"CANCELED":"Canceled"
			}
		}
	],
	"limit": 9999999,
	"offset": 0,
	"sortBy": "id",
	"sortOrder": "ASCENDING"
}

So we are going to :

• Keep order of exported column

• Add specific Header name for each column (FrontEnd side can use it to change value depond on used Locale)

• Add specific format for number

• Add specific pattern o date (FrontEnd side can use it to change value depond on used Locale)

• Avoir displayed name of Enum, and use more friendly value (FrontEnd side can use it to change value depond on used Locale)

The result of same example of Basic export is the following :

… / …