Copyright...6. Overview Preparing Data for Import and Export by Using Scenarios... 10

Transcription

1

2 Contents 2 Contents Copyright...6 Overview... 7 Preparing Data for Import and Export by Using Scenarios Import and Export Scenarios Data Providers To Create a CSV Data Provider To Create an Excel Data Provider...15 To Create a Microsoft SQL Data Provider To Modify a File Data Provider To Link a File Data Provider to an Existing File Configuring Import Scenarios Import Scenario Creation Import Scenario Parameters Target Objects and Fields in Import Scenarios Source Fields in Import Scenarios Source Restrictions in Import Scenarios Target Restrictions in Import Scenarios...28 Configuring Export Scenarios Export Scenario Creation...29 Export Scenario Parameters...30 Source Restrictions in Export Scenarios Configuring Scenario Mapping...32 General Recommendations and Limitations of Data Import Types of Target Fields in Import Scenarios Fields with Commit in Import and Export Scenarios Service Commands in Import and Export Scenarios...37 Pop-Up Dialog Boxes in Import Scenarios Actions in Import Scenarios Key Fields and Search in Import Scenarios Export of All Records: Use of Every Data Modification During Export: Use of Commit and Actions...41 Multi-Language Fields in Import and Export Scenarios Formulas in the Mapping...43 Operators Functions...48 Importing and Exporting Records by Using Scenarios...55 Data Import... 55

3 Contents 3 Simplified Scenarios for Data Import Data Export Authorizing Client Applications to Work with Acumatica ERP Authorization Code Flow...61 Implicit Flow Resource Owner Password Credentials Flow...71 Comparison of the Flows...75 To Register a Client Application...75 To Revoke the Access of a Connected Application...77 Configuring the Contract-Based SOAP and REST API Contract-Based Web Services API Endpoints and Contracts API Entities, Fields, and Actions...81 Custom Fields Custom Endpoints and Endpoint Extensions...84 Naming Rules for Endpoints Comparison of Contract Versions...86 To Create a Custom Endpoint To Extend an Existing Endpoint...88 To Validate an Endpoint Working with the Contract-Based SOAP API Multi-Language Fields To Configure the Client Application...92 Working with the Contract-Based REST API...96 Representation of a Record in JSON Format Login to the Service Logout from the Service Creation of a Record Update of a Record Retrieval of a Record by Key Fields Retrieval of a Record by ID Retrieval of Records by Conditions Retrieval of Data from an Inquiry Form Parameters for Retrieving Records Removal of a Record Execution of an Action Attachment of a File to a Record Retrieval of a File Attached to a Record Retrieval of the Schema of Custom Fields Multi-Language Fields Working with the Screen-Based SOAP API Screen-Based Web Services API

4 Contents 4 API Objects Related to Acumatica ERP Forms Screen-Based API Wrapper To Generate the WSDL File of the Web Services To Import the WSDL File Into the Development Environment To Use the Screen-Based API Wrapper Working with Commands of the Screen-Based SOAP API Commands for Retrieving the Values of Elements Selection of a Group of Records for Export Commands for Setting the Values of Elements Commands for Clicking Buttons on a Form Commands for Adding Detail Lines Commands for Pop-Up Dialog Boxes and Pop-Up Forms Commands for Pop-Up Panels Commands for Record Searching: Filter Service Command Commands for Record Searching: Key Command Commands for Record Searching: Custom Field Commands That Require a Commit Commands for Working with Attachments Commands for Working with Multi-Language Fields Configuring Push Notifications Push Notifications Recommendations for the Data Queries Push Notification Destinations Push Notification Format To Configure Push Notifications To Process Failed Notifications Integration Form Reference Connected Applications Data Providers Export by Scenario Export Scenarios Export Scenarios Formula Editor Dialog Box Import by Scenario Import Scenarios Import Scenarios Process Push Notifications Push Notifications Salesforce Data Resync Salesforce Sync Salesforce Sync Salesforce Sync State Web Service Endpoints...199

5 Contents 5 Web Services Contract-Based SOAP API Reference Login() Method Logout() Method SetBusinessDate() Method Get() Method GetList() Method (Contract Version 3) GetList() Method (Contract Version 2) GetList() Method (Contract Version 1) Put() Method Delete() Method Invoke() Method GetProcessStatus() Method GetFiles() Method PutFiles() Method GetCustomFieldSchema() Method Attributes Property CustomFields Property (Contract Version 2) CustomFields Property (Contract Version 1) ReturnBehavior Property (Contract Version 3) ReturnBehavior Property (Contract Version 2) Contract-Based REST API Reference Screen-Based SOAP API Reference Login() Method Logout() Method SetLocaleName() Method SetBusinessDate() Method GetScenario() Method GetSchema() Method SetSchema() Method Export() Method Submit() Method Import() Method Clear() Method GetProcessStatus() Method Appendix Reports Report Form Report Form Toolbar Table Toolbar Glossary

6 Copyright 6 Copyright 2018 Acumatica, Inc. ALL RIGHTS RESERVED. No part of this document may be reproduced, copied, or transmitted without the express prior consent of Acumatica, Inc SE 6th, Suite 140 Bellevue, WA Restricted Rights The product is provided with restricted rights. Use, duplication, or disclosure by the United States Government is subject to restrictions as set forth in the applicable License and Services Agreement and in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS or subparagraphs (c)(1) and (c)(2) of the Commercial Computer Software-Restricted Rights at 48 CFR , as applicable. Disclaimer Acumatica, Inc. makes no representations or warranties with respect to the contents or use of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Acumatica, Inc. reserves the right to revise this document and make changes in its content at any time, without obligation to notify any person or entity of such revisions or changes. Trademarks Acumatica is a registered trademark of Acumatica, Inc. HubSpot is a registered trademark of HubSpot, Inc. Microsoft Exchange and Microsoft Exchange Server are registered trademarks of Microsoft Corporation. All other product names and services herein are trademarks or service marks of their respective companies. Software Version: 2017 R2 Last updated: June 29, 2018

7 Overview 7 Overview The implementation of an ERP system is a complex process that could last many months or even a year or two. During initial implementation, your organization may need to perform data migration from legacy applications to Acumatica ERP to eliminate manual data entry. Moreover, for various reasons, some companies may continue to use legacy applications and software from different vendors during implementation or even after it. Because of the distributed design of ERP software, your company can assemble applications from different vendors to create functionality that completely matches its business needs. For some areas, your company may need specialized, country-specific software such as tax reporting and payroll software that requires annual updates so that the company can comply with the yearly governmental regulations of the country. In such cases, data synchronization is an ongoing task, performed periodically to keep data consistent between the source and the target over time. This topic describes the primary features and options of the Integration module, which are described in their own topics as well. Best Practices for Importing Data Before you import data into your live system, take the following necessary precautions: 1. Create a snapshot of your system with all the data available. This snapshot will help you restore the data if anything goes wrong with the import. 2. Validate the scenario. Before you start importing real data, which sometimes has hundreds or thousands of records, prepare a test file that contains no more than 10 records and import from that file first. 3. Perform the operation when the users are inactive or less active for example, overnight. If the import was performed successfully but you imported the wrong data, you can modify the same scenario that was used for import to remove the imported data from the system. Data Providers If you need to transfer data between an external application and Acumatica ERP, you have to convert the data in an external format to or from the data in the format of Acumatica ERP. The tool you use to perform such conversions in Acumatica ERP is a data provider. A configured data provider, which has information about the source of external data and the structure of the data, performs data transfers between the external application or external file and Acumatica ERP. You create data providers on the Data Providers (SM206015) form. To create a provider, you specify its name and type, the access parameters to the source, and the data schema. You can find more information on data providers in Data Providers. Import Scenarios To import data from an external system or file to Acumatica ERP, you need to map the external data fields to the fields of an Acumatica ERP form. To define such mapping in Acumatica ERP, you use import scenarios. An import scenario specifies the sequence of actions to be performed by Acumatica ERP to import data from an external source. You can create an import scenario in one of the following ways: Standard way: First you create a data provider, and then you add a new import scenario and map the data. For details, see Configuring Import Scenarios.

8 Overview 8 Simplified way: You upload the file, map form elements to external data, and then import the data. The data provider and the standard import scenario are added automatically. For more information, see Simplified Scenarios for Data Import. Export Scenarios Export scenarios are used primarily to export data from Acumatica ERP to an external data source, such as a file or SQL table. You can also use export scenarios to update records in the system. For example, you can use export scenarios to mark records in the system once they have been exported to exclude them from future exports. As another example, suppose you want to update existing records or massexecute some action on them. If you have the list of particular record IDs that you want to update, it is easier to compose an import scenario and update the records by processing the list of IDs. If you have no list of IDs, you can compose an export scenario to select and update the needed records by the specified condition. For more information on export scenarios, see Configuring Export Scenarios. Easy Data Conversion Each of the built-in data providers, which are reusable and require no additional custom code, recognizes the data structure of the file or application and efficiently converts data from the particular external format into the internal format of Acumatica ERP; it also efficiently converts internal data into the particular external format. Nevertheless, you may need to convert the data during import or export to formats specific to the particular system or perform other necessary data transformation. To do this, you can create formulas with the help of the easy-to-use formula editor. For details, see the following topics: Formulas in the Mapping Functions Operators Export and Import Scheduling To automatically initiate the import or export of data or import or export sessions for synchronization, you can create a schedule to execute particular scenarios. To schedule scenarios, use the forms listed in the Schedule section on the Navigation pane. For details on scheduling, see Scheduled Processing. Acumatica ERP Web Services You can create a client application that can access Acumatica ERP through web services to import, update, or delete records in Acumatica ERP and export records from Acumatica ERP. To access these web services, you can use the screen-based SOAP application programming interface (API), the contract-based SOAP API, or contract-based REST API. For all new projects, we recommend that you use either the contract-based SOAP API, or the contract-based representational state transfer (REST) API. For details on the contract-based SOAP and REST API, see Configuring the Contract-Based SOAP and REST API, Working with the Contract-Based SOAP API, and Working with the Contract-Based REST API. For details on the screen-based web services API, see Working with the Screen-Based SOAP API. OAuth 2.0 Authorization Acumatica ERP supports the OAuth 2.0 mechanism of authorization for applications that are integrated with Acumatica ERP through application programming interfaces (APIs). When a client application of Acumatica ERP uses the OAuth 2.0 mechanism of authorization, the client application does not operate with the Acumatica ERP credentials to log in a user to Acumatica ERP; instead, the application obtains an access token from Acumatica ERP and uses this token when it requests data from Acumatica ERP. Depending on the OAuth 2.0 flow that the client application implements, the client application either has no information on the credentials of an Acumatica ERP user or uses this information only once

9 Overview 9 to obtain the access token. The OAuth 2.0 mechanism of authorization improves the security of the Acumatica ERP data accessed by the application and simplifies the management of access rights. For details on the OAuth 2.0 authorization flow, see Authorizing Client Applications to Work with Acumatica ERP. Push Notifications Acumatica ERP provides push notifications that make it possible for the external applications to track the changes in the data in Acumatica ERP. That is, you can configure Acumatica ERP to send notifications to a destination (such as an HTTP address) when specific data changes in Acumatica ERP. The external application can receive these notifications and process the information on the data changes, if necessary. With push notifications, the external application doesn't need to continually poll for the data to find out whether there are any changes in this data, which helps improve the performance of the external application. For more information on push notifications, see Configuring Push Notifications. Daylight Saving Settings Each Acumatica ERP instance uses the Daylight Saving Time (DST) settings of a server (which are settings of an operating system, such as Windows) on which the instance is installed. If Acumatica ERP is integrated with any third-party service, DST settings of the Acumatica ERP and service servers may differ, which may result in synchronization errors. To adjust the discrepancy, on the Daylight Saving Settings (CS209020) form, you can select the Custom check box for all timezones to make the DST settings of the Acumatica ERP instance completely independent from the server settings.

10 Preparing Data for Import and Export by Using Scenarios 10 Preparing Data for Import and Export by Using Scenarios Before you import data to or export data from Acumatica ERP, you must define to the Acumatica ERP system the format of the data in the external system or file. For this purpose, you use data providers in the system. In this chapter, you will find detailed information on data providers and will learn how to create data providers for the external data. In This Chapter Import and Export Scenarios To Create a CSV Data Provider Data Providers To Create an Excel Data Provider To Create a Microsoft SQL Data Provider To Modify a File Data Provider To Link a File Data Provider to an Existing File Import and Export Scenarios To upload data to and from Acumatica ERP, you can use import scenarios and export scenarios, which define the data import and data export instructions, respectively, for the system. An import or export scenario is a sequence of actions to be executed for a data record as if the record is being manipulated by user through an Acumatica ERP form. When you enter data into the system manually, you perform a sequence of actions. You open the needed data entry form and start entering data. To add a new record, you use the UI elements one by one that is, you type text, select values from combo boxes, clear or select check boxes, and click buttons. In the corresponding scenario, you compose exactly the same sequence of actions you specify a command for each user action on the form. Just as you cannot perform multiple actions simultaneously on the form, the scenario executes commands successively. To construct the scenario, you reflect the actions you make on the form in the sequence of commands for the scenario. Because in these scenarios you either save data to an external system or file, or upload data from an external system or file to Acumatica ERP, you must define in Acumatica ERP the format of the external system or file. For this purpose, you set up a data provider in the system. A data provider is an entity that defines the structure of the external data source; Acumatica ERP then uses the data provider to transfer data from and to the external system or file. Therefore, to use an integration scenario, you have to define the data provider and the needed import or export scenario, as illustrated in the diagram below. An integration scenario works as if the data being manually processed on an Acumatica ERP form.

11 Preparing Data for Import and Export by Using Scenarios 11 Figure: Manual input and integration scenarios input When you're creating an integration scenario, you first create the needed data provider, which defines the type and schema of the data source. For example, the type can be an Excel file, and the schema of an Excel data source consists of the names of spreadsheets that should be used for data import or export and the list of columns on the spreadsheets. If the external data source has changed (for example, if a new column has been added to an Excel spreadsheet), you have to update the data provider in Acumatica ERP to be able to use the new column in scenarios for which the data provider is specified. After you have prepared the data provider, the second step is to define the scenario, including the scenario mapping. You can construct a scenario for any data entry form. In the scenario, you use internal fields, which are the fields of Acumatica ERP, and external fields, which are defined in the specified data provider. In the scenario, you map internal fields to external fields and specify commands. An integration scenario is specific to the Acumatica ERP form and the external data schema. After the scenario is ready, you can run the import or export for the scenario to get the result. You can also schedule scenarios to be run, so that you can import and export data on a regular basis. You can find examples of integration scenarios in the I100 Integration Scenarios training course.

12 Preparing Data for Import and Export by Using Scenarios 12 Data Providers You create data providers on the Data Providers (SM206015) form. To create a provider, you specify its name and type, the access parameters to the source, and the data schema. Data Provider Types Excel spreadsheets or files in CSV format are generally used for data exchange between different ERP products, because most ERP products support exporting and importing data in these formats. Besides using files in an external format as a data source, you can import data from or export data to an external application directly. For example, you can connect to a Microsoft SQL Server and download data from it or upload data to it. Acumatica ERP provides a number of built-in types of data providers through which the application can efficiently import data from external files or third-party software to Acumatica ERP, or export data from Acumatica ERP to external destinations. These types of data providers, which you use when you configure a provider on the Data Providers form, are listed below: File providers that you use to access data in external files: CSV Provider (PX.DataSync.CSVSYProvider): For import from and export to files in CSV format Excel Provider (PX.DataSync.ExcelSYProvider): For import from and export to Excel spreadsheets XML Provider (PX.DataSync.XMLSYProvider): For import from and export to files in XML format Providers that are preconfigured for importing data from and exporting data to external systems: Salesforce Provider (PX.DataSync.SFSYProvider): For import from and export to SalesForce CRM by using the Simple Object Access Protocol (SOAP). Salesforce Sync Provider (PX.Salesforce.SalesforceProvider): For real-time synchronization of data between Acumatica ERP and Salesforce. For details, see Synchronization with Salesforce. MS SQL Provider (PX.DataSync.MSSqlSYProvider): For import from and export to Microsoft SQL Server. HubSpot Provider (PX.DataSync.HubSpot.HSSYProvider): For exporting leads to HubSpot for nurturing and importing leads to Acumatica ERP for processing. You can find more information in Integration with HubSpot. Providers for exporting payment data to external payment systems: ACH Provider (PX.DataSync.ACHProvider): For exporting data for processing in the Automated Clearing House (ACH) system. You can find more information in ACH Payment Support. Giro Payment Provider (PX.DataSync.Banks.GIROPaymentProvider): For exporting data for processing in giro-based payment systems. : The Tax Provider, Tax Provider CSV, and Tax Zip Provider built-in types are obsolete. They were used to import data from the Avalara data files, but Avalara no longer supplies these files. Integration with Avalara is done through the Avalara AvaTax SOAP API. To import data from other sources, you need to create a custom data provider by using the API provided by Acumatica ERP.

13 Preparing Data for Import and Export by Using Scenarios 13 Provider Parameters To define a particular data source to be used for import or export, you define the parameters of the data provider on the Data Providers (SM206015) form. The set of parameters depends on the data provider type, as described below: Parameters of file providers: File providers generally have a simple set of parameters that specify the file properties necessary for accessing data in the file. Each of the file providers has the FileName parameter, which specifies the path to the file that should be used for data import or export. The path to the file is set automatically after you have uploaded an external file to the provider. The FileName parameter displays the path to the uploaded file in the internal format: Data Providers (<Data Provider Name>)\<File Name>, where <Data Provider Name> and <File Name> are replaced with the corresponding values. Other parameters of a file provider depend on the provider type. You should specify these parameters so the system can correctly open the file and process the contents of the file. Parameters of providers that connect to external data systems: For providers that connect to external data systems, such as SalesForce or MS SQL provider, you specify a set of parameters for connecting Acumatica ERP to the external system. Each of these providers has a parameter that you use to specify the location of the remote resource. This parameter is either the URL of a remote service or the path to a local server. Other parameters are specific to each provider type. These parameters are necessary for authentication on the remote resource. External Data Schema Data that you are going to transfer between an external data source and Acumatica ERP usually has a table structure. That is, the data includes a number of data records, and each record has a list of parameters specified. You specify the structure of an external data source for a data provider by defining the external data schema that is, you specify the objects and fields of the data source. The object is usually the whole data source or a part of the data source that corresponds to a complete data table. For example, for an Excel file, objects correspond to spreadsheets. For the source objects that should be used for import or export, you should select the Active check box in the Source Objects table on the Schema tab of the Data Providers (SM206015) form. Source fields are defined by the list of attributes that are specified for each record. For an Excel file, source fields correspond to columns on a spreadsheet. For each field you want to use the field in a scenario, you should select the Active check box in the Source Fields table on the Schema tab of the Data Providers form. Data Provider Creation You create data providers on the Data Providers form. The process of creating a data provider consists of the following general steps: 1. Reviewing the structure of external data Before you create the data provider, you review the external source to identify the needed provider type and the external data schema. If you are going to import data to Acumatica ERP, you review the source data to determine the needed provider type, to check that the data meets the requirements, and to see the external data schema. If you are going to export data from Acumatica ERP, you review the data schema in the target file or application to which you want to export the Acumatica ERP data, or create a file to hold the data to be exported and provide field names matching the intended use of the data. 2. Creating a provider and setting its type On the Data Providers form, you create the data provider. You specify the name of the provider, which usually describes the data you will transfer by using this provider. You also select the

14 Preparing Data for Import and Export by Using Scenarios 14 needed type of the provider. You can use built-in provider types or develop a custom data provider type. 3. Specifying the provider parameters On the Parameters tab of the Data Providers form, you specify the particular data source. You attach a file or specify the location of the remote source. You also specify the source-dependent parameters, if necessary. 4. Filling in the source objects and fields of the provider On the Schema tab of the Data Providers form, you fill in objects and fields from the attached file or remote resource to the data provider. After that, the data provider is ready and can be edited as needed. For a file provider, you can upload the new version of an attached file and then update source objects and fields. For a provider connected to a remote system, you can reload the data schema from the server if you make any changes. To Create a CSV Data Provider You use the Data Providers (SM206015) form to create a data provider that defines the structure of external data for Acumatica ERP during data import or data export. This procedure describes how to create a data provider that works with the records in a CSV file. To Create a CSV Data Provider 1. Review the file for which you need to create the data provider to identify the needed provider parameters (the delimiter that is used in the file and file encoding) and external data schema. 2. On the System tab, click Integration. In the navigation pane, navigate to Manage > Data Providers. 3. Create a provider and specify the following settings: Name: The name of the provider, which usually describes the data you will transfer by using this provider, such as Import/Export Customers Data Type: CSV Provider (PX.DataSync.CSVSYProvider) 4. On the form toolbar, click Save. The system requires you to save the provider before you upload the file. 5. Drag and drop the file to the form, and refresh the form in your browser. The file is uploaded to the form. : As an alternative to this step, to upload the source file to the form, on the title bar, click Files. In the Files dialog box that opens, click Browse to locate the source file. Select the file, and click Open. In the dialog box, click Upload to upload the file to the website; then close the dialog box On the Parameters tab, do the following to set the parameters of the data provider: Check that the value of the FileName parameter is correct; it was filled in automatically when you uploaded the file. As the value of the Encoding parameter, specify the encoding of the source file by selecting the proper encoding value from the drop-down list in the Value column of the table. As the value of the Delimiter parameter, specify the delimiter that is used in the CSV file. Open the Schema tab. In the Source Objects pane, select the Active check box for the only available object of the CSV provider to make the object available in integration scenarios.

15 Preparing Data for Import and Export by Using Scenarios 15 : If you don't see an object on the Source Objects pane, click Fill Schema Objects on the toolbar of the Source Objects pane. 8. On the toolbar of the Source Fields pane, click Fill Schema Fields. The system displays the field names available in the file in this pane. Make sure the Active check box is selected for all the fields of the file for which data will be imported or exported. 9. Click Save. You have created a CSV data provider that you can use in an import or export scenario. To Create an Excel Data Provider You use the Data Providers (SM206015) form to create a data provider that defines the structure of external data for Acumatica ERP during data import or data export. This procedure describes how to create a data provider that works with the records in an Excel file. To Create an Excel Data Provider 1. Review the data file for which you need to create the data provider to identify the external data schema. Open the file and review the available columns. Make sure that you understand how the names of the columns match the contents. 2. On the System tab, click Integration. In the navigation pane, navigate to Manage > Data Providers. 3. Create a provider with the following settings: Name: The name of the provider, which usually describes the data you will transfer by using this provider, such as Import/Export AR Invoices Data Type: Excel Provider (PX.DataSync.ExcelSYProvider) The list of provider parameters becomes available on the Parameters tab, which contains one parameter: FileName. 4. On the form toolbar, click Save. The system requires that you save the provider before you upload a file. 5. Drag and drop the file to the form, and refresh the form in your browser. The file is uploaded to the form. : As an alternative to this step, to upload the source file to the form, on the title bar, click Files. In the Files dialog box that opens, click Browse to locate the source file. Select the file, and click Open. In the dialog box, click Upload to upload the file to the website; then close the dialog box. The FileName parameter is set to the name of the file that you have uploaded. 6. On the toolbar of the Source Objects pane of the Schema tab, select the Active check box for the needed object (which corresponds to a spreadsheet) to make the object available in integration scenarios. 7. On the toolbar of the Source Fields pane, click Fill Schema Fields. The system displays the fields available in the source file in this pane. Make sure the Active check box is selected for all the columns of the file for which data will be imported or exported. 8. Repeat the previous two steps for all the objects (spreadsheets) and fields (columns) that you want to use for data import and export. 9. Click Save to save the data provider. You have created an Excel data provider that you can use in an import or export scenario.

16 Preparing Data for Import and Export by Using Scenarios 16 To Create a Microsoft SQL Data Provider You use the Data Providers (SM206015) form to create a data provider that defines the structure of external data for Acumatica ERP during data import or data export. This procedure describes how to create a Microsoft SQL data provider that is used to transfer data between Acumatica ERP and a table of a Microsoft SQL Server database. To Create a Microsoft SQL Data Provider 1. Review the columns of the database table for which you need to create the data provider to identify the external data schema. 2. On the System tab, click Integration. In the navigation pane, navigate to Manage > Data Providers. 3. Create a provider, and specify the following settings for it: 4. a. Name: The name of the provider, which usually describes the data you will transfer by using this provider, such as Import Purchase Orders b. Data Type: MS SQL Provider (PX.DataSync.MSSqlSYProvider) On the Parameters tab, do the following: a. 5. As the value of the Server parameter, specify one of the following: The name of the computer where the Microsoft SQL Server instance is installed if you use the default instance of Microsoft SQL Server (for example, MyServer) The name of the computer and the name of the Microsoft SQL Server instance if you use a named instance (for example, MyServer\MyInstance) b. Specify the database name as the value of the Database parameter. c. Specify the login and password for accessing the SQL Server instance and the type of authentication that is used by the SQL Server instance (either SQL or Windows). On the toolbar in the Source Objects pane of the Schema tab, click Fill Schema Objects. The system connects to the database, pulls the list of tables and views from it, and populates the Source Objects tab with the schema objects that correspond to tables and views. : If you don't see Fill Schema Objects on the toolbar, click not fit on the toolbar., which displays any buttons that do 6. Select the Active check box for the needed object. On the toolbar of the Source Fields pane, click Fill Schema Fields. The system displays the column headers available in the source database table. Make sure the Active check box is selected for all needed fields. 7. Repeat the previous step for all objects (SQL tables and views) that you want to import data to and export data from. 8. Click Save. You have created a Microsoft SQL data provider that you can use in an import or export scenario. To Modify a File Data Provider You can use the Data Providers (SM206015) form to modify existing data providers.

17 Preparing Data for Import and Export by Using Scenarios 17 If the data source has changed for example, if you have added a column to the Excel file you have to update the data provider. To update the data provider, you have to replace the file attached to the provider on the Data Providers (SM206015) form and update the provider schema. To Modify a File Data Provider 1. On the System tab, click Integration. In the navigation pane, navigate to Manage > Data Providers. 2. Select the provider that you want to modify, and on the form title bar, click Files. 3. In the Files dialog box, click Edit to the right of the file name. Clicking Edit opens the File Maintenance form (SM202510), which displays the details of the file attachment. 4. On the form toolbar, click Check Out to make the file unavailable to other users for editing while you are updating it. You may skip this step if no other users can work with this file simultaneously. 5. Click Get Latest Version on the form toolbar, and download the file. Open the file and modify it. Save the edited version to your computer. : You do not necessarily have to download the file first; you can just upload a new version and skip this step. 6. On the form toolbar of the File Maintenance form, click Upload New Version to open the File Upload dialog box, and upload the edited version of the file into the system. If you checked the file out, select the Check In check box to make the file available for editing to other users. On the Versions tab, notice the list of available file versions (see the screenshot below). If necessary, you could download or restore the needed file version. To download a file version, select the needed version and click View Selected Version on the table toolbar. Then you can upload the file as a new version. To delete a file version, click Delete Row on the table toolbar. Figure: Versions of the file attached to the provider 7. Close the File Maintenance form and the Files dialog box to resume work on the Data Providers (SM206015) form. 8. On the Schema tab, on the toolbar of the Source Fields pane, click Fill Schema Objects. The system updates the list of available objects. Make sure the Active check box is selected for all objects that you need to use for data import or data export. 9. For each active source object, select the object on the Source Fields pane and click Fill Schema Fields on the toolbar of the Source Fields pane. The system updates the list of available fields. Make sure the Active check box is selected for all fields that you need to use for data import or data export.

18 Preparing Data for Import and Export by Using Scenarios Click Save on the form toolbar. To Link a File Data Provider to an Existing File The file that should be used for creating the data provider may be already uploaded to Acumatica ERP. In this case, you perform the steps described below. You use the Search in Files (SM202520) form to get the link of the file you need to link to a file provider. You then use the Data Providers (SM206015) form to create a provider and specify the copied link on that form. To Link a File Data Provider to an Existing File 1. On the Organization tab, click Communication. In the navigation pane, navigate to Documents > Search in Files. 2. In the File Name Contains box, type the name of the file that you need to link to a file provider and press Enter. The table in the lower right pane contains the list of files matching the specified criteria. 3. For the needed file that appeared in the search results, click Get File Link, and copy the internal link to the file from the Attached File Link dialog box. 4. On the System tab, click Integration. In the navigation pane, navigate to Manage > Data Providers. 5. Create a data provider, and specify its name and type in the Name and Data Type boxes. 6. On the Parameters tab, set the FileName parameter value to the copied link, such as [updata Providers (Export Leads)\Leads.xlsx]. 7. On the Schema tab in the Source Objects pane, click Fill Schema Objects. The source objects appear on the tab. Select the Active check box for the needed object. In the Source Fields pane, click Fill Schema Fields. The fields have been retrieved from the file and appear on the tab. Make sure all fields are active. 8. Save the provider. You have created a file provider and linked it to a file that was uploaded to the system earlier. This provider can be used for importing or exporting records.

19 Configuring Import Scenarios 19 Configuring Import Scenarios You create import scenarios on the Import Scenarios (SM206025) form. To create an import scenario, you should specify its name, the Acumatica ERP form that should be used for importing data, the data provider that defines the structure of the imported data, and the data provider object; you should also configure the mapping of the scenario. In This Chapter Import Scenario Creation Import Scenario Parameters Target Objects and Fields in Import Scenarios Source Fields in Import Scenarios Source Restrictions in Import Scenarios Target Restrictions in Import Scenarios Import Scenario Creation You create import scenarios on the Import Scenarios (SM206025) form. The creation of the import scenario consists of the following general steps: 1. Analyzing the sequence of actions on the form Before you start creating an import scenario on the Import Scenarios form, you should create a data provider, as described in Data Providers, and learn how a data record is entered on the target Acumatica ERP form. When reviewing the Acumatica ERP form for which you will compose the import scenario, pay attention to the required fields on the form. All these fields must be filled in when you create a new record. Some fields on the form can get default values, which can also be used during import. For example, you can configure customer classes before you import customer records so that when these records are imported, the system gets most of settings from the customer class specified for the customer. You can provide the values of the fields that have default values during import and override these default values. Make sure all required data fields either are included in the imported data or are filled with default values. Before you start creating a scenario, we strongly recommend that you manually enter one record of the imported data (or a test record) on the target Acumatica ERP form. (If you enter a record of the imported data, during import, you can exclude this record from processing to avoid duplication of records in the system.) As you manually enter the record, make a note of the sequence of actions you perform: the order in which you specify values in the fields on the form, and the actions you perform for the entered record, such as adding a new row and saving your changes. 2. Specifying scenario parameters The parameters of an import scenario define the name of the scenario, the Acumatica ERP form to which data will be imported, and the data provider and source object, which together specify the data source. You can also set other import scenario parameters that define the mode of import and the properties of the data being imported. 3. Creating mapping of the scenario Mapping is the process of creating one-way relations between the fields of an external data source and the fields of an Acumatica ERP form. To provide mapping for a particular field on an Acumatica ERP form, you perform the following steps on the Mapping tab of the Import Scenarios (SM206025) form:

20 Configuring Import Scenarios Add a row for the field you want to map. 2. In the Target Object box, specify the Acumatica ERP object that includes the target field. An object represents a group of fields on an Acumatica ERP form, such as a summary area or a detail tab. 3. In the Field/Action Name column, select the appropriate internal field or action. An internal field is a field of the Acumatica ERP object selected in the Target Object box. 4. In the Source Field/Value column, select the matching external field, internal field, or combination of internal and external fields, functions, and constants. An external field is a field of the object from the data provider specified in the scenario. When you are mapping fields, you should first map the key fields: the fields that the system uses to distinguish records that belong to different documents. For example, on the Invoices and Memos (AR301000) form, there are two key fields: Type and Reference Nbr. You should map these fields before you map the other fields, because you fill in these fields first on the form when you manually enter an invoice. After you have mapped key fields, you should map other fields in the order in which you would fill them in on the form. You can deactivate some rows of the scenario mapping by clearing the Active check box for corresponding rows. This will exclude the corresponding instruction from the scenario mapping, and this instruction will not be executed during the import process. At the end of the mapping of the scenario that imports or updates data in the system, to save the imported record to the database, you have to insert a row with the <Action: Save> action. 4. Configuring source and target restrictions To import only some records from the data source or update only the records that satisfy some condition, you can configure source and target restrictions for an import scenario on the Import Scenarios (SM206025) form. You can find detailed descriptions and examples of the use of source and target restrictions in the following topics: Source Restrictions in Import Scenarios Target Restrictions in Import Scenarios After these steps have been performed, the scenario is ready, and you can use it for data processing. Import Scenario Parameters When you begin creating an import scenario by using the Import Scenarios (SM206025) form, you specify the following required parameters: Name: In this box, you specify a name that reflects the functionality of the import scenario. You have to use unique names between import and export scenarios. Screen Name: In this box, you select the Acumatica ERP form that should be used for data import. Provider and Provider Object: In these boxes, you select one of the previously created data providers and its object that should be used for data import. If you select a file data provider, Acumatica ERP automatically attaches to the scenario on the Import Scenarios form the file used for file data provider creation. This file is shared between the data provider and the import scenario that uses it for data import that is, it is attached to both the Data Providers (SM206015) form for the provider and the Import Scenarios form for the scenario. You can view and modify the attached file on the File Maintenance (SM202510) form; to open the form, while you are viewing the import scenario, click Files on the title bar. After you specify the required parameters, you can set the following optional parameters: Sync Type: By default, the Full sync type is selected in this box, which means that all data available in the source is imported. Selecting a different option is useful if you use the same scenario regularly for importing only some of the data from the source. For example, if after the initial import you need to periodically upload new data records that have appeared in the source.

21 Configuring Import Scenarios 21 If the data is imported from a file data source, you can set the scenario to import the data only if a new version of the source file is provided before import. To do this, set Sync Type to Incremental - All Records or Incremental - New Only; both options provide the same result. In this case, if you upload a new version of the source file by using the Import by Scenario (SM206036) form before import, the data from the source file is imported to the system. If no new version of the file is provided, no data is imported. Format Locale: For Acumatica ERP to recognize the format of imported dates, numbers, and other country-specific data correctly, you should specify the appropriate locale in this box. By default, Acumatica ERP uses the invariant locale, which is similar to the English (United States) locale. The newly created scenario has the Active check box selected by default. This check box must be selected so that you can use the scenario for processing records on the Import by Scenario form. Target Objects and Fields in Import Scenarios When you are performing mapping on the Mapping tab of the Import Scenarios (SM206025) form, you have to select the target object and field. Target Objects and Fields In the Target Object column, you have to select the object of the Acumatica ERP form into which you want to insert the value. The object names that appear in this drop-down box are the names of the UI elements that you see on the form. Custom UI elements that you add to the system by means of customization are also available for mapping in the same way as the original ones. For example, to be able to select the Statement Cycle ID field that is located in the Financial Settings group on the General Info tab of the Customers (AR303000) form (shown in the following screenshot), you would select General Info -> Financial Settings as the target object for mapping. Each field or action on an Acumatica ERP form (such as a text box, combo box, table column, or button) is associated with a particular target object and becomes available for selection in the Field / Action Name column once you select the target object in the Target Object column. The field name has the same name as the corresponding box on the form, such as Statement Cycle ID, as the following screenshot shows.

22 Configuring Import Scenarios 22 Figure: Target object and field : If you are not sure that you have selected the field name correctly, you can check it as follows: 1. On the Mapping tab of the Import Scenarios form, add the Native Field/Action Name column to the mapping table. (You can change the list of columns that are displayed in the mapping table in the Columns Configuration dialog box, which opens if you click the header icon of the first column in the mapping table.) In the Native Field/Action Name column, you can see the internal name of the target field. 2. On the title bar of the target Acumatica ERP form, click Customization > Inspect Element and click the target element on the form. In the Element Properties dialog box, which opens, check that the value of the Data Field element is equal to the value in the Native Field/Action Name column in the mapping table on the Import Scenarios form, as shown in the following screenshot. Figure: Internal field name

23 Configuring Import Scenarios 23 Multiple objects support the functionality of each Acumatica ERP form: a summary object, detail objects, and related objects. These types of objects are described in the following sections. Summary Object The summary object is the main object on the form; it contains the keys that identify the record in the system. You can use the fields of the summary object to do the following: Set the values of the corresponding fields on the form. Search for a record in the system. That is, you can create custom keys from these fields to search for a particular record. For example, you can find a needed customer record in the system by using the value of the Customer Name field on the Customers (AR303000) form. Filter imported records by these fields by using target restrictions. For example, you can select for processing only the customer records that have the Inactive status in the Status field on the Customers form. Generally, you can identify the fields that belong to the summary object on the form as the fields of the summary area of the form. More precisely, these are the data fields of the data access class (DAC) underlying the summary object. (In Acumatica Framework, this DAC is called the main DAC of the primary data view.) To use the summary object in scenario mapping, select the first object in the Target Object drop-down box in the Mapping tab of the Import Scenarios (SM206025) form. For example, the summary object on the Customers form is Customer Summary. It includes the key Customer ID field. The object and field are shown in the following screenshot. Figure: Summary object and key field

24 Configuring Import Scenarios 24 The summary object on the Invoices and Memos (AR301000) form is Invoice Summary. It includes two key fields: Type and Reference Nbr. (See the following screenshot.) Figure: Summary object and key fields Detail Objects Detail objects correspond to the tabs that include lists of detail records. The fields of a detail object correspond to the columns of the detail tab. You can use the fields of the detail object to do the following: Set the values of corresponding fields of a detail line. Search for a detail line in the document. That is, you can create custom keys from these fields to search for a particular detail line in the document. For example, on the Invoices and Memos form, you can find a needed detail line of an Accounts Receivable invoice by using the value in the Transaction Descr. column. To use the detail object in the scenario mapping, in the Target Object column in the Mapping tab of the Import Scenarios (SM206025) form, select the object with the same name as the name of the detail tab. For example, Customers form has the Contacts tab, shown in the following screenshot, which includes a list of contacts. The corresponding detail object has the Contacts name.

25 Configuring Import Scenarios 25 Figure: Detail object On the Invoices and Memos (AR301000) form, the Document Details object (shown in the following screenshot) contains a list of invoice lines. Figure: Detail object

26 Configuring Import Scenarios 26 Related Objects Related objects support the functionality of other tabs and groups of fields on the form. You can use the fields of these objects only to set the values of the corresponding fields on the form. You cannot use the fields of these objects to search for records by using customer keys or to filter imported records by using target restrictions. For example, on the Customers (AR303000) form, you cannot search for the needed customer record by using the value of the field of the Main Contact group of the General Info tab as a custom key, and you cannot filter records by using the Country field of the Main Address group of the General Info tab by using target restrictions. To use a related object in the scenario mapping, in the Target Object column in the Mapping tab of the Import Scenarios (SM206025) form, select the object with the name of corresponding tab or group of fields on the form. The related objects that correspond to tabs on the form have the names of the tabs. The related objects that correspond to groups of fields on the form have names in one of the following formats: Summary Name -> Group of Fields Name or Tab Name -> Group of Fields Name. For example, on the Customers form, the Main Contact and Main Address groups of elements on the General Info tab are represented by related objects, as the following screenshot illustrates. These objects are listed in the Target Object column as General Info -> Main Contact and General Info -> Main Address. Figure: Related objects Source Fields in Import Scenarios When you are performing mapping on the Mapping tab of the Import Scenarios (SM206025) form, you have to select in the Source Field / Value column the source field from which the system takes the value to be inserted into the target field. You can use the following as source fields:

27 Configuring Import Scenarios 27 The fields defined in the data provider The fields of an Acumatica ERP form, from which we can take the value that already exists in the system or the default value Any combination of the fields defined in the data provider, the fields of an Acumatica ERP form, constants, and functions Relationships Between Source Fields and Target Objects and Fields Source data includes a set of master records, such as customer account records. Each master record has a set of fields that are mapped to the fields of the summary object and related objects. For customer accounts, these fields can include Customer ID and . There may be only one value of such field for each summary object or related object. A master record can have a set of detail lines that are mapped to the fields of detail objects. For example, a customer account can have multiple contact details. There may be many detail lines for each detail object. Therefore, for these detail lines to be imported to Acumatica ERP, external data should include the identifier of the master record for each detail line. That is, each detail line should have the key fields of the summary object specified. For example, suppose that you have a customer account with two contact details. In this case, the external data that you are going to import to Acumatica ERP should include two records one record with the customer ID and contact information for each contact detail. Such records should include a key field that the system uses to distinguish lines that belong to different records. The relationships between the external data and Acumatica ERP objects on the Customers (AR303000) form are shown in the following screenshot. Figure: Relationships Between External Data and Acumatica ERP Objects Source Restrictions in Import Scenarios You can use source restrictions to filter the data that you want to extract from the source for processing by the import scenario. For example, some customer ID values in the source have CUST prefixes. You can specify a source restriction that selects only the records from the source that have the CUST prefix in the customer ID field. To configure restrictions on the data that will be extracted from the source during the import, you specify conditions for the fields of the source file on the Source Restrictions tab of the Import Scenarios (SM206025) form. If you specify source restrictions, when the system prepares records for import, it selects only the records that conform to the specified condition or conditions from the source and imports only these records.

28 Configuring Import Scenarios 28 For example, suppose that you want to import only the customer records that have the CUST prefix in the customer ID. In this case, you can add the condition to the source restrictions that the external customer ID field should start with the CUST prefix. The system will import only the records for which the customer ID has the specified prefix. Target Restrictions in Import Scenarios You can specify target restrictions that apply to records after they have been processed by the import scenario. For example, suppose that you have imported customer records to Acumatica ERP and then manually changed the status of some of these records to Inactive on the Customers (AR303000) form, and now you want to update only imported customer records that have the Inactive status. Because you do not have the status in the source file, you cannot use source restrictions to select needed records. You can, however, specify a target restriction that makes the system save the results of import for only the records that have Inactive status on the form. To configure restrictions that apply to records after they have been processed by the import scenario, you specify conditions for the target fields on the Target Restrictions tab of the Import Scenarios (SM206025) form. If you have specified target restrictions, after a record is imported, the system checks the conditions for the imported record. If a record satisfies the conditions, the system saves the result of processing the record during import. If a record violates the target restrictions, the resulting record is not saved; by default, the system stops processing records and displays an error. To make the system skip errors for the records that do not meet the restrictions and proceed with processing other records, you should set the system to not break on an incorrect target. In this case, the system will continue to process subsequent records after an error has occurred for a record. For example, suppose that you want to delete customer records that have an Inactive status on the Customers form. To do this, you can add to the target restrictions the condition that the imported customer records should have the Inactive status. During import, the system will check whether each imported record has the Inactive status, and delete the record only if it has this status. To determine target restrictions, you can use only the fields of the summary object. For example, on the Customers form, you can filter records by the Customer ID, Customer Name, and Status fields. You cannot use columns of Select dialog boxes, fields of related objects, and fields of detail objects to filter records. For example, for this form, you can filter customer records neither by the value of the Country field of the Main Contact group on the General Info tab, nor by the Country column of the Selector dialog box of the Customer ID field.

29 Configuring Export Scenarios 29 Configuring Export Scenarios You create export scenarios on the Export Scenarios (SM207025) form. To create an export scenario, you specify its name, the Acumatica ERP form to be used for export, the data provider that defines the structure of the target data, and the data provider object; you also configure scenario mapping. After you have created an export scenario, you can export data by using this scenario. You export data on the Export by Scenario (SM207036) form. The system executes the export scenario when you click Prepare on this form. This processing differs from the processing of an import scenario in that the import scenario is executed only when you click the Import button after you have prepared data. When you invoke the preparation process for the export scenario, the system executes the mapping instructions for each record in the system that satisfies the conditions of the export scenario, and then lists the processed records on the Prepared Data tab. To upload the processed records to the external data source, you then click Export. In the mapping of an export scenario, you can use actions, the <Dialog Answer> command, and service commands, just as you can use in import scenarios. In This Chapter Export Scenario Creation Export Scenario Parameters Source Restrictions in Export Scenarios Export Scenario Creation You create export scenarios on the Export Scenarios (SM207025) form. The creation of the export scenario consists of the following general steps: 1. Analyzing the sequence of actions on the form for data export Before you start creating an export scenario on the Export Scenarios form, you create a data provider and learn how to retrieve the needed data records from the corresponding Acumatica ERP form. You can find more information on data providers in Data Providers. If needed, you could use the same data provider for import and export of data in the same format. However, a data provider and the scenarios that use this provider share the same external data source. Therefore, if you do not want to confuse the input and output data sources, you should create separate data providers for importing and exporting data. Before you start creating a scenario, we strongly recommend that you open a record of the exported data on the source form by selecting the values of the key fields (which gives you an understanding of how a record is retrieved on the form and which fields you need to export). As you open the record on the form, make a note of the sequence of actions you perform: the order in which you specify the values in the key field (or fields) on the form, the actions you perform, and the list of fields you need to export. 2. Specifying scenario parameters You specify the following parameters of an export scenario: the name of the scenario, the Acumatica ERP form that should be used for export, and the data provider and the object, which together specify the target data source. You can also specify other export scenario parameters that define the mode of export and the properties of the data resulting from the export. 3. Creating scenario mapping

30 Configuring Export Scenarios 30 Mapping is the process of creating one-way relations between the fields of the Acumatica ERP form and the fields of the external data source. To provide mapping for a particular field on an Acumatica ERP form, you perform the following steps on the Mapping tab of the Export Scenarios form: 1. In the Source Object box, you specify the Acumatica ERP object that includes the source field. An object represents a group of fields on an Acumatica ERP form, such as a summary area or a detail tab. (These are the same objects that are used in import scenario mapping. You can find the description of these objects in Target Objects and Fields in Import Scenarios.) 2. In the Field/Action Name column, you select the appropriate internal field or action. An internal field is a field of the Acumatica ERP object selected in the Source Object box. (These are the same internal fields that are used in import scenario mapping. You can find the description of these fields in Target Objects and Fields in Import Scenarios.) 3. In the Target Field/Value column, you select the matching external field or type a formula the system will use to determine the value. An external field is a field of the object from the data provider specified in the scenario. You first map the key fields that identify the records you want to export. After you have mapped the key fields, you should map the other needed fields. You can deactivate some steps of a scenario by clearing the Active check box for the corresponding rows. 4. Configuring source restrictions To export only some records from the Acumatica ERP database, you can configure source restrictions for an export scenario on the Export Scenarios form. You can find a detailed description of source restrictions and an example of their use in Source Restrictions in Export Scenarios. After these steps have been performed, the scenario is ready and can be used for data processing. Export Scenario Parameters When you create an export scenario on the Export Scenarios (SM207025) form, you first specify the following required parameters: Name: In this box, you specify a name for the export scenario that reflects its functionality. You have to use unique names between import and export scenarios. (That is, you cannot use the same name for both an import scenario and an export scenario.) Screen Name: In this box, you select the Acumatica ERP form from which you want to export data. Provider and Provider Object: In this box, you select one of the existing data providers and its object that should be used for data export. If you select a file data provider, Acumatica ERP automatically attaches to the scenario on the Export Scenarios form the file used for file data provider creation. This file is shared between the data provider and the export scenario that uses it for data export (that is, it is attached to both the Data Providers (SM206015) form for the provider and the Export Scenarios form for the scenario). You can view and modify the attached file by using the File Maintenance (SM202510) form. To open the form, while you are viewing the export scenario, click Files on the title bar. Then you can specify the following optional parameters: Sync Type: By default, the Full option is selected, causing all records to be exported. Selecting a different option is useful when you use the same scenario for exporting data regularly. For

31 Configuring Export Scenarios 31 example, after the initial export, you may periodically need to export new or changed data records in Acumatica ERP to the external system or file. You can select from two options that provide incremental export. To export only the records for which data has changed in the Acumatica ERP database since the previous export took place, select the Incremental - All Records sync type. To import only new records in the Acumatica ERP database, select the Incremental - New Only sync type. Format Locale: For Acumatica ERP to export dates, numbers, and other country-specific data in the needed format, you should specify the locale in the Format Locale box. By default, Acumatica ERP uses the invariant locale. The newly created scenario has the Active check box selected, which indicates that the scenario can be used for processing. Source Restrictions in Export Scenarios You use source restrictions in an export scenario for the data available in the Acumatica ERP database. For example, you can configure the system to export only the records that have a particular status. To specify restrictions on the data being exported, you specify conditions for the Acumatica ERP fields on the Source Restrictions tab of the Export Scenarios (SM207025) form. In this case, when it prepares records for export, the system selects only the records that meet the specified condition (or conditions) and imports only these records. For example, suppose that you want to export from the Customers (AR303000) form only the customer records that have Active status. In this case, you can add to the source restrictions the condition that the Status field should be equal to Active. During the preparation process (when you click Prepare on the Export Scenarios form and the system prepares the data for export), the system processes the records that match the source restrictions of the scenario and prepares only the records with the Active status. In source restrictions, you can use only the fields of the summary object or detail objects of the form from which you are exporting data. You cannot use columns of Select dialog boxes and fields of related objects to filter records or detail lines.

32 Configuring Scenario Mapping 32 Configuring Scenario Mapping You perform the mapping of an import scenario on the Mapping tab of the Import Scenarios (SM206025) form, and you perform the mapping of an export scenario on the Mapping tab of the Export Scenarios (SM207025) form. You use similar principles when configuring the mapping of either type of scenario. In this chapter, you can find the main ideas that apply to scenario mapping. Most of the ideas are described in examples of import scenarios. However, you can configure the mapping of an export scenario similarly. The topics of this chapter also describe information that is specific to mappings of export scenarios. You can find examples of scenario mapping in the I100 Integration Scenarios training course. In This Chapter General Recommendations and Limitations of Data Import Types of Target Fields in Import Scenarios Fields with Commit in Import and Export Scenarios Service Commands in Import and Export Scenarios Pop-Up Dialog Boxes in Import Scenarios Actions in Import Scenarios Key Fields and Search in Import Scenarios Export of All Records: Use of Every Data Modification During Export: Use of Commit and Actions Multi-Language Fields in Import and Export Scenarios Formulas in the Mapping Operators Functions General Recommendations and Limitations of Data Import In this topic, you will find general recommendations for data import, including its limitations. General Recommendations for Importing Accounts and Subaccounts When you import accounts and subaccounts to Acumatica ERP, consider the following general recommendations: In your new Acumatica ERP implementation, the chart of accounts may differ from the chart of accounts in the legacy application from which you are going to import the data. When the company switches to newer software, the length of the account identifier is usually extended to include more characters; in many cases, several zeros are added in the middle of or at the end of the account identifier. In such a simple case, consider inserting these additional characters during the import process by using a formula. In Acumatica ERP, subaccount identifiers are segmented, but the separator characters are not part of the subaccount identifier as it is saved in the database. If subaccount identifiers in the

33 Configuring Scenario Mapping 33 external file have segments separated by a character, use a formula such as the following to remove this character from the external data during import. replace([sales Subaccount],'-','') If you import subaccounts from your subsidiary or parent company, consider the differences in their segment structures. You may need to add a segment when you're importing from a subsidiary or remove a segment when you're importing from a parent company. General Recommendations for Importing Vendor and Customer Data Here are some general recommendations for importing vendor and customer data to Acumatica ERP: In Acumatica ERP, vendor and customer IDs may be segmented. You can create a formula to insert any missing segments into the imported IDs. If the external file contains fields with vendor or customer data that is not tracked in Acumatica ERP in built-in fields, you can create and use attributes to store this vendor or customer data in Acumatica ERP. Attributes are created for vendor or customer classes, and then can be entered and tracked for individual vendors and customers. For details, see Attributes. If customer and vendor records have numerical IDs in the source and you want to retain these IDs in the new implementation, perform the following steps: On the Segmented Keys (CS202000) form, configure the VENDOR and CUSTOMER segmented keys as alphanumeric one-segment keys. Import the records with their IDs unchanged. On the Numbering Sequences (CS201010) form, assign appropriate numbering sequences to the VENDOR and CUSTOMER segmented keys with the appropriately adjusted lastused numbers (equal to the largest number used in the imported data for vendors and customers, respectively) to assign numeric IDs to new customers and vendors. When an Acumatica ERP user creates a new vendor or customer account in the standard way, by filling out the Vendors (AP303000) or Customers (AR303000) form, some fields are populated automatically with values provided by the default vendor or customer class or the vendor or customer class the user has selected instead. To use the functionality of classes while you are importing vendor or customer data, before import, analyze the source data and create as many classes as there are groups of customers or vendors in the source (or source file) that would need accounts, subaccounts, and other common information you can specify among the class settings. When you create classes, take one of the following approaches: If one group of settings can fit all customers or vendors, use just one default class. To use default values from the default vendor or customer class, you don't even need to do anything specific, such as mapping the Vendor Class field or Customer Class field to any data. To use default values from a particular class, in the Field/Action Name box of the Import Scenarios (SM206025) form, you can assign the class to the Vendor Class field (when you are importing vendor records) or to the Customer Class field (when you are importing customer records) directly as a literal or assign a class conditionally, by using appropriate formulas that are based on customer or vendor properties. Filling in the class ID field requires a commit to the database and a form refresh. General Recommendations for Importing Documents and Batches When you're importing batches, Accounts Payable documents, or Accounts Receivable documents, consider the following recommendations regarding the mapping: Batch or Document IDs: By default, Acumatica ERP automatically generates identifiers for General Ledger batches and Accounts Payable and Accounts Receivable documents. For example,

34 Configuring Scenario Mapping 34 when importing batches to the Journal Transactions (GL301000) form, even if you map the Batch Number field to an external field holding batch IDs, when the record is saved, the original batch ID will be overwritten by an automatically generated ID. If you plan to update the imported batches later, you will not be able to recognize the imported records by their new IDs. To make updating of the imported records possible, you need to save the original ID to another field to be able to recognize the previously imported records. You can use the field for this purpose. As an alternative to this approach, you can configure manual numbering of batches or documents on the Numbering Sequences (CS201010) form, import them with their IDs defined in the source, and then configure the system to use auto-numbering again. Batch Control Totals: When importing batches to the Journal Transactions form, if you are mapping the Control Total field, take into account whether the Validate Batch Control Totals on Entry check box is selected on the General Ledger Preferences (GL102000) form. If it is selected and you map the Control Total field to the source field, during data import until all batch entries are imported, the system will display the error, indicating that the control total does not match the credit total or debit total. In this case, on the Import Scenarios form, select the Ignore Error check box for the row that maps the Control Total field to force the system to ignore such errors during the import process. Document Amounts: When importing documents to the Bills and Adjustments (AP301000) or the Invoices and Memos (AR301000) form, if you are mapping the Amount field, take into account whether the Validate Document Totals on Entry check box is selected on the Accounts Payable Preferences (AP101000) or Accounts Receivable Preferences (AR101000) form. If it is selected and you map the Amount field to the source field, during data import until all document details are imported, the system will display the error, indicating that the document is out of balance. In this case, on the Import Scenarios form, select the Ignore Error check box for the row that maps the Amount field to force the system to ignore such errors during the import process. Mapping Statuses: The possible batch and document statuses in the source may be different from those in Acumatica ERP. To manage this discrepancy, you might want to exclude the Status field of the applicable form from mapping. In this case, the imported batch or document will get one of the following statuses: On Hold, if the Hold Batches on Entry check box is selected on the General Ledger Preferences form or the Hold Documents on Entry selected is selected on the Accounts Receivable Preferences or Accounts Payable Preferences form Open, if the Hold Batches on Entry or Hold Documents on Entry check box is not selected on the appropriate form General Recommendations for Importing Attributes Attributes in Acumatica ERP make it possible for users to specify additional properties (those not already defined on the applicable Acumatica ERP form) of entities, such as stock items, leads, opportunities, customers. The list of attributes is specified for an entity class, so that entities assigned to different classes may have different sets of attributes. To import data with attributes, you have to create a scenario for each class if the applicable classes have different sets of attributes. In the mapping of the scenario created to import entities of a particular class on the Import Scenarios (SM206025) form, you should specify the name of the attribute as the source field for the Attribute target field and the value of this attribute as the source field for the Value target field. Limitations of Data Import By using import scenarios, you can perform the same commands on the form as you do during manual input, with the following exception:

35 Configuring Scenario Mapping 35 For the Bills and Adjustments (AP301000) form, <Action: Auto Apply> (which corresponds to the Auto Apply button on the Applications tab) does not work because Acumatica ERP does not load applications during data import. Types of Target Fields in Import Scenarios You perform mapping of an import scenario on the Mapping tab of the Import Scenarios (SM206025) form. For each target field on an Acumatica ERP form, you need to know the type of the target field and be sure the source field values have the appropriate format for the type, so that the system can insert the value of the field correctly. The type of the target field, which depends on the type of UI element that represents it on the form to which you are importing data, might be a text box of several types, a date picker, a check box, a drop-down list, a radio button, or an action or menu on the toolbar. Also, the target field might be on a dialog box or pop-up panel rather than on the form itself. : In most cases, it is clear which format of the value you need for the mapping. However, if you are not sure which format of the value you need, you can create one record manually in Acumatica ERP, specify the needed value of a field of this record, compose an export scenario, and export the value of this field. Make sure the export scenario has output the value in the appropriate format. For more information on export scenarios, see Configuring Export Scenarios. Text Box with Text The target field on the Acumatica ERP form may be a text box into which a user types text. For example, the box on the General Info tab of the Customers (AR303000) form is a text box in which the user types an address. A text box can have a mask, which is denoted by the (_) symbol. If the text box has a mask, you cannot insert the underscore symbol (_) because this symbol is reserved for masked input in the system. If the text box has no mask, you can insert any characters into the box, including any letters and symbols. The length of the string that you insert into a text box should not exceed the maximum length of the underlying target element. (To check the maximum length, find the maximum string that can be manually inserted into the box on the form.) For some text boxes, you can type text in multiple languages. (For the list of these text boxes, see Boxes that Have Multi-Language Support.) To import the values of a text box in multiple languages, you should specify a string in JSON format that contains values in the needed languages. For details, see Multi-Language Fields in Import and Export Scenarios. Text Box with Currency Amount The target field on the Acumatica ERP form may be a text box that holds a currency amount. For example, the Amount box in the Summary area of the Invoices and Memos (AR301000) form is a text box with a currency amount. You have to provide currency amounts in the format that you specified for the import scenario in the Format Locale box in the Summary area of the Import Scenarios (SM206025) form. For example, if you specified the English (United States) locale for a import scenario, you have to provide amounts where the decimal part is separated by a decimal point: : By default, Acumatica ERP imports currency amounts with a decimal precision of 2, which is specified in the Decimal Precision box on the Branches (CS102000) form. When you import the currency amounts of Account Payable or Account Receivable documents, make sure that the sum of imported lines is equal the imported document total, taking into account the rounding accuracy as follows: The decimal precision of line amounts must be equal to the decimal precision of document total. The decimal precision of all amounts must be less than or equal to the decimal precision that is specified in Acumatica ERP. For example, if the decimal precision in Acumatica ERP is 2 and you import an amount with a decimal precision of 3, such as , the imported value will be rounded by arithmetical rules to

36 Configuring Scenario Mapping 36 If you import data from an Excel file, you can use the Round(x,y) function to round the amounts, and then you can copy the values to a column from which you will import data. Text Box with a Key Value The target field on the Acumatica ERP form may be a text box that holds a key value. Two examples of key fields are Customer ID on the Customers (AR303000) form, and Reference Nbr on the Invoices and Memos (AR301000) form. The way you specify the value for key fields depends on your goal and the auto-numbering settings of the records that you are importing. For more information and examples of mapping key fields, see Key Fields and Search in Import Scenarios. Date Picker The target field on the Acumatica ERP form may be a date picker that is used to select the date. For example, the Date element in the Summary area of the Invoices and Memos form is a date picker. You have to provide date values in the format that you specified for the import scenario in the Format Locale box in the Summary area of the Import Scenarios form (SM206025). For example, if you specified the English (United States) locale for the import scenario, you have to provide dates in the format MM/DD/YYYY. Thus, the September 1, 2014 will be 09/01/2014. Check Box The target field on the Acumatica ERP form may be a check box the user can select or clear. For example, the Hold element in the Summary area of the Invoices and Memos (AR301000) form is a check box. To select a check box, map the corresponding target field to the value True. To clear a check box, map the target field to the value False. Drop-Down List The target field on the Acumatica ERP form may be a drop-down list from which the user selects an option. For example, the Type element in the Summary area of the Invoices and Memos form is a dropdown list. To insert a value into a drop-down list, you have to specify the value as it is displayed in the list. For example, on the Invoices and Memos form, you can insert the value Invoice into the Type field. Radio Buttons The target field on the Acumatica ERP form may be a group of radio buttons. For example, a group of radio buttons is in the Additional Processing group of the Settings for Use in AP tab of the Payment Methods (CA204000) form. In the system, a group of radio buttons is treated as one field, which can have as the values the names of the radio buttons. Therefore, to select a radio button by using an import scenario, you should select the name of the group that contains the radio button in the Field / Action Name column of the Import Scenarios form (SM206025), and specify the name of the radio button in the Source Field / Value column. For example, to select the Print Checks radio button in the Additional Processing group of the Settings for Use in AP tab of the Payment Methods form, you should select the Settings for Use in AP target object and the APAdditionalProcessing field, and specify the source value ='Print Checks'. Buttons and Menu Items on the Toolbar The action on the Acumatica ERP form may be a button or menu item on the toolbar. For example, the Release button is on the form toolbar of the Invoices and Memos (AR301000) form. To reflect a user clicking a button in the scenario mapping, you have to insert the corresponding action in the proper position in the mapping, and you don't have to map the action to any value. For more information and examples, see Actions in Import Scenarios.

37 Configuring Scenario Mapping 37 Dialog Box The target field may be on a dialog box invoked by a user action on the Acumatica ERP form. Dialog boxes usually appear on a form to request confirmation from the user. For example, when you update the Customer Class value on the Customers (AR303000) form for an existing customer, the system displays a Warning dialog box. For more information on handling dialog boxes in import scenarios, see Pop-Up Dialog Boxes in Import Scenarios. Pop-up Panel The target field may be on a pop-up panel invoked by a user action on the Acumatica ERP form. For example, the Add Sales Order pop-up panel appears when the user clicks Add Order on the Document Details tab of the Shipments (SO302000) form. In a similar way as you specify values for fields on forms and invoke actions, you can specify values and click buttons in pop-up panels that users can invoke. Fields with Commit in Import and Export Scenarios There are two types of fields on Acumatica ERP forms: fields with commit, and fields without commit. A commit is an action initiated by the form that, when triggered, sends the data to the server. On the server, the commit causes all data on the form to be updated, including the insertion of default values and the recalculation of appropriate fields on the form. A commit is a costly operation that causes the browser to make requests to the server and takes server time. As such, a commit is invoked for only a limited number of fields: mainly the key fields and the fields on which the other fields depend. On the Mapping tab of the Import Scenarios (SM206025) form or the Export Scenarios (SM207025) form, if you select a field for which the system performs a commit, the system automatically selects the Commit check box. If the Commit check box is cleared on this tab, the field is filled in with data, but no update of the form is invoked. If the Commit check box is selected, after the field is filled in, the commit is invoked on the server and the form is updated. For example, when you select a customer on the Invoices and Memos (AR301000) form, the system assigns values to fields related to customer settings, such as the customer terms, due date, and cash discount date. When you create an import scenario for this form, for fields such as Customer, the system automatically selects the Commit check box on the Mapping tab of the Import Scenarios form. In most cases, when you compose the mapping of an import or export scenario, you can use the Commit check boxes as they are set by default. However, you may need to force the system to invoke a commit to the server for example, when you need to commit the value of one field before entering another field value, or to indicate the beginning and the end of a record if you enter records without specifying the key field value. In such cases, you should manually select the Commit check box for the field or action. For more information on the situations when the Commit check box should be selected in export scenarios, see Data Modification During Export: Use of Commit and Actions. Service Commands in Import and Export Scenarios For key fields and the first field that has a commit among the fields of a detail table, the system adds service commands on the Mapping tab of the scenario you are creating on the Import Scenarios (SM206025) form or the Export Scenarios (SM207025) form. Service commands are commands that invoke hidden actions in the system, such as searching for the record by the key field, refreshing the form, and adding a new line to the detail table. The system automatically adds service commands to the scenario immediately before the commands that invoke them. For example, suppose that on the Import Scenarios form, you are mapping the Type field of the Invoices and Memos (AR301000) form. The system automatically inserts a set of service commands before the mapping of the Type field: The <Key: DocType> and <Key: RefNbr> commands invoke

38 Configuring Scenario Mapping 38 search by the key fields, and the <Action: Cancel> command restores the default settings for the selected document type. On the table toolbar of the Mapping tab of the Import Scenarios form or the Export Scenarios form, by default, the Show All Commands option is selected in the drop-down list, which means that you can view the service commands that the system automatically adds to the import scenario. You can replace service commands with your own commands to change the default behavior of the system. For example, if you map the first field that has a commit among the fields of a detail table, the system adds the <Line Number>=-1 service command. That means that a new row is added for each new detail line. You can specify the needed line number in the <Line Number> command to modify the value of the previously imported detail line. Line numbering starts with 0. : If you search for a detail line by a custom key, you have to delete the instruction that sets the <Line Number> to -1 from the mapping so that the system does not add a new detail line but instead searches for a detail line. Pop-Up Dialog Boxes in Import Scenarios When you update specific fields on some forms under certain circumstances, the system displays popup dialog boxes where you need to specify an answer (by clicking a button) to a question in order to proceed. For example, when you update the Customer Class value on the Customers (AR303000) form for an existing customer, the system displays a Warning dialog box with the text Please confirm if you want to update current customer settings with the customer class defaults. Otherwise, original settings will be preserved. and the Yes and No buttons. You should click Yes to proceed with changing the customer class. When you are specifying mapping for an import scenario, when you need to specify an answer to a question that would appear in a pop-up dialog box if the data was being entered manually, you should use a dialog answer command (which has the <Dialog Answer> name) of the Summary object. You should insert this command directly before you map the field that causes the appearance of the dialog box. For the dialog answer, you should select the proper answer from the options available in the Source Field/Value drop-down list on the Mapping tab of the Import Scenarios (SM206025) form. The system selects the Commit check box for the dialog answer command automatically. : In most cases, you can select the summary object as the target object of the dialog answer command, because the dialog answer is shared between all objects of an Acumatica ERP form. You may need to select another object as the target object of the dialog answer command, if you need to overwrite the answer that is specified by the dialog answer command of the Summary object. Below are the settings in the two rows you would enter on the Mapping tab to update the customer class of an existing customer record. The first row contains the instruction to click Yes in the confirmation dialog box. Example of <Dialog Answer> Command Usage Target Object Field / Action Name Source Field / Value Customer Summary <Dialog Answer> ='Yes' General Info -> Financial Settings Customer Class CUSTOMER CLASS Actions in Import Scenarios As you perform mapping for an import scenario on the Import Scenarios (SM206025) form, when you need to reflect a button being clicked on a form (such as Save, Delete, or Release to perform one of these actions on a document), you should use the corresponding action. Actions are available for all buttons on a form. In import scenario mapping, to use an action, you always have to select the summary object as the target object. No matter where the button that corresponds to the action appears on the form (on the

39 Configuring Scenario Mapping 39 summary area, the toolbar of a tab, or a pop-up panel), all actions use the summary object as the target object. Action names have the Action: prefix and are surrounded with angle brackets for example, <Action: Save> or <Action: Delete>. For an action, you should not select any external field in the Source Field/Value column of the Mapping tab of the Import Scenarios form. Key Fields and Search in Import Scenarios In the mapping of an import scenario, you have to map the key fields first, mapping the target key fields in the system to the source key fields. The system uses the following keys: Customer ID for customers on the Customers (AR303000) form, and Type and Reference Nbr. for documents on multiple forms, such as the Invoices and Memos (AR301000) form. The order of key fields is important for mapping, so you should follow the order of key fields as they are displayed on Acumatica ERP forms. In particular, for documents, you have to assign first the Type field and then the Reference Nbr. field. Auto-Numbering of Records You can import records with their key values from the source, and the records will have the same key values in the system and the source. For example, suppose you are importing records to the Customers form. If you have the customer CUST in the Excel file, you can import this customer to the system so that the customer record will have the same ID: CUST Later, you can update customer records by mapping the Excel column with the ID to the Customer ID field in the system. As an alternative to importing records with their key values from the source, you can import records and have the system automatically assign IDs. For example, you can import the customer records so that after the import, the customer will have an automatically assigned ID in the system that was not in the Excel file, such as C You can import master records with automatically assigned IDs in several ways, which are described below: You can enable auto-numbering of records in the system and map the key fields to unique identifiers of records in the source. If there is just one line for each unique record in the data source, you can enable auto-numbering of records in the system and import each line from the source file as an unique record in the system with an automatically assigned ID. With this way of mapping, you do not map key fields in the import scenario and add the <Action: Insert> instruction at the beginning of the mapping. You can map the key field to a formula that produces unique identifiers for each imported record in the needed format. For details on creating formulas, see Formulas in the Mapping. Auto-numbering of master records is configured in the corresponding segmented keys on the Segmented Keys (CS202000) form. Documents are usually automatically assigned a reference number in the system. During the initial implementation, you can disable auto-numbering of documents in the system, import the documents with their IDs, and then turn on auto-numbering starting from the last imported ID. Auto-numbering of documents is configured in the numbering sequences that are specified for the corresponding document types in module preferences. For example, the ARINVOICE sequence is specified for the auto-numbering of invoices on the Accounts Receivable Preferences (AR101000) form. You can update records imported with automatically generated IDs by searching for them in the system by using their unique fields available the source. For example, you can identify customers by addresses or phone numbers in the Excel file. To search for a record, you have to declare a custom key or use a column of a Select dialog box. Both of these methods are described below. Custom Key To specify a custom key, you have to define the key by using notation; directly after the notation, assign the custom key field a value. On the Mapping tab of the Import Scenarios (SM206025) form, you should select the Commit check box for this field to make the system update the form

40 Configuring Scenario Mapping 40 after the key is specified. Below is an example of the settings for a mapping instruction that declares the Customer Name as the custom key for customer records you are importing to the Customers (AR303000) form. In this example, we suppose that the Excel file doesn't contain the customer ID, and you are using the CUSTOMER NAME value from the Excel file to find the customer record in the system. Custom Key Mapping Target Object Field / Action Name Native Field / Action Name Customer Summary Customer Name AcctName Commit Source Field / Value =[BAccount.AcctName] Selected CUSTOMER NAME You can specify custom keys to search for a record or a detail line. You can use the fields of the summary object and the detail objects, but not the fields of related objects, as custom key fields. For example, you can find the needed customer record in the system by using the Customer Name field of the Customers form as the custom key, but you cannot find the record by using the field of the Main Contact group of the General Info tab as the custom key. Selector Column Selector columns on an Acumatica ERP form appear when a user clicks the Magnifier icon of a key field of the form to bring up the Select dialog box. When you are performing mapping for an import scenario, you can use any selector columns that are available on the form for the key field. To use a selector column for a search in an import scenario, you have to map the selector column to the matching external field. Selector column names start with the key field name, followed by -> and then the name of the selector column on the form, such as Customer ID -> . For example, the instruction with the following settings maps the selector column of the Customer ID field on the Customers form to the field available in the source. Selector Command Mapping Target Object Field / Action Name Source Field / Value Customer Summary Customer ID -> Export of All Records: Use of Every If you want to export every record of a specific type, on the Mapping tab of the Export Scenarios (SM207025) form, you map the key field to the =Every system action. (The Commit check box is selected automatically for this field.) This action ensures that every record of the specific type will be processed during export. For example, if you want to export all customer records available in the system, you should map the Customer ID field to =Every. The Commit check box is selected automatically for this field. If you need the value of the Customer ID field in the output destination, you should also map this field to the appropriate external field. The example below shows the mapping that makes the system export all customer records available in the system and export the Customer ID field to the target CUSTOMER ID field. Usage of the =Every Instruction Source Object Field / Action Name Target Field / Value Customer Summary Customer ID =Every

41 Configuring Scenario Mapping 41 Source Object Field / Action Name Target Field / Value Customer Summary Customer ID CUSTOMER ID Data Modification During Export: Use of Commit and Actions You can change the values of some fields or apply an action to a record during export. For example, you can change a description field of a record or delete a record as you are exporting it. Changing the Value of a Field If you need to change the values of some fields during export, you must perform a commit of these fields to the server. That is, on the Mapping tab of the Export Scenarios (SM207025) form, you must select the Commit check box for each internal field whose data is modified. If you change the values of some fields during export, you also need to insert the <Action: Save> command at the end of the scenario to save the changes to Acumatica ERP. If you specified specific field values on the form during export only in order to select the data for exporting, however, you don't need to insert the <Action: Save> command at the end of the scenario. If you configured the scenario to change the values of some fields in Acumatica ERP, the system prepares the specified records in the source and tries to apply modifications to them during the preparation process. (If modification of the specified field is not allowed in the system, the field remains unchanged.) Then the system exports all prepared records to the external system. For example, suppose that you create a scenario that exports AR invoices from the Invoices and Memos (AR301000) form and adds the string Exported on to their descriptions in Acumatica ERP. As a result of the processing of this scenario, all invoices are exported, and only the invoices with the Balanced and On Hold statuses are modified. Modification of documents with other statuses is not allowed in the system, so these documents are exported without any change to their descriptions in Acumatica ERP. Applying an Action As you perform mapping for an export scenario, when you need to reflect the clicking of a button on a form, you should use the corresponding action. You can use the same actions in export scenarios as in import scenarios. For more information, see Actions in Import Scenarios. If you are going to delete records or apply another action to records by using an export scenario, you have to specify precise source restrictions that select only those records that can be processed; otherwise, no records will be processed. For example, suppose that you want to delete Accounts Receivable invoices that have X as the value of the Project element on the Invoices and Memos form. To select only invoices that can be deleted, in the source restrictions of the export scenario, you have to specify not only the condition Project = X but also the condition Status = On Hold or Status = Balanced. If you do not specify filtering by status and there are invoices with the Open status in the system, no records will be deleted. Multi-Language Fields in Import and Export Scenarios For some text boxes on Acumatica ERP forms, users can type values in multiple languages if multiple locales are configured in Acumatica ERP. For example, if your Acumatica ERP instance has English and French locales activated and multilingual user input configured, you can specify the value of the box on the Stock Items (IN202500) form in English and French. For the list of elements that support multiple languages, see Boxes that Have Multi-Language Support. For details on how to turn on multilingual user input, see Enabling Multilingual User Input.

42 Configuring Scenario Mapping 42 Import of Localized Field Values As you perform mapping for an import scenario on the Import Scenarios (SM206025) form, when you need to import localized values of a field, you map this field to a source field that contains a string in JSON format with the localized values. In this string, you use the two-letter ISO code of the language with which the value should be associated. In the example that is mentioned at the beginning of the topic, if you need to import the values in English and French to the element of stock item records on the Stock Items form, you map the field to a source field that contains data in the following format: [en:english description,fr:french description]. The mapping example below presumes that the sinjsonformat source field contains a string in JSON format. Import of Localized Field Values Target Object Field / Action Name Source Field / Value Stock Item Summary sinjsonformat : In the JSON-formatted string, you should specify the actual values of the field in all languages that are configured for multilingual user input. If you specify the values of the field in particular languages, the values of the field in other languages configured for multilingual user input become empty. For example, suppose that in your instance of Acumatica ERP, multi-language fields can have values in English and French. If you pass the value of a field in the following format [en:english description], the French value of the field becomes empty. If a source field that you map to a multi-language field contains plain text, this text is saved as the value of the field in the current language of Acumatica ERP (that is, the language that you selected on the Welcome page of Acumatica ERP). Export of Localized Field Values Each text field that supports multiple input languages has a corresponding field with the suffix Translations in its native name. This corresponding field contains all localized values of the text field. For example, the box on the Stock Items form corresponds to the field with native name Descr. The Descr field has the DescrTranslations corresponding field, which contains the localized descriptions of a stock item. If you want to export localized values of a text box, on the Mapping tab of the Export Scenarios (SM207025) form, you map the needed Translations field, which contains localized values, to a target field. The Translations fields are not available in the list of fields in the Field / Action Name column on the Mapping tab; you should type the needed name manually. For example, suppose that you need to export the localized values of the element of the Stock Items form. You should find out the native name of the field, which is Descr, and map the DescrTranslations field to the target field, as shown in the following mapping example. : To find out the native name of a field, on the title bar of the target Acumatica ERP form, click Customization > Inspect Element, and then click the target element on the form. In the Element Properties dialog box, which opens, find the value of the Data Field element, which is the native name of the field. Export of Localized Field Values Source Object Field/Action Name Target Field/Value Stock Item Summary DescrTranslations DESCRIPTION As a result of the export of localized field values, the target field contains a string in JSON format with the available localized values of the field. The language to which the value belongs is identified by the

43 Configuring Scenario Mapping 43 two-letter ISO code of the language. For example, suppose that the element of the Stock Items form has value Item in English and Pièce in French. In this case, the target field contains the following string: [en:item,fr:pièce]. Formulas in the Mapping If you need to convert data into a different format during data import or export, you can map an internal field to a formula. You can define formulas by using the Import Scenarios (SM206025) or Export Scenarios (SM207025) form. Components of a Formula A formula can include the following components: Digital and text literals: Literals are constants within the formula that you don't want to be modified: Type digital literals as they are, such as 2, 8.25, or Enclose text literals within single quotation marks for example, 'DEF_CLASS' and 'FOB'. Operators: The following types of operators are available: Arithmetic operators take numerical values and return a numerical value. Logical operators evaluate one or two Boolean expressions and return a Boolean result. Comparison operators compare two expressions and return a Boolean value that represents the result. Functions: Functions, which perform specific tasks and return results, include the following types: Text functions perform operations on text strings. Math functions perform calculations. Conversion functions convert data from one type to another. Date/time functions perform functions related to the date, the time, or both. Fields: External or internal fields (elements) can be used in a formula as operands or function arguments. Assigning a Formula To assign a formula to a field, do the following on the Import Scenarios or Export Scenarios form: 1. Click the pen icon in the field where you want to insert a formula. This invokes the Formula Editor dialog box, which can be used to create the formula you want. See Formula Editor Dialog Box for details on using the dialog box, as well as descriptions of components.

44 Configuring Scenario Mapping Click any of the types in the Component Types pane (on the upper left of the dialog box) to open the list of related components in the right pane. 3. Double-click a component from the list of components. Note that all components are added to the right of the formula text. 4. Repeat Steps 2 3 to add all the needed components. 5. In the Formula Text pane (at the bottom of the dialog box), manually edit the text to construct a correct formula: Move the function argument or arguments within a function's parentheses, correctly arrange operands and operations, and add any needed brackets to ensure the proper order of operations. 6. Click Validate to check the syntax of the formula and make necessary corrections if required. 7. Click OK to save the formula. Once it's inserted, a formula is preceded by an equal sign (=). Formulas in Export Scenarios When you map the data in Acumatica ERP to the external fields, you will usually need field-to-field mapping. In some cases, however, you may need to add values from multiple internal fields to export the resulting value to an external one, to extract only a part of the internal field's value, or to perform another transformation or conversion for the data to be exported. If you map an internal field to a formula instead of an external field, the resulting value will be assigned back to the Acumatica ERP field. This functionality can be used, for example, to set criteria on inquiry forms to export only filtered data or to mark exported records as exported. Formulas in Import Scenarios When you map Acumatica ERP fields to the external data, you will usually need field-to-field mapping. For some fields, however, you may need to add values from multiple external fields to an internal one, to extract only a part of the external field's value, or to perform another transformation or conversion.

45 Configuring Scenario Mapping 45 As you map an Acumatica ERP field to the external data, the system checks the functionality of the mapped field and automatically adds, if necessary, a line that contains the system action (hidden by default) required for the field, such as a refresh of the form or a commit to the database. Formula Examples Here are some examples illustrating the use of formulas: This formula is used for assigning a literal: ClassID ='Imported Vendors'. This formula assigns a concatenated string: VendorID = 'X'+[VendID]. This formula is used for assigning a value to a check box: IsAddressSameAsMain = true. If the internal field is required, it's important to check that the field value is not blank. To do this, use the Iif(str, truestatement, falsestatement) function, as in the following example: CountryID =iif(trim[country]='','us',[country]). Then the internal field will get the US value if the external field is blank. If the customer IDs from the source cannot be used in your implementation, create new IDs for them. For example, in the demo data, customer and vendor IDs are short versions (up to 15 characters) of their names converted to uppercase. To do this, remove any spaces from the name by using the trim(arg) function, convert it to uppercase with the UCase(arg) function, and remove any characters in excess of 10 by using the Left(arg) function: Customer ID =Left( trim(ucase([name])),10). You can find more information on the operators and functions that can be used in formulas in the mapping in the following topics: Operators Functions Operators Operators are used in formulas that you create on the Formula Editor Dialog Box, which is called from the Import Scenarios (SM206025) and Export Scenarios (SM207025) forms. To add operators to the formula, you can enter them directly in the Formula Text pane of the dialog box or select them from the list of formula components available within the dialog box. (Select an operator type to view the list of operators of the type, and then select an operator.) To specify the operands for operators, you can type them in the Formula Text pane or select them from the list of external or internal fields provided within the Formula Editor dialog box. This article describes and provides examples of the operators you can use in formulas, broken down by operator type. Overview of Operators There are two types of operators: unary and binary. Unary operators are applicable to only one operand, while binary operators require two operands. In general, expressions are evaluated from left to right with the following order of precedence: Logical Operators: Not, And, Or Comparison Operators: =, <>,, <=, >= Arithmetic Operators: -, *, /, Mod, +, -

46 Configuring Scenario Mapping 46 Arithmetic Operators Arithmetic operators, which are listed below, take numerical values as their operands and return a single numerical value. Operator and Example + Adds the two operands and returns the result. If at least one operand is a string, this operator returns a concatenated string. Example: =[Amount]+[Tax Amount] In this example, the [Amount] and [Tax Amount] values are used as operands. - Subtracts the second operand from the first. Example: =[Amount]-[Cash Discount] In this example, the [Amount] and [Cash Discount] values act as operands. * Multiplies the two operands. Example: =[Chargeable Amount]*0.03 In this example, the [Chargeable Amount] value and the number 0.03 serve as operands. / Yields the quotient of the operands, which is the first operand divided by the second. Example: =[Amount]/[Rate Reciprocal] In this example, the [Amount] and [Rate Reciprocal] values are the first and second operands. Mod (Modulus) Divides the first integer operand by the second integer operand and returns the remainder, rounded to the nearest integer. Example: =[Volume] Mod [Conversion Factor] In this example, the [Volume] and [Conversion Factor] values are used as operands. Logical operators Logical operators evaluate one or two Boolean expressions and return a Boolean result (True or False). Because these operators evaluate only Boolean expressions, you must use elements whose only values are True and False (typically check boxes and radio buttons). The logical operators are listed below. Operator and Example And Performs logical conjunction on two Boolean expressions: returns True if and only if both expressions evaluate to True; in other cases, returns False. Example: =[Hold] And [Validate Control Totals on Entry] In this example, the [Hold] and [Validate Control Totals on Entry] check boxes are used as operands. Or Performs logical disjunction on two Boolean expressions: returns True if at least one expression evaluates to True; returns False if neither expression evaluates to True.

47 Configuring Scenario Mapping 47 Operator and Example Example: =[Hold] Or [Validate Control Totals on Entry] In this example, the [Hold] and [Validate Control Totals on Entry] check boxes act as operands. Not Performs logical negation on a Boolean expression: returns True if and only if the operand is False. Logical negation is an unary operator. Example: =Not [Hold Documents on Entry] In this example, the [Hold Documents on Entry] check box is used as the single operand. Comparison Operators Comparison operators compare two expressions and return a Boolean value (True or False) that represents the result of the comparison. This group of operators includes the following operators. Operator and Example = Returns True if operands are equal. Example: =([Credit Total] = [Control Total]) In this example, the [Credit Total] and [Control Total] values are used as operands. <> Returns True if operands are not equal. Example: =([Credit Total] <> [Debit Total]) In this example, the [Credit Total] and [Debit Total] values act as operands. < Returns True if the first operand is less than the second one. Example: =([DocDate] < [DueDate]) In this example, the [DocDate] and [DueDate] values act as operands. > Returns True if the first operand is greater than the second one. Example: =([CrLmt] > 1000]) In this example, the [CrLmt] value is used as the first operand, and the number 1000 acts as the second operand. <= Returns True if the first operand is less than or equal to the second operand. Example: =(([DueDate]-[CashDiscountDate]) <= [LeadTime]) In this example, [DueDate] - [CashDiscountDate] is the first operand, and the [LeadTime] value is used as the second operand. >= Returns True if the first operand is greater than or equal to the second operand. Example: =([Balance] => [Amount]) In this example, the [Balance] and [Amount] values are used as operands. Other Operators This miscellaneous group of operators includes the following operators and constants.

48 Configuring Scenario Mapping 48 Operator and Example In An operator that returns True if the second operand (a string) contains the first operand (which is also a string). Example: =('Inc.' In [Vendor Name]) In this example, the [Vendor Name] value is used as an operand, and the formula returns True if the name of the vendor contains Inc. True A binary constant used as an operand in logical expressions. Example: =True False A binary constant used as an operand in logical expressions. Example: =False Null A special value used as an operand in logical expressions; designates an undefined value. Example: =Null Functions Functions are used in formulas that you create on the Formula Editor Dialog Box, which you can invoke from the Import Scenarios (SM206025) and Export Scenarios (SM207025) forms. To add functions to a formula, you can type them in the Formula Text pane of the dialog box or select them from the list of formula components available within the dialog box. (Select a function type to view the list of functions of the type, and then select a function.) This topic describes and provides examples of the functions you can use in formulas, broken down by type. Conversion Functions The available conversion functions, which are used to convert data from one data type to another, are listed below. Function and Example CBool(x) Converts the expression used as the function argument into a Boolean expression. Returns False if the Boolean value is zero; otherwise, returns True. Example: =CBool([CashDiscountAmount] Here [CashDiscountAmount] is used as the function argument. CDate(x) Converts the expression used as the function argument into a value of the Date type. The argument should be a valid date expression according to the locale selected for the import or export scenario. Example: =CDate('24/12/2011') Here a string is used as the function argument. CStr(x) Converts the expression used as the function argument into a string. If the argument is Null, the function returns a run-time error; otherwise, it returns a string. Example: ='(' +CStr([AreaCode])+')'+CStr([Phone])

49 Configuring Scenario Mapping 49 Function and Example Here [AreaCode] and [Phone] are used in the function argument. CDbl(x) Converts the expression defined in the function argument into a value of the Double type. Example: =CDbl(1.0/[ExchangeRate]) Here [ExchangeRate] is used in the function argument. CSng(x) Converts the expression used as the function argument into a value of the Single type. If the expression has a value outside the acceptable range for the Single type, this function returns an error. Example: =CSng([CashDiscountAmount]/[DocAmount]) Here [CashDiscountAmount] and [DocAmount] are used in the function argument. CDec(x) Converts the expression used as the function argument into a value of the Decimal type. Example: =CDec([DocAmount]*0.015) Here [DocAmount] is used in the function argument. CInt(x) Converts the expression used as the function argument into a value of the Integer type. Example: =CInt('2012')-Year([DocDate]) Here [DocDate] is used in the function argument. CShort(x) Converts a numeric value to a value of the Short type. Example: =CShort([CashDiscountAmount]) Here [CashDiscountAmount] is used as the function argument. CLong(x) Converts a numeric value to a value of the Long type. Example: =CLong([CashDiscountAmount]) Here [CashDiscountAmount] is used as the function argument. Text Functions Text functions are used to perform operations on text strings. The group of text functions includes the functions described below. Function and Example LTrim(string) Removes all leading spaces or parsing characters from the specified string, or all leading zero bytes (0) from the specified binary expression. Example: =LTrim(CStr([Phone])) Here [Phone] is used as the function argument. RTrim(string) Removes all trailing spaces or parsing characters from the specified character expression, or all trailing zero (0) bytes from the specified binary expression. Example: =RTrim(CStr([AreaCode]))

50 Configuring Scenario Mapping 50 Function and Example Here [AreaCode] is used as the function argument. Trim(string) Removes all leading and trailing spaces or parsing characters from the specified character expression, or all trailing zero (0) bytes from the specified binary expression. Example: =Iif(Trim([Country]) Here [Country] is used in the function argument. Format(format, argument(s)) Replaces the format item in a specified formatting string (format) with the text equivalent of the arguments (arguments). Example: =Format('Currency: :C; Account: :N', [Currency], [AccountBalance]) Here [Currency] and [AccountBalance] are used in the function argument; 0 and 1 are the specifiers indicating where the arguments will be inserted, C is the currency format specifier, and N is the number format specifier. UCase(string) Returns a string that has been converted to uppercase. The string argument can be any valid string expression. If string contains Null, Null is returned. Example: =UCase([CustomerName]) Here [CustomerName] is used as the function argument. LCase(string) Returns a string that has been converted to lowercase. The string argument can be any valid string expression. If string contains Null, Null is returned. Example: =LCase(CStr([CustomerID]) Here [CustomerID] is used in the function argument. InStr(string, findstring) Returns the position of the first occurrence of one string (findstring) within another (string). Example: =InStr([CustomerName], 'Inc') Here [CustomerName] is used in the function argument. InStrRev(string, Returns the position of the last occurrence of one string (findstring) within findstring) another (string). Example: =InStrRev([CustomerName], 'Inc') Here [CustomerName] is used in the function argument. Len(string) Returns an integer containing either the number of characters in the string or the nominal number of bytes required to store a variable. Example: =Len([CustomerName]) Here [CustomerName] is used as the function argument. Left(string, length) Returns a string containing the specified number of characters from the left side of a string. If string contains Null, Null is returned. Example: =Left(Trim([VendorName]), 10) Here [VendorName] is used in the function argument.

51 Configuring Scenario Mapping 51 Function and Example Right(string, length) Returns a string containing a specified number of characters from the right side of a string. If string contains Null, Null is returned. Example: =Right(CustomerName, 3) Here [CustomerName] is used in the function argument. Replace(string, oldvalue, newvalue) Returns a string in which the specified substring (oldvalue) has been replaced with another substring (newvalue). Example: =Replace([], 'rur', 'eur') Here [] is used in the function argument. PadLeft(string, width, paddingchar) Right-aligns the characters in a specified string (string), padding with the specified character (paddingchar) on the left up to the specified total width (width). If the actual length of the string is less than the specified width, returns the original string. Example: =PadLeft(CStr(Phone), 12, '_') Here [Phone] is used in the function argument. If the actual length of the string is less than the specified width, returns the original string. PadRight(string, Left-aligns the characters in a specified string (string), padding with the specified width, character (paddingchar) on the right up to the specified total width (width). paddingchar) Example: =PadRight(CStr([City]), 25, '_') Here [City] is used in the function argument. If the actual length of the string is less than the specified width, returns the original string. Math Functions Mathematical functions, which are listed and described below, perform calculations, usually based on input values provided as arguments, and return numeric values. Function and Example Abs(x) Returns the absolute value of the number. Example: =Abs([TotalDebit]-[TotalCredit]) Here [TotalDebit] and [TotalCredit] are used in the function argument. Floor(x) Returns the largest integer that is not greater than the argument. Example: =Floor([Price]/([Cost]) Here [Price] and [Cost] are used in the function argument. Ceiling(x) Returns the smallest integer that is not less than the argument. Example: =Ceiling([Price]/[Cost]) Here [Cost] and [Price] are used in the function argument. Round(x, decimals) Returns a numeric expression, rounded to the specified precision (decimals). Example: =Round(([Price]-[Cost])/[Cost], 2) Here [Cost] and [Price] are used in a function argument, and 2 is the number of decimal places.

52 Configuring Scenario Mapping 52 Function and Example Min(x, y) Returns the smaller of the two values. Example: =Min([Price],[Cost]) Here [Cost] and [Price] are used in the function argument. Max(x, y) Returns the greater of the two values. Example: =Max(StandardCost],[AvrCost]) Here [StandardCost] and [AvrCost] are used in the function argument. Pow(x, power) Computes the value of x raised to the specified power (power). Example: =Pow(([Markup], 2)) Here [Markup] is used in the function argument; the function returns the markup value squared (or to the second power). Date/Time Functions The date/time functions, described below, perform operations on system-generated values and return values of the following types: string, numeric, or Date/Time. Function and Example Now() Returns the current date and time according to the system date and time on the local computer. Example: =Now() Today() Returns the current date according to the system date and time on the local computer. Example: =Today() NowUTC() Returns the current date and time according to the user's time zone. The system gets the user's time zone from the following sources, which are ordered by the priority from the highest to the lowest: 1. User's preferences specified on the User Profile (SP203010) form. 2. The employee calendar specified on the Work Calendar (CS209000) form and selected for the user's employee on the Employees (EP203000) form. 3. Site preferences specified on the on the Site Preferences (SM200505) form. Example: =NowUTC() TodayUTC() Returns the current date according to the user's time zone. The system gets the user's time zone from the following sources, which are ordered by the priority from the highest to the lowest: 1. User's preferences specified on the User Profile (SP203010) form. 2. The employee calendar specified on the Work Calendar (CS209000) form and selected for the user's employee on the Employees (EP203000) form. 3. Site preferences specified on the on the Site Preferences (SM200505) form.

53 Configuring Scenario Mapping 53 Function and Example Example: =TodayUTC() DateAdd(dt, int, Returns a new date calculated by adding the specified number (nbr) of time nbr) intervals (int) to the date (dt). The int argument specifies the type of time interval and is one of the following options: yyyy: A number (nbr) of years will be added to the specified date (dt). m: A number (nbr) of months will be added to the specified date (dt). y: Same as d; see below. d: A number (nbr) of days will be added to the specified date (dt). h: A number (nbr) of hours will be added to the specified date (dt). n: A number (nbr) of minutes will be added to the specified date (dt). s: A number (nbr) of seconds will be added to the specified date (dt). Examples: =DateAdd([StartPeriod], 'm', 12) =DateAdd([CashDiscountDate], 'd', -2) In these examples, [CashDiscountDate] and [StartPeriods] are used in the function arguments. Year(date) Returns the year, as an integer, extracted from the specified date (date). Example: =Year([StartPeriod]) Here [StartPeriod] is used as the function argument. Month(date) Returns the month, as an integer, extracted from the specified date (date). Example: =Month([StartPeriod]) Here [StartPeriod] is used as the function argument. Day(date) Returns the day (as an integer) extracted from the specified date (date). Example: =Iif(Day([DueDate]-[LeadTime])=0, True, False Here [DueDate] and [LeadTime] are used in the function argument. DayOfWeek(date) Returns the day of the week associated with the specified date (date) as an integer. Example: =DayOfWeek([StartPeriod]) Here [StartPeriod] is used as the function argument. DayOfYear(date) Returns the day of the year calculated for the specified date (date). Example: =DayOfYear([StartPeriod]) Here [StartPeriod] is used as the function argument. Hour(date) Returns the hours extracted from the specified date (date). Example: =Hour([StartPeriod]) Here [StartPeriod] is used as the function argument.

54 Configuring Scenario Mapping 54 Function and Example Minute(date) Returns the number of minutes extracted from the specified date (date). Example: =Minute([StartPeriod]) Here [StartPeriod] is used as the function argument. Second(date) Returns the seconds extracted from the specified date (date) as an integer. Example: =Second([StartPeriod]) Here [StartPeriod] is used as the function argument. Other Functions This miscellaneous group of functions includes the following functions. Function and Example IIf(expression, truepart, falsepart) Returns one of two values, depending on the evaluation of the expression: If the expression evaluates to True, the function returns the truepart value; otherwise, it returns the falsepart value. Example: =IIf(([CurrencyID]='', 'USD', [CurrencyID]) Here [CurrencyID] is used in the function argument. Switch( expression_1, Returns the value value_n that corresponds to the first expression expression_n value_1, that evaluates to True. expression_1, expression_2, and so on are Boolean expression_2, expressions. value_2,...) Example: =Switch(([DocAmount]<100), 'small', (([DocAmount]>=100)And([DocAmount]<500)), 'medium', (([DocAmount]>=500)And([DocAmount]<1000)),'large') Here [DocAmount] is used in the function argument. IsNull(value, nullvalue) Replaces NULL with the specified replacement value. The value argument is to be checked for NULL. Example: =IsNull([CustomerID],'NULL value') Here, [CustomerID] is used in the function argument. Sum(from, to) Is not applicable to formulas used by the Integration forms. Provider.CalculateHash(string) Calculates the hash string for the specified string. Example: =Provider.CalculateHash([CUSTOMER ID] + [INVOICE REF NBR] + [LINE NBR]) In this example, the hash string is calculated for the string that contains concatenated values of the [CUSTOMER ID], [INVOICE REF NBR], and [LINE NBR] fields. Provider.CalculateHashCode(string) Calculates the hash code (which is an Integer value) for the specified string. Example: =Provider.CalculateHash([CUSTOMER ID] + [INVOICE REF NBR] + [LINE NBR]) In this example, the hash code is calculated for the string that contains concatenated values of the [CUSTOMER ID], [INVOICE REF NBR], and [LINE NBR] fields.

55 Importing and Exporting Records by Using Scenarios 55 Importing and Exporting Records by Using Scenarios After you have created an integration scenario, you can use it to transfer data between Acumatica ERP and the external system or file. You import records on the Import by Scenario (SM206036) form by using the import scenario you have created. Similarly, you export records on the Export by Scenario (SM207036) form by using the export scenario you have created. In this chapter, you can find a description of standard data import, simplified data import, and data export. In This Chapter Data Import Simplified Scenarios for Data Import Data Export Data Import After you have created an import scenario, you should test it on one record. If the scenario is not working as you expected, the first way to troubleshoot the scenario is to reproduce the mapping instructions manually on the form to which you want to import the data. In most cases, this troubleshooting step helps you quickly identify the reason why the scenario is not working, so that you can fix the scenario and continue. After you have tested an import scenario, you can use it to import data on the Import by Scenario (SM206036) form. To import external data to Acumatica ERP by using a scenario that has already been created, you should perform the steps, which are described in this topic. 1. Selecting an Import Scenario On the Import by Scenario form, you first select the name of the scenario that has been created for data import. : You can select a scenario from only the scenarios that work with forms on which you can enter data. If you do not have the access rights to enter data on the form, you cannot use a scenario that imports data to this form either. If you do not have access rights to a particular form, you will not see any scenarios for this form listed among the other scenarios. You can view the access rights to particular forms on the Access Rights by Screen (SM201020) form. 2. Uploading a New File Version If you are not using a file for importing data, skip this step. If you are importing data from a file, decide whether you need to upload a new version of the file. The file that is used for data import is attached to the form; you can click Files on the title bar to view the file. This file is attached to each of the following forms: Data Providers (SM206015), Import Scenarios (SM206025), and Import by Scenario (SM206036). If you need to use a new version of the file when importing data, you can upload the new file to the Import by Scenario form by clicking Upload File Version on the form toolbar. The schema of the uploaded file must match the schema defined in the data provider and used in the import scenario. If you have changed the file structure, you have to update the data provider and the import scenario, and only then can you use the new file to import the data.

56 Importing and Exporting Records by Using Scenarios 56 : If there is no file attached to theimport by Scenario form, you have to upload the file either by dragging the file to the form or by using the Files menu. Do not use the Upload File Version button to upload the file. After the file is uploaded to the form, you can update the version of the file by clicking Upload File Version. 3. Preparing the Data for Import You prepare records by uploading them on the Import by Scenario (SM206036) form. To prepare the data for import, you click the Prepare button on the form toolbar. The data is displayed on the Prepared Data tab; no data is yet imported into the system. 4. Importing the Prepared Data To import data to the system, you click the Import button on the form toolbar of the Import by Scenario form. The system tries to import the records with the Active check box selected one by one. After a record has been successfully processed, the system selects the Processed check box for this record. If an error occurs during the processing of a record, the process stops on the record that caused the error. 5. Correcting Any Errors If an error occurred during the import process, you have to review the error; you then do one of the following: correct the record that caused the error, or exclude the wrong record from import, or modify the import scenario. Then you have to run the import process again to process the remaining records. If you need to correct only a small number of records, you can correct them directly on the Prepare Data tab, click Save, and click Import again. You can exclude an incorrect record by clearing the Active check box, saving your changes, and clicking Import again. If you need to correct a large number of records or all records, you can correct the records in the source, upload a new file version if you are importing data from a file, and prepare and import the data again. If you need to correct the import scenario itself, make changes to the scenario on the Import Scenarios (SM206025) form, and prepare and import the data again on the Import by Scenario (SM206036) form. You can clear the history of scenario execution and clear the prepared data by clicking Roll Back on the History tab of the Import by Scenario form. The Roll Back action doesn't reverse records that have already been imported. Summary of Data Import After you have imported data, open the destination form and make sure that the imported records appear among the records. The following diagram shows the process of importing records to Acumatica ERP by using an import scenario.

57 Importing and Exporting Records by Using Scenarios 57 Figure: Data import process Simplified Scenarios for Data Import With simplified scenarios, you skip the step of creating the data provider before you create the import scenario. You compose the mapping directly on the Import by Scenario (SM206036) form and then you immediately run the import procedure on the form. Simplified scenarios are appropriate for one-time import, such as during data migration. For data migration, you can prepare all data in the source file in the format needed for import and use a

58 Importing and Exporting Records by Using Scenarios 58 straightforward mapping of the source fields to the target fields. If you need to compose a complex scenario which might involve using custom keys, searching for records, and modifying service commands you have to use regular import scenarios that you compose by creating the data provider and then defining the mapping on the Import Scenarios (SM206025) form. To import data by using a simplified scenario, you have to complete the following steps: 1. Upload the file You first upload the file with data that you want to import to the Import by Scenario form. You can upload an Excel, CSV, or XML file. The following criteria should be met for the source files for a simplified scenario: 2. Only the data from the first sheet of an Excel file is imported. A CSV file should use a comma (,) as the delimiter and have US-ASCII encoding. These default parameters are used for data provider creation. An XML file should have US-ASCII encoding and a tree structure. These default parameters are used for data provider creation. Specify the parameters of the import scenario Also on the Import by Scenario (SM206036) form, you specify the Acumatica ERP form to which you want to import data. The system suggests the scenario name depending on the selected form, but you can change the name. The system automatically detects the type of the data provider based on the extension of the uploaded file. When you click Save, the system automatically creates an import scenario (with default parameters and the specified name) and a data provider of the specified type for the simplified import procedure. 3. Configure mapping You configure mapping between the fields of the external file and the fields of the Acumatica ERP form on the Mapping tab of the Import by Scenario form. You should select the source field and the corresponding target object and field. You use the same target objects and fields that are used in regular import scenarios that you create on the Import Scenarios (SM206025) form. However, in simplified scenarios, you cannot use service commands and actions. You should select the Key check box for the fields that should be used as key fields to distinguish records that belong to different documents. You can use as keys only the fields that are mapped to the fields of the summary object. You can map the fields of the source file in any order. After you have saved the mapping, the system places the fields in the correct order and creates the import scenario mapping. The system adds all actions (including <Action: Save>) and service commands to the import scenario automatically. 4. Prepare and import data After you have specified the scenario mapping, you can prepare and import data in the same way as you do with regular import scenarios. Simplified scenarios are not available for editing on the Import Scenarios (SM206025) form, and you cannot edit the data provider that was automatically created for the simplified import scenario. If the simplified scenario is not working, you should convert the simplified scenario to a regular scenario by clicking Convert to Manual Scenario on the Import by Scenario (SM206036) form. Data Export You use the Export by Scenario (SM207036) form for data export. To export data from Acumatica ERP to an external source, you perform the steps, which are described in this topic. 1. Select an Export Scenario On the Export by Scenario form, you select the name of the scenario created for data export.

59 Importing and Exporting Records by Using Scenarios Prepare the Data for Export You prepare records by uploading them on the Export by Scenario form. The system performs all modifications defined by the scenario and uploads the modified data on the form. To prepare the data for export, you click the Prepare button on the form toolbar. You can view the data on the Prepared Data tab of this form. 3. Export Prepared Data To run the export process, you should click Export on the form toolbar of the Export by Scenario form. The system tries to export the records that have the Active check box selected. 4. Correct Any Errors Make sure each record has the check box in the Processed column on the Prepared Data tab of the Export by Scenario form selected, which means that this record has been successfully exported. The result of export may include errors, which are indicated by the icon on the form toolbar. 5. Download the Results of the Export If you are exporting data to a file, during export, the system creates a new version of the file attached to the Export by Scenario form. This file has the same structure as the file that was used for data provider creation. You can download the result of export by clicking the Get Latest Version button on the form toolbar. Internal data is exported to the external data source in a table form. That means that the values of the fields of detail objects are translated to multiple rows of this table. The number of rows is equal to the number of detail lines of the source record. Each of these rows has the values of the fields of the summary object and related objects specified. For example, suppose that on the Invoices and Memos (AR301000) form, an AR invoice has three detail lines. If you export this AR invoice with the detail lines, the data prepared for export will include three records for this invoice one record for each detail line. These records will include identical values of the fields of the invoice summary, such as type and reference number, and different values of the detail line fields. Summary of Data Export The following diagram shows the process of exporting records from Acumatica ERP by using an export scenario.

60 Importing and Exporting Records by Using Scenarios 60 Figure: Data export process

61 Authorizing Client Applications to Work with Acumatica ERP 61 Authorizing Client Applications to Work with Acumatica ERP Acumatica ERP supports the OAuth 2.0 mechanism of authorization for applications that are integrated with Acumatica ERP through application programming interfaces (APIs). When a client application of Acumatica ERP uses the OAuth 2.0 mechanism of authorization, the client application does not operate with the Acumatica ERP credentials to log in a user to Acumatica ERP; instead, the application obtains an access token from Acumatica ERP and uses this token when it requests data from Acumatica ERP. Depending on the OAuth 2.0 flow that the client application implements, the client application either has no information on the credentials of an Acumatica ERP user or uses this information only once to obtain the access token. The OAuth 2.0 mechanism of authorization improves the security of the Acumatica ERP data accessed by the application and simplifies the management of access rights. The client application that implements the OAuth 2.0 authorization mechanism can use one of the OAuth 2.0 authorization flows supported by Acumatica ERP, which are the following: Authorization code Implicit Resource owner password credentials In this chapter, you can find details on the OAuth 2.0 authorization flows and information about how to register the OAuth 2.0 or OpenID Connect client applications and revoke access of the applications. In This Chapter Authorization Code Flow To Register a Client Application Implicit Flow Resource Owner Password Credentials Flow To Revoke the Access of a Connected Application Comparison of the Flows Authorization Code Flow When you implement OAuth 2.0 authorization in a client application to make the application work with Acumatica ERP, you can use the authorization code flow. With this authorization flow, the client application never gets the credentials of the applicable Acumatica ERP user. After the user is authenticated in Acumatica ERP, the client application receives an authorization code, exchanges it for an access token, and then uses the access token to work with data in Acumatica ERP. When the access token expires, the client application can request a new access token by providing a refresh token. The following diagram illustrates the authorization code flow, whose steps are described in the sections of this topic.

62 Authorizing Client Applications to Work with Acumatica ERP 62 Figure: Authorization code flow For details on the OAuth 2.0 authorization mechanism, see the specification at html/rfc6749. Granting Permission to a Client Application Before an OAuth 2.0 client application can work with Acumatica ERP, you must register this application in Acumatica ERP and provide credentials to the application, as described in To Register a Client Application with the Authorization Code Flow. After the registration, you have the client ID and the secret value of the client application. Important: According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the OAuth 2.0 client application can work with data in Acumatica ERP. For more information, see Setting Up an HTTPS Service in Web Server (IIS). When you are registering the client application, you have to be logged in to the company whose data the client application needs to access.

63 Authorizing Client Applications to Work with Acumatica ERP 63 Connecting to the Authorization Endpoint The client application connects to the authorization endpoint of Acumatica ERP by specifying the following URL with parameters: URL The client application can use one of the following options: If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is ERP instance URL>/identity/. In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint address is : We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization endpoint address changes. The client application can directly use the authorization endpoint address, which is ERP instance URL>/identity/connect/authorize. In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the authorization endpoint address is connect/authorize. URL Parameters The client application should specify the following URL parameters. Parameter response_type The type of the OAuth 2.0 flow, which must be set to code for the authorization code flow. client_id The client ID that was assigned to the client application during the registration of the application in Acumatica ERP. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50EF710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID. redirect_uri The URI in the client application to which the response to the request should be sent. The URI must exactly match one of the values specified for the application in the Redirect URI column on the Redirect URIs tab of the Connected Applications (SM303010) form. scope The access scope that is requested by the client application. The scope can be a combination of the following values, delimited by spaces: api: Requests access to a web services API. If a user grants this scope to the application, the client application can work with either or both of the following types of the web services API: contract-based SOAP API or contract-based REST API. If this scope is granted and the api:concurrent_access scope is not granted, Acumatica ERP manages the sessions of the application through tokens. Acumatica ERP issues the first access token along with the session ID. If the client application requests a new access token

64 Authorizing Client Applications to Work with Acumatica ERP 64 Parameter by presenting a refresh token, Acumatica ERP reuses the session ID that was issued for the first access token issued with the refresh token. That is, the system uses a single session for each access granted to the client application. offline_access: Requests that a refresh token be granted. If a user grants this scope to the application, Acumatica ERP issues to the client application a refresh token along with the access token. (For information on issuing the access token, see Connecting to the Token Endpoint in this topic.) When the access token has expired, the client application can request a new access token by sending a request to the token endpoint and providing the refresh token. api:concurrent_access: Requests permission for the concurrent use of multiple types of web service APIs. If a user grants this scope to the application, the client application can access data in Acumatica ERP in concurrent mode. In this case, Acumatica ERP can maintain multiple sessions for the client application, managing session IDs through cookies. We recommend that the client application request this scope only if concurrent access is required for the client application. An example of a URL with parameters is shown below. (Line breaks are for display purposes only.) response_type=code &client_id=4b1dfd71-c5ee-0b21-a6be-9a1f060a93bd &redirect_uri=http%3a%2f%2flocalhost%2fclientapp%2f &scope=api%20offline_access Authorizing a User in Acumatica ERP and Granting Access The authorization endpoint directs the user of the client application to the login page of Acumatica ERP, where the user should enter the credentials to log in to a company configured in the Acumatica ERP instance. : The user must log in to the company that was specified in the client_id URL parameter passed to the authorization endpoint. (This company is selected by default on the login page.) If the credentials are accepted by Acumatica ERP, the system displays the consent form, where the user can confirm that the application has access to the requested scopes. Only the scopes that were requested by the application are displayed on the consent form. Receiving the Authorization Code Once the user grants access to the requested scopes, Acumatica ERP redirects the client application to the redirect_uri address that was specified in the request, and adds the authorization code in the code URL parameter. Connecting to the Token Endpoint The client application connects to the token endpoint of Acumatica ERP by specifying the following URL and the following parameters in the request body: URL The client application can use one of the following options: If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is ERP instance

65 Authorizing Client Applications to Work with Acumatica ERP 65 URL>/identity/. In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint address is : We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization endpoint address changes. The client application can directly use the token endpoint address, which is <Acumatica ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint address is Parameters in the Request Body You specify the following parameters in the request body. Parameter grant_type The type of the OAuth 2.0 flow, which must be set to authorization_code for the authorization code flow. client_id The client ID that was assigned to the client application during the registration of the application in Acumatica ERP. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50EF710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID. code The authorization code that the client application has received from the authorization endpoint. client_secret The value of the secret that was created for the client application during the registration of the application in Acumatica ERP. Receiving the Access Token Acumatica ERP verifies the provided application credentials and issues the access token, which the client application should provide with each data request to Acumatica ERP. During authentication in Acumatica ERP, if the user has granted to the client application the offline_access scope, Acumatica ERP issues the refresh token along with the access token. A successful response includes the following parameters in the response body. Parameter token_type The type of the access token, which is Bearer. access_token The access token. expires_in The period of time during which the access token is valid. refresh_token The refresh token. The parameter is returned only if the offline_access scope was granted.

66 Authorizing Client Applications to Work with Acumatica ERP 66 Requesting Data with the Access Token The client application should include the access token in the Authorization header of each subsequent request to Acumatica ERP, as shown in the following HTTP example. GET /AcumaticaDB/entity/Default/ /SalesOrder/SO/ HTTP/1.1 Host: localhost Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc Refreshing the Access Token The access token is valid for a specific period of time, which is specified in the response that returns the access token. When the access token expires, the client application can request a new access token by providing the refresh token to the token endpoint. To request a new access token, the client application should have the following URL and the following parameters specified in the request body: URL The client application can use one of the following options: If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is ERP instance URL>/identity/. In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint address is : We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization endpoint address changes. The client application can directly use the token endpoint address, which is <Acumatica ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint address is Parameters in the Request Body You specify the following parameters in the request body. Parameter grant_type The type of the request, which must be set to refresh_token for the request of the refresh token. client_id The client ID that was assigned to the client application during the registration of the application in Acumatica ERP. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50EF710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID. client_secret The value of the secret that was created for the client application during the registration of the application in Acumatica ERP. refresh_token The refresh token that the client application received from the token endpoint along with the access token if the user granted the offline_access scope to the client application.

67 Authorizing Client Applications to Work with Acumatica ERP 67 Receiving the New Access Token Acumatica ERP verifies the provided application credentials and issues the new access token. The new refresh token is not issued. To request the access token once again, the client application should use the refresh token issued with the first access token. A successful response includes the following parameters in the response body. Parameter token_type The type of the access token, which is Bearer. access_token The access token. expires_in The period of time during which the access token is valid. Logging Out from Acumatica ERP To prevent issues with licenses that limit the number of concurrent user sessions, the client application should directly call the logout method of the Acumatica ERP web services API when the application finishes its work with Acumatica ERP. Implicit Flow When you implement OAuth 2.0 authorization in a client application to make the application work with Acumatica ERP, you can use the implicit flow, which is a simplified variant of the authorization code flow. With the implicit flow, the client application never gets the credentials of the applicable Acumatica ERP user. When the user is authenticated in Acumatica ERP, the client application does not receive an authorization code (as with the authorization code flow); instead, the client application directly receives an access token, and then uses the access token to work with data in Acumatica ERP. The access token is valid for a limited period of time and cannot be renewed. The following diagram illustrates the implicit flow, whose steps are described in the sections later in this topic.

68 Authorizing Client Applications to Work with Acumatica ERP 68 Figure: Implicit flow This flow can be used for clients using a scripting language (such as JavaScript) or for mobile clients. For details on the OAuth 2.0 authorization mechanism, see the specification at html/rfc6749. Granting Permission to a Client Application Before an OAuth 2.0 client application can work with Acumatica ERP, you must register this application in Acumatica ERP and provide credentials to the application, as described in To Register a Client Application with the Implicit Flow. After the registration, you have the client ID of the client application. Important: According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the OAuth 2.0 client application can work with data in Acumatica ERP. For more information, see Setting Up an HTTPS Service in Web Server (IIS). When you are registering the client application, you have to be logged in to the company whose data the client application needs to access. Connecting to the Authorization Endpoint The client application connects to the authorization endpoint of Acumatica ERP by specifying the following URL and parameters: URL The client application can use one of the following options:

69 Authorizing Client Applications to Work with Acumatica ERP 69 If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is ERP instance URL>/identity/. In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint address is : We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization endpoint address changes. The client application can directly use the authorization endpoint address, which is ERP instance URL>/identity/connect/authorize. In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the authorization endpoint address is connect/authorize. URL Parameters The client application should specify the following URL parameters. Parameter response_type The type of the OAuth 2.0 flow, which must be set to token for the implicit flow. client_id The client ID that was assigned to the client application during the registration of the application in Acumatica ERP. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50EF710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID. redirect_uri The URI in the client application to which the response to the request should be sent. The URI must exactly match one of the values specified for the application in the Redirect URI column on the Redirect URIs tab of the Connected Applications (SM303010) form. scope The access scope that is requested by the client application. The scope can be a combination of the following values delimited by spaces: api: Requests access to a web services API. If a user grants this scope to the application, the client application can work with either or both of the following types of the web services API: contract-based SOAP API or contract-based REST API. If this scope is granted and the api:concurrent_access scope is not granted, Acumatica ERP manages the sessions of the application through tokens. The system uses a single session for each access granted to the client application. api:concurrent_access: Requests permission for the concurrent use of multiple types of web service APIs. If a user grants this scope to the application, the client application can access data in Acumatica ERP in concurrent mode. In this case, Acumatica ERP can maintain multiple sessions for the client application, managing session IDs through

70 Authorizing Client Applications to Work with Acumatica ERP 70 Parameter cookies. We recommend that the client application request this scope only if concurrent access is required for the client application. : The offline_access scope is not supported by the implicit flow. An example of the HTTP request is shown below. (Line breaks are for display purposes only.) response_type=token &client_id=4b1dfd71-c5ee-0b21-a6be-9a1f060a93bd &redirect_uri=http%3a%2f%2flocalhost%2fclientapp%2f &scope=api Authorizing a User in Acumatica ERP and Granting Access The authorization endpoint directs the user of the client application to the login page of Acumatica ERP, where the user should enter the credentials to log in to a company configured in the Acumatica ERP instance. : The user must log in to the company that was specified in the client_id URL parameter passed to the authorization endpoint. (This company is selected by default on the login page.) If the credentials are accepted by Acumatica ERP, the system displays the consent form, where the user can confirm that the application has access to the requested scopes. Only the scopes that were requested by the application are displayed on the consent form. Obtaining the Access Token Once the user grants access to the requested scopes, Acumatica ERP redirects the client application to the redirect_uri address, which was specified in the request, and adds the access token in the URL parameters. The redirect URL includes the following URL parameters. Parameter token_type The type of the access token, which is Bearer. access_token The access token. expires_in The period of time during which the access token is valid. : Refresh tokens are not supported by the implicit flow. Requesting Data with the Access Token The client application should include the access token in the Authorization header of each subsequent request to Acumatica ERP, as shown in the following HTTP example. GET /AcumaticaDB/entity/Default/ /SalesOrder/SO/ HTTP/1.1 Host: localhost Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc Logging Out from Acumatica ERP To prevent issues with licenses that limit the number of concurrent user sessions, the client application should directly call the logout method of the Acumatica ERP web services API when the application finishes its work with Acumatica ERP.

71 Authorizing Client Applications to Work with Acumatica ERP 71 Resource Owner Password Credentials Flow When you implement OAuth 2.0 authorization in a client application to make the application work with Acumatica ERP, you can use the resource owner password credentials flow. With the resource owner password credentials flow, the credentials (username and password) of the Acumatica ERP user are provided directly to the client application, which uses the credentials to obtain the access token. When the access token expires, the client application can request a new access token by providing a refresh token. The following diagram illustrates the resource owner password credentials flow, whose steps are described in the sections later in this topic. Figure: Resource owner password credentials flow For details on the OAuth 2.0 authorization mechanism, see the specification at html/rfc6749. Granting Permission to a Client Application Before an OAuth 2.0 client application can work with Acumatica ERP, you must register this application in Acumatica ERP and provide credentials to the application, as described in To Register a Client Application with the Resource Owner Password Flow. After the registration, you have the client ID and secret value of the client application. Important: According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the OAuth 2.0 client

72 Authorizing Client Applications to Work with Acumatica ERP 72 application can work with data in Acumatica ERP. For more information, see Setting Up an HTTPS Service in Web Server (IIS). When you are registering the client application, you have to be logged in to the company whose data the client application needs to access. Obtaining the Credentials of the Acumatica ERP User The client application should obtain the username and password of the applicable Acumatica ERP user, which can then be exchanged for an access token. Connecting to the Token Endpoint The client application connects to the token endpoint of Acumatica ERP by specifying the following URL and parameters in the request body: URL The client application can use one of the following options: If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is ERP instance URL>/identity/. In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint address is : We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization endpoint address changes. The client application can directly use the token endpoint address, which is <Acumatica ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint address is Parameters in the Request Body You specify the following parameters in the request body. Parameter grant_type The type of the OAuth 2.0 flow, which must be set to password for the resource owner password credentials flow. client_id The client ID that was assigned to the client application during the registration of the application in Acumatica ERP. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50EF710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID. client_secret The value of the secret that was created for the client application during the registration of the application in Acumatica ERP. username The username of an Acumatica ERP user.

73 Authorizing Client Applications to Work with Acumatica ERP 73 Parameter password The password for the specified username. scope The access scope that is requested by the client application. The scope can be a combination of the following values, delimited by spaces: api: Requests access to a web services API. If a user grants this scope to the application, the client application can work with either or both of the following types of the web services API: contract-based SOAP API or contract-based REST API. If this scope is granted and the api:concurrent_access scope is not granted, Acumatica ERP manages the sessions of the application through tokens. Acumatica ERP issues the first access token along with the session ID. If the client application requests a new access token by presenting a refresh token, Acumatica ERP reuses the session ID that was issued for the first access token issued with the refresh token. That is, the system uses a single session for each access granted to the client application. offline_access: Requests that a refresh token be granted. If a user grants this scope to the application, Acumatica ERP issues to the client application a refresh token along with the access token. (For information on issuing the access token, see Connecting to the Token Endpoint in this topic.) When the access token has expired, the client application can request a new access token by sending a request to the token endpoint and providing the refresh token. api:concurrent_access: Requests permission for the concurrent use of multiple types of web service APIs. If a user grants this scope to the application, the client application can access data in Acumatica ERP in concurrent mode. In this case, Acumatica ERP can maintain multiple sessions for the client application, managing session IDs through cookies. We recommend that the client application request this scope only if concurrent access is required for the client application. Receiving the Access Token Acumatica ERP verifies the provided application credentials and issues the access token, which the client application should provide with each data request to Acumatica ERP. During authentication in Acumatica ERP, if the user has granted to the client application the offline_access scope, Acumatica ERP issues the refresh token along with the access token. A successful response includes the following parameters in the response body. Parameter token_type The type of the access token, which is Bearer. access_token The access token. expires_in The period of time during which the access token is valid. refresh_token The refresh token. The parameter is returned only if the offline_access scope was granted.

74 Authorizing Client Applications to Work with Acumatica ERP 74 Requesting Data with the Access Token The client application should include the access token in the Authorization header of each subsequent request to Acumatica ERP, as shown in the following HTTP example. GET /AcumaticaDB/entity/Default/ /SalesOrder/SO/ HTTP/1.1 Host: localhost Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc Refreshing the Access Token The access token is valid for a specific period of time, which is specified in the response that returns the access token. When the access token expires, the client application can request a new access token by providing the refresh token to the token endpoint. To request a new access token, the client application should have the following URL and the following parameters specified in the request body: URL The client application can use one of the following options: If the client application supports OpenID Connect Discovery, the client application can use the discovery endpoint address, which is ERP instance URL>/identity/. In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint address is : We recommend that the client application use the discovery endpoint address, which eliminates the need to change the application if the authorization endpoint address changes. The client application can directly use the token endpoint address, which is <Acumatica ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client application is going to connect. For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint address is Parameters in the Request Body You specify the following parameters in the request body. Parameter grant_type The type of the request, which must be set to refresh_token for the request of the refresh token. client_id The client ID that was assigned to the client application during the registration of the application in Acumatica ERP. The client ID must have the format in which the ID was generated during the registration of the application. That is, the client ID must include an auto-generated string and the ID of the company, such as 88358B02-A48D-A50EF710-39C1636C30F6@MyCompany. The client application will have access to the data of the company specified in the client ID. client_secret The value of the secret that was created for the client application during the registration of the application in Acumatica ERP. refresh_token The refresh token that the client application received from the token endpoint along with the access token if the user granted the offline_access scope to the client application.

75 Authorizing Client Applications to Work with Acumatica ERP 75 Receiving the New Access Token Acumatica ERP verifies the provided application credentials and issues the new access token. The new refresh token is not issued. To request the access token once again, the client application should use the refresh token issued with the first access token. A successful response includes the following parameters in the response body. Parameter token_type The type of the access token, which is Bearer. access_token The access token. expires_in The period of time during which the access token is valid. Logging Out from Acumatica ERP To prevent issues with licenses that limit the number of concurrent user sessions, the client application should directly call the logout method of the Acumatica ERP web services API when the application finishes its work with Acumatica ERP. Comparison of the Flows The table below summarizes the characteristics of the authorization flows supported by Acumatica ERP. Characteristic Authorization Code Implicit Resource Owner Password Credentials The access token is returned from the authorization endpoint. No Yes No The access token is returned from the token endpoint. Yes No Yes The refresh token can be issued. Yes No Yes The client application has access to Acumatica ERP credentials (username and password). No No Yes The client application is authenticated in Acumatica ERP (that is, the client application provides the client ID and client secret). Yes No Yes To Register a Client Application You use the Connected Applications (SM303010) form to register an OAuth 2.0 or OpenID Connect client application. To register a client application in Acumatica ERP, you need to know the OAuth 2.0 flow that this application implements. For more information on the flows, see Authorization Code Flow, Implicit Flow, and Resource Owner Password Credentials Flow. Important: According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the OAuth 2.0 client application can work with data in Acumatica ERP. For more information, see Setting Up an HTTPS Service in Web Server (IIS).

76 Authorizing Client Applications to Work with Acumatica ERP 76 When you are registering the client application, you have to be logged in to the company whose data the client application needs to access. To Register a Client Application with the Authorization Code Flow 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Connected Applications. 2. In the Client Name box, type the name of the registered application. : Leave the Client ID box blank. The system will fill it in when you save your changes on the form. 3. In the OAuth 2.0 Flow box, select Authorization Code. 4. On the Secrets tab, do the following for each client secret you want to add: a. On the tab toolbar, click Add Shared Secret. The Add Shared Secret dialog box opens. b. In the box, type the description of the shared secret. c. Optional: In the Expires On (UTC) box, enter the date and time on which the secret expires. d. Copy and save the value that is displayed in the Value box. The client application should use this client secret for authentication in Acumatica ERP. Important: For security reasons, the value of the secret is displayed only once: when you create the secret by invoking this dialog box. e Click OK to save the secret and close the dialog box. On the Redirect URIs tab, do the following for each redirect URI you want to add: a. On the tab toolbar, click Add Row. b. In the Redirect URI column of the new row, type the exact redirect URI to which Acumatica ERP should redirect the client application after the client application has been authorized. The redirect URI must be absolute and must not have the fragment part (the part preceded with #). On the form toolbar, click Save. Notice that the client ID has been generated in the Client ID box. The client application should use this client ID along with the client secret for authentication in Acumatica ERP. To Register a Client Application with the Implicit Flow 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Connected Applications. 2. In the Client Name box, type the name of the registered application. : Leave the Client ID box blank. The system will fill it in when you save your changes on the form. 3. In the OAuth 2.0 Flow box, select Implicit. 4. On the Redirect URIs tab, do the following for each redirect URI you want to add: a. On the tab toolbar, click Add Row. b. In the Redirect URI column of the new row, type the exact redirect URI to which Acumatica ERP should redirect the client application after the client application has been authorized. The redirect URI must be absolute and must not have the fragment part (the part preceded with #).

77 Authorizing Client Applications to Work with Acumatica ERP On the form toolbar, click Save. Notice that the client ID has been generated in the Client ID box. You should use this client ID to connect the client application to the authorization endpoint of Acumatica ERP. To Register a Client Application with the Resource Owner Password Flow 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Connected Applications. 2. In the Client Name box, type the name of the registered application. : Leave the Client ID box blank. The system will fill it in when you save your changes on the form. 3. In the OAuth 2.0 Flow box, select Resource Owner Password Credentials. 4. On the Secrets tab, do the following for each client secret you want to add: a. On the tab toolbar, click Add Shared Secret. The Add Shared Secret dialog box opens. b. In the box, type the description of the shared secret. c. Optional: In the Expires On (UTC) box, enter the date and time on which the secret expires. d. Copy and save the value that is displayed in the Value box. The client application should use this client secret for authentication in Acumatica ERP. Important: For security reasons, the value of the secret is displayed only once: when you create the secret by invoking this dialog box. e. 5. Click OK to save the secret and close the dialog box. On the form toolbar, click Save. Notice that the client ID has been generated in the Client ID box. The client application should use this client ID along with the client secret for authentication in Acumatica ERP. To Revoke the Access of a Connected Application To revoke the access of an OAuth 2.0 or OpenID Connect client application, you use either the Connected Applications (SM303010) form or the User Profile (SM203010) form. On the Connected Applications form, you can revoke the access of any application registered in the current company. On this form, you revoke all access granted to the application. On the User Profile form, you can revoke the access of any application to which you (that is, the user account to which you are logged in) have granted access. Any access granted to this application by other users remains unchanged. To Revoke All Access of a Client Application 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Connected Applications. 2. In the Client ID box, select the application whose access you want to revoke. 3. On the form toolbar, click Revoke Access. 4. In the message box that opens, click OK to confirm that you want to revoke the access of the application. : After you have confirmed that you want to revoke access, all access tokens are removed from the Acumatica ERP database, and these tokens cannot be used to access data in Acumatica

78 Authorizing Client Applications to Work with Acumatica ERP 78 ERP. However, the client secrets remain valid until their expiration dates (if applicable), and the application can use these secrets to request a new access token. To Revoke Access You Have Provided 1. In the info area (in the upper-right corner of the screen), click your user name, and then click User Profile. 2. On the toolbar of the User Profile form, which opens, click View Connected Applications. The list of applications to which you have granted access is displayed on the Client Application Permissions webpage. 3. For the application whose access you want to revoke, click Revoke Access. : After you have revoked access, the access tokens that were created when you granted access to the application are removed from the Acumatica ERP database, and these tokens cannot be used to access data in Acumatica ERP. However, the client secrets remain valid until their expiration dates (if applicable), and the application can use these secrets to request a new access token.

79 Configuring the Contract-Based SOAP and REST API 79 Configuring the Contract-Based SOAP and REST API Acumatica ERP provides web services for integration with external systems. Through the web services of Acumatica ERP, external systems can get data records from Acumatica ERP, process these records, and save new or updated records to Acumatica ERP. To access these web services, you can use the contract-based SOAP application programming interface (API), the contract-based representational state transfer (REST) API, and the screen-based SOAP API. In this chapter, you will find the main concepts that are related to the contract-based SOAP API and the contract-based REST API. In This Chapter Contract-Based Web Services API To Create a Custom Endpoint Endpoints and Contracts To Extend an Existing Endpoint API Entities, Fields, and Actions To Validate an Endpoint Custom Fields Custom Endpoints and Endpoint Extensions Naming Rules for Endpoints Comparison of Contract Versions Contract-Based Web Services API Contract-based web services API operates with business logic objects that do not depend on Acumatica ERP forms and their properties and methods. (In this context, contract-based means based on the object model the web services API provides.) Each contract of the web service is fixed and does not change based on system customization, localization, or any other changes made to Acumatica ERP. For example, suppose that the contract of the web service contains the definition of the CustomerID field, which accesses the Customer ID element on the Customers (AR303000) form. If you have changed the name of the Customer ID element to Customer Identifier in a customization project, the contract of the web service remains fully functional and does not require update; also, your application requires no further modifications. You can access the Customer Identifier element on the form through the same CustomerID field. You can work with the contract-based web services API through either the SOAP interface or the REST interface. To use the contract-based web services API in your application, first of all, you should decide which endpoint to use. You can find more information on the endpoints and their contracts in Endpoints and Contracts. After that, to use the contract-based SOAP API in your application, you should obtain the WSDL description of the contract of this endpoint, import the WSDL file into your development environment (as described in To Configure the Client Application), and start developing your application. You can find the description of the SOAP API methods in Contract-Based SOAP API Reference. You can find examples of how to use the contract-based SOAP API in the I210 Contract-Based Web Services training course. You can find information on the REST API in Working with the Contract-Based REST API.

80 Configuring the Contract-Based SOAP and REST API 80 Endpoints and Contracts You can access the contract-based SOAP and REST API through endpoints that you can configure on the Web Service Endpoints (SM207060) form. Endpoints and Contracts An endpoint is an entry point to the Acumatica ERP web services. For each endpoint that a web service API provides, a contract of the endpoint defines the entities, with their actions and fields, that are available through the endpoint and the methods that you can use to work with these entities. The endpoint is identified by the URL that you use to access the web services API. You can see the name and version of an endpoint in its URL. For example, the endpoint AcumaticaDB/entity/Default/ ?wsdl has the version and the name Default. The version of an endpoint defines the list of entities, with their actions and fields you can work with through this endpoint. The contract of an endpoint is identified by its version. The version of a contract defines the list of methods for working with entities that you can use when working with Acumatica ERP through the endpoint with this version of the contract. For the difference between the contract versions, see Comparison of Contract Versions. System and Custom Endpoints You can use two types of endpoints to access the web services: System endpoint: The system endpoints are precofigured in the system and have the Default name. Each of these endpoints has a predefined contract, which includes the API that is preconfigured in the system. You cannot change the contract of a system endpoint. If the API that is available in the contract of a system endpoint is sufficient for the requirements of your application, you should use the system endpoint for accessing Acumatica ERP web services. You can use the same system endpoint in future versions of Acumatica ERP. For example, if you use the system endpoint with Version and Contract Version 1 to access Acumatica ERP 5.3, you can use the same endpoint to access future versions of Acumatica ERP. Custom endpoint: By default, there are no custom endpoints in the system. If the API provided by the system endpoint is not sufficient for the requirements of your application, you can create a custom endpoint. You can configure the contract of a custom endpoint by adding the needed elements of the API to the contract. If you need to use the same custom endpoint in future versions of Acumatica ERP, you should maintain it in future versions. The following diagram provides an example of multiple endpoints configured in the system. The diagram shows two system endpoints with Contract Versions 1 and 2 and two custom endpoints with the names CustomEndpoint1 and CustomEndpoint2.

81 Configuring the Contract-Based SOAP and REST API 81 Figure: Contract-based web services API Entities, Fields, and Actions The contract of an endpoint defines the following elements of the contract-based web services API: Entities: An entity corresponds to a business logic object that you are going to work with. For example, the contract of a system endpoint includes the Warehouse entity, which represents a warehouse and holds the data related to the warehouse. This entity is associated with the Warehouses (IN204000) form. For a custom endpoint, if you are going to use an entity to transfer data to or from Acumatica ERP, you should associate this entity with a particular Acumatica ERP form. For example, you can create a Vendor entity, which represents a vendor. This entity is associated with the Vendors (AP303000) form. Fields: The fields of an entity correspond to the parameters of a business logic object. For example, the Warehouse entity that is available through the system endpoint has the and WarehouseID fields, among others. In the contract, these fields are mapped to the and the Warehouse ID elements of the Summary area of the Warehouses form. For a custom endpoint, if you need to connect the field with a particular element on an Acumatica ERP form, you should map the field to this element. For example, if you have created the Vendor entity, which designates a vendor, you can add the field VendorID to the entity and connect this field with the Vendor ID element of the Summary area of the Vendors form. Actions: The actions of an entity correspond to the actions that can be applied to a business logic object. For example, the TransferOrder entity, which is available through the system endpoint, has the ReleaseTransferOrder action. This action corresponds to the Release button on the form toolbar of the Transfers (IN304000) form. For a custom endpoint, if you need to use an Acumatica ERP action, you should add this action to the contract of the custom endpoint with the needed parameters. For example, suppose you want to add an action that changes the customer ID of an existing customer, you can add the action

82 Configuring the Contract-Based SOAP and REST API 82 ChangeID and map it to the Change ID action, which is available on the Customers form. The new action should have one parameter, which specifies the new ID of a customer as the Change ID action has. When you add a new entity to a contract, you should specify the type of the entity, which can be one of the following: Top-Level: Entities of this type are the main entities of the contract. A top-level entity usually corresponds to an Acumatica ERP form. For example, the Warehouse entity of the contract of the system endpoint is a top-level entity that corresponds to the Warehouses form. Detail: Detail entities correspond 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 Document Details tab of the Sales Orders (SO301000) form, as shown in the following screenshot. Figure: Detail entity Linked: Linked entities are supplementary entities of a contract. 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 such 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, as shown in the following screenshot.

83 Configuring the Contract-Based SOAP and REST API 83 Figure: Linked entity Custom Fields By using Version 2 of the system contract of the contract-based web services application programming interface (API), you can work with the values of the custom fields that are not included in the entity definition. That is, custom fields can correspond to both the predefined elements on an Acumatica ERP form that are not included in the entity definition and the elements that were added to the Acumatica ERP form in a customization project. : In Version 1 of the system contract, you can work with the values of the elements that were added to an Acumatica ERP form in a customization project, but not with the predefined elements on an Acumatica ERP form that are not included in the entity definition. To work with the needed custom field, you need to know the name of the data view that contains the corresponding custom element and the name of the field, which are described in detail below. Field Name and View Name A field name is the internal name of a particular element of an Acumatica ERP form. A view name is the name of the data view to which a particular element belongs. For example, the Post Class ID element of the Stock Items (IN202500) form has the PostClassID field name and belong to the ItemSettings data view. To find out the field name and view name, 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,

84 Configuring the Contract-Based SOAP and REST API 84 which opens, you find the field name in the Data Field element and the view name in the View Name element, as shown in the following screenshot. Figure: Field name and view name In the contract-based SOAP API, you can also find out the field name and the view name in code by using the GetCustomFieldSchema() method. For details on the method, see GetCustomFieldSchema() Method. In the contract-based REST API, you can find out the field name and the view name through the special URL. For details on the URL and the HTTP method, see Retrieval of the Schema of Custom Fields. Use of Custom Fields For details on working with custom elements through the contract-based SOAP API, see CustomFields Property (Contract Version 2), CustomFields Property (Contract Version 1). For details on retrieving the values of custom fields by using the contract-based representational state transfer (REST) API, see the description of the $custom parameter in Parameters for Retrieving Records. For details on specifying the values of custom fields, see Representation of a Record in JSON Format. Custom Endpoints and Endpoint Extensions If the API provided by the system endpoint of Acumatica ERP is not sufficient for the requirements of your application, you can create a custom endpoint from scratch or by extending an existing endpoint. An Extension of an Existing Endpoint If you are creating an endpoint as an extension of an existing endpoint, for the API elements that were inherited from the base endpoint, you cannot edit the names and types of the entities and fields, and the names, types, and parameters of the actions. In the contract of the new endpoint, you can add new top-level entities, new fields or entities to any entity, and new actions. Then you can use both the API that you added to the contract of the endpoint and the API of the base endpoint in your application. For information on how to extend an existing endpoint, see To Extend an Existing Endpoint.

85 Configuring the Contract-Based SOAP and REST API 85 The new endpoint that was created as an extension of an existing endpoint has the version of the contract of the base endpoint; that is, the SOAP API methods for working with entities are the same for the base endpoint and the new endpoint. See Contract-Based SOAP API Reference for the description of methods of the needed contract version. An Endpoint Created from Scratch If you are creating an endpoint from scratch, you should add the needed elements of the API to the contract. Then you can use these API elements in your application. For information on how to create an endpoint from scratch, see To Create a Custom Endpoint. The new endpoint that is created from scratch always has the latest version of the contract. For the description of the SOAP API methods for working with entities that are available in the latest version of the contract, see Contract-Based SOAP API Reference. Naming Rules for Endpoints When you create a custom endpoint on the Web Service Endpoints (SM207060) form (either from scratch or by extending a system endpoint), for the names of the entities, fields, actions, and action parameters of the endpoint, and the endpoint name and version, you should make sure to adhere to the following rules: The name of the endpoint can contain only English letters, digits, underscores, and periods, and cannot start with a digit. The version of the endpoint can contain only English letters, digits, underscores, and periods. The name of the entity, field, action, or action parameter can contain only English letters, digits, and underscores, and cannot start with a digit. The name of the field cannot match any of the following reserved names: ID RowNumber Note Delete CustomFields ReturnBehavior Entity Action The name of the field must be unique among the names of the fields of the entity. The name of the parameter must be unique among the names of the parameters of the action. The name of the entity or action must be unique among the names of the entities and actions of the endpoint. The system checks whether the names used in the endpoint satisfy these rules each time you enter the name of a new entity, field, action, or action parameter. You can also validate the endpoint manually, as described in To Validate an Endpoint.

86 Configuring the Contract-Based SOAP and REST API 86 Comparison of Contract Versions Acumatica ERP 2017 R2 supports three versions of system contracts. In this topic, you can learn the main differences between the contract versions. Comparison of Contract Versions Characteristic Contract Version 1 Contract Version 2 Contract Version 3 The SOAP API is supported for the endpoints with this contract version. Yes Yes Yes The REST API is supported for the endpoints with this contract version. No Yes Yes You can specify particular fields of the entity to be returned from the system. No Yes Yes By default, the system returns all fields of the entity (including fields of the linked and detail entities defined within the entity). Yes For the SOAP API: Yes No By default, the system returns only the fields of the entity itself (without the fields of the linked and detail entities defined within the entity). No Through the endpoint, you can work with the elements that were added to the Acumatica ERP form in a customization project. Yes Yes Yes Through the endpoint, you can work with the predefined elements on an Acumatica ERP form that are not included in the entity definition. No Yes Yes When optimization for speed of the retrieval of the list of records fails, the system behaves as follows. The system retrieves data in an unoptimized way (slow). The system retrieves data in an unoptimized way (slow). The system returns an error. Custom endpoints created from scratch have this contract version. No No Yes The system endpoint that has this contract version is included in Acumatica ERP. Yes (Endpoint Yes (Endpoint Yes (Endpoint Version Version Version default/ )default/ )default/ ) For the REST API: No For the SOAP API: No Yes For the REST API: Yes To Create a Custom Endpoint You use the Web Service Endpoints (SM207060) form to create a custom endpoint. If you need to use a custom endpoint, you can either create an endpoint from scratch or extend an existing endpoint with the needed API. This procedure describes how to create a custom endpoint from scratch. To learn how to extend an existing endpoint, see To Extend an Existing Endpoint.

87 Configuring the Contract-Based SOAP and REST API 87 To Create an Endpoint from Scratch 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Web Service Endpoints. 2. In the Endpoint Name box, type the name of the new endpoint. : The name of the endpoint can contain only English characters and digits. 3. In the Endpoint Version box, type the version of the new endpoint. 4. Add the needed entities, fields, and actions to the contract of the created endpoint, as described in the sections below. 5. Click Save on the form toolbar. To Add a Top-Level Entity to the Contract of the Endpoint 1. In the Endpoint Name box, select the name of the endpoint to which you want to add an entity. 2. In the Endpoint Version box, select the version of the endpoint to which you want to add an entity. 3. In the left pane, select the Endpoint node. 4. On the toolbar of the left pane, click Insert, and in the Create Entity dialog box, specify the values as follows, and click OK: a. In the Object Name box, type the name of the entity. This is the name of the API object that you will use in the code of your application to work with the entity. : The name of the entity can contain only English characters and digits. b. 5. In the Screen ID lookup box, select the form to which the entity should correspond. Add the needed fields, actions, or nested entities to the entity, as described in the sections below. To Add a Linked or Detail Entity to Another Entity 1. In the Endpoint Name box, select the name of the endpoint to which you want to add an entity. 2. In the Endpoint Version box, select the version of the endpoint to which you want to add an entity. 3. In the left pane, select the entity node to which you want to add a linked or detail entity. 4. On the toolbar of the left pane, click Insert. 5. In the Field Name box of the Create Entity dialog box, which opens, type the name of the field that should be used to access the nested entity, and specify the values of other elements in one of the following ways: If you want to insert an entity that already exists in the contract, select the Use Existing Entity check box, and select the needed entity in the Entity Type box. If you want to insert a new entity, in the Object Name box, type the name of the entity, and in the Object Type box, select the type of the entity: Top-Level, Linked, or Detail. If you have selected the top-level entity to be inserted, in the Screen ID lookup box, specify the form to which the entity should correspond. : The name of the entity or field can contain only English characters and digits.

88 Configuring the Contract-Based SOAP and REST API Click OK. The new entity appears in the contract. 7. Add fields to the created entity, as described in the following section. To Add Fields to an Entity 1. In the Endpoint Name box, select the name of the endpoint to which you want to add an entity. 2. In the Endpoint Version box, select the version of the endpoint to which you want to add an entity. 3. In the left pane, select the entity node to which you want to add fields. 4. On the Fields tab of the right pane, do one of the following: Click Populate on the tab toolbar. In the Populate Fields dialog box, select the Acumatica ERP object whose fields you want to include in the entity and the fields that you want to include, and click OK. The selected fields are added to the contract. Click Add Row on the tab toolbar; then type the name of the new field in the Field Name column of the added row, select the Acumatica ERP object whose field you want to include in the entity in the Mapped Object column, and select the field that you want to include in the Mapped Field column. : For some fields to be included in the entity, the corresponding Acumatica ERP feature or features must be enabled on the Enable/Disable Features (CS100000) form. For information on Acumatica ERP basic functionality and add-on features, see Overview of the Acumatica ERP Features. 5. Click Save on the form toolbar. To Add an Action to an Entity 1. In the Endpoint Name box, select the name of the endpoint to which you want to add an entity. 2. In the Endpoint Version box, select the version of the endpoint to which you want to add an entity. 3. On the left pane, select the Actions node in the needed entity. 4. On the toolbar, click Insert. 5. In the Create Action dialog box, which opens, select the needed Acumatica ERP action, type the name that should be used to invoke this action through the API, and click OK. The new action is added to the contract. : The name of the action can contain only English characters and digits. 6. Click Save on the form toolbar. To Extend an Existing Endpoint You use the Web Service Endpoints (SM207060) form to create an endpoint as an extension of an existing 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 you also need some additional entities, fields, and actions in the contract. For example, the contract of the system endpoint with the name Default and Version contains the Address entity, which includes the following fields: AddressLine1, AddressLine2, City, Country, PostalCode, and State. Suppose that you want to add the new GPSCoordinates field to the Address entity of the contract and use it with other API of the contract. You cannot edit the contract of the system endpoint; instead, you should create an endpoint that is

89 Configuring the Contract-Based SOAP and REST API 89 based on this system endpoint, and add the new GPSCoordinates field to the Address entity of the contract of the new endpoint. This procedure describes how to create an endpoint that is based on an existing endpoint. To Extend an Existing Endpoint 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Web Service Endpoints. 2. Select the endpoint that you want the new endpoint to be based on as follows: a. Select the name of the base endpoint in the Endpoint Name box. b. Select the version of the base endpoint in the Endpoint Version box. 3. Click Extend Endpoint on the form toolbar. 4. In the Extend Current Endpoint dialog box, which opens, make sure the correct name and version of the base endpoint are specified in the Base Endpoint Name and Base Endpoint Version boxes. Specify the name of the new endpoint in the Endpoint Name box and the version of the new endpoint in the Endpoint Version box and click OK. : The name of the endpoint can contain only English characters and digits. The new endpoint with the name and version you specify appears on the form. On the left pane of the form, you can see the list of entities that were inherited from the base endpoint. 5. Add the needed entities, fields, and actions to the contract of the created endpoint, as described in To Create a Custom Endpoint, or extend the entities inherited from the base endpoint, as described in To Extend an Existing Entity. 6. Click Save on the form toolbar. To Extend an Existing Entity 1. Select the extended endpoint in which you want to extend an entity inherited from the base endpoint as follows: a. In the Endpoint Name box, select the name of the extended endpoint. b. In the Endpoint Version box, select the version of the extended endpoint. 2. In the left pane, select the entity inherited from the base endpoint to which you want to add new fields. 3. On the toolbar of the Fields tab in the right pane, click Extend Endpoint. 4. Use the Add Row, Delete Row, and Populate buttons, which have become available on the tab toolbar, to add and delete fields of the entity. For more details, see To Add Fields to an Entity. 5. Click Save on the form toolbar. To Validate an Endpoint You use the Web Service Endpoints (SM207060) form to validate an endpoint, an entity, or an action. During this validation, the system makes sure the following criteria are met for the elements of the endpoint, entity, or action: The names of the elements satisfy the naming rules. For details on these rules, see Naming Rules for Endpoints.

90 Configuring the Contract-Based SOAP and REST API 90 The elements are mapped to objects, fields, and actions that exist in the system. The validation of the name of a new entity, field, action, or action parameter is performed automatically once you have entered the name on the form. You can validate an endpoint, entity, or action manually, as described in this topic. To Validate an Endpoint 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Web Service Endpoints. 2. Select the endpoint that you want to validate as follows: 3. a. In the Endpoint Name box, select the name of the endpoint. b. In the Endpoint Version box, select the version of the endpoint. On the form toolbar, click Validate Endpoint. The long-running validation operation starts. Once the validation is finished, the system displays a message with results of the validation. If the validation has failed, the error message contains the names of all fields that caused the error. 4. If any errors occur, correct the endpoint accordingly. To Validate an Entity 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Web Service Endpoints. 2. Select the endpoint that contains the entity that you want to validate as follows: a. In the Endpoint Name box, select the name of the endpoint. b. In the Endpoint Version box, select the version of the endpoint. 3. In the left pane, click the entity that you want to validate. 4. On the toolbar of the Fields tab of the right pane, click Validate Entity. Once the validation is finished, the system displays a message with results of the validation. If the validation has failed, the error message contains the names of all fields that caused the error. 5. If any errors occur, correct the entity accordingly. To Validate an Action 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Web Service Endpoints. 2. Select the endpoint that contains the action that you want to validate as follows: a. In the Endpoint Name box, select the name of the endpoint. b. In the Endpoint Version box, select the version of the endpoint. 3. In the left pane, click the action that you want to validate. 4. On the toolbar of the Parameters tab of the right pane, click Validate Action. Once the validation is finished, the system displays a message with results of the validation. If the validation has failed, the error message contains the names of all fields that caused the error. 5. If any errors occur, correct the action accordingly.

91 Working with the Contract-Based SOAP API 91 Working with the Contract-Based SOAP API The contract-based SOAP application programming interface (API) of Acumatica ERP provides the SOAP interface of the Acumatica ERP contract-based web services through which external systems can get data records from Acumatica ERP, process these records, and save new or updated records to Acumatica ERP. This chapter includes the topics that are specific for the contract-based SOAP API. For general information on the contract-based web services, see Configuring the Contract-Based SOAP and REST API. You can find examples of how to use the contract-based SOAP API in the I210 Contract-Based Web Services training course. For the API reference, see Contract-Based SOAP API Reference. In This Chapter Multi-Language Fields To Configure the Client Application Multi-Language Fields For some text boxes on Acumatica ERP forms, users can type values in multiple languages if multiple locales are configured in Acumatica ERP. For example, if your Acumatica ERP instance has English and French locales activated and multilingual user input configured, you can specify the value of the box on the Stock Items (IN202500) form in English and French. For the list of elements that support multiple languages, see Boxes that Have Multi-Language Support. For details on how to turn on multilingual user input, see Enabling Multilingual User Input. Specifying Localized Values of a Multi-Language Field When you need to specify localized values of a text box by using the contract-based SOAP API, you specify the value of the field that corresponds to the box as a string in JSON format with the localized values. In this string, you use the two-letter ISO code of the language with which the value should be associated. In the example that is mentioned at the beginning of the topic, if you need to specify values in English and French in the box on the Stock Items form, you specify the value of the field of the StockItem entity in the following format: [en:english description,fr:french description], as shown in the following code fragment. public static void CreateStockItem(DefaultSoapClient soapclient) //Specify the values of the new stock item StockItem stockitemtobecreated = new StockItem InventoryID = new StringValue Value = "BASESERV", = new StringValue Value = "[en:item,fr:pièce]", ItemClass = new StringValue Value = "STOCKITEM", ; //Create a stock item with the specified values StockItem newstockitem = (StockItem)soapClient.Put(stockItemToBeCreated); : In the JSON-formatted string, you should specify the actual values of the field in all languages that are configured for multilingual user input. If you specify the values of the field in particular languages, the values of the field in other languages configured for multilingual user input become empty. For example, suppose that in your instance of Acumatica ERP, multi-language fields can have values in English and

92 Working with the Contract-Based SOAP API 92 French. If you pass the value of a field in the following format [en:english description], the French value of the field becomes empty. If you specify the value of a multi-language field as plain text, this text is saved as the value of the corresponding box in the current language of Acumatica ERP (that is, the language that you specified when you logged in to Acumatica ERP). For details on how to specify the language on login through the contract-based SOAP API, see Login() Method. Retrieving Localized Values of a Multi-Language Field If you need to retrieve localized values of a text box that supports multiple input languages, you retrieve the value of a special custom field that contains all localized values of the text box and has the Translations suffix in its field name. To find out the field name and the view name of the needed custom field with localized values, you find out the field name and the view name of the multi-language text box and append Translations to the field name. (For details on how to find out the field name and the view name of an element on the form, see Custom Fields.) For example, the multi-language box on the Stock Items form has the Descr field name and the Item view name; therefore, the custom field that contains the localized descriptions of a stock item has the DescrTranslations field name and the Item view name. The following code shows how to retrieve the localized values of the element of the Stock Items form. (The code below uses Contract Version 2.) public static void ExportStockItem(DefaultSoapClient soapclient) StockItem stockitem = new StockItem InventoryID = new StringValue Value = "BASESERV", //Specify the localized values to be returned CustomFields = new[] new CustomStringField fieldname = "DescrTranslations", viewname = "Item", Value = new StringReturn(), ; //Retrieve the stock item record StockItem stockitemtoretrieve = (StockItem)client.Get(stockItem); The returned value of a Translations custom field is a string in JSON format with the available localized values of the field. The language to which the value belongs is identified by the two-letter ISO code of the language. For example, suppose that the element of the Stock Items form has the value Item in English and Pièce in French. In this case, the value of the DescrTranslations custom field, which corresponds to the element, is the following string: [en:item, fr:pièce]. To Configure the Client Application In this topic, you will learn how to import the WSDL description of the Acumatica ERP web services into a Visual Studio project. Do the following: 1. In Visual Studio, create a new application. : To create a new application, select File > New > Project in the menu. In the New Project dialog box that appears, select the needed template, specify the name and location of the application, and click OK.

93 Working with the Contract-Based SOAP API Add to the project a reference to the Acumatica ERP web service as follows: a. In the menu, select Project > Add Service Reference. b. In the Address box of the Add Service Reference dialog box, which appears, specify the URL of the needed endpoint (see item 1 in the following screenshot). : To get the URL of the service, on the Web Service Endpoints (SM207060) form, select the name of the endpoint contract in the Endpoint Name box and the version of the contract in the Endpoint Version box, click View Endpoint Service > WSDL on the form toolbar, and copy the URL from the address line in the browser for the page that opens. For example, the URL of the Default endpoint of the version is localhost/webserviceapitest/entity/default/ ?wsdl. c. Click Go (item 2 in the screenshot) to make Visual Studio connect to the web service. : If your Acumatica ERP website uses a self-signed certificate, Visual Studio displays security alert windows with warnings on the certificate. Click Yes in these windows to proceed. d. In the Namespace box, type the name of the namespace for the web service classes generated by Visual Studio based on the WSDL description of the service, such as Default (3). e. Click OK (4) to add to the project the reference to the specified service. Figure: Add Service Reference dialog box Visual Studio adds to the project the service reference in the Service References folder, as shown in the following screenshot.

94 Working with the Contract-Based SOAP API 94 Figure: Solution Explorer 3. Modify the app.config file of the project as shown below. Cookies are required for the client application to log in to Acumatica ERP. The security mode Transport indicates that API calls to Acumatica ERP will be made through HTTPS (which is the recommended approach). <?xml version="1.0" encoding="utf-8"?> <configuration>... <system.servicemodel> <bindings> <basichttpbinding> <binding name="acumatica" allowcookies="true" maxreceivedmessagesize=" "> <security mode="transport" /> </binding>... </basichttpbinding> </bindings> <client> <endpoint address= " binding="basichttpbinding" bindingconfiguration="acumatica" contract="default.defaultsoap" name="defaultsoap" /> </client> </system.servicemodel> </configuration> : You can make API calls to Acumatica ERP through HTTP if requirements to your application do not include secure data transfer between the application and Acumatica ERP. If you do not need to use HTTPS, you can use the configuration shown below in the app.config file. Notice that you use the HTTP address of the endpoint instead of HTTPS address. The security tag is not used for HTTP connection. <?xml version="1.0" encoding="utf-8"?> <configuration>... <system.servicemodel> <bindings> <basichttpbinding> <binding name="acumatica" allowcookies="true" maxreceivedmessagesize=" "> </binding> </basichttpbinding> </bindings> <client> <endpoint address= "

95 Working with the Contract-Based SOAP API 95 binding="basichttpbinding" bindingconfiguration="acumatica" contract="default.defaultsoap" name="defaultsoap" /> </client> </system.servicemodel> </configuration> 4. Rebuild the project. You have created a Visual Studio application and added to it the reference to the Acumatica ERP web service. Now you can start developing your application. For the description of the SOAP API methods, see Contract-Based SOAP API Reference.

96 Working with the Contract-Based REST API 96 Working with the Contract-Based REST API The contract-based representational state transfer (REST) application programming interface (API) of Acumatica ERP provides the REST interface of the Acumatica ERP contract-based web services through which external systems can get data records from Acumatica ERP, process these records, and save new or updated records to Acumatica ERP. This chapter includes the topics that are specific to the contract-based REST API. For general information on the contract-based web services, see Configuring the Contract-Based SOAP and REST API. For the API reference, see Contract-Based REST API Reference. In This Chapter Representation of a Record in JSON Format Login to the Service Logout from the Service Creation of a Record Update of a Record Retrieval of a Record by Key Fields Retrieval of a Record by ID Retrieval of Records by Conditions Retrieval of Data from an Inquiry Form Parameters for Retrieving Records Removal of a Record Execution of an Action Attachment of a File to a Record Retrieval of a File Attached to a Record Retrieval of the Schema of Custom Fields Multi-Language Fields Representation of a Record in JSON Format By using the contract-based REST API, you obtain existing records from Acumatica ERP, create new records, update, and delete them. You work with the records in Acumatica ERP by using the entities that are defined in the contract of the endpoint that you use to access the service. You pass records to and receive them from the contract-based REST API in JavaScript object notation (JSON) format. JSON is a text format for transmitting data objects that consist of key-value pairs. To represent a record in JSON format, you use the rules that are described in the following sections. You do not need to specify the values of all fields of an entity; you can specify the values of only the needed fields.

97 Working with the Contract-Based REST API 97 System Fields You specify the value of a system field (such as ID, RowNumber, and Note) of an entity in the following format. <Field name> : <Value> For example, if you need to specify the note Imported for an entity, you use the following string. "Note" : "Imported" General Fields You specify the value of a general field (that is, a field that is not a system field) of an entity in the following format. <Field name> : value : <Value> For example, if you need to specify JOHNGOOD as the customer ID of a customer record, you use the following string. "CustomerID" : value : "JOHNGOOD" Linked Entities You specify the values of the fields of a linked entity in the following format. <Field name> : <List of fields of the linked entity with values For example, if you need to specify the values of an address and the address of a customer main contact, you use the following string. "MainContact" : " " : value : "demo@gmail.com", "Address" : "AddressLine1" : value : "4030 Lake Washington Blvd NE", "AddressLine2" : value : "Suite 100", "City" : value : "Kirkland", "State" : value : "WA", "PostalCode" : value : "98033" Detail Entities You specify the values of the fields of a detail entity in the following format. <Field name> : [ <List of fields of the detail entity with the values, <List of fields of the detail entity with the values>, ]

98 Working with the Contract-Based REST API 98 For example, if you need to specify the values of two detail lines of a sales order, you use the following string. "Details" : [ "InventoryID" : value: "AALEGO500", "Quantity" : value: 10, "UOM" : value: "PIECE",, "InventoryID" : value: "CONGRILL", "Quantity" : value: 1, "UOM" : value: "PIECE", ] Custom Fields You specify the values of the custom fields (that is, the fields that are not included in the contract of the endpoint) in the following format. "custom" : <View name> : <Field name> : "type" : <value>, "value" : <value> You use this block in the JSON representation of the entity (top-level, detail, or linked) that contains this custom field. : For details on how to find out the field name and the name of the data view, see Custom Fields. For example, suppose that you added the Personal ID element to the Main Contact area of the Customers (AR303000) form in a customization project. The Contact entity, which is available through the MainContact property of the Customer entity, contains the Personal ID custom element. This element has the UsrPersonalID field name and belongs to the DefContact data view. The type of the element depends on the contract version (in Contract Version 2, String; in Contract Version 3, CustomStringField). Therefore, to specify the value AB of the Personal ID custom element for the customer with ID JOHNGOOD through the REST API, you use one of the following strings depending on the contract version of the endpoint: For Contract Version 2 "CustomerID" : value : "JOHNGOOD", "MainContact" : "custom" : "DefContact" : "UsrPersonalID" : "type" : "String", "value" : "AB123456"

99 Working with the Contract-Based REST API 99 For Contract Version 3 "CustomerID" : value : "JOHNGOOD", "MainContact" : "custom" : "DefContact" : "UsrPersonalID" : "type" : "CustomStringField", "value" : "AB123456" Login to the Service Each time your application starts work with the Acumatica ERP contract-based REST service, you have to log in to Acumatica ERP. To log in to Acumatica ERP, you access the needed URL address with the POST HTTP method and pass the credentials in the request body. See details on the URL, parameters, HTTP method, and response format in the following sections. URL When you need to log in to Acumatica ERP, you use the following URL. ERP URL>/entity/auth/login You replace <Acumatica ERP URL> with the URL of your Acumatica ERP instance. For example, suppose that you want to log in to a local Acumatica ERP instance with the name AcumaticaDB. You should use the following URL: auth/login. Parameters You use no parameters when you log in to Acumatica ERP. HTTP Method You use the POST HTTP method and pass the credentials for accessing Acumatica ERP in JSON format, as shown in the following example. "name" : "admin", "password" : "123", "company" : "MyCompany", "branch" : "MYSTORE", "locale" : "en-us"

100 Working with the Contract-Based REST API 100 Response The response of a successful method call is 204 No Content. Example The following code shows an example of a class that implements a login to Acumatica ERP through the REST application programming interface (API). public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch, string locale) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; //Log in to Acumatica ERP _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch, locale = locale ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); The following code logs in to Acumatica ERP when an instance of the RestService class, which is defined in the code fragment above, is created. RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch, Properties.Settings.Default.Locale );

101 Working with the Contract-Based REST API 101 Logout from the Service Each time your application finishes work with the Acumatica ERP contract-based REST service, you have to log out from Acumatica ERP. To log out from Acumatica ERP, you access the needed URL address with the POST HTTP method and pass the credentials in the request body. See the following sections for details on the URL, parameters, HTTP method, and response format. URL When you need to log out from Acumatica ERP, you use the following URL. ERP URL>/entity/auth/logout You replace <Acumatica ERP URL> with the URL of your Acumatica ERP instance. For example, suppose that you want to log out from a local Acumatica ERP instance with the name AcumaticaDB. You should use the following URL: auth/logout. Parameters You use no parameters when you log out from Acumatica ERP. HTTP Method You use the POST HTTP method to log out from Acumatica ERP. Response The response of a successful method call is 204 No Content. Example The following code shows an example of a class that implements a logout from Acumatica ERP through the REST application programming interface (API). Logout is performed each time an instance of the RestService class is released. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ;

102 Working with the Contract-Based REST API 102 _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch ).Result.EnsureSuccessStatusCode(); //Log out from Acumatica ERP void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); Creation of a Record When you need to create a record by using the contract-based REST API, you access the needed URL address with the PUT HTTP method and pass the record representation in JSON format in the request body. See the following sections for details on the URL, parameters, HTTP method, and response format. URL If you need to create a record in Acumatica ERP, you use the following URL. endpoint URL>/<Top-level entity> 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 Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <Top-level entity> is the name of the entity for which you are going to create a record. For example, suppose that you want to create a stock item record in a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You should use the following URL to create a record: Default/ /StockItem. Parameters You can use the following parameters when you retrieve a record from Acumatica ERP: $expand: To specify the linked and detail entities to be expanded $select: To specify the fields of the entity to be returned $custom: To specify the fields that are not defined in the contract to be returned For detailed descriptions of the parameters, see Parameters for Retrieving Records.

103 Working with the Contract-Based REST API 103 HTTP Method You use the PUT HTTP method and pass a record in JSON format in the request body. You can find details on how to represent a record in JSON format in Representation of a Record in JSON Format. See below for an example of a customer record representation in JSON format. "CustomerID" : value : "JOHNGOOD", "CustomerName" : value : "John Good", "MainContact" : " " : value : "demo@gmail.com", "Address" : "AddressLine1" : value : "4030 Lake Washington Blvd NE", "AddressLine2" : value : "Suite 100", "City" : value : "Kirkland", "State" : value : "WA", "PostalCode" : value : "98033" Response The response of a successful method call contains the created record in JSON format in the response body. The response includes only the values of the fields of the created record that were specified during creation of the record or that were specified to be returned by using the parameters of the request. Example The following code shows an example of a class that implements the creation of a record in Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company,

104 Working with the Contract-Based REST API 104 branch = branch ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); //Data submission public string Put(string entityname, string parameters, string entity) var res = _httpclient.putasync(_acumaticabaseurl + "/entity/default/ /" + entityname + "?" + parameters, new StringContent(entity, Encoding.UTF8, "application/json")).result.ensuresuccessstatuscode(); return res.content.readasstringasync().result; The following code uses the RestService.Put() method, which is defined in the previous code fragment, to create a customer record. public static void CreateCustomer() //Path to a source text file that contains //the new customer record in JSON format string entitysource //Initialize the REST service RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); using (StreamReader sr = new StreamReader(entitySource)) //Read the customer record in JSON format from the file string entityasstring = sr.readtoend().tostring(); //Create a customer record string customer = rs.put("customer", null, entityasstring); Update of a Record When you need to update an existing record by using the contract-based REST API, you access the needed URL with the PUT HTTP method and pass the record representation in JSON format in the request body. See the following sections for details on the URL, parameters, HTTP method, and response format.

105 Working with the Contract-Based REST API 105 URL If you need to update a record in Acumatica ERP, you use the following URL. endpoint URL>/<Top-level entity> 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 Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <Top-level entity> is the name of the entity for which you are going to update a record. For example, suppose that you want to update a stock item record in a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You would use the following URL to update a record: Default/ /StockItem. Parameters You can use the following parameters when you are updating a record in Acumatica ERP: $filter: To specify filtering conditions that identify the record to be updated $expand: To specify the linked and detail entities to be expanded $select: To specify the fields of the entity to be returned $custom: To specify the fields that are not defined in the contract to be returned For detailed descriptions of the parameters, see Parameters for Retrieving Records. HTTP Method You use the PUT HTTP method and pass a record in JSON format in the request body. You can find details on how to represent a record in JSON format in Representation of a Record in JSON Format. To make it possible for the record to be found by Acumatica ERP, you can use any of the following approaches: Specify the values of the key fields in the record representation in JSON format. Specify the value of the ID property in the record representation in JSON format. Specify the filtering conditions that identify the record in the $filter parameter of the method. For details on the parameter, see the Parameters section in this topic. If you want to delete a detail line during update, you should specify true as the value of the delete property of the corresponding detail entity: "delete" : true. To identify the detail line to be deleted, you can specify either the values of the key fields of the detail line or the value of the ID property. Response The response of a successful method call contains the updated record in JSON format in the response body. The response includes only the values of the fields of the updated record that were specified during the update or that were specified to be returned by using the parameters of the request.

106 Working with the Contract-Based REST API 106 Example The following code shows an example of a class that implements the update of a record in Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); //Data submission public string Put(string entityname, string parameters, string entity) var res = _httpclient.putasync(_acumaticabaseurl + "/entity/default/ /" + entityname + "?" + parameters, new StringContent(entity, Encoding.UTF8, "application/json")).result.ensuresuccessstatuscode(); return res.content.readasstringasync().result; The following code uses the RestService.PutWithFilter() method, which is defined in the previous code fragment, to update an existing customer record that has the demo@gmail.com address. public static void UpdateCustomer()

107 Working with the Contract-Based REST API 107 //Path to a source text file that contains an updated customer record in JSON format string entitysource //REST service initialization RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); using (StreamReader sr = new StreamReader(entitySource)) //Read customer record in JSON format from file string entityasstring = sr.readtoend().tostring(); //Specify filtering parameters that identify the customer string parameter = "$filter=maincontact/ eq 'demo@gmail.com'"; //Update the customer record string customer = rs.put("customer", parameter, entityasstring); Retrieval of a Record by Key Fields To retrieve a record by the values of its key fields from Acumatica ERP by using the contract-based REST API, you access the needed URL with the GET HTTP method and specify the fields that should be returned in the parameters of the method. See the following sections for details on the URL, parameters, HTTP method, and response format. URL If you need to obtain a particular record with the known key fields, you use the following URL endpoint URL>/<Top-level entity>/<key value 1>/<Key value 2> 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 Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <Top-level entity> is the name of the entity for which you are going to retrieve a record. <Key value 1> and <Key value 2> are the values of the key fields of the record to be retrieved. You use the number and order of key fields as they are defined on the corresponding Acumatica ERP form. : You can pass the key fields separated by vertical bar ( ) instead of slash(/). For example, suppose that you want to retrieve the sales order with order type SO and order number from a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You should use the following URL to retrieve the sales order: SO/

108 Working with the Contract-Based REST API 108 Parameters You can use the following parameters when you retrieve a record from Acumatica ERP: $expand: To specify the linked and detail entities to be expanded $custom: To specify the fields that are not defined in the contract to be returned $select: To specify the fields of the entity to be returned For detailed descriptions of the parameters, see Parameters for Retrieving Records. HTTP Method You use the GET HTTP method to retrieve records. Response The response of a successful method call contains the retrieved record in JSON format in the response body. For details on record representation in JSON format, see Representation of a Record in JSON Format. Example The following code shows an example of a class that implements the retrieval of a record in Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait();

109 Working with the Contract-Based REST API 109 _httpclient.dispose(); //Retrieval of a record by key fields public string GetByKeys(string entityname, string keys, string parameters) var res = _httpclient.getasync( _acumaticabaseurl + "/entity/default/ /" + entityname + "/" + keys + "?" + parameters).result.ensuresuccessstatuscode(); return res.content.readasstringasync().result; The following code uses the RestService.GetByKeys() method, which is defined in the previous code fragment, to retrieve a sales order with detail lines from Acumatica ERP. public static void ExportSODetails() //Sales order data string ordertype = "SO"; string ordernbr = "000001"; //Initialize the REST service RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); //Specify the parameter to obtain the details of a sales order string parameters = "$expand=details"; //Retrieve a sales order by keys string stockitems = rs.getbykeys("salesorder", ordertype + "/" + ordernbr, parameters); Retrieval of a Record by ID To retrieve a record by the value of the session entity ID from Acumatica ERP by using the contractbased REST API, you access the needed URL with the GET HTTP method and specify the fields that should be returned in the parameters of the method. See the following sections for details on the URL, parameters, HTTP method, and response format. : The session entity ID is a GUID that is assigned to each entity you work with during an Acumatica ERP session. You can obtain the value of the session entity ID from the ID property of an entity returned from Acumatica ERP. The session entity ID is different for each new session with Acumatica ERP. That is, after a new login to Acumatica ERP, you cannot use the session entity ID that you received in the previous session to work with the entity. URL If you need to obtain a particular record with the session entity ID, you use the following URL. endpoint URL>/<Top-level entity>/<session entity ID> The URL has the following components:

110 Working with the Contract-Based REST API 110 <Base endpoint URL> is the URL of a contract-based endpoint through which you are going to work with Acumatica ERP. This URL has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <Top-level entity> is the name of the entity for which you are going to retrieve a record. <Session entity ID> is the session ID of the record to be retrieved. For example, suppose that you want to retrieve the sales order with session entity ID 03efa bd5-ae06-3d9fb3b3c1e6 from a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You should use the following URL to retrieve the sales order: Default/ /SalesOrder/03efa bd5-ae06-3d9fb3b3c1e6. Parameters You can use the following parameters when you retrieve a record from Acumatica ERP: $expand: To specify the linked and detail entities to be expanded $select: To specify the fields of the entity to be returned $custom: To specify the fields that are not defined in the contract to be returned For detailed descriptions of the parameters, see Parameters for Retrieving Records. HTTP Method You use the GET HTTP method to retrieve records. Response The response of a successful method call contains the retrieved record in JSON format in the response body. For details on record representation in JSON format, see Representation of a Record in JSON Format. Retrieval of Records by Conditions To retrieve records that satisfy the specified conditions from Acumatica ERP by using the contractbased REST API, you access the needed URL address with the GET HTTP method and specify filtering conditions in the parameters of the method. See the following sections for details on the URL, parameters, HTTP method, and response format. URL If you need to retrieve the list of records that satisfies the specified conditions, you use the following URL. endpoint URL>/<Top-level entity> 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 Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <Top-level entity> is the name of the entity for which you are going to retrieve the list of records. For example, suppose that you want to retrieve the list of stock item records from a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default

111 Working with the Contract-Based REST API 111 and Version You should use the following URL to retrieve the list of records: localhost/acumaticadb/entity/default/ /stockitem. Parameters You can use the following parameters when you retrieve records from Acumatica ERP: $filter: To specify filtering conditions on the records to be returned $skip: To specify the number of records to be skipped from the list of returned records $top: To specify the number of records to be returned in the list $expand: To specify the linked and detail entities to be expanded $select: To specify the fields of the entity to be returned $custom: To specify the fields that are not defined in the contract to be returned For detailed descriptions of the parameters, see Parameters for Retrieving Records. HTTP Method You use the GET HTTP method to retrieve records. Response The response of a successful method call contains the retrieved records in JSON format in the response body. For details on record representation in JSON format, see Representation of a Record in JSON Format. Example The following code shows an example of a class that implements the retrieval of records from Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company,

112 Working with the Contract-Based REST API 112 branch = branch ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); public string Get(string entityname, string parameters) var res = _httpclient.getasync( _acumaticabaseurl + "/entity/default/ /" + entityname + "?" + parameters).result.ensuresuccessstatuscode(); return res.content.readasstringasync().result; The following code uses the RestService.Get() method, which is defined in the previous code fragment, to retrieve the list of stock item records that have the Active status in Acumatica ERP and have been modified within the past month. The code uses the $expand parameter to retrieve the vendor details of each record. public static void ExportStockItems() //Initialize the REST service RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); //Specify the parameter to filter records by status and last modified date string parameters1 = "$filter=itemstatus eq 'Active' and LastModified gt datetimeoffset'" + WebUtility.UrlEncode(new DateTimeOffset(DateTime.Now.AddMonths(-1)).ToString("yyyy-MM-ddTHH:mm:ss.fffK")) + "'"; //Specify the parameter to obtain vendor details string parameters2 = "$expand=vendordetails"; //Retrieve the list of stock items string stockitems = rs.get("stockitem", parameters1 + "&" + parameters2); Usage Notes for Endpoints with Contract Version 3 When multiple records are retrieved from Acumatica ERP through an endpoint with Contract Version 3, the system tries to optimize the retrieval of the records and obtain all needed records in one request to the database (instead of requesting the records one by one). If the optimization fails, the system returns an error, which specifies the entities or fields that caused the failure of the optimized request. To prevent the error from occurring, you can do any of the following: If you do not need to retrieve the entities or fields that caused the failure, you can exclude these entities or fields from the request as follows: Exclude the entities from the entities specified in the $expand parameter.

113 Working with the Contract-Based REST API 113 Explicitly specify the other fields to be returned (while excluding the fields that caused the failure) by using the $select parameter. If you need to retrieve the entities or fields that caused the failure, you can retrieve the needed records one by one either by key fields, or by IDs. Retrieval of Data from an Inquiry Form To retrieve data from an inquiry form of Acumatica ERP by using the contract-based REST API, you access the needed URL with the PUT HTTP method and pass the parameters of the inquiry in JSON format in the request body. See the following sections for details on and examples of the URL, parameter, HTTP method, and response format. URL If you need to retrieve data from an inquiry form, you use the following URL. endpoint URL>/<Top-level entity> 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 Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <Top-level entity> is the name of the entity that corresponds to the inquiry form from which you are going to retrieve data. For example, suppose that you want to retrieve data from the Inventory Summary (IN401000) form in a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You would use the following URL to retrieve data: localhost/acumaticadb/entity/default/ /inventorysummaryinquiry. Parameter When you are retrieving data from an inquiry form, you should use the $expand parameter to expand the detail entity, which contains the results of the inquiry. For a detailed description of the parameter, see Parameters for Retrieving Records. HTTP Method You use the PUT HTTP method and pass parameters of the inquiry in JSON format in the request body. See below for an example of the representation of parameters of the Inventory Summary inquiry form in JSON format. "InventoryID" : value : "AALEGO500", "WarehouseID" : value : "MAIN" Response The response of a successful method call contains the data returned from an inquiry form in JSON format in the response body.

114 Working with the Contract-Based REST API 114 Example The following code shows an example of a class that implements the retrieval of data from an inquiry form of Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); //Data submission public string Put(string entityname, string parameters, string entity) var res = _httpclient.putasync(_acumaticabaseurl + "/entity/default/ /" + entityname + "?" + parameters, new StringContent(entity, Encoding.UTF8, "application/json")).result.ensuresuccessstatuscode(); return res.content.readasstringasync().result; The following code uses the RestService.Put() method, which is defined in the previous code fragment, to retrieve the quantities of a stock item from the Inventory Summary inquiry form. public static void ExportItemQty() //Path to a source text file that contains the parameters of //the inquiry in JSON format

115 Working with the Contract-Based REST API 115 string entitysource //REST service initialization RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); using (StreamReader sr = new StreamReader(entitySource)) //Read inquiry parameters in JSON format from a file string entityasstring = sr.readtoend().tostring(); //Specify the parameter to expand results of the inquiry string parameters = "$expand=results"; //Retrieve data from the inquiry string stockitems = rs.put("inventorysummaryinquiry", parameters, entityasstring); Parameters for Retrieving Records When you retrieve records from Acumatica ERP by using the contract-based REST API, you can use the URL parameters, which are described in this topic, to filter records by the specified conditions, expand particular entities, and retrieve the values of the fields that are not defined in the contract of the endpoint. $filter Parameter You use this parameter to specify the conditions that determine which records should be selected from Acumatica ERP. You use OData URI conventions to specify the value of the parameter. The following examples illustrate the use of this parameter: $filter=itemstatus eq 'Active': Obtains stock item records that have the Active status in Acumatica ERP. $filter=maincontact/ eq 'demo@gmail.com': Obtains a customer record that has the demo@gmail.com address. (The field is defined in a linked entity, which is available through the MainContact property.) $filter=itemstatus eq 'Active' and LastModified gt datetimeoffset' t10%3a31%3a28.402%2b03%3a00': Obtains stock item records that have the Active status in Acumatica ERP and have been modified later than July 15, : You should encode date and time values in URL format before passing them as the value of the parameter. For example, you can encode the current date and time by using the System.Net.WebUtility.URLEncode() method as follows: WebUtility.UrlEncode(new DateTimeOffset(DateTime.Now).ToString("yyyy-MM-ddTHH:mm:ss.fffK")). : For one field, multiple conditions cannot be specified in the $filter parameter. The only exception is the ge X and le Y condition, such as $filter=createddatetime ge DateTimeOffset' T00%3A00%3A00%2B000' and CreatedDateTime le DateTimeOffset' T00%3A00%3A00%2B000'. When you specify the value of the parameter, you can use the following functions as they are defined in OData: substringof

116 Working with the Contract-Based REST API 116 startswith endswith You can also use the following custom function to filter records by the values of the elements that are not defined in the contract of the endpoint: cf.<type name>(f='<view name>.<field name>'), where <Type name> is the type of the custom element, <View name> is the name of the data view that contains the element, and <Field name> is the name of the element. For example, if you want to obtain all records on the Stock Items (IN202500) form that have the value of the Post Class ID element equal to STOCKITEM, you would use the following parameter string: $filter=cf.string(f='itemsettings.postclassid') eq 'STOCKITEM'. : For details on how to find out the name of a custom element and the name of its data view, see Custom Fields. $top Parameter You use this parameter to specify the number of records to be returned from Acumatica ERP. That is, if you specify N as the value of this parameter, the first N records will be returned from Acumatica ERP. For example, if you want to obtain only first five records from the list, you use the following parameter string: $top=5. $skip Parameter You use this parameter to specify the number of records to be skipped from the list of returned records. That is, if you specify N as the value of this parameter, the first N records will be skipped from the list of returned records. For example, if you do not want to obtain the first five records from the list, you use the following parameter string: $skip=5. If you use the $skip and $top parameters together, the $skip parameter is applied first. $expand Parameter You use this parameter to specify the linked and detail entities that should be expanded. By default, no linked or detail entities are expanded; that is, only fields of the top-level entity are returned. You use OData URI conventions to specify the value of this parameter. For example, if you want to obtain the values of the warehouse detail lines of stock item records, you use the following parameter string: $expand=warehousedetails. You explicitly specify each linked or detail entity to be expanded. For example, if you specify $expand=maincontact for the Customer entity, only the Contact linked entity of the Customer entity is expanded, but the Address linked entity within MainContact is not. To expand the Address entity, you should explicitly specify the Address entity to be expanded: $expand=maincontact/address. $select Parameter You use this parameter to specify the fields of the entity to be returned from Acumatica ERP. By default, all fields of the entity are returned. You use OData URI conventions to specify the value of this parameter. For example, if you want to obtain only the order types and order numbers of sales orders, you use the following parameter string: $select=ordertype,ordernbr. $custom Parameter You use this parameter to specify the fields that are not defined in the contract of the endpoint to be returned from Acumatica ERP. That is, you can use this parameter to obtain both the values of predefined elements on an Acumatica ERP form that are not included in the entity definition and the values of elements that were added to the Acumatica ERP form in a customization project.

117 Working with the Contract-Based REST API 117 You specify the element whose value should be returned in the following format: <View name>.<field name>, where you replace <View name> with the name of the data view that contains the element and <Field name> with the internal name of the element. For example, if you want to obtain the value of the Post Class ID element of the Stock Items (IN202500) form, you use the following parameter string: $custom=itemsettings.postclassid. For details on how to find out the field name and the name of the data view, see Custom Fields. : If you want to obtain the value of a custom field of a linked or detail entity, you have to specify this entity in the $expand parameter. If you want to obtain the values of multiple custom elements, you specify the custom elements to be returned divided by commas. Removal of a Record In the contract-based REST API, you can delete the record by the value of its key fields or by its session identifier. To delete a record from Acumatica ERP, you access the needed URL address with the DELETE HTTP method. See the following sections for details on the possible URL, parameters, HTTP method, and response format. : If you need to delete a detail line of a record, you should use the PUT HTTP method, as described in Update of a Record. URL for Removing by Key Fields If you need to delete a record with known key fields, you use the following URL. endpoint URL>/<Top-level entity>/<key value 1>/<Key value 2> 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 Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <Top-level entity> is the name of the entity for which you are going to delete a record. <Key value 1> and <Key value 2> are the values of the key fields of the record to be deleted. You use the number and order of key fields as they are defined on the corresponding Acumatica ERP form. : You can pass the key fields separated by vertical bar ( ) instead of slash(/). For example, suppose that you want to delete the sales order with order type SO and order number from a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You should use the following URL to delete the sales order: SO/ URL for Removing by ID If you need to delete a record with a known session ID, you use the following URL. endpoint URL>/<Top-level entity>/<session entity ID> You replace <Base endpoint URL> with the URL of the contract-based endpoint through which you are going to work with Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. You replace <Top-level

118 Working with the Contract-Based REST API 118 entity> with the name of the entity for which you are going to retrieve the list of records. You replace <Session entity ID> with the session entity ID (which is the GUID). For example, suppose that you want to delete the sales order with session entity ID 03efa bd5-ae06-3d9fb3b3c1e6 from a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You should use the following URL to delete the sales order: Default/ /SalesOrder/03efa bd5-ae06-3d9fb3b3c1e6. Parameters You use no parameters when deleting a record. HTTP Method You use the DELETE HTTP method to retrieve records. You pass no content in the request body. Response The response of a successful method call is 204 No Content. Example The following code shows an example of a class that implements the removal of a record from Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait();

119 Working with the Contract-Based REST API 119 _httpclient.dispose(); //Removal of a record public string Delete(string entityname, string keys) var res = _httpclient.deleteasync(_acumaticabaseurl + "/entity/default/ /" + entityname + "/" + keys).result.ensuresuccessstatuscode(); return res.content.readasstringasync().result; The following code uses the RestService.Delete() method, which is defined in the previous code fragment, to delete a stock item record. public static void DeleteStockItem() //Stock item data string inventoryid = "ASDF"; //Initialize the REST service RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); //Remove the stock item string stockitem = rs.delete("stockitem", inventoryid); Execution of an Action To perform an action by using the contract-based REST API, you access the needed URL address with the POST HTTP method and pass the record representation in JSON format and parameters of the action in the request body. See the following sections for details on the URL, parameters, HTTP method, and response format. URL If you need to perform an action on an Acumatica ERP form, you use the following URL. 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 Acumatica ERP, which has the following format: ERP 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. For example, suppose that you want to confirm a shipment in a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You should use the following URL to confirm a shipment: Default/ /Shipment/ConfirmShipment.

120 Working with the Contract-Based REST API 120 Parameters You use no parameters when performing an action. HTTP Method You use the POST HTTP method and pass the record to which the action should be applied and the parameters of the action in the request body in JSON format as follows. "entity" : <record in JSON format>, "parameters" : <parameters in JSON format> You can find details on how to represent a record in JSON format in Representation of a Record in JSON Format. Response If the long-running operation that was initiated by the action is completed or wasn't created, the response is 204 No Content. If the long-running operation is in progress, the response is 202 Accepted; it has the Location header, which contains a URL that can be used 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. Example The following code shows an example of a class that implements the execution of an action in Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch ).Result.EnsureSuccessStatusCode();

121 Working with the Contract-Based REST API 121 void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); //Invocation of an action public string Post(string entityname, string actionname, string entityandparameters) var result = _httpclient.postasync(_acumaticabaseurl + "/entity/default/ /" + entityname + "/" + actionname, new StringContent(entityAndParameters, Encoding.UTF8, "application/json")); var res = result.result; var cont = res.content.readasstringasync().result; res.ensuresuccessstatuscode(); var dt = DateTime.Now; while (true) switch (res.statuscode) case HttpStatusCode.NoContent: return "No content"; case HttpStatusCode.Accepted: if ((DateTime.Now - dt).seconds > 30) throw new TimeoutException(); Thread.Sleep(500); res = _httpclient.getasync(res.headers.location).result.ensuresuccessstatuscode(); continue; default: throw new InvalidOperationException( "Invalid process result: " + res.statuscode); The following code uses the RestService.Post() method, which is defined in the previous code fragment, to release a sales order invoice. public static void ReleaseSOInvoice() //Invoice to be released string invoice = "\"Type\" : value : \"Invoice\", " + "\"ReferenceNbr\" : value : \"INV000045\" "; //Initialize the REST service RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); //Release the invoice invoice = rs.post("salesinvoice", "ReleaseSalesInvoice", "\"entity\" : " + invoice + ", \"parameters\" : null");

122 Working with the Contract-Based REST API 122 Attachment of a File to a Record When you need to attach a file to a record by using the contract-based REST API, you access the needed URL address with the PUT HTTP method and pass the file in the request body. See the following sections for details on the URL, parameters, HTTP method, and response format. URL If you need to attach a file to a record in Acumatica ERP, you use the following URL. endpoint URL>/<Top-level entity>/<key value 1>/<Key value 2>/files/ <File 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 Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <Top-level entity> is the name of the entity to which you are going to attach a file. <Key value 1> and <Key value 2> are the values of the key fields of the record to which you are going to attach a file. You use the number and order of key fields as they are defined on the corresponding Acumatica ERP form. : You can pass the key fields separated by vertical bar ( ) instead of slash(/). <File name> is the name of the file that you are going to attach with the extension. For example, suppose that you want to attach the Sample.jpg file to the stock item record with inventory ID AALEGO500 in a local Acumatica ERP instance with name AcumaticaDB by using the system endpoint with the name Default and Version You should use the following URL to attach the file: AALEGO500/files/Sample.jpg. Parameters You use no parameters when you attach a file to a record. HTTP Method You use the PUT HTTP method and pass the file to be attached in the request body. Response The response of a successful method call is 204 No Content. Example The following code shows an example of a class that implements the attachment of a file to a record in Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password,

123 Working with the Contract-Based REST API 123 string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); //Attachment of a file to a record public string PutFile(string entityname, string keys, string filename, System.IO.Stream file) var res = _httpclient.putasync(_ acumaticabaseurl + "/entity/default/ /" + entityname + "/" + keys + "/files/" + filename, new StreamContent(file)).Result.EnsureSuccessStatusCode(); return res.content.readasstringasync().result; The following code uses the RestService.PutFile() method, which is defined in the previous code fragment, to attach a file to a stock item record. public static void PutFile() //Input data string inventoryid = "AALEGO500"; string filename = "T2MCRO.jpg"; string entitysource //Initialize the REST service RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); using (StreamReader sr = new StreamReader(entitySource))

124 Working with the Contract-Based REST API 124 //Attach a file to a stock item record string stockitem = rs.putfile("stockitem", inventoryid, filename, sr.basestream); Retrieval of a File Attached to a Record To retrieve a file that is attached to a record from Acumatica ERP by using the contract-based REST API, you access the URL address of the file with the GET HTTP method. See the following sections for details on the URL, parameters, HTTP method, and response format. URL If you need to obtain a file attached to a record, you use the following URL. endpoint URL>/files/<File identifier> 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 Acumatica ERP, which has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. <File identifier> is the internal identifier of the file in the system. To get this URL for a particular file attached to a record, you should obtain the record from Acumatica ERP and, in the returned JSON representation of the record, find the value of the href property of the needed file in the files array. For information on how to retrieve a record from Acumatica ERP, see Retrieval of a Record by Key Fields and Retrieval of a Record by ID. For example, suppose that you retrieved the stock item record that contains the following files array from a local Acumatica ERP instance with the name AcumaticaDB...., "files":[ "id":"9be45eb7-f97d-400b-96a5-1c4cf82faa96", "filename":"stock Items (AAMACHINE1)\\T2MCRO.jpg", "href": "/AcumaticaDB/entity/Default/ /files/9be45eb7-f97d-400b-96a5-1c4cf82faa96" ] You should use the following URL to retrieve the T2MCRO.jpg file attached to the stock item record: Parameters You use no parameters when retrieving a file. HTTP Method You use the GET HTTP method to retrieve a file.

125 Working with the Contract-Based REST API 125 Response The response of a successful method call contains the retrieved file in the response body. Example The following code shows an example of a class that implements the retrieval of a file attached to a record in Acumatica ERP through the REST API. public class RestService: IDisposable private readonly HttpClient _httpclient; private readonly string _acumaticabaseurl; public RestService( string acumaticabaseurl, string username, string password, string company, string branch) _acumaticabaseurl = acumaticabaseurl; _httpclient = new HttpClient( new HttpClientHandler UseCookies = true, CookieContainer = new CookieContainer() ) BaseAddress = new Uri(acumaticaBaseUrl + "/entity/default/ /"), DefaultRequestHeaders = Accept = MediaTypeWithQualityHeaderValue.Parse("text/json") ; _httpclient.postasjsonasync( acumaticabaseurl + "/entity/auth/login", new name = username, password = password, company = company, branch = branch ).Result.EnsureSuccessStatusCode(); void IDisposable.Dispose() _httpclient.postasync(_acumaticabaseurl + "/entity/auth/logout", new ByteArrayContent(new byte[0])).wait(); _httpclient.dispose(); //Retrieval of a record by key fields public string GetByKeys(string entityname, string keys, string parameters) var res = _httpclient.getasync( _acumaticabaseurl + "/entity/default/ /" + entityname + "/" + keys + "?" + parameters).result.ensuresuccessstatuscode(); return res.content.readasstringasync().result; //Retrieving of a file public System.IO.Stream GetFile(string href) var res = _httpclient.getasync(href).result.ensuresuccessstatuscode(); return res.content.readasstreamasync().result;

126 Working with the Contract-Based REST API 126 The following code uses the RestService.GetByKeys() and RestService.GetFile() methods, which are defined in the previous code fragment, to retrieve a file attached to a stock item record from Acumatica ERP. public static void GetFile() //Specify stock item data string inventoryid = "AAMACHINE1"; //Initialize the REST service RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch ); //Retrieve the stock item string stockitem = rs.getbykeys("stockitem", inventoryid, null); //Find href and the file name of the needed file //(using Newtonsoft.Json.Linq and System.IO) JObject jitem = JObject.Parse(stockItem); JArray jfiles = jitem.value<jarray>("files"); string fileref = jfiles[0].value<string>("href"); string fullfilename = jfiles[0].value<string>("filename"); string filename = Path.GetFileName(fullFileName); //Obtain the file Stream file = rs.getfile(fileref); using (var outputfile = File.Create(@"..\..\Output\" + filename)) file.seek(0, SeekOrigin.Begin); file.copyto(outputfile); Retrieval of the Schema of Custom Fields To retrieve the schema of custom fields of an entity that is, the field name, view name, and type of the fields that are not defined in the contract of the endpoint for this entity by using the contract-based REST API, you access the needed URL with the GET HTTP method. See the following sections for details on and examples of the URL, parameters, HTTP method, and response format. URL If you need to obtain the schema of custom fields of an entity, you use the following URL. 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 Acumatica ERP, which has the following format: ERP 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.

127 Working with the Contract-Based REST API 127 For example, suppose that you want to obtain the schema of custom fields of a stock item entity from a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and Version You would use the following URL to retrieve the schema: localhost/acumaticadb/entity/default/ /stockitem/$adhocschema. Parameters You use no parameters when retrieving the schema of custom fields of an entity. HTTP Method You use the GET HTTP method to retrieve the schema of custom fields. Response The response of a successful method call contains the schema of custom fields in JSON format in the response body. Multi-Language Fields For some text boxes on Acumatica ERP forms, users can type values in multiple languages if multiple locales are configured in Acumatica ERP. For example, if your Acumatica ERP instance has English and French locales activated and multilingual user input configured, you can specify the value of the box on the Stock Items (IN202500) form in English and French. For the list of elements that support multiple languages, see Boxes that Have Multi-Language Support. For details on how to turn on multilingual user input, see Enabling Multilingual User Input. Specifying Localized Values of a Multi-Language Field When you need to specify localized values of a text box by using the contract-based REST API, you specify the value of the field that corresponds to the box as a string in JSON format with the localized values. In this string, you use the two-letter ISO code of the language with which the value should be associated. In the example that is mentioned at the beginning of the topic, if you need to specify values in English and French in the box on the Stock Items form, you specify the value of the field of the StockItem entity in the following format: [en:english description,fr:french description]. See below for an example of a stock item record with localized field values in JSON format. For details on how to pass the record to the service, see Creation of a Record and Update of a Record. "InventoryID" : value : "BASESERV", "" : value : "[en:item,fr:pièce]" : In the JSON-formatted string, you should specify the actual values of the field in all languages that are configured for multilingual user input. If you specify the values of the field in particular languages, the values of the field in other languages configured for multilingual user input become empty. For example, suppose that in your instance of Acumatica ERP, multi-language fields can have values in English and French. If you pass the value of a field in the following format [en:english description], the French value of the field becomes empty. If you specify the value of a multi-language field as plain text, this text is saved as the value of the corresponding box in the current language of Acumatica ERP (that is, the language that you specified when you logged in to Acumatica ERP). For details on how to specify the language on login through the contract-based REST API, see Login to the Service.

128 Working with the Contract-Based REST API 128 Retrieving Localized Values of a Multi-Language Field If you need to retrieve localized values of a text box that supports multiple input languages, you retrieve the value a special custom field that contains all localized values of the text box and has the Translations suffix in its field name. To find out the field name and the view name of the needed custom field with localized values, you find out the field name and the view name of the multi-language text box and append Translations to the field name. (For details on how to find out the field name and the view name of an element on the form, see Custom Fields.) For example, the multi-language box on the Stock Items form has the Descr field name and the Item view name; therefore, the custom field that contains the localized descriptions of a stock item has the DescrTranslations field name and the Item view name. You obtain the value of the needed custom field by using the $custom parameter. For example, suppose that you need to obtain the localized values of the element of the Stock Items form. In this case, you should use the following parameter string in the request URL: $custom=item.descrtranslations. For details on how to retrieve a record, see Retrieval of a Record by Key Fields and Retrieval of Records by Conditions. The returned value of a Translations custom field is a string in JSON format with the available localized values of the field. The language to which the value belongs is identified by the two-letter ISO code of the language. For example, suppose that the element of the Stock Items form has the value Item in English and Pièce in French. In this case, the value of the DescrTranslations custom field, which corresponds to the element, is the following string: [en:item, fr:pièce].

129 Working with the Screen-Based SOAP API 129 Working with the Screen-Based SOAP API The screen-based SOAP API of Acumatica ERP provides the SOAP interface of the Acumatica ERP contract-based web services through which external systems can get data records from Acumatica ERP, process these records, and save new or updated records to Acumatica ERP. In This Chapter Screen-Based Web Services API API Objects Related to Acumatica ERP Forms Screen-Based API Wrapper To Generate the WSDL File of the Web Services To Import the WSDL File Into the Development Environment To Use the Screen-Based API Wrapper Screen-Based Web Services API The screen-based web services API is a part of Acumatica ERP integration services, which provides integration with external data sources and third-party systems by using a SOAP interface. External applications and systems that use the Acumatica ERP web services API can access the data managed by Acumatica ERP and the business functionality of Acumatica ERP. For example, you can integrate Acumatica ERP with ecommerce or an online store system, so that an external system pushes all information about customers, sales orders, and payments to Acumatica ERP, and Acumatica ERP provides information on the availability of stock items and processes all incoming data. The screen-based web services API works with Acumatica ERP forms. That is, it provides API objects and methods for working with elements on Acumatica ERP forms. To upload data to and from Acumatica ERP by using the screen-based web services API, you define the sequence of commands for the system to work with elements on an Acumatica ERP form. This sequence of commands reflects the sequence of actions to be executed for a data record as if the record is being manipulated by a user through an Acumatica ERP form. That is, when you enter data into the system manually, you perform a sequence of actions. You open the needed data entry form and start entering data. As you add a new record, you use the UI elements one by one you type text, select values from combo boxes, clear or select check boxes, and click buttons. In the sequence of commands for the web services, you compose exactly the same sequence of actions by specifying a command for each user action on the form. For more information on the commands you can use, see Working with Commands of the Screen-Based SOAP API. : This sequence of commands is similar to the sequence of commands you configure when you create import and export scenarios. You can find more information on import and export scenarios in Configuring Import Scenarios and Configuring Export Scenarios. To use screen-based web services API in your application, you should generate the WSDL file of the web service, as described in To Generate the WSDL File of the Web Services, and import this file to your development project as described in To Import the WSDL File Into the Development Environment. After that, you can start developing your application. You can find the description of the API methods in Screen-Based SOAP API Reference. You can find more details on screen-based web services API and examples of use of the API in the I200 Screen-Based Web Services training course.

130 Working with the Screen-Based SOAP API 130 API Objects Related to Acumatica ERP Forms The main object, which provides access to all other objects and methods of the Acumatica ERP web services API, is a Screen object. By using the methods of a Screen object, you can log in to Acumatica ERP and retrieve, insert, update, and delete data. You can also use the methods to perform any actions that are exposed by Acumatica ERP forms available through the web service. Screen Object After you have logged in to Acumatica ERP by using the web services API, you can access data on Acumatica ERP forms available through the web service. The Screen class provides the same set of API methods for working with all Acumatica ERP forms available through the service. You can find out which form a method accesses by noting the prefix in the name of the method, which is the form ID. For example, the Export() method that you use to export data from the Stock Items (IN202500) form is IN202500Export(). Content Object To get the description of the structure (schema) of a form, you should use the GetSchema() method of the Screen object. This method is specific for each Acumatica ERP form, and you should use the method with the ID of the needed form in the prefix of the method name. The method returns the schema of the form as the corresponding Content object, which is specific for each form. For example, to get the schema of the Stock Items form, you should call the IN202500GetSchema() method of the Screen object. You will receive the result as a IN202500Content object, as the following code shows. Screen context = new Screen();... IN202500Content stockitemsschema = context.in202500getschema(); Command Object By using subobjects of a Content object, you configure the sequence of commands that should be executed during data import, data export, or data processing through the web service. You configure the sequence of commands inside an array of objects of the Command type. When you are reflecting the selection of an element on a form in the sequence of commands, you have to select the object of the Acumatica ERP form whose element you want to access. The objects that are available inside a Content object have names that are similar to the names of the UI elements that you see on the form and have the ID of the form as a prefix. For example, to be able to select the Item Class element, which is located in the Item Defaults group on the General Settings tab of the Stock Items form (shown in the following screenshot), you would select the GeneralSettingsItemDefaults property of the IN202500Content object. This property provides access to the IN202500GeneralSettingsItemDefaults object, which includes the ItemClass property. Each element on an Acumatica ERP form (such as a text box, combo box, or table column) is associated with a particular web services API class and is available through corresponding property of this class. The property has a similar name to that of the corresponding box on the form, such as ItemClass, as the following screenshot shows.

131 Working with the Screen-Based SOAP API 131 Figure: API object on an Acumatica ERP form The following code shows an example of configuring a list of commands for the Stock Items form inside an array of Command objects. //stockitemsschema is a IN202500Content object var commands = new Command[] stockitemsschema.stockitemsummary.servicecommands.everyinventoryid, stockitemsschema.stockitemsummary.inventoryid, stockitemsschema.stockitemsummary., stockitemsschema.generalsettingsitemdefaults.itemclass, stockitemsschema.generalsettingsunitofmeasurebaseunit.baseunit ; For more information on the commands, see Working with Commands of the Screen-Based SOAP API. Actions Object To insert an action to a sequence of commands, such as clicking a button, you use the corresponding property of the special API object Actions (which has a prefix with the ID of the form in the name). The Actions object is available through the Actions property of the Content object that corresponds to the form. The properties of the Actions object have names that are similar to the names of corresponding buttons on the form, such as Delete. You can view the classes available through the web services API by using Object Browser in Visual Studio. Screen-Based API Wrapper Because of the connection of the screen-based SOAP API with Acumatica ERP forms, the applications that are developed based on this API are sensitive to the UI changes in the system. That is, any changes made to the UI after the application is created require the application to be updated and recompiled. If you want your application to not depend on the UI changes in the system, you should use the screen-based API wrapper, which is described in this topic.

132 Working with the Screen-Based SOAP API 132 How a Client Application Based on the Screen-Based API Works A client application that uses the screen-based web services API includes the WSDL description of the service, which contains the API elements that the application can use to work with the service. The API elements have names that are similar to the names of the elements in the UI of Acumatica ERP. For example, the Customer ID element of the Customers (AR303000) form corresponds to the Customer.CustomerSummary.CustomerID property. When the application calls the Screen.GetSchema() method, it retrieves from Acumatica ERP the schema of an Acumatica ERP form. The schema of the form is a Content object, which defines the correspondence between the API elements and the internal data fields that are used for operations with data by Acumatica ERP. If something has been changed in the schema of an Acumatica ERP form, the Content object that is returned by the Screen.GetSchema() method contains a different correspondence between the API elements and internal data fields than the correspondence for which the application is compiled, and the application fails. For example, suppose that a client application requests the customer ID by the Customer.CustomerSummary.CustomerID property. Suppose also that in an update of Acumatica ERP, the Customer ID element of the Customers form was renamed to Customer, and therefore it should be requested by using the Customer.CustomerSummary.Customer property from the API. The client application requests the customer ID by using the Customer.CustomerSummary.CustomerID property and fails. What the Screen-Based API Wrapper Is The screen-based API wrapper is a special wrapper designed to prevent the UI changes in the system from causing application failure. The wrapper works with any changes in the schema of an Acumatica ERP form. That is, the wrapper makes the application work regardless of the changes in the names of UI elements and the changes in the internal names of data fields and objects. The wrapper is distributed as the PX.Soap.dll file, which is installed automatically during Acumatica ERP installation. You can find the PX.Soap.dll file in the ScreenBasedAPIWrapper folder of your Acumatica ERP installation folder. The PX.Soap library, which the wrapper provides, includes the Helper.GetSchema() method, which you should use instead of the Screen.GetSchema() method of the screen-based web services API. For information on how to use the screen-based API wrapper, see To Use the Screen-Based API Wrapper. How the Screen-Based API Wrapper Works When the client application is executed for the first time and requests the schema of an Acumatica ERP form by using the Helper.GetSchema() method, the wrapper requests the schema from the Acumatica ERP screen-based web service by using the Screen.GetSchema() method of the screen-based API. The web service interacts with the Acumatica ERP import and export engine and returns the current schema of the form. The wrapper saves the schema in an XML file and returns the schema to the client application as a Content object. The client application uses this schema to work with Acumatica ERP. : Instead of the Helper.GetSchema() method you can use the Helper.ReuseStoredSchema() method to upload a schema that was saved earlier by the wrapper. The following diagram illustrates the way the screen-based API wrapper works during the first execution of a client application.

133 Working with the Screen-Based SOAP API 133 Figure: First execution of an application When the client application is executed for the second time and all subsequent times and it requests the schema of an Acumatica ERP form by using the Helper.GetSchema() method, the wrapper retrieves the XML schema that is saved locally and submits this schema to the Acumatica ERP screen-based web service by using the Screen.SetSchema() method of the screen-based API. The web service interacts with the Acumatica ERP import and export engine, which replaces the current schema of the form that is stored on the server with the one that was saved locally. The wrapper returns the schema that was saved locally to the client application. The client application uses the local schema to work with Acumatica ERP. : The schema that is submitted to Acumatica ERP by using the screen-based API wrapper is used on the server during the current session and is discarded after the end of the session. The following diagram illustrates the way the screen-based API wrapper works during the second execution and all subsequent executions of a client application.

134 Working with the Screen-Based SOAP API 134 Figure: Subsequent executions of the application : You should distribute the XML file with the schema along with your client application. If the wrapper has not found the XML file, it requests the new schema. The name of the XML file with the schema contains a hash code that depends on the WSDL description. If you update the WSDL description in your application, the wrapper works in the same way as it did during the first execution of the application and creates a new XML file with the schema. To Generate the WSDL File of the Web Services The WSDL description of the Acumatica ERP screen-based web services API contains the descriptions of the API objects and methods that you can use to access Acumatica ERP forms. Because of the connection of the API with Acumatica ERP forms, each generated WSDL description of this API reflects the current state of the system. That is, the WSDL description does not include any changes made to the system after the WSDL file was generated, and each time you change the system, you should regenerate the WSDL description and update your application accordingly. : You can prevent breaking changes in your application and omit regeneration of the WSDL description for each change in the system by using the screen-based API wrapper. For details on how to use the wrapper, see To Use the Screen-Based API Wrapper. For example, suppose that you generated a WSDL description of the web service that contains the definition of the CustomerID property, which corresponds to the Customer ID element on the Customers (AR303000) form. Further, suppose that you changed the name of the Customer ID element to Customer Identifier in a customization project. To access the Customer Identifier element on the form through the screen-based web services API, you need to regenerate the WSDL

135 Working with the Screen-Based SOAP API 135 description so that it contains the definition of the CustomerIdentifier property that corresponds to the Customer Identifier element, and update your application accordingly. You can generate the WSDL file of an Acumatica ERP web service in one of the following ways. To Generate a WSDL File for One Acumatica ERP Form If your application needs to work with only one Acumatica ERP form, you can generate the web service that provides access to only this form. To generate a WSDL file for a form, on the title bar of this form, click Tools > Web Service in the modern UI or Help > Web Service in the classic UI. This opens the page that contains the description of the web service, with the following URL: http(s)://<applicationpath>/soap/ <FormID>.asmx. In this URL, <ApplicationPath> is replaced with the actual URL of your application, and <FormID> is replaced with the ID of the form. For example, suppose that you generated a web service for the Customers form of the WebServiceAPITest application, which is accessed under a secure connection and is running on a local computer. The URL of this service is To Generate a WSDL File for Multiple Acumatica ERP Forms If your application needs to work with multiple Acumatica ERP forms, you can generate one web service that provides access to all needed forms. To generate a WSDL file for multiple forms, on the Web Services (SM207040) form, you should do the following: 1. Type the ID of the web service in the Service ID box of the Summary area of the form. This ID will be used in the URL of the generated service. 2. Select the Acumatica ERP forms that your application needs to use on the left pane of the form, and click Add to Grid for each form. 3. Select the types of integration these forms should provide (which can include importing data, exporting data, and submitting data) by selecting the appropriate check boxes (any combination of Import, Export, or Submit) for corresponding rows on the right pane of the form. 4. Click Generate. : The modules that expose the selected forms should be properly configured and the forms should open in a web browser. If a form could not be opened in a web browser, the web service definition will not be generated for this form. After the web service is generated, you can view the WSDL description by clicking View Generated on the form toolbar. This opens the page that contains the description of the web service with the following URL: http(s)://<applicationpath>/soap/<serviceid>.asmx. In this URL, <ApplicationPath> is replaced with the actual URL of your application, and <ServiceID> is replaced with the ID of the service that you specified in the Service ID box when configuring the service. For example, suppose that you generated a web service for multiple forms with the MYSTORE service ID for the WebServiceAPITest application, which is accessed under a secure connection and is running on a local computer. The URL of this service is Soap/MYSTORE.asmx. To Import the WSDL File Into the Development Environment When the WSDL file is generated, you must import it into your development environment to generate proxy classes. If necessary, see the documentation of your development environment to find out the correct way of building the proxy classes based on the WSDL definition. In this topic, you will find instructions on how to implement the proxy classes by using Visual Studio 2012 or later.

136 Working with the Screen-Based SOAP API 136 To Generate Proxy Classes from the WSDL Definition by Using Visual Studio 2012 or Later In Microsoft Visual Studio, create a new project as follows: a. Select File > New > Project. b. In the New Project window that appears, select the required template. c. Define the name of the project and solution, as shown in the figure below, and click OK. Add a web service reference to the project as follows: a. In the menu, select Project > Add Service Reference. b. In the Add Service Reference dialog box, which appears, click Advanced. c. In the Service Reference Settings dialog box, which appears, click Add Web Reference. d. In the URL box of the Add Web Reference dialog box, which appears, specify the URL of the web service (see item 1 in the following screenshot). : To get the URL of the service, on the Web Services (SM207040) form, select the needed web service in the Service ID box, click View Generated on the form toolbar, and copy the URL from the address line in the browser for the page that opens, such as localhost/webserviceapitest/soap/mystore.asmx. : You can make API calls to Acumatica ERP through HTTP if requirements to your application does not include secure data transfer between the application and Acumatica ERP. If you do not need to use HTTPS, use the HTTP address of the application instead of HTTPS, such as e. Click Go (2 in the screenshot) to make Visual Studio connect to the web service. : If your Acumatica ERP website uses a self-signed certificate, Visual Studio displays security alert windows with warnings on the certificate. Click Yes in these windows to proceed. f. In the Web reference name box, type the name of the web reference (3). This name will be used as a namespace for the web service classes generated by Visual Studio based on the WSDL description of the service. g. Click Add Reference (4) to add to the project the reference to the specified service.

137 Working with the Screen-Based SOAP API 137 Figure: Add Web Reference dialog box Visual Studio adds to the project the Web References folder with the web service reference in it, as shown in the following screenshot. Figure: Solution Explorer : If you need to update a web reference to the Acumatica ERP web service in a Visual Studio project, you can update the WSDL description in Acumatica ERP and update the web reference in the project by right-clicking the web reference in Solution Explorer and selecting Update Web Reference, as shown in the following screenshot.

138 Working with the Screen-Based SOAP API 138 Figure: Update Web Reference menu item 3. Rebuild the project. To Use the Screen-Based API Wrapper The screen-based SOAP API depends on the user interface of Acumatica ERP forms. That is, each generated WSDL description of this API includes the API elements that correspond to the current names of UI elements of the system. Therefore, if any changes have been made to the user interface of the system after the WSDL file was generated, the WSDL description will not include these changes, and the client application that uses this WSDL will fail when it works with the system. To prevent application failures and omit the regeneration of the WSDL description for each change of the user interface of the system, you can use the screen-based API wrapper, as described in this topic. You can find more information on the screen-based API wrapper in Screen-Based API Wrapper. To Use the Screen-Based Web Services API Wrapper in a Client Application 1. Add to your project a reference to PX.Soap.dll. : The PX.Soap.dll file is installed automatically during Acumatica ERP installation. You can find this file in the ScreenBasedAPIWrapper folder of your Acumatica ERP installation folder. 2. Use the Helper.GetSchema() method from the PX.Soap library in the code of your application instead of the corresponding Screen.GetSchema() method to obtain the schema of each form. For example, the following code retrieves the schema of the Customers (AR303000) form by using the screen-based API wrapper. Screen context = new Screen(); context.cookiecontainer = new System.Net.CookieContainer(); context.url = Properties.Settings.Default.MyStoreIntegration_MyStore_Screen; context.login ( Properties.Settings.Default.Login,

139 Working with the Screen-Based SOAP API 139 Properties.Settings.Default.Password ); AR303000Content custschema = PX.Soap.Helper.GetSchema<AR303000Content>(context); 3. Work with the retrieved Content object by using the standard screen-based web services API methods.

140 Working with Commands of the Screen-Based SOAP API 140 Working with Commands of the Screen-Based SOAP API To upload data to and from Acumatica ERP by using the screen-based SOAP API, you should define the sequence of commands for the system as it works with elements on an Acumatica ERP form. This sequence of commands reflects the sequence of actions to be executed for a data record as if the record is being manipulated by a user through an Acumatica ERP form. In This Chapter Commands for Retrieving the Values of Elements Selection of a Group of Records for Export Commands for Setting the Values of Elements Commands for Clicking Buttons on a Form Commands for Adding Detail Lines Commands for Pop-Up Dialog Boxes and Pop-Up Forms Commands for Pop-Up Panels Commands for Record Searching: Filter Service Command Commands for Record Searching: Key Command Commands for Record Searching: Custom Field Commands That Require a Commit Commands for Working with Attachments Commands for Working with Multi-Language Fields Commands for Retrieving the Values of Elements You configure the sequence of commands that should be executed during data import, data export, or data processing through the web service by using an array of objects of the Command type. As you specify this sequence of commands, when you need to reflect obtaining the value of an element on a form, you should use a Field object. To specify the element whose value you need to obtain, you can do one of the following: Select the needed Field object from the subobjects of the Field type of a Content object that corresponds to the needed Acumatica ERP form Create an object of the Field type and specify its properties Both of these ways are described in detail in the following sections of this topic. Selection of the Fields Available in a Content Object If you want to obtain the value of an element on an Acumatica ERP form, you can select the needed Field object from the subobjects of the Field type of the Content object that corresponds to the form. For example, if you want to export the values of the Inventory ID and elements on the Stock Items (IN202500) form, you can use the following code. //stockitemsschema is an IN202500Content object

141 Working with Commands of the Screen-Based SOAP API 141 var commands = new Command[]... stockitemsschema.stockitemsummary.inventoryid, stockitemsschema.stockitemsummary.,... ; Field Object Creation You can retrieve the values of not only the fields that are available on the Acumatica ERP form, but also the data fields of the data access classes (DACs) underlying the form. Some of these data fields are not available directly through the elements of the form. That is, you cannot select the needed Field object among the subobjects of the Content object. If you want to retrieve the value of an element that is not available on the form, you can create a Field object and specify its properties so that it specifies the needed data field of the DAC. You should specify the name of the object that corresponds to the needed DAC as the ObjectName and type the name of the data field in FieldName. The following code illustrates the creation of a Field object for the LastModifiedDateTime data field (which specifies the date and time when a record was modified) that is available through the DAC underlying the StockItemSummary object of the Stock Items form. : To find the names of the data fields that belong to DACs, you should read the applicable Acumatica ERP code. You can find the source code of Acumatica ERP on the Source Code (SM204570) form or in <ApplicationFolder>\App_Data\CodeRepository\PX.Objects\, where <ApplicationFolder> is replaced with the path to the folder of the Acumatica ERP application instance. You can learn the details of working with the source code of Acumatica ERP in the T300 Acumatica Customization Platform training course. //stockitemsschema is an IN202500Content object var commands = new Command[]... new Field ObjectName = stockitemsschema.stockitemsummary.inventoryid.objectname, FieldName = "LastModifiedDateTime",... ; : You can create Field objects for the elements that are available on a form. If you want to create a Field object for an element available on the form, set the ObjectName property to the ObjectName property of the needed subobject of the Field type of a Content object, and set the FieldName property to the FieldName property of this Field object. The following code illustrates the creation of a Field object for the InventoryID field of the Stock Items form. new Field ObjectName = stockitemsschema.stockitemsummary.inventoryid.objectname, FieldName = stockitemsschema.stockitemsummary.inventoryid.fieldname Selection of a Group of Records for Export Each record in the system is identified by the values of the key elements on the applicable Acumatica ERP form. For example, a record on the Stock Items (IN202500) form is identified by the value of the Inventory ID key element. Key elements are available through the Summary object of a form. You can use the key element or elements of the form to select all records of the form for export. The other way to specify a group of records for export is to use the elements of the Summary area of the form in custom filters. Both ways of selecting records are described in detail below.

142 Working with Commands of the Screen-Based SOAP API 142 Export of All Records from a Form If you want to export every record from an Acumatica ERP form, in the array of Command objects that you pass to the Export() method, you should insert the service command of the EveryValue type for the corresponding key element on the form. The EveryValue service command is available through the ServiceCommands subobject of the Summary object of the Content object that corresponds to the form. This service command specifies that every record of the specific type should be processed during export. For example, if you want to export all stock item records available in the system, you should insert the EveryInventoryID service command, as the following code shows. //stockitemsschema is an IN202500Content object var commands = new Command[] stockitemsschema.stockitemsummary.servicecommands.everyinventoryid,... ; Export of a Group of Records from a Form You can filter the data available in the Acumatica ERP database to select the records for export. For example, you can configure the system to export only the records that have a particular status. To define a filter for the data being exported, you should create an array of Filter objects and add the needed filters to it. To define a filter, you should specify: The UI element whose value should be used for filtering (in the Field property of the Filter object). The value or values with which the value of the element should be compared (in the Value property or Value and Value2 properties of the Filter object). The condition of comparison (in the Condition property of the Filter object). If you define multiple filters in the array, you should also specify the logical operator (either And or Or) that defines how to apply these filters. If filters are passed to an Export() method, during export, the system selects only the records that conform to the specified condition (or conditions) and exports only these records. For example, suppose that you want to export only the stock item records that have the Active status. In this case, you can specify the filtering condition that the Item Status element should be equal to Active, as the following code shows. During export, the system processes the records that match the filtering conditions and exports only the records with the Active status. var filters = new Filter[] new Filter Field = stockitemsschema.stockitemsummary.itemstatus, Condition = FilterCondition.Equals, Value = "Active", ; For filtering records, you can use either the data fields of the Summary object of the form from which you are exporting data, or the data fields of the data access class (DAC) underlying the Summary object. (In Acumatica Framework, this DAC is called the main DAC of the primary data view.) If a data field of the DAC is not available directly through the elements of the Summary object, you cannot select the needed Field object among the subobjects of a Content object, as the previous code example shows for the ItemStatus data field. Instead, you should create a new Field object and specify its properties as follows: Specify the name of the Summary object as ObjectName (that is, the object name

143 Working with Commands of the Screen-Based SOAP API 143 that corresponds to the object to which the key data field belongs), and type the name of the data field as FieldName in the code directly. The following example shows filtering by the LastModifiedDateTime data field (which specifies the date and time when a record was modified) that is available through the DAC underlying the StockItemSummary object of the Stock Items form. new Filter Field = new Field ObjectName = stockitemsschema.stockitemsummary.inventoryid.objectname, FieldName = "LastModifiedDateTime", Condition = FilterCondition.Greater, Value = DateTime.Now.AddMonths(-1).ToLongDateString() Commands for Setting the Values of Elements As you specify the sequence of commands in an array of Command objects, when you need to specify the value of an element on a form, you should use Value commands. To set the value of an element on a form, you should do the following: 1. Create a Value object. 2. Specify the value of the element on the form in the Value property of the created Value object. 3. Specify the element on the form whose value should be set by using the LinkedCommand property of the Value object. The following code illustrates setting the value of the Customer Name element on the Customers (AR303000) form. //custschema is an AR303000Content object var commands = new Command[]... new Value Value = "John Good", LinkedCommand = custschema.customersummary.customername,... Commands for Clicking Buttons on a Form As you specify the sequence of commands in an array of Command objects, when you need to reflect the clicking of a button on a form (such as clicking Save, Delete, or Release to perform the action on a document), you should use the corresponding Action command. Actions are available for all buttons on the form. In an array of Command objects, to use an Action command, you have to select the needed action in the Actions subobject of the Content object that corresponds to the form. Actions have names that are similar to the names of the buttons on the form. The following code reflects the clicking of the Save button on the Customers (AR303000) form in a command. //custschema is an AR303000Content object var commands = new Command[]

144 Working with Commands of the Screen-Based SOAP API 144 ;... custschema.actions.save,... Commands for Adding Detail Lines When you need to add a detail line to an Acumatica ERP form, you can use one of the following approaches: Add detail lines one by one on the Details tab of the form. For example, on the Sales Orders (SO301000) form, you can click Add Row on the Document Details tab and specify the values of the elements of each detail line. Add detail lines by using a pop-up panel. For example, on the Shipments (SO302000) form, you can use the Add Sales Order pop-up panel, which is opened when you click Add Order on the table toolbar of the Document Details tab. In this topic, you will find the description of the NewRow command, which imitates the first approach listed above in the screen-based API. The second approach is described in Commands for Pop-Up Panels. NewRow Service Command When you are specifying the sequence of commands in an array of Command objects for a processing method and you need to add a new detail line to a document, you should use commands as follows: 1. To add a new row, use the NewRow service command, which is an available service command of the Details subobject of a Content object. 2. To specify the values of the elements of the created row, use the Value commands corresponding to the elements. The following code shows an example of an order line being added to a sales order. //orderschema is an SO301000Content object var commands = new Command[]... orderschema.documentdetails.servicecommands.newrow, new Value Value = "AALEGO500", LinkedCommand = orderschema.documentdetails.inventoryid, new Value Value = "10.0", LinkedCommand = orderschema.documentdetails.quantity, new Value Value = firstitemuom, LinkedCommand = orderschema.documentdetails.uom,...

145 Working with Commands of the Screen-Based SOAP API 145 Commands for Pop-Up Dialog Boxes and Pop-Up Forms In this topic, you will learn how to enter data to pop-up dialog boxes and pop-up forms by using the screen-based SOAP API. Pop-Up Dialog Boxes When you update specific fields on some forms under certain circumstances, the system displays popup dialog boxes where you need to respond to a question (by clicking a button) in order to proceed. For example, when you update the Customer Class value on the Customers (AR303000) form for an existing customer, the system displays a Warning dialog box with the text Please confirm if you want to update current customer settings with the customer class defaults. Otherwise, original settings will be preserved. and the Yes and No buttons. You should click Yes to proceed with changing the customer class. When you are specifying the sequence of commands in an array of Command objects for a processing method and you need to specify an answer to a question that would appear in a pop-up dialog box if the data was being entered manually, you should create a Value command and set its properties as follows: In the Value property, specify the answer that you select in the dialog box during manual entry of a record. In the LinkedCommand property, use a DialogAnswer service command, which is available through the ServiceCommands subobject of an object that invokes the appearance of the pop-up dialog box. You should insert this Value command directly before the field that causes the appearance of the dialog box. The following code shows how you would update the customer class in an existing customer record on the Customers form. //custschema is an AR303000Content object var commands = new Command[]... new Value Value = "Yes", LinkedCommand = custschema.customersummary.servicecommands.dialoganswer, new Value Value = "INTL", LinkedCommand = custschema.generalinfofinancialsettings.customerclass,... ; Pop-Up Forms When you click specific buttons on some forms, the system opens a pop-up window with another Acumatica ERP form where you can specify or edit the values of elements as needed. For example, if you click Add Contact on the Contacts tab of the Customers form, the system displays the Contacts (CR302000) form. : Do not confuse a situation when the system opens a pop-up window that contains an Acumatica ERP form with a situation when the system opens a pop-up panel (where you can specify needed settings but no Acumatica ERP form is shown). A pop-up window that contains a form has an address line in the

146 Working with Commands of the Screen-Based SOAP API 146 browser where you can see the ID of the form. A pop-up panel looks like a dialog box and does not have an address line. When you are specifying a sequence of commands in an array of Command objects for a processing method and you need to reflect the setting of values of elements of a pop-up form in these commands, you should perform the following steps: Call an action that invokes a pop-up form as follows: a. By using the GetSchema() method of the PX.Soap.Helper class, get the Content object that corresponds to the form that invokes a pop-up form. b. Specify the command that invokes a pop-up form in the sequence of commands by using the corresponding Action command. c. Submit this sequence of commands to the form that invokes the pop-up form by using the corresponding Submit() method. Specify the values on the pop-up form as follows: a. By using the GetSchema() method of the PX.Soap.Helper class, get the Content object that corresponds to the form that appears as a pop-up. b. Specify the list of commands that specifies the values of needed elements of the pop-up form. c. Add the Save action to the list of commands. d. Submit this sequence of commands to the pop-up form by using the corresponding Submit() method. The following code illustrates the setting of the values of the Contacts form, which appears as a pop-up after the user clicks Add Contact on the Contacts tab of the Customers form. //context is a Screen object //custschema is an AR303000Content object var commands = new Command[] new Value Value = customerid, LinkedCommand = custschema.customersummary.customerid, custschema.actions.newcontact ; context.ar303000submit(commands); //contschema is a CR302000Content object commands = new Command[] new Value Value = "Green", LinkedCommand = contschema.detailssummary.lastname, contschema.actions.save, ; context.cr302000submit(commands); Commands for Pop-Up Panels In some instances, when you click a specific button on some form, the system opens a pop-up panel, where you can set the values of needed elements. This pop-up panel looks like a dialog box and does not contain an Acumatica ERP form. For example, if you click Add Order on the table toolbar of the

147 Working with Commands of the Screen-Based SOAP API 147 Document Details tab of the Shipments (SO302000) form, the system displays the Add Sales Order pop-up panel. : Do not confuse a situation when the system opens a pop-up panel (where you can set needed settings but no Acumatica ERP form is shown) with a situation when the system opens a pop-up window that contains an Acumatica ERP form. A pop-up window that contains a form has an address line in the browser where you can see the ID of the form. A pop-up panel looks like a dialog box and does not have an address line. When you are specifying a sequence of commands in an array of Command objects for a processing method and you need to reflect the setting of values of elements on a pop-up panel in these commands, you should perform the following steps: 1. Insert the DialogAnswer service command of the pop-up panel object before the action that opens the panel, and set the Commit property to true for this command. 2. Specify the action that opens the pop-up panel, and set the Commit property of the action to true. 3. Specify the values of elements as needed on the pop-up panel. 4. Specify the action that closes the panel, and set the Commit property of the action to true. : For some pop-up panels, you need to specify only one action to select values from the pop-up panel. For example, you need to specify only one action if you are creating a shipment by using the Create Shipment action on the Sales Orders (SO301000) form, which displays the Specify Shipment Parameters pop-up panel. The following code illustrates the setting of the values on the Add Sales Order pop-up panel, which appears after a user clicks Add Order on the toolbar of the Document Details tab of the Shipments form. //shipmentschema is a SO302000Content object //Force a commit for the SelectSO action var selectsowithcommit = shipmentschema.actions.selectso; selectsowithcommit.commit = true; //Force a commit for the AddSO action var addsowithcommit = shipmentschema.actions.addso; addsowithcommit.commit = true; //Configure the list of commands var commands = new Command[]... //Open the Add Sales Order panel new Value Value = "OK", LinkedCommand = shipmentschema.addsalesorderoperation.servicecommands.dialoganswer, Commit = true, selectsowithcommit, //Specify the first order number on the Add Sales Order panel //and get the values of item elements new Value Value = firstordernbr, LinkedCommand = shipmentschema.addsalesorderoperation.ordernbr, new Value Value = "True", LinkedCommand = shipmentschema.addsalesorder.selected, shipmentschema.addsalesorder.inventoryid, shipmentschema.addsalesorder.quantity, shipmentschema.addsalesorder.openqty, shipmentschema.addsalesorder.line,

148 Working with Commands of the Screen-Based SOAP API 148 ; //context is a Screen object //Submit the commands to the form var solines = context.so302000submit(commands); //Select all items of the first order for shipment List<Command> commandlist = new List<Command>(); for (int index = 0; index < solines.length; index++) commandlist.add(new Value Value = index.tostring(), LinkedCommand = shipmentschema.addsalesorder.servicecommands.rownumber ); commandlist.add(new Value Value = "True", LinkedCommand = shipmentschema.addsalesorder.selected, Commit = index < solines.length - 1 ); //Add items to the shipment commandlist.add(addsowithcommit); context.so302000submit(commandlist.toarray()); Commands for Record Searching: Filter Service Command The system uses the key element or elements on a form to find records that belong to different documents. For example, on the Invoices and Memos (AR301000) form, there are two key elements: Type and Reference Nbr. If you know the values of the key element or elements of the needed record, you can select this record for update by specifying the key values in the sequence of commands that you pass to the processing method of the web services API. In the sequence of commands, you should first specify key element or elements to identify the record that you are going to update. After you have specified the values of key element or elements, you should specify the values of other elements in the order in which you would specify them on the form. If you do not know the values of the key element or elements of the needed record, you can update records in the system by searching for them using their unique field values that you know. For example, you can identify customers by addresses or phone numbers. To search for a record, you have to imitate the use of a column of a Select dialog box, declare a custom key, or declare a custom field in the sequence of commands that you pass to a processing method. In this topic, you will find a detailed description of the Filter service command, which imitates the use of a selector column. You can find a description of two other approaches in Commands for Record Searching: Key Command and Commands for Record Searching: Custom Field. Filter Service Command Selector columns on an Acumatica ERP form appear when a user clicks the Magnifier icon of the key element of the form to bring up the Select dialog box. Service commands for selector columns have the Filter prefix in their names. For example, to search for a customer record, you can use the FilterCity, FilterCountry, Filter , and FilterPhone1 service commands. To use a column of a Select dialog box for a search, you have to do the following: 1. Create a Field object, and initialize its properties with the values of the properties of the key field.

149 Working with Commands of the Screen-Based SOAP API Concatenate the FieldName property of this object (which is now equal to the value of the FieldName property of the key field) with! and the FieldName property of the needed Filter service command. 3. In the Value command in the array of Command objects, set the Value property to the value that should be used for the search and the LinkedCommand property to the created Field object. For example, the following code searches for a customer record by address. //custschema is an AR303000Content object Field customeridselector = custschema.customersummary.customerid; customeridselector.fieldname += "!" + custschema.customersummary.servicecommands.filter .fieldname; var commands = new Command[] new Value Value = "demo@gmail.com", LinkedCommand = customeridselector,... ; : If you need to get the value of the field that was used for a search as a result of the processing, you should assign an initial FieldName to the field before getting the value. For example, the following code shows how to get the value of the Customer ID element after you have modified the corresponding field for the search. //custschema is an AR303000Content object //Save the initial field name of the CustomerID field string initialcustomeridfieldname = custschema.customersummary.customerid.fieldname; //Configure the command that searches for a customer record //by using the Filter service command Field customeridselector = custschema.customersummary.customerid; customeridselector.fieldname += "!" + custschema.customersummary.servicecommands.filter .fieldname; //Configure the list of commands var commands = new Command[] //Search for the needed customer record new Value Value = customermaincontact , LinkedCommand = customeridselector, ; //Do the needed modifications and save changes on the form... //context is a Screen object //Submit commands to the form context.ar303000submit(commands); //Assign an initial field name to the CustomerID field custschema.customersummary.customerid.fieldname = initialcustomeridfieldname; //Get the customer ID commands = new Command[] custschema.customersummary.customerid ; //Submit commands to the form AR303000Content customer = context.ar303000submit(commands)[0];

150 Working with Commands of the Screen-Based SOAP API 150 Commands for Record Searching: Key Command To search for a record, you have to imitate the use of a column of a Select dialog box, declare a custom key, or declare a custom field in the sequence of commands that you pass to a processing method. In this topic, you will find a detailed description of the use of the Key command, which you use to declare a custom key. You can find descriptions of two other approaches in Commands for Record Searching: Filter Service Command and Commands for Record Searching: Custom Field. Key Command If you specify the value of key elements on an Acumatica ERP form, the system does not change the current record in the system; instead, it searches for the record, which is identified by the values of the key elements, and selects this record. By using custom keys, you can make some elements on an Acumatica ERP form work as key elements. You can specify custom keys to search for a record or a detail line. You can use the fields of the summary object and the detail objects, but not the fields that belong to other objects, as custom key fields. For example, you can find the needed customer record in the system by using the CustomerName field of the AR303000CustomerSummary object of the Customers (AR303000) form as the custom key, but you cannot find the record by using the field of the AR303000GeneralInfoMainContact object as the custom key. To specify a custom key, you have to define the key by using the Key command as follows: 1. Create a Key command by using the operator new. 2. To specify the element that should be used as a custom key, set the ObjectName and FieldName properties of the created Key command to the values of the ObjectName and FieldName properties of the field corresponding to the element. 3. To specify the value of the custom key, set the Value property of the created Key command to the needed value in the format ='<Key value>', where you should replace <Key value> with the needed value of the key. Below is an example of the Key command that declares the Warehouse column as the custom key on the Document Details tab of the Sales Orders (SO301000) form. new Key ObjectName = orderschema.documentdetails.warehouse.objectname, FieldName = orderschema.documentdetails.warehouse.fieldname, Value = "='MAIN'", Commands for Record Searching: Custom Field To search for a record, you have to imitate the use of a column of a Select dialog box, declare a custom key, or declare a custom field in the sequence of commands that you pass to a processing method. In this topic, you will find a detailed description of the declaration of a custom field. You can find descriptions of two other approaches in Commands for Record Searching: Filter Service Command and Commands for Record Searching: Key Command. Custom Field Acumatica ERP does not include Filter service commands for all selector columns that are available on Acumatica ERP forms. To use the needed selector column for record searching, you can create a custom field as follows: 1. Initialize the properties of a Field object with the values of the properties of the key field.

151 Working with Commands of the Screen-Based SOAP API Concatenate the FieldName property of this object (which is now equal to the value of the FieldName property of the key field) with! and the internal name of the selector column that you are going to use for the search. The internal name of the selector column is equal to the value of the FieldName property of the corresponding element on the form. 3. In the Value command in the array of Command objects, set the Value property to the value that should be used for the search and the LinkedCommand property to the created Field object. For example, the following code searches for a sales order by order number. //orderschema is an SO301000Content object var searchcustomerorder = orderschema.ordersummary.ordernbr; searchcustomerorder.fieldname += "!" + orderschema.ordersummary.customerorder.fieldname; var commands = new Command[] new Value Value = "SO", LinkedCommand = orderschema.ordersummary.ordertype, new Value Value = "SO ", LinkedCommand = searchcustomerorder,... Commands That Require a Commit There are two types of elements on an Acumatica ERP form: elements with a commit, and elements without a commit. A commit is an action initiated by the form that, when triggered, sends the data to the server. On the server, the commit causes all data on the form to be updated, including the insertion of default values and the recalculation of the values of elements on the form. A commit is a costly operation that causes the browser to make requests to the server and takes server time. As such, a commit is invoked for only a limited number of elements: mainly the key elements and the elements the other elements depend on. In a Visual Studio project, if you specify the value of an element for which the system performs a commit by using a Value command, the Commit property of the LinkedCommand property (which specifies this element) is automatically set to true. You can check the value of the Commit property when you are debugging an application if you insert a breakpoint in the code after an array of commands has been configured. In the following screenshot, you can see that for the command that sets the value of the Customer ID element on the Customers (AR303000) form, the Commit property of the LinkedCommand is set to true. (The Customer ID element has the internal field name AcctCD.)

152 Working with Commands of the Screen-Based SOAP API 152 Figure: Commit property If the Commit property is false, the element is filled in with data but no update of the form is invoked. If the Commit property is true, after the element is filled in, the commit is invoked on the server and the form is updated. For example, when you select a customer class on the Customers form, the system assigns values to the elements related to customer class settings, such as Statement Cycle ID and Country. When you configure a sequence of commands for setting the values of elements on the Customers form, for elements such as Customer, the system automatically sets the Commit property of LinkedCommand to true. In most cases, when you compose the sequence of commands, you can use the values of the Commit property that are set by default. However, you may need to force the system to invoke a commit to the server for example, when you need to commit the value of the field before entering another field value. In such cases, you should set the Commit property to true for the command or action. Commands for Working with Attachments In Acumatica ERP, you can attach files to records on Acumatica ERP forms and to detail lines on master-detail forms. To obtain a file attached to the selected record or detail line through the web services API, you specify the Value command in the array of Command objects as follows: In the FieldName property, you specify the name of the file that should be obtained. In the LinkedCommand property, you specify the needed Attachment service command. To work with a file attached to a form, you use the Attachment service command of the object that corresponds to the Summary object. For example, to obtain a file attached to a stock item record on the Stock Items (IN202500) form, you use the Attachment service command of the IN202500StockItemSummary object. To work with the file attached to a detail line of a master-detail form, you use the Attachment service command of the object that corresponds to the Details object. For example, to obtain the file attached to a warehouse detail line of a stock item on the Stock Items form, you use the Attachment service command of the IN202500WarehouseDetails object.

153 Working with Commands of the Screen-Based SOAP API 153 The following code shows how to retrieve the file attached to a stock item record on the Stock Items form. //stockitemsschema is an IN202500Content object var commands = new Command[] new Value Value = "AAMACHINE1", LinkedCommand = stockitemschema.stockitemsummary.inventoryid, new Value FieldName = "T2MCRO.jpg", LinkedCommand = stockitemschema.stockitemsummary.servicecommands.attachment ; //context is a Screen object var stockitemattachment = context.in202500export(commands, null, 1, false, true); Commands for Working with Multi-Language Fields For some text boxes on Acumatica ERP forms, users can type values in multiple languages if multiple locales are configured in Acumatica ERP. For example, if your Acumatica ERP instance has English and French locales activated and multilingual user input configured, you can specify the value of the box on the Stock Items (IN202500) form in English and French. For the list of elements that support multiple languages, see Boxes that Have Multi-Language Support. For details on how to turn on multilingual user input, see Enabling Multilingual User Input. Specifying Localized Values of a Multi-Language Field When you need to specify localized values of a text box by using the screen-based SOAP API, you specify the value of the field that corresponds to the box as a string in JSON format with the localized values. In this string, you use the two-letter ISO code of the language with which the value should be associated. In the example that is mentioned at the beginning of the topic, if you need to specify values in English and French in the box on the Stock Items form, you specify the value of the field of the StockItem entity in the following format: [en:english description,fr:french description], as shown in the following code fragment. //stockitemschema is an IN202500Content object new Value Value = "[en:item,fr:pièce]", LinkedCommand = stockitemschema.stockitemsummary. : In the JSON-formatted string, you should specify the actual values of the field in all languages that are configured for multilingual user input. If you specify the values of the field in particular languages, the values of the field in other languages configured for multilingual user input become empty. For example, suppose that in your instance of Acumatica ERP, multi-language fields can have values in English and French. If you pass the value of a field in the following format [en:english description], the French value of the field becomes empty. If you specify the value of a multi-language field as plain text, this text is saved as the value of the corresponding box in the current language of Acumatica ERP (that is, either the default language of the instance or the language that you have specified by using the SetLocaleName() method). For details on how to specify the locale through the screen-based SOAP API, see SetLocaleName() Method.

154 Working with Commands of the Screen-Based SOAP API 154 Retrieving Localized Values of a Multi-Language Field If you need to retrieve localized values of a text box that supports multiple input languages, you retrieve the value of an internal field that contains all localized values of the text box and has the Translations suffix in its field name. To specify the field name and the object name of the needed internal field with localized values, you specify the field name and the object name of the multi-language text box and append Translations to the field name. For example, the following code shows the command that you should use to retrieve the localized values of the element of the Stock Items form. //stockitemschema is an IN202500Content object new Field ObjectName = stockitemsschema.stockitemsummary..objectname, FieldName = stockitemsschema.stockitemsummary..fieldname + "Translations" The returned value of a Translations field is a string in JSON format with the available localized values of the field. The language to which the value belongs is identified by the two-letter ISO code of the language. For example, suppose that the element of the Stock Items form has the value Item in English and Pièce in French. In this case, the value of the DescrTranslations field, which corresponds to the element, is the following string: [en:item,fr:pièce].

155 Configuring Push Notifications 155 Configuring Push Notifications Acumatica ERP provides push notifications that make it possible for the external applications to track the changes in the data in Acumatica ERP. That is, you can configure Acumatica ERP to send notifications to a destination (such as an HTTP address) when specific data changes in Acumatica ERP. The external application can receive these notifications and process the information on the data changes, if necessary. With push notifications, the external application doesn't need to continually poll for the data to find out whether there are any changes in this data, which helps improve the performance of the external application. In this chapter, you can find information on how to configure Acumatica ERP to send push notifications. In This Chapter Push Notifications To Configure Push Notifications Recommendations for the Data Queries To Process Failed Notifications Push Notification Destinations Push Notification Format Push Notifications Push notifications are notifications in JSON format that are sent by Acumatica ERP to notification destinations when specific data changes in Acumatica ERP. External applications can receive the notifications and process them to retrieve the information about changes. : If you have installed a new version of Acumatica ERP or updated your Acumatica ERP instance by using the Acumatica ERP Configuration Wizard, push notifications are enabled in Acumatica ERP automatically. If you have updated your Acumatica ERP instance through the web interface, you need to manually enable push notifications in Acumatica ERP, as described in To Enable Push Notifications Manually in the Installation Guide. If you need to enable push notifications on the Acumatica ERP instances in a cluster, you should follow the instructions in To Enable Push Notifications in a Cluster in the Installation Guide. To work with Acumatica ERP push notifications, you need to configure the following items: The data query that defines the data changes for which Acumatica ERP should send notifications The destination to which Acumatica ERP should send notifications The way the external application processes the notifications The definition of the push notification in Acumatica ERP, which specifies the data query and the notification destination The following diagram illustrates the sending of a push notification. In the diagram, rectangles with a red border indicate the items that you need to configure to receive push notifications when changes occur.

156 Configuring Push Notifications 156 Figure: Sending a push notification Data Query The data query can be defined by either a generic inquiry or a built-in definition (which is a data query defined in code). For details on generic inquiries, see Managing Generic Inquiries. For information on how to create a built-in definition, see To Create a Built-In Definition in the Acumatica Framework Development Guide. You can define multiple queries for one notification destination. The data query should adhere to the recommendations described in Recommendations for the Data Queries. Notification Destination The following predefined notification destinations are provided: webhook (HTTP address), message queue, or SignalR hub. For more information on the predefined notification destinations, see Push Notification Destinations. You can also create your own destination type, as described in To Create a Custom Destination Type in the Acumatica Framework Developer Guide. Processing of the Notifications in the External Application The external application can process the notifications and extract the information about the data changes. Acumatica ERP sends notifications to notification destinations in JSON format. For details on the format of the notifications, see Push Notification Format. If your application watches notifications in the SignalR hub, you need to connect to the hub, as described in To Connect to the SignalR Hub. Definition of the Push Notification In the definition of the push notification on the Push Notifications (SM302000) form, you specify the notification destination and the data queries for which the notifications should be sent. For details on the setup of the push notifications, see To Configure Push Notifications. Recommendations for the Data Queries For optimal results, follow these recommendations when you create each data query for which you want to configure push notifications: Do not use aggregation and grouping in the query; Acumatica ERP does not guarantee that push notifications will work correctly with such queries. Do not use joins of multiple detail tables in the query because this may cause the system to hang. If you need to join multiple tables, use a left outer join in the data query, because if you use other joins, the system does not send notifications when the top-level entities are removed.

157 Configuring Push Notifications 157 Use as simple a data query as possible. For a query defined by using a generic inquiry, do not use a formula on the Results Grid tab of the Generic Inquiry (SM208000) form. Push Notification Destinations When you configure a push notification on the Push Notifications (SM302000) form of Acumatica ERP, you select the type of the notification destinations, which can be any of the predefined types described in this topic. You can also create your own destination type, as described in To Create a Custom Destination Type in the Acumatica Framework Developer Guide. Webhook A webhook is an HTTP address to which Acumatica ERP sends HTTP POST requests with notification information. For this destination type, you specify a valid HTTP address (such as localhost:80/main.aspx?pushqueue) in the Address box on the Push Notifications (SM302000) form. For security reasons, you can specify a header of the HTTP request in the Header Name and Header Value boxes. If Acumatica ERP cannot send notifications to the HTTP address, Acumatica ERP logs information on the failed notifications and displays these notifications on the Process Push Notifications (SM502000) form. You can resend the failed notifications for two days, after which the notifications are removed from the Acumatica ERP database. For details on how to resend notifications, see To Process Failed Notifications. Message Queue The message queue is a local or remote private Microsoft message queue. You specify the address of the message queue (such as MyComputer\private$\TestQueueForPushNotificatons) in the Address box on the Push Notifications (SM302000) form. For information on how to configure a private Microsoft message queue, see the Microsoft documentation. The message queue is the most reliable destination type protected from network failures. However, if Acumatica ERP cannot send notifications to the message queue for some reason, Acumatica ERP logs information about the failed notifications and displays these notifications on the Process Push Notifications (SM502000) form. You can resend the failed notifications for two days, after which the notifications are removed from the Acumatica ERP database. For information on how to resend notifications, see To Process Failed Notifications. SignalR Hub The SignalR hub is the destination type implemented in Acumatica ERP by using the ASP.NET SignalR library. The address of this destination type is PushNotificationsHub, which is filled in automatically in the Address box on the Push Notifications form. This destination type can be used if you can expose neither an HTTP address (webhook) nor a message queue to receive push notifications. If Acumatica ERP is configured to send notifications to the SignalR hub, the external application can connect to Acumatica ERP through websoket or a long-polling mechanism and receive notifications through this connection. If multiple external applications are connected to the SignalR hub, they receive notifications simultaneously. For information on how to connect your application to the SignalR hub of Acumatica ERP, see To Connect to the SignalR Hub in the Acumatica Framework Developer Guide. The SignalR hub destination type is not reliable: If the connection fails or there are no clients connected to the SignalR hub when a notification comes, this notification will not be sent and it cannot be resent later.

158 Configuring Push Notifications 158 Push Notification Format Acumatica ERP sends push notifications in JSON format. This topic describes the structure of the notifications. Elements The push notifications that Acumatica ERP sends include the following elements in JSON format. Element Inserted The rows that are new in the results of the query execution. Deleted The rows that were in the results of the query execution but are missing after the latest data transaction. You can compare the Inserted and Deleted rows to identify the rows that have been updated. Query The query for which Acumatica ERP has produced the notification. The value of the element can be either the name of the generic inquiry or the name of the class with the built-in definition. CompanyId The name of the company. Id The unique identifier of the data transaction in Acumatica ERP that has initiated the notification. The external application can use this identifier to omit duplicated notifications. TimeStamp The long value that corresponds to the date and time when the transaction that initiated the notification happened in Acumatica ERP. By using the value of this element, the external application can define the order of notifications. AdditionalInfo Any additional information that is added to the notification. For more information on how to add additional information to push notifications, see To Add Additional Information to Push Notifications in the Acumatica Framework Development Guide. Example Suppose that push notifications are configured for the Stock Items: Last Modified Date generic inquiry (which displays the InventoryID, StockItem, ItemStatus, and InventoryItem_lastModifiedDateTime columns). Acumatica ERP sends the following notification when the status of the AACOMPUT01 inventory item has been changed from Active to Inactive. "Inserted": [ "InventoryID":"AACOMPUT01", "StockItem":true, "ItemStatus":"Inactive", "InventoryItem_lastModifiedDateTime":" T15:16:23.1" ], "Deleted": [ "InventoryID":"AACOMPUT01", "StockItem":true, "ItemStatus":"Active", "InventoryItem_lastModifiedDateTime":" T15:16:23.103" ], "Query":"Stock Items: Last Modified Date", "CompanyId":"Company", "Id":"1af4d f2-a2ec-50b67f577c6c", "TimeStamp": ,

159 Configuring Push Notifications 159 "AdditionalInfo": To Configure Push Notifications To configure push notifications, you use the Push Notifications (SM302000) form. Before You Proceed : If you have installed a new version of Acumatica ERP or updated your Acumatica ERP instance by using the Acumatica ERP Configuration Wizard, push notifications are enabled in Acumatica ERP automatically. If you have updated your Acumatica ERP instance through the web interface, you need to manually enable push notifications in Acumatica ERP, as described in To Enable Push Notifications Manually in the Installation Guide. If you need to enable push notifications on the Acumatica ERP instances in a cluster, you should follow the instructions in To Enable Push Notifications in a Cluster in the Installation Guide. You need to define the data query or data queries for which Acumatica ERP should send notifications on data changes. Each data query can be defined by either a generic inquiry or a built-in definition. For details on generic inquiries, see Managing Generic Inquiries. For information on how to create a builtin definition, see To Create a Built-In Definition in the Acumatica Framework Development Guide. For details on defining the data queries, see Recommendations for the Data Queries. You should also identify the notification destination that your external application will scan, which can be one of the following: webhook (HTTP address), message queue, or SignalR hub. For more information on the notification destinations, see Push Notification Destinations. You should configure your external application so that it can process notifications sent to the destination. To Send Notifications to an HTTP Address 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Push Notifications (SM302000). 2. In the Destination Name box, type the name of the target notification destination, which can be the name of your external application. 3. In the Destination Type box, select Webhook. 4. In the Address box, type the HTTP address to which Acumatica ERP should send the push notifications, such as 5. Optional: In the Header Name and Header Value boxes, specify the header of the HTTP POST request in which Acumatica ERP sends the notification. 6. For each generic inquiry for which you want Acumatica ERP to send notifications on changes in the inquiry results, do the following: 7. a. On the table toolbar of the Generic Inquiries tab, click Add Row. The new row has the Active check box selected. b. In the Inquiry Title column of the added row, select the generic inquiry for which you want Acumatica ERP to send notifications. For each built-in definition for which you want Acumatica ERP to send notifications on changes in the results, do the following: a. On the table toolbar of the Built-In Definitions tab, click Add Row. The new row has the Active check box selected.

160 Configuring Push Notifications 160 b. 8. In the Class Name column of the added row, select the class that defines the data query for which you want Acumatica ERP to send notifications. On the form toolbar, click Save. To Send Notifications to a Message Queue 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Push Notifications (SM302000). 2. In the Destination Name box, type the name of the target notification destination, which can be the name of your external application. 3. In the Destination Type box, select Message Queue. 4. In the Address box, type the address of the local or remote private Microsoft message queue that you have configured for receiving messages from Acumatica ERP, such as MyComputer \private$\testqueueforpushnotificatons. 5. For each generic inquiry for which you want Acumatica ERP to send notifications on changes in the inquiry results, do the following: a. On the table toolbar of the Generic Inquiries tab, click Add Row. The new row has the Active check box selected. b. In the Inquiry Title column of the added row, select the generic inquiry for which you want Acumatica ERP to send notifications. For each built-in definition for which you want Acumatica ERP to send notifications on changes in the results, do the following: a. On the table toolbar of the Built-In Definitions tab, click Add Row. The new row has the Active check box selected. b. In the Class Name column of the added row, select the class that defines the data query for which you want Acumatica ERP to send notifications. On the form toolbar, click Save. To Send Notifications to a SignalR Hub 1. On the System tab, click Integration. In the navigation pane, navigate to Configure > Push Notifications (SM302000). 2. In the Destination Name box, type the name of the target notification destination, which can be the name of your external application. 3. In the Destination Type box, select SignalR Hub. The Address box is filled in automatically with PushNotificationsHub. 4. For each generic inquiry for which you want Acumatica ERP to send notifications on changes in the inquiry results, do the following: 5. a. On the table toolbar of the Generic Inquiries tab, click Add Row. The new row has the Active check box selected. b. In the Inquiry Title column of the added row, select the generic inquiry for which you want Acumatica ERP to send notifications. For each built-in definition for which you want Acumatica ERP to send notifications on changes in the results, do the following: a. On the table toolbar of the Built-In Definitions tab, click Add Row. The new row has the Active check box selected.

161 Configuring Push Notifications 161 b. 6. In the Class Name column of the added row, select the class that defines the data query for which you want Acumatica ERP to send notifications. On the form toolbar, click Save. To Process Failed Notifications To process the push notifications that Acumatica ERP could not send, you use the Process Push Notifications (SM502000) form. On this form, you can view the notifications that Acumatica ERP has failed to send, try to resend them, or delete the notifications. : If a notification has failed in Acumatica ERP before it was sent (for example, if Acumatica ERP could not retrieve the data for the notification), this notification is not displayed in the table on the Process Push Notifications form. Acumatica ERP saves the information about these notifications in the PushNotificationsErrors database table. To View a Notification 1. On the System tab, click Integration. In the navigation pane, navigate to Process > Process Push Notifications (SM502000). 2. In the table on the form, select the row that contains the notification you want to view. 3. On the form toolbar, click Show Notification. 4. In the Notification Event dialog box, which opens, view the notification in JSON format. For details on the format of the notification, see Push Notification Format. To Resend Notifications 1. On the System tab, click Integration. In the navigation pane, navigate to Process > Process Push Notifications (SM502000). 2. Do one of the following: If you want to resend particular notifications, in the table on the form, select the check boxes in the rows that correspond to the notification you want to send, and click Send on the form toolbar. If you want to resend all notifications, on the form toolbar, click Send All on the form toolbar. To Delete Notifications 1. On the System tab, click Integration. In the navigation pane, navigate to Process > Process Push Notifications (SM502000). 2. Do one of the following: 3. If you want to delete particular notifications, in the table on the form, select the unlabeled check boxes in the rows that correspond to the notifications you want to delete, and click Delete on the form toolbar. If you want to delete all notifications, on the form toolbar, click Delete All. On the form toolbar, click Save.

162 Integration Form Reference 162 Integration Form Reference On the Navigation pane of the Integration module, the forms are grouped into nodes to bring together similar forms. This topic follows this layout when listing the forms of the Integration module. Process Import by Scenario (SM206036) Export by Scenario (SM207036) Process Push Notifications (SM502000) Salesforce Sync State (SF205040) Manage Data Providers (SM206015) Import Scenarios (SM206025) Export Scenarios (SM207025) Schedule Import Scenarios (SM206035) Export Scenarios (SM207035) Salesforce Sync (SF205030) Salesforce Data Resync (SF205035) Configure Web Services (SM207040) Web Service Endpoints (SM207060) Salesforce Sync (SF205020) Connected Applications (SM303010) Push Notifications (SM302000) Other Formula Editor Dialog Box Connected Applications Form ID: (SM303010) You use this form to register OAuth 2.0 or OpenID Connect (OIDC) client applications in Acumatica ERP; you can also use the form to review the access settings of an application and to revoke the access that has been granted. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below.

163 Integration Form Reference 163 Button Revoke Access Revokes the access that has been provided to the application. When you invoke this action, the system removes from the database all access tokens generated for this application, and the application cannot access data in Acumatica ERP by providing any of these tokens. : If the access formerly granted to the application is revoked, the secrets that were configured for this application on the Secrets tab of the form remain valid (until their expiration date, if applicable), and the application can use these secrets to request an authorization token again. Summary Area In this area, you can register a client application to which you want to grant access or select a registered application and then edit its access settings. Element Client ID The automatically generated ID of the client application. Acumatica ERP generates this ID when you save a new client application on the form; you cannot enter the value of this field manually for a new client application. The client application uses this ID during authentication in Acumatica ERP. The format of the client ID is <GUID>@<Company_ID>, where <GUID> is an auto-generated string, and <Company_ID> is the ID of the company to which data the client application can request access. This company ID is the ID of the company to which the user who registered the client application was logged in at the time of registration. To view the settings of an existing client application, select the identifier of the client application in this box. Client Name Required. The name of the client application. Active A check box that indicates (if selected) that the registration of this client application is active and the application can access Acumatica ERP by using the provided client credentials. By default, the check box is selected. OAuth 2.0 Flow The OAuth 2.0 flow that is used by the client application for authentication in Acumatica ERP. The flow can be one of the following options: Authorization Code: The client application uses the OAuth 2.0 authorization code flow. For details on the authorization code flow, see Authorization Code Flow. Implicit: The client application uses the OAuth 2.0 implicit flow, described in Implicit Flow. Resource Owner Password Credentials: The client application uses the OAuth 2.0 resource owner password credentials flow. For information about the flow, see Resource Owner Password Credentials Flow. Secrets Tab You use this tab to add secrets, which are used during application authorization, for the selected application. You can use one secret or multiple secrets for the selected application. For an already-

164 Integration Form Reference 164 registered client application, you can also edit and delete the secrets that have been defined on this tab. : The system ignores secrets for an application with the Implicit flow, so you should not add secrets in this case. 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 below. Button Add Shared Secret Opens the Add Shared Secret dialog box, which you can use to add a secret of the Shared Secret type to the list of secrets of the client application on this tab. Table Columns Column Type The type of the secret. Currently, Shared Secret is the only supported type. The description of the secret. Expires On (UTC) The date and time when the secret expires. Expired secrets remain in the table rather than being deleted automatically. Add Shared Secret Dialog Box In the Add Shared Secret dialog box, you can create a secret of the Shared Secret type for the application. Element Required. The description of the secret. Expires On (UTC) The date and time when the secret expires. Expired secrets remain in the table on Secrets tab rather than being deleted automatically. Value Required. The value of the secret. The value is generated automatically by the system when you open the dialog box to create a shared secret. To be authorized in Acumatica ERP, the client application must provide this value along with other authorization parameters. Important: For security reasons, the value of the secret is displayed only once: during the creation of the secret in this dialog box. You should copy and save this value before you close the dialog box. The dialog box has the following buttons. OK Closes the dialog box and adds the new secret to the table on the Secrets tab. Cancel Closes the dialog box without creating a secret. Redirect URIs Tab You use this tab to add or remove the unique resource identifiers (URIs) to which the client application is redirected after the user is authenticated in Acumatica ERP and grants access to the application. : A redirect URI is not necessary if you are registering a client application with the resource owner password credentials flow (that is, a client application with Resource Owner Password Credentials selected in the Flow box of the Summary area).

165 Integration Form Reference 165 The table toolbar includes only standard buttons. For the list of standard buttons, see Table Toolbar. Table Columns Column Redirect URI The URI to which the client application should be redirected after the user is authenticated in Acumatica ERP and grants access to the application. The redirect URI must be absolute and must not have the fragment part (the part preceded with #). The system compares this URI with the URI specified in the authorization request of the client application, and if these URIs are not identical, redirection fails. Data Providers Form ID: (SM206015) You use this form to create a provider for data import or data export; you can also use the form to view the details of existing providers. You can configure providers to work with files in CSV, Excel, and XML format and with different external systems. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. : If you have exported to XML a file data provider that has a file attached to the form (by using the Clipboard > Export to XML standard button on the form toolbar), when you import the data of the provider (by using Clipboard > Import from XML), you need to attach the file to the data provider manually. Form-Specific Buttons Button Get File Link Opens the Attached File Link dialog box, where you can get a link to the file attached to the provider. Attached File Link Dialog Box The dialog box, which is brought up when you click Get File Link on the form toolbar, has the following elements. Element Link The internal link to the file that is attached to the provider. The dialog box has the following button. Close Closes the dialog box. Summary Area You use this area to identify the provider. You can specify the name and details for a new provider, or you can select an existing provider and view its information.

166 Integration Form Reference 166 Element Name The name of the provider, which usually describes the data you will transfer by using this provider. You can use an alphanumeric string of up to 100 characters. Provider Type The type of provider, such as the following: File providers that you use to access data in external files: CSV Provider (PX.DataSync.CSVSYProvider): For import from and export to files in CSV format Excel Provider (PX.DataSync.ExcelSYProvider): For import from and export to Excel spreadsheets XML Provider (PX.DataSync.XMLSYProvider): For import from and export to files in XML format Providers that are preconfigured for importing data from and exporting data to external systems: Salesforce Provider (PX.DataSync.SFSYProvider): For import from and export to SalesForce CRM by using the Simple Object Access Protocol (SOAP) MS SQL Provider (PX.DataSync.MSSqlSYProvider): For import from and export to Microsoft SQL Server HubSpot Provider (PX.DataSync.HubSpot.HSSYProvider): For exporting leads to HubSpot, for nurturing and importing leads to Acumatica ERP for processing Providers for exporting payment data to external payment systems: ACH Provider (PX.DataSync.ACHProvider): For exporting data for processing in the Automated Clearing House (ACH) system Giro Payment Provider (PX.DataSync.Banks.GIROPaymentProvider): For exporting data for processing in giro-based payment systems : The Tax Provider, Tax Provider CSV, and Tax Zip Provider built-in types are obsolete. They were used to import data from the Avalara data files, but Avalara no longer supplies these files. Integration with Avalara is done through the Avalara AvaTax SOAP API. Active A check box that indicates (if selected) that this provider is active and will be available for selection on the Acumatica ERP forms related to data import. Parameters Tab The Parameters tab provides the list of parameters specific for the selected provider type. For a new provider, fill in the columns. 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 below. Button Reload Parameters Reloads the default values of the parameters specific to the provider type.

167 Integration Form Reference 167 Table Columns Column Name The name of the parameter, which is specific to the provider type. A CSV provider uses the following parameters: FileName: Specifies the name of the file that should be used for data import or data export; this parameter is standard for file providers. The path to the file is set automatically after you have uploaded an external file to the provider. Encoding: Specifies the encoding of the source file. You can select the proper encoding value from the drop-down list in the Value column of the table on the Parameters tab. By default, the value of the parameter is set to US-ASCII. Delimiter: Specifies the delimiter that is used in the CSV file. You can use as a delimiter any printable character. By default, a comma (,) is used as the delimiter. QuoteAll: Makes the provider enclose all values from the source file in double quotes. By default, the system does not enclose source values in double quotes. An Excel provider uses the following parameter: FileName parameter: Specifies the name of the file that should be used for data import or data export; this parameter is standard for file providers. An XML provider uses the following parameters: FileName: Specifies the name of the file that should be used for data import or data export; this parameter is standard for file providers. Encoding: Specifies the encoding of the source file. You can select the proper encoding value from the drop-down list in the Value column of the table on the Parameters tab. By default, the value of the parameter is set to US-ASCII. Format: Specifies the format of the XML file, which can be one of the following: Tree (default): The source file has a tree structure; that is, the values of the source fields are placed in tags of the source XML file. Flat: The source file has a flat structure; that is, the values of the source fields are placed in attributes of tags in the source XML file. A Microsoft SQL provider uses the following parameters: Server: Specifies the location of the Microsoft SQL Server instance. This is a required parameter. You set the parameter to the server name for a default instance of Microsoft SQL Server (for example, MyServer), and to the server name and instance name for a named instance of Microsoft SQL Server (for example, MyServer\MyInstance). If a default instance of Microsoft SQL Server is installed on the same computer where Acumatica ERP is installed, you can set the value of the parameter to (local). Database: Specifies the name of the database on the server. This is a required parameter.

168 Integration Form Reference 168 Column Login: Specifies the login for accessing the Microsoft SQL Server database. This is a required parameter. Password: Specifies the password for accessing the Microsoft SQL Server database. This is a required parameter. LastModifiedDateColumn: Specifies the column of the database table or view that contains the date when the record was most recently modified. This parameter is necessary only if you want Acumatica ERP to use the synchronization type of an import scenario based on the Microsoft SQL provider. For details on the synchronization types, see the description of the Sync Type box in the Import Scenarios (SM206025) form reference topic. CreatedDateColumn: Specifies the column of the database table or view that contains the date when the record was created. This parameter is necessary only if you want Acumatica ERP to use the synchronization type of an import scenario based on the Microsoft SQL provider. For details on the synchronization types, see the description of the Sync Type box in the Import Scenarios form reference topic. Authentication: Defines the authentication type to be used to connect to the database server. It can be one of the following: SQL: Acumatica ERP connects through SQL Server authentication. The account you specify should have sufficient rights for making changes to the database. This authentication type is used by default. Windows: Acumatica ERP connects through a Windows user account with the login and password you provide. Windows authentication works only for a local Microsoft SQL Server or when both application and database servers are members of the same Windows domain. For the description of the parameters of the HubSpot data provider, see Integration with HubSpot. For more details about ACH payment configuration, see ACH Payment Support. The description of the parameter. Value The value of the parameter to be used by the provider. Schema Tab On this tab, you can view and manually correct, if needed, the schema of the data used in the specified external data source (file or application). For a new provider, you can extract the schema from the data source in accordance with the provider type. : If you uploaded a new version of the file for an existing provider, refresh the data schema by filling in schema lines again. This tab includes two panes: The Source Objects pane contains the table with the list of objects of the data source, and the Source Fields pane contains the table with the list of fields for the object selected in the left pane. Source Objects 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 below.

169 Integration Form Reference 169 Button Fill Schema Objects Fills in the objects from the data source in accordance with the provider type. If Edit Command Opens the Object Command Editor dialog box, where you can type the commands for the selected table line. Click Close to save the command and close the dialog box. you don't see this button on the toolbar, click the that do not fit on the toolbar. icon, which displays actions : The ORDER BY clause cannot be used in the command. This button is used for only SQL data providers. Source Objects Table Columns Column Active A check box that indicates (if selected) that the object should be used for import or export. By default, the check box is not selected. Object The name of the object in the source, such as a worksheet in an Excel spreadsheet or a data table in the Salesforce application. Command The command to be executed for the object during data preparation. For example, you can apply SQL commands to source objects to apply restrictions on the imported records, select particular records from the source database table, or join data from several tables into one object in the data provider. : The ORDER BY clause cannot be used in the command. This column is used for only SQL data providers. Source Fields Pane 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 below. Button Fill Schema Fields Fills in the fields from the selected data source object in accordance with the provider type. Edit Command Opens the Object Command Editor dialog box, where you can type the commands for the selected table line. Click Close to save the command and close the dialog box. This button is used for only SQL data providers. Toggle Activation Reverses the value in the Active column in the selected line and updates the rest of the lines with this value. Source Fields Table Columns Column Active A check box that indicates (if selected) that the field can be used in an import or export scenario.

170 Integration Form Reference 170 Column Field The name of the field of the object in the external data source. Key A check box that indicates (if selected) that the field contains the key to the data set of the object. Currently this column is not used by data providers. The description of the field. Data Type The type of data in the field, which can be one of the following options: String, DateTime, Double, Decimal, Boolean, or Int32. For SQL data providers, the value of this field is filled in automatically from the corresponding property of the columns of SQL tables. For other provider types, you do not need to set the value in this column. Data Length The length of the data in the field. For SQL data providers, the value of this field is filled in automatically from the corresponding property of the columns of SQL tables. For other provider types, you do not need to set the value in this column. Command The action to be performed on the field data during data preparation. For example, you can replace the value of a field with some calculated value, or change the value of a field depending on some condition. This column is only used for SQL data providers. Export by Scenario Form ID: (SM207036) You can use this form to select an export scenario and prepare the data, export it, or roll back the changes in accordance with the selected scenario. On the form, you can review the prepared data if the export has failed and view the history of processing for the scenario. You can create scenarios for export by using the Export Scenarios (SM207025) form. Export is performed to the file uploaded to the Acumatica ERP website or to the third-party application specified in the export provider. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button Prepare & Export Prepares and exports the data. Prepare Prepares the data for export by uploading it on the form. The system performs all modifications defined by the scenario at this step and uploads the modified data on the form. You can view the data on the Prepared Data tab of the form. Export Exports the prepared data. The system tries to export the records that have the Active check box selected. Upload File Version Opens the Upload New Revision dialog box, which you can use to update an already uploaded file.

171 Integration Form Reference 171 Button Get Latest Version Downloads the latest file attached to the selected scenario. If you export data to a file, during export, the system creates a new version of the file attached to the form. Selection Area In this area, you can select an export scenario and view information about the selected scenario. Element Name The name of the export scenario. Select the scenario you want to work with, and you can view information about it. Screen Name A read-only box showing the name of the Acumatica ERP form whose functionality is used to perform data export. Status A read-only box showing the status of the selected scenario, which is automatically assigned during the processing and can be one of the following options: Number of Records New: This scenario is either new and has not been used for data preparation or that the history of processing for this scenario has been rolled back. Prepared: The data has been prepared in accordance with the scenario. Partially Exported: The data for the scenario has been exported only partially. Exported: The data for the scenario has been exported completely. A read-only box that displays the number of records prepared or exported to the target file or application. Prepared Data Tab On this tab, you can review the data prepared for export and view any errors that have occurred. The actual list displays the processed data, with as many columns as there are external fields mapped to the internal data. 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 below. Button Toggle Activation Reverses the value in the Active column in the selected line, and updates the rest of the lines with this value. Clear Activation Till Error Clears the check boxes in the Active column for the lines before the line with an error. If there are no errors, clears all the check boxes in the Active column. Toggle Processing Reverses the value in the Processed column in the selected line, and updates the rest of the lines with this value. Clear Errors Clears the error messages in the Error column.

172 Integration Form Reference 172 Table Columns These columns contain information about processing. Column Number The number of the record in the list of records for export. Active A check box that indicates (if selected) that this record is active and will be exported. Processed A check box that indicates (if selected) that the information in the row was exported. Error The error message, if an error occurred for this row. History Tab On this tab, you can view the history of processing for the selected scenario. 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 below. Button Roll Back Rolls back the changes in the export history and removes the prepared data. Table Columns Column Status Date The date when the status of the data had changed as a result of processing being performed. Status The status of the data as a result of the processing being performed. Number of Records The number of records processed. Version The version of the exported file. If export was successful, the system creates a new version. Details Tab On this tab, you can view additional information about the selected scenario. Info Section Element Provider A read-only box that displays the data provider that is used in the export scenario. To view the details about the provider, click the button to the right of the box to open the Data Providers (SM206015) form. Sync Type A read-only box that shows the type of synchronization for the selected scenario, which can be one of the following options: Full: Performs export of all the data in accordance with the scenario.

173 Integration Form Reference 173 Element Incremental: All Records: Performs partial export, including only the data (mentioned in the scenario) that has changed in the Acumatica ERP records. Incremental: New Only: Performs partial export, including only those records that have appeared in the Acumatica ERP database since the previous export took place. Prepared On A read-only box displaying the date when the data was prepared or the export was performed. Completed On A read-only box that shows the date and time when the export was completed. Site Map Section Element Site Map Location The location of the scenario on the site map. Select the location if you want to add the scenario to the site map. Site Map Title The title of the scenario on the site map. Provide the title if you want to add the scenario to the site map. Options Section Element Skip Headers A check box that you select to not export the titles of the elements on the form. You specify this option for a particular execution of a scenario. That is, the selected value is discarded after each execution of the scenario or each refresh of the page. Export Scenarios Form ID: (SM207025) You use this form to create export scenarios. You can perform data export as a one-time activity or periodically if you have configured synchronization between Acumatica ERP and the third-party software. You create an export scenario for a specific provider. You can create and view providers for export by using the Data Providers (SM206015) form. Generally, a scenario includes the mapping between the data in Acumatica ERP (source data) and the fields in an external file or a third-party source (target data), as well as any restrictions on the source data. For more information, see Configuring Export Scenarios. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button View Screen Navigates to the form selected in the Screen Name box.

174 Integration Form Reference 174 Summary Area You use the elements in this area to create a new scenario for one-time export or periodic synchronization, or to select an existing scenario for editing. Element Name The name of the scenario, which may be an alphanumeric string of up to 50 characters. Active A check box that indicates (if selected) that this scenario is active and can be used for data export. Screen Name The name of the Acumatica ERP form whose functionality will be used to perform data export. You can select the screen name by finding its module, finding its section, and selecting the applicable form. Export Only Mapped Fields A check box that indicates (if selected) that only the fields that are mapped in the export scenario should appear in the output of data export; other fields of the data provider are skipped during export. If the check box is cleared, the fields of the data provider that are not mapped in the export scenario are exported and have null values. We recommend that you select this check box when you are exporting data to external systems, such as HubSpot, to avoid the system rewriting of the fields that are not mapped in the scenario with null values during data export. Provider The data provider that should be used for data export. Provider Object The object of the specified data provider. Only active provider objects are available for selection. Sync Type The type of synchronization for the selected scenario, which can be one of the following options: Full: Select this option to perform export of all the data in accordance with the scenario. Incremental - All Records: Select this option to perform partial export, including only the data (mentioned in the scenario) that has changed in the Acumatica ERP records. Incremental - New Only: Select this option to perform partial export, including only those records that have appeared in the Acumatica ERP database since the previous export took place. Format Locale The locale whose date format (and other locale-specific formats) will be used for the data to be exported. Inverse Mapping ID The scenario that can be used for import of the same data if data synchronization between Acumatica ERP and the third-party software is configured. Mapping Tab You use this tab to map the data on the Acumatica ERP form (in any section of forms except for Reports) to the target fields in the external file or third-party application. For more details on mapping in export scenarios, see Configuring Scenario Mapping. 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 below.

175 Integration Form Reference 175 Button Insert Inserts a new table row above the selected row. Unlabeled box with Displays the form controls according to the selected option, which is one of the display options following: Show All Commands or Hide Service Commands. By default, the Show All Commands option is selected, which indicates that all commands (including service commands) are displayed. For more information on service commands, see Service Commands in Import and Export Scenarios. Up Moves the selected row up the list. Down Moves the selected row down the list. Insert From Gives you the ability to insert a part of another scenario; invokes the Choose Scenario to Insert Steps From dialog box. Choose Scenario to Insert Steps From Dialog Box In this dialog box, you can select another scenario to insert its mapping lines into the current scenario. This operation inserts all lines of the selected scenario. Once the lines are inserted, you can make inactive or delete any lines you don't want to keep. This dialog box has the following elements. Element Mapping The scenario whose mapping lines you want to insert. The dialog box has the following buttons. OK Closes the dialog box and inserts the lines from the selected scenario. Cancel Closes the dialog box without performing insertion. Table Columns Column Active A check box that indicates (if selected) that this step of the scenario is active during data export. Source Object The name of the functional object of the graph the Acumatica ERP form is based on. (The functional object can be the Summary area, the Details area, or any of the tabs or dialog boxes.) Field/Action Name The name of the field or action of the functional object selected as the Source Object. Click the icon to select a field or action, or click the the Formula Editor Dialog Box and create a formula. icon to open For details on the functions and operators that can be used in the formula, see Functions and Operators. Commit A check box that indicates (if selected) that when this field or action is filled in, a commit to the database is required. Target Field/ Value The external field (in the target file) to hold the value to be exported. Click the icon to select from the available external fields. Click the icon to create a formula if you want to assign its resulting value back to the internal field specified as the Field/Action Name.

176 Integration Form Reference 176 Column Ignore Error A check box that indicates (if selected) that the system should ignore errors when processing the data for this field. Source Restrictions Tab You can use this tab to set up restrictions for the data to be exported. The table toolbar includes only standard buttons. For the list of standard buttons, see Table Toolbar. Column Active A check box that, if selected, indicates that the restriction is active. Brackets The opening bracket or brackets for composing a logical expression with multiple conditions. Field Name The field whose value the condition will be applied to. Condition The logical operation to apply to the value of the selected field. The following options are available: Is Relative Equals: Returns True if the field value is equal to the value specified in the Value field. Does Not Equal: Returns True if the field value is not equal to the value specified in the Value field. Is Greater Than: Returns True if the field value is greater than the value specified in the Value field. Is Greater Than or Equal to: Returns True if the field value is greater than or equal to the value specified in the Value field. Is Less Than: Returns True if the field value is less than the value specified in the Value field. Is Less Than or Equal to: Returns True if the field value is less than or equal to the value specified in the Value field. Is Between: Returns True if the field value is between the values specified for Value and Value 2. Contains: Returns True if the field value (string) contains the value specified in the Value field. Ends With: Returns True if the field value ends with the character or string specified in the Value field. Starts With: Returns True if the field value begins with the character or string specified in the Value field. Is Null: Returns True if the field value is null. Is Not Null: Returns True if the field value is not null. Does Not Contain: Returns True if the field value (string) does not contain the value specified in the Value field. A check box that indicates (if selected) that the field value represents the number of days with respect to the current business date.

177 Integration Form Reference 177 Column Value The first value of the condition, which will be compared with the value of the chosen field. Most of the conditions require only one value, while Is Between requires two values. Value 2 The second value of the condition, if required by the selected condition. Brackets The closing bracket or brackets for composing a logical expression with multiple conditions. Operator A logical operator to be used between the logical conditions enclosed in brackets. Export Scenarios Form ID: (SM207035) You can use this form to prepare data for export and to export the data for the export scenarios that you select. Also, you can view any errors that have occurred during the process and fix them in the scenarios. You can roll back the prepared data and the history of processing, if needed. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button Process Performs the operation that you selected (in the Operation box) for the selected scenarios. Process All Performs the operation that you selected for all scenarios in the list. Selection Area In this area, you can select an operation to be executed. Element Operation The operation to be performed for the scenario or scenarios selected in the Scenarios area. Select one of the following options: Skip Headers Prepare & Export: Prepares and exports the data in one step. Prepare: Only prepares the data for export (without exporting it); select this option if the data may require manual editing. Export: Exports the already-prepared data. Roll Back: Rolls back the data prepared for export that is, removes the prepared data from the Prepared Data dialog box and removes the latest record from the history of scenario processing in the Mapping History dialog box. A check box that you select to not export the titles of the elements on the form. Table The table of scenarios in this area includes the scenarios with the appropriate status for the operation (selected in the Parameters area) to be performed. You can select one export scenario or multiple scenarios for processing.

178 Integration Form Reference 178 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 below. Button History Opens the Mapping History dialog box, which displays the history of operations for the selected scenario. Prepared Data Opens the Prepared Data dialog box, which displays the prepared data for the selected scenario. Table Columns Column Selected An unlabeled check box that you select to indicate that you have selected this scenario for processing. Name The name of the scenario. Screen Name A read-only box showing the screen ID of the Acumatica ERP form used by the scenario. Provider A read-only box showing the provider used for export. Sync Type The type of synchronization for the export scenario, which is one of the following options: Full; Incremental - All Records; or Incremental - New Only. Status The status of the scenario, which can be one of the following options: Prepared, Exported, or Partially Processed. Number of Records The number of records that have been processed. Prepared On The date and time when the data was prepared. Completed On The date and time when the data export was completed. Mapping History Dialog Box On the Mapping History dialog box, you can view the history of data export for the selected scenario. The table in the dialog box has the following columns. Column Status Date The date when the status last changed. Status The status of the data, which is one of the following options: Prepared, Exported, or Partially Processed. Number of Records The number of records that have been processed. Version The date and time stamp of the version of the exported file. Prepared Data Dialog Box On the Prepared Data dialog box, you can view the prepared data with errors indicated. The dialog box includes the toolbar and the data organized into columns that depend on the mapping of the data exported. The list below describes only the three columns that have information about processing. The table in the dialog box has the following columns.

179 Integration Form Reference 179 Column Active A check box that indicates (if selected) that the data is active and will be exported. Processed A check box that indicates (if selected) that the data in the row was processed. Error The error message, if an error has occurred for the data in this row. The dialog box has the following button. Close Saves the selections and closes the dialog box. Formula Editor Dialog Box The Formula Editor dialog box, which you can invoke from the Import Scenarios (SM206025) and Export Scenarios (SM207025) forms, helps you create formulas to transform the data while you are importing or exporting it. You invoke the dialog box (shown in the following screenshot) from the Mapping tab of either form by clicking the pen icon in the Source Field/Value or Target Field/Value box. You can enter the formula directly to the formula editor or compose it by selecting the appropriate parameters. Formula Editor Dialog Box Figure: Formula Editor dialog box The Formula Editor dialog box, which is shown in the screenshot above, includes the following panes: Component Type pane (upper left): Displays the types of operators, functions, and fields that can be used as formula components. Click any of the types to display the corresponding list of available components in the Component Selection pane. Component Selection pane (upper right): For the component type chosen in the Component Types pane, displays the list of available components. Click a component to add it to the formula at the bottom of the dialog box. You can search for the needed component by using the Search box at the top of the Component Selection pane.

180 Integration Form Reference 180 Formula Text pane (bottom): Contains the text of the formula, which you can edit manually. The formula may include the selected components, arguments of manually inserted components, and other elements, all arranged in accordance with the syntax of the formula. Formula Editor Dialog Box Buttons The dialog has the following buttons. Button Validate Checks whether the formula typed in the Formula Text pane is valid. OK Closes the dialog box and inserts into the specified box the formula you have created. Cancel Closes the dialog box without saving your changes. Import by Scenario Form ID: (SM206036) On this form, you can select an import scenario and prepare and import the data in accordance with the selected scenario. You create scenarios for import by using the Import Scenarios (SM206025) form. Alternatively, you can use this form to import data directly from a file, such as an Excel spreadsheet. In this case, upload the file, set up the mapping, and then prepare and import the data. For more information, see Simplified Scenarios for Data Import. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button Add New Record Gives you the ability to add a new simplified import scenario. Clicking this button first opens the Select File for Import dialog box, where you can select the file whose data you want to import, and then opens the Provide New Scenario Properties Dialog Box, where you select the form to be used for data import, name the scenario, and select the data provider type. Prepare & Import Prepares the data and imports it. Prepare Prepares the data for import. Import Imports the prepared data. Upload File Version Opens the Upload New Revision dialog box, which you can use to update an already uploaded file. Get File Downloads the latest file attached to the selected scenario. View Screen Displays the Acumatica ERP form to which you are importing data with the error occurred during data import. The button is only available if there was an error during data import. Provide New Scenario Properties Dialog Box In this dialog box, you can select the form to be used for importing data, enter the scenario name, and change the data provider.

181 Integration Form Reference 181 Element Screen Name Required. The Acumatica ERP form to be used for importing data from the uploaded file. You select the screen name by finding its module, finding its section, and selecting the applicable form in the site tree. Scenario Name Required. The name of the new simplified import scenario. The system generates the name automatically, based on the title of the form you selected in the Screen Name box. If required, you can change the name. Provider Type Required. The provider type, which is defined automatically based on the file type. OK Creates a new simplified scenario for data import and closes the dialog box. Close Closes the dialog box without creating a new simplified scenario for data import. Selection Area In this area, you can select an existing import scenario and view information about the scenario. Element Name The name of the scenario that should be used for data import. Screen Name A read-only element showing the name of the Acumatica ERP form whose functionality will be used to perform import. Status A read-only element that shows the status of the selected scenario, which is automatically assigned during the processing and can be one of the following options: New: Either this scenario is new and has not been used for data preparation or the history of processing for this scenario has been rolled back. Prepared: The data has been prepared in accordance with the scenario. Partially Processed: The data for the scenario has been imported only partially. Processed: The data for the scenario has been imported completely. Number of Records A read-only element that displays the number of records in the external source. Simple Scenario A read-only check box that indicates (if selected) that the selected scenario is a simplified import scenario. For more information, see Simplified Scenarios for Data Import. Discard Previous Result A check box that you select to prepare and import data regardless of the status and the results of the previous import. Generally, you should select this check box if you are scheduling the processing of the selected scenario and you expect errors during the import that do not affect the performance of the scenario. For example, the system returns an error for a line when it is trying to import a line that has been imported in the previous cycle. If you select the check box, the system can run the scenario on a schedule, thus importing the new lines. If you clear the check box, the system won't be able to run the scenario on schedule if the previous processing of the scenario returned errors. For more information about scheduling, see Scheduled Processing.

182 Integration Form Reference 182 Prepared Data Tab On this tab, you can review the data prepared for import and any errors that have occurred. The actual list displays the processed data, with as many columns as there are internal fields mapped to the external data. 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 below. Button Toggle Activation Reverses the value in the Active column in the selected line and updates the rest of the lines with this value. Clear Activation Till Error Clears the check boxes in the Active column for the lines before the line with an error. If there are no errors, clears all the check boxes in the Active column. Toggle Processing Reverses the value in the Processed column in the selected line and updates the rest of the lines with this value. Clear Errors Clears the error messages in the Error column. Table Columns The Table Columns list below describes only the first four columns, which have information about processing. Column Number The number of the record in the list of records for import. Active A check box that indicates (if selected) that the record is active and will be imported. Processed A check box that indicates (if selected) that the information in the row was processed. Error The error message, if an error has occurred for this row. Mapping Tab You use this tab, which appears only when you create or open a simplified data import, to map the data from the external source to the fields of the specified data entry form in Acumatica ERP for automatic import. For more details on simplified import scenarios, see Simplified Scenarios for Data Import. 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 below. Button Refresh From File Refreshes the data schema for an existing provider after you have uploaded a new version of the file.

183 Integration Form Reference 183 Table Columns Column Active A check box that indicates (if selected) that this field or action is active during import. Source Field/ Value An external field (in the source file) whose value should be imported into the specified internal field, or an expression to be executed on import to generate the value for an internal field. Click the fields, or click the formula. icon to select from the list of available icon to open the Formula Editor Dialog Box and create a For details on the functions and operators that can be used in the formula, see Functions and Operators. Key A check box you select to mark the key fields in the uploaded file. Target Object The name of the functional object of the graph that the Acumatica ERP form is based on. (The functional object can be the Summary area, the Details area, or any of the tabs or dialog boxes available for the form.) Field Name The name of the field or action of the functional object selected in the Target Object column. Click the field to display the list of available values. History Tab You use this tab to view the history of processing for the selected scenario. : A history record is inserted in the table after the import operation is completed. Therefore, if an application server restarts during processing of an import scenario (for example, if the session was timed out), no history record is inserted in the table. 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 below. Button Roll Back Clears the history of scenario execution and clears the prepared data. Clicking Roll Back doesn't reverse records that have already been imported. Table Columns Column Status Date The date when the status of the data had changed as a result of the processing being performed. Status The status of the data as a result of processing being performed. Number of Records The number of records processed. Version The version of the uploaded external file. The description of the operation.

184 Integration Form Reference 184 Details Tab On this tab, you can view additional information about the selected scenario. Info Section Element Provider A read-only box that displays the data provider of the selected import scenario. To view the details of the provider, click the button to the right of the box to open the Data Providers (SM206015) form. Sync Type A read-only box that shows the type of synchronization for the selected scenario, which can be one of the following options: Full: Performs export of all the data in accordance with the scenario. Incremental: All Records: Performs partial export, including only the data (mentioned in the scenario) that has changed in the Acumatica ERP records. Incremental: New Only: Performs partial export, including only those records that have appeared in the Acumatica ERP database since the previous export took place. Prepared On A read-only box displaying the date when the data was prepared or the export was performed. Completed On A read-only box that shows the date and time when the export was completed. Site Map Section Element Site Map Location The location of the scenario on the site map. Select the location if you want to add the scenario to the site map. Site Map Title The title of the scenario on the site map. Provide the title if you want to add the scenario to the site map. Options Section Element Break on Error A check box that indicates (if selected) that the processing will be canceled if an error occurs. You specify this option for a particular execution of a scenario. That is, the selected value is discarded after each execution of the scenario or each refresh of the page. This check box affects the order in which the records are imported. For example, suppose that you are importing documents with auto-numbering of documents, and each line of the source contains one document. If you clear the Break on Error check box, all correct documents will be imported first, and then you will review all errors at once and import the corrected records. The order in which the reference numbers are assigned to the imported documents will be different than in the situation if you import documents one by one and stop after each error. If the order of record processing is not important, you can clear the Break on Error check box.

185 Integration Form Reference 185 Element Break on Incorrect Target A check box that indicates (if selected) that the system will stop processing records at the first error that occurs for a record that violates the target restrictions. You specify this option for a particular execution of a scenario. That is, the selected value is discarded after each execution of the scenario or each refresh of the page. Validate Data (No Saving) A check box you select to validate the selected import scenario. The scenario processing emulates data import and is canceled if an error occurs. If you want to save the imported data after successful validation, select the Save if Data Is Valid check box. You specify this option for a particular execution of a scenario. That is, the selected value is discarded after each execution of the scenario or each refresh of the page. Save if Data Is Valid A check box you select to save the data if the import validation is successful. Clear the check box if you don't want to save the data after import validation. You specify this option for a particular execution of a scenario. That is, the selected value is discarded after each execution of the scenario or each refresh of the page. This option is available only when you select the Validate Data (No Saving) check box to switch to import validation mode. Skip Headers A check box that you select to not import the titles of the elements on the form. You specify this option for a particular execution of a scenario. That is, the selected value is discarded after each execution of the scenario or each refresh of the page. Import Scenarios Form ID: (SM206025) You use this form to create an import scenario. You can perform data import as a one-time activity or periodically if you have configured synchronization between Acumatica ERP and the third-party software. An import scenario is created for a specific provider. You can create and view providers for import by using the Data Providers (SM206015) form. Generally, a scenario includes the mapping between the data in the external data source and the data in Acumatica ERP, as well as any restrictions on the source and target data. For more information, see Configuring Import Scenarios. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button View Screen Navigates to the form selected in the Screen Name box.

186 Integration Form Reference 186 Summary Area In this area, you can create a new import scenario or select an existing one for editing. Element Name The name of the scenario, which may be an alphanumeric string of up to 50 characters. Active A check box that indicates (if selected) that this scenario is active and can be used for data import. Screen Name The name of the Acumatica ERP form whose functionality will be used to perform data import. You can select the screen name by finding its module, finding its section, and selecting the applicable form. Provider The data provider that should be used for data import. Provider Object The object of the specified data provider. Only active provider objects are available for selection. Sync Type The type of synchronization for the import scenario, which can be one of the following options: Full: To perform import of all the data available in the source. Incremental - All Records: To perform partial import, including only the data in each record that has changed in the source. Incremental - New Only: To perform partial import, including only records that have appeared in the source since the previous import took place. If the data is imported from a file data source, the Incremental - All Records and Incremental - New Only options provide the same result: Selecting either of these options makes the system import the data only if a new version of the source file is provided before import. Format Locale The locale used in the source field to format date, time, and other locale-specific information. Inverse Mapping ID The scenario that can be used for export of the same data if data synchronization between Acumatica ERP and the third-party software is configured. Mapping Tab You use this tab to map the data from the external source to the fields of the specified data entry form in Acumatica ERP for automatic import or synchronization. For more details on import scenarios, see Configuring Scenario Mapping. 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 below. Button Insert Inserts a new table row above the selected row. Unlabeled field with display options Displays the Acumatica ERP form controls according to the selected option, which is one of the following: Show All Commands or Hide Service Commands. By default, the Show All Commands option is selected, which indicates that all commands (including service commands) are displayed.

187 Integration Form Reference 187 Button For more information on service commands, see Service Commands in Import and Export Scenarios. Up Moves the selected row up the list. Down Moves the selected row down the list. Insert From Makes it possible to insert a part of another scenario; invokes the Choose Scenario to Insert Steps From dialog box. Choose Scenario to Insert Steps From Dialog Box In this dialog box, you can select another scenario to insert its mapping lines into the scenario currently under modification. This operation inserts all lines of the selected scenario. Once the lines are inserted, you can make inactive or delete any lines you don't want to keep. The dialog box has the following elements. Element Mapping The scenario whose mapping lines you want to insert. The dialog box has the following buttons. OK Closes the dialog box and inserts the lines from the selected scenario. Cancel Closes the dialog box without performing insertion. Table Columns Column Active A check box that indicates (if selected) that this step of the scenario is active during data import. Target Object The name of the functional object of the graph the Acumatica ERP form is based on. (The functional object can be the Summary area, the Details area, or any of the tabs or dialog boxes available for the form.) Field/Action Name The name of the field or action of the functional object selected in the Target Object column. Click the field to display the list of available values. Commit A check box that indicates (if selected) that when this field is filled in, a commit to the database is required. The check box is automatically selected when it is required by the functionality of the field. Source Field/ Value An external field (in the source file) whose value should be imported into the specified internal field, or an expression to be executed on import to generate the value for the internal field. Click the fields, or click the formula. icon to select from the list of available icon to open the Formula Editor Dialog Box and create a For details on the functions and operators that can be used in the formula, see Functions and Operators. Ignore Error A check box that indicates (if selected) that the system should ignore errors when the data for this field is imported.

188 Integration Form Reference 188 Source Restrictions Tab On this tab, you can set up restrictions to filter the data that you want to extract from the source for processing by the import scenario. For example, some customer ID values in the source have CUST prefixes. You can specify a source restriction that selects the only the records from the source that have the CUST prefix in the customer ID field. The table toolbar includes only standard buttons. For the list of standard buttons, see Table Toolbar. Column Active A check box that indicates (if selected) that the restriction is active. Brackets The opening bracket or brackets for composing a logical expression with multiple conditions. Field Name The field whose value the condition will be applied to. Condition The logical operation to apply to the value of the selected field; in some cases, the operation entails comparing it to the values specified for Value and Value 2. The following options are available: Is Relative Equals: Returns True if the field value is equal to the value specified in the Value field. Does Not Equal: Returns True if the field value is not equal to the value specified in the Value field. Is Greater Than: Returns True if the field value is greater than the value specified in the Value field. Is Greater Than or Equal to: Returns True if the field value is greater than or equal to the value specified in the Value field. Is Less Than: Returns True if the field value is less than the value specified in the Value field. Is Less Than or Equal to: Returns True if the field value is less than or equal to the value specified in the Value field. Is Between: Returns True if the field value is between the values specified for Value and Value 2. Contains: Returns True if the field value (string) contains the value specified in the Value field. Ends With: Returns True if the field value ends with the character or string specified in the Value field. Starts With: Returns True if the field value begins with the character or string specified in the Value field. Is Null: Returns True if the field value is null. Is Not Null: Returns True if the field value is not null. Does Not Contain: Returns True if the field value (string) does not contain the value specified in the Value field. A check box that indicates (if selected) that the field value represents the number of days with respect to the current business date.

189 Integration Form Reference 189 Column Value The first value of the condition, which will be compared with the value of the selected field. Most of the conditions require only one value, while Is Between requires two values. Value 2 The second value of the condition, if required by the selected condition. Brackets The closing bracket or brackets for composing a logical expression with multiple conditions. Operator The logical operator to be used between the logical conditions enclosed in brackets. Target Restrictions Tab You can use this tab to set up restrictions that are applied to records after they have been processed by the import scenario. For example, suppose you have imported customer records to Acumatica ERP and then manually changed the status of some of these records to Inactive, and now you want to update only those imported customer records that have Inactive status. Because you do not have the status in the source file, you cannot use source restrictions to select needed records. You can specify a target restriction that makes the system save the results of import for only the records that have Inactive status in Acumatica ERP. The table toolbar includes only standard buttons. For the list of standard buttons, see Table Toolbar. Column Active A check box that indicates (if selected) that the restriction is active. Brackets The opening bracket or brackets for composing a logical expression with multiple conditions. Field Name The field whose value the condition will be applied to. Condition The logical operation to apply to the value of the selected field; in some cases, the operation entails comparing it to the values specified for Value and Value 2. Typically, the following options are available: Equals, Does Not Equal, Is Greater Than, Is Greater Than or Equal to, Is Less Than, Is Less Than or Equal to, Is Between, Contains, Ends With, Starts With, Is Null, Is Not Null. Is Relative A check box that indicates (if selected) that the field value represents the number of days with respect to the current business date. Value The first value of the condition, which will be compared with the value of the selected field. Most of the conditions require only one value, while Is Between requires two values. Value 2 The second value of the condition, if required by the selected condition. Brackets The closing bracket or brackets for composing a logical expression with multiple conditions. Operator The logical operator to be used between the logical conditions enclosed in brackets. Import Scenarios Form ID: (SM206035)

190 Integration Form Reference 190 On this form, you can prepare data for import and import the data for multiple import scenarios. Also, you can roll back the prepared data (or history or processing) if needed. You can perform data import for the selected import scenarios that were created on the Import Scenarios (SM206025) form. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button Process Performs the operation you have selected (in the Operation box) for the selected scenarios. Process All Performs the operation you have selected for all scenarios in the list. Parameters Area By using the elements in this area, you can select the operation to be executed and the processing options. Element Operation The operation to be performed for the scenarios selected in the table. The following options are available: Prepare & Import: To prepare and import the data in one step. Prepare: To only prepare (but not import) the data for import if the data may require manual editing. Import: To only import (but not prepare) the already-prepared data. Roll Back: To roll back the data prepared for import that is, to remove the prepared data from the Prepared Data dialog box and remove the latest record from the history of scenario processing in the History dialog box. Break on Error A check box that indicates (if selected) that the processing will be canceled if an error occurs. Break on Incorrect Target A check box that indicates (if selected) that the system will stop processing records at the first error that occurs for a record that violates the target restrictions. Validate Data (No Saving) A check box that indicates (if selected) that only data validation will be performed. The scenario processing emulates data import and is canceled if an error occurs. If you want to save the imported data after successful validation, select the Save if Data Is Valid check box. Save if Data Is Valid A check box that indicates (if selected) that the data should be saved if it is valid. Clear the check box if you don't want to save the data after import validation. This option is available only when you select the Validate Data (No Saving) check box to switch to import validation mode. Skip Headers A check box that you select to not export the titles of the elements on the form. Table The table contains the list of scenarios with the appropriate status for the operation (selected in the Parameters area) to be performed. You can select one scenario or multiple scenarios for processing.

191 Integration Form Reference 191 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 below. Button History Opens the History dialog box, which displays the history of operations for the selected scenario. Prepared Data Opens the Prepared Data dialog box, which displays the prepared data for the selected scenario. Table Columns Column Selected An unlabeled check box that you select to include this scenario in processing if you click Process. Name The name of the scenario. Screen Name A read-only box showing the screen name of the Acumatica ERP form used by the scenario. Provider A read-only box showing the provider used for import. Sync Type The type of synchronization for the import scenario, which is one of the following options: Full; Incremental - All Records; or Incremental - New Only. Status The status of the scenario, which can be one of the following options: Prepared, Imported, or Partially Processed. Number of Records The number of records in the external source. Prepared On The date and time when the data was prepared. Completed On The date and time when the import was completed. History Dialog Box On the History dialog box, you can view the history of data import for the selected scenario. The dialog box has the following columns. Column Status Date The date when the status last changed. Status The status of the scenario, as automatically assigned during the processing. The status can be one of the following options: Prepared: The data has been prepared in accordance with the scenario Partially Processed: The data for the scenario has been imported only partially Imported: The data for the scenario has been imported completely Number of Records The number of records processed. Version The date and time stamp of the version of the source file.

192 Integration Form Reference 192 Prepared Data Dialog Box On the Prepared Data dialog box, you can view the prepared data, with any errors indicated. This dialog box includes the toolbar and the data organized into columns that are specific to the data being imported. The list below describes only the three columns that have information about processing. The table in the dialog box has the following columns. Column Active A check box that indicates (if selected) that the data should be processed. Processed A check box that indicates (if selected) that the data in the row was processed. Error The error message, if an error has occurred for the data in this row. The dialog box has the following button. Close Saves the selections and closes the dialog box. Process Push Notifications Form ID: (SM502000) You use this form to process the push notifications that have not been sent by Acumatica ERP automatically. You can view the notifications that Acumatica ERP failed to send, try to resend them, or delete them. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button Send Sends the notifications that you have selected in the table by selecting the unlabeled check boxes in their rows. Send All Sends all notifications in the table. Show Notification Opens the Notification Event dialog box, where you can view the text (in JSON format) of the notification you have clicked. For more information about the format of the notification, see Push Notification Format. Delete All Deletes all notifications from the table. Table The table contains the notifications that Acumatica ERP failed to send within the past two days. : If a notification has failed in Acumatica ERP before it was sent (for example, if Acumatica ERP could not retrieve the data for the notification), this notification is not displayed in the table on the Process Push Notifications form. Acumatica ERP saves the information about these notifications in the PushNotificationsErrors database table. Column Selected An unlabeled check box that you select to include the notification when you click Send or Delete on the form toolbar. Destination Name The name of the notification destination.

193 Integration Form Reference 193 Column Date The date when Acumatica ERP attempted to send the notification. Source Name The source for which Acumatica ERP produced the notification: either the name of the generic inquiry or the name of the class with the built-in query definition. Error The error that occurred when Acumatica ERP sent the notification. Push Notifications Form ID: (SM302000) You use this form to add push notification definitions that is, to set up Acumatica ERP to send push notifications to the notification destination if specific data is changed in Acumatica ERP. You can also use the form to view the details of existing push notification definitions. Form Toolbar The form toolbar includes only standard buttons. For the list of standard buttons, see Form Toolbar. Summary Area In this area, you can specify the main properties of a new notification definition, or select a definition (by selecting its name) and view its main properties. Element Destination Name Required. The name of the notification destination. Active A check box that indicates (if selected) that this notification destination is active and notifications can be sent to it. Destination Type Required. The type of the notification destination, which can be one of the following options: Webhook: An HTTP address to which Acumatica ERP sends HTTP POST requests with notification information. Message Queue: A queue of the Microsoft Message Queuing (MSMQ) service. SignalR Hub: The SignalR hub, which can be used if you can expose neither an HTTP address (webhook) nor a message queue to receive push notifications. For information about how to connect your application to the SignalR hub of Acumatica ERP, see To Connect to the SignalR Hub in the Acumatica Framework Developer Guide. For more information on the types of notification destinations, see Push Notification Destinations. Address Required. The address to which Acumatica ERP should send push notifications. The format of the address depends on the value specified in the Destination Type box as follows: For the Webhook type, you specify the HTTP address to which Acumatica ERP should send notifications in the following format: <SiteName>:<PortNumber>/<PageName>?<ParameterNames>, where <SiteName> is the name of the site, <PortNumber> is the optional number of the port, <PageName> is the optional name of the

194 Integration Form Reference 194 Element page, <ParameterNames> is the optional list of the URL parameters. For example, the following HTTP address specifies a site on the local computer: Header Name For the Message Queue type, you specify the address of a local or remote private Microsoft message queue in the following format: <ComputerName>\private$\<QueueName>, where <ComputerName> is the name of the computer, and <QueueName> is the name of the queue. For example, the following address specifies the TestQueueForPushNotifications queue on the MyComputer computer: MyComputer\private$ \TestQueueForPushNotificatons. For the SignalR Hub type, the system fills in the PushNotificationsHub value automatically. The name of the header that should be included in the HTTP POST request that Acumatica ERP sends to the destination address (which is specified in the Address box). This element is available only if Webhook is selected in the Destination Type box. Header Value The value of the header that should be included in the HTTP POST request that Acumatica ERP sends to the destination address (which is specified in the Address box). This element is available only if Webhook is selected in the Destination Type box. Generic Inquiries Tab You use this tab to include an existing generic inquiry in the list of inquiries for which Acumatica ERP produces push notifications to the selected destination if the results of any of these generic inquiries change. On this tab, you can also review the list of generic inquiries based on which Acumatica ERP sends notifications to the selected notification destination. 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 below. Button View Inquiry Opens the selected generic inquiry on the Generic Inquiry (SM208000) form. Table Columns Column Active A check box that indicates (if selected) that this generic inquiry is active and Acumatica ERP generates notifications for changes in the results of this generic inquiry. Inquiry Title The name of the generic inquiry for which Acumatica ERP sends notifications to the selected notification destination.

195 Integration Form Reference 195 Built-In Definitions You use this tab to include a class that defines a data query in the list of classes for which Acumatica ERP produces push notifications to the selected destination if the results of any of these queries change. On this tab, you can also review the list of classes based on which Acumatica ERP sends notifications to the selected notification destination. For information about how to define a class with the data query, see To Create a Built-In Definition in the Acumatica Framework Development Guide. The table toolbar includes only standard buttons. For the list of standard buttons, see Table Toolbar. Table Columns Columns Active A check box that indicates (if selected) that this class is active and Acumatica ERP generates notifications for the changes in the results of the data query defined by this class. Class Name The name of the class that defines a data query for which Acumatica ERP sends notifications to the selected notification destination. Salesforce Data Resync Form ID: (SF205035) This form is available only if the Salesforce Integration feature is enabled on the Enable/Disable Features (CS100000) form. You use this form to synchronize records that have become out of sync due to processing failures. For details, see Overview of Synchronization with Salesforce. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button Process Initiates the process selected in the Sync to Start box for records of the selected types. Process All Initiates the process selected in the Sync to Start box for records of all the types listed in the table. Selection Area Element Sync to Start The operation you want to execute when you click Process or Process All on the form toolbar. The following options are available: Failed & Missed Data Resync: Starts synchronization of only the data that is out of sync either due to previous failures of the synchronization process or because one of the systems was temporarily unavailable due to a connection failure. Full Data Resync: Checks all supported records for updated data and synchronizes those that are out of sync.

196 Integration Form Reference 196 Table The table toolbar includes only standard buttons. For the list of standard buttons, see Table Toolbar. Table Columns Column Selected An unlabeled check box that indicates (if selected) that the process selected in the Sync to Start box will be initiated for records of a particular type if you click Process on the form toolbar. Entity The type of records that you want to process. Latest Failed & Missed Data Resync Attempt The date of the latest attempt to synchronize records of the type that previously was missed or failed to synchronize. Latest Full Data Resync Attempt The date of the latest attempt to resynchronize all records of the type. Salesforce Sync Form ID: (SF205030) This form is available only if the Salesforce Integration feature is enabled on the Enable/Disable Features (CS100000) form. You use this form to initiate or stop real-time data synchronization between Acumatica ERP and Salesforce for records of particular types or for all records that can be synchronized. For details, see Overview of Synchronization with Salesforce. Table You use this table to select the type or types of records whose data you want to synchronize between Acumatica ERP and Salesforce in real time. 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 below. Button Process Initiates the real-time synchronization process for records of the types for which unlabeled check boxes are selected in the table. Process All Initiates the real-time synchronization process for all records that can be synchronized. Stop Stops the real-time synchronization process for records of the types for which unlabeled check boxes are selected in the table. Stop All Stops the real-time synchronization process for records of all the types listed in the table.

197 Integration Form Reference 197 Table Columns Column Selected An unlabeled check box that indicates (if selected) that the real-time synchronization process will be initiated or stopped for records of a particular type if you click Process or Stop on the form toolbar. Status The current status of the real-time synchronization process. Entity The type of records for which you can initiate or stop the real-time synchronization process. Import Scenario The import scenario to be used for real-time synchronization of records of a particular type. Export Scenario The export scenario to be used for real-time synchronization of records of a particular type. Salesforce Sync Form ID: (SF205020) This form is available only if the Salesforce Integration feature is enabled on the Enable/Disable Features (CS100000) form. You use this form to configure data synchronization between Acumatica ERP and Salesforce. For details, see Quick Configuration Steps. Table In this table, you can add or remove types of records whose data can be synchronized between Acumatica ERP and Salesforce and specify the integration scenarios to be used for synchronization. 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 below. Table Columns Column Entity The type of records whose data can be synchronized between Acumatica ERP and Salesforce. Import Scenario The import scenario to be used for importing records of the type from Salesforce to Acumatica ERP. Export Scenario The export scenario to be used for exporting records of the type from Acumatica ERP to Salesforce. Number of Attempts The maximum number of synchronization attempts. The first attempt is performed by the system during any synchronization process (realtime synchronization, full synchronization, or failed and missed data resynchronization) that is first initialized for the record. Each subsequent attempt is performed upon each run of the failed and missed data resynchronization until the specified number of attempts is reached. After that the system stops trying to synchronize the record.

198 Integration Form Reference 198 Salesforce Sync State Form ID: (SF205040) This form is available only if the Salesforce Integration feature is enabled on the Enable/Disable Features (CS100000) form. You use this form to review information about the current state of data synchronization between Salesforce and Acumatica ERP. Also, on this form, you can start the synchronization process for particular records in the table or for all listed records. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button Sync Initiates the synchronization process for the records that have the unlabeled check box selected in the table. Sync All Initiates the synchronization process for all records listed in the table. Selection Area You use the elements in this area to specify selection criteria for the records displayed in the table. Element Status The status of the records that you want to be listed in the table. The following options are available: Any: All modified records are listed in the table regardless of the status. Modified Locally: Only records that have been modified in Acumatica ERP are listed in the table. Modified Externally: Only records that have been modified in Salesforce are listed in the table. Synchronized: Only records whose data has been synchronized are listed in the table. Entity The type of records that you want to be listed in the table. The following options are available: Any, Contact, Lead, Opportunity, Stock Item, Non-Stock Item, and Business Account. Errors Only A check box that indicates (if selected) that only the records that failed to synchronize during the latest attempt due to some error will be listed in the table. Table The table toolbar includes only standard buttons. For the list of standard buttons, see Table Toolbar. Table Columns Column Selected An unlabeled check box that indicates (if selected) that synchronization will be initiated for records of a particular type if you click Sync on the form toolbar.

199 Integration Form Reference 199 Column Entity The type of the record. Local ID The identifier of the record in Acumatica ERP. Modified The date and time when the record data was modified in Acumatica ERP. Ext. Ref. The external reference to the corresponding record in Salesforce. Ext. Modified The date and time when the record data was modified in Salesforce. Operation The type of operation that modified the record data. The following options are available: Update, Delete, and Insert. Status The synchronization status of the record. The following options are available: Modified Locally: The record has been modified in Acumatica ERP. Modified Externally: The record has been modified in Salesforce. Synchronized: The record data has been synchronized between the systems. Error The error message displayed for this record if synchronization has failed. Latest Attempt The date and time of the latest synchronization attempt. Attempt Counter The number of synchronization attempts made for this record. 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. Form 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 below. Button View Endpoint Service Opens the description of the web service endpoint that is selected on the form. A web service endpoint exposes the objects and methods that a client application can use to transfer data to and from Acumatica ERP. The following options are available: WSDL: The WSDL description, which is used for the contract-based SOAP API. Once the browser window opens with the WSDL description of the endpoint, the address line contains the path that a client application should use to access the web service endpoint. OpenAPI 2.0: The OpenAPI 2.0 description, which is used for the contractbased REST API. For more information about the swagger.json file, which is opened, see Contract-Based REST API Reference. The option is available

200 Integration Form Reference 200 Button only if the endpoint with System Contract 2 or higher is selected on the form. 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 Acumatica ERP and importing the schema to Acumatica ERP. 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. 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 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 results of the validation. If the validation has failed, the error message contains the names of all fields that caused the error. 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 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.

201 Integration Form Reference 201 Element Endpoint Name The name of the endpoint. By default, only system endpoints (which have the name Default) are predefined in Acumatica ERP. Endpoint Version The version of the endpoint. By default, the following versions of system endpoints are predefined in Acumatica ERP: : This version, introduced in Acumatica ERP 5.3, has Contract Version : This version, introduced in Acumatica ERP 6, has Contract Version 2. The endpoint provides the same list of entities, fields, and actions as the Default/ endpoint does : This version, introduced in Acumatica ERP 2017R2, has Contract Version 3. The endpoint provides an extended list of entities as compared with the list of entities of the Default/ endpoint. For details on the differences between the contract versions, see Comparison of Contract Versions. For the list of entities in the endpoints, see Contract-Based REST API Reference. 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. Pane Toolbar The toolbar on the pane includes only custom button, which is described in the following table. Button Insert Brings up a dialog box 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.

202 Integration Form Reference 202 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 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 does not appear in the dialog box if the Use Existing Entity check box is selected. Object Type The type of the created entity. The following options are available: Top-Level: This the only available option if you insert an entity into an endpoint node. Entities of this type are the main entities of the contract. A top-level entity usually corresponds to an Acumatica ERP 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: These entities are supplementary entities of a contract. 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 the default endpoint contains the linked entity 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: Detail entities correspond 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 default endpoint contains the detail entity SalesOrderDetail, which corresponds to a detail line on the Document Details tab of the Sales Orders (SO301000) form. This option is not available if you insert an entity into an endpoint node. Screen ID The Acumatica ERP form to which the entity should correspond.

203 Integration Form Reference 203 Element 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. 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 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. 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. Endpoint Properties Tab This tab appears in the right pane of the form if the endpoint is selected in the left pane. On this tab, you can view the properties of the endpoint. Element Endpoint Name The name of the selected endpoint. Endpoint Version The version of the selected endpoint. 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.

204 Integration Form Reference 204 Element 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 an entity. Element 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: Entities of this type are the main entities of the contract. A top-level entity usually corresponds to an Acumatica ERP 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: These entities are the supplementary entities of a contract. 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 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: Detail entities correspond 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 Document Details tab of the Sales Orders (SO301000) form. Screen ID The Acumatica ERP form to which the selected entity corresponds. This box appears on the tab if a top-level entity is selected on the left pane. Active A check box that indicates (if selected) that the entity is available in the API of the endpoint. 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, for a custom endpoint, modify the list of fields. The table on the tab has the following columns.

205 Integration Form Reference 205 Column 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. 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. Field Type The type of the entity field. 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 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 if, when creating a custom endpoint, 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 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 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 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. Active A check box that indicates (if selected) that the action is available in the API of the endpoint.

206 Integration Form Reference 206 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, for a custom endpoint, modify the parameters. The table on the tab has the following columns. Column 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. Parameter Type The type of the action parameter. 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 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 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 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, corresponding Acumatica ERP feature must be enabled on the Enable/Disable Features (CS100000) form. For information on Acumatica ERP basic functionality and addon features, see Overview of the Acumatica ERP Features. Element 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 A check box that indicates (if selected) that the fields that correspond to the Selectors 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.

207 Integration Form Reference 207 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 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 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. Web Services Form ID: (SM207040) You use this form to configure the Acumatica ERP screen-based web services API for your client application; you can also use the form to view the details of existing web services. On this form, you can configure a service that provides the methods for working with the selected Acumatica ERP forms. By using the methods of the created service, a client application can transfer data to and from Acumatica ERP through these forms. Form Toolbar The form toolbar includes standard and form-specific buttons. For the list of standard buttons, see Form Toolbar. The form-specific buttons are listed below. Button Generate Starts the process of generating the WSDL description of the service with the selected parameters. After the service is generated, the Is Generated check box is selected for this service. View Generated Opens the browser window with the WSDL description of the service selected on the form. The address line contains the path that a client application should use to access this service. This button is available if the Is Generated check box is selected for the service. View Untyped Opens a browser window with the WSDL description of the service that provides untyped methods, which work with arrays of containers and fields instead of structured data for each Acumatica ERP form with which the standard methods work. Untyped methods are not specific for each form: The same untyped method can work with different Acumatica ERP forms. Summary Area By using the elements of this area, you can select a service on the form (by selecting its service ID) and view its main properties.

208 Integration Form Reference 208 Element Service ID The identifier of the service. When you are creating a service, you must specify a service ID. A user-provided description of the service. Is Generated A check box that indicates (if selected) that the WSDL description of the service has already been generated. Current System Version The build number of the current Acumatica ERP application instance. System Time The system time when the selected service was most recently generated. System Version The build number of the Acumatica ERP application instance on which the selected service was most recently generated. Import A check box that indicates (if selected) that by default, the import operation will be available for all forms of the service that is, the Import check box will be selected for all newly added lines in the table in the lower right pane of the form. Export A check box that indicates (if selected) that by default, the export operation will be available for all forms of the service that is, the Export check box will be selected for all newly added lines in the table in the lower right pane of the form. Submit A check box that indicates (if selected) that by default, the submit operation will be available for all forms of the service that is, the Submit check box will be selected for all newly added lines in the table in the lower right pane of the form. Include Untyped A check box that indicates (if selected) that untyped methods should be included in the WSDL description of the service. The untyped methods in WSDL have the Untyped prefix in their names for example, UntypedExport. The untyped methods work with arrays of containers and fields; the same untyped method can work with different Acumatica ERP forms. Conversely, the standard methods work with structured data for each Acumatica ERP form; standard methods are specific for each form. Left Pane On this pane, you can select the Acumatica ERP forms your client application will work with through the service. Pane Toolbar The toolbar on the pane includes only custom buttons, which are described in the following table. Button Add to Grid Adds the form that you have selected on the left pane to the list of forms that should be available through the service in the table on the right pane. Right Pane In the table on this pane, you can view and edit the list of Acumatica ERP forms that should be available through the service and the list of operations for working with these forms. The API methods for the operations with these forms are included in the WSDL description of the service.

209 Integration Form Reference 209 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 below. Button Reset Usage Sets the default values in the Import, Export, and Submit columns for all lines of the table. The default values are defined by the Import, Export, and Submit check boxes of the Summary area. Table Columns Column Active A check box that indicates (if selected) that the API methods for the Acumatica ERP form specified in this line should be included in the WSDL description of the service. Generated A check box that indicates (if selected) that the WSDL description of the service already includes the API methods for the Acumatica ERP form specified in this line. Screen ID The ID of the Acumatica ERP form to be available through the service. Title The name of the Acumatica ERP form to be available through the service. Import A check box that indicates (if selected) that the WSDL description of the service will include the import method for the Acumatica ERP form specified in this line. If the import method for the Acumatica ERP form is included in the WSDL description of the service, the client application can import records to this form. Export A check box that indicates (if selected) that the WSDL description of the service will include the export method for the Acumatica ERP form specified in this line. If the export method for the Acumatica ERP form is included in the WSDL description of the service, the client application can export records from this form. Submit A check box that indicates (if selected) that the WSDL description of the service will include the submit method for the Acumatica ERP form specified in this line. If the submit method for the Acumatica ERP form is included in the WSDL description of the service, the client application can submit data to this form and get the result of processing.

210 Contract-Based SOAP API Reference 210 Contract-Based SOAP API Reference In this chapter, you will find the reference information for the main objects and methods of the contract-based SOAP API; these objects and methods are used to transfer data to and from Acumatica ERP. This chapter covers the following methods, which are exposed by the DefaultSoapClient class: : Semantics and syntax of some methods and properties are different depending on the version of the system contract. Login() Method Logout() Method SetBusinessDate() Method Get() Method GetList() Method (Contract Version 3) GetList() Method (Contract Version 2) GetList() Method (Contract Version 1) Put() Method Delete() Method Invoke() Method GetProcessStatus() Method GetFiles() Method PutFiles() Method GetCustomFieldSchema() Method You will also find descriptions of the following properties: Attributes Property CustomFields Property (Contract Version 2) CustomFields Property (Contract Version 1) ReturnBehavior Property (Contract Version 3) ReturnBehavior Property (Contract Version 2) Login() Method You use the Login() method of a DefaultSoapClient object to make the client application log in to Acumatica ERP. Syntax public void Login(string name, string password, string company, string branch, string locale) Parameters name: The username that should be used to log in to Acumatica ERP, such as "admin". password: The password that should be used to log in to Acumatica ERP, such as "123".

211 Contract-Based SOAP API Reference 211 company: The company name to which the client application should log in, such as "MyCompany". branch: The branch of the company to which the client application should log in, such as "MYSTORE". locale: The locale that should be used in Acumatica ERP. You should specify the locale in the System.Globalization.CultureInfo format converted to string, as with "EN-US". : This parameter has been developed for future use. You do not need to set its value. Example The following code causes the client to log in to Acumatica ERP by using the parameters that are specified in the application settings. using (var soapclient = new DefaultSoapClient()) //Log in to Acumatica ERP soapclient.login ( Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.CompanyName, Properties.Settings.Default.Branch, null ); Usage Notes For each call of the Login() method, you must call the Logout() method after you finish your work with Acumatica ERP to close the session. Logout() Method You use the Logout() method of a DefaultSoapClient object to make the client application log out from Acumatica ERP. Syntax public void Logout() Example The following code shows how to make the client application log out from Acumatica ERP. using (var soapclient = new DefaultSoapClient()) //Log in to Acumatica ERP... try //Work with Acumatica ERP through the web services API finally //Log out from Acumatica ERP soapclient.logout();

212 Contract-Based SOAP API Reference 212 Usage Notes For each call of the Login() method, you must call the Logout() method after you finish your work with Acumatica ERP to close the session. Therefore, we recommend that you call the Logout() method within the finally block. SetBusinessDate() Method You use the SetBusinessDate() method to specify the business date in Acumatica ERP. You can set the business date to any date to make the system insert this date into the date fields by default. The business date is inserted into any new document that you create and is used in the default selection parameters that appear on processing and inquiry screens. Syntax public void SetBusinessDate(System.DateTime businessdate) Parameter businessdate: The business date that should be used in Acumatica ERP. Usage Notes The business date resets to the current date of your computer after each login. Therefore, if you need to specify a business date in your application, you should call the SetBusinessDate() method after each client application login. Get() Method You use the Get() method to get one record that satisfies the specified conditions from Acumatica ERP. The conditions must specify only one record in Acumatica ERP; otherwise, an error is returned. If you need to get multiple records that satisfy the specified conditions, use the GetList() method instead. Syntax public Entity Get(Entity entity) Parameter entity: The entity that specifies the record that should be obtained from Acumatica ERP. Return Value The method returns the Entity object that corresponds to the specified record. Example The following code gets a customer record with the specified customer ID. Customer customer = new Customer CustomerID = new StringSearch Value = "C ", ;

213 Contract-Based SOAP API Reference 213 Customer customerdata = (Customer)soapClient.Get(customer); GetList() Method (Contract Version 3) : This topic describes the GetList() method that is available in Version 3 of the system contract. You use the GetList() method to retrieve from an Acumatica ERP data entry form a list of records that satisfy the specified conditions. : Do not use the GetList() method to retrieve the records from an inquiry form; instead, use the Put() method. Syntax public Entity[] GetList(Entity entity) Parameter entity: The entity that specifies the conditions that must be met for the records to be returned from Acumatica ERP. Return Value The method returns the array of Entity objects that correspond to the specified records. Example The following example gets the list of stock items that have the Active status and that were modified within the past month. The code returns only the top-level fields of each stock item record (no fields of the detail or linked entities are returned). //Filter the items by the last modified date and status StockItem stockitemstobefound = new StockItem LastModified = new DateTimeSearch Value = DateTime.Now.AddMonths(-1), Condition = DateTimeCondition.IsGreaterThan, ItemStatus = new StringSearch Value = "Active" ; //Get the list of stock items Entity[] stockitems = soapclient.getlist(stockitemstobefound); Usage Notes To specify the fields whose values you need to obtain for each entity, you use the ReturnBehavior property of the entity. When the GetList() method is called, the system tries to optimize the retrieval of the records and obtain all needed records in one request to the database (instead of requesting the records one by one). If the optimization fails, the system returns an error, which specifies the entities or fields that caused the failure of the optimized request. To prevent the error from being generated, you can do any of the following: If you do not need to retrieve the entities or fields that caused the failure, you can exclude these entities or fields from the list of requested fields by setting the ReturnBehavior

214 Contract-Based SOAP API Reference 214 property to None for the entities, or by using the Skip classes of the needed value type (such as StringSkip) for the fields. If you need to retrieve the entities of fields that have caused the failure, you can retrieve the needed records one by one by using the Get() method. GetList() Method (Contract Version 2) : This topic describes the GetList() method that is available in Version 2 of the system contract. You use the GetList() method to retrieve from an Acumatica ERP data entry form a list of records that satisfy the specified conditions. : Do not use the GetList() method to retrieve the records from an inquiry form; instead, use the Put() method. Syntax public Entity[] GetList(Entity entity) Parameter entity: The entity that specifies the conditions that must be met for the records to be returned from Acumatica ERP. Return Value The method returns the array of Entity objects that correspond to the specified records. Example The following example gets the list of stock items that have the Active status and that were modified within the past month. The code returns all fields of each stock item record. //Filter the items by the last modified date and status StockItem stockitemstobefound = new StockItem LastModified = new DateTimeSearch Value = DateTime.Now.AddMonths(-1), Condition = DateTimeCondition.IsGreaterThan, ItemStatus = new StringSearch Value = "Active" ; //Get the list of stock items Entity[] stockitems = soapclient.getlist(stockitemstobefound); Usage Notes To specify the fields whose values you need to obtain for each entity, you use the ReturnBehavior property of the entity. When the GetList() method is called, the system tries to optimize the retrieval of the records and obtain all needed records in one request to the database. If the optimization fails, the system obtains the records one by one, which may significantly increase the time of data retrieval.

215 Contract-Based SOAP API Reference 215 GetList() Method (Contract Version 1) : This topic describes the GetList() method that is available in Version 1 of the system contract. You use the GetList() method to retrieve from an Acumatica ERP data entry form a list of records that satisfy the specified conditions. : Do not use the GetList() method to retrieve the records from an inquiry form; instead, use the Put() method. Syntax public Entity[] GetList(Entity entity, bool returnfullentities) Parameters entity: The entity that specifies the conditions that must be met for the records to be returned from Acumatica ERP. returnfullentities: The Boolean value that specifies whether the master-detail records should be returned with detail lines. If the value of this property is set to false, the detail lines of the returned master-detail records have null values. Return Value The method returns the array of Entity objects that correspond to the specified records. Example The following example gets the list of stock items that have the Active status and that were modified within the past month. All detail lines of stock item records (for example, warehouse details) have null values as a result of the code execution. //Filter the items by the last modified date and status StockItem stockitemstobefound = new StockItem LastModified = new DateTimeSearch Value = DateTime.Now.AddMonths(-1), Condition = DateTimeCondition.IsGreaterThan, ItemStatus = new StringSearch Value = "Active" ; //Get the list of stock items Entity[] stockitems = soapclient.getlist(stockitemstobefound, false); Put() Method You use the Put() method to create or modify a record on a data entry form of Acumatica ERP. For example, by using the Put() method, you can create a customer record on the Customers (AR303000) form. You also use this method to retrieve data from an inquiry form. For example, by using the Put() method, you can retrieve data from the Inventory Summary (IN401000) form.

216 Contract-Based SOAP API Reference 216 Syntax public Entity Put(Entity entity) Parameter entity: The entity that specifies the values of the fields of the created record, or the entity that specifies the record that should be modified and the values of the fields that should be modified in this record. : If you use this method to create or modify a record on a data entry form, the entity must specify only one record in Acumatica ERP. If the entity specifies more than one record or no records, an error is returned during the execution of the method. Return Value The method returns the Entity object that corresponds to the created or modified record. Example 1: Creating a Record The following example creates a customer record with the specified field values in Acumatica ERP. //Specify the values of a new customer record Customer customertobecreated = new Customer CustomerID = new StringValue Value = "JOHNGOOD", CustomerName = new StringValue Value = John Good", MainContact = new Contact = new StringValue Value = "demo@gmail.com", Address = new Address AddressLine1 = new StringValue Value = "43 Lake Washington Blvd NE", AddressLine2 = new StringValue Value = "Suite 100", City = new StringValue Value = "Kirkland", State = new StringValue Value = "WA", PostalCode = new StringValue Value = "98033" ; //Create a customer record with the specified values Customer newcustomer = (Customer) soapclient.put(customertobecreated); Example 2: Updating a Record The following example searches for the needed customer record in Acumatica ERP by the address and updates the record with the specified customer class value. //Select the needed customer record and //specify the values that should be updated var customertobeupdated = new Customer MainContact = new Contact //Search for the customer record by address = new StringSearch Value = "info@jevy-comp.con", CustomerClass = new StringValue Value = "INTL" ; ; //Update the customer record with the specified values var updcustomer = (Customer)soapClient.Put(customerToBeUpdated);

217 Contract-Based SOAP API Reference 217 Example 3: Retrieving Data from an Inquiry Form The following example retrieves the values of all elements available for a stock item from the Inventory Summary (IN401000) inquiry form. //Filter details by warehouse InventorySummaryInquiry stockitemstobefound = new InventorySummaryInquiry InventoryID = new StringValue Value = "AALEGO500", WarehouseID = new StringValue Value = "MAIN" ; //Retrieve the list of stock items from the inquiry InventorySummaryInquiry stockitems = (InventorySummaryInquiry)soapClient.Put(stockItemsToBeFound); foreach (InventorySummaryRow stockitem in stockitems.results) //Do something with the results... Usage Notes When the Acumatica ERP web services receive a Put request that contains an entity with at least one Search object, Acumatica ERP tries to search for a record by using the specified search value or values, and does one of the following: If the record that satisfies the specified conditions has been found, Acumatica ERP updates the fields of the record that are specified by using the Value objects. If no record has been found that satisfies the specified conditions, a new record is inserted. Note that the values that were specified with the Search objects are inserted into the created record in the same way as the values specified with the Value objects are inserted. If multiple records have been found, Acumatica ERP returns an error. For the key fields of a record that are passed in the Put request as Value objects, the service converts the corresponding Value objects to Search objects. When the Acumatica ERP web services receive a Put request that contains only Value, Return, and Skip objects without key fields specified, Acumatica ERP adds a new record with the specified values. The workflow of a Put request is illustrated in the following diagram.

218 Contract-Based SOAP API Reference 218

219 Contract-Based SOAP API Reference 219 Delete() Method You use the Delete() method to delete a record from Acumatica ERP. Syntax public void Delete(Entity entity) Parameter entity: The entity that specifies the record that should be deleted. : The entity must specify only one record in Acumatica ERP. If the entity specifies more than one record or no records, an error is returned during the execution of the method. Usage Notes The Delete() method is used to delete only the records that correspond to top-level entities. If you need to delete a detail line of a record, you should set the Delete property of the entity that corresponds to the detail line to true and pass the top-level entity that contains this entity to Acumatica ERP by using the Put() method. Invoke() Method You use the Invoke() method to invoke an action on a record in Acumatica ERP (for example, to perform the release action on a document). Syntax public InvokeResult Invoke(Entity entity, Action action) Parameters entity: The entity that specifies the record on which the action should be invoked. : The entity must specify only one record in Acumatica ERP. If the entity specifies more than one record or no records, an error is returned during method execution. action: The action that should be invoked on the record. Return Value The method returns an InvokeResult object, which you should use to monitor the status of the longrunning operation by using the GetProcessStatus() method. Example The following code releases a payment. //Find the payment that should be released Payment sopaymenttobereleased = new Payment Type = new StringSearch Value = "Payment", ReferenceNbr = new StringSearch Value = "000001" ; Payment payment = (Payment)soapClient.Get(soPaymentToBeReleased);

220 Contract-Based SOAP API Reference 220 //Release the payment InvokeResult invokeresult = soapclient.invoke(payment, new ReleasePayment()); //Monitor the status of the release operation... GetProcessStatus() Method You use the GetProcessStatus() method to monitor the status of a long-running operation (such as the release or confirmation operation) that you invoked by using the Invoke() method. Syntax public ProcessResult GetProcessStatus(InvokeResult invokeresult) Parameter invokeresult: An InvokeResult object that was returned by the Invoke() method. Return Value The method returns a ProcessResult object. You should use the Status property of this object to get the status of the processing operation. When the status of the operation is Completed, you can get the result of processing, which is identified by the EntityID property of a ProcessResult object. Example The following code monitors the status of the payment release processing.... //Release payment InvokeResult invokeresult = soapclient.invoke(payment, new ReleasePayment()); //Monitor the status of the process ProcessResult processresult = soapclient.getprocessstatus(invokeresult); while (processresult.status == ProcessStatus.InProcess) Thread.Sleep(1000); //pause for 1 second processresult = soapclient.getprocessstatus(invokeresult); if (processresult.status == ProcessStatus.Completed) //Get the released payment payment = (Payment)soapClient.Get( new Payment ID = processresult.entityid ); GetFiles() Method You use the GetFiles() method to get the files that are attached to a record. Syntax public File[] GetFiles(Entity entity) Parameter entity: The entity that specifies the record in Acumatica ERP to which the files are attached.

221 Contract-Based SOAP API Reference 221 Return Value The method returns an array of web service File objects that contain the properties for accessing the contents and names of the files. Example The following example retrieves the files attached to a stock item record. //Filter the items by inventory ID StockItem stockitemtobefound = new StockItem InventoryID = new StringSearch Value = "AAMACHINE1" ; //Get the stock item record StockItem stockitem = (StockItem) soapclient.get(stockitemtobefound); //Get the files that are attached to the stock item if (stockitem!= null && stockitem.imageurl!= null) //Get the attached files File[] files = soapclient.getfiles(stockitem);... ; PutFiles() Method You use the PutFiles() method to attach files to a record in Acumatica ERP. Syntax public void PutFiles(Entity entity, File[] files) Parameters entity: The entity that specifies the record to which the files should be attached. files: An array of web service File objects that specify the files to be attached. Example The following code attaches a file to a stock item record. //Find the needed stock item StockItem stockitemtobefound = new StockItem InventoryID = new StringSearch Value = "AALEGO500", ; StockItem stockitem = (StockItem)soapClient.Get(stockItemToBeFound); //Read the file data byte[] filedata; using (FileStream file = System.IO.File.Open("D:\\T2MCRO.jpg", FileMode.Open)) filedata = new byte[file.length]; file.read(filedata, 0, filedata.length); //Add the file to the stock item record Default.File[] stockitemfiles = new[]

222 Contract-Based SOAP API Reference 222 //Default is the name of the service reference new Default.File Name = filename, Content = filedata ; soapclient.putfiles(stockitem,stockitemfiles); GetCustomFieldSchema() Method You use the GetCustomFieldSchema() method to obtain the list of custom fields of an entity. You can find out the field name and view name of the needed element by using this method. Depending on the version of the system contract, this method returns different set of fields: In Contract Version 2, custom fields correspond to both the predefined elements on an Acumatica ERP form that are not included in the entity definition and the elements that were added to the Acumatica ERP form in a customization project; in Contract Version 1, custom fields correspond to only the elements that were added to an Acumatica ERP form in a customization project. Syntax public Entity GetCustomFieldSchema(Entity entity) Parameter entity: The entity for which the list of custom fields should be obtained. Return Value The method returns the Entity object, which contains the array of custom fields in its CustomFields property. Example The following example retrieves the list of custom fields of the StockItem entity. StockItem stockitem = (StockItem) soapclient.getcustomfieldschema(new StockItem()); CustomField[] customfields = stockitem.customfields; Attributes Property By using the Attributes property, you can view and edit the attributes of a record in Acumatica ERP. Through this property, you work with an array of AttributeValue objects. : In Version of the default endpoint, you can work with attributes of only stock item records. To specify the value of an attribute, you specify the name of the attribute in the AttributeID property of an AttributeValue object, and the value of the attribute in the Value property of this AttributeValue object. Syntax public AttributeValue[] Attributes set; get;

223 Contract-Based SOAP API Reference 223 Example The following code shows how to edit the attributes of a stock item record. //Specify the values of a stock item record StockItem stockitemtobecreated = new StockItem InventoryID = new StringValue Value = "BASESERV", ItemClass = new StringValue Value = "STOCKITEM", Attributes = new [] //Specify the values of attributes of the item class (STOCKITEM) new AttributeValue AttributeID = new StringValue Value = "Operation System", Value = new StringValue Value = "Windows", new AttributeValue AttributeID = new StringValue Value = "Version Of Software", Value = new StringValue Value = "Server 2012 R2" ; //Create a stock item with the specified values StockItem newstockitem = (StockItem)soapClient.Put(stockItemToBeCreated); CustomFields Property (Contract Version 2) : This topic describes the CustomFields property that is available in Version 2 of the system contract. By using the CustomFields property, you can view and edit the values of the elements that are not included in the entity definition. That is, custom fields can correspond to both the predefined elements on an Acumatica ERP form that are not included in the entity definition and the elements that were added to the Acumatica ERP form in a customization project. Through the CustomFields property, you work with an array of CustomField objects. This property is exposed by the Entity class that is, all entities of the web services API expose this property. To get or set the value of an element that is not included in the entity definition, you should use the CustomFields property of the entity that contains this element. To work with the needed element in the CustomFields array, you specify the values of the fieldname and viewname properties of the CustomField object of the needed type. In the viewname property, you specify the name of the data view that contains the element, and in the fieldname property, you specify the internal name of the element. For details on how to find out the field name and the name of the data view, see Custom Fields. For example, suppose that you added the Personal ID element to the Main Contact area of the Customers (AR303000) form in a customization project. To work with this customization element through the web services API, you should use the CustomFields property of the Contact entity, which is available through the MainContact property of the Customer entity. The Personal ID customization element has the String type and has the UsrPersonalID field name and belongs to the DefContact data view. Therefore, to access this element, you should set the fieldname property of the CustomStringField object to UsrPersonalID, and the viewname property of the CustomStringField object to DefContact. Syntax public CustomField[] CustomFields set; get;

224 Contract-Based SOAP API Reference 224 Example Suppose that you added the Personal ID Type, Personal ID, and Credit Record Verified elements to the Customers form in a customization project, as shown in the following screenshot. Figure: Custom elements The following code shows how to specify the values of these custom elements through the web services API. //Specify the values of a new customer record Customer customertobecreated = new Customer CustomerID = new StringValue Value = "TEDSMITH", CustomerName = new StringValue Value = "Ted Smith", //Specify the values of the custom fields MainContact = new Contact CustomFields = new[] new CustomStringField fieldname = "UsrPersonalIDType", viewname = "DefContact", Value = new StringValue Value = "Passport", new CustomStringField fieldname = "UsrPersonalID", viewname = "DefContact", Value = new StringValue Value = customerpersonalid, new CustomBooleanField

225 Contract-Based SOAP API Reference 225 fieldname = "UsrCreditRecordVerified", viewname = "DefContact", Value = new BooleanValue Value = true ; //Create a customer record with the specified values Customer newcustomer = (Customer)soapClient.Put(customerToBeCreated); Usage Notes To work with elements of an object that was added in a customization project or with a custom Acumatica ERP form, you have to create a custom endpoint for the needed form. You can create a custom endpoint on the Web Service Endpoints (SM207060) form. For details on creation of a custom endpoint, see To Create a Custom Endpoint and To Extend an Existing Endpoint. CustomFields Property (Contract Version 1) : This topic describes the CustomFields property that is available in Version 1 of the system contract. By using the CustomFields property, you can view and edit the values of the elements that were added to an Acumatica ERP form in a customization project. Through this property, you work with an array of CustomField objects. This property is exposed by the Entity class that is, all entities of the web services API expose this property. To get or set the value of a custom element, you should use the CustomFields property of the entity that contains this custom element. To work with the needed element in the CustomFields array, you specify the Name property of a CustomField object in the following format: <ViewName> <FieldName>, where <ViewName> is the name of the data view that contains the custom element, and <FieldName> is the internal name of the custom element. For details on how to find out the field name and the name of the data view, see Custom Fields. You can learn the details of working with the customization projects of Acumatica ERP by taking the T300 Acumatica Customization Platform training course. For example, suppose that you added the Personal ID custom element to the Main Contact area of the Customers (AR303000) form in a customization project. To work with this custom element through the web services API, you should use the CustomFields property of the Contact entity, which is available through the MainContact property of the Customer entity. The Personal ID custom element has the UsrPersonalID field name and belongs to the DefContact data view. Therefore, to access this element, you should specify the Name property of the CustomField object as follows: DefContact UsrPersonalID. Syntax public CustomField[] CustomFields set; get; Example Suppose that you added the Personal ID Type, Personal ID, and Credit Record Verified elements to the Customers form in a customization project, as shown in the following screenshot.

226 Contract-Based SOAP API Reference 226 Figure: Custom elements The following code shows how to specify the values of these custom elements through the web services API. //Specify the values of a new customer record Customer customertobecreated = new Customer CustomerID = new StringValue Value = "TEDSMITH", CustomerName = new StringValue Value = "Ted Smith", //Specify the values of the custom fields MainContact = new Contact CustomFields = new[] new CustomStringField Name = "DefContact UsrPersonalIDType", //The internal name of //the Personal ID Type element Value = new StringValue Value = "Passport", new CustomStringField Name = "DefContact UsrPersonalID", //The internal name of //the Personal ID element Value = new StringValue Value = customerpersonalid, new CustomBooleanField Name = "DefContact UsrCreditRecordVerified", //The internal name of //the Credit Record Verified check box Value = new BooleanValue Value = true

227 Contract-Based SOAP API Reference 227 ; //Create a customer record with the specified values Customer newcustomer = (Customer)soapClient.Put(customerToBeCreated); Usage Notes To work with custom elements of a custom object or with a custom Acumatica ERP form, you have to create a custom endpoint for the needed form. You can create a custom endpoint on the Web Service Endpoints (SM207060) form. For details on creation of a custom endpoint, see To Create a Custom Endpoint and To Extend an Existing Endpoint. ReturnBehavior Property (Contract Version 3) : This topic describes the ReturnBehavior property that is available in Version 3 of the system contract. By using the ReturnBehavior property, you can specify the fields of the entity whose values should be returned from the request to the service that is performed by the Get(), GetList(), or Put() method. This property is exposed by the Entity class that is, all entities of the web services API expose this property. For each entity, you can specify one of the following options, which determine the fields for which values should be returned: None: Values should not be returned for any fields of the entity. You can use this option for detail entities and linked entities, but not for top-level entities. OnlySystem: Values should be returned for only the system fields (that is, the fields of the Entity class, such as ID, RowNumber, and Note). You may need to obtain only the values of the system fields, for example, if you want to delete the entity. OnlySpecified: Values should be returned for only the specified fields of the entity and the system fields. You can specify the values to be returned by using the Return classes of the needed value type, such as StringReturn. The values of the fields that are specified by using the Value or Search classes of the corresponding value type, such as StringValue and StringSearch, are returned automatically. Default: Values should be returned for only the fields of the entity that are defined in the entity itself (without the fields of the linked and detail entities defined within the entity). This option is used by default. All: Values should be returned for all fields of the entity that are defined in the contract (including the fields of the linked and detail entities defined within the entity). No values of the custom fields (the Acumatica ERP fields that are not defined in the contract or the fields that are defined in a customization project) are returned. You can specify the values to be skipped by using the Skip classes of the needed value type, such as StringSkip. In the sections below, you can find examples of how to specify the fields whose values should be returned. Syntax public ReturnBehavior ReturnBehavior set; get;

228 Contract-Based SOAP API Reference 228 Example: Obtaining All Fields The following example shows how to obtain the values of all fields of all stock item records in the system. StockItem stockitemstobefound = new StockItem ReturnBehavior = ReturnBehavior.All ; //Get the list of stock items with the values of all fields //that are defined in the contract Entity[] stockitems = soapclient.getlist(stockitemstobefound); Example: Obtaining Only the Fields of the Entity Itself Without Linked and Detail Fields In the following example, only the fields of the top-level StockItem entity are retrieved from the system. //You can omit the setting of the ReturnBehavior property to ReturnBehavior.Default //because this option is used by default StockItem stockitemstobefound = new StockItem(); //Get the list of stock items with the values of the fields //of the StockItem entity itself (without the fields of the detail or linked entities) Entity[] stockitems = soapclient.getlist(stockitemstobefound); Example: Obtaining Only Specified Fields The following example shows how to obtain the values of the InventoryID field, the ItemStatus field, and all WarehouseDetail fields of all stock item records in the system. StockItem stockitemstobefound = new StockItem ReturnBehavior = ReturnBehavior.OnlySpecified, InventoryID = new StringReturn(), ItemStatus = new StringSearch Value = "Active", WarehouseDetails = new StockItemWarehouseDetail[] new StockItemWarehouseDetail ReturnBehavior = ReturnBehavior.All, ; //Get the list of stock items with the values of the specified fields Entity[] stockitems = soapclient.getlist(stockitemstobefound); Example: Obtaining All Fields Except the Specified Ones The following example shows how to obtain the values of all fields of all stock item records in the system except the LastModified field and all WarehouseDetail fields. StockItem stockitemstobefound = new StockItem ReturnBehavior = ReturnBehavior.All, LastModified = new DateTimeSkip(), WarehouseDetails = new StockItemWarehouseDetail[] new StockItemWarehouseDetail ReturnBehavior = ReturnBehavior.None, ; //Get the list of stock items with the values of the specified fields Entity[] stockitems = soapclient.getlist(stockitemstobefound);

229 Contract-Based SOAP API Reference 229 Example: Obtaining Only System Fields The following example shows how to obtain the values of only system fields of all stock item records in the system. StockItem stockitemtobefound = new StockItem ReturnBehavior = ReturnBehavior.OnlySystem, ; //Get the list of stock items with the values of system fields Entity[] stockitems = soapclient.getlist(stockitemtobefound); ReturnBehavior Property (Contract Version 2) : This topic describes the ReturnBehavior property that is available in Version 2 of the system contract. By using the ReturnBehavior property, you can specify the fields of the entity whose values should be returned from the request to the service that is performed by the Get(), GetList(), or Put() method. This property is exposed by the Entity class that is, all entities of the web services API expose this property. For each entity, you can specify one of the following options, which determine the fields for which values should be returned: None: Values should not be returned for any fields of the entity. You can use this option for detail entities and linked entities, but not for top-level entities. OnlySystem: Values should be returned for only the system fields (that is, the fields of the Entity class, such as ID, RowNumber, and Note). You may need to obtain only the values of the system fields, for example, if you want to delete the entity. OnlySpecified: Values should be returned for only the specified fields of the entity and the system fields. You can specify the values to be returned by using the Return classes of the needed value type, such as StringReturn. The values of the fields that are specified by using the Value or Search classes of the corresponding value type, such as StringValue and StringSearch, are returned automatically. All: Values should be returned for all fields of the entity that are defined in the contract. No values of the custom fields (the Acumatica ERP fields that are not defined in the contract or the fields that are added in a customization project and are not included in the contract) are returned. You can specify the values to be skipped by using the Skip classes of the needed value type, such as StringSkip. This option is used by default. In the sections below, you can find examples of how to specify the fields whose values should be returned. Syntax public ReturnBehavior ReturnBehavior set; get; Example: Obtaining All Fields The following example shows how to obtain the values of all fields of all stock item records in the system. //You can omit the setting of the ReturnBehavior property to ReturnBehavior.All //because this option is used by default StockItem stockitemstobefound = new StockItem();

230 Contract-Based SOAP API Reference 230 //Get the list of stock items with the values of all fields //that are defined in the contract Entity[] stockitems = soapclient.getlist(stockitemstobefound); Example: Obtaining Only Specified Fields The following example shows how to obtain the values of the InventoryID field, the ItemStatus field, and all WarehouseDetail fields of all stock item records in the system. StockItem stockitemstobefound = new StockItem ReturnBehavior = ReturnBehavior.OnlySpecified, InventoryID = new StringReturn(), ItemStatus = new StringSearch Value = "Active", WarehouseDetails = new StockItemWarehouseDetail[] new StockItemWarehouseDetail ReturnBehavior = ReturnBehavior.All, ; //Get the list of stock items with the values of the specified fields Entity[] stockitems = soapclient.getlist(stockitemstobefound); Example: Obtaining All Fields Except the Specified Ones The following example shows how to obtain the values of all fields of all stock item records in the system except the LastModified field and all WarehouseDetail fields. StockItem stockitemstobefound = new StockItem ReturnBehavior = ReturnBehavior.All, LastModified = new DateTimeSkip(), WarehouseDetails = new StockItemWarehouseDetail[] new StockItemWarehouseDetail ReturnBehavior = ReturnBehavior.None, ; //Get the list of stock items with the values of the specified fields Entity[] stockitems = soapclient.getlist(stockitemstobefound); Example: Obtaining Only System Fields The following example shows how to obtain the values of only system fields of all stock item records in the system. StockItem stockitemtobefound = new StockItem ReturnBehavior = ReturnBehavior.OnlySystem, ; //Get the list of stock items with the values of system fields Entity[] stockitems = soapclient.getlist(stockitemtobefound);

231 Contract-Based REST API Reference 231 Contract-Based REST API Reference Acumatica ERP provides the reference information for the methods of the contract-based REST API endpoint in the swagger.json file, which is an OpenAPI 2.0 (formerly known as Swagger 2.0) file. (For more information about the OpenAPI specification, see You can use this file to review the API of the endpoint and build the client applications of Acumatica ERP based on this file. Acumatica ERP 2017 R2 does not provide a user interface to view the swagger.json file. You can use external tools to view the file. You can retrieve the swagger.json file by clicking View Endpoint Service > OpenAPI 2.0 on the Web Service Endpoints (SM207060) form, or by using the following URL. endpoint URL>/swagger.json In this URL, <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work with Acumatica ERP. This URL has the following format: ERP instance URL>/entity/<Endpoint name>/<endpoint version>/. You can specify the company URL parameter to obtain information on the API of the endpoint available in a particular company. For example, suppose that you wanted to retrieve the API reference of the custom endpoint with the name MyEndpoint and Version available in the MyCompany company from a local Acumatica ERP instance with the name AcumaticaDB. You would use the following URL to obtain the swagger.json file. company=mycompany If no company is specified, the API of the endpoint available in the company to which the user is currently logged in is returned.

232 Screen-Based SOAP API Reference 232 Screen-Based SOAP API Reference In this chapter, you will find the reference information for the main methods of the screen-based web services API; these methods are used to transfer data to and from Acumatica ERP. This chapter covers the following objects, and the following methods, which are exposed by the Screen class: Login() Method Logout() Method SetLocaleName() Method SetBusinessDate() Method GetScenario() Method GetSchema() Method SetSchema() Method Export() Method Submit() Method Import() Method Clear() Method GetProcessStatus() Method Login() Method You use the Login() method to make the client application log in to Acumatica ERP. Syntax public LoginResult Login(string name, string password) Parameters name: The username that should be used to log in to Acumatica ERP, such as "admin". To log in to a specific Acumatica ERP company, specify the login as follows: UserName@CompanyName, where you should specify the user name instead of UserName and the company name instead of CompanyName. For example, if you log in to the company with the name Dollar as the user with the name admin, you should specify the login as admin@dollar. To log in to a company under a certain branch, specify the login as follows: UserName@CompanyName:BranchName, where you should specify the user name instead of UserName, the company name instead of CompanyName, and the branch name instead of BranchName. For example, if you log in to the East branch of the Dollar company as the user with the name admin, you should specify the login as admin@dollar:east. password: The password that should be used to log in to Acumatica ERP, such as "123". Return Value The method returns the LoginResult object, which contains the description of errors that occurred during login, if any.

233 Screen-Based SOAP API Reference 233 Example The following code logs in to Acumatica ERP by using the parameters that are specified in the application settings. Screen context = new Screen(); context.cookiecontainer = new System.Net.CookieContainer(); context.url = " context.login("admin@mycompany:mystore", "123"); Usage Notes Before you log in to Acumatica ERP by using the Login() method, do the following: 1. Initialize the CookieContainer property of the object with a new System.Net.CookieContainer(). The CookieContainer property is a standard property of an object of the HttpWebClientProtocol system type. (The Screen class is derived from the HttpWebClientProtocol class.) This property is used to maintain the session state for a client. 2. Specify the URL of the web service in the URL property of the object. This is the same URL that you specify when you add a web reference to the Acumatica ERP web service. You can change the URL of the service dynamically in your application if you need to switch between multiple Acumatica ERP web services. For each call of the Login() method, you must call the Logout() method after you finish your work with Acumatica ERP to close the session. Therefore, when you are working with the web services API, we recommend that you use the pattern that is shown in the following code. using ( //Connect to the web services and log in to Acumatica ERP Screen context = new Screen();... ) try //Import, export, or submit data... finally //Log out from Acumatica ERP context.logout(); Logout() Method You use the Logout() method to make the client application log out from Acumatica ERP. Syntax public void Logout()

234 Screen-Based SOAP API Reference 234 Usage Notes For each call of the Login() method, you must call the Logout() method after you finish your work with Acumatica ERP to close the session. Therefore, when you are working with the web services API, we recommend that you use the pattern that is shown in the following code. using ( //Connect to the web services and log in to Acumatica ERP Screen context = new Screen();... ) try //Import, export, or submit data... finally //Log out from Acumatica ERP context.logout(); SetLocaleName() Method You use the SetLocaleName() method to specify the locale for Acumatica ERP to correctly recognize the format of dates, numbers, and other country-specific data that is passed by using the web services API. By default, Acumatica ERP uses the invariant locale, which is similar to the English (United States) locale. Syntax public void SetLocaleName(string localename) Parameter localename: The locale that should be used in Acumatica ERP. You should specify the locale in the System.Globalization.CultureInfo format converted to string, such as "EN-US". Example The following code shows how to specify the appropriate locale with the SetLocaleName() method of the Screen object.... using System.Threading;... Screen context = new Screen(); context.setlocalename(thread.currentthread.currentculture.tostring()); SetBusinessDate() Method You use the SetBusinessDate() method to specify the business date in Acumatica ERP. You can set the business date to any date to make the system insert this date into the date fields by default. The business date is inserted into any new document that you create and is used in the default selection parameters that appear on processing and inquiry screens.

235 Screen-Based SOAP API Reference 235 Syntax public void SetBusinessDate(System.DateTime businessdate) Parameter businessdate: The business date that should be used in Acumatica ERP. Usage Notes The business date resets to the current date of your computer after each login. Therefore, if you need to specify a business date in your application, you should call the SetBusinessDate() method after each client application login. GetScenario() Method You use the GetScenario() method to retrieve the list of commands of an integration scenario that is configured in the system. Syntax public Command[] GetScenario(string scenario) Parameter scenario: The name of the import or export scenario for which the list of commands should be retrieved. Return Value The method returns the list of commands of the specified integration scenario. GetSchema() Method You use the GetSchema() method of the Screen object to get the description of the structure (schema) of a form. This method is specific for each Acumatica ERP form, and you should use the method with the ID of the needed form in the prefix of the method name. : To prevent application failures due to UI changes in Acumatica ERP, you can use the GetSchema() method of the screen-based API wrapper instead of the GetSchema() method of the Screen object. For more information on the screen-based API wrapper, see Screen-Based API Wrapper. Syntax public Content GetSchema() Return Value The method returns the schema of the form as the corresponding Content object, which is specific for each form.

236 Screen-Based SOAP API Reference 236 Example To get the schema of the Stock Items (IN202500) form, you should call the IN202500GetSchema() method of the Screen object. You will receive the result as a IN202500Content object, as the following code shows. Screen context = new Screen();... IN202500Content stockitemsschema = context.in202500getschema(); SetSchema() Method You use the SetSchema() method of the Screen object to change the description of the structure (schema) of a form to the one specified in the method. This method is useful when you need to work with the description of the form that was used in previous versions of Acumatica ERP. This method is specific for each Acumatica ERP form, and you should use the method with the ID of the needed form in the prefix of the method name. Syntax public void SetSchema(Content schema) Parameter schema: The schema of an Acumatica ERP form. Export() Method You use the proper Export() method of a Screen object to export data from Acumatica ERP. You select the needed Export() method by using in the name of the method the prefix that contains the ID of the Acumatica ERP form from which the method exports data. Syntax public string[][] Export( Command[] commands, Filter[] filters, int topcount, bool includeheaders, bool breakonerror ) Parameters commands: In this parameter, you specify the UI elements of the Acumatica ERP form whose values you need to export. In the array of commands that you pass to the commands parameter, you can also use the EveryValue service command, which makes the system export all records of the specific type. filters: In this parameter, you specify any restrictions on the data to be exported. For example, you can configure the system to export only the records that have a particular status. topcount: In this parameter, you can restrict the number of records to be exported. If this parameter is set to 0, the system exports all records that are specified by the commands and filters parameters of the Export() method.

237 Screen-Based SOAP API Reference 237 includeheaders: In this parameter, you specify whether the result of the export should include column headers. If this parameter is set to true, the result of the export includes the names of exported elements in the first row of the exported data. breakonerror: In this parameter, you specify whether the system should stop the export if an error occurs during this process. If this parameter is set to true, the system stops exporting data when the first error occurs during the export. Return Value The result of the data export is a two-dimensional string array, which represents the exported data in a table format. Thus, if an exported record contains detail lines, the values of the detail lines are translated to multiple rows of this table. The number of rows is equal to the number of detail lines of the source record. The table rows that belong to one record have the same values of the elements of the summary area specified. For example, suppose that on the Invoices (SO303000) form, an invoice has three detail lines. If you export this invoice with detail lines, the data prepared for export will include three records for this invoice one record for each detail line. These records will include identical values of the elements in the summary area of the invoice, such as the type and reference number, and different values of the detail line elements. Submit() Method You use the proper Submit() method of a Screen object to submit data to Acumatica ERP. You select the needed Submit() method by using in the name of the method the prefix that contains the ID of the Acumatica ERP form with which the method works. Syntax public Content[] Submit(Command[] commands) Parameter commands: You use this parameter to specify the data that you are going to submit. In this parameter, you pass to the web service an array of Command objects in which you can specify commands that do the following: Set the values of elements on the form by using Value commands. Click buttons on the form (for example, the Save button) by using Action commands. Get the result of data processing by using Field commands. Return value The result of processing of the data submitted by using the Submit() method is returned as a Content object specific to the form to which the data has been submitted. This object contains the values of the elements that you specified by using Field commands in the array of Command objects, which you pass to the Submit() method. The values of the elements that were not specified by using Field commands are null. If you want only to submit data to an Acumatica ERP form and do not need to obtain any values of elements after submitting, do not specify any Field commands in the array of the Command object that you pass to a Submit() method. In this case, the Submit() method does not return any value.

238 Screen-Based SOAP API Reference 238 Example 1: Submitting Data and Obtaining the Result of Processing Suppose that you want to submit a customer record to the Customers (AR303000) form and obtain as a result of processing the values of the Customer Name and Customer Class elements. You pass the list of commands, which includes Field commands for the CustomerName and CustomerClass fields, to the AR303000Submit() method, as the following code shows. In this example, the AR303000Submit() method returns a AR303000Content object that has non-null values of the CustomerName and CustomerClass fields. The values of the other elements of the returned AR303000Content object are null. AR303000Content custschema = context.ar303000getschema(); var commands = new Command[]... custschema.actions.save, custschema.customersummary.customername, custschema.generalinfofinancialsettings.customerclass ; AR303000Content customer = context.ar303000submit(commands)[0]; Example 2: Submitting Data without Obtaining the Result of Processing Suppose that you want to create a customer record on the Customers form and do not need to get the values of any element on the form after the customer record is created. You pass the list of commands, which sets the needed values and saves the changes on the form (the list of commands does not include any Field commands), to the AR303000Submit() method, as the following code shows. In this example, the AR303000Submit() method does not return any value. AR303000Content custschema = context.ar303000getschema(); var commands = new Command[] new Value..., custschema.actions.save ; context.ar303000submit(commands); Import() Method To import data to Acumatica ERP by using the web services API, you should use the proper Import() method of a Screen object. You select the needed Import() method by using in the name of the method a prefix that contains the ID of the Acumatica ERP form to which the method imports data. Syntax public ImportResults[] Import( Command[] commands, Filter[] filters, string[][] data, bool includedheaders, bool breakonerror, bool breakonincorrecttarget )

239 Screen-Based SOAP API Reference 239 Parameters commands: In this parameter, you specify the UI elements of the Acumatica ERP form to which you need to import data by using Field commands. You can click buttons on the form (for example, the Save button) by using Action commands. filters: In this parameter, you specify any restrictions on the data to be imported. For example, you can configure the system to import only the records that have the CUST prefix in the customer ID field. data: In this parameter, you specify the data that should be imported in a two-dimensional string array. Each row of the array should contain the values of the fields in the order that you specified in the commands parameter. includeheaders: In this parameter, you specify whether the imported data include column headers. If this parameter is set to true, this signals to the system that the data, which is imported, includes the names of the imported elements in the first row. breakonerror: In this parameter, you specify whether the system should stop the data import if an error occurs during this process. If this parameter is set to true, the system stops importing data when the first error occurs during the import. breakonincorrecttarget: In this parameter, you specify whether the system should stop the data import if the record does not meet the condition specified for the imported record. If this parameter is set to true, the system stops processing records and displays an error. Return Value The result of the processing of the data imported by using the Import() method is returned as a ImportResults object specific to the form to which the data has been imported. This object contains the result of the processing. Clear() Method You use the Clear() method to clear all changes on the form. The method works in the same way as the Cancel button on the toolbar of an Acumatica ERP form does. This method is specific to the particular Acumatica ERP form, and you should use the method with the ID of the needed form in the prefix of the method name. Syntax public void Clear() GetProcessStatus() Method You use the GetProcessStatus() method to monitor the status of a long-running operation (such as the release or confirmation operation). Syntax public ProcessResult GetProcessStatus()

240 Screen-Based SOAP API Reference 240 Return Value The method returns a ProcessResult object. You should use the Status property of this object to get the status of the processing operation. When the status of the operation is Completed, you can get the result of processing.

241 Appendix 241 Appendix The appendix provides some reference information relevant for this document. The additional information in this section is a useful source for readers who need some reference material that is related to system forms and tables, as well as running reports. In this section: Reports Form Toolbar Table Toolbar Glossary Reports In addition to offering a comprehensive collection of reports for each module, Acumatica ERP gives you a high degree of control over each report. A typical report form, described in Report Form, lets you adjust the report settings to meet your specific informational needs. You can specify sorting and filtering options and select the data by using reportspecific settings such as financial period, ledger, and account and configure additional processing settings for each report. The settings can be saved as a report template for later use. For details, see To Run a Report and To Create a Report Template. After you run a report, the prepared report appears on your screen. You can print the report, export the report to a file, or send the report by . This chapter describes a typical report form and the main tasks related to using reports. In This Chapter Report Form To Run a Report To Configure an Ad Hoc Filter on a Report Form To Modify an Ad Hoc Filter on a Report Form To Create a Report Template Report Form Before you run a report, you set a variety of parameters on the report form. You can select a template or manually make selections that affect the information collected. Also, you can specify appropriate settings to print or the finished report. The following screenshot shows a typical report form.

242 Appendix 242 Figure: Parameters View of Report Form 1. Report Form Toolbar 2. Parameters Toolbar 3. Template Area 4. Details Area Report Form Toolbar The following table lists the buttons of the report form toolbar when you are configuring a report. Button Cancel Clears any changes you have made and restores default settings. Run Report Initiates data collection for the report and displays the generated report. Save Template Gives you the ability to save the currently selected report as a template with all the selected settings. Remove Template Removes the previously saved template. Schedule Template Opens the Select Schedule Name dialog box, which you can use to schedule report processing. This button is available only when you select a template. This button is available only when you select a template. Select Schedule Name Dialog Box Element Schedule The schedule for report processing. Select an existing schedule, or leave the box blank and click OK to open the Automation Schedules (SM205020) form to create a new schedule for running the report. For more information on scheduling, see To Schedule Processing in the Acumatica ERP User Guide. Merge Reports A check box that indicates (if selected) that this report will be merged with the other reports selected for merging into one net report when processed.

243 Appendix 243 Element : You can check the reports that will be merged when processed on the Send Reports (SM205060) form. Merging Order The number of the report in the net report. Report Toolbar The following table lists the buttons of the toolbar after you run the configured report. Buttons Icon Parameters Navigates back to the report form to let you change the report parameters. Refresh Refreshes the information displayed in the report (if any data changes were made). Groups Adds to the report a left pane where the report structure is shown. Click a report node to highlight the pertinent data in the right pane. View PDF / View HTML Displays the report as a PDF, or displays the report in HTML format. The available button depends on the current report view; if you're viewing a PDF, for instance, you will see the View HTML button. / First Displays the first page of the report. Previous Displays the previous page. Next Displays the next page. Last Displays the last page of the report. Print Opens the browser dialog box so you can print the report. Send Opens the Activity dialog box, which you use to send the report file (in the chosen format) to the specified address. Export Enables you to export the data in the chosen format (Excel or PDF). Template Area Use the elements in this area to select an existing template and then use the template, share it with other users, or use it as your default report settings. The Template area elements, which are available for all reports, are described in the following table. Template Area Elements Element Template The template to be used for the report. If any templates were created and saved, you can select a template to use its settings for the report.

244 Appendix 244 Element Default A check box that indicates (if selected) that the selected template is marked as the default one for you. A default template cannot be shared. Shared A check box that indicates (if selected) that the selected template is shared with other users. A shared template cannot be marked as the default. Locale A locale that you select to indicate to the system that the report should be prepared with the data translated to the language associated with this locale. This box is displayed if there are multiple active locales in the system. For details, see Locales and Languages. Report Parameters Tab The Report Parameters tab includes sections where you can specify the contents of the report depending on the current report and vary in the following regards: How many elements and which elements are available on a particular report Whether elements contain default values Whether specific elements require values to be selected Whether elements may be left blank to let you display a broader range of data Additional Sort and Filters Tab The Additional Sort and Filter tab contains additional sorting and filtering conditions: Additional sorting conditions: Defines the sorting order. You can add a line, select one of the report-specific properties, and select the Descending or Ascending sort order for the column. Additional filtering conditions: Defines the report filter. You can add a line, select one of the report-specific properties, and define a condition and its value. The list of conditions include oneoperand and two-operand conditions. To create a more complicated logical expression, you can use brackets and logical operations between brackets. For more information on creating filters, see Creation of Ad Hoc and Reusable Filters in Acumatica ERP User Guide. For detailed procedures on using ad hoc filters, see To Configure an Ad Hoc Filter on a Report Form and To Modify an Ad Hoc Filter on a Report Form. Print and Settings Tab If you plan to print the report or save the report as a PDF, select the appropriate settings in the Print Settings area. Print Settings Section Element Deleted Records Selects the visibility of the data deleted from the database. Print All Pages Causes all pages of the report to be printed. Print in PDF format Displays the report in PDF format. Compress PDF file Indicates that the system will generate a compressed PDF. Embed fonts in PDF file Indicates that the system will generate the PDF with fonts embedded.

245 Appendix 245 If you plan to send the report as an , in the Settings area, specify the format in which the report will be sent, as well as the subject, the recipients of copies of the report, and the account of the recipient. Settings Section Field Format The format (HTML, PDF, or Excel) in which the report will be ed. : Merge function for reports in Excel format is not supported. If you want to merge a report with other reports and send an aggregated report by , you should select either the HTML or PDF format for the report. Account The address of the recipient. CC An additional addressee to receive a carbon copy (CC) of the . BCC The address of a person to receive a blind carbon copy (BCC) of the ; an address entered in this box will be hidden from other recipients. Subject The subject of the . Report Versions Tab If the report has multiple versions, you can select one of them. Report Versions Tab Toolbar Button Refresh Refreshes the list of report versions. Select Temporarily activates the selected report version. Report Once you click Run Report, the prepared report appears on your screen. You can print the report, export the report to a file, or send the report by . The prepared report is displayed in the report view of the report form. For more information about setting up the report parameters and the parameters view of the report form, see Report Form. Report Toolbar The following table lists report toolbar buttons. Buttons Icon Parameters Navigates back to the report form to let you change the report parameters. Refresh Refreshes the information displayed in the report (if any data changes were made). Groups Adds to the report a left pane where the report structure is shown. Click a report node to highlight the pertinent data in the right pane.

246 Appendix 246 Buttons Icon View PDF / View HTML Displays the report as a PDF, or displays the report in HTML format. The available button depends on the current report view; if you're viewing a PDF, for instance, you will see the View HTML button. / First Displays the first page of the report. Previous Displays the previous page. Next Displays the next page. Last Displays the last page of the report. Print Opens the browser dialog box so you can print the report. Send Opens the Activity dialog box, which you use to send the report file (in the chosen format) to the specified address. Export Enables you to export the data in the chosen format (Excel or PDF). Form Toolbar The form toolbar, available on most forms, is located near the top of the form, under the form title bar (see the screenshot below). The form toolbar may include standard and form-specific buttons. Figure: Form toolbar You use the standard buttons on the form toolbar to navigate through objects and entities that were created by using the current form, insert or delete an object or entity, use the clipboard, save the data you have entered, or cancel your work on the form. In addition to standard buttons, a form toolbar on a particular form may include form-specific buttons. These buttons usually provide navigation to other forms, take specific actions, and perform modifications or processing related to the functionality of the form.

247 Appendix 247 Standard Form Toolbar Buttons The following table lists the standard buttons of the form toolbar. A form toolbar may include some or all of these buttons. Standard Form Toolbar Buttons Button Icon Save Saves the changes made to the object or entity. Cancel Depending on the context, does one of the following: Discards any unsaved changes you have made to objects or entities and retrieves the last saved version. Clears all changes and restores the default settings. Add New Record Clears any values you've specified on the form, restores any default values, and initiates the creation of a new object or entity. Clipboard Provides options to do the following: Copy: Copy the selected object or entity to the clipboard. Paste: Paste an object, entity, or template from the clipboard. Save as Template: Create a template based on the selected object or entity. Import from XML: Import an object, entity, or template from an.xml file. Export to XML: Export the selected object or entity to an.xml file. For more information on templates and copy-and-paste operations in Acumatica ERP, see Using Forms. For more information on importing and exporting.xml files, see System-Wide Actions in Acumatica ERP in the Acumatica ERP User Guide. Delete Deletes the currently selected object or entity, clears any values you've specified on the form, and restores default values. : You can delete a document that is not linked with another document. Go to First Record Displays the first object or entity (in the list of objects or entities of the specific type) and its details. Go to Previous Record Displays the previous object or entity and its details. Go to Next Record Displays the next object or entity and its details. Go to Last Record Displays the last object or entity (in the list of objects or entities of the specific type) and its details. Schedules Gives you the ability to schedule the processing. For more information, see To Schedule Processing topic in the Acumatica ERP User Guide.

248 Appendix 248 Inquiry Form Toolbar Buttons Acumatica ERP inquiry forms present the data in a tabular format. These forms can be designed by a user with the appropriate access rights by using the Generic Inquiry tool (for details, see Managing Generic Inquiries in the Acumatica ERP User Guide), or can be initially configured in your system. A toolbar of an inquiry form contains both the standard form toolbar buttons (described in the table above) and additional buttons described below. Button Icon Fit to Screen Expands the form to fit on the screen and adjusts the column widths proportionally. Export to Excel Exports the data to an Excel file. For more information, see Integration with Excel in the Acumatica ERP User Guide. Filter Settings Opens the Filter Settings dialog box, which you can use to define a new filter. After the filter has been created and saved, the corresponding tab appears on the table. For more information about filtering, see Filters. Table Toolbar Each table on an Acumatica ERP form, tab, or dialog box has a table toolbar, which contains the search box and buttons you can use to work with the details or objects of the table. The table toolbar, shown in the following screenshot, can include the following sections: Action section: Contains buttons that are specific to the table, standard buttons that most table toolbars have, and the search box. Footer section: Displays navigation buttons if there are too many details or objects (that is, table rows) to fit on one page. Figure: Table toolbar sections 1. Action section 2. Footer section Action Section of Table Toolbar The action section, commonly located at the top of a table, can contain standard and table-specific buttons. If a table toolbar includes table-specific buttons, they are described in the form reference help topic.