Retrieve the Schema of Custom Fields and Workflow Actions

Not all fields and actions that are available for an entity on the corresponding MYOB Acumatica form may be included in the system endpoint. However, you can still work with some of these fields and actions through the REST API. For each top-level entity, the REST API provides the schema of custom fields and workflow actions.

Custom fields of an entity are the fields that are not defined in the endpoint for this entity. For each custom field, the schema includes the view name, field name, and type of the custom field. For more details, see Custom Fields.

Tip:

Custom fields can correspond to the following elements:

The predefined elements on an MYOB Acumatica form that are not included in the entity definition
The elements that were added to the MYOB Acumatica form in a customization project
The user-defined fields

Workflow actions are the actions defined in the workflow of the form. (See more information in Workflow Actions: General Information.) For each workflow action that is not included in the endpoint for an entity, the schema includes the name of the action and information about its parameters, including the name and type of each parameter.

To retrieve this schema by using the REST API, you access the needed URL with the GET HTTP method. See the following sections for details on the request and the response.

HTTP Method and URL

If you need to obtain the schema of custom fields of an entity, you use the GET HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>/$adHocSchema

The URL includes the following components:

<Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work with MYOB Acumatica. This URL has the following format: http://<MYOB Acumatica instance URL>/entity/<Endpoint name>/<Endpoint version>/.
<Top-level entity> is the name of the entity for which you are going to retrieve the schema of custom fields.

For example, suppose that you want to obtain the schema of custom fields of a stock item entity from a local MYOB Acumatica instance with the name AcumaticaDB by using the system endpoint with the name Default and Version 25.200.001. You would use the following URL to retrieve the schema: http://localhost/AcumaticaDB/entity/Default/25.200.001/StockItem/$adHocSchema.

Parameters

You use no parameters when you retrieve the schema of custom fields.

Request Headers

You specify the following header in the request.


Header	Description
Accept	Specifies the format of the response body, which should be application/json.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves the schema of the custom fields of an entity.


Code	Description
200	The request has been completed successfully. The response body contains: The custom fields in each entity with the view name, field name, and type of the custom fields The _workflowActions field with the names of workflow actions and information about their parameters, including the name and type of each parameter
401	The user is not signed in to the system.
403	The user has insufficient rights to access the MYOB Acumatica form that corresponds to the API entity.
429	The number of requests has exceeded the limit imposed by the license (see License Restrictions for API Users).
500	An internal server error has occurred.

Example

The following request shows an example of the retrieval of the schema of custom fields and workflow actions of the Opportunity entity.

Tip:

In the request example below, <MYOB Acumatica host> is the URL of the MYOB Acumatica host (such as https://my.acumatica.com). You need to use the instance name in the URL of the request (such as https://my.acumatica.com/MyInstance) if the instance is not installed in the root of the website.

GET /entity/Default/25.200.001/Opportunity/$adHocSchema HTTP/1.1
Host: <MYOB Acumatica host>
Accept: application/json
Content-Type: application/json

The following fragment of response shows an example of custom fields of the entity.

"TaxDetails": [
        {
            ...,
            "custom": {
                "Taxes": {
                    "CuryExemptedAmt": {
                        "type": "CustomDecimalField",
                        "value": null
                    },
                    "TaxUOM": {
                        "type": "CustomStringField",
                        "value": null
                    },
                    "TaxableQty": {
                        "type": "CustomDecimalField",
                        "value": null
                    },
                    "RecordID": {
                        "type": "CustomIntField",
                        "value": null
                    },
                    "QuoteID": {
                        "type": "CustomGuidField",
                        "value": null
                    }
                }
            }
        }
    ],

The following fragment of response shows an example of information about a workflow action of the entity.

"_workflowActions": [
        {
            "Open": {
                "parameters": {
                    "custom": {
                        "FilterPreview": {
                            "Reason": {
                                "type": "CustomStringField",
                                "value": null
                            },
                            "Stage": {
                                "type": "CustomStringField",
                                "value": null
                            }
                        }
                    }
                }
            }
        },
        ...
]