このページでは、CData Cloud でのAcumatica への接続の確立 のガイド、利用可能なリソースに関する情報、および使用可能な接続プロパティのリファレンスについて説明します。

Acumatica への接続

接続の確立 は、CData Cloud にデータベースを作成するためのAcumatica への認証方法と必要な接続プロパティの設定方法について示します。

CData Cloud サービスからデータにアクセス

利用可能な標準サービスを経由してAcumatica からデータにアクセスする方法と、CData Cloud の管理については、CData Cloud ドキュメント で詳しく説明します。

Database タブで対応するアイコンを選択して、Acumatica に接続します。必須プロパティはSettings にリストされています。Advanced タブには、通常は必要ない接続プロパティが表示されます。

Acumatica への接続

Acumatica データソースに接続するには、次の接続プロパティを指定する必要があります。

• Url：（必須）Acumatica ERP インスタンスのベースURL。例：https://domain.acumatica.com/。
• Schema：（オプション）異なるデータを含む2つのスキーマがあります。デフォルトはREST で、Acumatica REST 契約ベースのAPI を使用し、OData スキーマはAcumatica OData API を使用します。OData スキーマはAcumatica Generic Inquiries へのクエリに使用されます。
• Company：（一部必須）会社名またはテナント名に設定。Schema がOData に設定されている場合は必須です。
• EndpointVersion：（オプション）Web Services エンドポイントのバージョン。例：17.200.001。これはREST スキーマにのみ適用されます。
• EndpointName：（オプション）Web Services エンドポイントの名前。例：Default。これはREST スキーマにのみ適用されます。

Acumatica インスタンスのEndpointVersion およびEndpointName を調べるには、Web ブラウザでAcumatica にログインし、Web Service Endpoints ページに移動します。必要に応じて、Web ブラウザのURL を編集し、ScreenId=00000000（ホームページ）を ScreenId=SM207060 に置き換えてこのページに移動してください。ホームページにリダイレクトされる場合は、ユーザーがWeb サービスにアクセスするために必要な権限を持っていないことを意味します。Endpoints プロパティで［Endpoint Name］および［Endpoint Version］を取得します。

Generic Inquiries の公開

Cloud は、Generic inquiries データをテーブルやビューとして検出することができます。ただし、それらを公開するには、まずWeb Services Endpoint を拡張する必要があります。

Generic inquiries を公開するプロセスは、Schema 接続プロパティで指定されたスキーマによって異なります。

REST スキーマ

Generic Inquiries は、デフォルトではREST 経由で公開されません。公開するには：

1. Acumatica UI でIntegration > Show All > Web Service Endpoints に移動します。
2. 最新のエンドポイントバージョンを使用している"Default" エンドポイントをクリックします。
3. 利用可能なアクションボタン（ページ上部のエンドポイント名の下のボタンバー）から、EXTEND ENDPOINT をクリックします。
   • このアクションは、"..." ボタンをクリックして表示される全アクションリストから見つける必要があるかもしれません。
4. Endpoint Name を使用して拡張エンドポイントに名前を付け、Endpoint Version でエンドポイントのバージョンを指定し、OK をクリックします。
5. 新しい拡張エンドポイントのページで、+ Insert ボタン（ENDPOINT ツリー構造の上）をクリックします。
6. 以下のように、新しいカスタムオブジェクトのエンティティ定義を作成します。
   • Object Name フィールドにオブジェクトの名前を付けます。
   • Object Type フィールドはデフォルトのTop-Level のままにしておきます。
   • Screen Name フィールドで、虫眼鏡アイコンをクリックして、Generic Inquiries に関連するスクリーンを検索します。Generic Inquiries のSite Map Title フィールドに一致する画面を選択します。
     • 自動入力されたScreen ID フィールドの値が、Generic Inquiries の値と一致していることを確認します。
   • OK をクリックします。
7. 以下のように、カスタムオブジェクトの下に新しい"Results" エンティティを作成します。
   • ENDPOINT ツリー構造で新しく作成したオブジェクトを選択し、+ Insert ボタンをクリックします。
   • Field Name を"Result" に設定します。
   • Object Name でこのオブジェクトの名前を指定します。
   • Object Type をDetail に設定します。
   • OK をクリックします。
8. ENDPOINT ツリー構造で、カスタムオブジェクトのノードを展開し、作成したばかりの新しいResults オブジェクトを選択して FIELDS > POPULATE をクリックします。
9. Populate Field ウィンドウのObject フィールドで、"Result"（先ほど作成したオブジェクト）を選択します。
10. Generic Inquiry から公開する各フィールドのチェックボックスを選択し、OK をクリックします。
11. テーブルリストで公開されているGeneric Inquiry を表示するには、EndpointName を拡張エンドポイントの名前に設定し、InquiryTables を上記ステップ6のトップレベルカスタムオブジェクトの名前に設定します。

OData スキーマ

Generic Inquiries は、デフォルトではOData 経由で公開されません。公開するには、Acumatica UI でCustomization > Profiles > Generic Inquiry に移動し、Expose via OData チェックボックスを選択します。

Acumatica への認証

Acumatica データソースへの接続に使用できる認証方法は2つあります。Basic およびOAuth です。

ユーザー資格情報

AuthScheme をBasic に設定し、User とPassword をログイン資格情報に設定します。

OAuth

Web アプリケーション

Web アプリケーション経由で接続する場合は、Acumatica にカスタムOAuth アプリケーションを作成および登録する必要があります。カスタムアプリケーションについて詳しくは、カスタムOAuth アプリの作成 を参照してください。それからCloud を使用してOAuth トークンの値を取得および管理します。

OAuth アクセストークンの取得

次の接続プロパティを設定し、OAuthAccessToken を取得します。

• OAuthClientId：アプリケーション設定のクライアントId に設定。
• OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。

続いてストアドプロシージャを呼び出し、OAuth 交換を完了します。

1. GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。CallbackURL インプットをアプリケーション設定で指定したコールバックURL に設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。

   ストアドプロシージャがOAuth エンドポイントのURL を返します。

2. URL を開き、ログインして、アプリケーションを認可します。コールバックURL にリダイレクトされます。
3. GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、コールバックURL のクエリ文字列の"code" パラメータに設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。

アクセストークンとリフレッシュトークンを取得すると、データに接続し、OAuth アクセストークンを自動または手動でリフレッシュすることができるようになります。

OAuth アクセストークンの自動リフレッシュ

ドライバーがOAuth アクセストークンを自動的にリフレッシュするようにするには、最初のデータ接続で次のように設定します。

• InitiateOAuth：REFRESH に設定。
• OAuthClientId：アプリケーション設定のクライアントId に設定。
• OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
• OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークンに設定。
• OAuthRefreshToken：GetOAuthAccessToken によって返されたリフレッシュトークンに設定。
• OAuthSettingsLocation：Cloud がOAuth トークン値を保存する場所に設定。これは接続間で維持されます。

OAuth アクセストークンの手動リフレッシュ

データ接続時に手動でOAuth アクセストークンをリフレッシュするために必要な値は、OAuth リフレッシュトークンのみです。

GetOAuthAccessToken によって返されたExpiresIn パラメータ値が経過した後に、RefreshOAuthAccessToken ストアドプロシージャを使用し、手動でOAuthAccessToken をリフレッシュします。次の接続プロパティを設定します。

• OAuthClientId：アプリケーション設定のクライアントId に設定。
• OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。

次に、RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを指定します。新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定し、新しい接続をオープンします。

最後に、OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。

Acumatica has introduced an optimization in version 3 of the Contract Based API. When multiple records are retrieved from the Acumatica ERP through an endpoint, 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 returns an error, specifying the entities or fields that caused the failure of the optimized request. Mostly the Navigation Views break the optimization because Acumatica is trying to get data from the linked tables, because of this the SELECT * queries from Navigation Views without specifying the key of the parent table are not possible. Our drivers tries to remove the columns that break the optimization from the SELECT * queries.

Some of the Views that break the optimization when selected without specifying the keyfields are JournalVoucher_Details. In order to qyery the JournalVoucher_Details the ParentBatchNbr should be specified.

 SELECT * FROM JournalVoucher_Details where ParentBatchNbr = '0001'

The view can be queried by geting the parent key field in this case ParentBatchNbr from the parent table JournalVoucher.

 SELECT * FROM JournalVoucher_Details where ParentBatchNbr IN (SELECT BatchNbr FROM JournalVoucher)

More information on how to bypass the Acumatica optimization can be found here: 制限.

SSL 設定のカスタマイズ

デフォルトでは、Cloud はサーバーとのTLS のネゴシエーションを試みます。サーバー証明書は、デフォルトのシステム信頼済み証明書ストアで検証されます。SSLServerCert 接続プロパティを使用して、証明書の検証方法をオーバーライドできます。

別の証明書を指定するには、SSLServerCert 接続プロパティを参照してください。

Firewall またはProxy 経由の接続

HTTP プロキシ

HTTP プロキシへの認証には、以下のように設定します。

• ProxyServer：HTTP トラフィックをルートするプロキシサーバーのホストネームもしくはIP アドレス。
• ProxyPort：プロキシサーバーが起動しているTCP ポート。
• ProxyAuthScheme：プロキシサーバーに対して認証する際にCloud が使用する認証方法。
• ProxyUser：プロキシサーバーに登録されているユーザーアカウントのユーザー名。
• ProxyPassword：ProxyUser に紐付けられたパスワード。

その他のプロキシ

次のプロパティを設定します。

• プロキシベースのファイヤーウォールを使用するには、FirewallType、FirewallServer、およびFirewallPort を設定します。
• 接続をトンネルするには、FirewallType をTUNNEL に設定します。
• 認証するには、FirewallUser とFirewallPassword を設定します。
• SOCKS プロキシへの認証には、さらにFirewallType をSOCKS5 に設定します。

Cloud はAcumatica API をリレーショナルテーブルとしてモデル化します。

接続すると、Cloud はAcumatica に接続し、テーブルのリストおよびテーブルとビューのメタデータを取得します。

テーブル定義は動的に取得されるため、リモートデータへのあらゆる変更はクエリに即時に反映されます。

Generic Inquiries

Cloud は、Web Services Endpoint がGeneric inquiries データを公開するように拡張されている場合、テーブルやビューとしてGeneric inquiries データを検出することができます。

Web Services Endpoint を拡張し、Generic inquiries を公開する方法については、 を参照してください。

Generic inquiries は、サーバーサイドフィルタリングをサポートするように設定することもできます。この手順についてはGeneric Inquiries のサーバーサイドフィルタリング を参照してください。

制限

制限 では、Acumatica REST API の制限と、それらがCloud の操作にどのように影響するかを説明します。

テーブル

テーブル は、Acumatica のデフォルトテーブル定義を表示します。実際の表示は、カスタマイズにより異なる場合があります。変更を取得するには、Url 接続プロパティを最新バージョンに設定します。

CData Cloud はテーブルおよびカラムのメタデータを動的に読み込みます。そのため、カスタマイズ内容と今後の標準 Acumatica エンティティに追加される新機能の両方が含まれます。

ビュー

ビュー は、子テーブルなどのAcumatica エンティティを表す読み取り専用テーブルです。

ストアドプロシージャ

ストアドプロシージャ は、Acumatica のファンクションライクなインターフェースです。これらは、テーブルと直接対話する標準的な操作には適さない追加のタスクを 実行するために使用できます。

Server-side Filtering for Generic Inquiries

By default, queries that filter on general inquiry columns will not be processed server-side. In order to enable server-side filtering for these columns, you must first explicitly set them as filter columns in the Acumatica UI.

To expose a general inquiry column as a filter:

1. Navigate in the Acumatica UI to the sidebar and select More Items > Customization > Generic Inquiry. The configuration page for your generic inquiry appears.
2. Click the magnifying glass icon in the Inquiry Title field. Select the generic inquiry that you have exposed as a table.
3. Click PARAMETERS. Perform the following steps for each column for which you want to enable server-side filtering.
   1. Click + (Add Row).
   2. Ensure the checkbox in the Active column is checked.
   3. Provide a name for the parameter in the Name column.
   4. Click the dropdown in the Schema Field column. Choose the general inquiry column for which you want to enable server-side filtering.
4. Click CONDITIONS. Perform the following steps for each column for which you want to enable server-side filtering.
   1. Click + (Add Row).
   2. Ensure the checkbox in the Active column is checked.
   3. Leave the Condition column set to Equals.
   4. Click the dropdown in the Data Field column. Choose the general inquiry column for which you want to enable server-side filtering. This should match the column chosen in the Schema Field column on the PARAMETERS tab.
   5. Click the dropdown in the Value 1 column. Choose the parameter you created earlier for this column.
5. Click the Save icon to submit these changes.
6. Navigate in the sidebar to Integration > Web Service Endpoints (expand the Integration page with Show More to find this, if needed).
7. Select the endpoint in which you have exposed the general inquiry as an object.
8. Expand the node for the general inquiry object's endpoint in the ENDPOINT tree structure, then select its child entity (Result), which you created earlier.
9. Click the FIELDS tab. Perform the following steps for each column for which you want to enable server-side filtering.
   1. Select the Mapped Object field associated with the column, then click its magnifying glass icon.
   2. Double-click Filter to set "Filter" as the mapped object.
10. Click the Save icon to submit these changes. Server-side filtering for these columns is now enabled.

Custom Fields

By default, the table and view schemas describe the column behavior of system fields as well as custom fields. You can set the IncludeCustomFields property to false if you want to work only with system fields. On a SELECT * FROM EntityName query, the custom fields will not be returned even though IncludeCustomFields is set to true. The Custom fields will be returned only when they are specified on projections. For example:

SELECT Custom_FieldA, Custom_FieldB, Custom_FieldC FROM EntityName

The requirement to explicitly select the custom fields is due to a limitation with the Acumatica API. It will not return results when too much overall data is selected per record. It is not possible to dynamically calculate at what point Acumatica will cut off results. You should only select the columns you need and not everything to keep things working smoothly.

In case a group of custom fields are important to your use case and the Acumatica API cannot return them in a single response, it is recommended to setup an extended endpoint and include the custom fields in it. After this change, you should be able to retrieve them as non-custom fields from the extended endpoint.

An alternative to extending an existing endpoint is to split the main query into two or more subqueries and distribute the selected custom fields between them. Lastly, you can join the subqueries on the primary key column as in the example below.

SELECT Customer_1.CustomerID, Customer_1.Custom_Timezone, Customer_1.Custom_ProductGroup, Customer_2.Custom_ContactCategory, Customer_2.Custom_DiscountGroup 
FROM Customer Customer_1 JOIN Customer Customer_2 
ON Customer_1.CustomerID = Customer_2.CustomerID

Linked and Detail Entities

The Linked and Detail entities to main entity are exposed in the main entity table as aggregate columns starting with the 'Linked' prefix. They are also exposed as separate views using the naming format 'MainEntityName_LinkedEntityName'. For example, the Customer table exposes the linked entity 'Contacts' as the aggregate field 'LinkedContacts'. The linked entity Contacts is also exposed as the separate view Customer_Contacts.

Due to Acumatica REST API limitations, the Linked and Detail entities cannot be retrieved when requesting multiple main entity records. For this reason, when querying the main entity, without specifying the primary key in the WHERE clause conditions, the linked aggregate fields are returned as null. For example, in order to retrieve the aggregate values of the linked entity Contacts in the Customer table, you can execute one of the queries below.

SELECT CustomerID, LinkedContacts FROM Customer WHERE customerId = '100009'

You can also make use of the IN operator and subqueries as below, in order to retrieve the Linked and Detail entities for multiple parent records.

SELECT CustomerID, LinkedContacts FROM Customer WHERE CustomerId IN (SELECT CustomerId FROM Customer)

Additionally, to query the exposed Linked and Detail entities, specifying the parent entity primary key in the WHERE clause conditions, is required. For example:

SELECT * from Customer_Contacts where ParentCustomerID = '100009'

Excluded Columns

Acumatica has introduced an optimization in version 3 of the Contract Based API. When multiple records are retrieved from the Acumatica ERP through an endpoint, 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 returns an error, specifying the entities or fields that caused the failure of the optimized request. To prevent the error from occurring, we need to do one of the following:

• Get all the records one by one by specifying the key fields.
• Get only the fields that don't break the optimization.

Create the schema by calling the CreateSchema if you have not already done so.

Add the additional parameters in the .rsd schema files below.

• key="true"
• other:exclude="true"

These two parameters are needed so the new entities don't return an error in SELECT * FROM Table queries. The example below is a rsd snippet that shows how these parameters are used.

In the example Contact.rsd, Duplicate and AddressValidated are fields that break the Acumatica optimization so they have the additional parameter other:exclude="true". When a SELECT * FROM Contact query is done, the driver will get all fields except those with the other:exclude="true" parameter. However, the omitted fields will still appear on your result set as null. The data provider will request the excluded fields from the endpoint only if they are explicitly stated in the SELECT clause or if the primary key column/s are specified.

In the example Contact.rsd, ContactID is the primary key so the additional parameter key="true" is added. When a SELECT * FROM Contact WHERE ContactID='contactid' is done, the driver will get all fields from the API including the Duplicate and AddressValidated.

<rsb:script xmlns:rsb="http://www.rssbus.com/ns/rsbscript/2">
  <rsb:info title="Contact" description="Contact is an auto-generated table." other:tablehref="https://try.acumatica.com/ISV/entity/Default/17.200.001/Contact" other:tablekind="EntitySet"/>
    <attr name="LanguageOrLocale" xs:type="string" columnsize="2000" readonly="false" description="null" other:entityname="Contact" other:schemanamespace="Contact" other:internalcolumnname="LanguageOrLocale"/>
    <attr name="DuplicateFound" xs:type="bool" readonly="false" description="null" other:internalcolumnname="DuplicateFound"/>
    <attr name="JobTitle" xs:type="string" columnsize="2000" readonly="false" description="null" other:internalcolumnname="JobTitle"/>
    <attr name="ContactID" xs:type="int" key="true" readonly="false" description="null" other:queue="0" other:internalkey="ContactID" other:internalcolumnname="ContactID"/>
    .......
    <attr name="Duplicate" xs:type="string" columnsize="2000" readonly="false" description="null" other:exclude="true" other:internalcolumnname="Duplicate"/>
    .......
    <attr name="AddressValidated" xs:type="bool" readonly="false" description="null" other:exclude="true" other:internalcolumnname="AddressValidated"/>
    .......
      <rsb:set attr="other:tablekind" value="EntitySet" />
  <rsb:set attr="tablename" value="Contact" />
  <rsb:set attr="description" value="Contact is an auto-generated table." />
  <rsb:set attr="entity" value="Contact" />
  <rsb:set attr="other:tablehref" value="https://try.acumatica.com/ISV/entity/Default/17.200.001/Contact" />
  <rsb:set attr="supportgetdeleted" value="true" />

  <rsb:script method="GET">
    <rsb:call op="acumaticaadoExecuteSearch">
      <rsb:push/>
    </rsb:call>
  </rsb:script>

  <rsb:script method="POST">
    <rsb:call op="acumaticaadoExecuteInsert">
      <rsb:push/>
    </rsb:call>
  </rsb:script>

  <rsb:script method="MERGE">
    <rsb:call op="acumaticaadoExecuteUpdate">
      <rsb:push/>
    </rsb:call>
  </rsb:script>

  <rsb:script method="DELETE">
    <rsb:call op="acumaticaadoExecuteDelete">
      <rsb:push/>
    </rsb:call>
  </rsb:script>
</rsb:script>
    

Creating User Defined Views

A simple and effective way to automate the process of getting all records one by one by specifying the key fields are the User Defined Views. User Defined Views are predefined queries stored in a local JSON file, which can be queried from the driver just as the existing views.

As stated in the above section, the excluded fields will be retrieved if the primary key is specified. You can use the driver's enhanced SQL support to automatically do this for each record by appending an IN subquery to your main query. From the subquery, you should be selecting only the primary key column as in the example below.

SELECT * FROM Contact WHERE ContactId IN (SELECT ContactId FROM Contact)

You can then add this query under the "query" field of a local created JSON file (ex. C:\Users\user\Desktop\CustomViews.json).

{
    "AllContacts": {
        "query": "SELECT * FROM Contact WHERE ContactId IN (SELECT ContactId FROM Contact)"
    },
    "AllCustomers": {
        "query": "SELECT * FROM Customer WHERE CustomerId IN (SELECT CustomerId FROM Customer)"
    }
}

Lastly, you can directly query the defined views (AllContacts and AllCustomers) after stating the Custom Views file location in the UserDefinedViews property under the Other connection parameter.

Other='UserDefinedViews=C:\Users\User\Desktop\CustomViews.json;'

You can also execute a query to the sys_tables view to verify if the custom views are added. You should be able to find them under the UserViews schema.

SELECT * FROM sys_tables where TableType='view'

Cloud はAcumatica のデータを、標準のSQL ステートメントを使用してクエリできるリレーショナルデータベースのテーブルのリストとしてモデル化します。

CData Cloud - Acumatica テーブル

Account is an auto-generated table.

Columns

AccountByPeriodInquiry is an auto-generated table.

Columns

AccountBySubaccountInquiry is an auto-generated table.

Columns

AccountDetailsInquiry is an auto-generated table.

Columns

AccountLocation is an auto-generated table.

Columns

AccountSummaryInquiry is an auto-generated table.

Columns

Adjustment is an auto-generated table.

Columns

AttributeDefinition is an auto-generated table.

Columns

Bill is an auto-generated table.

Columns

BusinessAccount is an auto-generated table.

Columns

Carrier is an auto-generated table.

Columns

Case is an auto-generated table.

Columns

CashSale is an auto-generated table.

Columns

Check is an auto-generated table.

Columns

Contact is an auto-generated table.

Columns

Currency is an auto-generated table.

Columns

Customer is an auto-generated table.

Columns

CustomerClass is an auto-generated table.

Columns

CustomerLocation is an auto-generated table.

Columns

CustomerPaymentMethod is an auto-generated table.

Columns

CustomerPriceClass is an auto-generated table.

Columns

Discount is an auto-generated table.

Columns

DiscountCode is an auto-generated table.

Columns

Email is an auto-generated table.

Columns

Employee is an auto-generated table.

Columns

Event is an auto-generated table.

Columns