Barium Integration Agent is a lightweight Windows service that can be configured to monitor local data sources and send messages and data to process applications in a space in Barium Live if the configured rules are fulfilled.


Contact Barium Live Support if you want a download link to Barium Integration Agent. Please provide your company name and a brief description of your integration needs in the request.


Supported data sources

Barium Integration Agent supports integration with the following data sources:

  • SQL server databases (Microsoft SQL Server 2005 or later)
  • XML documents
  • LDAP-compatible directory services (LDAP version 3, including Active Directory)
  • Excel documents (experimental support)


Barium Integration Agent communicates with Barium Live over the Barium Live REST API. Many other integration scenarios are possible through the use of Barium Live REST API. Contact a Barium Integration Partner if you need help creating integration with Barium Live.


Deployment requirements

The Barium Integration Agent software is technically a .Net executable service that connects to the Barium Live REST API over HTTPS (port 443) and performs HTTP requests. The requests contains custom HTTP headers used for authentication, content type etc. and string and binary data is transferred between Barium Integration Agent and the Barium Live website.


Pre-installation checklist:

  • Make sure that the server where Barium Integration Agent will be installed has Microsoft .Net Framework 4.0 installed.
  • The server where Barium Integration Agent will be installed must allow outgoing HTTPS connections to https://live.barium.se on port 443.
  • Make sure that the communication Barium Integration Agent and the Barium Live website is not blocked. Note that Barium Integration Agent uses the default proxy settings of Internet Explorer.


Installation

Extract the zip file with Barium Integration Agent into a folder on an application server.


Barium Integration Agent can be run on-demand in console mode or be installed as a Windows service. Make sure to configure the configuration file agent.xml (see the Configuration section) before running the integration agent for the first time.


BariumIntegrationAgent.exe    Runs the agent in console mode
-service Installs and starts the agent service
-uninstall Stops and uninstalls the agent service

Note that Barium Integration Agent must be installed/uninstalled with an administrator account or using "Run as administrator" in Windows.


Configuration

All configuration is made in the file agent.xml in the installation folder of Barium Integration Agent. Each installation of Barium Integration Agent can contain multiple configurations defined by the <config> element.


Pre-configuration checklist:

  • Contact http://bariumlive.com/support and obtain an API key for Barium Live
  • Register a user account on Barium Live and add it to the desired Barium Live space. Make sure that you set the space as the default space for the user (this is required by Barium Integration Agent).


Global settings for a configuration in the <config> element

Example:

<agent version="1.0">
<config id="Test" enabled="true">
<apiurl>https://live.barium.se/api/v1.0</apiurl>
<apikey></apikey>
<apiusername></apiusername>
<apipassword></apipassword>
<datasources>
...
</datasources>
<triggers>
...
</triggers>
<tasks>
...
</tasks>
</config>
</agent>


Setting

Description

id

The unique identifier of the configuration (max 100 characters, no spaces).

enabled

Enables or disables the configuration. Valid values are true or false.

apiurl

The URL to the Barium Live REST API. The default value is:

https://live.barium.se/API/v1.0

apikey

The API key for access to the Barium Live REST API.

apiusername

The username for the user that should access the Barium Live REST API.

apipassword

The password for the user that should access the Barium Live REST API.


Data source settings in the <datasources> element

Example:

<datasources>
<datasource id="MyDatabase" adapter="MSSQL">
<connectionstring>Data Source=DB_SERVER;Initial Catalog=DB_NAME;User Id=DB_USERNAME;Password=DB_PASSWORD;</connectionstring>
</datasource>
</datasources>


Setting

Description

id

The unique identifier of the data source (max 100 ascii characters, no spaces).

adapter

The adapter that should be used in the data source. Valid values are MSSQL, XML, LDAP or EXCEL

MSSQL = Microsoft SQL server database (Microsoft SQL Server 2005 or later)

XML = XML file

LDAP = LDAP directory service (LDAP version 3, including Active Directory)

EXCEL = Excel document


MSSQL adapter settings


Setting

Description

connectionstring

The connection string to a Microsoft SQL server database. 

Example format:

Data Source=DB_SERVER;Initial Catalog=DB_NAME;User Id=DB_USERNAME;Password=DB_PASSWORD;


XML adapter settings


Setting

Description

uri

A URI string referencing the XML document. 

Example formats:

D:\Folder\Data.xml

\\Server\Share\Data.xml

http://server.com/data.xml


LDAP adapter settings


Setting

Description

directoryentrypath

The directory entry path from where the information should be read. 

Example format:

LDAP://company.local/OU=Users,OU=Employees,OU=SE,DC=company,DC=local

company.local is the directory server name.

recursive

Searches the whole subtree, including the base object and all its child objects. Valid values are true or false

username

The LDAP directory service username (with permission to read from the directoryentrypath)

password

The LDAP directory service password


EXCEL adapter settings


Setting

Description

filepath

A fully qualified path to an Excel document. 

Example:

D:\Folder\Exceldocument.xls

\\Server\Share\Exceldocument.xlsx



Trigger settings in the <triggers> element

Examples:

<triggers>
<trigger id="Every10Minutes" type="timer" enabled="true">
<period>0.00:10:00</period>
</trigger>
<trigger id="EveryDay" type="timer" enabled="true">
<period>1.00:00:00</period>
</trigger>
<trigger id="Every12HourFrom23" type="timer" enabled="true">
<duetime>0.23:00:00</period>
<period>0.12:00:00</period>
</trigger>
</triggers>


Setting

Description

id

The unique identifier of the trigger (max 100 ascii characters, no spaces).

type

The type of the trigger. Valid values are timer or signal

timer = Timer trigger, supporting due times and periods.

signal = Signal trigger (triggered from Barium Live process)


Timer trigger settings


Setting

Description

duetime

The amount of time to delay before invoking the trigger. 

Format:

d.HH:mm:ss (Days.Hours.Minutes.Seconds)

period

The time interval between invocations of the trigger. 

Format:

d.HH:mm:ss (Days.Hours.Minutes.Seconds)


Signal trigger settings


Setting

Description

url

The url for the signal source



Task settings in the <task> element

Example:

<tasks>
<task id="MyTask" trigger="EveryDay" enabled="true">
... task actions ...
</task>
</tasks>


Setting

Description

id

The unique identifier of the task (max 100 characters, no spaces).

trigger

The trigger for the task (must be defined in the <triggers> section).

enabled

Enables or disables the task. Valid values are true or false.


Task actions within the <task> element

Task actions are processed in sequence except for the <on> action which captures events within the scope of a task. Many task actions return data which can be accessed using the variable syntax $actionid.variable$, where actionid refers to a task action id, such as the id of a query.


Example of a task that queries a data source, creates new process instances in Barium Live and updates the data source afterwards:

<tasks>
<task id="MyTask" trigger="Every10Minutes" enabled="true">
<query id="Orders" datasource="MyDatabase">
SELECT ID, Name, Article, Amount from Order WHERE Processed = 0
</query>
<foreach queryid="Orders" as="Order">
<sendmessage id="OrderMessage" applicationid="f1fdd395-dd27-426b-abaa-165ca6b3036a" message="NEW_ORDER">
<param name="OrderID">$Order.ID$</param>
<param name="instance.name">$Order.Name$</param>
<param name="Article">$Order.Article$</param>
<param name="Amount">$Order.Amount$</param>
</sendmessage>
<query id="UpdateOrder" datasource="MyDatabase">
UPDATE Order SET Processed = 1, BariumLiveInstanceId = $OrderMessage.InstanceId$ WHERE ID = $Orders.ID$
</query>
</foreach>
<on event="error">
<log>An error occured when processing orders</log>
</on>
</task>
</tasks>


<query>

The query action queries a datasource and loads the query result into memory.

<query id="MyQuery" datasource="MyDatabase" fields="Field1,Field2">
.. query text ..
</query>


Setting

Description

id

The mandatory unique identifier of the query (max 100 characters, no spaces)

datasource

The data source that should be queried (must be defined in the <datasources> section)

fields

(optional) A comma-separated list of fields that should be included in the query result

query text

The query text. Make sure that the query is compatible with the adapter that is configured in the data source. The MSSQL adapter supports the Transact-SQL language including calls to stored procedures. The XML adapter supports XPath expressions (note that the XML adapter is case sensitive). The LDAP adapter support LDAP format filter strings. 

Examples:

MSSQL = SELECT Col1, Col2 FROM Table WHERE Col3 = 0

Queries a database table and selects two columns of data


XML = //Article

Selects all Article nodes.


LDAP = (objectClass=user)

Filters all items with the objectClass "user"


<sendmessage>

The sendmessage action sends a message and parameters to a process application or process instance in Barium Live. Either the applicationid or instanceid setting must be specified.

<sendmessage id="MyMessage" applicationid="ProcessApplicationId" instanceid="InstanceId" message="MessageName">
<param name="instance.name">The name of the process instance, if the message is sent to a process app</param>
<param name="MyParam">MyValue</param>
.. additional parameters ..
</sendmessage>


Setting

Description

id

The unique identifier of the message (max 100 characters, no spaces)

applicationid

(Optional) The process application id that the message should be sent to. Note that the process must include at least one message start event configured as a receive named message with a matching message name for this to work

instanceid

(Optional) The instance id that the message should be sent to. Note that the process must include at least one intermediate message event configured as a receive named message with a matching message name for this to work.

message

The message name, which must correspond to a receive named message in the target process.

parameters

All parameters that should be sent with the message. 

Example:

<sendmessage id="MyMessage" applicationid="ProcessApplicationId" instanceid="InstanceId" message="MessageName">

<param name="param1">value1</param>

<param name="param2">$actionid.variable$</param>

</sendmessage>


<foreach>

The foreach action iterates query result items. The <foreach> element runs the task actions that are defined within the <foreach> action for each query result item. Each task action within the <foreach> element can access the current result item though the iterator variable $iterator.variable$.

<foreach queryid="MyQuery" as="QueryItem">
.. task actions ..
</foreach>


Setting

Description

queryid

The id of the query to iterate result items for. The query action must be defined before the foreach action

as

The iterator variable (max 100 characters, no spaces)

<actions>

The task actions that should be run for each query result item


<on event="eventname">

The on action captures an event within the current scope and runs task actions if the event occurs.

<on event="eventname">
.. task actions ..
</on>


Setting

Description

event

The event to capture. Valid events are:

error = If any error occurs

completed = If all actions are completed successfully

<actions>

The task actions that should be run if the event occurs.


<log>

The log action logs text to the agent log file. The log text can be built up using variables.

<log>
.. log text ..
</log>


Setting

Description

log text

The log text