Topic overview

This article describes the procedures for working with the Import data application with regard to partner data. These procedures contain general instructions, such as the sequence that must be followed to import partner data. Furthermore, this document discusses the preconditions and effects of partner data import. For a description of the Import data application itself, see the Import data article.

Definition of terms

Extensible Markup Language (XML)

It is a universal markup language used to represent different data in a structured way. XML allows structured data to be saved in a text file. The description language enables the definition, transfer, checking, and interpretation of data between applications and is especially suitable for structured data exchange. Content, structure, and information are separated for presentation in XML documents.

Separator-delimited text (CSV)

CSV (comma-separated values) is a file type in which the values of individual columns are delimited by a separator. Rows are delimited by line breaks. This separator must be known in order to import the file. Usual separators are, for example, the simple comma and the semicolon. Data saved in this format can be used and processed in numerous application programs. The simple, non-hierarchical structure of CSV means that this file type is not suitable for mapping complex data structures.

Tab-delimited Unicode text

This file type is similar to CSV, except that the separator is a tab and the character encoding is Unicode. Files in this format can be used in Microsoft Excel, among other applications. In order to save this file type in Excel, you must specify the file type with the same name in Excel.

General

Two categories of data exchange are distinguished in the system:

• Data exchange between existing Comarch ERP Enterprise systems
• Data import from an older system to a newly configured Comarch ERP Enterprise system

The data exchange between systems is described in detail in the Import data and Export data articles.

You can use various import formats. The following formats are available:

• XML format
• CSV format
• XLS format
• JSON format

Each format has special properties that affect the data import.

If import is carried out in XML format, all of the data desired can be imported
in a single import operation.

If import is carried out in CSV format, a different procedure is necessary. A technical limitation exists in that parallel 1:n relationships between business objects cannot be represented in one import file. That means, for example, that it is not possible to import supplier and customer data from one file. However, it is possible to work with references and, thus, to import most of the data within one import operation, even from multiple files. This plays a decisive role in the import speed.

Processes

This chapter discusses the preconditions that must be met for importing partner data and the procedures for working with the Import data application:

• Importing data
• Necessary attributes for importing data from older systems
• Sequence
• Importing a new partner
• Importing a new partner role
• Importing a partner role for a subordinate organization
• Importing an inherited structure

Importing data

Instructions

1. Open the Import data application

2. Select the Partner value in the Filter field

3. Select the filter for the com.cisag.app.general.obj.Partner business entity in the Business entity field

4. Selected filter attributes will be activated. If required, it is possible to further adjust attributes.

5. Click the [Import data] button in the standard toolbar

6. The Import data dialog window will open. The window makes it possible to adjust import file settings.

7. Click the [In background] button to initiate import

Necessary attributes for importing data from older systems

To import data from earlier versions of the system, it is necessary to specify at least the following attributes for each Partner business entity:

• Identification attributes (business key)

In most business cases you are probably using the business key, while the primary key is generated automatically when import is carried out.

• Required fields

The Partner business object cannot be assigned without the identification attributes. The required fields and identification attributes of individual business objects are summarized in the Identification fields and required fields chapter.

If the primary key of a business object consists solely or partly of an external key, the business object to which this external key refers must be resolved in the import file by means of its identification attributes.

Sequence

If the user wants to import data items that are dependent on one another, it is necessary to follow the defined sequence.

Standard sequence

1. Employees of the company

2. Customer and suppliers that refer only to themselves in partner relationships (invoice recipient, delivery recipient, invoicing party, delivery partner)

3. Customers and suppliers that refer to other partners in partner relationships

4. Employees of customers and suppliers

5. Contact person relationships

6. Bank detail data of all partners

Standard sequence for a single-site environment

1. Base data

2. Financials data

3. Role data

Sequence and additional conditions for a multi-site environment

If the user wants to import a Customer, Supplier, or Marketing role, it is necessary to import the active OLTP client data for the relevant usage before any other organizations.

In the Partners application, it is also possible to maintain relationships to other partners, such as invoice recipients and contact persons, and therefore the sequence of partner data must also be observed during the import.

Importing a new partner

Preconditions

• The destination system does not yet contain any partners with the corresponding key

The business key is the attribute number for the Partner object. The primary key is the GUID technical identifier.

• A filter is available for the business object cisag.app.general.obj.Partner which contains attributes to be imported

Instructions

Perform the steps as described in the chapter Importing data. Data import can then be performed immediately or as a batch job. The system determines the time at which these processes start and initiates them. The user cannot influence the start time.

Importing a new partner role

Preconditions

• The destination system already contains a partner with the corresponding key. That is, the base data has already been imported.
• A filter is available for the business entity cisag.app.general.obj.Partner which contains attributes to be imported
• The data of the role to be imported relates to the organization of the active OLTP client (except employees and financials)

Instructions

1. Generate an import file that contains at least a partner number (partner code) and the data of the role to be imported. If the role also contains the organizationalUnit attribute, the field must always be filled in (this also applies to single-site environments).

2. Ensure that all required fields of the role to be imported (see section Identification fields and required fields) are specified

3. Perform the steps as described in the chapter Importing data

Importing a partner role for a subordinate organization

Preconditions

• The system is a multi-site environment
• The destination system already contains a partner with the corresponding key. That is, the base data has already been imported.
• A filter is available for the business entity cisag.app.general.obj.Partner which contains attributes to be imported
• Before starting the import, ensure that data for the corresponding role/view of the Partners application already exists

Instructions

1. Generate an import file that contains at least a partner number (partner code) and the data of the role (view in the Partners application) to be imported and its key (organizationalUnit)

2. Ensure that all required fields of the view/role to be imported (see section Identification fields and required fields) are specified

3. Perform the steps as described in the chapter Importing data

Importing an inherited structure

Preconditions

• The system is a multi-site environment or content-based authorizations are active
• The organization that is to inherit the data must be authorized for this role
• The organization must be a subordinate organization
• The destination system already contains a partner with the corresponding key. That is, the base data has already been imported.
• At the level of the organization, data must already exist for the corresponding role from which the destination organization is to inherit the data
• A filter is available for the business entity cisag.app.general.obj.Partner which contains attributes to be imported

Instructions

1. Generate an import file that contains at least a partner number (partner code) and the identification attribute

2. The inherited structure of the roles is defined in the OrganizationalUnitPartner business object. Each role having an inherited structure has a reference attribute in this business object:

In the reference attribute for the corresponding role, enter the organization from which the destination organization is to inherit data.

3. Make sure that the subordinate organization is also authorized to inherit data for the role to be imported.

4. Perform the steps as described in the chapter Importing data

Change via import

The import function allows the user to easily make changes to partners. For example, if the user wants to set the credit limit to a new value for all accounts receivables, this is also possible via an import operation.

Instructions

Generate a filter that contains a partner number, the key attribute of the role, and the fields to be changed. Then, export the corresponding partners, e.g. in CSV format. Change the relevant field in the file created. Then, import the file again with the generated filter.

The following example will change the credit limit to 50,000.

Deleting partners or roles

An import operation can also be used to flag existing partners or individual roles for deletion. Likewise, it is also possible to remove a deletion marker in this manner. Import has the same effect as pressing the [Mark for deletion] button in the Partners application.

To set a deletion marker, the corresponding business object is imported in the Delete mode. Likewise, the corresponding business object must be imported in the Delete mode in order to remove an existing deletion marker again.

This mode can only be set in XML format. More information may be found in the article Introduction: Data exchange.

Import with CSV files

With CSV files, it is also possible to import multiple data, such as multiple roles and organizations, in one import run. For reasons of import speed, it is recommended to import as much information as possible in the first import operation.

The files should have the following structure:

1. The main file contains all information of the required base data

2. A subsequent file contains communication data

3. A subsequent file contains financials data

4. A subsequent file contains customer data

In this file, it is important that the first line with a partner number contain data for the active OLTP client organization.

5. Additional files could then contain data for additional roles (views)

It is important here that the sequence of partners in the individual files correspond to the sequence of partners in the main file. Individual partner numbers can be omitted if a partner is not assigned to a role. To import this data in one import operation, references must be defined. Partner numbers not contained in the main file must not be specified in the referenced files.

References of files

Instructions: Data import with references of files

1. Open the Import data application

2. Select the filter for the com.cisag.app.general.obj.Partner business object

3. Selected filter attributes will be activated. If required, it is possible to further adjust attributes.

4. Click the [Import data] button in the standard toolbar

5. The Import data dialog window will open. The window makes it possible to adjust import file settings.

6. Click the [Create links…] button

8. Specify the object path, the source file in the KStore repository and the referencing attribute

9. After the [Accept] button is selected, the system opens a window where it is necessary to select a processing queue

10. To start the file import, click the [In background] button

Examples

The structure of the base data file and the additional files is described below.

Base data file

Communication data file

The 4712 file contains no communication data.

Financials data file

Customer data file

Supplier data file

All these files can be transferred in one import operation. The base data file is the main file. The other files are linked by means of references.

Bank details file

A bank details file can be imported afterwards in a further import operation.

In this case, the import is performed without references and the bank details file is the main file. It must be noted here that the bank details – as in the case of tax information (PartnerTaxIdentification) – are saved independent of the organization. However, they must be embedded in an organization-dependent PartnerAccountingData object.

Employee data file

In this case, the user should work with a reference again. The main file is a file that contains the base data of the employees. This file is referenced with the employee data file.

Contact partner relationships in the base view

In this case, additional partners will also be referenced. For this reason, it is appropriate to import this file in an additional import operation.

Contact partner relationships in the Customer view

Additional partners will be referenced in this case, as well. For this reason, it is appropriate to import this file in an additional import operation.

Example of importing the inherited structure of the Supplier role

In this example, partner 4715 in Purchasing organization 1 inherits the supplier data of the active OLTP client. Partner 4716 inherits the data of Purchasing organization 1 in Purchasing organization 2. This requires that partner 4715 be the supplier at the active OLTP client level and that partner 4716 maintain the supplier data itself in Purchasing organization 1 and that Purchasing organization 2 be a lower-level organization of Purchasing organization 1.

Identification fields and required fields

The required fields and key attributes (K) of the individual business objects are listed below. The identification fields and required fields are subject to changes and can also be expanded by partner adaptations.

Base data

Required field/Key attribute (K)

• number (K) – partner number
• human – flag indicating whether the partner is a person
• searchString – partner search string (it can also remain empty, in which case it is formed automatically)
• MaintainingOrganization – organization responsible (this attribute is only required for a multi-site environment or if content-based authorizations are active)
• Language – correspondence language
• type – affiliation
• surname – surname for persons
• gender – gender for persons
• name[0] – name 1 for organizations
• type – organization category
• postalCode – PLZ, required field status is dependent
• city – city
• country – country

Communication details

Required field/Key attribute (K)

• number (K) – partner number
• commData (K) – communication data (phone number, fax number, etc.)
• preferred – preferred communication data
• Method – communication method

Financials data

Required field/Key attribute (K)

• number (K) – partner number
• OrganizationalUnit(K) – organization
• TaxResidence – tax municipality
• birthDate – date of birth
• PaymentReason – payment reason

Required field/Key attribute (K)

Accounts receivable

• outputTaxClassification – VAT classification
• receivablesPartner – A/R account; the field is only required if the Financials function is activated in the Customizing application
• receivablesTemplate – account template of the accounts receivable; the field is only required if the Financials function is activated in the Customizing application
• creditLimit.amount – amount of the credit limit
• creditLimit.Currency – currency of the credit limit
• debtor – accounts receivable
• SalesCurrency – currency of the accounts receivable
• TaxRegister – tax register of the accounts receivable
• SalesPaymentTerms – payment term of the accounts receivable

Accounts payable

• outputTaxClassification – input tax classification
• payablesPartner – A/P account; the field is only required if the Financials function is activated in the Customizing application
• payablesTemplate – account template of the accounts payable; the field is only required if the Financials function is activated in the Customizing application
• creditor – accounts payable
• PurchasingCurrency – currency of the accounts payable
• TaxRegisterCreditor – tax register of the accounts payable
• PurchasingPaymentTerms – payment term of the accounts payable

Tax identification

VAT Id and Codice fiscale are managed in a separate business object. This business object is dependent on the organization, and the fields are not required fields. For the import, however, integration into one organization-based attribute (PartnerAccountingData) is required.

Required field/Key attribute (K)

• number (K) – partner number
• OrganizationalUnit(K) – organization
• PartnerTaxIdentification.taxIdentificationNumber – VAT identification
• PartnerTaxIdentification.localTaxIdentificationNumber – tax no.

The specification of the organization is only required in a multi-site environment. If the organization is not specified in a single-site environment, the organization is set to that of the active OLTP client.

Bank details

Required field/Key attribute (K)

• number (K) – partner number
• OrganizationalUnit (K) – organization
• BankAssignment.bank.country (K) – country
• BankAssignment.bank.code (K) – bank routing number
• BankAssignment.BankBranch (K) – bank branch
• BankAssignment.bankAccount (K) – account number
• BankAssignment.preferred – preferred bank assignment

The specification of the organization is only required in a multi-site environment. If the organization is not specified in a single-site environment, the organization is set to that of the active OLTP client.

Suppliers

Required field/Key attribute (K)

• number (K) – partner number
• OrganizationalUnit(K) – organization
• classification1 – classification 1
• deliveryDataInfo.DeliveryTerms – delivery term

The specification of the organization is only required in a multi-site environment. If the organization is not specified in a single-site environment, the organization is set to that of the active OLTP client.

Customers

Required field/Key attribute (K)

• number (K) – partner number
• OrganizationalUnit(K) – organization
• classification1 – classification 1
• deliveryDataInfo.DeliveryTerms – delivery term

Marketing

Required field/Key attribute (K)

• number (K) – partner number
• OrganizationalUnit (K) – organization

Employee

Required field/Key attribute (K)

• number (K) – partner number
• PartnerRelations.preferred – preferred (employer relationship)
• PartnerRelations.SourceOrganizationalUnit – organization
• PartnerRelations.Target – employee
• PartnerRelations.Type – relationship category, must always be of the Employee type

Partner organizational unit

Required field/Key attribute (K)

• number (K) – partner number
• OrganizationalUnit (K) – organization