Importing Customer Segments

In broadleaf it is possible to import CustomerCustomerSegmentXref's using both the admin interface and an API.

Activation

Admin Application

The admin based CSV import is enabled by default when the Import module is part of the project.

The API based import endpoints are disabled by default and can be enabled using @EnableFrameworkRestControllers in a servlet @Configuration class. Note that this will enable all framework API endpoints in the application. Please see the Full Framework Controller Documentation for more information.

Integration Application

If you are writing a custom integration application and would like to include this endpoint, you must explicitly define it as a bean using JavaConfig or XML configuration as so:

JavaConfig

@Configuration
public class MyIntegrationConfiguration {
    @Bean
    public AdminCustomerSegmentImportEndpoint adminCustomerSegmentImportEndpoint() {
        return new AdminCustomerSegmentImportEndpoint();
    }
}

XML

<beans>
    <bean class="com.broadleafcommerce.customersegment.admin.web.api.endpoint.AdminCustomerSegmentImportEndpoint" />
</beans>

Via the Admin

In order to import customer segments in the admin, navigate to the customer care section on the left side navbar. Click the Customer Segments link to navigate to the main customer segments page. From there select the drop down selector in the top right of the header and choose Import Customer Segments. A popup window will display. From there, select the file type of the file you're uploading. Next click the Choose File button which will prompt you to pick the file you want to import from your computer. Accept your choice and finally click upload. After the file has been uploaded, a job will be scheduled to handle the import in a separate thread.

Modifying Customer Segments via export and imports

To export the current customer segments use the same instructions as noted above but instead of clicking Import Customer Segments, click Export Customer Segments. After the prompt is shown, choose the format you would like the export in and click the Shareable check box if this export should be available to be downloaded by other admin users that have read permission for customer segments. After clicking Export navigate to the settings tab (the cog, generally located at the bottom) on the left-hand navbar. In the menu that opens, click the My Exports option. On this page you can click the link to your export and it will be downloaded to your browser.

Then you can edit the export file however you'd like and save the modified file. This file can now be re-imported into the admin in order to update the records. To do so follow the instructions from above.

Via the REST API

First the admin has to be setup to accept REST calls without the normal Spring security and CSRF filters. To do so please reference the api setup for imports.

In order to actually hit the api refer to the AdminCustomerSegmentImportEndpoint class for the urls, but, by default, the url is /admin/api/import/customer-segment?importType={import_type} where import_type is the file type of the file that you are uploading. By default the import type is CSV. Make sure that the request is a POST and is sent with basic authentication credentials for an active admin user. Lastly send the file you wish to upload as the body of the request. On a successful request the endpoint will return a 200 status code with no body.

It is also possible to import identifier values into a specific Customer Segment by specifying the Customer Segment id or name in the url, such as /admin/api/import/customer-segment/id/{id}?importType={import_type} or /admin/api/import/customer-segment/name/{name}?importType={import_type}

Out of box import format

Each row in the CSV represents a CustomerCustomerSegmentXref. As noted previously any fields can be added to the import file as long as the properties exist on CustomerCustomerSegmentXref or an extension of CustomerCustomerSegmentXref. By default the following fields are needed:

identifierType,identifierValue,name
EMAIL,bob@bob.com,TEST SEGMENT 1
EMAIL,jane@jane.com,TEST SEGMENT 2
EMAIL,abc@abc.com,TEST SEGMENT 3

If no id's are provided, each row will be treated as an add. For updates the id of the CustomerCustomerSegmentXref needs to be provided as well. i.e.

id,identifierType,identifierValue,name
1,EMAIL,bob@bob.com,TEST SEGMENT 1
2,EMAIL,jane@jane.com,TEST SEGMENT 2
3,EMAIL,abc@abc.com,TEST SEGMENT 3

By default, exporting customer segments from broadleaf will give the above format.

Before the import jobs attempts to persist a CustomerCustomerSegmentXref, it will lookup the CustomerSegment using the name. If one is not found, it will create a new CustomerSegment with the given name, and it will default the values of the other fields on the CustomerSegment. This creates 2 restrictions. First, CustomerSegment names must be unique within in each site. Second, any additional values provided for CustomerSegment will not used for an add or an update, the only value that will be used is the name, all others will be defaulted.

Archiving Records

All import files also support archiving segments. Assuming that these records exist, this archives 'bob@bob.com' and 'abc@abc.com' and unarchives previously-archived 'jane@jane.com' :

id,identifierType,identifierValue,name,archived
1,EMAIL,bob@bob.com,TEST SEGMENT 1,Y
2,EMAIL,jane@jane.com,TEST SEGMENT 2,N
3,EMAIL,abc@abc.com,TEST SEGMENT 3,Y

Importing into a specific Customer Segment

Broadleaf provides the ability to import identifier values into a single Customer Segment. This can be accessed in the admin by navigating to the details page of a specific Customer Segment. From there, if the Customer Segment is of type Customer Set, then there will be a Import Segments button on the targeted customer listgrid. When you click the button, you will prompted with a popup window that is similar to the one that is displayed for the other Customer Segment import.

Since you are importing to a specific customer segment, there is no need to specify all of the values that are required for a regular customer segment import. The only values that need to be specified are the identifier values that you wish to import for the customer segment, example:

identifierValue
bob@bob.com
jane@jane.com
bill@bill.com
jim@jim.com