MARIFlow User Guide

• MARCA
• UMIA
• UMIA_Server
• Trusted Authority Tool
• Process Definition Tool
• Database Initialization
• Key Initialization
• Online Backup Tool
• Super User Tool
• Web Page
• How to Add New Site & UMIA to the scenerio.
• Running a component in test mode.
• Changes
• Bug Fixes

1 - MARCA Configuration

A - Alias Configuration

1. First you should enter information about your site < Alias Name of your MARCA, MARCA Host Name, Marca Mail Address and Outgoing Mail Server >. Then, click Next button.
2. Then, you should enter information about other MARCAs, their host names and aliases.
   Click "Add" button to add a "new site", an empty row will appear, fill that row with the required values.
   Click "Delete" button to delete the selected row.
   Click "Back" button to go to step 1.
   Click "Next" button to go to final step.
3. Finally, you should enter the alias names and e-mail addresses of UMIAs that this MARCA needs to communicate with.
   Click "Add" button to add a "new UMIA" for this MARCA, an empty row will appear, fill in the fields of that row.
   Click "Delete" button to delete the selected row.
   Click "Back" button to go to step 2.
   Click "Finish" button and information will be saved to a file called MARCA_Aliases.cfg.

Note:All aliases should be the same with the aliases that are entered from "Trusted Authority Tool", all blanks in MARCA_Aliases.cfg file are tabs.

B - MARCA Configuration

1. Communication parameters
   Message Port: The port number through which the MARCA listens for the messages. ("7952" is default).
   Incoming Mail Server: POP3 server address through which the MARCA receives mails.
   Incoming Mail Server User Name and password: User Name and Password that POP3 Server (The mail account of MARCA).
2. Database Parameters
   JDBC Driver to be used for the local database: JDBC Driver Class name to be used for the local database.
   JDBC String for the local database: JDBC URL string for the local database of the MARCA.
   Login Name and Password for the local database: Login name and password needed by the MARCA, in order to connect to the local database.
3. System Parameters
   MARCA Path: Absolute path of the directory where the MARCA software runs, it should be installationDirectory/MARCA. installationDirectory is the directory which you installed the software.
   Local Host IP: IP address of the machine that the MARCA will run on.
   Local Host Name: Host name of the machine that the MARCA will run on.
   Debugging Level: Level of detail of debugging information that the MARCA outputs to the terminal.
4. Task User
   UMIA Mail addresses/UMIA Server Address: The list in this part associates given workflows to given UMIAs. When TCP/IP option is selected, UMIAs are identified by their UMIA Server Addresses, otherwise, they are identified by their E-mail addresses. WorkflowName default is reserved for workflows that are not assigned with an address. Hence the workflows which are not assigned an address, use the address defined for default
5. Options
   Disbale Send Task: When selected, send tasks are ignored (i.e Effect of send task is seen but the document is not actually send).
   Record lifetimes of activities: When this option is , lifetimes of each activity is recorded.
   Communication Type with UMIA Server: In test mode, MARCA and UMIA Server can communicate through TCP/IP. When TCP/IP option is selected, list of workflow/E-Mail pairs at Task-User panel is changed to list of workflow/UMIA Server Address pairs.
6. File Menu
   Saving Configuration File: Either choose "Save" from "File" menu or "click" the "Save Icon". Configuration will be saved to the file MARCA.cfg in the installationDirectory/MARCA directory.
   Exit: To exit, choose "Exit" from the "File" menu.

2 - Running MARCA

3 - Running Rescue

4 - Key Initialization

UMIA User Guide:

1 - File Menu

• Document Ready: Inform the MARCA about a document that has been received manually. The user needs to fill the Document Name, Workflow ID and Instance ID corresponding to this document from a dialog window.
• Exceptions: Connection problems between MARCAs. The user can command the MARCA to retry or ignore the operation by selecting the exception from the list and clicking the "Retry"/"Ignore" button.
• New Instance: Creates a new instance. A window will be opened, the user selects the Workflow Name from the "Workflow" selection item and press "OK" button. New instance will be created.
• Options: List of options provided.
  • Enable Auto Commit:When this option is selected, received activity automatically commits.
  • Ignore non-existance of output documents: When selected, no check is made to the activity if its output documents are assigned.
  • Auto assign output documents:When this option is selected, output documen name is automatically assigned by the software which stands under "installationDirectort/UMIA_Server/OutputDocuments/WorkflowID/InstanceID" directory and name of the document is name given in the definition.
  • Enable Autosend function:Enables autosend function.
  • Autosend committed:If this option is selected, UMIA sends the result of the committed activity to the MARCA automatically.
  • Autosend aborted:If this option is selected, UMIA sends the result of the aborted activity to the MARCA automatically.
• Exit: Closes the UMIA.

2 - Applications Menu

• Assigning Applications to Activities: Before any workflow instance is started, you should assign applications to activities which will be executed when the given activity starts at that site. Choose "Assign Activity" from "Applications" menu. The "Activity-Application Assignment" window opens. Proceed as follows:
  1. You can define applications by clicking the "Applications" button, a frame is opened listing applications you have defined so far.
     • Click "New" button to add a new application to the list, a window will ask the Name, full path and the parameters of the application. Fill in the required fields then press "Save" button. The application that is defined will appear in the application list.
     • "Edit" button edits/modifies the selected application information.
     • "Delete button removes the selected application from the list of applications.
     • Click "OK" button when you are finished.
  2. Click "New Activity" button to add a new assignment. You will enter the Workflow Name and Activity Name from the window that will open, and when you click "OK" button, a new assignment will be added to the list with Application field being empty. To assign an application, select the application you want to assign from the column labeled as "Application", if you choose "Automatic" mode, assigned application will start as soon as the user is informed (i.e. mail is received), otherwise it will start when the user clicks start by selecting that activity when it arrives.
  3. "Delete Activity" button removes the selected assignment from the list of assignments.
  4. Click "OK" button when you are finished, assignments will be sent to the UMIA Application Server, if the Application Server cannot receive all assignments succesfully, user will be informed.
• Document Type Assignment-Chosing "Document Types" option from the "Applications" menu, you can define which document is opened using which application. When selected, "Document Types" window opens, Click "New" button to add a new document type along with its viewer appplication. A new empty row will be added to the list, type the extension of document to the "Document Type" column (e.g type "pdf" for pdf documents, and choose "Acrobat Reader" as the viewer application) and choose the viewer application by clicking "Application" button. "Delete" button removes the selected assignment. "Document Type" "default" is reserved, and if no extension matches the document when opening, the default viewer application will be used. To define default application, just add a new row whose "Document Type" is "default" and select to default viewer application. Press "OK" button to finish.

3 - Information

• Involved Workflows: When selected, displays a list of Workflows that the user is involved in, along with the Monitoring Addresses.
• Finished/Incoming Activities: When an activity is finished and MARCA is informed, it is put in another list namely finished activities. List of incoming and finished activities can be viewed by selecting this item from the menu.

4 - List of Activities.

• Start: When selected, starts the application assigned to this activity. If no application is assigned to this activity, user should do it manually and tell the result by selecting ABORT/COMMIT.
• Commit: If no application is assigned to this activity, user can commit this activity manually by selecting this item.
• Abort: Aborts the current activity, if no application is running for it.
• Send: Sends the result of the activity to the MARCA.
• Related Info: Opens related information list about the process. Related Information that needs to be filled in by this application is denoted by "NOTAVAILABLEYET" value. You can modify them.
• Variables: Lists variables that the activity should assign some values (like "pool_empty").
• Output Documents: Displays the list of documents to be returned by this activity. Output Documents Frame contains the following :
  1. Browse: To choose the file/document that will be returned within the result.
  2. View: View the document if it is assigned.
  3. If document will be sent manually: Click the "Will be sent manually" column corresponding to that document. Then MARCA will assume that document is received.
  4. OK Button: Saves changes when you are finished.
  5. Cancel Button: Cancels changes you have made so far.
• Input Documents: Opens a frame that lists Input Documents of this activity. You can view a document if a viewer application is assigned for the corresponding document extension, otherwise you can view it with the default viewer application. If that also does not exist, you will not be able to view the document. Click "Save" button to save the document for further use.
• Switch to Manual Mode: Switchs from the automatic mode to the manual mode for the selected activity.
• Delete: Deletes the selected activity.
• Properties: Displays information about the selected activity. You can also fill the result of the activity (variables returned, Related Info, Output Documents, etc.) by using the buttons at the right side of the window.

5 - Running UMIA

UMIA Application Server User Guide :

Application Execution:

Initialization:

Configuration:

• Incoming Mail Server: POP3 server host name through which the UMIA Server will read mails.
• User Name and Password: User name and password used to connect POP3 server.
• Outgoing Mail Server: Mail server host name from which UMIA will send mails to the MARCA.
• Login Name: Login Name to Outgoing mail server.
• Marca Mail Address: Mail address of the MARCA corresponding to this UMIA.
• Polling Interval: An integer constant that determines how frequent UMIA Server will check for mails (in seconds).
• Enable TCP/IP communication: When selected, UMIA Server tries establishes communication with its MARCA throug TCP/IP.
• MARCA Address : The MARCA host name or IP address should be entered to this field that this UMIA Server belongs to when TCP/IP communication option is selected.
• MARCA Port No :Port Number from which the MARCA that this UMIA Server belongs to listens from.

Running:

Trusted Authority Tool User Guide

1. Information about all MARCAs to be used:
   At this step you will provide all MARCAs at each site with an alias that will be used during encryption/decryption of the messages. You should use the same aliases for each MARCA, that is entered during MARCA configuration at each site. To add an alias, click "Add" button, a window opens for adding the alias information. Enter the alias and the host address of the machine corresponding to that alias and press "Add" button. "Delete" button removes the selected assignment from the list. Click "Next" button to go to the next step.



2. UMIA Aliases and their corresponding MARCAs:
   Click "Add" button to add a new UMIA, give an alias name and select its corresponding MARCA, then click "Add" button. New UMIA alias will be added to the list of UMIAs. "Delete" button removes selected UMIA-MARCA assignment from the list. Click "Next" button to go to next step. When you click "Next" button, a key pair will be generated for the Trusted Authority and the public key will be exported to a file called TAPublicKey.pk (This may take a while). Before running a MARCA at each site, place this file under the installationDirectory/Keys or installationDirectory/MARCA directory by some secure method. Click "Back" button to go to the first step.



3. Transfer of the Key Pairs:
   At this final step, when you press the "Finish" button, a key pair is generated for each MARCA and UMIA you defined and they are encrypted using the private key of Trusted authority. The generated key pairs are send to the corresponding MARCAs. Please be sure that all MARCAs receives the public key file of the Trusted Authority and is started as expected at all sites. To go back to previous step, click "Back" button.

1 - Central Database Initialization :

1. Creating central database using SQL_SERVER
   • Choose SQL_SERVER from "Database Type" combo box.
   • Type the address of machine to the "Database Server Host" field that SQL Server is running on.
   • Type user name and password which has been granted access to create database.
   • Enter the directory that you want your database files to be stored to the "Database File Path" field.
   • Type the monitoring web address for this central database into the "Monitoring Address" field.
   • Enter the database name you want for central database to the "Database Name" field.
   • Click "Initialize" button.
2. Creating central database using POSTGRES
   • Choose POSTGRES from the "Database Type" combo box.
   • Type the address of machine to the "Database Server Host" field that SQL Server is running on.
   • Type user name and password which has been granted access to create database.
   • Type the monitoring web address for this central database into the "Monitoring Address" field.
   • Enter the database name you want for central database to the "Database Name" field.
   • Click "Initialize" button.
   Remark:In order to create database, you should have initial database named "template1".
3. Creating central database by entering Own JDBC String
   • Click "Enter JDBC String" radio button, and type your JDBC URL String to the box corresponding to this radio button.
   • Type user name and password which has been granted access to create database.
   • Type class name of driver you are using to the "Driver Name" field.
   • Type the monitoring web address for this central database into the "Monitoring Address" field.
   • Enter the database name you want for central database to the "Database Name" field.
   Remark:In order to successfully create all tables, your driver should support "setDatabase" function in "Connection" class. Otherwise, driver will silently ignore this command and all the tables will be created using the URL you entered rather than the database created.

2 - Local Database Initialization :

Key Initialization

Before Trusted authority sends all keys to responsible sites, following files must be present at all sites!

• MARCA_Aliases.cfg, under the Keys directory (Alias information about all the other sites and UMIAs corresponding to this MARCA). MARCA matches keys it received with the aliases given in this file, and checks if all the keys it needs are received using this file. Without this file, MARCA will not start.
• TAPublicKey.pk, under the Keys directory (This file holds the public key of the Trusted Authority). With this file, the MARCA can decrypt the keys it receives. Without this file, the MARCA will not start if it is not initialized before.

MARCA Initialization

UMIA Server Initialization

Postgres Backup

Postgres Backup Using Online Backup Tool:

• Select the time interval you want to backup your database (Each day/week/month).
• Select the hour at which you want backup to be taken.
• Browse the directory of the database files that you want to backup.
• Choose a backup directory.
• Click "Finish" button.

Configuration

• User Information:Enter Super User Name and e-mail address.
• Server Information:
  1. Incoming Mail Server:POP3 server host name, from which super user reads his mails.
  2. Outgoing Mail Server:Server host name, from which super user sends his mails.
• Incoming Mail Server:Enter user name and password to connect Incoming mail server.
• Polling Interval:Enter the time interval you want the POP3 Server to be checked for new mails.
• Marca Mail Address:Enter the mail address of the MARCA which this Super user manages.

Usage

Mariflow Web Page :

• Installation Guide.
• User Guide.
• Monitoring Tool.

Monitoring Tool

1. Configuration
   To configure Monitoring tool, type "source configure" on unix and "configure" on windows, under the mariweb/Monitoring_Tool directory. The configuration frame opens. You should enter the necessary parameters to connect to the central database for the process. If you want to enter your own JDBC String, click the radio button labeled "Enter own JDBC String" and enter JDBC URL String into the text field, next to it. Enter User Name, password and Driver class name; Web Address is optional. Otherwise (If you do not want to enter your own JDBC URL String), choose database type, POSTGRES/SQL_SERVER, enter User name, Database Server Host, Database Server Port and Database Name for the central database. Then click "Save" button. Options will be saved to a file named parameterFile.txt.
   
   
2. Usage
   In order to use Monitoring, you should copy "mariweb" directory to your web page (Web page and Database server for the central database must be on the same machine for applet security restrictions). Monitoring address has three fields :
   1. Current System Information:From this field, you can see the list of workflows, current instances, activities and participating sites. Also you can see the state of any instance by clicking on "Instance State Monitoring" Button and selecting the workflow and instance from the list which will be present on the appearing window.
   2. Basic Queries for Certification:You can execute predefined queries for "Certification Process" from here.
   3. User Defined Queries:You can execute any SQL query from this field on the central database.

Adding a new partner and UMIA to the current scenerio

Adding a new partner

1. Click "Add New Site" button on Super User tool.
2. Enter alias name of new site and MARCA address of the new site as configured at new site.
3. Select UMIAs and add all UMIAs that new site will use. (All UMIAs should be configured at new site).
4. Click "Add New Site" button to add the new site when you finished.
5. Click "Exit" button to exit without adding new site.

Adding a new UMIA

1. Click "Add New UMIA" button from Super User tool.
2. Enter alias name for the UMIA and mail address of the UMIA.
3. Click "Workflow Info" tag.
4. Enter workflow names from which this UMIA is responsible for.
5. Click "Add New UMIA" button to add the new UMIA.
6. Click "Exit" button to exit.

Running a component in test mode

CHANGES Since Version 2.0

1. MARCA Recovery: MARCA can be recovered to the state when it is dead, by running MARCA with -r option.
   
   
2. Switching to Manual Mode in UMIA: Each activity assigned to an application can be switched to the manual mode.
   
   
3. Version numbering: Each tool will print its version number by giving an option "-version" to it.
   
   
4. Format of the Alias configuration file is changed for MARCA: Format of Alias configuration file is understandable now.
   
   
5. Close Button added to Alias Configuratoion Tool: Close button added to Alias Configuration Tool, which exits without saving configuration.
   
   
6. Driver for Central Database: MARCA receives driver for central database for each workflow from the process definition int this version rather than sticking to one driver for all processes. MARCA holds driver class names for each process in its local database. For this reason, Local database for MARCA needs to be recreated, it is not compatible with version 2.0.
   
   
7. "Config" and "Keys" directories:Two new directories namely Config and Keys are added to hold the keys & configuration files for each tool/program. Each component will first look at this directories for Keys and Configuration files, if it can`t find here, then it search for it on the current directory.
   
   
8. MARCA Port number: MARCA Port number can be changed now, which was not possible in version 2.0 since it was hard coded in Trusted Autority Tool . Now, Trusted authority tool can be run by giving port number of MARCAs from the command line.
   
   
9. Auto save function for DB Initialization: Auto save function is added to central and local database initialization tools.
   
   
10. Console output for UMIA Server: UMIA Server will output to standard console by running it with "-console" option.

CHANGES Since Version 2.1

1. Adding new partner:Adding a new partner to the scenerio is implemented.
2. Adding a new UMIA:Adding a new UMIA to the scenerio is implemented.
3. Super User configuration:Configuration file for Super User tool is editable with this version with the addition of Marca Mail Address field.

CHANGES Since Version 2.1.1

1. Selectively deletion of activities: It is possible to selectively delete the activities within the UMIA.
2. Finished activities put into a new list: When an activity finishes and its result is send to the MARCA, it is put into a new list.
3. Time information for workflows: Workflows information is displayed with the arrival times to the UMIA from the Involved Workflows section.

CHANGES Since Version 2.1.2

1. Optional Keys: Each component can be run without using security package for testing purposes, by providing -t option.
2. Mail Server Configuration: Mail server can be configured by providing IP Addresses in all configuration files.
3. UMIA: UMIA interface opens without password.
4. Document Types file Format of UMIA: Document types file is editable and named DocumentTypes.cfg.
5. Expression information at Monitoring tool: While blocks, statement blocks and if blocks can be monitored from monitoring tool including state and expression information.
6. Lifetimes of activities: Lifetimes of activities of each instance at each MARCA are recorded to the file named InstanceId/TaskTimes.

CHANGES Since Version 2.1.3

1. Import/Export functions are provided in definition Tool
2. Several options for MARCA, UMIA and UMIA Server are provided.
3. Rescue process is made optional, and a script is provided for unix like systems that will make MARCA to start at boot time when called by OS.
4. Format of tables in Central Database are changed:Format of Central database is changed to identify each MARCA by both hostname and port number, a field indication the port number is added to some tables. So, central database must be recreated.

CHANGES Since Version 2.2

1. Top node in the Monitoring Tool is given the Workflow name rather than "Coordinator".
2. Input&Output Document List Frames in the UMIA are made resizable.

Bug Fixes

Since Version 2.0

1. Incompatibility between Definition Tool an Monitoring: It was now possible to monitor a process including while block with version 2.1 which was not possible in version 2.0.
   
   
2. Format of date in mails of UMIA: UMIA Server is now able to read the e-mails it receives from MARCA, which was not possible in version 2.0 due to the locale difference in Germay and Turkey and now in version 2.1 software is locale independent.
   
   
3. Domain Definition in Process Definition Tool: When defining domains in Process Definition Tool, it is now possible to use "-" character, which was not possible in version 2.0.
   
   
4. Key file for Super User may not be created: At key initialization phase, key file of Super User is created which was not possible in version 2.0 because of the file name incompatibility.
   
   
5. Definition Tool unable to open saved definition including while block: Definition tool is now able to open saved definitions including while blocks which was not possible in version 2.0.
   
   
6. Web page doesn`t work with Internet Explorer: It was not possible to click links on the web page using internet explorer in version 2.0. Now, it is possible with this version (2.1).

Since Version 2.1

1. MARCA Config File:MARCA was unable to open configuration file from "Config" directory with version 2.1. It can open "MARCA.cfg" file from "Config" directory.
2. Involved Workflows section in UMIA:OK button doesn`t work at Involved Workflows section in UMIA, with this version it closes the window.

Since Version 2.1.1

1. Saving input document of an activity:It was not possible to save input document of an activity from the UMIA with the old versions, with this version it is possible.
2. Mail Receiver was unable to decode attachment:Mail receiver was unable to decode files attached from different platform with old releases, now it can open all the files attached.

Since Version 2.1.2

1. Generates/Returns fields of activity in Definition tool:When an activity choosen to generate/return something, old information about returns/generates fields of that activity was lost with the old versions, it is now fixed with this version.
2. Comment format in MARCA config file:Comments can be entered by putting '#' character at the beginning of each line to be commented out. Old versions accepts comment anywhere preceeded by '#' character, which creates problem when user has '#' character in password field.
3. Reconstruction:MARCA reconstructs workflow definition by looking only at host name, however definition might be send using IP Address. So, MARCA was unable to be reconstructed when definition send using IP Address of the machine, with this version the bug is fixed.
4. While Block in Monitoring Tool:There was a small displacement in drawing when definition send contains while block in Monitoring Tool. It is fixed with this version.
5. While Block in Definition Tool:Lines of while block crashes with block under the while block if there is a parallel block under it that has enough width. The bug is fixed with this version.

Since Version 2.2

1. UMIA Server could not run Windows batch files properly:In earlier earlier versions, windows batch files couldn`t be run properly by the UMIA Server due to limited output buffer size for batch files under Windows OS. With this version, output of the processes are taken while the process is running to make batch files to run correctly.
2. Empty fields in Application Assignment:Saving assigned application with empty fields may cause Application Assignment not to open further with the older versions. It is fixed with this version.

Compatibility with old version

Since Version 2.0,

Since Version 2.1,

Since Version 2.1.3,

Since Version 2.2,