Acumatica v2-Verbindungsdetails

Einführung

Connector-Version

Diese Dokumentation basiert auf Version 23.0.8858 des Connectors.

Erste Schritte

Acumatica Versionsunterstützung

Der Connector unterstützt Acumatica 2017 R2 und höher.

Herstellen einer Verbindung

Mit Acumatica verbinden

Um eine Verbindung mit der Acumatica Datenquelle herzustellen, müssen Sie die folgenden Verbindungseigenschaften angeben.

• URL: (Erforderlich) Die Basis URL für die Acumatica ERP-Instanz. Beispiel: https://domain.acumatica.com/entity/.
• Schema: (Optional) Es gibt zwei Schemata, die unterschiedliche Daten enthalten. Das Standardschema ist REST, das die Acumatica REST Contract-Based API verwendet, und das OData Schema, das die Acumatica OData API verwendet. Das OData Schema wird zum Abfrage von Acumatica Generic Inquiries verwendet.
• Company: (Teilweise erforderlich) Setzen Sie hier den Namen Ihres Unternehmens oder Mieters. Dies ist erforderlich, wenn Schema ist auf OData eingestellt.
• EndpointVersion: (Optional) Die Version des Web Services Endpoint. Beispiel: 17.200.001 Dies gilt nur für das REST Schema.
• EndpointName: (Optional) Der Name des Web Services Endpoint. Beispiel: Standard. Dies gilt nur für das REST Schema.

Um das herauszufinden EndpointVersion Und EndpointName Melden Sie sich für Ihre Acumatica Instanz in einem Webbrowser bei Acumatica an und navigieren Sie dann zu Web Service Endpoints Seite. Navigieren Sie bei Bedarf zu dieser Seite, indem Sie die URL des Webbrowsers bearbeiten und ersetzen ScreenId=00000000 (die Homepage) mit ScreenId=SM207060. Wenn Sie zur Startseite zurückgeleitet werden, bedeutet dies, dass Ihr Benutzer nicht über die erforderlichen Berechtigungen verfügt, um auf Webdienste zuzugreifen. Unter Endpoints properties Holen Sie sich den Endpoint und die Endpoint.

Authentifizieren Sie sich bei Acumatica

Für die Verbindung mit der Acumatica Datenquelle stehen zwei Authentifizierungsmethoden zur Verfügung: Basic und OAuth.

Benutzeranmeldeinformationen

Setzen Sie die AuthScheme Zu Basic und setzen Sie die User Und Password zu Ihren Anmeldedaten.

OAuth

OAuth erfordert, dass der authentifizierende Benutzer über den Browser mit Acumatica interagiert. Daher erfordern alle OAuth-Flows eine benutzerdefinierte OAuth-Anwendung. Legen Sie außerdem für alle Flows Folgendes fest: AuthScheme Zu OAuth. Die folgenden Abschnitte setzen voraus, dass Sie dies getan haben.

Desktop-Anwendungen

Es wird eine eingebettete OAuth-Anwendung bereitgestellt, die die OAuth-Desktop-Authentifizierung vereinfacht. Alternativ können Sie eine benutzerdefinierte OAuth-Anwendung erstellen. Siehe Erstellen einer benutzerdefinierten OAuth-App für Informationen zum Erstellen benutzerdefinierter Anwendungen und Gründe dafür.

Der einzige Unterschied zwischen den beiden Methoden zur Authentifizierung besteht darin, dass Sie bei Verwendung benutzerdefinierter OAuth-Anwendungen zwei zusätzliche Verbindungseigenschaften festlegen müssen.

Nachdem Sie die folgenden Verbindungseigenschaften festgelegt haben, können Sie eine Verbindung herstellen:

• InitiateOAuth: Setzen Sie dies auf GETANDREFRESH. Sie können InitiateOAuth verwenden, um die Wiederholung des OAuth-Austauschs und das manuelle Festlegen der zu vermeiden OAuthAccessToken.
• OAuthClientId: Stellen Sie dies in Ihren Anwendungseinstellungen auf die Client-ID ein.
• OAuthClientSecret: Legen Sie dies in Ihren Anwendungseinstellungen auf das Client-Geheimnis fest.
• CallbackURL: Legen Sie dies in Ihren Anwendungseinstellungen auf die Umleitungs URL fest.

Wenn Sie eine Verbindung herstellen, öffnet der Connector den OAuth-Endpoint in Ihrem Standardbrowser. Melden Sie sich an und erteilen Sie der Anwendung Berechtigungen. Der Connector schließt dann den OAuth-Prozess ab:

1. Extrahiert das Zugriffstoken aus der Rückruf URL und authentifiziert Anfragen.
2. Erhält einen neuen Zugriffstoken, wenn der alte abläuft.
3. Speichert OAuth-Werte in OAuthSettingsLocation die über Verbindungen hinweg bestehen bleiben.

Webanwendungen

Wenn Sie eine Verbindung über eine Webanwendung herstellen, müssen Sie eine benutzerdefinierte OAuth-Anwendung erstellen und bei Acumatica registrieren. Siehe Erstellen einer benutzerdefinierten OAuth-App für weitere Informationen zu benutzerdefinierten Anwendungen. Sie können dann den Connector verwenden, um die OAuth-Tokenwerte abzurufen und zu verwalten.

OAuth-Zugriffstoken abrufen

Legen Sie die folgenden Verbindungseigenschaften fest, um das abzurufen OAuthAccessToken:

• OAuthClientId: Stellen Sie dies in Ihren Anwendungseinstellungen auf die Client-ID ein.
• OAuthClientSecret: Legen Sie dies in Ihren Anwendungseinstellungen auf das Client-Geheimnis fest.

Rufen Sie dann gespeicherte Prozeduren auf, um den OAuth-Austausch abzuschließen:

1. Rufen Sie GetOAuthAuthorizationURL auf gespeicherte Prozedur. Legen Sie den CallbackURL-Eingang auf die Rückruf URL fest, die Sie in Ihren Anwendungseinstellungen angegeben haben. Legen Sie bei Bedarf den Scope-Parameter fest, um benutzerdefinierte Berechtigungen anzufordern. Die gespeicherte Prozedur gibt die URL an den OAuth-Endpoint zurück.
2. Öffnen Sie die URL, melden Sie sich an und autorisieren Sie die Anwendung. Sie werden zurück zur Rückruf-URL geleitet.
3. Rufen Sie den GetOAuthAccessToken gespeicherte Prozedur. Setzen Sie den AuthMode-Eingang auf WEB. Setzen Sie den Verifier-Eingang auf den Parameter „Code“ in der Abfrage der Rückruf URL. Legen Sie bei Bedarf den Scope-Parameter fest, um benutzerdefinierte Berechtigungen anzufordern.

Sobald Sie die Zugriffs- und Aktualisierungstoken erhalten haben, können Sie eine Verbindung zu Daten herstellen und das OAuth-Zugriffstoken entweder automatisch oder manuell aktualisieren.

Automatische Aktualisierung des OAuth-Zugriffstokens

Damit der Treiber den OAuth-Zugriffstoken automatisch aktualisiert, legen Sie bei der ersten Datenverbindung Folgendes fest:

• InitiateOAuth: Setzen Sie dies auf REFRESH.
• OAuthClientId: Stellen Sie dies in Ihren Anwendungseinstellungen auf die Client-ID ein.
• OAuthClientSecret: Legen Sie dies in Ihren Anwendungseinstellungen auf das Client-Geheimnis fest.
• OAuthAccessToken: Setzen Sie dies auf den von GetOAuthAccessToken zurückgegebenen Zugriffstoken.
• OAuthRefreshToken: Setzen Sie dies auf das von GetOAuthAccessToken zurückgegebene Aktualisierungstoken.
• OAuthSettingsLocation: Legen Sie hier den Speicherort fest, an dem der Connector die OAuth-Tokenwerte speichert, die über Verbindungen hinweg bestehen bleiben.

Bei nachfolgenden Datenverbindungen werden die Werte für OAuthAccessToken und OAuthRefreshToken von übernommen OAuthSettingsLocation.

Manuelle Aktualisierung des OAuth-Zugriffstokens

Der einzige Wert, der zum manuellen Aktualisieren des OAuth-Zugriffstokens bei der Verbindung mit Daten benötigt wird, ist das OAuth-Aktualisierungstoken.

Verwenden Sie das RefreshOAuthAccessToken gespeicherte Prozedur zum manuellen Aktualisieren der OAuthAccessToken nach dem von GetOAuthAccessToken zurückgegebenen ExpiresIn-Parameterwert abgelaufen ist, legen Sie die folgenden Verbindungseigenschaften fest:

• OAuthClientId: Stellen Sie dies in Ihren Anwendungseinstellungen auf die Client-ID ein.
• OAuthClientSecret: Legen Sie dies in Ihren Anwendungseinstellungen auf das Client-Geheimnis fest.

Rufen Sie dann RefreshOAuthAccessToken auf mit OAuthRefreshToken gesetzt auf das von GetOAuthAccessToken zurückgegebene OAuth-Aktualisierungstoken. Nachdem die neuen Token abgerufen wurden, öffnen Sie eine neue Verbindung, indem Sie den OAuthAccessTokenEigenschaft auf den von RefreshOAuthAccessToken zurückgegebenen Wert.

Speichern Sie abschließend das OAuth-Aktualisierungstoken, damit Sie es nach Ablauf des OAuth-Zugriffstokens manuell aktualisieren können.

Erstellen einer benutzerdefinierten OAuth-App

Acumatica verwendet den OAuth-Authentifizierungsstandard, der erfordert, dass der authentifizierende Benutzer über den Browser mit Acumatica interagiert. Der Connector erleichtert den OAuth-Austausch auf verschiedene Weise, wie unten beschrieben.

Registrieren einer OAuth-Anwendung

Sie können das folgende Verfahren befolgen, um die OAuth-Client-Anmeldeinformationen zu erhalten, die OAuthClientId Und OAuthClientSecret.

1. Sie verwenden das Formular „Verbundene Anwendungen“ (SM303010), um eine OAuth 2.0- oder OpenID Connect-Clientanwendung zu registrieren. Um eine Clientanwendung in Acumatica ERP zu registrieren, müssen Sie den OAuth 2.0-Flow kennen, den diese Anwendung implementiert.
2. Wenn Sie die Client-Anwendung registrieren, müssen Sie bei dem Mandanten angemeldet sein, auf dessen Daten die Client-Anwendung zugreifen muss.
3. Klicken Sie auf der Tab „System“ auf „Integration“. Navigieren Sie im Navigationsbereich zu „Konfigurieren“ > „Verbundene Anwendungen“.
4. Geben Sie im Feld „Clientname“ den Namen der registrierten Anwendung ein.
5. Wählen Sie im Feld „OAuth 2.0 Flow“ die Option „Autorisierungscode“ aus.
6. Gehen Sie auf der Tab „Geheimnisse“ für jedes Client-Geheimnis, das Sie hinzufügen möchten, wie folgt vor:
   1. Klicken Sie in der Tab auf „Shared Secret hinzufügen“. Das Dialogfeld „Shared Secret hinzufügen“ wird geöffnet.
   2. Geben Sie im Feld Beschreibung die Beschreibung des gemeinsamen Geheimnisses ein.
   3. Optional: Geben Sie im Feld „Läuft ab am (UTC)“ das Datum und die Uhrzeit ein, an dem das Geheimnis abläuft.
   4. Kopieren und speichern Sie den im Feld „Wert“ angezeigten Wert. Die Client-Anwendung sollte dieses Client-Geheimnis zur Authentifizierung in Acumatica ERP verwenden.
7. Klicken Sie auf „OK“, um das Geheimnis zu speichern und das Dialogfeld zu schließen.
8. Führen Sie auf der Tab „Umleitungs-URIs“ für jede Umleitungs-URI, die Sie hinzufügen möchten, die folgenden Schritte aus: Klicken Sie in der Symbolleiste der Tab auf „Zeile hinzufügen“. Geben Sie in der Spalte „Umleitungs-URI“ der neuen Zeile die genaue Umleitungs-URI ein, zu der Acumatica ERP die Client-Anwendung umleiten soll, nachdem die Client-Anwendung autorisiert wurde. Die Umleitungs-URI muss absolut sein und darf keinen Fragmentteil enthalten (den Teil, dem # vorangestellt ist). Klicken Sie in der Symbolleiste des Formulars auf „Speichern“. Beachten Sie, dass die Client-ID im Feld „Client-ID“ generiert wurde. Die Client-Anwendung sollte diese Client-ID zusammen mit dem Client-Geheimnis zur Authentifizierung in Acumatica ERP verwenden.

Authentifizieren Sie sich bei Acumatica über eine Desktop-Anwendung

Um ein Token zu erhalten, muss die Clientanwendung den Oauth2 Endpoint mit verschiedenen Berechtigungen aufrufen, je nach den erforderlichen Authentifizierungsszenarien. Der standardmäßige OAuthGrantType ist CODE, was erfordert, dass Sie die folgenden Schritte ausführen. Nachdem Sie die folgenden Verbindungseigenschaften festgelegt haben, können Sie eine Verbindung herstellen:

• OAuthClientId: Setzen Sie dies auf Ihre Client-ID.
• OAuthClientSecret: Setzen Sie dies auf Ihr Client-Geheimnis.
• InitiateOAuth: Setzen Sie dies auf GETANDREFRESH. Sie können InitiateOAuth verwenden, um die Wiederholung des OAuth-Austauschs und das manuelle Setzen von zu vermeiden OAuthAccessToken Verbindungseigenschaft.
• CallbackURL: Legen Sie dies auf die in der OAuth-Anwendung konfigurierte Umleitungs-URI fest.

Wenn Sie eine Verbindung herstellen, schließt der Connector den OAuth-Prozess ab:

1. Extrahiert das Zugriffstoken aus dem CallbackURL.
2. Erhält einen neuen Zugriffstoken, wenn der alte abläuft.
3. Speichert OAuth-Werte zusammen mit der Geolokalisierung in OAuthSettingsLocation soll über mehrere Verbindungen hinweg bestehen bleiben.

Acumatica Optimierung

Acumatica hat in Version 3 der Contract Based API eine Optimierung eingeführt. Wenn mehrere Datensätze über einen Endpoint aus dem Acumatica ERP abgerufen werden, versucht das System, den Abruf der Datensätze zu optimieren und alle benötigten Datensätze in einer Anfrage an die Datenbank abzurufen. Wenn die Optimierung fehlschlägt, gibt das System einen Fehler zurück und gibt die Entitäten oder Felder an, die das Fehlschlagen der optimierten Anfrage verursacht haben. Meistens unterbrechen die Navigationsansichten die Optimierung, da Acumatica versucht, Daten aus den verknüpften Tabellen abzurufen. Aus diesem Grund sind die SELECT *-Abfragen von Navigationsansichten ohne Angabe des Schlüssels der übergeordneten Tabelle nicht möglich. Unsere Treiber versuchen, die Spalten, die die Optimierung unterbrechen, aus den SELECT *-Abfragen zu entfernen.

Einige der Ansichten, die die Optimierung unterbrechen, wenn sie ohne Angabe der Schlüsselfelder ausgewählt werden, sind JournalVoucher_Details. Um die JournalVoucher_Details Abfrage, muss die ParentBatchNbr angegeben werden.

SELECT * FROM JournalVoucher_Details where ParentBatchNbr = '0001'

Die Ansicht kann abgefragt werden, indem das übergeordnete Schlüsselfeld, in diesem Fall ParentBatchNbr, aus der übergeordneten Tabelle JournalVoucher abgerufen wird.

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

Weitere Informationen zum Umgehen der Acumatica Optimierung finden Sie hier: Einschränkungen.

Wichtige Hinweise

Konfigurationsdateien und ihre Pfade

• Alle Verweise auf das Hinzufügen von Konfigurationsdateien und deren Pfaden beziehen sich auf Dateien und Speicherorte auf dem Jitterbit-Agenten, auf dem der Connector installiert ist. Diese Pfade sind je nach Agent und Operationssystem entsprechend anzupassen. Wenn mehrere Agenten in einer Agentengruppe verwendet werden, werden auf jedem Agenten identische Dateien benötigt.

Erweiterte Funktionen

In diesem Abschnitt wird eine Auswahl erweiterter Funktionen des Acumatica Connectors beschrieben.

Benutzerdefinierte Ansichten

Der Connector ermöglicht Ihnen die Definition virtueller Tabellen, sogenannter benutzerdefinierter Ansichten, deren Inhalt durch eine vorkonfigurierte Abfrage bestimmt wird. Diese Ansichten sind nützlich, wenn Sie die an die Treiber gesendeten Abfragen nicht direkt steuern können. Siehe Benutzerdefinierte Ansichten für einen Überblick über das Erstellen und Konfigurieren benutzerdefinierter Ansichten.

SSL-Konfiguration

Verwenden Sie SSL-Konfiguration, um anzupassen, wie der Connector TLS/SSL-Zertifikatsverhandlungen handhabt. Sie können aus verschiedenen Zertifikatsformaten wählen; siehe SSLServerCert-Eigenschaft unter „Verbindungszeichenfolgenoptionen“ für weitere Informationen.

Proxy

So konfigurieren Sie den Connector mit privaten Agent-Proxy-Einstellungen, wählen Sie die Use Proxy Settings Kontrollkästchen auf dem Verbindungskonfigurationsbildschirm.

Abfrageverarbeitung

Der Connector verlagert möglichst viel der Verarbeitung der SELECT-Anweisung auf Acumatica und verarbeitet dann den Rest der Abfrage im Speicher (clientseitig).

Siehe Abfrageverarbeitung für weitere Informationen.

Benutzerdefinierte Ansichten

Mit dem Jitterbit Connector für Acumatica können Sie eine virtuelle Tabelle definieren, deren Inhalt durch eine vorkonfigurierte Abfrage bestimmt wird. Diese werden als benutzerdefinierte Ansichten bezeichnet und sind in Situationen nützlich, in denen Sie die an den Treiber gesendete Abfrage nicht direkt steuern können, z. B. wenn Sie den Treiber von Jitterbit verwenden. Die benutzerdefinierten Ansichten können verwendet werden, um Prädikate zu definieren, die immer angewendet werden. Wenn Sie in der Abfrage an die Ansicht zusätzliche Prädikate angeben, werden diese mit der bereits als Teil der Ansicht definierten Abfrage kombiniert.

Es gibt zwei Möglichkeiten, benutzerdefinierte Ansichten zu erstellen:

• Erstellen Sie eine Konfigurationsdatei im JSON-Format, die die gewünschten Ansichten definiert.
• DDL-Anweisungen.

Definieren von Ansichten mithilfe einer Konfigurationsdatei

Benutzerdefinierte Ansichten werden in einer JSON-formatierten Konfigurationsdatei namens UserDefinedViews.json. Der Connector erkennt die in dieser Datei angegebenen Ansichten automatisch.

Sie können auch mehrere Ansichtsdefinitionen haben und diese mit steuern UserDefinedViews Verbindungseigenschaft. Wenn Sie diese Eigenschaft verwenden, werden vom Connector nur die angegebenen Ansichten angezeigt.

Diese Konfigurationsdatei für benutzerdefinierte Ansichten ist wie folgt formatiert:

• Jedes Stammelement definiert den Namen einer Ansicht.
• Jedes Stammelement enthält ein untergeordnetes Element namens query, das die benutzerdefinierte SQL- Abfrage für die Ansicht enthält.

Zum Beispiel:

{
    "MyView": {
        "query": "SELECT * FROM Events WHERE MyColumn = 'value'"
    },
    "MyView2": {
        "query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
    }
}

Verwenden Sie UserDefinedViews Verbindungseigenschaft, um den Speicherort Ihrer JSON-Konfigurationsdatei anzugeben. Beispiel:

"UserDefinedViews", "C:\Users\yourusername\Desktop\tmp\UserDefinedViews.json"

Definieren von Ansichten mit DDL-Anweisungen

Der Connector kann das Schema auch über DDL-Anweisungen wie CREATE LOCAL VIEW, ALTER LOCAL VIEW und DROP LOCAL VIEW erstellen und ändern.

Erstellen einer Ansicht

Um eine neue Ansicht mit DDL-Anweisungen zu erstellen, geben Sie den Ansichtsnamen und die Abfrage wie folgt an:

CREATE LOCAL VIEW`[MeinAnsichtsname] `AS SELECT * FROM Customers LIMIT 20;

Wenn keine JSON-Datei vorhanden ist, erstellt der obige Code eine. Die Ansicht wird dann in der JSON-Konfigurationsdatei erstellt und ist nun erkennbar. Der Speicherort der JSON-Datei wird durch angegeben UserDefinedViews Verbindungseigenschaft.

Ändern einer Ansicht

Um eine vorhandene Ansicht zu ändern, geben Sie den Namen der vorhandenen Ansicht zusammen mit der neuen Abfrage an, die Sie stattdessen verwenden möchten:

ALTER LOCAL VIEW`[MeinAnsichtsname] `AS SELECT * FROM Customers WHERE TimeModified > '3/1/2020';

Die Ansicht wird dann in der JSON-Konfigurationsdatei aktualisiert.

Löschen einer Ansicht

Um eine vorhandene Ansicht zu löschen, geben Sie den Namen eines vorhandenen Schema neben der neuen Abfrage an, die Sie stattdessen verwenden möchten.

DROP LOCAL VIEW [MyViewName]

Dadurch wird die Ansicht aus der JSON-Konfigurationsdatei entfernt. Sie kann nicht mehr abgefragt werden.

Schema für benutzerdefinierte Ansichten

Benutzerdefinierte Ansichten werden im angezeigt UserViews Schema standardmäßig. Dies geschieht, um zu vermeiden, dass der Name der Ansicht mit einer tatsächlichen Entität im Datenmodell kollidiert. Sie können den Namen des für UserViews verwendeten Schema ändern, indem Sie festlegen UserViewsSchemaName Eigentum.

Arbeiten mit benutzerdefinierten Ansichten

Beispielsweise eine SQL-Anweisung mit einer benutzerdefinierten Ansicht namens UserViews.RCustomers listet nur Kunden in Raleigh auf:

SELECT * FROM Customers WHERE City = 'Raleigh';

Ein Beispiel für eine Abfrage an den Treiber:

SELECT * FROM UserViews.RCustomers WHERE Status = 'Active';

Daraus ergibt sich die effektive Abfrage an die Quelle:

SELECT * FROM Customers WHERE City = 'Raleigh' AND Status = 'Active';

Dies ist ein sehr einfaches Beispiel für eine Abfrage an eine benutzerdefinierte Ansicht, die tatsächlich eine Kombination aus der Abfrage und der Ansichtsdefinition ist. Es ist möglich, diese Abfragen in viel komplexeren Mustern zusammenzustellen. Alle SQL-Operationen sind in beiden Abfragen zulässig und werden bei Bedarf kombiniert.

SSL-Konfiguration

Anpassen der SSL-Konfiguration

Standardmäßig versucht der Connector, SSL/TLS auszuhandeln, indem er das Zertifikat des Servers mit dem vertrauenswürdigen Zertifikatspeicher des Systems vergleicht.

Um ein anderes Zertifikat anzugeben, siehe SSLServerCert Eigenschaft für die verfügbaren Formate, um dies zu tun.

REST-Datenmodell

Der Connector modelliert die Acumatica API als relationale Tabellen. Alle Änderungen an den Remote-Daten werden sofort in Ihren Abfragen widergespiegelt; die Tabellendefinitionen werden dynamisch abgerufen. Wenn Sie eine Verbindung herstellen, stellt der Connector eine Verbindung zu Acumatica her und ruft die Liste der Tabellen und die Metadaten für die Tabellen ab, indem er die entsprechenden Webdienste aufruft.

API Einschränkungen und-Anforderungen sind in diesem Abschnitt dokumentiert. Sie können die SupportEnhancedSQL Funktion, standardmäßig eingestellt, um die meisten dieser Einschränkungen zu umgehen.

Tabellen

Zeigt Standardtabellendefinitionen von Acumatica an. Ihre tatsächlichen Tabellen können je nach Ihren Anpassungen abweichen. Diese Tabellen wurden ab Version 17.200.001 aufgezeichnet, aber spätere Versionen können mehr Tabellen und Felder enthalten als hier angezeigt. Der Jitterbit Connector für Acumatica liest Tabellen- und Spaltenmetadaten dynamisch, sodass er sowohl Ihre Anpassungen als auch alle neuen Funktionen enthält, die in Zukunft zu Standard Acumatica-Entitäten hinzugefügt werden. Sie müssen nur die festlegen URL Verbindungseigenschaft zur neuesten Version, um die Änderungen zu erhalten.

Gespeicherte Prozeduren

Gespeicherte Prozeduren sind funktionsähnliche Schnittstellen zu Acumatica. Sie können verwendet werden, um zusätzliche Aufgaben auszuführen, die nicht in die

Operation der direkten Interaktion mit einer Tabelle.

Einschränkungen

Benutzerdefinierte Felder

Standardmäßig beschreiben die Tabellen- und Ansichtsschemata das Spaltenverhalten von Systemfeldern sowie benutzerdefinierten Feldern. Sie können die IncludeCustomFields-Eigenschaft auf „false“, wenn Sie nur mit Systemfeldern arbeiten möchten. Bei einer SELECT * FROM EntityName Abfrage werden die benutzerdefinierten Felder nicht zurückgegeben, obwohl IncludeCustomFields ist auf true gesetzt. Die benutzerdefinierten Felder werden nur zurückgegeben, wenn sie in Projektionen angegeben sind. Beispiel:

SELECT Custom_FieldA, Custom_FieldB, Custom_FieldC FROM EntityName

Die Anforderung, die benutzerdefinierten Felder explizit auszuwählen, beruht auf einer Einschränkung der Acumatica API. Sie gibt keine Ergebnisse zurück, wenn zu viele Gesamtdaten pro Datensatz ausgewählt werden. Es ist nicht möglich, dynamisch zu berechnen, an welchem Punkt Acumatica die Ergebnisse abschneidet. Sie sollten nur die Spalten auswählen, die Sie benötigen, und nicht alles, damit alles reibungslos funktioniert.

Falls eine Gruppe benutzerdefinierter Felder für Ihren Anwendungsfall wichtig ist und die Acumatica API sie nicht in einer einzigen Antwort zurückgeben kann, empfiehlt es sich, einen erweiterten Endpoint einzurichten und die benutzerdefinierten Felder darin einzuschließen. Nach dieser Änderung sollten Sie sie als nicht benutzerdefinierte Felder vom erweiterten Endpoint abrufen können.

Eine Alternative zur Erweiterung eines vorhandenen Endpoint besteht darin, die Abfrage in zwei oder mehr Unterabfragen aufzuteilen und die ausgewählten benutzerdefinierten Felder auf diese zu verteilen. Schließlich können Sie die Unterabfragen in der Primärschlüsselspalte wie im folgenden Beispiel verknüpfen.

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

Verknüpfte und detaillierte Entitäten

Die verknüpften und Detailentitäten zur Hauptentität werden in der Hauptentitätstabelle als aggregierte Spalten angezeigt, die mit dem Präfix „Verknüpft“ beginnen. Sie werden auch als separate Ansichten mit dem Benennungsformat „Hauptentitätsname_VerknüpfterEntitätsname“ angezeigt. Beispielsweise wird Kunde-Tabelle stellt die verknüpfte Entität „Kontakte“ als Aggregatfeld „LinkedContacts“ bereit. Die verknüpfte Entität „Kontakte“ wird auch als separate Ansicht Customer_Contacts bereitgestellt.

Aufgrund von Einschränkungen der Acumatica REST- API können die verknüpften und detaillierten Entitäten nicht abgerufen werden, wenn mehrere Hauptentitätsdatensätze angefordert werden. Aus diesem Grund werden die verknüpften Aggregatfelder als Null zurückgegeben, wenn die Hauptentität abgefragt wird, ohne dass der Primärschlüssel in den Bedingungen der WHERE-Klausel angegeben wird. Um beispielsweise die Aggregatwerte der verknüpften Entität „Kontakte“ in Kunde abzurufen,-Tabelle können Sie eine der folgenden Abfragen ausführen.

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

Sie können auch den IN-Operator und die Unterabfragen wie unten verwenden, um die verknüpften und Detailentitäten für mehrere übergeordnete Datensätze abzurufen.

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

Um die angezeigten verknüpften und detaillierten Entitäten Abfrage, ist es außerdem erforderlich, den Primärschlüssel der übergeordneten Entität in den Bedingungen der WHERE-Klausel anzugeben. Beispiel:

SELECT * from Customer_Contacts where ParentCustomerID = '100009'

Ausgeschlossene Spalten

Acumatica hat in Version 3 der Contract Based API eine Optimierung eingeführt. Wenn mehrere Datensätze über einen Endpoint aus dem Acumatica ERP abgerufen werden, versucht das System, den Abruf der Datensätze zu optimieren und alle benötigten Datensätze in einer Anfrage an die Datenbank abzurufen. Wenn die Optimierung fehlschlägt, gibt das System einen Fehler zurück und gibt die Entitäten oder Felder an, die das Fehlschlagen der optimierten Anfrage verursacht haben. Um das Auftreten des Fehlers zu verhindern, müssen wir einen der folgenden Schritte ausführen:

• Holen Sie sich alle Datensätze nacheinander, indem Sie die Schlüsselfelder angeben.
• Nur die Felder abrufen, die die Optimierung nicht beeinträchtigen.

Erstellen Sie das Schema durch den Aufruf von CreateSchema, sofern Sie dies nicht bereits getan haben.

Fügen Sie die zusätzlichen Parameter in den folgenden RSD Schema hinzu.

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

Diese beiden Parameter sind erforderlich, damit die neuen Entitäten bei SELECT * FROM Table-Abfragen keinen Fehler zurückgeben. Das folgende Beispiel ist ein RSD-Ausschnitt, der zeigt, wie diese Parameter verwendet werden.

Im Beispiel sind Contact.rsd, Duplicate und AddressValidated Felder, die die Acumatica Optimierung unterbrechen, daher haben sie den zusätzlichen Parameter other:exclude="true". Wenn eine SELECT * FROM Contact-Abfrage ausgeführt wird, erhält der Treiber alle Felder außer denen mit dem other:exclude="true"-Parameter. Die ausgelassenen Felder werden jedoch trotzdem als Null in Ihrem Ergebnissatz angezeigt. Der Datenanbieter fordert die ausgeschlossenen Felder nur dann vom Endpoint an, wenn sie in der SELECT-Klausel explizit angegeben sind oder wenn die Primärschlüsselspalte(n) angegeben sind.

Im Beispiel Contact.rsd ist ContactID der Primärschlüssel, daher der zusätzliche Parameter key="true" wird hinzugefügt. Wenn ein SELECT * FROM Contact WHERE ContactID='contactid' ausgeführt wird, erhält der Treiber alle Felder von der API, einschließlich Duplicate und 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>

Benutzerdefinierte Ansichten erstellen

Eine einfache und effektive Möglichkeit, den Prozess des Abrufens aller Datensätze nacheinander durch Angabe der Schlüsselfelder zu automatisieren, sind benutzerdefinierte Ansichten. Benutzerdefinierte Ansichten sind vordefinierte Abfragen, die in einer lokalen JSON-Datei gespeichert sind und wie die vorhandenen Ansichten vom Treiber abgefragt werden können.

Wie im obigen Abschnitt angegeben, werden die ausgeschlossenen Felder abgerufen, wenn der Primärschlüssel angegeben ist. Sie können die erweiterte SQL-Unterstützung des Treibers verwenden, um dies automatisch für jeden Datensatz durchzuführen, indem Sie Ihrer Abfrage eine IN-Unterabfrage anhängen. Aus der Unterabfrage sollten Sie wie im folgenden Beispiel nur die Primärschlüsselspalte auswählen.

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

Sie können diese Abfrage dann unter dem Feld „Abfrage“ einer lokal erstellten JSON-Datei hinzufügen (z. B. C:\Benutzer\Benutzer\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)"
    }
}

Schließlich können Sie die definierten Ansichten (AllContacts und AllCustomers) direkt Abfrage, nachdem Sie den Speicherort der benutzerdefinierten Ansichten-Datei in der Eigenschaft UserDefinedViews unter dem Verbindungsparameter „Sonstiges“ angegeben haben.

Andere='UserDefinedViews=C:\Benutzer\Benutzer\Desktop\CustomViews.json;'

Sie können auch eine Abfrage an die sys_tables-Ansicht ausführen, um zu überprüfen, ob die benutzerdefinierten Ansichten hinzugefügt wurden. Sie sollten sie unter dem UserViews Schema finden können.

SELECT * FROM sys_tables where TableType='view'

Tabellen

Der Connector modelliert die Daten in Acumatica als Liste von Tabellen in einer relationalen Datenbank, die mit Standard-SQL-Anweisungen abgefragt werden können.

Jitterbit-Anschluss für Acumatica Tabellen

Konto

Konto ist eine automatisch generierte Tabelle.

Spalten

KontoNachZeitraumAnfrage

AccountByPeriodInquiry ist eine automatisch generierte Tabelle.

Spalten

KontoNachUnterkontoAnfrage

AccountBySubaccountInquiry ist eine automatisch generierte Tabelle.

Spalten

KontodetailsAnfrage

AccountDetailsInquiry ist eine automatisch generierte Tabelle.

Spalten

Kontostandort

AccountLocation ist eine automatisch generierte Tabelle.

Spalten

KontoübersichtAnfrage

AccountSummaryInquiry ist eine automatisch generierte Tabelle.

Spalten

Anpassung

Die Anpassung erfolgt über eine automatisch generierte Tabelle.

Spalten

Attributdefinition

AttributeDefinition ist eine automatisch generierte Tabelle.

Spalten

Rechnung

Bill ist eine automatisch generierte Tabelle.

Spalten

Geschäftskonto

BusinessAccount ist eine automatisch generierte Tabelle.

Spalten

Fahrer

Carrier ist eine automatisch generierte Tabelle.

Spalten

Fall

Fall ist eine automatisch generierte Tabelle.

Spalten

Barverkauf

CashSale ist eine automatisch generierte Tabelle.

Spalten

Überprüfen

Check ist eine automatisch generierte Tabelle.

Spalten

Kontakt

Kontakt ist eine automatisch generierte Tabelle.

Spalten

Währung

Währung ist eine automatisch generierte Tabelle.

Spalten

Kunde

Kunde ist eine automatisch generierte Tabelle.

Spalten

Kundenklasse

CustomerClass ist eine automatisch generierte Tabelle.

Spalten

Kundenstandort

CustomerLocation ist eine automatisch generierte Tabelle.

Spalten

KundeZahlungsmethode

CustomerPaymentMethod ist eine automatisch generierte Tabelle.

Spalten

KundenPreisKlasse

CustomerPriceClass ist eine automatisch generierte Tabelle.

Spalten

Rabatt

Rabatt ist eine automatisch generierte Tabelle.

Spalten

Rabattcode

DiscountCode ist eine automatisch generierte Tabelle.

Spalten

Email

Email ist eine automatisch generierte Tabelle.

Spalten

Mitarbeiter

Mitarbeiter ist eine automatisch generierte Tabelle.

Spalten

Ereignis

Ereignis ist eine automatisch generierte Tabelle.

Spalten

Finanzperiode

FinancialPeriod ist eine automatisch generierte Tabelle.

Spalten

FOBPunkt

FOBPoint ist eine automatisch generierte Tabelle.

Spalten

InterBranchAccountMapping

InterBranchAccountMapping ist eine automatisch generierte Tabelle.

Spalten

BestandszuordnungAnfrage

InventoryAllocationInquiry ist eine automatisch generierte Tabelle.

Spalten

Inventarbeleg

InventoryReceipt ist eine automatisch generierte Tabelle.

Spalten

BestandsübersichtAnfrage

InventorySummaryInquiry ist eine automatisch generierte Tabelle.

Spalten

Rechnung

Die Rechnung ist eine automatisch generierte Tabelle.

Spalten