Working with Configurations
A TrustBuilder Configuration (TB Config) is the collection of resources that the TB Engine uses to function. These include the following:
|Configuration file||Here adapters, workflow references, license, security keys and services are defined.||Yes.|
|Workflow file||The workflow perfomed by the TB Engine against an incoming request||Yes at least one.|
|Script files||Scripts that are used by the workflow||No|
|Template files||Templates, such as login page, that are used by the scripts to render pages||No|
|Layout files||These are TBA representations of workflow files||One for each workflow|
|Logging||This is the logging configuration for the TB engine||No|
|Properties files||TrustBuilder can be configured using a .properties file||No|
All of these items can be created/imported and edited within TBA.
Adding a New TrustBuilder Configuration
|Form Field||Description||Is Required?|
|Configuration Name||An identifier for the configuration||yes|
This is a comma delimited list of tags that can be used to filter the view of TB Servers.
Used only by TBA
|Description||A description of the TB Server, used only by TBA.||no|
Once the form is saved a new unrelated configuration is created.
This configuration has an expired license no adapter, workflows, scripts, templates or services.
Import a New TrustBuilder Configuration
To import a TrustBuilder Configuration from an already established TB Server first create a TB Server pointing to the correct host and management port.
Then click the Options button on the TB Server box, and then import.
A new configuration will then be created and all the files found in TB_HOME of the server will be imported. The configuration will be automatically related to the TB Server that imported it.
Upload a New TrustBuilder Configuration
Configurations can be packaged and zipped from the TrustBuilder Administrator (TBA). Naturally the application offers the option to upload and import packaged configurations also. This function will only accept configurations that are packaged by TBA for 100% compatibility package and upload using the same versions of TBA. This is a secure way of sharing configurations if network restrictions apply.
To upload a packaged config click the Upload Config Zip button.
On the next screen select the configuration zip file from you local computer.
Then click the Upload & Import button. You will then be taken to the configuration editing screen with everything imported. A new unrelated configuration block is created on the Server screen named ID-uploadedConfig
Enabling Export for a Configuration
In order to export a configuration it must first be related to one or more TB Servers. To do this drag and drop a configuration box onto a TB Server box.
The TB Server box will then be coloured green and hold the id and name of the configuration that it is now related to. The configuration box will be coloured blue.
To see which TB Servers are related to a specific configuration move the mouse over the configuration box and the related TB Servers will be coloured blue.
The same applies if the mouse is moved over the name of a configuration within a TB Server box, the relevant configuration is then coloured green.
To break the relationship between a configuration and TB Sever click the rubbish bin icon on within the TB Server box to the right of the configuration name.
Once a configuration is related to at least one TB Server export buttons are displayed when editing the configuration.
Exporting Configuration from Server Screen
Once a configuration is related to one or more TB servers on the server screen then it can be exported. An export button will show on the configuration block. Click this button to export to all the servers that this configuration is related to. The standard export form will be displayed.
Exporting Configuration Whilst Editing
The complete configuration can also be exported during editing by clicking the Export All button at the top right of the configuration edit screen.
A configuration can be downloaded from the configuration editing screen. This will produce a zip package containing the complete configuration. This zip package can be used on the Servers screen to import into another TBA installation or distributed to a TB_HOME manually.
Deleting a Configuration
To delete a configuration click the delete button within the configuration box. This action is not reversible there is no undo.
When a configuration all of it's relationships with TB Servers are broken. Those TB Servers are then left unrelated.
On the first tab of the configuration screen are general details directly related to the configuration.
This is the same as the description that can be entered from the Config & Servers screen and is only used within TBA.
This is the TB Engine license. If this is a newly created configuration it will be an expired license.
To enter a new license click the Update button within the license box.
A form will then be displayed to past a new license key into.
Click the Save button to update the license or cancel.
These enable or disable extra functionality of the TB Engine. Each extension is described by moving the mouse over the question mark icons to the right of each label.
The security element of the configuration is for storage of any certificates that may be called by adapters or from scripts.
Two stores can be configured; a key store and a trust store. Both are secured by a password that is automatically encrypted.
From a security point of view, it is recommended to make a clear distinction between a trust store and a key store:
- A trust store only contains public certificates making it ideal to share with other people.
- A key store does contain private keys, which must be kept private.
Both stores must be of the same protocol and format.
The key store is used as trust store if no trust store has been defined.
More details of each input field can be viewed by mousing over the question marks beside each label
The TrustBuilder Administrator does not currently provide any interface to these key stores.
There are many 3rd party tools available that already fulfil this task such as:
- Portecle ( http://portecle.sourceforge.net/ )
- Keytool ( http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html )
- CERTivity Keystores Manager ( http://www.edulib.com/products/keystores-manager/overview/ )
Stores are uploaded from the local computer to the configuration in TBA. To upload a store:
- select a jks or p12 file
- provide the password for that store.
- click upload
Once the store is uploaded more buttons are displayed:
Offers the functionality to download the store that TBA has for this configuration
Delete the store from TBA.
Export the store to the servers that this configuration is related to. This button will only be displayed if this configuration is related to one or more servers. The store is also exported if the Export Complete Configuration is also used.
This will import a store from a remote TrustBuilder Server. This will overwrite and store that is in TBA.
The Save button will only save any changes made to the Key Store Password or Trust Store Password fields.
The adapters tab is where adapters can be added, edited and deleted for a single configuration.
Add a new adapter by clicking the Add Adapter button at the top of the adapters tab.
This will display a form. Select the type of adapter that is to be created from the select list.
Then the appropriate form will be displayed.
Complete the form. Each label of the form has a question mark icon. Move the mouse over the question mark for details of what data is expected for each field.
Note that fields marked with an asterisk (**) are required and those marked (numeric*) will only accept numeric values.
Once the form is complete click the Submit Form and Create Adapter button. The form will be validated before submission and any issues highlighted.
Any password fields will be encrypted locally within TBA so no passwords are stored or transmitted over the wire in plain text. On export the TB engine will determine if the keys need to be encrypted using a local master password if one has been configured for each specific TB server. For details of master passwords refer to the hardening and password encryption chapters.
Beside each label within an adapter form is an override checkbox. If this box is checked it means that the value can be replaced when the configuration is exported.
For example the JDBC adapter has an entry for DataSource. This is the name of a datasource that is configured in the application server.
This datasource name may be different in the development and test environments but this same configuration is to be used in both environments.
In this instance checking override will allow the datasource name to be overridden by a value set in the config-override.properties file.
On export the configuration is checked to see if any data is to be overridden and a form is provided to enter the value for each TB Server that is to be exported to.
So for the development TB Server a value of jdbc/devDS can be entered and for the test TB Server a value of jdbc/testDS can be entered.
These values will then be written to the config-override.properties file when the export is made to each server.
When the engine is started it will use the value defined in the config-override.properties file.
Any value that is entered in the DataSource field will be ignored when the engine loads the configuration.
To edit an adapter click the Edit button beside the adapter in the list.
The same form that is displayed when adding will be presented with the values populated.
To view the entry that will be made in the configuration for a specific adapter click the adapter name to reveal the XML. Click it again to hide it.
To delete an adapter click the Delete button beside the adapter in the list.
Deletion of an adapter is final, there is no undo.
Services are comprised of Java code that can be used in scripts enabling more complex functionality.
Some services can also be used as endpoints to accept incoming requests such as the LDAP or Radius service.
All types of services, endpoint or normal, are configured in the TrustBuilder Administrator in the same manner.
There are a number of pre-packaged services that come with TrustBuilder refer to the services documentation.
Add a New Service
To add a new service click the Add Service button.
Complete the form and click the Save Service button.
|Field Name||Description||Is Required?|
|ID||This is the id that is used to reference the service from within a script when calling tb.getService("thisID");||yes|
This is the Java type a full package and class name.
Refer to the services documentation for the pre-packaged types for examples.
|Should be a Singleton||If there is to be only one instance of this class created on the server and used by each request||no|
|Should be Synchronised||Lock the use of this class so it can only be accessed by one thread at a time||no|
|Service Properties||These are properties that are passed to the service such as charSet for the DomTai service||by some services|
Edit a Service
To edit a service click the Edit button beside the service in the list. The add form will then be presented with the values populated.
Note that the ID cannot be edited as this is a reference to the service within the configuration.
Delete a Service
To delete a service click the Delete button beside the service in the list.
The deletion of a service is final, there is no undo.
Add, edit, upload, convert and delete workflows.
Add New Workflow
To add a new workflow click the Add New Workflow button.
This will open a form, complete the form and click the Add New Workflow button.
|Workflow ID||This is the ID of the workflow that will be used by the configuration as a reference.||yes|
|Make Draft Workflow||Select this to create a work in progress workflow that will not be validated on save and not exported.||no|
Once the workflow is added the workflow editing screen is displayed to begin creating a workflow.
Upload and Import Workflow
If you have received a workflow from an external source this can be added to the current configuration but uploading it.
Click the Upload and Import Workflow button. A new screen will be displayed with a form.
|Field Name||Description||Is Required?|
|Layout File Name||This is the name of the XML file that will be created by TBA which is a representation of the workflow.||yes|
|Workflow ID||This ID will be used by the configuration to reference the workflow||yes|
|Select Workflow File||Here select the workflow.xml file that you have from your local machine.||yes|
|Select Existing Layout File||
If a layout file has also been supplied with the workflow.xml file this can also be uploaded.
This will automatically format the layout of the workflow to this file.
If no layout file is supplied then the workflow will be converted by TBA as per a usual import.
Once the Import button is clicked then the workflow will be uploaded and the workflow console screen displayed with the new workflow.
If a configuration has been imported all the workflow files are also imported.
For any imported workflow to be used within the TrustBuilder Administrator it must have a layout file that represents the workflow in a graphical manner.
If an imported workflow is imported without a layout file the option to create a layout file will be provided.
Click the Convert to Layout button and a form is presented, click the Import button to import the workflow and the workflow console will be displayed:
|Form Field||Description||Is Required|
|Layout File Name||Name of the layout file that is to be created||yes|
|Select Existing Layout File||
If a layout file has been provided it can be uploaded from the local machine.
If it is valid this layout file will be used to arrange the workflow activities and connections.
Workflow Is Only Sub-Workflow
If a workflow is only to be used as a sub-workflow; one that is only referenced from a parent workflow and not directly from an incoming request, then it can be marked that it is only to be used as such.
This is done by ticking the check box under the Only Sub heading in the relevant workflow row in the list.
A workflow that is not only a sub-workflow can be used as both; either a parent workflow or a sub-workflow.
The type of the workflow, which can define it's purpose and use, can be specified by selecting one of the available types from the Workflow Type drop down box. When the type is selected the configuration is saved immediately.
If a workflow is created or saved as a draft workflow. A draft workflow is one that can be invalid and is not validated upon save, is not exported or added to the configuration file. In this instance the row is highlighted orange.
Delete a Workflow
To delete workflows check boxes beside the workflows that you wish to delete and then click the Delete Selected button.
Deletion of a workflow is final, there is no undo.
Export a Workflow
If this configuration is related to one or more servers an Export Selected button will be available. To export a single or number of workflows check the box to the left of the workflow row that is to be exported and then click the Export Selected button. The standard export screen will then be displayed.
Exporting a workflow only exports the workflow XML file not any scripts related to that workflow or the configuration file. If a new workflow has been created then the configuration file needs to be exported also so that the engine is aware of the new workflow.
Changing the Workflow ID
It is possible to change the workflow ID by clicking the ID. This will display a single form input to change the workflowID.
The tests tab allows for the creation of workflow tests to run a workflow against the TB Engine before exporting it or deploying it. This will reduce the risk of deploying a faulty workflow or script.
Mocks are created for each adapter and sub-workflow within a workflow and these are used during the test. So for instance a real LDAP server is not needed as the response from the server can be mocked.
Tests are created by the TrustBuilder administrator for each workflow. The adpaters and sub-workflows are initially mocked automatically.
The test area allows the tests to be run within TBA so no TrustBuilder instances need to be created in order to run a test just the Run Test button needs to be clicked within TBA.
Create a Test File for a Workflow
For each workflow there is a row in the tests tab.
To create a test file click the Create Test File button.
This will create a test by reading the workflow.
For each adapter activity found in the workflow a mock adapter will be made.
For each sub-workflow activity found in the workflow a mock sub-adapter will be made.
Mocks allow for mocking responses so that a real adapter does not need to be called to run the test.
For instance if there is an LDAP adapter in the workflow a mock adapter can be created that will return a specific user in the adapter response which the workflow can then process.
This means that an LDAP server does not need to be installed just to run a test.
For each adapter activity a mock adapter is created in the test. Each mock adapter is represented as a form in the Adapters tab of the test file.
|Field Name||Description||Is Required?|
This is the status returned in the response from the adapter.
The default is 0 meaning OK.
Check the adapter documentation for relevant response status codes
This is the sub status returned in the response from the adapter.
The default is 0 meaning OK
Check the adapter documentation for relevant response status codes.
|Message||This is a message that will be added to the response.||no|
This is the return code in the response from the adapter.
The default is OK
Check the adapter documentation for relevant return codes.
|Properties||Name value pair that will be added to the response.||no|
To add extra properties to a mock adapter click the Add Property button. To delete a property click the rubbish bin icon beside the name entry of the property.
If changes are made click the Save button.
For each sub-workflow activity a mock sub-workflow is made in the test file.
The form for the mock sub-workflow has one input which is return. If a value is entered this is what will be returned from the sub-workflow when the workflow is run.
For each mock adapter a test is created by default.
New tests can be created by entering a name for a test in the input box at the top of the test name tab and then clicking the Add New Test button.
There is a form for each test:
|Form Field||Description||Is Required|
|Parameters||This is data that will be passed to the workflow when it is tested as request parameters||yes, null is acceptable|
|Headers||This is data that will be passed to the workflow when it is tested as request http headers||yes, null is acceptable|
|Cookies||This is data that will be passed to the workflow when it is tested as request http cookies||yes, null is acceptable|
|Body||This is the body of the request that will be passed to the workflow when it is tested||yes, null is acceptable but no usual|
|Assertions||These assertions will be tested once the call to the workflow has been run.||yes at least one|
|Assertion: Variable Name||This is the name of the variable to be tested||yes|
This is the type of assertion if the resulting value is to be exactly or to match.
Match can be used with regular expressions.
|Assertion: Value||The value that is expected||yes|
The value of evaluations will be run when the test is run.
This is commonly used to add a log line such as marking the beginning of the test.
For more details and examples regarding these fields please refer to the testing your workflow documentation.
To add new assertions click the Add New Assertion button. To delete assertions click the rubbish bin icon to the right of the value entry.
To add a new evaluation click the Add New Evaluation button. To delete evaluations click the rubbish bin icon to the right of the input box.
To delete a test click the Delete button in the bottom right hand corner of the relevant test box.
If changes are made, including adding/removing assertions and evaluations then the test must be saved by clicking the Save button in the bottom left hand corner of the test box.
Editing a Test
To edit a test click the Edit button in the list of workflow tests in the relevant row.
Deleting a Test
To delete a test click the Delete Test button in the list of workflow tests in the relevant row.
If a test is deleted but the workflow remains then a new test can be created by clicking the Create Test File.
Running a Test
To run a test click the Run Test button in the list of workflow tests in the relevant row.
Running a test will open the test results screen showing a summary of test results and the output log from the TB Engine when it run the test.
If the test failed for any reason: such as an error in a script, workflow or the configuration, the log will be displayed so that the error can be diagnosed and corrected.
If there are not errors from the engine and it can run the tests then there will be results detailed counting the number of tests run, passed and failed.
If there are failed tests the results of the failed assertions will be printed in an errors list.
If the tests run successfully this is displayed.
The scripts tab allows direct access to scripts.
Adding a New Script
To add a new script click the Add New Script button. This will open a form dialog. Enter the path and script name to be created. The script must have a .js extension.
Scripts are created relative to the root where the configuration is stored, the root of TB_HOME when exported.
Editing a Script
To edit a script click the Edit button in the relevant script row.
This will open the script editor in a new window.
Deleting a Script
To delete scripts check the box beside each script that is to be deleted. Then click the Delete Selected button.
Deletion of scripts is final, there is no undo.
Importing a Script
If the configuration is related to one or more TB servers on the Servers screen then Import and Import All Scripts buttons are visible.
Clicking an Import button in a script row will open the standard import screen to select which server to import the script from. If the script is found in the TB_HOME of the selected server then it will be imported replacing the script in TBA.
Clicking the Import All Scripts button will display the standard import screen to select which server to import scripts from. If any scripts are found in the TB_HOME of the selected server then they will be imported into TBA.
If scripts that are already in TBA are imported they will be overwritten. This is final with no undo.
Exporting a Script
If the configuration is related to one or more TB servers on the Servers screen then an Export Selected button is available on the scripts tab. To export one or more scripts check the box to the left of the script row(s) and click the Export Selected button. The standard export screen is displayed.
Scripts can also be exported from within the script editor
The templates tab allows direct access to templates.
Adding a New Template
To add a new template click the Add New Template button. This will open a form enter the path and the template name. Accepted file extensions are displayed above the input box.
Templates are created relative to the root where the configuration is stored, the root of TB_HOME when exported.
Editing a Template
To edit a template click the Edit button in the relevant template row.
This will open the template editor in a new window.
Deleting a Template
To delete a template check the box beside each template to be deleted. Then click the Delete Selected button.
Deletion of templates is final, there is no undo.
Importing a Template
If the configuration is related to one or more TB servers on the Servers screen then Import and Import All Templates buttons are visible.
Clicking an Import button in a template row will open the standard import screen to select which server to import the template from. If the script is found in the TB_HOME of the selected server then it will be imported replacing the template in TBA.
Clicking the Import All Templates button will display the standard import screen to select which server to import templates from. If any templates are found in the TB_HOME of the selected server then they will be imported into TBA.
If templates that are already in TBA are imported they will be overwritten. This is final with no undo.
Exporting a Script
If the configuration is related to one or more TB servers on the Servers screen then an Export Selected button is available on the templates tab. To export one or more templates check the box to the left of the template row(s) and click the Export Selected button. The standard export screen is displayed.
The logging tab exposes the logging configuration file that is used by the TB engine. This defines what level of logging the TB engine will perform and the manner that the logging is written.
Editing the Logging Configuration
The logging configuration is a configuration file that is provided by the logging mechanism that the TB engine uses called Logback. For documentation using Logback refer to the Logback website:
Changes can be made directly to the logging file and saved by using the save button on the logging tab.
When a new configuration is created a default logging configuration is provided.
Exporting the Logging Configuration
The logging file is exported when the configuration is exported and is also available in the zip package when downloaded.
The TB engine optionally uses a trustbuilder.properties file. For instance when enabling session management. This can be created and edited in the properties tab. A file with a .properties extension is a standard Java mechanism for key value pairs. Other property files can also be created and edited in this tab.
Creating Property Files
New property files can be created by clicking the Add New Property File button. A form is presented. Enter a name for the property file and click the Submit button.
Editing Property Files
Property files can be edited by clicking the Edit button beside the property file. This will open a text editor.
Deleting Property Files
To delete a property file check the box to the left of the property file to be deleted then click the Delete Selected button. A confirmation will be displayed.
Note that deleting a template is final
Exporting Property Files
If a configuration is related to one or more TB servers on the Servers screen then an Export Selected button will be displayed. Check the box to the left of the property files that are to be exported then click the button. The standard export screen will then be displayed.
Importing Property Files
If a configuration is related to one or more TB servers on the Servers screen then an Import All Property Files button will be displayed. Clicking this button will display the standard import screen. Select the server to import from and then click the OK Import from Selected Server button. If there are any property files in the TB_HOME of the server that is selected then they will be imported into this configuration.