Imports
|
|
You can import data from a system or Excel lists into your Umantis solution by applying the most efficient method and using the appropriate templates for the import. Another option here is to set up an automatic import. Under the Imports tab, you can access the imports overview as an administrator (Applicant Management). Employee Management also allows you to do imports using the Imports module role.
Procedure during an import
- The data format used for your data is crucial in determining the type of import (Excel or XML). Select the appropriate template, save it, and enter your data. A new row should be selected for each entry. The example row should not be used as this is not imported.
- In the Umantis solution, navigate to the Imports tab and select the corresponding action for the import (identical to the above section assignment for the templates)
- You can then define a title for the import in this window and upload the completed template.
- Various Import settings can also be defined.
- Click on “Start import” to begin the import process.
- A status report window informs you of the import’s current status.
- A confirmation message is displayed when the import is complete.
- The data can now be found at the relevant target location as usual.
If a record cannot be imported, check the import for errors in the log file (search for “Error”) and re-import the record after correcting it.
Detailed information on the import process and status information during the process can be found under Run import.
Important notes:
- Importing organizational units: If organizational units (use the “Selection list” template) are to be imported, proceed as follows: Import the organizational units first using the templates, then check the solution whether they have been imported correctly (focus on the connections with the individual organizational units, which can be found under: Basic settings -> Selection lists -> Organizational units) and import the relevant employees affected by this change (including their organizational unit and access rights).
- For user-defined fields, the column name may be changed in the template, provided that the name has also been changed accordingly in the solution. Never change the variables in the templates, however, as this will prevent the import from working.
- You can use the import to assign a manager to each person. To do this, enter the details you activated for the manager (employee ID, position ID, external system abbreviation) into the corresponding column for each subordinate employee.
- The following presentation provides a description of the import logic, and especially of the interaction of import keys for unique identification of the imported employees, persons, positions or organizational units: Help with using the import keys. The import keys can be alphanumeric and, ideally, should not include any spaces. Leading zeros are not suitable for purely numeric import keys.
- You can compress all your import files using gzip https://en.wikipedia.org/wiki/Gzip gzip'’. This is especially helpful for large import files: Compressing a file reduces the amount of digital data needed to represent it, which in turn reduces the necessary storage space and file transfer time. We recommend that you compress XML files using gzip , since this file type works especially well with compression techniques.
Run import — Options
There are various options available to you when creating a new import, which are explained below.
The import process can also be tracked using system feedback.
Partial imports vs. full imports
Partial imports and full imports differ only in that the full import historizes the remaining data (which has not been sent in the import) after importing the data that is passed in the import file. Historization is only performed within the same source system.
Same source system
| Explanation of Figure 1: Full vs. partial import from the same source system |
|---|
|
If a full import is performed with data within the same source system, the process is as follows:
If a partial import is performed with data within thesame source system, the existing data are updated and supplemented; however, the already existing data will not be historized. |
From different source systems
| Explanation of Figure 2: Introduction |
|---|
|
Data is to be imported into two source systems and the Umantis solution.
|
Full import
| Explanation of Figure 3: Full import with different source systems |
|---|
|
A full import with data from different source systems can be demonstrated briefly using an example:
|
Partial import
| Explanation of Figure 4: Partial import with different source systems |
|---|
|
A partial import with data from different source systems can be demonstrated briefly using an example:
|
Notes:
For selection lists 66 (organizational units) and 67 (matrix organizational units), the import works the same way with regard to partial vs. full imports as when importing employees. The system automatically aggregates a consolidated list of the imported entries from different source systems.
Delta import vs. Import all data
Since 11/2023, the delta import is also available as standard for user imports in Umantis Applicant Management. It cannot be deactivated for automatic imports.
Alongside the distinction between Full import and Partial import a separate distinction is also made as to whether all data is to be imported or only data that differs from the last import (delta import). If the option to Import all records from the file is selected, all data will imported, regardless of the last import. If this option is selected, the import will take considerably longer than a delta import, because all records are processed, even if a record has not changed since the previous import. With the delta import , on the other hand, a check is run before importing to determine which data have changed relative to the last import, and only then only those data are imported. For the purposes of this comparison, the current import file is compared with the one from the previous import.
| Explanation of Figure 5: Delta import vs. Import all data |
|---|
|
The delta import compares the data to be imported with those from the last import, and only updates the data for which differences are found. The remaining entries are retained 1:1. However, if all data is imported, the entire record is processed. |
Notes:
- Delta import cannot be deactivated for automatic import
- In the import, the record is not compared with the current version in the database, but with the state of the previous import (import file). This comparison also works in cases where you are switching between partial and full imports.
- If a record cannot be imported, check the import for errors in the log file (search for “Error”) and re-import the record after correcting it. In this case, you should also select the option to “Import all records in the file”.
- The delta import', i.e. the import in which only those data records are imported that have changed since the last import, is used in Applicant Management only for the "user import" and in Employee Management only for the "employee" and "job import" as well as for the import of the selection list "66" and "67" (organizational units) with code per organizational unit. For all other imports, all data records are always imported from the file.
- The delta import is a performance optimization.
Other import options
- Import notification: When an import finishes unsuccessfully (incomplete import), a message with the import status is sent to the email address specified in the organizational profile.
Specify date format for imports
Specify the date format for imports of records that contain date information. You can use the following variables for this:
- Datum.Format
- With this variable, specify the output format for each record (each line of your Excel template):
- D/M/YYYY
- D.M.YYYY
- M/D/YYYY
- M.D.YYYY
If you do not explicitly define a specific date format, then the following date format is used: D.M.YYYY
- DatumZeit.Format
- With this variable, specify the output format for each record (each line of your Excel template):
- D/M/YYYY hh:mm
- D.M.YYYY hh:mm
- M/D/YYYY hh:mm
- M.D.YYYY hh:mm
If you do not explicitly define a specific date/time format, then the following format is used: D.M.YYYY hh:mm
Status information during the import
Continuous status information is displayed during the import. Refresh your browser to receive the most recent information on the current import status. The following messages can be displayed:
- Import file uploaded
- The file was received -> OK/Error
- ZIP file uploaded
- The second file with the possible files (e.g. photos) was received -> OK/Error
- Processing
- The processing engine is operational -> OK/Error
- Import file checked
- The file meets the basic requirements for the selected import type (e.g. file type) -> OK/Error
- ZIP file checked
- The second file meets the basic requirements for the selected import type (e.g. file type) -> OK/Error
- ZIP file extracted
- The ZIP archive was successfully extracted -> OK/Error
- Number of entries
- This number of entries was found in the import file for processing -> (Number of entries)
- Import all records from the file
- For employees, only the delta relative to the previous import is typically written in the system (see Options). Has this Delta function been deactivated, despite the considerably longer processing time? -> yes/no
- Number of changed entries in the import
- Number of records that were changed since the previous import or are new -> (Number of entries)
- Process entries
- Number of entries that were prepared for import. -> OK (Number of entries)
- Write entries
- Number of entries that were written. If you see a difference here compared with “Process entries”, check the log. Progress in % -> OK (Number of entries)
- Entries not fully imported
- Number of entries that were not imported. You should consult the log file.
- Reorganize access permissions to OUs
- Only applicable when importing selection lists 66 and 67 organizational units (OU) and matrix OU. If the OU structure was changed, employee authorizations need to be re-configured. This is a very time-consuming process if there is a large number of employees.
No special template is provided for a reorganization, since it cannot be predicted how the reorganization of employees will affect the import structure. In addition to the usual variables, the following can be used specifically in the case of a reorganization: [Quellsystem.NeuerSchluessel], [Person.NeuerSchluessel] and [Stelle.NeuerSchluessel]. After finding existing employees (using existing keys), these variables are used to “convert” the existing keys to the new ones. Please note that this process should be used with caution, and that any template you used can only be used once, since using it again will generate a duplicate.
- Terminate
- Entries that were not fully imported are deleted again and, in the case of a full import, non-imported entries from the same source system are historized.
- Log
- Documentation of the entire import process
Third-party systems can be isolated from one another using source system keys. For example, if you define a different source system key for each import, automatic archiving of non-imported employees or organizational units is only performed within the same source system. For example, this detects overlapping identical PersonKeys, and the employees and their jobs continue to be uniquely identifiable for import.
Deletion of outdated imports
Please note that imports older than one year are automatically deleted from the system.
Importing documents and photos
Importing documents and photos is possible in both Employee and Applicant Management.
To import documents and photos, use the designated columns in the respective import template (Example: Person.Foto or Bewerbung.DokumentLebenslauf, as shown in Figure 6).
The import templates can be expanded as needed with other variables (from “Bewerbung.DokumentWeiteres2” to “Bewerbung.DokumentWeiteres14”).
Save all documents that you would like to upload into the solution into a folder as per Figure 7, and convert it into a ZIP archive folder. It is important that the folder structure is laid out schematically, i.e. the folder names are identical to the variables and the document names are identical to the entry in the cell for the respective variable in the template. Proceed as follows:
- Create a folder with the same name as the variable in the import template (e.g. a variable in the template is called “Person.Foto” -> the name of the folder is identical and with square brackets, i.e. [Person.Foto]) and add all similar documents to be imported into this folder.
- Then fill in the corresponding column for each person with the associated document name (as shown in Figure 7, e.g. for Brad Pitt, enter “Foto_Brad_Pitt.jpg” for the “Person.Foto” variable).
- If you would like to import additional documents (e.g. for the Bewerbung.DokumentLebenslauf variable), simply repeat the procedure above.
- Once you have created all folders in this way, join them into a single ZIP-compressed folder. You can choose any name you like for the ZIP folder.
- Next, navigate to the associated import window in the solution; there, you will not only select the completed template for the import, but also upload the ZIP file you have just created.
- The import can now be run as usual.
In order for the import to work smoothly, you may need to rewrite umlauts (ä,ö,ü) or letters with accents (e.g. Á or Å) in the document names in ae, oe, ue or A. When exporting documents from a legacy system, for example, these letters are often output as HTML codes in the document name. In order to import these again, it may be necessary to make transcriptions.
Notes:
A few requirements for the ZIP archive folder:
- The ZIP archive must be created as a .zip file (e.g. the.rar format will not work)
- The ZIP archive may not be larger than 125 MB.
- Tip for creating the ZIP folder: Select the desired variables folder, right-click and select “Send to”, then click on “Compressed (zipped) folder”. This creates the ZIP folder automatically.
Common log file errors — Tips & tricks
If an import appears to be incomplete, check the log file stored in the solution for errors. Open it directly in your browser. Then search for the word “Error” in the log file to identify the source of the error. The list below can help you in this process.
- Login already exists:
- If the log file shows this error, it means that the login is already saved in the solution. It could be the same person with a different user ID.
- Value does not exist in selection list XY:
- This error message indicates that the given entry does not exist in the selection list stored in your Umantis solution. Accordingly, you need to make adjustments to the list in the solution, or modify the entry and then re-start the import.
- Organizational unit does not exist:
- This error indicates that an organizational unit is missing. Supplement the selection list in the solution or change your entry of the organizational unit.
- Value is missing in a fixed list:
- The entry to be imported is not part of the fixed list. Adjust the entry in the import file so that it corresponds to the entries of the fixed lists in the solution.
- Incorrect XML structure:
- The “parser error” means that the XML contains errors, and that the import therefore cannot be performed. In the example shown here, for instance, the closing tag </Record>(PARAMID-LOOP-END) is missing.</Category></Import>
Other error messages during import
This is a list of error messages that may occur during import:
- Parser error: opening and ending tag mismatch
- Reason: Field end missing
- OU not found: ERROR: SearchValue: ID not found in list 66 of customer CUSTOMERID
- Reason: OU not available in list 66
- List: ERROR: SearchValue: ID not found in list 12 of customer CUSTOMERID
- Reason: Selection list value missing
- Fixed lists: ERROR: Matching code (fixed lists) could not be found...
- Reason: Incorrect value -> fixed list
- Login: Error setting login name ... Login name already exists.
- Reason: Username already assigned
- OU value: (Split) SearchValue: ID not found in list 66 of customer CUSTOMERID
- Reason: An OU (Organizational unit) is not available in selection list 66
- Parser error: Starting Import...----import died, reason: run/import/upload/2014040...xml: parser error:
- Premature end of data in tag Record line...
- Premature end of data in tag Category line...
- Premature end of data in tag Import line...
- Reason: Closure missing (was cut off):
- </Record>
- </Category>
- </Import>