Web Service Endpoints

Form ID: (SM207060)

You use this form to configure the endpoints of the MYOB Advanced 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.
WSDL	For the web service endpoint that is selected on the form, opens a browser window with the WSDL description of the endpoint, which is used for the contract-based SOAP API. In the browser window that opens, the address line contains the path that a client application should use to access the web service endpoint.
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 Contract-Based REST API of a Web Service Endpoint.
View Maintenance Service	Opens the WSDL description of the maintenance web service. The maintenance web service provides API methods for exporting the schema of an endpoint from MYOB Advanced and importing the schema to MYOB Advanced. Once the browser window opens with the WSDL description of the maintenance service, the address line contains the path that a client application should use to access the maintenance service.

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 Advanced. Note: MYOB Advanced 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 Advanced: 17.200.001: This version, introduced in MYOB Advanced 2017 R2, has Contract Version 3. 18.200.001: This version, introduced in MYOB Advanced 2018 R2, has Contract Version 3. For the differences between the Default/18.200.001 and Default/17.200.001 endpoints, see Comparison of System Endpoints. 20.200.001: This version, introduced in MYOB Advanced 2020 R2, has Contract Version 4. For the differences between the Default/20.200.001 and Default/18.200.001 endpoints, see Comparison of System Endpoints. For details on the differences between the contract versions, see Comparison of Contract Versions.

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 Advanced 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 Advanced 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: This is the only available option if you insert an entity into an endpoint node. An entity of this type is one of the main entities of the contract. A top-level entity usually corresponds to an MYOB Advanced form. For example, the Warehouse entity of the contract of the default endpoint is a top-level entity that corresponds to the Warehouses (IN204000) form. Linked: This entity is a supplementary entity of a contract. A linked entity usually corresponds to a part of an MYOB Advanced 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 the default endpoint contains the linked entity’s Address, 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 the default endpoint contains the detail entity SalesOrderDetail, 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.
Screen Name	The name of the MYOB Advanced form to which the entity should correspond. This element appears in the dialog box if Top-Level is selected in the Object Type box.
Screen ID	A read-only box with the ID of the MYOB Advanced form selected in the Screen Name box. This element appears in the dialog box if Top-Level 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 Advanced action that should be added to the contract. You can select any available action on the MYOB Advanced 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 Comparison of Contract Versions.
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: An entity of this type is one of the main entities of the contract. A top-level entity usually corresponds to an MYOB Advanced form. For example, the Warehouse entity of the contract of the system endpoint is a top-level entity that corresponds to the Warehouses (IN204000) form. Linked: This entity is a supplementary entity of a contract. A linked entity usually corresponds to a part of an MYOB Advanced 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 the system endpoint contains the linked entity Address, which corresponds to the Address group of fields on the Details tab of the Contacts (CR302000) form. Detail: A detail entity corresponds to the detail lines 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 the system endpoint contains the detail entity SalesOrderDetail, which corresponds to a detail line on the Details tab of the Sales Orders (SO301000) form.
Screen Name	The name of the MYOB Advanced form to which the selected entity corresponds. This box appears on the tab if a top-level entity is selected on the left pane.
Screen ID	The ID of the MYOB Advanced form to which the selected entity corresponds. This box appears on the tab if a top-level 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 Advanced. 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 Advanced 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 Advanced object that contains the field to which the entity field corresponds. If this MYOB Advanced 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 Advanced 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 Advanced 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 Advanced object that contains the field to which the action parameter corresponds.
Mapped Field	The name of the MYOB Advanced 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 Advanced feature must be enabled on the Enable/Disable Features (CS100000) form. For information on the basic functionality and add-on features of MYOB Advanced, see Preparing an Instance: MYOB Advanced Features.
Element	Description
Object	The name of the MYOB Advanced 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.