Configure dependencies between additional fields

Petition Details

Base URL: {host}/ASMSAPI/
Uri: /api/v9/additionalsfields/dependents/load
Type: POST
Required headings:
content-type: application/json
X-Authorization: Bearer {token}

URL Description

{host}: It represents the domain of the environment in which the API is located.
ASMSAPI/: Fixed API prefix.
URI: Specific endpoint for the request.

⚐ EXAMPLE URL:

https://{host}/ASMSAPI/api/v9/additionalsfields/dependents/load

Request Body Parameters

Name	Data type	Obligatory	Description
dependencies	List	Yes	An array of objects that defines the dependencies to be configured. Multiple dependencies can be sent in a single request.
sourceFieldId	Number	Yes	Parent field identifier. Only List, CatalogList, and CheckBox fields are allowed.
triggerValueId	Number	Yes	The ID of the value of the parent field that triggers the dependency. For List and CatalogList fields, it is obtained from the value query endpoint. For CheckBox type fields the value is always 1 (true).
targetFieldId	Number	Yes	The ID of the child field that is activated when the parent field has the value set to triggerValueId.
visible	Boolean	Yes	Indicates whether the child field is visible when the dependency is activated.
editable	Boolean	Yes	Indicates whether the child field is editable when the dependency is activated.
mandatory	Boolean	Yes	Indicates whether the child field is required when the dependency is activated.
inheritValues	Boolean	Yes	Indicates whether the ShortText child field automatically inherits the key from the value selected in the parent CatalogList field. It only applies when the child field is of type ShortText.
filteredValueIds	List	No	An array of identifiers for the child field values that will be displayed when the dependency is activated. If it is sent empty, the child field displays all of its available values. It only applies to List and CatalogList child fields.

⚐ NOTE:

A child field can only have A single parent field. If you try to configure a child field that already has another parent assigned, the dependency will return success: false.

The parent field and the child field must belong to the Same model and to the Same type of case. Z- The parent field cannot be the same as the child field.

Only the type fields List, CatalogList and CheckBox they can act as a parent field.

It can only exist a ShortText field with inheritValues=true by combination of sourceFieldId + triggerValueId.

If an existing dependency is forwarded (same sourceFieldId + targetFieldId + triggerValueId), the system performs a upsert- Updates properties and replaces existing filteredValueIds.

The processing is Independent by item: If one dependency fails, the others are processed successfully.

Auto-correct properties

The system applies the following automatic corrections when inconsistent combinations of visible, editable, and mandatory are submitted:

Combination sent	Persistent result
mandatory=true, visible=false, editable=false	visible=true, editable=true, mandatory=true
editable=true, visible=false	visible=true, editable=true
visible=false, editable=false, mandatory=false	visible=false, editable=false, mandatory=false

⚐ NOTE: For Type Fields CheckBox As the parent field, the endpoint accepts the sending of filteredValueIds and the visible, editable, and mandatory properties, however this setting has no impact on consoles Specialist and Customer. From the Administrator console, you can’t configure filtered values or properties for CheckBox field dependencies.

Body of the petition

List → List dependency with filteredValueIds:

{
    "dependencies": [
        {
            "sourceFieldId": 543,
            "triggerValueId": 494,
            "targetFieldId": 544,
            "visible": true,
            "editable": true,
            "mandatory": true,
            "inheritValues": false,
            "filteredValueIds": [497, 498, 499]
        }
    ]
}

CatalogList dependency → ShortText with inheritValues:

{
    "dependencies": [
        {
            "sourceFieldId": 545,
            "triggerValueId": 81,
            "targetFieldId": 546,
            "visible": true,
            "editable": true,
            "mandatory": false,
            "inheritValues": true,
            "filteredValueIds": []
        }
    ]
}

CheckBox Dependency → List:

{
    "dependencies": [
        {
            "sourceFieldId": 552,
            "triggerValueId": 1,
            "targetFieldId": 544,
            "visible": true,
            "editable": true,
            "mandatory": false,
            "inheritValues": false,
            "filteredValueIds": []
        }
    ]
}

Multiple dependencies in a single request:

{
    "dependencies": [
        {
            "sourceFieldId": 543,
            "triggerValueId": 494,
            "targetFieldId": 544,
            "visible": true,
            "editable": true,
            "mandatory": true,
            "inheritValues": false,
            "filteredValueIds": [497, 498]
        },
        {
            "sourceFieldId": 543,
            "triggerValueId": 495,
            "targetFieldId": 544,
            "visible": true,
            "editable": true,
            "mandatory": true,
            "inheritValues": false,
            "filteredValueIds": [500]
        }
    ]
}

Answer

{
    "content": [
        {
            "errorMessage": null,
            "sourceFieldId": 543,
            "success": true,
            "targetFieldId": 544,
            "triggerValueId": 494
        }
    ],
    "totalItems": 1
}

Response Parameters

Name	Data type	Description
totalItems	Number	Total dependencies processed in the petition.
content	List	List with the result of each dependency sent.
sourceFieldId	Number	Identifier of the parent field sent in the request.
targetFieldId	Number	The identifier of the child field sent in the request.
triggerValueId	Number	The identifier of the trigger value sent in the request.
success	Boolean	Indicates whether the dependency was successfully configured. If it is `false`, the errorMessage field describes the reason.
errorMessage	Text	Description of the error when success is `false`. Its value is `null` when the operation is successful.

Error messages

Code	HTTP status	Error Message
200	OK	`success: false — Source field {id} not found or deleted`
200	OK	`success: false — Source and target field cannot be the same`
200	OK	`success: false — Source field type '{tipo}' is not valid. Must be List, CatalogList or CheckBox`
200	OK	`success: false — Trigger value {id} does not exist in source field {id}`
200	OK	`success: false — inheritValues is only valid for target fields of type ShortText, but target is '{tipo}'`
200	OK	`success: false — Only one ShortText with inheritValues=true is allowed per source+triggerValue in a single request (source {id}, triggerValue {id})`
200	OK	`success: false — Source field model ({id}) does not match target field model ({id})`
401	Unauthorized	Token not provided or expired.
500	InternalServerError	FailureLoadDependentFields