Configuration
All configuration is made in the file agent.xml in the installation folder of Business Integration Agent. Each installation of the Business Integration Agent can contain multiple configurations defined by the <config> element.
Pre-configuration checklist:
- Contact Process Automation Support and obtain an API key for InRule Process Automation
- Register a user account in Process Automation and add it to the desired space. Make sure that you set the space as the default space for the user (this is required by Business 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 Process Automation REST API. The default value is: https://live.barium.se/API/v1.0 |
| apikey | The API key for access to the Process Automation REST API. |
| apiusername | The username for the user that should access the Process Automation REST API. |
| apipassword | The password for the user that should access the Process Automation 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 a Process Automation 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 Process Automation 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 Process Automation. 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 |