Documentation Home

API Import

The API import is the same format as the CSV file import through the admin with the CSV portion of the request sent in the
body. The import endpoint is available at /api/import so if you have the admin application deployed as admin.war the
full url is /admin/api/import. Below is a high-level overview of how the endpoint works:

/api/import/{ceilingClass}, POST

URI Parameters

  • ceilingClass - the fully-qualified Java class name of the import. Examples:
    • Product import - org.broadleafcommerce.core.catalog.domain.Product
    • Category import - org.broadleafcommerce.core.catalog.domain.Category
    • Bulk asset upload - org.broadleafcommerce.cms.file.domain.StaticAsset

Request Parameters

  • sandboxId - optional, allows importing into a particular sandbox. If not specific the import goes straight to production
  • spec - defaults to CSV. Currently supports CSV or ASSET_UPLOAD

Request Headers

  • catalog - the ID of the catalog that the items should be imported into
  • site - the ID of the site that the items should be imported into

Request Body

If executing a CSV-based import, the request body should be the CSV data to be imported. If executing a bulk asset upload
then the request body should be the .zip file containing the assets.

Response

The response is a JSON object representing the scheduled ImportStatus that also includes the status URL representing where
you should poll to determine the status of the import. Example:

{
  "status": "SCHEDULED",
  "createdDate": "2017.01.11 07:22:30",
  "totalRecords": 33,
  "totalProcessed": 0,
  "totalRemaining": 33,
  "statusId": 6,
  "statusUrl": "/admin/api/import/status/6",
}

/api/import/{statusId}, GET

URI Parameters

  • statusId - the primary key of the import status you are trying to retrieve

Response

The response is a JSON object representing the scheduled ImportStatus. Example:

{
  "status": "IN_PROCESS",
  "createdDate": "2017.01.11 07:22:30",
  "totalRecords": 33,
  "totalProcessed": 15,
  "totalRemaining": 18,
  "lastUpdateDate": "2017.01.11 07:22:50",
  "statusId": 6
}

If the import has completed, you would see something like this:

{
  "status": "COMPLETED",
  "createdDate": "2017.01.11 07:22:30",
  "totalRecords": 33,
  "totalProcessed": 33,
  "totalRemaining": 0,
  "lastUpdateDate": "2017.01.11 07:22:50",
  "statusId": 6
}

If there were errors, those come as apart of the details array inside the returned JSON:

{
  "status": "COMPLETED",
  "createdDate": "2017.01.11 07:22:30",
  "totalRecords": 33,
  "totalProcessed": 33,
  "totalRemaining": 0,
  "lastUpdateDate": "2017.01.11 07:22:50",
  "statusId": 6
}

Example Requests

  • Import 2 products into the -1 catalog and the -1 site:

    curl -X POST -H "Accept: application/json" -H "catalog: -1" -H "site: -1" -d 'name,Url,defaultCategory,retailPrice,Primary Image
Product 2,/product2,2001,11.99,/cmsstatic.primary2.png
Product 3,/product3,2001,12.99,/cmsstatic.primary3.png' "http://test.blc.dev:8081/admin/api/import/org.broadleafcommerce.core.catalog.domain.Product"

  • Import 2 products into the catalog and site resolved by the current URL (undergoes the same site domain matching as other multi-tenant functionality):

    curl -X POST -H "Accept: application/json" -d 'name,Url,defaultCategory,retailPrice,Primary Image
Product 2,/product2,2001,11.99,/cmsstatic.primary2.png
Product 3,/product3,2001,12.99,/cmsstatic.primary3.png' "http://test.blc.dev:8081/admin/api/import/org.broadleafcommerce.core.catalog.domain.Product"

API Security

Security in the admin can be done a number of ways with Spring Security. The easiest implementation of this is to use HTTP Basic security
and the existing blAdminAuthenticationManager. In order to enable this, we recommend creating a new API Admin User that
has all the same roles and permissions as the global super user. This serves 2 purposes:

  1. Ensures that your API user can performa all operations and will not be blocked by the admin security services
  2. Allows you to track changes that were performed by this separate admin user, for instance if you are importing into a sandbox

To enable admin security with HTTP basic auth, add the following to applicationContext-admin-security.xml:

<sec:http pattern="/api/**" create-session="stateless" authentication-manager-ref="blAdminAuthenticationManager">
    <sec:http-basic />
    <sec:custom-filter ref="blAdminRestPreSecurityFilterChain" before="CHANNEL_FILTER"/>
    <sec:custom-filter ref="blAdminRestPostSecurityFilterChain" after="SWITCH_USER_FILTER"/>
</sec:http>

Then add the following to applicationContext-admin-filter.xml:

<bean id="blAdminRestPreSecurityFilterChain" class="org.springframework.security.web.FilterChainProxy">
    <sec:filter-chain-map request-matcher="ant">
        <sec:filter-chain pattern="/**" filters="
           openEntityManagerInViewFilter,
           blMultiTenantAdminRequestFilter"/>
    </sec:filter-chain-map>
</bean>

<bean id="blAdminRestPostSecurityFilterChain" class="org.springframework.security.web.FilterChainProxy">
    <sec:filter-chain-map request-matcher="ant">
        <sec:filter-chain pattern="/**" filters="
           resourceUrlEncodingFilter,
           blAdminRequestFilter,
           hiddenHttpMethodFilter,
           blLog4jMappedDiagnosticContextFilter"/>
    </sec:filter-chain-map>
</bean>

If you are not using multi tenant, remove the blMultiTenantAdminRequestFilter bean id