Web Service Endpoints

Form ID: (SM207060)

You use this form to configure the endpoints of the MYOB Acumatica contract-based web services; you can also use the form to view the details of existing endpoints.

You can use the predefined default endpoint to access the basic contract-based web services API. If you need to add more elements to the API, you must create a custom endpoint and add all needed elements to it.

Form Toolbar

The form toolbar includes standard buttons and form-specific buttons and commands. For the list of standard buttons, see Form Toolbar and More Menu. The form-specific commands can be shown as buttons on the form toolbar, as commands on the More menu, or in both places. These commands are listed in the following table in alphabetical order.


Command	Description
Extend Endpoint	Opens the Extend Current Endpoint dialog box, where you can specify the name and version of the endpoint that should be created as an extension of the current endpoint. You may need to create an extension of an endpoint if you want to use the entities that are defined in the contract of the existing endpoint but also need some additional entities, fields, and actions in the contract.
Validate Endpoint	Validates the endpoint. That is, the system makes sure that the following criteria are met for all elements (entities, fields, actions, and action parameters) of the endpoint: The names of the elements satisfy the naming rules. For details on these rules, see Naming Rules for Endpoints. The elements are mapped to objects, fields, and actions that exist in the system. Once the validation is finished, the system displays a message with the results of the validation. If the validation has failed, the error message contains the names of all fields that caused the error.
OpenAPI 2.0	For the web service endpoint that is selected on the form, opens the swagger.json file with its OpenAPI 2.0 description, which is used for the contract-based REST API. For more information about this file, see OpenAPI 2.0.

Table 1. Extend Current Endpoint Dialog BoxYou use this dialog box to create an extension of the endpoint that is currently selected on the form. This dialog box appears if you click Extend Endpoint on the toolbar of the form.
Element	Description
Base Endpoint Name	The name of the currently selected endpoint whose contract should be extended.
Base Endpoint Version	The version of the currently selected endpoint whose contract should be extended.
Endpoint Name	The name of the endpoint that should be created as an extension of the current endpoint.
Endpoint Version	The version of the endpoint that should be created as an extension of the current endpoint.
The dialog box has the following buttons.
OK	Creates an endpoint with the specified name and version that contains the API of the current endpoint.
Cancel	Closes the dialog box without creating any endpoint.

Selection Area

By using the elements of this area, you can select the web service endpoint. To select an endpoint, you must specify both the name and the version of the endpoint.


Element	Description
Endpoint Name	The name of the endpoint. By default, system endpoints (which have the name Default) are predefined in MYOB Acumatica. Note: MYOB Acumatica can include endpoints preconfigured in the system that have names other than Default. The system uses these endpoints internally. We recommend that you not use these endpoints.
Endpoint Version	The version of the endpoint. By default, the following versions of system endpoints are predefined in MYOB Acumatica: 20.200.001: This version, introduced in MYOB Acumatica 2020 R2, has Contract Version 4. 22.200.001: This version, introduced in MYOB Acumatica 2022 R2, has Contract Version 4. For information about the differences between the Default/22.200.001 and Default/20.200.001 endpoints, see Comparison of System Endpoints. 23.200.001: This version, introduced in MYOB Acumatica 2023 R2, has Contract Version 4. For information about the differences between the Default/23.200.001 and Default/22.200.001 endpoints, see Comparison of System Endpoints. For details about Contract Version 4, see Contract Version.

Left Pane

In this pane, the entities of the existing endpoint are represented as nodes. If the selected endpoint was created as an extension of another endpoint, the entities inherited from the base endpoint have the arrow sign to the right of the entity name.

You can click the node icon to the left of any entity to expand the node and view the hierarchical structure of the entity. Each entity can include actions and other entities.

If you click the endpoint, the right pane displays the properties of the endpoint. If you click an entity, the right pane displays the properties of the entity and the fields that are included in the entity. If you click an action, the right pane shows the properties and parameters of the action.

Table 2. Pane ToolbarThe toolbar on the pane includes only custom button, which is described in the following table.
Button	Description
Insert	Brings up a dialog box that you can use to add an entity or action to the contract of the endpoint. If an endpoint node or entity node is selected on the left pane of the form, when you click this button, the Create Entity dialog box opens. By using this dialog box, you can specify the name of the new entity, connect it to the MYOB Acumatica form, and create the entity in the selected node with the specified parameters. If an Actions node is selected on the left pane of the form, when you click this button, the Create Action dialog box opens. In this dialog box, you can specify the name of the new action, map it to an action of an MYOB Acumatica form, and create the action in the selected node with the specified parameters.
Delete	Deletes the selected node.

Table 3. Create Entity Dialog BoxYou use this dialog box to add an entity to the contract of the endpoint. This dialog box appears if you click Insert on the toolbar of the left pane of the form and an endpoint node or entity node is selected on this pane.
Element	Description
Field Name	The name of the field of the entity in which the created entity is being inserted. This field should be used to access the entity you are adding. For the rules on the naming of fields, see Naming Rules for Endpoints. This element appears in the dialog box if you insert an entity in another entity.
Use Existing Entity	A check box that indicates (if selected) that an entity that exists in the contract should be inserted. This element appears in the dialog box if you insert an entity in another entity.
Entity Type	The type of the entity that should be inserted into the contract. You can select any entity type that exists in the contract. This element appears in the dialog box if the Use Existing Entity check box is selected.
Object Name	The name of the created entity. This is the name of the API object that will be used to access the entity. For the rules on the naming of entities, see Naming Rules for Endpoints. This element appears in the dialog box if the Use Existing Entity check box is cleared.
Object Type	The type of the created entity. The following options are available: Top-Level: A top-level entity usually corresponds to an MYOB Acumatica form. For example, the Warehouse entity of the contract of a default endpoint is a top-level entity that corresponds to the Warehouses (IN204000) form. Entities of this type can be inserted into an endpoint node. Linked: A linked entity usually corresponds to a part of an MYOB Acumatica form and is related to one top-level entity of the contract or to multiple top-level entities. For example, the top-level entity Contact of the contract of a default endpoint contains the Address linked entity, which corresponds to the Address group of fields on the Details tab of the Contacts (CR302000) form. This option is not available if you insert an entity into an endpoint node. Detail: A detail entity corresponds to a detail line of a master-detail form. A detail entity exists only as a part of a top-level entity. For example, the top-level entity SalesOrder of the contract of a default endpoint contains the SalesOrderDetail detail entity, which corresponds to a detail line on the Details tab of the Sales Orders (SO301000) form. This option is not available if you insert an entity into an endpoint node. Report: An entity of this type corresponds to an MYOB Acumatica report. For example, in a custom endpoint, you can create the CashAccountSummary report entity, which corresponds to the Cash Account Summary (CA633000) report. Entities of this type can be inserted into an endpoint node.
Screen Name	The name of the MYOB Acumatica form to which the entity should correspond. This element appears in the dialog box if Top-Level or Report is selected in the Object Type box.
Screen ID	A read-only box with the ID of the MYOB Acumatica form selected in the Screen Name box. This element appears in the dialog box if Top-Level or Report is selected in the Object Type box.
The dialog box has the following buttons.
OK	Inserts the entity with the specified parameters into the contract of the endpoint, and closes the dialog box.
Cancel	Closes the dialog box without inserting any entity into the contract of the endpoint.

Table 4. Create Action Dialog BoxYou use this dialog box to insert an action into the contract of the endpoint. This dialog box appears if you click Insert on the toolbar of the left pane of the form and an *Actions* node is selected on this pane.
Element	Description
Mapped Action	The MYOB Acumatica action that should be added to the contract. You can select any available action on the MYOB Acumatica form that corresponds to the entity to which the action is added.
Action Name	The name of the created action. This is the name of the API object that will be used to invoke the created action. For the rules on the naming of actions, see Naming Rules for Endpoints.
The dialog box has the following buttons.
OK	Inserts the action with the specified parameters into the contract of the endpoint, and closes the dialog box.
Cancel	Closes the dialog box without inserting any action into the contract of the endpoint.

Right Pane

This pane displays detailed information on the selected endpoint, entity, or action. If the endpoint is selected in the left pane of the form, the right pane contains the Endpoint Properties tab. If an entity is selected in the left pane of the form, the right pane contains the Entity Properties and Fields tabs. If an action is selected in the left pane of the form, the right pane contains the Action Properties and Parameters tabs.

Table 5. Endpoint Properties TabThis tab appears in the right pane of the form if an endpoint is selected in the left pane. On this tab, you can view the properties of the endpoint.
Element	Description
Endpoint Name	The name of the selected endpoint.
Endpoint Version	The version of the selected endpoint. For the differences between the system endpoints, see Comparison of System Endpoints.
System Contract	The version of the contract of the selected endpoint. For the difference between the contract versions, see Contract Version.
Base Endpoint Name	The name of the endpoint that was used as the base endpoint for the selected endpoint when the endpoint was created.
Base Endpoint Version	The version of the endpoint that was used as the base endpoint for the selected endpoint when the endpoint was created.

Table 6. Entity Properties TabThis tab appears on the right pane of the form if an entity is selected on the left pane. On this tab, you can view the properties of the entity.
Element	Description
Object Name	The name of the selected entity. This is the name of the API object that should be used to access the entity. For the rules on the naming of entities, see Naming Rules for Endpoints.
Object Type	The type of the created entity. It can be one of the following: Top-Level: A top-level entity usually corresponds to an MYOB Acumatica form. For example, the Warehouse entity of the contract of a default endpoint is a top-level entity that corresponds to the Warehouses (IN204000) form. Linked: A linked entity usually corresponds to a part of an MYOB Acumatica form and is related to one top-level entity of the contract or multiple top-level entities. For example, the top-level entity Contact of the contract of a default endpoint contains the Address linked entity, which corresponds to the Address group of fields on the Details tab of the Contacts (CR302000) form. Detail: A detail entity corresponds to a detail line of a master-detail form. A detail entity exists only as a part of a top-level entity. For example, the top-level entity SalesOrder of the contract of a default endpoint contains the SalesOrderDetail detail entity, which corresponds to a detail line on the Details tab of the Sales Orders (SO301000) form. Report: An entity of this type corresponds to an MYOB Acumatica report. For example, in a custom endpoint, you can create the CashAccountSummary report entity, which corresponds to the Cash Account Summary (CA633000) report.
Screen Name	The name of the MYOB Acumatica form to which the selected entity corresponds. This box appears on the tab if a top-level or report entity is selected on the left pane.
Screen ID	The ID of the MYOB Acumatica form to which the selected entity corresponds. This box appears on the tab if a top-level or report entity is selected on the left pane.
Default Action	The default action that should be performed when the entity with data is passed to MYOB Acumatica. This action is performed when the PUT method of a web services client object is called. If no value is specified in this element, the Save action is the default action. This box appears on the tab if a top-level entity is selected on the left pane.

Table 7. Fields Tab
This tab appears on the right pane of the form if an entity is selected on the left pane. In the table on this tab, you can view the list of fields that are available in the entity, find out which elements of an MYOB Acumatica form the fields correspond to, and modify the list of fields if it is a custom endpoint.

The table on the tab has the following columns.
Column	Description
Field Name	The name of the entity field. This is the name that is used to access this field through the API. For the rules on the naming of fields, see Naming Rules for Endpoints.
Mapped Object	The name of the MYOB Acumatica object that contains the field to which the entity field corresponds. If this MYOB Acumatica object is a view that is not optimized for obtaining a list of entities by a single GET request, a proper warning is attached to this table cell. For more information about the optimization of the retrieval of multiple records, see the Usage Notes section of Retrieve Records by Conditions.
Mapped Field	The name of the MYOB Acumatica field to which the entity field corresponds. This is one of the fields of the object selected in the Mapped Object column.
Field Type	The type of the entity field.

Table 8. Fields Tab: Table ToolbarThe table toolbar includes standard buttons and buttons specific to this table. For the list of standard buttons, see Table Toolbar. The table-specific buttons are listed in the following table.
Button	Description
Populate	Opens the Populate Fields dialog box, where you can select the fields that should be available through the entity.
Extend Entity	Makes the Add Row, Delete Row, and Populate buttons available on the toolbar of the tab. You should click Extend Entity when creating a custom endpoint if you need to extend an entity inherited from the base endpoint. This button is available on the toolbar of the tab if an entity inherited from the base endpoint is selected in the left pane.
Validate Entity	Validates the entity. That is, the system makes sure that the following criteria are met for the nested entities and fields in the selected entity: The names of the entities and fields satisfy the naming rules. For details on these rules, see Naming Rules for Endpoints. The entities and fields are mapped to objects and fields that exist in the system. Once the validation is finished, the system displays a message with the results of the validation. If the validation has failed, the error message contains the names of all fields that caused the error.

Table 9. Action Properties TabThis tab appears on the right pane of the form if an action is selected on the left pane. By using this tab, you can view the properties of the action.
Element	Description
Action Name	The name of the selected action. This is the name of the API object that should be used to invoke the selected action. For the rules on the naming of actions, see Naming Rules for Endpoints.
Mapped Action	The action of the MYOB Acumatica form that corresponds to the selected action.

Table 10. Parameters Tab
This tab appears on the right pane of the form if an action is selected on the left pane. By using this tab, you can view the parameters of the action and modify the parameters if it is a custom endpoint.

The table on the tab has the following columns.
Column	Description
Parameter Name	The name of the action parameter. This is the name that is used to access this parameter through the API. For the rules on the naming of action parameters, see Naming Rules for Endpoints.
Mapped Object	The name of the MYOB Acumatica object that contains the field to which the action parameter corresponds.
Mapped Field	The name of the MYOB Acumatica field to which the action parameter corresponds. This is one of the fields of the object selected in the Mapped Object column.
Parameter Type	The type of the action parameter.

Table 11. Parameters Tab: Table ToolbarThe table toolbar includes standard buttons and buttons specific to this table. For the list of standard buttons, see Table Toolbar. The table-specific buttons are listed in the following table.
Button	Description
Populate	Opens the Populate Fields dialog box, where you can select the fields that should be used as parameters of the action.
Validate Action	Validates the action. That is, the system makes sure that the following criteria are met for the action and its parameters: The names of the action and its parameters satisfy the naming rules. For details on the rules, see Naming Rules for Endpoints. The action and its parameters are mapped to an action and fields that exist in the system. Once the validation is finished, the system displays a message with the results of the validation. If the validation has failed, the error message contains the names of all fields that caused the error.

Table 12. Populate Fields Dialog Box: Summary AreaBy using this dialog box, you can select the fields that should be used as the fields of the entity or as parameters of the action.
Note:
For some fields to be included in the entity, the corresponding MYOB Acumatica feature must be enabled on the Enable/Disable Features (CS100000) form. For information on the basic functionality and add-on features of MYOB Acumatica, see Preparing an Instance: MYOB Acumatica Features.
Element	Description
Object	The name of the MYOB Acumatica object whose fields should be used to populate the parameters of the entity or action.
Show Fields from Selectors	A check box that indicates (if selected) that the fields that correspond to the columns of the Select dialog box (which appears if you click the Magnifier icon of a box) should appear in the table of the Populate Fields dialog box.

Table 13. Populate Fields Dialog Box: Table ToolbarThe table toolbar includes standard buttons and buttons specific to this table. For the list of standard buttons, see Table Toolbar. The table-specific buttons are listed in the following table.
Button	Description
Select All	Selects all fields in the table of the Populate Fields dialog box.
Clear	Clears the selection of the fields in the Populate Fields dialog box.

Table 14. Populate Fields Dialog Box: Table Columns
Column	Description
Populate	An unlabeled check box that you select to include the field in the list of fields of the entity or in the list of parameters of the action.
Field	The name of the field of the object selected in the Object box.