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"
})
public
class
Connector {
public
static
void
main(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:
Implement com.bmc.connector.worker.plugin.ConnectorPlugin for all commands executed from the cloud. For example:
Sample connector plugin implementation
public
class
AppDataCollector
implements
CollectorPlugin
{
@Override
public
void
collectData(PublishFeed publishFeed)
throws
CollectorException
{
}
}
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
Implement com.bmc.pathway.connector.collector for all autonomous collection schedules. For example:
Sample collection plugin implementation
public
class
AppDataCollector
implements
CollectorPlugin
{
@Override
public
void
collectData(PublishFeed publishFeed)
throws
CollectorException
{
}
}
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.
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=<
user
action content directory>
#example:C:\\work\\actionContents
#Optional parameters
actioncontent.restoreLocalContent=false #<
Forcefully
publish local action contents> (Default value is false)
actioncontent.continueDespiteErrors=false #<
Will
make 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 thegetConfiguration()
.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. SeegetConfiguration()
.Refer to the sample connector to also run additional scripts (Run, Deploy, and so forth) as required.
Comments
Log in or register to comment.