Setting up the development environment

Set up the development environment in Eclipse IDE for writing your plugins. Use any Java EE IDE of your choice and make the required configurations mentioned in this topic. You need certain artifacts from <ASSET_PICKER_HOME> to complete the environment setup. This topic will provide information about project building and packaging using Apache Maven so ensure that you have Apache Maven installed.

About this task

To set up the development environment, complete the following steps:

Procedure

  1. From the <ASSET_PICKER_HOME>/dev-kits/ location, copy the asset-integration-starter project and place it in your development workspace.
  2. Open the Eclipse IDE.
  3. Select File > Import.
    The Select dialog appears.
  4. Select WAR file and click Next.
    The WAR Import dialog appears.
  5. Click Browse, navigate to <ASSET_PICKER_HOME>, and select asset-viewer.war file.
  6. Click Finish.
    The WAR Import: Web libraries dialog appears.
  7. Click Finish.
  8. Select Window > Show View > Other.
    The Show View dialog appears.
  9. Select Servers and click Open.
    As an example, we will illustrate the use of Apache Tomcat 9.0 for running Content Integration. You can use any supported application server and make the required configurations.
    1. Open the conf/server.xml file from your Apache Tomcat 9.0 installation directory and add the following entry, with appropriate database details, inside the <GlobalNamingResources> element. Please replace <DRIVER_CLASS_NAME>, <URL_TO_YOUR_PLATFORM_DATABASE>, <DATABASE_USERNAME>, and <DATABASE_PASSWORD> with Platform database details:
      <Resource auth="Container" driverClassName="{DRIVER_CLASS_NAME}" 
                                 maxActive="20" 
                                 maxIdle="0" 
                                 maxWait="10000" 
                                 name="UnicaPlatformDS" 
                                 password="{DATABASE_PASSWORD}" 
                                 username="{DATABASE_USERNAME}"
                                 type="javax.sql.DataSource" 
                                 url="{URL_TO_YOUR_PLATFORM_DATABASE}"/>
    2. Open the conf/context.xml file from your Apache Tomcat 9.0 installation directory and add the following entry inside the <Context> element:
      <ResourceLink auth="Container" global="UnicaPlatformDS" name="UnicaPlatformDS" 
      type="javax.sql.DataSource"/>
  10. To add Apache Tomcat 9.0 as a new server in Eclipse, complete the following steps:
    1. In the Servers tab, click the link to create a new server.
      The Define a New Server dialog opens.
    2. Select Tomcat v9.0 Server and provide values for Server host name and Server name.
    3. Click Next.
      The server is successfully added.
    4. In the Servers tab, double-click the newly added server entry.
      The Overview dialog appears.
    5. Click the link Open launch configuration.
      The Edit launch configuration properties dialog appears.
    6. Edit the launch configurations to the add following JVM arguments
      
      -DASSET_PICKER_HOME=<Point this to <ASSET_PICKER_HOME> directory>
      -Dspring.profiles.active=platform-disintegrated
      
    7. Click OK.
  11. To run the imported asset-viewer.war file on Apache Tomcat 9.0, right click the asset-viewer.war file and select Run As > Run on Server.
    The Run on Server dialog appears.
  12. Click Finish.
    The asset-viewer.war will start executing on Apache Tomcat. After the setup is verified, stop the server and import the plugin development starter project.
  13. To install Content Integration SDK, complete the following steps:
    1. In the following directories, delete the SDKs that are already installed:
      • <LOCAL_M2_REPOSITORY>\com\hcl\unica\integration-api\0.0.1-SNAPSHOT
      • <LOCAL_M2_REPOSITORY>\com\hcl\unica\standard-integrations \0.0.1-SNAPSHOT
      • <LOCAL_M2_REPOSITORY>\com\hcl\unica\asset-integration-api\0.0.1-SNAPSHOT
      • <LOCAL_M2_REPOSITORY>\com\hcl\unica\entity-mapper-api\0.0.1-SNAPSHOT

      On UNIX or Mac OS X, <LOCAL_M2_REPOSITORY> refers to the ~/.m2/repository directory.

      On Microsoft Windows, <LOCAL_M2_REPOSITORY> refers to the C:\Users\{your-username}\.m2\repository directory.

    2. Use the following commands to install Content Integration SDKs into your local Maven repository. Find asset-integration-api.jar, integration-api.jar, standard-integrations.jar and entity-mapper-api.jar inside the <ASSET_PICKER_HOME>/dev-kits/sdk directory.
      mvn install:install-file -Dfile=<ASSET_PICKER_HOME>/dev-kits/sdk/asset-integration-api.jar -DgroupId=com.hcl.unica -DartifactId=asset-integration-api -Dversion=0.0.1-SNAPSHOT -Dpackaging=jar
      
      mvn install:install-file -Dfile=<ASSET_PICKER_HOME>/dev-kits/sdk/integration-api.jar -DgroupId=com.hcl.unica -DartifactId=integration-api -Dversion=0.0.1-SNAPSHOT -Dpackaging=jar
      
      mvn install:install-file -Dfile=<ASSET_PICKER_HOME>/dev-kits/sdk/standard-integrations.jar -DgroupId=com.hcl.unica -DartifactId=standard-integrations -Dversion=0.0.1-SNAPSHOT -Dpackaging=jar
      
      mvn install:install-file -Dfile=<ASSET_PICKER_HOME>/dev-kits/sdk/entity-mapper-api.jar -DgroupId=com.hcl.unica -DartifactId=entity-mapper-api -Dversion=0.0.1-SNAPSHOT -Dpackaging=jar
  14. To import the plugin development starter project, select File > Import.
    The Select dialog appears.
  15. Select Existing Maven Projects and click Next.
    The Maven Projects dialog appears.
  16. Click Browse to select the project and click Finish.
  17. To update Maven dependencies of the asset-integration-starter project, right-click the asset-integration-starter project and select Maven > Update Project.
  18. Ensure that newly imported project is using Java 8 to compile sources. Open project properties and complete the following steps to setup the compiler:
    1. Select Java Compiler.
    2. If Compiler compliance level is non-editable, select Enable project specific settings.
    3. Change the Compiler compliance level to 1.8.
    4. Click Apply and Close.
  19. To ensure that the right Java library is set up in the build path, complete the following steps:
    1. Select Java Build Path > Libraries.
    2. Select JRE System Library (J2SE-1.5).
    3. Click Remove.
    4. Click Add Library.
      The Add Library dialog opens.
    5. Select JRE System Library > Next.
      The JRE System Library appears.
    6. Select an appropriate library and click Finish.
  20. To enable annotation processing, complete the following steps:
    1. Select Java Compiler > Annotation Processing.
    2. Select Enable project specific settings.
    3. Select Apply and Close.
  21. To install Lombok, complete the following steps:
    1. Double-click the LOCAL_M2_REPOSITORY\org\projectlombok\lombok\1.18.16\lombok-1.18.16.jar.
      The installer dialog appears.
    2. To specify the installation location of your IDE, click Specify location.
    3. To complete the installation, click Install / Update.
    4. Post installation of Lombok, restart the IDE.
  22. To change the project name, complete the following steps:
    1. Open the file pom.xml and change its Maven project properties.
    2. Right-click the asset-integration-starter project and select Refactor > Rename.
  23. In the <ASSET_PICKER_HOME>/conf/custom-plugin-services.yml file, declare the plugin services. You can access this file later to add declarations when you introduce services for your plugins.
  24. To add plugin project to the deployment assembly of the asset-viewer.war project, complete the following steps:
    1. Right-click the asset-viewer.war project and select Properties.
      The Properties for asset-viewer dialog opens.
    2. Select Deployment Assembly.
    3. Select Add.
      The Select Directive Type dialog opens.
    4. Select Project and click Next.
    5. Select the asset-integration-starter plugin project you imported in previous steps and click Finish.
  25. If necessary, clean the projects.
  26. Make the appropriate configuration for your system in <ASSET_PICKER_HOME>/conf/systems.properties (refer sample-systems.properties file available in the <ASSET_PICKER_HOME>/dev-kits/asset-integration-starter project). All the system onboarding configurations mentioned in Unica Content Integration Administration Guide are supported in systems.properties using relevant properties.
  27. As you develop your plugin, check it by running the asset-viewer.war project on a previously configured application server. Since the project would already be added to the Deployment Assembly of asset-viewer.war, changes to your plugin project will be deployed whenever you run the asset-viewer.war project.
  28. As you develop your plugin, by adding services to it, use a tool of your choice to hit the following REST endpoints (change the context root to match your setup) to verify the accuracy of your implementation:
    1. Ensure system onboarding
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/instances
      Request Method GET
    2. Verify simple-search service
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/mysystem/assets?query=mountain&page=0&size=10&types=Phto
      where,
      • mysystem represents the system identifier chosen by plugin implementation.
      • query contains the search keyword to lookup the content for.
      • page & size contains pagination details, where page is the serial number of pages to be retrieved and size is the total search items on a single page.
      • types is one of the supported content categories (types) to filter the search items against.
      Request Method GET

      When you hit the URL, ensure that the response JSON contains the expected result. Only presentation details are included for every search items. Other content properties are excluded for the sake of brevity and performance.

    3. Verify resource-loader service
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/mysystem/download?resource=

      http://repository_base_url/contents/sample_image.jpg%26resourceId=12345"

      where
      • mysystem represents the system identifier chosen by plugin implementation.
      • resource contains the absolute URL content to be downloaded.
      • resourceId contains the identifier of the content to be downloaded.

      (Plugin can choose to utilize either resource or resourceId or both to load the content.)

      Request Method GET
    4. Verify list-folders service
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/mysystem/folders?parentFolderId=1234
      where:
      • mysystem represents the system identifier chosen by plugin implementation.
      • parentFolderId contains the identifier of the parent folder whose immediate subfolders are expected in response. This query parameter is optional & not supplied while listing the top/root level folders.
      Request Method GET
    5. Verify list-contents service
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/mysystem/folders/1234/contents
      where:
      • mysystem represents the system identifier chosen by plugin implementation.
      • 1234 represents the identifier of the folder whose immediate contents are expected in response.
      Request Method GET

      Only presentation details are included for every content listed by the list-contents service. Other content properties are excluded for the sake of brevity and performance.

    6. Verify get-content-details service
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/mysystem/assets/Images/1234
      where:
      • mysystem represents the system identifier chosen by plugin implementation.
      • Images represents the category ID of the content whose details are expected in response.
      • 1234 represents the identifier of the content whose details are expected in response.
      Request Method GET

      The JSON response produced by get-content-details service includes all the content properties, in addition to the presentation details.

    7. Verify get-object-schema service
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/object-mapping/application/mysystem/object/Images/1234/schema
      where:
      • mysystem represents the system identifier chosen by plugin implementation.
      • Images represents the category of the reference content being used for schema generation.
      • 1234 represents the identifier of the reference content being used for schema generation.

      As of 12.1.0.4, content identifier and category are not much relevant since the schema is expected to include attributes for all the supported content categories.

      Request Method GET

      The JSON response must contain the flattened list of all mappable attributes and their metadata.

    8. Verify list-content-categories service
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/mysystem/categories
      where:
      • mysystem represents the system identifier chosen by plugin implementation.
      Request Method GET
    9. Verify get-cognitive-analysis service
      Endpoint URL http://localhost:8888/asset-viewer/api/AssetPicker/actions/cognize?url=absolute_image_url
      where:
      • url contains absolute URL of the image to fetch the cognitive analysis for
      Request Method GET