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
<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
Add the following annotation in the main class of the connector:
Connector main class
@ComponentScan({"com.bmc.pathway.connector.worker","com.bmc.pathway.connector.common","com.bmc.pathway.connector.collector"})
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());
BaseConnector.init(args, Connector.class, initializer);
- Add the following interfaces and add the configuration details in the corresponding application.properties file:
Implement com.bmc.connector.worker.plugin.ConnectorPlugin for all commands executed from the cloud. For example:
publicclassAppDataCollector implementsCollectorPlugin
publicvoidcollectData(PublishFeed publishFeed) throwsCollectorException
# 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
Implement com.bmc.pathway.connector.collector for all autonomous collection schedules. For example:
publicclassAppDataCollector implementsCollectorPlugin
publicvoidcollectData(PublishFeed publishFeed) throwsCollectorException
# 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.
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:
@ComponentScan({ "com.bmc.pathway.connector.actioncontents", "com.bmc.pathway.connector.worker", "com.bmc.pathway.connector.common", "com.bmc.pathway.connector.collector"})
actioncontent.publish=true
actioncontent.location=<useraction content directory>
#example:C:\\work\\actionContents
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.
xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<includeBaseDirectory>false</includeBaseDirectory>
<directory>resources/bin</directory>
<include>checkEnv.bat</include>
<include>EncryptPassword.bat</include>
<include>checkEnv.sh</include>
<include>EncryptPassword.sh</include>
<outputDirectory>bin</outputDirectory>
<directory>resources</directory>
<include>run.bat</include>
<include>run.sh</include>
<outputDirectory></outputDirectory>
<include>ReadMe.txt</include>
<outputDirectory></outputDirectory>
<directory>resources/config</directory>
<include>creds.json</include>
<include>*.properties</include>
<outputDirectory>config</outputDirectory>
<directory>${project.build.directory}/lib</directory>
<outputDirectory>lib</outputDirectory>
"name": "Sample Collector",
"type": "sample-collector",
"description": "Sample Connector.",
"tags": "ADAP, DepCheker",
"imgSrc": "content/images/collector/bmc_logo.png",
"propertiesFile": "config/application.properties",
"supportedCapabilities": [],
"services:policyservice",
"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>",
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.
# Connector plugin handler property
# To enable configuration fetch from cloud on startup
app.fetchCloudProperties=true
Connector configuration reader
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
public long getHeartBeatPeriod();
* Get property value by propertyKey
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.
"supportedCapabilities": ["updateConfigurations"],
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.