CSV Operators

ℹ️ Info: While it is possible to provide a CSV file to a user, for the automated process, the recommended way is still to use the API.

In some cases you may not want to query the API on behalf of the user. For example if they do not provide your with their api credentials. In that case you can create a CSV file with the receiver information and a path to the file.

Companies can send mail as bulk via a SFTP connection to a server. More Connectors will be added in the future.

Nevertheless, by using the API more metadata can be added to the mail.

This Operator will generate a CSV file with a HMAC (HmacSHA256) for row validation. It does not provide to check for the deletion for rows. It will only check if the rows are tampered with or if an additional row is added.

The following Receiver Types are supported:

• CsvBirthInformationRecord(external_id, first name, last name, birth date, birth place, path)
• CsvEmailRecord (external_id, email, name, birth date, path)
• CsvTelRecord (external_id, phone number, name, birth date, path)

The external_id can be the employee number or any other unique identifier. It is used only by the creator of the CSV file.

Create CSV File

You can create a CSV file with the following code:

// when no mac key is provided, the operator will generate one
CsvOperator<CsvBirthInformationRecord> csvOperator = new CsvOperator<>(CsvBirthInformationRecord.class);
// retrieve the generated mac key
String macKey = csvOperator.getMacKey();
assert macKey != null;

// test ressource folder    
String path = "/output.csv";


List<CsvBirthInformationRecord> records = List.of(
        CsvBirthInformationRecord.builder()
                .withExternalId("1")
                .withFirstName("Max")
                .withLastName("Mustermann")
                .withBirthDate("1998-04-02")
                .withBirthPlace("Musterstadt")                       
                .withPath("file1")  // when using SFTP paths, use the absolute path starting with /
                .build(),
        CsvBirthInformationRecord.builder()
                .withExternalId("2")
                .withFirstName("Maxine")
                .withLastName("Musterfrau")
                .withBirthDate("2000-01-01")
                .withBirthPlace("Musterstadt")
                .withPath("file2")
                .build()
);

File res = csvOperator.writeCsvFile(path,records);

assert res.exists();

Each generated CSV file will have a unique MAC key. This key is used to verify the integrity of the file. The key is generated by the CsvOperator class and can be retrieved by calling the getMacKey() method.

Example Output:

Mac Key: 5F2D235813DBDF424CF3FFF48DD60CF611060A0CCDEB7CE52C09EB9C799B995B

__HMAC__,external_id,first_name,last_name,birth_date,birth_place,path
B9A7689949B9E9B3451C019BA9D2AD0474198CF50D0748D2F0F5FCAFDB8565C5,1,Max,Mustermann,1998-04-02,Musterstadt,file1
E57DAAF592CEC191C4E3CF78EA7B0D16C2C38CB4FAF8C448C85E55B6340908BC,2,Maxine,Musterfrau,2000-01-01,Musterstadt,file2

Read CSV File

When you want to read a File and validate with the MAC key, you can use the following code:

// specify the mac key for row validation
String macKey = "E1485697814619123D96743F04CE44BAA16FDB37996E5F502A30448739C9F3DF";
CsvOperator<CsvBirthInformationRecord> csvOperator = new CsvOperator<>(CsvBirthInformationRecord.class,macKey);
// read the file
String path = this.getClass().getClassLoader().getResource("expected.csv").getPath();
try {
    List< CsvBirthInformationRecord> res = csvOperator.readCsvFile(path);
    // row check, it will remove the header line of the csv file
    assert res.size() == 2;
} catch (HMacValidationFailedException e) {
    // if the MAC key is not valid, or the file is tampered with, this exception will be thrown
} catch (HMacHeaderMissingException e) {
    // if the MAC header is missing, if the mac is set null or to an empty string, this exception will not be thrown
}