•  Refresh
  • Tools
  •  
  • Expand All
  • Collapse All
  • Locales
  • Get File Link
  • Report Typo
  • Print
  • Export

Web Service Endpoints

Form ID: (SM207060)

You use this form to configure the endpoints of the Acumatica ERP 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.

In This Topic [Hide/Show]

Back to TopForm Toolbar

The form toolbar and More menu include the buttons and commands described below.

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 3.0 For the contract-based API endpoint that is selected on the form, opens the swagger.json file with its OpenAPI 3.0 schema. For more information about this file, see OpenAPI 3.0.

Extend Current Endpoint Dialog Box

You 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.

Back to TopSelection 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 Acumatica ERP.
Acumatica ERP 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.
Acumatica ERP provides multiple endpoint versions by default. For information about the differences between endpoint versions, see Comparison of System Endpoints.

Back to TopEndpoint Structure Pane

In this pane, the entities of the selected endpoint are represented as nodes. 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.

For a custom endpoint or an endpoint extension, you can understand for every entity or action whether it’s inherited or newly added:

  • An entity inherited from the base endpoint has a grey icon and the arrow sign to the right of the entity name.
  • An inherited entity that has been extended has a blue icon.
  • A new entity or action has a green icon.

Pane Toolbar

The 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 Acumatica ERP 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 Acumatica ERP form, and create the action in the selected node with the specified parameters.
Delete Deletes the selected node.

Create Entity Dialog Box

You 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 Acumatica ERP 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 Acumatica ERP 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 Acumatica ERP 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 Acumatica ERP 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 Acumatica ERP 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.

Create Action Dialog Box

You 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 Acumatica ERP action that should be added to the contract. You can select any available action on the Acumatica ERP 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.

Back to TopRight 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.

Endpoint Properties Tab

This 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.

Entity Properties Tab

This 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 Acumatica ERP 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 Acumatica ERP 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 Acumatica ERP 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 Acumatica ERP 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 Acumatica ERP 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 Acumatica ERP. 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.

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 Acumatica ERP 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 Acumatica ERP object that contains the field to which the entity field corresponds. If this Acumatica ERP 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 Acumatica ERP field to which the entity field corresponds. This is one of the fields of the object selected in the Mapped Object column.
Data Field The name of the data access class (DAC) field to which the entity field corresponds. You can use this name to distinguish custom DAC fields, which usually have the Usr prefix in their names, from the DAC fields available in the system by default.
Field Type The type of the entity field.
Inherited A check box that indicates (if selected) that the field has been inherited from the base endpoint. If the check box is cleared, a user has added the field to the endpoint.

Fields Tab: Table Toolbar

The 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.

Action Properties 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 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 Acumatica ERP form that corresponds to the selected action.

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 Acumatica ERP object that contains the field to which the action parameter corresponds.
Mapped Field The name of the Acumatica ERP field to which the action parameter corresponds. This is one of the fields of the object selected in the Mapped Object column.
Data Field The name of the data access class (DAC) field to which the action parameter corresponds. You can use this name to distinguish custom DAC fields, which usually have the Usr prefix in their names, from the DAC fields available in the system by default.
Parameter Type The type of the action parameter.
Inherited A check box that indicates (if selected) that the parameter has been inherited from the base endpoint. If the check box is cleared, a user has added the parameter to the endpoint.

Parameters Tab: Table Toolbar

The 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.

Populate Fields Dialog Box: Summary Area

By 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.

For some fields to be included in the entity, the corresponding Acumatica ERP feature must be enabled on the Enable/Disable Features (CS100000) form. For information on the basic functionality and add-on features of Acumatica ERP, see Preparing an Instance: Acumatica ERP Features.

Element Description
Object The name of the Acumatica ERP 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.

Populate Fields Dialog Box: Table Toolbar

The 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.

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.

Back to TopRelated Articles