Execute a Custom Action

Contract Version 4 allows you to execute actions that are not present in the endpoint. These actions can be defined in the forms' graphs or in customization projects.

To perform an action by using the contract-based REST API, you access the needed URL with the POST HTTP method and pass the record representation in JSON format and the parameters of the action in the request body. See the following sections for details on the request and the response.

HTTP Method and URL

If you need to perform an action on an MYOB Acumatica form, you use the POST HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>/<Action name>

The URL has the following components:

<Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work with MYOB Acumatica, which 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 perform an action.
<Action name> is the name of the action that you are going to perform. If an action is defined for a UI element, you can find out the action name as follows: on the title bar of the form, you click Customization > Inspect Element and click the needed element on the form. In the Element Properties dialog box, which opens, you find the action name in the Action Name element.

For example, suppose that you want to invoke the Close action of some Case entity in a local MYOB Acumatica instance with the name AcumaticaDB by using the system endpoint with the name Default and Version 23.200.001. You should use the following URL to invoke the action.

http://localhost/AcumaticaDB/entity/Default/23.200.001/Case/Close

Parameters

You use no parameters when you execute an action.

Request Headers

You can specify the following headers in the request.


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

HTTP Body

For the invocation of a custom action, an HTTP body with the following pattern is used.

{
    "entity": {
        "id": "<entity id>"
    },
    "parameters": {
        "custom": {
            ...
        }
    }    
}

In this pattern, the following information is provided:

<entity id> is the identifier of the entity for which you need to invoke a custom action. For more information, see Retrieve a Record by ID. You can also use the key fields to define the entity.
The custom collection contains the parameters of the action that are normally entered in a dialog box that the system displays upon the execution of the action. You need to specify the parameters' names and the view in which the parameters are defined. You can find out this information as follows: Execute the action from the UI, press Ctrl+Alt, and click the parameter’s input box. In the Element Properties dialog box, which opens, you find the parameter name in the Data Field element and the view name in the View Name element.

You can find details on how to represent a record in JSON format in Representation of a Record in JSON Format.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that performs an action.


Code	Description
202	The operation is in progress. The `Location` header of the response contains the URL that you can use to check the status of the operation by using the `GET` HTTP method. When the `GET` HTTP method with this URL returns 204 No Content, the operation is completed.
204	The operation that has been initiated by the action has completed or was not created.
400	The data specified in the request is invalid.
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 entity.
404	The action with this name does not exist.
422	The data specified in the request is invalid and the validation errors are returned in the error fields of the response body, as in the following example. `"CustomerID": { "value": "ABARTENDE1", "error": "'Customer' cannot be found in the system." }`
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

For example, suppose that you want to invoke the Close action of some Case entity in a local MYOB Acumatica instance with the name AcumaticaDB by using the system endpoint with the name Default and Version 23.200.001. The Close action has the only Reason parameter, which is defined in the FilterPreview view. Following is an example of a request.

Tip:

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

POST / HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/Case/Close
Accept: application/json
Content-Type: application/json

{
    "entity": {
        "id": "e3f46a39-1a14-e911-816f-bc920a5e0ac8"
    },
    "parameters": {
        "custom": {
            "FilterPreview": {
                "Reason": {
                    "type" : "CustomStringField", 
                    "value" : "Abandoned"
                }
            }
        }
    }    
}