Integrating With JustOn Connector for DATEV

Your organization's business may require to export bookkeeping data to DATEV. To support this scenario, you can integrate your Salesforce app with JustOn Connector for DATEV DE, an app for exporting accounting data to DATEV.

This document aims at developers. Namely, it

• outlines the involved object schemas,
• shows how to transfer accounting data from your app to JustOn Connector for DATEV, and
• summarizes best practices.

Object Schemas

The relevant objects include the accounting document and the accounting document item (or accounting detail). Accounting documents and accounting details are in a master-detail relationship.

The schemas below show the fields that are required to transfer accounting data. The package namespace prefix for accessing this data is DATEV1.

Accounting Document

An Accounting Document object represents an invoice or a cash book record.

The type of an accounting document is determined by its record type. There are three record types available:

Record Type Name	Purpose
Accounts Payable Ledger	used for purchase (incoming) invoice data
Accounts Receivable Ledger	used for sales (outgoing) invoice data
Cash Ledger	used for cashbook data

The following Accounting Document fields require particular attention with respect to the integration:

Field Name	Data Type	Required	Description
DocumentDate	Date		The date of the document. The date is used to chose the accounting month/period for this invoice or cash book.
CurrencyCode	Picklist		The ISO currency code
CurrencyIsoCode	Text		If the Salesforce org has enabled the multi-currency feature, the CurrencyIsoCode field must hold the same value as the CurrencyCode field.
RecordTypeId	Id		Determines the extension of the ledger XML file that will be generated when the data is transferred to DATEV.
Locked	Checkbox		Must be set true after inserting the last accounting detail.
ThirdParty	Checkbox		Must be set true after inserting the last accounting detail.

Info

To get a complete overview of Accounting Document fields, use the Salesforce Object Manager.

Accounting Document Item

An Accounting Document Item (Accounting Detail) object represents a record in an accounting ledger. It is used to split the amount of the invoice or cash book record to multiple bookkeeping accounts.

You need at least one Accounting Detail record to work with. The sum of the amount over all accounting details must be equal to the grand total of the invoice or the amount of the cash book record.

The type of an accounting document item is determined by its record type. The record type must match the record type of the parent accounting document. There are three record types available:

Record Type Name	Purpose
Accounts Payable Ledger	used for purchase (incoming) invoice data
Accounts Receivable Ledger	used for sales (outgoing) invoice data
Cash Ledger	used for cashbook data

The following Accounting Document Item fields require particular attention with respect to the integration:

Field Name	Data Type	Required	Description
AccountingDocument	Lookup (Accounting Document)		The associated accounting document
Amount	Currency (10,2)
AccountNo	Text (9)		Used to provide an initial account assignment for DATEV.
AccountingDate	Date		Can be used to overwrite the field DocumentDate of the accounting document for this particular accounting detail.
RecordTypeId	Id		Determines the extension of ledger XML file that will be generated when the data is transferred to DATEV. The API name of this record type must be the same as the API name of the record type of the accounting document.
CurrencyIsoCode	Currency		Must match the CurrencyIsoCode of the accounting document. Required if the Salesforce org has enabled the multi-currency feature.

Info

To get a complete overview of Accounting Document Item (Document Detail) fields, use the Salesforce Object Manager.

Accounting Document Attachments

There are typically one or more file attachments associated with an accounting document. The file attachments represent images of the invoice. They are sent to the accounting system with the first job that has the accounting document in scope.

Note

• A file attachment must not be larger than 4 MB.
• File attachments are expected as binaries.
• Base64 encoding is not supported.
• File names that include decomposed Unicode characters are not supported.
• Document images must be associated with the accounting document as Attachment (Salesforce Classic-specific type). Document images associated with the accounting document as File (Salesforce Lightning default type) will not be transferred.

The allowed file types include:

bmp, gif, jpeg, jpg, png, tif, tiff, csv, doc, docx, dta, msg, ods, odt, pdf, rtf, txt, xls, xlsx, xml, eml

Data Transfer Procedure

The following steps outline an example workflow for transferring accounting data to JustOn Connector for DATEV.

1. Retrieve the IDs of the record types.

   The JustOn Connector for DATEV package contains record types with the following API names:

   • accountsPayableLedger
   • accountsReceivableLedger
   • cashLedger

   These types are available for both the Accounting Document object and the Accounting Document Item object. When setting the RecordTypeId field of these objects, make sure to use the IDs of the corresponding SObject type.

   Retrieve a map that maps the SObject type to the ID of the record type for accountsPayableLedger:

   Map<String, Id> recordTypes = new Map<String, Id>();
   for (SObject recordType : [SELECT Id,SobjectType FROM recordtype WHERE (DeveloperName = 'accountsReceivableLedger')]) {
       recordTypes.put((String)recordType.get('SobjectType'), recordType.Id);
   }
   Id recordTypeForAccountingDocument = recordTypes.get('DATEV1__AccountingDocument__c');
   Id recordTypeForAccountingDetail = recordTypes.get('DATEV1__AccountingDetail__c');
   

2. Prepare the Accounting Document records in memory.

   An Accounting Document record is required for each set of accounting data that refers to a specific invoice or cash book record. Prepare the records and set all fields except the Locked and ThirdParty fields, which are set in the final step.

3. Insert the Accounting Document records into the database.

   This step will also associate Salesforce IDs with the Accounting Document records.

4. Prepare the Accounting Detail records in memory.

   Prepare the records by setting all fields and the AccountingDocument field to the corresponding Salesforce ID of the Accounting Document.

5. Persist the Accounting Detail records.

   In case of errors, make sure to delete the corresponding Accounting Document records in order to avoid incompletely transferred accounting data.

6. Add file attachments to the Accounting Document records.

   Clone any attachment that should be associated with the Accounting Document records, set the ParentId to the ID of the accounting document and insert the clones into the database.

7. Set the Locked and ThirdParty fields of the Accounting Document records.

   For the created Accounting Document records, set the Locked and ThirdParty fields to true and update them. This is required to comply with the regulations for the accounting standard compliant operation (GoBD).

8. Mark the transferred records.

   Mark your original accounting data records to indicate that the related data is already transferred to avoid multiple transfers. This can be done by a lookup relationship to the Accounting Document object or the Accounting Document Item object or by setting a flag on the source records.

Best Practices

Lookup Relations

JustOn recommends to create lookup relations between the original accounting data of your app and the Accounting Document or Accounting Document Item objects. This facilitates the navigation between the transferred data and the original accounting data.

To this end, create some custom Lookup fields as shown below. Make sure to replace YourInvoice and YourAccountingData with the names of the appropriate objects of your app.

Object	Data Type	Description	Configuration Details
Accounting Document	Lookup (YourInvoice)	Links to the related original invoice or cash book.	Set the field when creating the Accounting Document object.
Accounting Document Item	Lookup (YourAccountingData)	Links to the related original accounting data.	Set the field when creating the Accounting Document Item object.
YourInvoice	Lookup (Accounting Document Item)	Links to the related exported accounting document item.	Set the field after persisting the Accounting Document Item objects.

Error Handling

In case of an error upon persisting the Accounting Document Item records, like, for example, because a validation rule rejects the data, the related Accounting Document record is also to be deleted. Already persisted accounting document items of the same accounting document are deleted as well, which avoids incompletely transferred accounting data.

Info

Generally, JustOn recommends to present errors to the users in order to resolve the corresponding issues.

Dependencies

In order to avoid dependencies of your app to JustOn Connector for DATEV, the objects and fields of JustOn Connector for DATEV must be accessed in a generic way as shown below.

Check whether package is available

Boolean packageAvailable = (Schema.getGlobalDescribe().get('DATEV1__AccountingDocument__c') != null);

Create and access objects

SObject accountingDocument = Schema.getGlobalDescribe().get('DATEV1__AccountingDocument__c').newSObject();
obj.put('DATEV1__InvoiceId__c', 'foo');

Accounting Standard Compliant Operation

IT systems must properly map accounting policies and comply with the generally accepted principles of computerized accounting systems and the generally accepted principles of proper accounting when using information technology. For Germany, these principles are determined in an administrative regulation of the Federal Ministry of Finance ("Grundsätze zur ordnungsmäßigen Führung und Aufbewahrung von Büchern, Aufzeichnungen und Unterlagen in elektronischer Form sowie zum Datenzugriff (GoBD)").

These regulations determine how and under which circumstances JustOn Connector for DATEV allows modifications to accounting documents and accounting document items.

Statuses

Status	Description
Unlocked	The accounting document is not locked (Locked = false) and no data transfer is associated.
Locked	The accounting document is locked (Locked = true) and no data transfer is associated.
In Transfer	A data transfer is associated with the accounting document and the local status is not Closed or the DATEV Status is In Progress or Open.
Transfer Successful 3rd Party Data	A data transfer is associated with the accounting document and the DATEV Status is Finished. In addition, the field ThirdParty = true.
Transfer Stopped	A data transfer is associated with the accounting document and the DATEV Status is Aborted, Needs Checking, Successfully Canceled, Canceled with Error.

Status	Insert/Update/Delete: Accounting Document Items & Attachments	Delete: Accounting Document & Accounting Document Items
Unlocked	Y	Y
Locked	N	Y
In Transfer	N	N
Transfer Successful 3rd Party Data	N	N
Transfer Stopped	N	Y

Data Transfer With Attachments

Data transfers can only be created and updated by JustOn Connector for DATEV. Data transfers are managed by users.

Action	Description
New Data Transfer	Create a new data transfer using the DATEV APIs.
Refresh Data Transfer	Update the DATEV status.
Delete Data Transfer	Delete the job and its attachments. Only possible if the DATEV status is one of Open, Aborted, Needs Checking, Successfully Canceled, Canceled with Error