Customizations as part of integrations


Integrations require that your service interacts with an external application or technology. A standard integration is any integration that communicates with BMC Helix platform using an approved method or adapter. See Integrations for a list of these standards. If you want to communicate with your Helix platform using any other method or adapter, it is considered a non-standard integration or plug-in. The integration code must be designed and developed by adhering to the design standards and best practices as defined in the customization policy.

Occasionally, integrations are required to support data flow between on-premises or third-party applications and the Helix platform. Allowable functions include extending core functionality through means of a Java filter or AR System Database Connectivity (ARDBC) plug-in. Customers wishing to use one of these two methods are subject to BMC’s discretion to reject the implementation in case of vulnerabilities and infrastructure risks identified. Non-standard integrations should only be considered if the use case cannot be easily achieved with existing product features or standard integration methods.

API standards

Ongoing support for your customizations is your responsibility. To maintain supportability, BMC enforces the following standards:

It is the customer's responsibility to review this policy and validate that their filter or plug-in complies with these published standards.

 Code standards

Ongoing support for your customizations is your responsibility. To maintain supportability, BMC enforces the following standards:

  • Plug-ins must follow development guidelines as documented by BMC. For information, see Creating Java plug-ins.

  • Customizations must comply with the licensing capacities purchased in your BMC Helix agreements; the customer is responsible for reviewing beforehand whether your plug-in will require additional BMC Helix subscription services licensing, please contact your BMC Account Team to review.
  • The customer is responsible for acquiring and maintaining any third-party licensing required outside of your BMC Helix subscription.
  • BMC is not responsible for errors and use cases associated with any third-party or open source code outside of your BMC Helix platform.
  • Plug-ins must be of type Filter or ARDBC.
  • Plug-ins must be written in Java.
  • Plug-ins must be compiled with current protocol version (same version as your environment's AR Server). As platform and/or application updates are scheduled, the customer is responsible for releasing a compatible plug-in version to BMC prior to the update.
  • Plug-ins may not contain GNU General Public License (GPL) or copyleft code as part of the distribution. The customer remains responsible for obtaining proper licensing for any third-party software and for providing license validation upon BMC's request.
  • Plug-ins must run in their own plug-in server.  Existing plug-in servers may not be modified.
  • Configuration may not depend on IP addresses or hard coded hostnames.
  • Configuration may not contain usernames and/or passwords.
  • Configuration information like keystore information, certificates, and so on must be provided by the customer. The customer is responsible for preventing certificate expiry.
  • Configuration information must be provided as-is. Any manual changes must be documented with the least possible steps.
  • Plug-ins may not modify standard application or system configuration files.
  • Plug-ins will not be accessible via the internet.
  • Plug-ins will not have access to internal DNS servers or services.
  • Plug-ins may not host a runtime that will perform continuous background processing. The plug-in can be a request/response handler only.

Nonstandard customizations and integrations not supported on SaaS

The following nonstandard customizations and integrations are not supported on the BMC Helix environments:

  • Direct access to update the database forms/tables
  • File and script processing through workflows
  • View forms/tables
  • Direct SQL updates through workflows

For more information about the best practices to convert nonstandard customizations to standard customizations, see Best-practices-to-convert-nonstandard-customizations-to-standard-customizations.

Important

Adherence to these tenets will serve as the basis for customization approval. Adherence is non-negotiable.

Additionally, if BMC suspects or identifies potential risks to our SaaS application, infrastructure, or network stability as a result of your custom plug-in, BMC holds the right to switch off your integration. The BMC Account team will notify your Maintenance Contacts of this action should this incident occur.

Best practices for non-standard customizations and integrations

The following table lists out the best practices for for non-standard customizations and integrations in the BMC Helix environments:

Integration type


Database

  • Read access to the database is controlled in the Helix environment and needs approval from BMC. If the access is not approved, you must rework the database integration.
  • After approval, the read-only access must be configured at the database level. The configuration must be set up within the BMC Helix Client Gateway. 
  • Writing directly into the database is not allowed in the Helix environment. You must rework the database integration so that it does not require write access to the database.

Custom workflows

  • The use of Direct SQL workflow is controlled and only permitted in the Data Wizard supported workflows in the Helix environment.
  • Direct SQLs require review and approval from BMC. If these are not approved, you must rework the direct SQLs.
  • Custom stored procedures, functions, tables, or other objects (non-Helix database objects) are not allowed in the Helix environment. You must rework these integrations.
  • Custom workflow that incorporates a run process of custom scripts or binaries is not allowed within Helix environment. You must rework these integrations to avoid the use of run process.

Plug-in and file system integrations

Adding files to the file systems is not allowed within BMC Helix environments. You must rework these integrations so that files need not be added to the file system.

Custom plug-ins

The use of a custom plug-ins is generally not allowed in BMC Helix environments, but exceptions may be allowed. Approval is required for the use of a custom plug-in.

Third-party applications

  • Third-party applications are supported within the BMC Helix environments if they conform to the requirements and utilize a standard API interface (AR API, Web services, or REST API).
  • You must check version compatibility of the application with BMC Helix services.

Recommended documentation

BMC requires that, at a minimum, the following information be included in the design document: 

  • Intended use of the integration including where data is coming from, where data is going to, and how data is being transported
  • Maximum memory footprint (-xmx flag) requirements
  • A pluginsrv_config.xml template describing content between <plugin></plugin> tags
  • An ar.cfg configuration template with optional configuration placeholders including the Server-Plugin-Alias MY.PLUGIN entry:  MY.PLUGIN onbmc-s:<PLUGINPORT>
  • A description of any access the plug-in will require including:
    • Inbound network ports (the plug-in port is assumed by default)
    • Outbound network ports and services
    • File system access (read and write)
    • Fork/execute permissions

Operational responsibilities

The following table outlines the responsibility of each party in the lifecycle of a custom integration implementation.

Task

Responsible party

Notes

Gather the required documentation related to the customization

Customer

Review the minimum documentation requirements above.

Validate proper compliance to the standards provided herein; validate proper software licensing is in place

Customer

Review this standard in its entirety prior to submitting a request for approval.

If you are unsure of the licensing terms of your customization, consult with your in-house legal department before requesting approval from BMC.

Request code installation

Customer

Submit a case if using BMC Support Central. A separate request is required for each environment.

The customer must provide the required documentation listed above, and provide detailed installation steps and operational requirements as part of the change request. Failure to provide the proper detail may result in a delay in implementing the change.

Implement change request

BMC SaaS Operations

Implementation of a change request will follow the BMC-Helix-Change-Management-policy.

BMC will enforce isolation according to the plug-in access requirements.

BMC will implement the change using the local AR Server port of 46262 and local AR Server hostname of "onbmc-s".

Customization isolation

BMC SaaS Operations

BMC reserves the right to isolate a plug-in and enforce the access requirements that were documented by the customer. The isolation may be enforced using any standard method, including, but not limited to:

BMC may use any isolation method to reduce exposure of the executable outside of the documented required access rights.

Customization validation/testing

Customer

The customer is responsible for performing all technical and functional testing for the customization, including initial configuration and after system patches and service updates.

Customization maintenance

Customer

The customer is responsible for maintaining the custom code. BMC will not analyze log files generated by the plug-in. The plug-in must use standard AR logging mechanisms and practices. BMC will provide the logs upon request via the File-transfer-process. A separate operational request is necessary to set up the MFT process.

Customization monitoring

Customer

BMC will not monitor the plug-in for termination or problems with availability as BMC does not know the test cases. BMC advises that the customer provide some self-monitoring and embed methods of notification in case of component failure. BMC will use a standard and dedicated AR plug-in server process to run the plug-in.

BMC will however monitor CPU consumption. Excessive resource consumption will not be permitted. The plug-in should not consume more than 10% of the total available CPU; BMC reserves the right to cap this consumption at 10%.

Customization removal

BMC SaaS Operations

Upon customer request, BMC will deactivate and uninstall the customization, and return or permanently destroy the code.

Customization guidelines

If BMC determines that the customization puts a contractual obligation between BMC and any of its customers at risk, BMC reserves the right to take any action necessary to guarantee these commitments. Causes for action include, but are not limited to, service stability, service availability, service performance or any kind of security threat. Mitigation actions may include restarting the plug-in, capping execution parameters, increasing the isolation configuration, changing configuration parameters or even deactivating the plug-in. BMC will promptly notify the customer if a restart or deactivation is required but may not be able to do so in advance of taking action.

In order to determine impact, BMC may monitor the customization, including but not limited to, accessing log files, changing log settings, tracking execution or even attaching debuggers.

Important

You are responsible for ensuring that your plug-in will not violate your agreement with BMC or any applicable law. You are solely responsible for the development, content, operation, maintenance, and use of your plug-in.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*