Overview

Since PIM 7.1.01

PIM Supplier Portal comes with a http-based remote API. This API can be used to remotely trigger functionality or to retrieve supplier related data. This API is complete in the sense of that every feature that is available in the Browser UI can also be accessed over the Remote API.

In contrast to the Supplier Portal REST API the application protocol of the API is proprietary (defined by the GWT Request Factory). Hence, clients should use a wrapper library that takes care of assembling http requests and parsing the http responses.

Authentication & Security

All communication is http based. User credentials are transferred within http post requests. Hence, all communication should be encrypted using SSL over https in production scenarios.

Authentication is done the same way as for the Browser-based UI. That means, that after successful authentication of valid user credentials a sessionId is generated and can be used for all subsequent requests. Because of that, explicit logout is required by clients. Also the configured http session time-out needs to be considered after a longer time of inactivity.

Both user types PIM portal administrators as well as supplier user can be used for authentication.

For localization the Accept-Language http header is used to request information using a specific language. If omitted, the server default locale will be used. This affects some localized data, e.g. when fetching the timeline for a user.

Getting Started

The Java Client for the Remote API and a sample project are available on request from Product Management.

The sample application shows how to implement a batch import for an existing supplier user database from an CSV file.
The sample project "com.heiler.hsp.custom.supplierimport" is available in the SDK package.
The source code itself is rather self explanatory, most communication with the PIM Supplier Portal happens in the class SupplierService.

images/download/attachments/312815814/supplierImportSampleProject.PNG

Note that the Remote API alone is not enough to get the sample running, since the Remote API is built on top of the GWT Request Factory.
Thus, additional dependent libraries are needed. These reside in the lib folder of the sample project.
Although there are already Remote Api jars api-<version>-SNAPSHOT.jar inside this folder, please always use the Remote Api jars provided to you by the Product Management that fit to your Supplier Portal version.
Keep all this in mind when setting up own projects using the Remote Api.

Sample Code - Create new supplier

This example shows how to create a new supplier organization with a supplier administrator user:

    // Login with a PIM portal administrator user
    FactoryHelper helper = new FactoryHelper( "http://localhost:9090/hsx" );
    helper.login( "portal", "portal" );
    
    // Create a factory and context to assemble a http request
    UserRequestFactory factory = helper.create( UserRequestFactory.class );
    UserRequestContext context = factory.context();
    
    // Create a supplier entity and set attributes
    OrganizationProxy supplier = context.create( OrganizationProxy.class );
    supplier.setName( "New Supplier" );
    supplier.setActive( true );
    supplier.setAutoImportConfiguration( AutoImportConfig.AUTO_IMPORT_NO_WARNINGS );
    
    // Create a supplier user, link with supplier and set attributes
    UserProxy user = context.create( UserProxy.class );
    supplier.setUsers( Arrays.asList( user ) );
    user.setEmail( "admin@suppliertest.com" );
    user.setFirstName( "Mister" );
    user.setLastName( "Administrator" );
    user.setStateAsString( UserProxy.STATE.ACTIVE );
    
    // Send the requests synchronously
    UserProxy savedUser = FactoryHelper.fire( context.saveWithPassword( user, "secret123" ) );
    
    // Handle the result. Supplier user and supplier are persisted now.
    System.out.println(savedUser);
    
    // Logout PIM portal administrator user
    helper.logout();

Sample Code - Get information about logged in user

This example shows how to retrieve information about the logged in supplier user.

    // Login as supplier user at default url http://localhost:9090/hsx 
    FactoryHelper helper = new FactoryHelper().login( "admin@suppliertest.com", "secret123" );
    
    // Create a factory and context to assemble a http request
    SecurityRequestFactory factory = helper.create( SecurityRequestFactory.class );
    SecurityRequestContext context = factory.securityContext();
    
    // Load data about logged in user with supplier organization details.
    UserProxy loggedInUser = FactoryHelper.fire( context.getLoggedInUser().with( "organization" ) );
    
    System.out.println( loggedInUser );
    
    // Logout supplier user
    helper.logout();

List of Available Services

The following tables gives an overview about the most important services that can be access remotely.

As a general note, all factories with the suffix NoAuth are accessible without being logged in as a user.

Service Factory Class Name	Purpose
UserRequestFactory	Manage supplier users, load list of users in batch.
OrganizationRequestFactory	Manage supplier organizations.
FeedRequestFactory	Handles timeline messages and feeds (a feed contains one or multiple messages). Provides methods to load a timeline, to create new feeds or to respond to existing messages.
InitialDataloadRequestFactory	Allows to trigger the test run workflow for supplier users.
ImportRequestFactory	Allows to trigger the import run workflow for supplier users.
DataLoadRequestFactory	Provides access to the results of a test/import run. The DataLoad entity references also the destination catalog and supplier as well as the user that actually triggered the job.
MappingRequestFactory	Provides access and management of import mappings that are necessary to run a import job.
RegistrationRequestFactory RegistrationRequestFactoryNoAuth	Manages the supplier registration workflow. The *NoAuth interface is accessible without authentication.
InvitationRequestFactory	Manages the supplier invitation workflow.
SecurityRequestFactory	Provides information about the authenticated user and its permissions.
SystemRequestFactory	Provides information about the system configuration, e.g. available languages and application version.
LostPasswordRequestFactoryNoAuth	Generates a email for lost password mechanism.

Supplier Portal Remote API

Overview

Authentication & Security

Getting Started

Sample Code - Create new supplier

Sample Code - Get information about logged in user

List of Available Services

Further Reading