Using a Java-based connector to create a custom connector

The Java-based connector enables you to write a new connector or enhance an existing connector that resides on-premise and hosts a set of commands that can be executed from BMC Helix Cloud services.

Before you begin

Ensure that the following prerequisites are met:

OpenJDK 11.0.2.
Eclipse is installed and a Maven project is set up. For more information, see To set up a Maven project in Eclipse.
A git client or github desktop is available.
You have a valid github.bmc.com account.
You have access to a BMC DEM account.

To write the connector

Add the latest release of the base connector in BMC Helix Cloud Security as a dependency in the pom.xml file, as shown in the following example:
pom.xml

<dependency>
      <groupId>com.bmc.pathway</groupId>
      <artifactId>base-connector</artifactId>
      <version><LATEST_AVAILABLE_VERSION></version> // use latest available version of base-connector , do not use LATEST or RELEASE
</dependency>
Add the following annotation in the main class of the connector:
Connector main class

@SpringBootApplication
@EnableAutoConfiguration
@ComponentScan({"com.bmc.pathway.connector.worker","com.bmc.pathway.connector.common","com.bmc.pathway.connector.collector"})
publicclassConnector {

    publicstaticvoidmain(String[] args) {
        BaseConnector.init(args, Connector.class);

        /**
            In case if there are loggers required before the initialization happens then one can use following way to initialize the system logger      first
            LoggerInitializer initializer = new LoggerInitializer(SCCMConnectorApp.class.getSimpleName());
            // DO SOMETHING
            // USE LOGGER
            BaseConnector.init(args, Connector.class, initializer);
        **/
    }
}
Add the following interfaces and add the configuration details in the corresponding application.properties file:
1. Implement com.bmc.connector.worker.plugin.ConnectorPlugin for all commands executed from the cloud. For example:
  Sample connector plugin implementation
  
  publicclassAppDataCollector implementsCollectorPlugin
  {
      @Override
      publicvoidcollectData(PublishFeed publishFeed) throwsCollectorException
      {
      }
  }
  application.properties
  
  # Service prefix to mark the number and prefix of collector schedules and their properties below: All collector schedule properties must start with any of the prefix defined any thing else will be ignored.
  collector.service.prefix=app
  # app schedule properties
  # property to define active schedule
  app.collector.plugin.active=true
  # schedule id for future ref , this id can be used later to access the schedule from cloud.
  app.collector.collectorId=app
  # collector plugin handler
  app.collector.plugin.handler=com.bmc.connector.plugin.samplecollector.AppDataCollector
  #collector schedule period
  app.collector.schedule.period=1
  #collector publish policy
  app.collector.publish.policy=CACHED
  #collector schedule time unit ,supported time unit "DAYS","HOURS","MINUTES","SECONDS",MILLISECONDS
  app.collector.schedule.TimeUnit=MILLISECONDS
2. Implement com.bmc.pathway.connector.collector for all autonomous collection schedules. For example:
  Sample collection plugin implementation
  
  publicclassAppDataCollector implementsCollectorPlugin
  {
      @Override
      publicvoidcollectData(PublishFeed publishFeed) throwsCollectorException
      {
      }
  }
  application.properties
  
  # Service prefix to mark the number and prefix of collector schedules and their properties below: All collector schedule properties must start with any of the prefix defined any thing else will be ignored.
  collector.service.prefix=app
  # app schedule properties
  # property to define active schedule
  app.collector.plugin.active=true
  # schedule id for future ref , this id can be used later to access the schedule from cloud .
  app.collector.collectorId=app
  # collector plugin handler
  app.collector.plugin.handler=com.bmc.connector.plugin.samplecollector.AppDataCollector
  #collector schedule period
  app.collector.schedule.period=1
  #collector publish policy
  app.collector.publish.policy=CACHED
  #collector schedule time unit ,supported time unit "DAYS","HOURS","MINUTES","SECONDS",MILLISECONDS
  app.collector.schedule.TimeUnit=MILLISECONDS
  Note
  
  The connector supports multiple schedules in a single instance as defined in the properties.
3. Implement com.bmc.pathway.connector.actioncontents as an additional component scan that enables you to add, update, or delete action contents from the connector at start-up. For example:
  Sample collection plugin implementation
  
  @ComponentScan({ "com.bmc.pathway.connector.actioncontents", "com.bmc.pathway.connector.worker", "com.bmc.pathway.connector.common", "com.bmc.pathway.connector.collector"})
  application.properties
  
  actioncontent.publish=true
  actioncontent.location=<useraction content directory>
  #example:C:\\work\\actionContents
  #Optional parameters
  actioncontent.restoreLocalContent=false #<Forcefullypublish local action contents> (Default value is false)
  actioncontent.continueDespiteErrors=false #<Willmake connector stop if invalid/wrong action content data is attempted>(Default value is false)
Install scripts required to deploy the connector. For example:
distribution.xml: Packages the connector as required by the cloud connector service.
distribution.xml

<assembly
    xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
    <id>distribution</id>
    <formats>
        <format>zip</format>
    </formats>
    <includeBaseDirectory>false</includeBaseDirectory>
    <fileSets>
        <fileSet>
            <directory>resources/bin</directory>
            <includes>
                <include>checkEnv.bat</include>
                <include>EncryptPassword.bat</include>
                <include>checkEnv.sh</include>
                <include>EncryptPassword.sh</include>
            </includes>
            <outputDirectory>bin</outputDirectory>
        </fileSet>
        <fileSet>
            <directory>resources</directory>
            <includes>
                <include>run.bat</include>
                <include>run.sh</include>
            </includes>
            <outputDirectory></outputDirectory>
        </fileSet>
        <fileSet>
            <directory></directory>
            <includes>
                <include>ReadMe.txt</include>
            </includes>
            <outputDirectory></outputDirectory>
        </fileSet>
        <fileSet>
            <directory>resources/config</directory>
            <includes>
                <include>creds.json</include>
                <include>*.properties</include>
            </includes>
            <outputDirectory>config</outputDirectory>
        </fileSet>
        <fileSet>
            <directory>${project.build.directory}/lib</directory>
            <includes>
                <include>*.jar</include>
            </includes>
            <outputDirectory>lib</outputDirectory>
        </fileSet>
    </fileSets>
</assembly>
connectorDefinition.json: Contains all required information about the connector.

{
    "id": "1",
    "name": "Sample Collector",
    "type": "sample-collector",
    "description": "Sample Connector.",
    "version": "1.0.0",
    "dateCreated": 0,
    "tags": "ADAP, DepCheker",
    "imgSrc": "content/images/collector/bmc_logo.png",
    "docLink": "",
    "fileType": "zip",
    "propertiesFile": "config/application.properties",
    "supportedCapabilities": [],
    "definitionTags": [
      "services:policyservice",
      "services:secure"],
  "usesInstructions": "<li>Ensure that the target environment has Java 1.8 or later.</li><li>Extract the zip file using any standard compression tool.</li><li>Configure parameters in the filename file.</li><li>Double-click run.bat or run.sh in your target environment.</li>",
    "configParams": []
}
Note

The previous examples are just two examples of the scripts that are available. For more information and examples of additional scripts, refer to the sample connector on bmc.github.com.
Add app.fetchCloudProperties=true to the application.properties file as shown in the following example.
This enables the Base connector to pull the configuration from the cloud at startup.
application.properties

# Connector plugin handler property
# To enable configuration fetch from cloud on startup
app.fetchCloudProperties=true
All cloud-related properties should be accessed through the following interface:
Connector configuration reader

* @author vajain
*
*/
public interface ConnectorConfigReader {
    /**
     * Register to configuration changeListener
     *
     * @param configurationListener
     */
    public void registerConfigurationChangeListener(ConfigurationListener configurationListener);
    /**
     * deregister to configuration changeListener
     *
     * @param configurationListener
     */
    public void deregisterConfigurationChangeListener(ConfigurationListener configurationListener);
    /**
     * Get Heart beat frequency
     *
     * @return
     */
    public long getHeartBeatPeriod();
    /**
     * Get property value by propertyKey
     * @param propertyKey
     * @return
     */
    public Object getPropertyValue(String propertyKey);
}
Add the following statement to access the connector configuration reader instance:
Connector configuration reader access

ConnectorConfigReader connectorConfigReader = ConnectorConfig.getConfigReader();
Note

The changes reflected in the connector configuration might fail some of the existing junit script as it connects to the cloud to get the configuration. To avoid the potential error, set app.fetchCloudProperties=false or mock the getConfiguration().
Specify the supported capabilities in connector definition:
Update configurations: Updates the configuration on the connector.
Note

The connector must be in the Running state to update the configuration.
connectorDefinition.json

{
   ...
   "supportedCapabilities": ["updateConfigurations"],
   ...
}
ConnectorConfigReader: Used for configuration updates notification.
Note

Additional utility methods are available in the ConnectorUtil.java to parse the configuration value in the required datatype. See getConfiguration().
Refer to the sample connector to also run additional scripts (Run, Deploy, and so forth) as required.

Using a Java-based connector to create a custom connector

Before you begin

To write the connector

Comments