Overview

Stonebranch Integrations are pre-built, installable enhancements to the Universal Automation Center (UAC) platform that allow you to orchestrate automated processes across your existing third-party applications and platforms. Via integrations, you can connect UAC to third-party solutions spanning cloud service providers, data tools, developer tools, business applications, and more.

Integrations are published to the Stonebranch Integration Hub, where they can be browsed and downloaded. Each integration is packaged as a Universal Template that is imported into UAC, enabling users to create and run Universal Tasks against the target system, all orchestrated and monitored from within UAC.

How Integrations Work

Each integration follows this general flow:

1. A Universal Template defines the structure of the integration, i.e. its input fields, actions, credentials, and behavior.
2. Users create a Universal Task from the template and configure it with the required parameters.
3. When executed, a Universal Agent runs the task against the target system.
4. Task results, including extension output, logs, and exit codes, are returned to the Universal Controller for visibility and downstream orchestration.

For full documentation on Universal Templates and Universal Tasks, see Related Documentation.

How To

Import a Universal Template

To use any integration, you must first import its Universal Template into your Universal Controller.

tip

For large Universal Templates, some parameters need to be adjusted, particularly for MySQL, Universal Controller and Universal Agent: (tomcat/conf/uc.properties)

MySQL (my.cnf):

• max_allowed_packet: Defines the maximum size of a single network packet that can be read or written by the server and clients.
  • Recommended setting: Ensure it is configured to a value at least 25% greater than the size of your largest imported integration.
• innodb_log_file_size: Determines the size of InnoDB redo log files. While this parameter has been simplified in recent MySQL versions, it's still relevant for MySQL versions prior to 8.0.30.
  • Purpose: Prevents "BLOB/TEXT data inserted in one transaction is greater than 10% of redo log size" errors that might appear on Universal Controller logs.
  • Recommended setting: Ensure 10% of the log file size exceeds your largest imported integration.

Universal Agent Configuration (config/omss.conf):

• max_msg_size: Specifies the maximum allowable size for messages. Messages exceeding the limit will not be accepted by the server.
  • Recommended setting: Ensure the configured value is 10% greater than your largest imported integration.

Universal Controller Configuration:

Universal Controller configuration can restrict import of an integration if the extension maximum bytes is not properly set. This can be configured in the following ways:

1. Universal Controller configuration file (tomcat/conf/uc.properties): uc.universal_template.extension.maximum_bytes
2. Universal Controller UI Admin Panel: Administration > Properties > Universal Template Extension Maximum Bytes
   • Recommended setting: Ensure the configured value is greater than the size of your largest imported integration.

The deployment of an integration from Universal Controller to Universal Agents can also be restricted by the JVM heap size of the Tomcat serving the Universal Controller. Make sure to configure the JVM heap size adequately. Things to consider:

• # of agents configured to accept the extension(s).
• # of agents configured to deploy on-registration and how many would be registering simultaneously.
• # of parallel, on-demand deployments, where deployment happens the first time the extension needs to execute on a specific agent.

1. The Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
2. Import the Universal Template into your Controller:
   1. Extract the zip file, you downloaded from the Integration Hub.
   2. In the Controller UI, select Services > Import Integration Template option.
   3. Browse to the "export" folder under the extracted files for the ZIP file (Name of the file will be unv_tmplt_*.zip) and click Import.
   4. When the file is imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Configure Universal Task

• Create a new Universal Task and enter the required input fields as defined in the Universal Template.
• Before creating the task, ensure any required external accounts, access tokens, or service credentials are available.
• Create the required Resolvable Credentials to be used as input fields in the Universal Task configuration.
• If additional resources are needed (such as configuration scripts, data files, or prerequisite tasks), set these up before configuring the Universal Task.

Import Grafana Dashboard

For integrations with observability metrics, users can benefit from a ready-to-use sample dashboard that the downloadable integration offers when observability features are used. It is located under /observability/grafana/ directory inside the downloadable zip file from Stonebranch Integration Hub. Administrators should refer to the official Grafana User Guide on how to import a Grafana Dashboard.

tip

Dashboard's Prometheus data source is configured as a variable, and therefore needs to be mapped to an existing Data Source configured on the target Grafana instance.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

• Python code modifications should not be done.
• Template Modifications
  • General Section
    • "Name", "Extension", "Variable Prefix", and "Icon" should not be changed.
  • Universal Template Details Section
    • "Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.
  • Result Processing Defaults Section
    • Success and Failure Exit codes should not be changed.
    • Success and Failure Output processing should not be changed.
  • Fields Restriction Section
    The setup of the template does not impose any restrictions. However, concerning the "Exit Code Processing Fields" section.
    1. Success/Failure exit codes need to be respected.
    2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining the success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

STDOUT/STDERR Notice

STDOUT and STDERR provide additional information to the user.

STDOUT content depends on the integration. It may be empty, contain task-specific output controlled by the STDOUT Options field, or directly reflect the output of an underlying command or API call.

STDERR provides execution log details. The level of detail is tuned by the Log Level Task Definition field.

warning

Backward compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice.

Related Documentation

Document Link	Description
Universal Templates	User documentation for creating, working with, and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.
Stonebranch Terms of Use	Terms governing use of downloaded integrations.
Stonebranch Integration Hub	Browse and download all available Stonebranch Integrations.