Skip to content

Commit c8d6fae

Browse files
k-s-popovak-s-popova
committed
AC-138025: files for two workshops added
1 parent 65471b0 commit c8d6fae

42 files changed

Lines changed: 160760 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎IntegrationDevelopment/Acumatica Integration Fundamentals OData & REST API/Activity5_1/DACODataMetadata.txt‎

Lines changed: 156031 additions & 0 deletions
Large diffs are not rendered by default.

‎IntegrationDevelopment/Acumatica Integration Fundamentals OData & REST API/Activity5_1/DAC_OData_DataRetrieval.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# DAC-Based OData: Data Retrieval {#_27f3a57a-0def-48ad-ba80-3ab664a98fde .concept}
2+
3+
In this topic, you can find details about how to retrieve data by using the DAC-based OData interface. To retrieve the data, you append the DAC name and various parameters to the base URL of the DAC-based OData interface. For details about the base URL, see [The URL for the DAC-Based OData Interface](RPT_DAC_OData_GeneralInfo.md#_17597c9b-c7c4-4659-ae6a-f15108e59eee).
4+
5+
## Retrieving All Records of a DAC { .section}
6+
7+
You can use the following request to get all records of a DAC.
8+
9+
```
10+
GET https://<Acumatica ERP instance URL>/t/<TenantName>/api/odata/dac/<DACName>
11+
```
12+
13+
In this URL, the DAC is specified by its fully qualified name, by its display name, or by its short name \(which does not include the namespace\). For example, the use of either of the following URLs receives the same contents of the SOOrder DAC:
14+
15+
- *https://sweetlife.com/erp/t/U100/api/odata/dac/SOOrder*
16+
- *https://sweetlife.com/erp/t/U100/api/odata/dac/PX\_Objects\_SO\_SOOrder*
17+
18+
**Tip:** Password fields are retrieved encrypted.
19+
20+
## Retrieving a Record by Its Key Fields { .section}
21+
22+
You can retrieve a record with certain values of key fields by specifying these fields and their values in the URL.
23+
24+
The following sample request retrieves the sales order for which the `OrderType` field is set to *SO* and the `OrderNbr` field is set to *000058*.
25+
26+
```
27+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/SOOrder(OrderType='SO',OrderNbr='000058')
28+
```
29+
30+
## Specifying a Filter { .section}
31+
32+
You can obtain the records that meet a particular filter’s criteria by specifying this filter in the *$filter* parameter of the URL. You use [OData URL conventions](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html) to specify the conditions in the *$filter* parameter.
33+
34+
The following sample URL retrieves the sales orders whose `OrderType` field value is *IN*.
35+
36+
```
37+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/SOOrder?
38+
$filter=(OrderType eq 'IN')
39+
```
40+
41+
## Retrieving Related Data { .section}
42+
43+
You can obtain records along with related data, such as detail records or other linked records. For example, consider a sales order record: Each sales order record may have one or more detail records, which contain data about the inventory items included in the sales order. A sales order record also includes the identifier of the customer, which can be used to retrieve the linked customer record. Therefore, along with a sales order record, you can retrieve detail records and the linked customer record.
44+
45+
You can obtain the records, along with their detail records, in a single query by using the *$expand* parameter and the needed navigation property.
46+
47+
The following sample request retrieves sales orders along with their detail information.
48+
49+
```
50+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/SOOrder?
51+
$filter=(OrderType eq 'IN')&
52+
$expand=SOLineCollection
53+
```
54+
55+
The following sample request retrieves sales orders along with data of the customer record related to each of those sales orders.
56+
57+
```
58+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/SOOrder?
59+
$filter=(OrderType eq 'IN')&
60+
$expand=BAccountByCustomerID
61+
```
62+
63+
To retrieve records with multiple kinds of detail lines from Acumatica ERP by using DAC-based OData, in the *$expand* parameter, you use multiple navigation properties separated with comma.
64+
65+
## Specifying Particular Fields in a Response { .section}
66+
67+
In a request, you can specify the DAC fields that you want the response to contain. You do this by specifying the desired fields in the *$select* parameter.
68+
69+
The following sample request retrieves customers and provides the `AcctCD`, `AcctName`, and `CustomerClassID` fields in the response.
70+
71+
```
72+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/PX_Objects_AR_Customer?
73+
$select=AcctCD,AcctName,CustomerClassID
74+
```
75+
76+
To list the fields of the detail records, you specify the following in the request:
77+
78+
- In the *$expand* parameter, the navigation property for the detail DAC
79+
- After the property, in parentheses, the DAC fields as the values of the *$select* parameter
80+
81+
**Tip:** By default, the maximum depth of expansion of the detail DACs in the *$expand* parameter is 3. You can change this value by specifying the value of the maxExpansionDepth attribute of the odata tag, which is available inside the px.core tag in the `Web.config` file of your Acumatica ERP instance.
82+
83+
The following sample URL retrieves customers along with their default addresses.
84+
85+
```
86+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/PX_Objects_AR_Customer?
87+
$select=AcctCD,AcctName,CustomerClassID&
88+
$expand=AddressByDefAddressID(
89+
$select=AddressLine1,AddressLine2,City,State,PostalCode)
90+
```
91+
92+
The response includes the customers' `AcctCD`, `AcctName`, and `CustomerClassID` fields and the following fields of the customers’ addresses: `AddressLine1`, `AddressLine2`, `City`, `State`, and `PostalCode`.
93+
94+
## Retrieving Records in Batches { .section}
95+
96+
To retrieve records in batches from Acumatica ERP by using DAC-based OData, you need to use the *$top* and *$skip* parameters of the request. We recommend that you also use the *$orderby* parameter to specify the order of records.
97+
98+
**Attention:** If the *$orderby* parameter is not specified for retrieving batches of records, the system sorts the records by the key fields in ascending order.
99+
100+
The following example retrieves a batch of warehouse detail records. It indicates that the records should be ordered by inventory ID in ascending order. The system will retrieve the top 500 records, excluding the first 50.
101+
102+
```
103+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/PX_Objects_IN_INSiteStatus?
104+
$skip=50&
105+
$top=500&
106+
$orderby=InventoryID
107+
```
108+
109+
## Retrieving Multilingual Fields { .section}
110+
111+
If a record has multilingual fields, you can obtain the values of these fields in any available language. You can do this in either of the following ways:
112+
113+
- By using the `Accept-Language` HTTP header and specifying the desired locale as its value
114+
- By using the `locale` URL parameter and specifying the desired locale as its value
115+
116+
If neither the `Accept-Language` HTTP header nor the `locale` URL parameter is used, the values of multilingual fields are returned in the default language \(see [Setting Up Languages](SM__CON_Locales_and_Languages.md#section_vkn_2lm_hw)\). If both the `Accept-Language` HTTP header and the `locale` URL parameter are used, the locale specified in the `locale` URL parameter is taken into account.
117+
118+
The following sample URL retrieves the *AACOMPUT01* inventory item with the French values of the multilingual fields.
119+
120+
```
121+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/PX_Objects_IN_InventoryItem?
122+
locale=fr-FR&
123+
$filter=InventoryCD eq 'AACOMPUT01'
124+
```
125+
126+
The use of the following request has the same effect.
127+
128+
```
129+
GET /AcumaticaERP/t/U100/api/odata/dac/PX_Objects_IN_InventoryItem?
130+
$filter=InventoryCD eq 'AACOMPUT01' HTTP/1.1
131+
Host: localhost
132+
Accept-Language: fr-FR
133+
```
134+
135+
## Retrieving Archived Records { .section}
136+
137+
You can retrieve archived records along with non-archived ones. To make archived records visible for requests, you use the `PX-ApiArchive` HTTP header with the *SHOW* value.
138+
139+
The following sample request retrieves the shipments \(including archived ones\) that were created before December 31, 2022.
140+
141+
```
142+
GET /AcumaticaERP/t/U100/api/odata/dac/PX_Objects_SO_SOShipment?
143+
$filter=ShipDate gt 2022-12-31T00:00:00%2b03:00
144+
&$select=ShipmentNbr,ShipDate HTTP/1.1
145+
Host: localhost
146+
PX-ApiArchive: SHOW
147+
```
148+
149+
## Retrieving Removed Records { .section}
150+
151+
The removed records are stored in the database if the corresponding database table has the DeletedDatabaseRecord column. For details about this mechanism, see [Preservation of Deleted Records \(DeletedDatabaseRecord\)](../StudioDeveloperGuide/DA__con_Preservation_of_Deleted_Records.md). By default, the removed records are not returned if you request data through the DAC-based OData interface.
152+
153+
To retrieve the removed records, you need to specify the `PX-ApiDeleted` HTTP header with the *SHOW* value in the request.
154+
155+
For example, the following request retrieves both removed customer records and customer records that have not been removed.
156+
157+
```
158+
GET /AcumaticaERP/t/U100/api/OData/DAC/Customer?
159+
$select=BAccountID,DeletedDatabaseRecord HTTP/1.1
160+
Host: localhost
161+
PX-ApiDeleted: SHOW
162+
```
163+
164+
## Tracking Removed Records for Synchronization {#_264ee4ec-929f-4356-b06d-f1485147899a .section}
165+
166+
The optimal way to synchronize data between Acumatica ERP and an external system is to synchronize only the data that has been modified since the previous synchronization. To track the modification date, you can use the values in the LastModifiedDateTime field of a record. However, this type of synchronization does not take into account the records that have been removed since the last synchronization. To synchronize the removed records, you can use the system mechanism that tracks the removal of records of particular data access classes \(DACs\).
167+
168+
You can use this mechanism as follows:
169+
170+
1. On the [Tables to Track Deleted Records](SM_20_70_10.md) \(SM207010\) form, you add the DACs for which the system should track the removed records. If you do not list a DAC, the system does not track its removed records.
171+
172+
**Tip:** If a record of a DAC listed on the form is removed, the system saves the NoteID of the record and the date and time of its removal. The system does not keep the record itself.
173+
174+
2. To obtain the list of removed records of a particular DAC, you use the px.GetDeletedRecords\(\) function in the request URL.
175+
176+
You can also filter the records by the date of removal by using the DeleteDate field in the *$filter* parameter.
177+
178+
**Attention:** A user can obtain the list of removed records of a DAC by using an OData request if the user has access to this DAC through DAC-based OData.
179+
180+
3. Optional: To include this list of DACs in a customization project, you use the [Tables to Track Deleted Records](AU_20_60_05.md) page of the Customization Project Editor. You need to list the DACs on the [Tables to Track Deleted Records](SM_20_70_10.md) \(SM207010\) form first in order they are available for selection on the page.
181+
182+
For example, suppose that you need to retrieve the list of sales orders that have been removed since November 1, 2024, from the *U100* tenant of the local Acumatica ERP instance. Further suppose that the SOOrder DAC has been added to the list on the [Tables to Track Deleted Records](SM_20_70_10.md) \(SM207010\) form. You can execute the following request to obtain the list of removed records.
183+
184+
```
185+
GET https://localhost/AcumaticaERP/t/U100/api/odata/dac/SOOrder/px.GetDeletedRecords()?$filter=DeleteDate ge 2024-11-01T00:00:00Z
186+
```
187+
188+
## Retrieving Custom and User-Defined Fields { .section}
189+
190+
In a customization project, you can add custom fields to Acumatica ERP forms. You can also add user-defined fields to Acumatica ERP forms and include them in a customization project. \(For details about user-defined fields, see [User-Defined Fields](CS__con_User_Defined_Fields.md#).\)
191+
192+
To retrieve custom and user-defined fields through the DAC-based OData interface, you do not need to perform special actions. You address custom and user-defined fields by their names.
193+

0 commit comments

Comments
 (0)