Field value

[!info] Overview The FieldValue REST API manages predefined values and options for dynamic form fields in the pkbillms billing system. FieldValues define selectable options, pricing information, and filtering logic for field configurations with multilingual support.

📋 Table of Contents

Quick Reference

[!abstract] API Configuration
Base URL: /api
Entity Name: FieldValue
Controller: FieldValueResource
Framework: Spring Boot + JHipster
Auth: Required (Spring Security)
Content-Type: application/json

Endpoints Summary

Method

Endpoint

Description

Status

POST

/api/field-values

Create new field value

201

PUT

/api/field-values/{id}

Full update

200

PATCH

/api/field-values/{id}

Partial update

200

GET

/api/field-values

Get all with pagination

200

GET

/api/field-values/get

Get all (alternative)

200

GET

/api/field-values/criteria

Get by criteria + field

200

GET

/api/v2/field-values

Get V2 projection

200

GET

/api/field-values/{id}

Get by ID

200

GET

/api/field-values/count

Count by criteria

200

DELETE

/api/field-values/{id}

Delete field value

204

DELETE

/api/field-values/cascaded/{id}

Cascaded delete

200

Data Models

FieldValue Specifications

Field

Type

Required

Max/Range

Description

id

Long

❌ Auto

Primary key

value

String

✅

Param value to send to server

amount

Long

❌

Price of selected value

filterBy

String

❌

Filter by parent field

ord

Integer

❌

Display order

checkId

String

❌

Check identifier

field

FieldDTO

✅

Parent field reference

titles

Set

✅

Multilingual titles

descriptions

Set

❌

Multilingual descriptions

API Endpoints

Create FieldValue

POST /api/field-values
Creates a new field value option.

Request

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

{
  "value": "50000",
  "amount": 50000,
  "filterBy": "mobile",
  "ord": 1,
  "field": {
    "id": 5
  },
  "titles": [
    {
      "lang": "EN",
      "text": "50,000 UZS"
    },
    {
      "lang": "RU",
      "text": "50 000 сум"
    },
    {
      "lang": "UZ",
      "text": "50 000 so'm"
    }
  ],
  "descriptions": [
    {
      "lang": "EN",
      "text": "Standard package"
    }
  ]
}

[!warning] Validation Rules
id must be null (auto-generated)
value and field are required
value max length is 64 characters
filterBy max length is 16 characters

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/field-values/1

{
  "id": 1,
  "value": "50000",
  "amount": 50000,
  "filterBy": "mobile",
  "ord": 1,
  "field": {
    "id": 5,
    "name": "amount",
    "type": "AMOUNT"
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "50,000 UZS"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "50 000 сум"
    },
    {
      "id": 3,
      "lang": "UZ",
      "text": "50 000 so'm"
    }
  ],
  "descriptions": [
    {
      "id": 4,
      "lang": "EN",
      "text": "Standard package"
    }
  ]
}

❌ Error (400 - ID exists):

{
  "status": 400,
  "detail": "A new fieldValue cannot already have an ID",
  "message": "error.idexists",
  "entityName": "pkbillmsFieldValue",
  "errorKey": "idexists"
}

Update FieldValue

PUT /api/field-values/{id}
Updates an existing field value (full update).

Request

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

{
  "id": 1,
  "value": "50000",
  "amount": 55000,
  "filterBy": "mobile",
  "ord": 1,
  "field": {
    "id": 5
  },
  "titles": [
    {
      "lang": "EN",
      "text": "55,000 UZS"
    }
  ]
}

[!warning] Validation Rules
id must match path parameter
id must not be null
FieldValue must exist in database

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "value": "50000",
  "amount": 55000,
  "filterBy": "mobile",
  "ord": 1,
  "field": {
    "id": 5,
    "name": "amount"
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "55,000 UZS"
    }
  ]
}

❌ Error (400 - Invalid ID):

{
  "status": 400,
  "detail": "Invalid ID",
  "message": "error.idinvalid",
  "entityName": "pkbillmsFieldValue",
  "errorKey": "idinvalid"
}

❌ Error (400 - Not found):

{
  "status": 400,
  "detail": "Entity not found",
  "message": "error.idnotfound",
  "entityName": "pkbillmsFieldValue",
  "errorKey": "idnotfound"
}

Partial Update

PATCH /api/field-values/{id}
Partially updates field value properties.

Request

Headers:

Content-Type: application/merge-patch+json
Authorization: Bearer {token}

Body:

{
  "id": 1,
  "amount": 60000,
  "ord": 2
}

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "value": "50000",
  "amount": 60000,
  "ord": 2,
  "field": {
    "id": 5
  }
}

❌ Error (404 - Not Found):

HTTP/1.1 404 Not Found

Get All FieldValues

GET /api/field-values
Retrieves all field values with pagination and filtering.

Request

Headers:

Authorization: Bearer {token}

Query Parameters:

Parameter

Type

Required

Description

page

Integer

❌

Page number (default: 0)

size

Integer

❌

Page size (default: 20)

sort

String

❌

Sort field and direction

unPaged

Boolean

❌

Disable pagination

Example:

GET /api/field-values?page=0&size=10&sort=ord,asc

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-Total-Count: 25

[
  {
    "id": 1,
    "value": "50000",
    "amount": 50000,
    "ord": 1,
    "field": {
      "id": 5,
      "name": "amount"
    },
    "titles": [
      {
        "lang": "EN",
        "text": "50,000 UZS"
      }
    ]
  },
  {
    "id": 2,
    "value": "100000",
    "amount": 100000,
    "ord": 2,
    "field": {
      "id": 5,
      "name": "amount"
    },
    "titles": [
      {
        "lang": "EN",
        "text": "100,000 UZS"
      }
    ]
  }
]

Get All FieldValues (Alternative)

GET /api/field-values/get
Alternative endpoint for retrieving field values.

Request

Headers:

Authorization: Bearer {token}

Query Parameters: Same as main GET endpoint plus FieldValueCriteria filters.

Example:

GET /api/field-values/get?fieldId.equals=5&page=0&size=10

Response

✅ Success (200 OK): Same format as main GET endpoint.

FieldValueCriteria - Advanced Filtering

[!abstract] JHipster Criteria Filtering FieldValueCriteria provides powerful filtering capabilities for querying field values. All filter parameters support multiple operators for precise data retrieval.

Available Filter Types

String Filters:

Operator

Description

Example

equals

Exact match

value.equals=50000

notEquals

Not equal

value.notEquals=100000

in

Match any value

value.in=50000,100000,150000

notIn

Not in list

value.notIn=0,5000

contains

Partial match

value.contains=000

doesNotContain

Doesn't contain

filterBy.doesNotContain=test

specified

Field exists/null

filterBy.specified=true

Numeric Filters (Long, Integer):

Operator

Description

Example

equals

Exact match

amount.equals=50000

notEquals

Not equal

amount.notEquals=0

in

Match any value

amount.in=50000,100000

notIn

Not in list

amount.notIn=0

greaterThan

Greater than

amount.greaterThan=50000

lessThan

Less than

amount.lessThan=100000

greaterOrEqualThan

Greater or equal

amount.greaterOrEqualThan=50000

lessOrEqualThan

Less or equal

amount.lessOrEqualThan=100000

specified

Field exists/null

amount.specified=true

Get FieldValues by Criteria

GET /api/field-values/criteria
Retrieves field values filtered by field name and criteria.

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/field-values/criteria?fieldName=amount&amount.greaterThan=50000&sort=ord,asc

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-Total-Count: 5

[
  {
    "id": 2,
    "value": "100000",
    "amount": 100000,
    "ord": 2,
    "field": {
      "id": 5,
      "name": "amount"
    }
  },
  {
    "id": 3,
    "value": "150000",
    "amount": 150000,
    "ord": 3,
    "field": {
      "id": 5,
      "name": "amount"
    }
  }
]

FieldValueCriteria Parameters

public class FieldValueCriteria implements Serializable, Criteria {
    private LongFilter id;
    private StringFilter value;
    private LongFilter amount;
    private StringFilter filterBy;
    private StringFilter checkId;
    private IntegerFilter ord;
    private LongFilter fieldId;           // Filter by parent field
    private LongFilter titleId;           // Filter by title I18n
    private LongFilter descriptionId;     // Filter by description I18n
}

Common Query Examples

Filter by Field:

GET /api/field-values?fieldId.equals=5

Filter by Amount Range:

GET /api/field-values?amount.greaterThan=50000&amount.lessThan=200000

Filter with filterBy:

GET /api/field-values?filterBy.equals=mobile&fieldId.equals=5

Search by Value:

GET /api/field-values?value.contains=000&fieldId.equals=5

Values with Amount:

GET /api/field-values?amount.specified=true&fieldId.equals=5

Sorted by Display Order:

GET /api/field-values?fieldId.equals=5&sort=ord,asc

Complex Filter (AND operation):

GET /api/field-values?fieldId.equals=5&amount.greaterThan=50000&filterBy.equals=mobile&sort=ord,asc

Combining Filters

[!tip] Multiple Criteria All criteria are combined with AND logic. Use .in operator for OR logic on same field.

Example:

# AND: Field=5 AND Amount>50000
GET /api/field-values?fieldId.equals=5&amount.greaterThan=50000

# OR (same field): Value=50000 OR Value=100000
GET /api/field-values?value.in=50000,100000&fieldId.equals=5

Get FieldValues V2

GET /api/v2/field-values
Retrieves field values using V2 projection (optimized response).

Request

Headers:

Authorization: Bearer {token}

Query Parameters: Same as standard criteria endpoint.

Example:

GET /api/v2/field-values?fieldId.equals=5&page=0&size=10

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-Total-Count: 10

[
  {
    "id": 1,
    "value": "50000",
    "amount": 50000,
    "ord": 1,
    "fieldId": 5
  },
  {
    "id": 2,
    "value": "100000",
    "amount": 100000,
    "ord": 2,
    "fieldId": 5
  }
]

[!info] V2 Projection V2 endpoint returns a lighter projection without nested objects for better performance.

Get Single FieldValue

GET /api/field-values/{id}
Retrieves a single field value by ID.

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/field-values/1

Response

✅ Success (200 OK):

{
  "id": 1,
  "value": "50000",
  "amount": 50000,
  "filterBy": "mobile",
  "ord": 1,
  "checkId": "CHK001",
  "field": {
    "id": 5,
    "name": "amount",
    "type": "AMOUNT",
    "controlType": "SELECT"
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "50,000 UZS"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "50 000 сум"
    }
  ],
  "descriptions": [
    {
      "id": 3,
      "lang": "EN",
      "text": "Standard package"
    }
  ]
}

❌ Error (404 - Not found):

HTTP/1.1 404 Not Found

Count FieldValues

GET /api/field-values/count
Counts field values matching criteria.

Request

Headers:

Authorization: Bearer {token}

Query Parameters: Any FieldValueCriteria filters.

Example:

GET /api/field-values/count?fieldId.equals=5&amount.greaterThan=50000

Response

✅ Success (200 OK):

Delete FieldValue

DELETE /api/field-values/{id}
Deletes a field value.

Request

Headers:

Authorization: Bearer {token}

Example:

DELETE /api/field-values/1

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

Cascaded Delete FieldValue

[!example] DELETE /api/field-values/cascaded/{id} Deletes a field value with all related entities (I18n translations).

Request

Headers:

Authorization: Bearer {token}

Example:

DELETE /api/field-values/cascaded/1

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

Error Handling

Error Response Format

{
  "type": "https://www.jhipster.tech/problem/problem-with-message",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed",
  "path": "/api/field-values",
  "message": "error.validation",
  "entityName": "pkbillmsFieldValue",
  "errorKey": "validation",
  "fieldErrors": [
    {
      "objectName": "fieldValueDTO",
      "field": "value",
      "message": "must not be null"
    }
  ]
}

HTTP Status Codes

Code

Description

When

200

Successful GET/PUT/PATCH

201

Created

Successful POST

204

No Content

Successful DELETE

400

Bad Request

Validation error

401

Unauthorized

Missing/invalid authentication

403

Forbidden

Insufficient permissions

404

Not Found

Resource doesn't exist

500

Internal Server Error

Server error

Validation Rules

Required Fields

[!check] Mandatory Fields
✅ value - Value to send to server
✅ field - Parent field reference
✅ titles - At least one title (I18n)

Field Constraints

Field

Rules

Error Messages

id

Null for POST

"A new fieldValue cannot already have an ID"

id

Not null for PUT/PATCH

"Invalid id"

value

@NotNull, @Size(max=64)

"must not be null", "size must be between 0 and 64"

filterBy

@Size(max=16)

"size must be between 0 and 16"

field

@NotNull

"must not be null"

titles

@NotNull

"must not be null"

Business Rules

[!info] Business Validation
value is used as the parameter sent to backend services
amount represents pricing information for the selected value
filterBy enables dependent dropdown filtering (parent-child relationships)
ord determines display order in UI select elements
checkId is used for validation and reconciliation processes
titles must include at least one language translation
descriptions are optional additional information

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/field-values \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "value": "50000",
    "amount": 50000,
    "filterBy": "mobile",
    "ord": 1,
    "field": {"id": 5},
    "titles": [
      {"lang": "EN", "text": "50,000 UZS"},
      {"lang": "RU", "text": "50 000 сум"},
      {"lang": "UZ", "text": "50 000 som"}
    ],
    "descriptions": [
      {"lang": "EN", "text": "Standard package"}
    ]
  }'

Update

curl -X PUT http://localhost:8080/api/field-values/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "value": "50000",
    "amount": 55000,
    "ord": 1,
    "field": {"id": 5},
    "titles": [{"lang": "EN", "text": "55,000 UZS"}]
  }'

Partial Update

curl -X PATCH http://localhost:8080/api/field-values/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"id": 1, "amount": 60000, "ord": 2}'

Get All

curl -X GET "http://localhost:8080/api/field-values?page=0&size=10&sort=ord,asc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get by Criteria (with Field Name)

curl -X GET "http://localhost:8080/api/field-values/criteria?fieldName=amount&amount.greaterThan=50000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get by Criteria (Standard)

curl -X GET "http://localhost:8080/api/field-values?fieldId.equals=5&amount.greaterThan=50000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get V2

curl -X GET "http://localhost:8080/api/v2/field-values?fieldId.equals=5&page=0&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Single

curl -X GET http://localhost:8080/api/field-values/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Count

curl -X GET "http://localhost:8080/api/field-values/count?fieldId.equals=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

curl -X DELETE http://localhost:8080/api/field-values/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Cascaded Delete

curl -X DELETE http://localhost:8080/api/field-values/cascaded/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

📝 Notes

[!tip] Best Practices
Always provide meaningful ord values for proper sorting
Use filterBy for cascading dropdown dependencies
Include translations for all supported languages
Set appropriate amount values for pricing information
Use checkId for validation and reconciliation tracking

[!warning] Important
Deleting field values may affect active payment forms
Use cascaded delete carefully as it removes all I18n data
value field is sent to backend services - ensure proper validation
V2 endpoint provides better performance for large datasets

PreviousField NextResponse field

Last updated 1 month ago

hashtag📋 Table of Contents

hashtagQuick Reference

hashtagEndpoints Summary

hashtagData Models

hashtagFieldValue Specifications

hashtagAPI Endpoints

hashtagCreate FieldValue

hashtagRequest

hashtagResponse

hashtagUpdate FieldValue

hashtagRequest

hashtagResponse

hashtagPartial Update

hashtagRequest

hashtagResponse

hashtagGet All FieldValues

hashtagRequest

hashtagResponse

hashtagGet All FieldValues (Alternative)

hashtagRequest

hashtagResponse

hashtagFieldValueCriteria - Advanced Filtering

hashtagAvailable Filter Types

hashtagGet FieldValues by Criteria

hashtagRequest

hashtagResponse

hashtagFieldValueCriteria Parameters

hashtagCommon Query Examples

hashtagCombining Filters

hashtagGet FieldValues V2

hashtagRequest

hashtagResponse

hashtagGet Single FieldValue

hashtagRequest

hashtagResponse

hashtagCount FieldValues

hashtagRequest

hashtagResponse

hashtagDelete FieldValue

hashtagRequest

hashtagResponse

hashtagCascaded Delete FieldValue

hashtagRequest

hashtagResponse

hashtagError Handling

hashtagError Response Format

hashtagHTTP Status Codes

hashtagValidation Rules

hashtagRequired Fields

hashtagField Constraints

hashtagBusiness Rules

hashtag🔧 cURL Command Reference

hashtagCreate

hashtagUpdate

hashtagPartial Update

hashtagGet All

hashtagGet by Criteria (with Field Name)

hashtagGet by Criteria (Standard)

hashtagGet V2

hashtagGet Single

hashtagCount

hashtagDelete

hashtagCascaded Delete

hashtag📝 Notes

📋 Table of Contents

Quick Reference

Endpoints Summary

Data Models

FieldValue Specifications

API Endpoints

Create FieldValue

Request

Response

Update FieldValue

Request

Response

Partial Update

Request

Response

Get All FieldValues

Request

Response

Get All FieldValues (Alternative)

Request

Response

FieldValueCriteria - Advanced Filtering

Available Filter Types

Get FieldValues by Criteria

Request

Response

FieldValueCriteria Parameters

Common Query Examples

Combining Filters

Get FieldValues V2

Request

Response

Get Single FieldValue

Request

Response

Count FieldValues

Request

Response

Delete FieldValue

Request

Response

Cascaded Delete FieldValue

Request

Response

Error Handling

Error Response Format

HTTP Status Codes

Validation Rules

Required Fields

Field Constraints

Business Rules

🔧 cURL Command Reference

Create

Update

Partial Update

Get All

Get by Criteria (with Field Name)

Get by Criteria (Standard)

Get V2

Get Single

Count

Delete

Cascaded Delete

📝 Notes