FRENDS Iron Documentation

Contents

• Getting Started
  • Introduction to FRENDS Iron
  • What is FRENDS Iron?
    • Enabling batch processing
    • Batch features also streamline other development
    • Highly extensible process model
  • Installing FRENDS Iron
  • Starting the FRENDS Iron processing engine service
  • Running your first FRENDS Iron execution
    • Set up BizTalk for handling FRENDS Iron messages
    • Create a FRENDS Iron routine for sending messages to BizTalk
    • Run and monitor routine execution
• Developing FRENDS Iron Solutions
  • FRENDS Iron Process model and elements
    • Routines
    • Managing Routine Elements
    • Tasks
    • Schedules
    • Connection points
    • Connection point groups
  • Technical details
    • Creating your own task workflows
    • Workflow persistence
    • Tracking activities
    • Ready-made WF elements
    • BizTalk Server integration
  • Troubleshooting
    • Finding the reason for the error: viewing logs
    • Contacting FRENDS Support
    • Common errors and fixes
• FRENDS Iron Management
  • FRENDS architecture
  • Providing high availability for FRENDS Iron host
  • Configuring FRENDS Iron
• Version history

Getting Started

This section provides you with guidelines on how to get started with FRENDS Iron. It provides you with the installation instructions and a general introduction to FRENDS Iron, with links to topics for more detail.

Introduction to FRENDS Iron

FRENDS Iron is a next generation process management and systems integration product developed by Frends Technology. It provides enhanced integration options for a customer while being based on latest industry standards. It utilizes latest integration technologies such as full support for XML and Web Services standards, BPEL for process orchestrations as well as various transformation technologies.

FRENDS Iron is designed for a heavy-duty process-based integration tasks. It can communicate with a large set of enterprise applications but its connection features scale down easily to include embedded devices, small databases, point-of-sale (POS) systems etc. It can communicate with systems based on modern technology such as .NET or J2EE, but it also provides tools to access data and functionality in legacy systems such as SAP or mainframes. FRENDS Iron provides both message-based brokering capabilities as well as tools for batch-based transfers. In addition to this, it provides basis for advanced human workflow management as well as tools for real-time management reporting.

FRENDS Iron consists of three functional parts:

• FRENDS Iron service, which triggers and parameterizes BizTalk executions
• Microsoft BizTalk Server 2006 R2 /2009 which provides business process management (BPM) and integration broker functionality
• Microsoft SQL Server 2005 or 2008 database for storing needed business data and FRENDS Iron control data.

What is FRENDS Iron?

FRENDS Iron is a stand-alone scheduling and triggering engine integrated with BizTalk Server that provides several new features on top of it.

Enabling batch processing

FRENDS Iron is a flexible and versatile tool. It is primarily meant for enabling enterprise batch processing on BizTalk, especially to systems with multiple passive endpoints that you need to send data to or receive data from.

Currently, BizTalk does not handle the following situations well:

• You cannot schedule business processes to run at specific times. You can only define schedules for receive locations and send ports. These schedules can only be open once a day. Say you need to schedule a batch to run four times a day, every six hours, and only on workdays - you need to create your own scheduler. You also need to have some kind of message to actually trigger the execution, so you need a process of your own to create the message and send it to the receive location, like a script scheduled using Windows Task Scheduler
• Defining and managing endpoint groups to send data can be tedious, especially with multiple groups and more than 10 send ports in a group – the send ports need to be added to the group one by one. When removing a send port from many groups, you need to remove them one by one.
• Only one-way send ports can be grouped – there is no way to get a response from multiple endpoints. Solicit-Response from multiple endpoints requires loops and dynamic ports in an orchestration.
• Monitoring executed batch processes with multiple sub-processes can be a pain: the process execution details can be found in HAT or BizTalk Explorer queries, but how will you know which processes belong to the same batch? Grouping different batch processes to BizTalk Applications can give some relief (but forces you to purchase the Enterprise version of BTS)

FRENDS Iron provides the features needed for the above mentioned situations:

• You can define and reuse complex schedules easily: schedules can have different time windows, with individual settings for season, recurrence, open days and delay.
• Endpoints can be easily grouped, e.g., dynamically using a query.
• As the endpoint configuration and process triggering is external to BizTalk, you can reuse simple BizTalk orchestrations to handle solicit-response message exchanges with any port type.
• All execution data and parameters of executed schedules, triggers and processes are stored in a single database - all grouped together. The batch execution status per each process can be monitored easily from the user interface or a custom reporting site. Failed executions are easily noticed and, as all their data is stored to the database, the reason for the failure can be analyzed quickly.

Batch features also streamline other development

You can also use FRENDS Iron for other business tasks.

• The need for doing things according to a schedule is not limited to batch processes. For instance, maintenance processes can be scheduled to run on specific dates and times. With FRENDS Iron, you can also schedule BizTalk receive locations and send ports.
• You can launch BizTalk processes from FRENDS Iron UI simply by clicking a mouse button.
• The messages sent to BizTalk can be easily defined and maintained in FRENDS Iron connection

Highly extensible process model

As FRENDS Iron uses its own process engine, the actual triggering process can contain any number of custom steps, e.g., fetching data from a local database or file and publishing execution results to a server or via email. In fact, FRENDS Iron can be used independently of BizTalk for simple processes that would be cumbersome to do with BizTalk and usually would be done with custom code.

Installing FRENDS Iron

FRENDS Iron is installed using a Windows Installer installation package. It installs the needed libraries and executables. After installing, you need to run the Configuration Tool to set up the Windows services, databases and other settings. The installer suggests you do this at the end of the installation.

Please see the accompanying Readme file for up-to-date information on the installation and basic configuration. For details on how to configure FRENDS Iron, see section Configuring FRENDS Iron or the FRENDS Iron Configuration Tool Documentation.

Starting the FRENDS Iron processing engine service

Normally the service is first started by the configuration tool or on system startup, but if for some case the service is not running, you can start it manually.There are multiple ways of starting the FRENDS Iron service, you may for example use the FRENDS Iron Management console, command line or Window's Services applet. The following images show how to accomplish this.

In the management console: Right click the FRENDS Iron node on the left pane and select Start FRENDS Iron service.

In the Services applet: Open the Services apllet and find the FRENDS Acc Service service from the Services list. Right click it and select Start.

Commandline: Open a commandline prompt with administrative rights (Run as administrator) and write the following command: net start FrendsAccService

Running your first FRENDS Iron execution

It is usually best to start learning a new technology by looking at an example. So, let's start simple: sending a message to BizTalk Server. There are ready-made FRENDS Iron tasks and routines for this, so you don't have to dive too deep into the specifics of FRENDS Iron.

Set up BizTalk for handling FRENDS Iron messages

You need to make BizTalk handle the messages FRENDS Iron sends to it. To do this, you first create a receive location and a receive port to receive the messages, and then a corresponding send port for passing the message onwards. For this sample, the receive location will use the FRENDS Iron Submit adapter, and the send port uses the file adapter.

NOTE: You can use a premade bindings file to import the sample port settings to BizTalk. The bindings file, Sample1_Bindings.xml can be found in the /Help/Samples directory under the installation directory.

First, you need to create a receive port and location:

1. Open the [Name] > Applications > BizTalk Application 1 > Receive Ports.
2. Right-click on the Receive Ports node and choose New > One-way Receive Port... from the menu.
3. In the Receive Port Properties dialog, give the receive port a name, like 'FRENDS In Port'.
4. Choose Receive Locations from the list on the left side of the dialog, and click New... to create a new receive location on the receive port.
5. In the Receive Location Properties dialog, give the receive location a name, like 'FRENDS In Location'.
6. Select Submit as the Transport Type from the combo box, and click Configure....
7. In the Submit Transport Properties dialog, give the Uri property a unique value, like 'FRENDSTest'.
   

   NOTE: This value is used for passing the message from FRENDS Iron to the correct endpoint, and is needed for configuring the FRENDS Iron task later on, so write this value down or memorize it.

8. Click Ok in all dialogs. The receive port and location are added to the lists.
9. Right-click on the newly created receive location, and choose Enable to allow the receive location to receive messages.

Then, you need to create a send port with subscription:

1. Open the Send Ports view, right-click on the list background and choose New > Static One-way Send Port...
2. In the Send Port Properties dialog, give the send port a Name like 'FRENDS Send Port', set the Type to 'File', and click Configure...
3. In the FILE Transport Properties dialog, set the Destination Folder to some folder on the local machine that the BizTalk server can write to. Click Ok.
4. Choose the Filters view from the left of the FILE Transport Properties dialog, and click on a new row in the table to create a new filter.
5. In the new filter row, set the Property value to 'BTS.ReceivePortName' and Value to 'FRENDS In Port' (or what you used when creating the receive port), both without the single quotes.
6. Click Ok. The new Send port is added to the list.
7. Right-click on the newly created Send port, and choose Start to create the subscription (enlist) and allow the port to write the messages to the given folder.

Create a FRENDS Iron routine for sending messages to BizTalk

Once the BizTalk Server is set up, you can send messages from FRENDS Iron by just creating a Routine and starting it up.

For this example, you can use the ready-made task for sending a sample message as follows:

1. In the FRENDS Iron Management Console, open the Routines view.
2. Right-click on the Routine view and choose Add new Routine from the menu.
   
   
3. In the Add Routine dialog, give the routine a Name, like 'Send BTS message'.
4. Add a new Task by clicking the Add button and choosing the 'BizTalk One-way call' task from the list.
   
5. Activate the Task arguments tab and set the parameters as follows:
   1. Set the URI parameter to the BizTalk receive location URI you defined in “Set up BizTalk for handling FRENDS Iron messages”
   2. Set the InMsg parameter to some XML string value, like '<FOO/>' - the BizTalk orchestration will just pass this string to a message structure.
6. Leave the other fields to their default values and click Ok. A new routine node is added to the Routines view.

You have now created a routine with the following properties:

• Task: BTS One-way call - When run, the routine executes this task that sends a message to BizTalk; basically, the ready-made Windows Workflow Foundation workflow is executed with the specified parameters. The task parameters defined directly, so no connection point data is used. Later on, you can use connection points and connection point groups to parameterize the routine tasks in a flexible way.
• Schedules: <empty> - The routine does not have a schedule, so you need to start it manually.

Run and monitor routine execution

Once you have set up BizTalk Server and the routine, you can test the actual execution of the routine and check the results.

To start the routine:

1. In the FRENDS Iron Management Console, open the Routines view.
2. Right-click on the routine node you created, and choose Routine Actions > Run Once from the menu. The routine is started.
3. Go to the Routine instances view for the routine by clicking on the routine node. Refresh the view if you do not see any rows by pressing F5, or choosing the Refresh from the right-click menu

From the Routine instances view you can see if the task execution was successful: if it was, the view will show a green icon and the state ‘Ok’.

You can view the details of the execution by right-clicking on the task instance row and choosing View execution. This brings out the workflow monitor tool that shows the flow of execution in the task and the parameter values of all executed activities.

Developing FRENDS Iron Solutions

This section provides you with the information needed for successfully working with FRENDS Iron solutions.

Creating a new FRENDS Iron process is straight-forward, as demonstrated in the Getting Started: First create a new routine and choose the elements you need for it, such as a task to execute and the schedule to use. Then just start the execution manually or activate the routine to be executed according to the schedule.

However, when creating and modifying your own tasks, schedules and other FRENDS Iron elements, first you need to have a basic understanding on the FRENDS Iron process model and elements, which is the topic of the next section. After that, you may want to look more closely to the technical details of FRENDS Iron, for instance on topics FRENDS architecture.

FRENDS Iron Process model and elements

Even though FRENDS Iron primarily uses BizTalk Server to execute business processes, FRENDS Iron also has a process engine of its own. The process engine uses Windows Workflow Foundation (WF) as the core engine. This allows easy creation of new processes, as well as nice graphical views on the tracking information, for instance.

The executable FRENDS Iron processes are called routines. You can start them from the FRENDS Iron Management Console or define schedules for starting them in a given time. Routines bring together the other FRENDS Iron elements:

• Tasks , which define the actual executable process as WF workflows,
• Schedules , which define the times when a routine can run,
• Connection points and connection point groups, which define endpoint specific parameters

Routines

Routines define the executable integration processes: Routines contain the information on the sequence of activities to execute (tasks) and the schedule according to which they are executed.

A routine can have one or more tasks that are executed sequentially, in the order they are listed in the user interface. If a task fails, the routine execution will end in a failure by default. You can choose to ignore the failure, if the task failure is not an actual error, e.g. the task used for polling for files to transfer.

You can give parameters to the tasks in routines, allowing you to create reusable processes. You can also define endpoint specific parameters in a reusable way as connection points, and group them for launching many executions at once.

All routine execution data is stored to the FRENDS database. You can view this data with the Routine View; see section Run and monitor routine execution for details. You can also create reports from the data using SQL Reporting Services, for instance.

Scheduling routines

Routines are usually scheduled to be executed at given times. To understand how schedules work, it is good to know some things about how the schedules are processed.

1. The FRENDS Iron scheduler polls the database once every second for active routines with schedules with an open time window, i.e. their start time and date have passed (and the possible end time has not), and the current date is one of the days when the schedule should execute, as defined by the recurrence type.
2. For all of these routines, the FRENDS Iron scheduler will create and launch a new routine instance. The routine instance will have a task instance for each task defined for the routine, and launch the first task.
   If the routine task uses a CP group, one task instance is created for each connection point in the group. All task instances in the same group are launched at the same time.
3. Finally, for each routine, the FRENDS Iron scheduler will calculate the next time the time window will be open and store that to the database. It is this pre-calculated value that the FRENDS Iron scheduler uses in its polling loop. This makes the poll more efficient, but also means you should not try to modify the values in the database directly! Otherwise, you may cause routines not being launched at the correct times.

One thing to note from this is that routines are scheduled with only best effort guarantees: the routine will be started if the schedule is open when the database is polled. Because the poll delay is one second by default, this can mean that the actual execution of a routine may start 1-2 seconds later than the actual scheduled time. Therefore you should not create too short time windows or expect the routines will start at exactly the given time.

The next scheduled execution is shown in the Routine view, in the Next Scheduled Execution column. If the routine is not active (i.e. is not scheduled for execution), the column shows “Not active”; also, if there are no schedules for the routine, the column shows “No Schedules”; and finally if the schedule season start date is in distant future (more than one year from now) or if the season end date has already passed, the column shows “No open schedules”.

Once a routine has been launched, it will be allowed to start and execute. This means that if you launch a routine with a large number of tasks (e.g. using a large CP group), the execution of the task instances and hence the routine instances may take a long time, continuing even after the time window has ended. If this can be a problem, the routine executions should be scheduled more evenly in time, e.g. by splitting large CP groups and scheduling them separately.

Once a task instance finishes successfully, the next task instance will be launched. If the routine contains no more task instances, the routine instance will finish.

If a task instance fails, the routine instance will by default be marked as failed, and the waiting task instances will be canceled. However, if the routine task is set to ignore possible failures, the next task will be allowed to execute.

Task instances for a CP group that are executed concurrently will all be allowed to start and finish, even if one of the instances fails. The next task may be started (or canceled) only after all task instances in the group have finished. If any of the instances in the group has failed, the routine instance will by default be marked as failed and the rest of the tasks canceled. If the expanded task was set to ignore failures, any failures will be ignored.

There are limits on how many routines and task instances are executed at one time:

• Maximum number of task instances running at a time (by default 100, see setting WfMaxTotalRunningInstances)
• Maximum number of running task instances per routine (by default 50, see setting WfMaxRunningInstancesPerRoutine)

In addition, you can limit a routine to run only one scheduled instance at a time by checking the Run only one scheduled instance at a time check box in the routine properties dialog. For instance, if a routine is scheduled to execute every 10 minutes, but the routine instance takes 13 minutes to complete, a new routine instance will be scheduled only after all the task instances of the previous routine instance have finished, i.e. about 14 minutes from the start of the previous instance. There are some things to note about this feature:

• If you start a routine manually e.g. with the "Run Once" action from the MMC UI, the a new instance will be executed, even if the setting was turned on and a previous instance was already running. This is because the setting is only checked for scheduled routine instances.
• A routine instance can still have many concurrent task instances running, if you use a connection point group.
• The previous routine instance may still show as Launched when launching the new routine instance, because the scheduler actually checks the number of running task instances.

The routine schedules are checked automatically once every minute. If you change the routine schedules, e.g. add new schedules or change the start time of one, the changes will therefore take effect in within one minute.

NOTE: Changes to schedules used in a routine may mean a routine that has executed for that day, will execute again. Example outcomes of this are described in the table below.

Multiple schedules

A routine can have many schedules. In this case, the routine will run once for each time window once they are open.

Note that only one time window can be started at a time. Especially, if two or more schedules have the same start time, only the first one evaluated (in the order of creation time) is considered. Therefore, you should not use overlapping schedules: if the routine has many schedules, make sure they all have end times and the time periods do not overlap.

Repeating (polling) schedules

Sometimes you need to start a task that polls some system e.g. once every hour. For this, you can define a schedule to repeat after a given delay during the period between the start and end times. The maximum repeat delay is 23 hours and 59 minutes, because the maximum time window length is 24 hours – if you need to define longer repeat periods, you should use the recurrence cycle options to define the days when the schedule is open. E.g. if you need a routine to execute once every day, there is no need to have its schedule with a 'Repeat every' setting. Only the 'Recurrence' needs to be set to 'Daily' and to 'Recur every' 1 days.

The repeat times within the open period are calculated from the local schedule start time: for example, if the schedule starts at 12:00, and should repeat every 10 seconds, the executions will be scheduled at 12:00:00, 12:00:10, 12:00:20 etc.

If the FRENDS Iron service has been stopped for a while, when it is started and there are repeating open schedules that should have been executed, they will be launched immediately. The next execution will again use the calculated repeat time.

Note that when a routine has multiple schedules, repeating schedules take precedence over any other schedules because they are assumed to repeat for the entire time window they are open. For instance, if a routine has two schedules, one that starts at 9:00 and ends at 17:00 and repeats every 25 minutes, and another that starts at 16:00 and ends at 20:00, the routine will not run at 16:00 because the second schedule is overlapped by the first one – it will only run at 17:00, when the first schedule has ended. Because of this, you should not use overlapping repeating schedules, because their executions may be in unwanted times.

Daylight saving time effects

The routine schedules are checked according to the server local time, which also takes possible daylight saving time (DST) adjustments into account. This means that if you schedule a routine to run every day at 12:00, it will execute at that time, whether DST is in effect or not.

However, because the scheduler uses the local time with adjustments, the time periods when DST is starting or ending may cause routines to be scheduled a bit differently than normally: In spring, when DST is starting, the clocks are turned forward, and one hour gets skipped. The opposite happens in autumn, when the clocks are turned back, and there is one additional hour. The effects of these adjustments for different schedules are shown in the tables below.

When the DST is starting, one hour (in EU, the hour from 3 to 4 AM) will be skipped, i.e. the clock will skip from 2:59:59 to 4:00:00. For routines this means that the schedules cannot be open during this period, and they are adjusted as follows:

When the DST is ending, one hour will be added to the day, i.e. the clock will be turned back from 4:00 to 3:00. Therefore the local time will be 3:00 twice for that day. For routines that start or stop at this ambiguous hour, the ambiguity is resolved by always choosing the first possible occurrence.

DST changes also affect repeating schedules. Because the repeats are calculated from the schedule’s local start time, the repeats will start to adhere to the adjusted local time as soon as a new schedule is opened. The table below shows an example of a polling routine that is scheduled to execute every three hours for the entire day with different start times.

If the schedule start time or end time is adjusted due to the DST change, a warning will be logged to the event log for every time the schedule is checked, i.e. every minute. If the schedule would be skipped, i.e. the schedule starts and stops during the invalid period (3:00-3:59:59), an error is logged.

Editing routines

Creating a new routine

You can create a new routine from the FRENDS Iron Management Console as follows:

1.  Right-click on the Routines node and choose Add new Routine from the menu. The New Element Properties dialog is opened.
   
2. In the Routine Properties dialog main tab, give the routine a name.
3. If you want to schedule a routine to run at a specific time:
   
   1. Choose or create the schedule(s) from the Schedules drop-down list
   2. Check the “Activate Schedules” checkbox so the process engine will evaluate the schedules and launch the routine if one is open.
4. Add a new routine task by clicking the Add button and choosing the task from the list.
   
5. For each task you add, you can define:
   • Connection point – the endpoint specific parameters for the routine. If you want to reuse routine parameters across routines (e.g. a URI) or execute tasks in groups, enable the connection point feature for the routine by checking the “Use Connection Point” checkbox.
     After this, you can choose the connection point that has the end-point specific parameters to the task workflow executions.
     You can also use a connection point group. In that case the routine task will be expanded to a task instance group upon execution, with one execution for each connection point in the group. Each execution will have its own connection point.
     
   • Task arguments – The values for the arguments for the task. You can write the value directly to the grid or use FRENDS Iron connection point references (see Connection point references in task parameters). You can use the Custom value editor, see Using the custom value editor for adding the values for the most common situations.

     NOTE: You can only pass value types (i.e. integer, decimal, etc.), date, or string type parameters using the property grid.

   
6. Failure action – What to do if the task fails, i.e. the task result value is false and the task is marked Failed. The options are:
   • Stop routine execution reporting failure - the routine is stopped once the task (or task group) has finished. The rest of the tasks will be canceled. The routine instance set will be set to the failed end state of the task instance.
   • Stop routine execution reporting success - the routine is stopped once the task (or task group) has finished. The rest of the tasks will be canceled. The routine instance will be set to the Ok state.
   • Ignore failure and continue to next task - the failure is ignored and the next task (or task group) will be launched.

   By default, the failure action will only be considered for Failed tasks, not for tasks that end up in Exception state (this usually happens if the workflow does not catch exceptions): the routine will always be stopped and the marked as failed.

   However, if you check the option to Treat exception as failure, also exceptions will use the chosen failure action. This way, if you have a ready-made workflow that throws an exception in case or error, you can ignore the error if needed.

7. Click Ok. The new routine is created and shown in the routine list.

Editing a routine

To edit an existing routine, right-click on the node in the routine view or element tree, and choose Properties from the menu. The Routine properties dialog, such as the one described in image routine properties, is opened. There you to change any routine property the same way as when creating a new routine.

Deleting a routine

To delete an existing routine, right-click on the node in the routine view or element tree, and choose Delete from the menu. Once you confirm the action, the routine and all its instances are deleted.

NOTE: You must terminate all currently executing routine instances before trying to delete the routine. If you try to delete a routine with currently executing instances, you will get an error.

Using the Custom value editor

You can use the Custom value editor to give values to the routine parameters in the most commonly used situations:

• Defining a reference to the FRENDS Iron connection point of the routine
• Choosing a BizTalk receive location URI
• Defining a multiline text value
• Defining an XML message by loading a schema and giving values to the fields

To open the Custom value editor:

1. Right-click on a routine node and choose Properties from the menu.
2. In the Routine Properties window, select a Routine Task. This shows the Task argument tab on the right side of the dialog.
3. Activate the property grid row by clicking on the row of any of the value cells.
4. Click on the small Ellipsis button ‘…’ in the right side of the value cell.
5. The Custom value editor will open.
   

Using a connection point reference

For setting endpoint specific parameters, you can use FRENDS Iron connection points. You refer to the data field values of connection points using connection point references (see Connection point references in task parameters for details). To ease the use of these references, the Custom value editor allows you to create the references by just choosing from a set of options:

1. Open the Custom value editor for the parameter value as described above.
2. Choose the Connection point reference radio button. The panel on the right shows the Connection point reference control.
3. Choose one of the reference types using the radio buttons. The text of the reference is also shown in the dialog:
   • Name: {CP:Name} – The name of the connection point.
   • Party name: {CP:PartyName} – The BizTalk party name associated with this connection point.
   • Custom data: {CP:<xpath>} – XPath reference to a data field in the internal XML data structure of a connection point. The reference is expanded at runtime based on the data of the connection point.
     If you leave the XPath expression empty, it will be interpreted as “{CP:/}”, meaning that the entire XML data structure is returned. You can use this to store and retrieve BizTalk messages in connection points, for instance.
   • Encrypted data: {ECP:<field name>} – Reference to an encrypted data field in connection point properties. 
4. Click OK. The property value cell in the Task arguments tab should now show the connection point reference value.

Choosing a BizTalk receive location URI

If you are using the ready-made BizTalk tasks, you need to give the receive location URI as a parameter. The Custom value editor allows you to select this value from a list.

1. Open the custom value editor for the parameter value.
2. Choose the BizTalk artifact name radio button. The panel in the right shows a list of BizTalk artifact names.
3. Choose All Ports from the Select drop down list, if not already selected. The list now shows available receive locations that use the FRENDS Iron Submit adapter.
4. Highlight the receive location you want to use and click OK. The property value cell should now show the name of the receive location you chose

If you have many FRENDS Iron receive locations in the system, you can filter the list by port name by choosing it from the Select drop down list.

You can also use this list to select a BizTalk party name. However, it is recommended better to use the PartyName connection point reference, as described in section Using a connection point reference.

Entering multiline text

Sometimes, you need to pass long text strings as parameters to the tasks. Because the parameter property grid is limited, you can define long, multiline strings from the Custom value editor as follows:

1. Open the custom value editor for the parameter value.
2.  Choose the Text radio button if it not active already. The panel on the right shows a text box where you can write the text
3. Enter the text in the text box and click OK. The property grid shows the beginning of the text you gave.

Entering an XML message

You can enter XML strings using the text box as described in the previous section. However, writing raw XML to the text box can be tedious. Instead, you can use the Custom value editor to fill out an XML message as follows:

1. Open the custom value editor for the parameter value.
2.  Choose the XML message radio button. The panel on the right shows the XML message editing grid.
3.  Load the XML schema by clicking on the Load schema button and choosing the schema file using the file dialog.
4.  Once the schema is loaded, enter the values for the XML message fields to the property grid.
5.  When finished, click OK. The property grid shows the beginning of the XML string with the contents you gave in the dialog.

Selecting a file

You might also need to pass entire contents of a file, not just the file path, as parameters to the tasks. It can be done as follows:

1. Open the custom value editor for the parameter value.
2. Choose the File contents radio button. The panel on the right shows the file selection panel.
3. Click on the small Ellipsis button ‘…’ to open the file chooser dialog.
4. Select the desired file and click Open. File reference for the file you selected should now be shown in the panel.
5. When finished, click OK.

Controlling routines

You can control the execution and activation status of routines from the FRENDS Iron Management Console. The commands you execute from there, use the FRENDS Iron process engine commands (see the topic FRENDS Iron process engine commands for more details)

Starting a routine instance manually

Sometimes, you may want to start a routine immediately, for instance to test the task works. Then you don’t want to wait for a time window of the schedule to open. You can start the routine manually as follows:

1. Go to the Routine view.
2. Right-click on the routine and choose Routine Actions > Run Once from the context menu. A new routine instance is created and started immediately.

NOTE:

1. When you start a routine manually, the schedule is ignored, and a dummy schedule that runs once is used.
2. If you start a repeating routine manually, it will only run once. If you want the routine to start repeating, you have to let it run according to the schedule. If you need to restart a repeating routine, you need to reschedule it; see Rescheduling a routine

Terminating a routine instance

Sometimes task execution hangs, or you want to otherwise terminate a routine instance before it can end normally. To terminate a single running routine instance:

1. Go to the Routine instance view.
2. Right-click on an instance and choose Terminate from the context menu. The routine instance execution is terminated using the StopRoutineInstance operation. For details on what happens internally when a routine instance is terminated, see the topic on the Stop RoutineInstance method.

NOTE: While the FRENDS Iron task is terminated this way, BizTalk processes triggered by the FRENDS Iron processes are not stopped: they will run until they finish, or are suspended or terminated from BizTalk's management interfaces.

To stop all running instances of a routine:

1. Go to the Routine view.
2. Right-click on the routine and choose Terminate from the context menu. All instances are terminated using the Stop Routine command. See the topic on the Stop Routine method for details.

NOTE: Terminating a recurring routine will not stop the routine from recurring. If you want to stop the routine from recurring, you need to deactivate it as well.

Activating / deactivating routine schedules

If you don’t check the Activate Schedules checkbox (see image routine properties) when creating a routine, the routine schedules will not be activated. This means the FRENDS Iron process engine will not check the schedules and the routine will not launch according to the schedules. In this case, you must start a routine manually, as described above in section “Starting a routine instance manually”

To activate the schedules, and make the routine execute according to the schedule:

1. Go to the Routine view.
2. Right-click on the routine and choose Routine Actions > Activate Schedules.

OR

Open the routine properties and check the Activate Schedules checkbox.

To disable the routine from starting according to the schedule:

1. Go to the Routine view.
2. Right-click on the routine and choose Routine Actions > Deactivate Schedules.

OR

Open the routine properties and un-check the Activate Schedules checkbox.

Rescheduling a routine

Routines are scheduled to run only once per schedule per day (for details on this, see the section on Schedules). If you want to make the FRENDS Iron process engine check the schedule for the routine again, you will need to reset the schedules. This can be useful when testing schedules, especially when restarting repeating routines – if you launch a routine manually, the possible recurrence will not be used. Therefore:

1. Go to the Routine view.
2. Right-click on the routine and choose Routine Actions > Reset Schedules. If the routine has a schedule that is currently open, a new routine instance is created and started.

If you change the schedule currently used by a routine, the schedule editor allows you to reset the schedules of the routines. See section Editing a schedule for details.

Monitoring routine execution

Routine view

You can see the latest status of all routines in the system from the Routine view.

The view shows the following details for each routine:

• Last State – the state of the latest execution of the routine, determined by the execution start time.
• Last Execution – The start time of the latest execution
• Next Scheduled Execution – The next time the routine may execute.
  If the routine is not active (i.e. is not scheduled for execution), the column shows “Not active”; also, if there are no schedules for the routine, the column shows “No Schedules”; and finally if the schedule season start date is in distant future (more than one year from now) or if the season end date has already passed, the column shows “No open schedules”.
• Waiting - The number of executions that are waiting to be executed
• Executing – The number of executions currently in the executing state (see Routine instance states for details)
• Successful – The number of executions that have finished successfully
• Failed – The number of executions that have failed

The routine view shows an icon for each routine to visualize the state of the latest execution. See the table in the following section for details on them.

Routine instance view

You can view the details of individual executions from the Routine instance view. You open this view by clicking on a routine node

The routine instance view shows the basic information on each routine instance:

• State – The routine instance state and icon. See section Instance states for more details and icon descriptions.
• Name – the name of the routine
• Routine Start Time , Routine End Time – The start and end time of the routine instance

When you select a routine instance in the list, another list showing the related task instances is shown. This list shows the basic information on their execution:

• State – The task instance state and icon. See section Instance states for more details and icon descriptions.
• Start Time , End Time – The start and end time of the task instance
• Execution Time – The total time the task instance has executed
• Connection Point – The connection point which was used by the task instance.
• User result message – The result message passed out from the task instance's workflow.

Showing only selected states in the routine instance view

You can filter the routine instance view to show only routine instances in specific states in the State filter menu:

1. Click on the left-most button with the label "States: All" on the bottom tool bar. The menu for choosing the states to show opens:
   
2. Click on the state menu items to uncheck and check them. The view will refresh and only the routine instances in checked states will be shown.

NOTE: The states in the filter menu refer to the states of the routine instances, not their task instances. This means that even if the filter is set to exclude e.g. ActionSkipped instances, if a routine instance has ended in OK state, it will be shown even if some of the tasks instances would have ended in ActionSkipped state.

If you want to only find the task instances that are in a specific state, e.g. Exception, you can also use the free-text Filter: its queries match the properties of the task instances, so the routine instance will be shown only if at least one of its task instances is in the given state.

Viewing task execution details

You can drill down to the details of each individual task execution from the Routine instance view: choose work on a task instance row opens the Workflow Monitor dialog that shows the tracked values and the execution status of the workflow.

The workflow execution flow is shown in the pane on the left side. The executed activities all have the little blue check mark on their top-right corner.

The Workflow information pane in the top-right corner of the monitor window shows workflow details. If the workflow ended successfully, the pane shows the times of the changes from one state to another. If there was an exception or other error, the pane shows the error details as well as stack trace for easier error diagnoses. (all exception details are shown in the logs)

The Activity Information pane shows the details of the currently selected Activity. The list shows the values of the tracked properties during the execution of the Activity according to the Tracking profile - NOTE: If you choose to create a default tracking profile when creating a task (see the section Creating a new Task), all value typed properties will be tracked. For details on editing the tracking profile, please see the FRENDS Tutorial 3.

If you select one of the ready-made BizTalk activities, the ‘Show HAT’ button is enabled. Clicking this button opens the BizTalk Health and Activity Tracking tool, showing the message send to BizTalk by FRENDS Iron. You can then further drill down to the process execution within BTS. NOTE: Because HAT has been deprecated since BizTalk 2009, the Show HAT integration will not work on it or more recent BizTalk versions.

Instance states

A routine instance can either be executing or finished. When a routine instance is executing, it has task instances that are executing or waiting to be executed. Once all task instances have finished executing, the routine instance will also be finished and take the end state of latest non-ignored task instance end state. The following tables describe these states.

Executing instance states:

State	Icon	Description
Waiting		Workflow runtime is currently under heavy workload and task instance is queued to be launched. This state applies only to task instances. Routine instance is always on Launched state when it is waiting for execution.
Launched		The instance has been launched, but it is waiting for the workflow runtime to start the execution
Starting		Workflow runtime is about to start workflow execution and is initializing workflow execution.
Started		Instance is currently executing, and is running the task.

Finished instance states:

State	Icon	Description
Successful		Instance was executed successfully
ActionSkipped		Instance was executed successfully, but it did not do its main action because some precondition failed. This state is usually used for polling tasks, to signal that while the task executed without errors, it did not do anything (e.g. transfer a file).
Failed		Instance has failed. The task was executed successfully, but it returned a false return value, signaling some kind of business level failure.
Exception		An error occurred when executing the instance or stopping the instance's workflow. This is a general error that can signal an exception. Please see the logs for more details on the error.
Canceled		The routine was stopped before any task instances were started.
TerminatedByUser		The instance was terminated by user request
FinishedAsZombie		The instance was left in a Started state, even though the workflow had already finished. This is usually caused by problems with updating the task instance states to the database. The FRENDS Iron service periodically cleans up old “zombie” instances and sets their state to FinishedAsZombie.

Managing Routine Elements

Routine elements include Tasks, Schedules, Connection points and Connection point groups. Every element has several common actions which are described below. A more accurate description about each routine element, including element specific actions, is in the element specific sections, starting with Tasks below.

Create copy

You can easily create a copy of one or more existing elements:

1. Right-click the element you want to copy with your mouse.
2. From the menu choose Create copy.
3. A dialog box will ask you to confirm the copy action. Click OK.

NOTE: Elements of same type cannot have duplicate names. Therefore copies are named “elementName (number)”. The number is next free number beginning with 2. E.g. copying element named “CPOne” would create copy named “CPOne (2)”.

Rename

You can change the name of an element by right clicking on the element you want to rename and choosing Rename from the menu.

In the element list views, you can also just select the name cell of the element to rename, and start typing the new name. You can cancel the rename action by pressing the <ESC> key. The new name is saved either by the pressing <ENTER> key or when the cell loses focus.

Delete

To delete one or more elements:

1. Choose all the elements you wish to delete
2. Right click on the selection
3. Choose Delete from the menu and confirm the delete action when asked.

You can also use the <DELETE> key to delete elements.

You cannot delete an element which is used by a routine or routine instance.

Where used

To check in which routines one or more routine elements are used:

1.  Choose all the routine elements you want to check
2. Right click on the selection
3.  Choose Where used? from the menu. The routine(s) using the routine elements will be shown in a dialog.

Export

You can export elements to an FRENDS Iron export file for importing later on.

1. Select all elements you wish to export
2. Right click on the selection
3. Choose Export from the menu. A Save As dialog will appear.
4. Select the file location, give a name for the file and click Save. The FRENDS Iron export XML file is created.

Import

To import elements from an FRENDS Iron export file:

1. Right click anywhere on the element list view
2. Choose Import from the menu. In the Open file dialog you choose the file you want to import.

If the imported elements have names that are already in use you will see a dialog asking what to do:

The dialog allows you to:

• Import the new element with an automatically modified name.
• Use the existing element, skipping the import of the element.
• Replace the existing element with the imported element.

You need to choose one action and click OK. If you click Cancel, the import is aborted and no elements are imported. After the import you will see a dialog showing the amount of elements imported.

The dialog will appear for every element with a duplicate name. You can check the Do this also for next duplicates checkbox to repeat the chosen action to all elements with a duplicate name.

NOTE: Duplicate names are checked from the base name of the element. Base name is the name of an element without the copy number. E.g. the base name of “Imported Task (2)” is “Imported Task”.

Tags

You can add tags to elements to help you group them. The tags are shown in the tags column in the element list view and in the element property dialog, next to the element name.

You can edit the tags either by clicking the tags in the element property dialog, which will open a add tags dialog, or by selecting the tags cell in the element list view and typing in new tags. You can cancel the editing by pressing esc key.

You can also add tags to multiple elements at the same time; just select all the tag cells you wish to add tags and start typing. This will open the add tags dialog. Write all the tags you wish to add, separated by commas, and click ok. These new tags are added to the selected elements existing tags.

NOTE: If you edit tags by selecting the cell and just start typing, you will lose previous tags. Try clicking the tags cell two times to activate the editing of the cell. This way you can edit existing tags or just add new tags.

Managing multiple elements at a time

You can select multiple elements at a time in the list view e.g. by painting the elements with a mouse. Also keyboard shortcuts, like <CTRL> + A for selecting all elements, work. NOTE: Only some actions may be enabled when multiple elements are selected.

Element List Views

Routine elements are shown in list views. The list view is modifiable, you can choose which columns are shown by right clicking the column header and checking those columns you wish to view.

Using the search filter

The list views also have a search filter feature with which you can filter the view to show only the elements that contain the given string in some their data columns. For the routines and routine elements, the default data columns used in the filter are Name and Tags. Therefore the search matches the following columns for each view:

• Routine: Name, Tags
• Routine / task instance: Schedule name, Connection point name, Task name, State, User result message
• Task: Name, Tags
• Schedule: Name, Tags
• Connection point: Name, Tags, Connection point data
• Connection point group: Name, Tags

Note: The filter tries to make an exact match. You can use wildcards to match partial strings, for example “Test*” matches everything starting with “Test” and “*test*” matches everything containing “test”.

Note: After version 3.1, the search filter no longer matches the internal arguments passed to the routine task instance: the argument data for executed instances took too much space in the database, so it is no longer stored, and cannot be searched.

Using an SQL Where -clause with the filter

It is also possible to use advanced straight SQL where-clauses by checking the ‘Use a SQL where-clause’. Using this feature requires knowledge of SQL and the database structure. When it is enabled the view is not updated on each keystroke but instead when enter is pressed or when control leaves the filter text field. An example of a where-clauses: ROUTINE_ID > 1 AND ROUTINE_ID < 10 or this_.NAME = 'OWC'.
Because of the way the database access layer, which uses NHibernate works, the query requires the internal table identifier in the query before some column names due to ambiguity. In these cases FRENDS Iron gives an error message:
Error when updating view. Ambiguous column name ‘<column name>’.
This can be fixed by adding the identifier ‘this_’ (or ‘this_0_’ for task instance fields) before the column name as shown in the example.

Tasks

FRENDS Iron tasks define the execution logic: the steps that are taken to get to the end result. Technically, tasks are parameterized Windows Workflow Foundation (WF) workflows: you define the logic using Visual Studio 2008, compile the workflow and deploy it to FRENDS Iron. FRENDS Iron then hosts the workflow engine and provides the necessary services for it.

The basic FRENDS Iron installation contains three ready-made tasks:

• BizTalk Send One-Way – task using the BizTalk One-Way Workflow to send a message to BizTalk. See WF Workflows for FRENDS Iron for details.
• BizTalk Send Two-Way – task using the BizTalk Two-Way Workflow to send a message to BizTalk and wait for a response. See WF Workflows for FRENDS Iron for details.
• Always True – Dummy task that only returns success value. See WF Workflows for FRENDS Iron for details.

Managing tasks

Creating a new task

You can create a new task from the FRENDS Iron Management Console as follows:

1. Right-click on the Tasks node and choose Add new Task from the menu. The New Element Properties dialog is opened.
   
2. In the New Element Properties dialog, first give the new task a name.
3. In the Workflow Assembly textbox, give the full assembly name of the assembly containing the WF workflow you wish to use. You can use the Browse… button to navigate to an assembly file.
4. In the Workflow Class combo box, choose the class to use for the task.
   
5.  Activate the Task parameters tab. Here you can choose, which workflow parameters you want to expose from the WF workflow, by either double-clicking on the parameters or choosing the parameter and clicking on the Add >> button.

   NOTE: Only the parameters you choose here can be given in the routine task arguments view (see image Task arguments)

6.  Click OK. The new task is created and added to the task list.

You can also choose to generate the default tracking profile by answering “OK” to the Update tracking profile dialog, which is shown when the Workflow assembly is changed or a new Task is created. Generating the tracking profile is recommended, as it allows for monitoring the details of the execution as described in topic Viewing task execution details

Editing a task

You can edit an existing task by right-clicking on a task row in the task view and choosing Properties from the menu or by double clicking the task. The Task properties dialog that is opened allows you to change all the properties the same way as when creating a new routine, described above.

Task parameters

Task parameters are basically properties of the underlying WF workflow. When running a routine, the parameters are filled to their given values and passed to the WF runtime.

You can use connection point references in routine property dialogs to extract some of the parameter values from the CP data structure. For details on this, see section Connection point references in task parameters.

NOTE: You can only pass value or string type parameters via the FRENDS Iron user interface.

You can select the parameters you wish to use from the Parameters tab, as described in “Creating a new task” above.

Using tasks as conditions or for polling

Sometimes it is necessary to check for some preconditions before doing an action: for example, it could be useful the check if the remote host is up and running before trying to send the message to it, avoiding an unnecessary error if the host is temporarily down. You may also try to poll a remote directory for files to transfer, and if there are no files, end the task doing nothing.

For the first case, you can create a separate precondition task that has its failure action set to Stop routine execution reporting success, and schedule it before the actual task that does something. Then if the precondition task fails, it will stop the routine instance, but set the state to Ok. This way there are no unnecessary errors shown in the view.

For polling tasks that did not do anything, you can use the ActionSkipped return value to end the task in the ActionSkipped end state. For instance, the FRENDS Cobalt task can end in ActionSkipped state if no files were transferred.

Schedules

FRENDS Iron schedules define the times a routine should be launched by the FRENDS Iron process engine. You can re-use existing schedules with different routines.

A routine is executed once for each schedule per day (i.e. 24 hour time window). For instance, if a routine has three open schedules in season, the process engine will launch three routine instances every day. A schedule is said to be open if the all its time conditions are true: for example, the daily start time has passed, but the daily end time has not yet passed.

A schedule must define:

1. Name – Descriptive name for the schedule
2. Daily start time – Time when the FRENDS Iron process engine should launch the routine
3. Season start date – The first day the schedule is open (“in season”)
4. The recurrence type – on which days the schedule is open:
   • - Daily: the schedule is open on every given day, i.e. every day (the default), or every second day and so on.
   • - Weekly: The schedule is open on every given week and on given weekdays
   • - Monthly: The schedule is open only on specified months and either on
     1. Specified dates, like the 13^th or the last of the month, or
     2. Relative dates, like the second Friday or the last weekday of the month, for instance.

The schedule may also define:

• Daily end time –Time after which no further routines should be launched. This value is usually important for repeating routines.

NOTE: Once a routine has been launched, it is allowed to complete even if it goes past its end time

• Season end date – The last day the schedule is open
• Repeats – Repeat the task after the given delay starting from the daily start time, and ending at the daily end time. If no end time is set, the routine will repeat the entire 24 hours in a day, i.e. all the time.

For details on how the schedules are used with routines, see section Scheduling routines

Managing schedules

Creating a new schedule

You can create a new schedule from the FRENDS Iron Management Console as follows:

1. Right-click on the Schedules node and choose Add new Schedule from the menu. The New Element Properties dialog is opened.
   
2. In the General tab, give the schedule a name.
3. Give the daily start time in the Start at time control
4. Give the season start date in the From date control – it should be the current date by default.
5. Select the recurrence type. See the previous section for descriptions on these options. By default, the schedule is set to be open every day ( Daily, Recur every 1 days)
6. Click Ok when done. The new schedule is added to the list.

Editing a schedule

You can edit an existing schedule by right-clicking the node and choosing Properties from the menu. The Schedule properties dialog that is opened allows you to change all the properties the same way as when creating a new element, described above.

When you change a schedule that is currently used by a routine, the editor will prompt you for resetting the schedules of those routines. Choosing to do so allows you to apply the changes immediately, but it may also make routines run again for today. If this is not desirable, you should decline, and possibly reset the schedules on some routines manually.

Connection points

Connection point contains the parameter information, such as IP address and user name for an FTP connection, on individual endpoints. The parameter data is stored as an XML structure to the FRENDS Iron control database. The data structure adheres to a XML schema, defined when creating the connection point.

You can use connection points in many ways, for instance keeping track of remote endpoint states or storing messages sent to BizTalk. You can access the data either via direct database queries to the FRENDS Iron control database or using connection point references.

Connection point data schemas

The connection point data structures are typed using XML schemas. Only very basic XML schema functionalities are supported:

• Simple element definitions
  

  <xs:element name="name" type="xs:string" />
  

• Complex element definitions with a <sequence> of sub-elements:

  <xs:element name="Data"> 
      <xs:complexType> 
          <xs:sequence> 
              <xs:element name="Name" type="xs:string" /> 
              <xs:element name="Id" type="xs:int" /> 
              <xs:element name="Location"> 
                  <xs:complexType> 
                      <xs:sequence> 
                          <xs:element name="Latitude" type="xs:double" /> 
                          <xs:element name="Longitude" type="xs:double" /> 
                      </xs:sequence> 
                  </xs:complexType> 
              </xs:element> 
          </xs:sequence> 
      </xs:complexType> 
  </xs:element>
  

• Simple global type definition:

  <xs:element name="Data"> 
      <xs:complexType> 
          <xs:sequence> 
              <xs:element name="Name" type="xs:string" /> 
              <xs:element name="Id" type="xs:int" /> 
              <xs:element name="Location" type="LocationType" /> 
              <xs:element name="OtherAddress" type="LocationType" /> 
          </xs:sequence> 
      </xs:complexType> 
  </xs:element> 
  <xs:complexType name="LocationType"> 
      <xs:sequence> 
          <xs:element name="Latitude" type="xs:double" /> 
          <xs:element name="Longitude" type="xs:double" /> 
      </xs:sequence> 
  </xs:complexType> 
  

• <all> list, as well as enumeration restrictions
  

  <xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> 
      <xs:element name="Data"> 
          <xs:complexType> 
              <xs:sequence> 
                  <xs:element name="All"> 
                      <xs:complexType> 
                          <xs:all> 
                              <xs:element name="One" /> 
                              <xs:element name="Two" /> 
                              <xs:element name="Three" type="CarEnum" /> 
                          </xs:all> 
                      </xs:complexType> 
                  </xs:element> 
              <xs:element name="Enum" type="CarEnum" /> 
          </xs:sequence> 
      </xs:complexType> 
  </xs:element> 
  <xs:simpleType name="CarEnum"> 
      <xs:restriction base="xs:string"> 
          <xs:enumeration value="Audi" /> 
          <xs:enumeration value="Golf" /> 
          <xs:enumeration value="BMW" /> 
      </xs:restriction> 
  </xs:simpleType> 
  </xs:schema>
  

Most of the more notable functionalities that are not supported are:

• Element attributes
• Schema imports
• Choice-elements

Schemas that use these features will not be shown correctly in the view: for instance, even if you define minoccurs=”3”, only a single element will be shown. However, as the schema is only used for initializing the editor, the data can still adhere to the schema – it just needs to be edited externally, and written directly to the database.

If you need to maintain multiple versions of CP schemas, you can use the XML Schema version attribute for distinguishing between the different versions. If the schema has a version, it will be shown e.g. in the Choose Connection Point Schema dialog.

Note: If you want to change target namespace for your connection point schema, you have to create a new connection point. Otherwise old target namespace is used.

Connection point references in task parameters

You can use the information stored in a connection point to parameterize the execution of Routine Tasks. You do this with connection point references. They are parameter strings enclosed in curly braces and starting with “CP:” that are expanded at runtime to the corresponding Connection Point value.

Currently there are four CP references you can use:

• CP Name Reference: “{CP:Name}” - The name of the Connection Point
• CP Party Name Reference: “{CP:PartyName}” – The BizTalk party name associated with the Connection Point
• CP Data Reference: “{CP:<XPath>”}, where XPath refers to an XPath query string. – A reference to the data stored in the Connection Point. When using this reference, the XPath query is executed on the XML data structure associated with the Connection Point of the routine.
• Encrypted CP Field Reference: “{ECP:<FieldName>}”, where FieldName refers to the encrypted CP field name – for more on this, see the next section, Encrypted connection point fields

There are some things to note when using the CP Data References:

• If the XPath query returns an XML data structure, the structure is transformed to a string (using XmlElement.OuterXml()).
• If the XPath query returns more than one node, the first one is used.
• If the XML data defines namespaces, you need to provide the namespace information in the query.

For example uses of the references, see the table below.

CP reference examples:

Encrypted connection point fields

Encrypted Connection point fields allow you to store login information and other sensitive data securely. You define and edit new fields and their values in the CP property dialogs in the FRENDS Iron Management Console: Just define the values in the Encrypted Fields tab.

Once you click OK, the data is encrypted to the FRENDS database, and only the FRENDS Iron Service can read and use the data – even the system administrator cannot see the encrypted field values in plain text in the Management Console or in the database.

In order to secure the field data but at the same time allow changing it in the UI, the field data is encrypted in two phases: First the UI encrypts the data using AES with a 256-bit symmetric key. Then the symmetric key is encrypted using the public key from an asymmetric 2048-bit key pair (generated during initial configuration – see the configuration tool documentation for more on this), and stored to the database with the encrypted data. The UI knows the public key because it is stored to the UI configuration file.

Only the FRENDS Iron service can decrypt the symmetric key, because only it knows the private asymmetric key, which is stored to the service configuration file. To secure this private key, it is encrypted using Windows’ DPAPI so that only the FRENDS Iron service user account can decrypt and use the private key.

The encrypted value can be used by a routine by passing it as a Task Argument. This is done by setting the argument field {ECP:<Encrypted field name>}. Example: {ECP:password}

NOTE: Using special characters <, >, or & in an encrypted field {ECP:x} or file {FILE:x} reference will cause the XML serialization to fail, which makes XML invalid and the fields unusable for input to the workflow. To avoid this problem you have to escape the characters in html format. If you have one of those characters for example in a password which you want to encrypt, replace illegal characters with following entries: (<) with &lt, (&) with &amp and (>) with &gt.

NOTE: If the key pair or FRENDS Iron user account is changed, the FRENDS Iron service cannot decrypt the private key anymore. Therefore it is recommended to backup the key pair by exporting it to a file. This is described in the Configuration Tool documentation.

Connection points and BizTalk Parties

In BizTalk, role links and parties can be used to model individual training partners – somewhat similar to FRENDS Iron connection points. You can store trading party specific details to them, especially

• Send ports, that store the connection details, e.g. addresses and protocol for that trading partner
• Certificates used for resolving the party at runtime

For more details on the parties, please see the BizTalk documentation.

FRENDS Iron connection points are loosely associated with BizTalk parties: You can give a party name to a special field in the connection point. This value can be used in routine parameters using the {CP:PartyName} reference. You can use this especially in the ready-made BizTalk tasks, which have the PartyName parameter. The value you give to this parameter will be passed on to the FRENDS Iron adapter, which in turn sets it the PartyName message property in the message sent to BizTalk. This property can then be used in orchestrations to associate the process with specific parties. For an example of this, see the FRENDS Tutorial 2.

Note: In FRENDS 2.2 or later, BizTalk parties are no longer created with connection points by default, as they were in 2.0 and 2.1. This was done for performance reasons. Therefore you need to create the parties and set the Party Name field in the connection point properties manually.

Managing connection points

Creating a new connection point

You can create a connection point using the FRENDS Iron Management Console as follows:

1. Right-click the Connection Points node and choose Add new Connection Point from the menu.
   
2. In the New Element Properties dialog, give the Connection Point a name.
   
3. Next, you need to choose the message schema.

   a. Click on Load Schema.

   b. In the Choose Connection Point Schema dialog, you can choose from already loaded schemas or load a new schema by clicking on the Import button in the upper-right corner to open a XML schema file.

   c. Click Ok.

4. The Connection point Parameters property grid is filled with the category schema elements, with possible default values. You can change the values as needed.
5. Click Ok. A new connection point is created and shown in the list.

If you change the schema of an existing connection point, the dialog tries to keep the existing data: if the new schema structure and names of the elements are the same as the previous one (e.g. you only added a new field to the schema), the data should remain the same as before.

Editing a connection point

You can edit an existing connection point by right-clicking a connection point in the list view, and choosing Properties from the menu. The Connection Point properties dialog that is opened allows you to change all the properties the same way as when creating a new connection point, as described in Creating a new connection point.

Managing Connection Points through the CP Web Service

You can query and update connection points through a Web Service interface. The URL for the Web Service is defined in the FRENDS Iron Configuration tool. Three different operations are provided: QueryCP, QueryCPValue and UpdateCP.

QUERYCP

QueryCP operation sends a CPQuery message and returns a list of CPInfo messages. The CPQuery message defines the query fields. All of the fields are optional, but you need to define at least one field. If you give multiple fields, all of them must be true for a connection point for it to be returned.

• CpId , CpName and PartyName refer to the corresponding CP properties – NOTE: name fields are expected to be an exact match!
• CpGroupId and CpGroupName refer to the connection point group properties. As with CP properties, these are also expected to be exact match.
• CpDataXQuery allows you to query for only those CPs with a specific value stored in the CPData. You give a XQuery that is matched to the CPData structures, and if there is a match, the CP is returned. An example XQuery: “//Id/text()[contains(.,"1")]”. It selects all CPs that contain the number 1.

QUERYCPVALUE

QueryCPValue is like QueryCP, but instead of returning a CPInfo it returns a string which contains the data from CPData selected with an XPath query.

UPDATECP

UpdateCP modifies an existing Connection Points fields by sending an CPInfo which contains the Id of the CP to modify and the new values. It is meant to be used in conjunction with QueryCP: First, fetch CPInfo structure for the connection point by QueryCP. Then modify the structure and send it to UpdateCP. An example of this can be found in the FRENDS Iron installations Help in the Example-ConnectionPointWebService-directory.

NOTE: Connection point’s PartyName or CP Schema cannot be updated via the Web Service interface.

Connection point groups

Sometimes you need to send the same message to many different endpoints at once. You can do this easily in FRENDS Iron by using connection point groups. Using them, you can group connection points together using criteria like CP name or tags, and give them to a single routine's task. When the routine is executed, the connection point group will be expanded so that a task instance is launched for each connection point in the group. This allows you to maintain these kinds of processes efficiently.

Connection point group filter

Connection points are grouped by creating a filter that defines conditions for connection points. These conditions are then evaluated for the entire list of connection points, and the ones that fulfill all the conditions will be returned.

The conditions are written in a simple language: each condition has a condition type, an operator and a value. There are two types of conditions:

• CP Name conditions that do string matching on the CP name.
• CP Tag conditions that do string matching on the CP tag values

NOTE: “This Group” conditions from 2.0 and 2.1 are no longer supported, because they cannot be reliably imported between environments – they reference specific CP IDs, which are likely not the correct ones on other environments. Furthermore, unique tags or names can be used instead. Therefore, please change filters using “This Group” conditions to use unique names or tags instead: e.g. “This Group Includes TestCP” -> “CP Name Equals TestCP”

You can group filter conditions together using basic Boolean operators AND, OR, and their negations NOT AND and NOT OR.

Editing connection point groups

Creating a new connection point group

1. Right-click the Connection Point Groups node and choose Add new Connection Point Group from the menu.
   
2. In the New Element Properties dialog, give the group a name.
3. To add a new CP group filter condition
   1. Clicking on the Add Condition link label after the condition group operator. This will add a new condition row in the condition group.
   2. Set the condition type by clicking on the first, blue link label in the row, and choosing the type from the menu.
   3. Set the condition operator by clicking on the second, green link label in the row, and choosing the operator from the menu.
   4. Set the condition value by clicking on the last label of the row and writing the value.
4. To remove a condition, click on the little red cross icon at the end of the row.
5. To group many conditions together, click on the Add Group link label. This will add a new group item under the last condition row.
6. When finished. Click Ok. The new connection point group is now added to the list.

Technical details

Creating your own task workflows

FRENDS Iron tasks use .NET 3.5 Windows Workflow Foundation workflows to define the actual sequence of actions to execute. Note that .NET 4.0 Windows Workflow Foundation workflows are not supported. You can create your own workflows easily using Visual Studio 2008 (or Visual Studio 2010 SP1, as long as the workflow assembly is compiled with the target framework set to .NET 3.5).

For information on creating a new workflow using Visual Studio 2008, please see the WF documentation, now part of the latest Microsoft Windows SDK documentation.

You can use almost any kind of WF workflow with FRENDS Iron. As the workflows are executed internally by the FRENDS Iron execution engine, you cannot expose any Web Service interfaces from the workflow, but otherwise there are no limitations: you can even provide your own WF runtime service (see Providing your own WF runtime service) for more complex interactions with external systems.

Task return value

Often you would need to handle a situation where a task execution had a logical failure: the execution went as it was supposed to and there were no timeouts or other technical failures, but the task failed, e.g., a called service declined the request. In these situations you would not want to throw an exception, because the situation was not exceptional, but still would like to communicate that the task did not go through as normal to the end-user.

You can communicate a return value from the task to the FRENDS Iron process engine by providing a Boolean output parameter with the name ‘Success’, and setting the value to true if the task execution was deemed successful and false otherwise. The FRENDS Iron process engine reads the value of this property when the task has been completed, and sets the result state of the routine to ‘Ok’ if the property was true and ‘Failed’ if false.

NOTE: If the ‘Success’ property is not found on the task workflow class, the execution is considered to be successful, and the routine is set to ‘Ok’ state.

You can also provide a custom string message that is displayed in the routine instance's task instance list once the task has completed. To do this, you only need to define a string property named ‘UserResultMessage’ with the message in your workflow. The process engine will read this value and store it in the history database, from which it is then shown by the user interface.

ActionSkipped return value

If your task has a logical precondition, e.g. it checks if a directory has any files before trying to copy them, you may want to show a different end result if the precondition failed and the actual action was skipped. Since version 3.1, FRENDS Iron has a separate end state for task instances like this: ActionSkipped. It signals that the execution was successful, but did not do anything.

To show the task instance end state as ActionSkipped, you need to provide two Boolean output parameters and set their value to true:

• Success -the property already discussed above that signals that the task executed successfully
• ActionSkipped - the new property signaling the task failed some precondition and did not execute its main action

Providing your own WF runtime service

For activities that would require more than a simple calculation, e.g., communication with external systems or other potentially long running processes, you should create a local WF service for handling the actual work, so the workflow execution does not block unnecessarily. For details on creating a local WF service, see the WF documentation.

Once created and compiled, the service can be added to the runtime as follows:

• The assembly containing the service should be copied to the FRENDS Iron installation directory.
• In the FRENDSAccService.exe.config file, you can add the service to the set of available runtime services simply by adding a new entry under the \configuration\workflowRuntime\services node. For details on the configuration formats, see the MSDN for Workflow configuration files.

Workflow versioning

If you change a workflow that has already been deployed and is in use, you must change the assembly version. Otherwise, you will run into problems when using tracking profiles and when dehydrating persisted workflows. If, for instance, a workflow is suspended and persisted in the database, waiting for a message, updating the workflow assembly without changing the version will make the runtime to try to rehydrate the stored state using the new assembly. If there are any changes in the workflow, e.g. new activities or variables, this dehydration is likely to fail.

Workflow persistence

FRENDS Iron uses Windows Workflow Foundation for defining and executing individual tasks. To allow for long-running processes and error recovery, the workflows are automatically persisted to a database. This allows the execution of a workflow to be resumed after long periods of inactivity or server restarts. FRENDS Iron uses the standard SqlWorkflowPersistenceService to persist the workflows to the WorkflowStore SQL Server database.

The execution will be continued from the latest persistence point. Workflows are persisted on following occasions ( http://msdn2.microsoft.com/en-us/library/aa663362.aspx):

• After executing a transaction scope or another activity marked with the PersistOnCloseAttribute.
• Before workflow instance completion or termination
• When the workflow instance goes idle (for five seconds) or is unloaded

These rules apply to any FRENDS Iron task workflows: if there are no delays or activities that demand persistence, the workflow will get persisted only when it completes. Therefore, if the server shuts down unexpectedly, the task workflows may not be resumed: the next execution will begin from the start of the task. You should usually consider tasks as stateless, transient.

If you need to make sure the tasks will continue from a specific location, you should explicitly persist the workflows. You can do this either with a custom activity decorated with the PersistOnCloseAttribute, or use a transaction scope.

Tracking activities

Workflow event logging

By default FRENDS Iron logs all workflow runtime error messages to the event log. You can change the logging settings from the FrendsAccService.exe.config file by modifying the value parameter on any of the switches in the ‘system.diagnostics’ section. Allowed values can be found in MSDN.

    </system.diagnostics> 
    ... 
    <switches> 
        <add name="System.Workflow.Runtime" value="Error" /> 
        <add name="System.Workflow.Runtime.Hosting" value="Error" /> 
        <add name="System.Workflow.Runtime.Tracking" value="Error" /> 
        <add name="System.Workflow.Activities" value="Error" /> 
        <add name="System.Workflow.Activities.Rules" value="Error" /> 
    </switches> 
    </system.diagnostics> 

Workflow tracking

FRENDS Iron uses the default WF SqlTrackingService to store workflow execution details to the SQL database. For the workflows that have been run from FRENDS Iron, you can access this data simply by right clicking on the executed task instance and selecting View execution in the Routine Instance list view. All public properties of the workflow are tracked and shown in the Workflow Monitor by default. If you don't want to show the property values in the Workflow Monitor, you can assign the PasswordPropertyTextAttribute to the property. This needs to be done during design time in the Visual Studio workflow development environment.

Windows Workflow Foundation provides a tracking service that stores the execution details of an executed workflow. By default, only the details on what activities were executed, are stored. If you wish to store other information from the execution, you need to define and store a tracking profile.

With FRENDS Iron, there are two ways of creating a WF tracking profile:

1. You can create a default tracking profile when creating a new task by selecting the checkbox “Enable Tracking Profile”. This will create a tracking profile that tracks all workflow events, activities and extracts all string or value type data.
2. You can create a tracking profile by hand, using, e.g., the Workflow Tracking Profile Designer, distributed as a sample in the .NET framework 3.5 documentation. For details on using the designer, please refer to the framework sample documentation or FRENDS Tutorial 3.

You may consider creating a task without a tracking profile (or removing an existing profile) especially if a task is used in a repeating routine – large amounts of executions with the default tracking profile may cause the tracking database to fill up. The tracking profile of a task can be deleted by unchecking the “Enable Tracking Profile” checkbox in the task properties dialog and clicking OK. This removes the tracking profile, and after restarting the FRENDS Iron service, no extra execution details like parameter values are stored to the tracking database. You can create a default new tracking profile by checking the “Enable Tracking Profile” checkbox again.

LOG table

The LOG table in the FRENDS Iron control database is meant for simple activity logging: you can use it to store key-value pairs with timestamp information. You can store e.g. the latest status of an order process, or keep track of the total order amounts.

The LOG table has the following structure:

The data stored to the table could be as follows:

To add entries to the LOG table, it is recommended to use the provided stored procedure, [dbo]. [AddLogEntry] It inserts the current timestamp to the new row automatically. Reports can then be generated by querying rows using the key columns, taking aggregates as needed.

The LOG table is not a full-blown business activity monitoring (BAM) implementation. It is meant to be used when you only need to track a small number of activities (< 100 updates per minute), and the data you need to track can be defined at design time. As said, you also need to create your own user interfaces for the data. In many cases it may be wise to use a ready BAM solution or create your own log system.

Ready-made WF elements

FRENDS Iron uses Windows Workflow Foundation for defining and executing its processes. FRENDS Iron comes with a set of ready-made WF activities and workflows that can be used for basic BizTalk integration.

WF Activities for FRENDS Iron

FRENDS Iron comes with a set of ready-made Windows Workflow Foundation Activities, mainly for integration with BizTalk Server. The activities are installed in the Frends.Acc.WF.BizTalk.dll assembly. You can use the activities in your own workflows created with Visual Studio 2008 and hosted in FRENDS Iron.

BizTalk Two-Way Activity

The BizTalkTwoWayActivity is a sequence activity that sends a single message to the specified BizTalk Server receive location and waits for a response. The activity also has a timer for specifying a timeout for the wait.

This activity is used in the BizTalkTwoWayWorkflow. It has three mandatory parameters:

• Uri - the URI of the BizTalk receive location to send the message to.
• TimeOutSeconds - the timeout in seconds. If no timeout is specified, the default is 10 minutes.
• InMsg - the message to send to BizTalk.

In addition, you can provide the PartyName as a parameter to the activity. This name will be assigned to the DestinationParty property in the message sent to BizTalk.

There are two parameters for activity output:

• MessageId - the Id of the actual message sent to BizTalk. This parameter is set when the message has been sent so you can track the process also when it is executing in BizTalk, using HAT, for instance.
• OutMsg - the response message from BizTalk.

BizTalk One-Way Activity

The BizTalkOneWayActivity is a one-way activity that sends a single message to the given BizTalk Server receive location and returns without checking for the response.

This activity is used in the BizTalkOneWayWorkflow. It has two mandatory parameters:

• Uri - the URI of the BizTalk receive location to send the message to
• InMsg - the message to send to BizTalk.

As with the Two-Way activity, you can also define the PartyName property.

There is also one output parameter:

• MessageId - the Id of the actual message sent to BizTalk. This parameter is set when the message has been sent so you can track the process also when it is executing in BizTalk, using HAT, for instance.

BizTalk Receive Location Activity

The BizTalkReceiveLocationActivity is meant for enabling and disabling BizTalk receive locations. This can be useful if you want to take advantage of FRENDS Iron scheduling with existing receive locations.

BizTalk Send Port Activity

The BizTalkSendPortActivity is meant for starting and stopping BizTalk send ports. This can be useful if you want to take advantage of FRENDS Iron scheduling with existing send ports.

WF Workflows for FRENDS Iron

In addition to a set of ready-made WF Activities, the FRENDS Iron installation includes a set of WF Sequential Workflows that make it possible to use the ready-made Activities out-of-the-box, without the need for creating a new workflow using Visual Studio 2008.    

The BizTalk workflows can be found in the assembly Frends.Acc.WF.BizTalk.dll:

• BizTalk Two-Way Workflow - meant for sending a single message to BizTalk, and waiting for the response. The single activity in it is the BizTalkTwoWayActivity.
• BizTalk One-Way Workflow - meant for sending a message to BizTalk Server without waiting for a response. The single activity in it is the BizTalkOneWayActivity.

There are also three ready-made WF workflows meant for simple preconditions (in assembly Frends.Acc.WF.Conditions.dll):

• Always Condition – a sample condition workflow used for creating the system conditions 'Always True' and 'Always False'. It merely sets the 'Success' parameter to a value according to its rule definition.
• File Exists Condition – simple workflow with a single policy activity and a ’FilePath’ parameter.
• Ping Condition - a sample condition workflow that pings the host (given in the ’Host’ parameter) and sets the ’Success’ output parameter to true if the host responded..

BizTalk Server integration

FRENDS Iron is meant to work on top of BizTalk Server. The idea is that BizTalk is used for all those tasks it does well, like message transformations, connections to backend systems, long-running transacted processes, processing large amounts of messages etc.

FRENDS Iron is used for triggering and parameterizing these BizTalk solutions, either according to a schedule or manually. FRENDS Iron process engine registers itself as an isolated adapter to BizTalk, and sends the trigger messages to BizTalk using the adapter interface. A configured receive location in BizTalk is all that is needed for receiving the messages from FRENDS Iron.

Submit Adapter

The Submit adapter used by FRENDS Iron uses the SubmitDirect sample programmatic adapter from BizTalk Server SDK. For more information on this adapter, see the SDK documentation.

Registering the FRENDS Iron submit adapter to BizTalk

Before you can create a receive location for FRENDS Iron, the Submit adapter must be registered to the BizTalk group. The adapter is installed by the setup program and added to the group's list of available adapters. If you need to install FRENDS Iron on multiple hosts in a group, you don’t need to install the submit adapter separately.

If the adapter is not correctly installed on the server, you may need to install it yourself later on as described below:

1. Open the BizTalk Server Administration Console and expand BizTalk Server Administration > BizTalk Group [Name] > Platform settings > Adapters.
2. Right-click on the Adapters node and choose New > Adapter from the menu.
3. In the Adapter properties dialog, give the adapter a name, like 'FRENDS' and choose 'Submit' from the Adapter combo box.
4. Click Ok. The new adapter should show on the list.

Receive location configuration

In order to pass messages from FRENDS Iron to BizTalk Server, you need to specify a Receive Location and a Port, using the Submit Adapter:

1. Open the BizTalk Server Administration Console and expand BizTalk Server Administration > BizTalk Group [Name] > Applications > BizTalk Application 1 > Receive Ports.
2. Right-click on the Receive Ports node and choose New > Request Response Receive Port... from the menu.
3. In the Receive Port Properties dialog, give the Receive Port a name, like 'FRENDS In'.
4. Choose Receive Locations from the list on the left side of the dialog, and click New... to create a new Receive Location on the Receive Port.
5. In the Receive Location Properties dialog, give the Receive Location a name, like 'FRENDS In'.
6. Select Submit as the Transport Type from the combo box, and click Configure....
7. In the Submit Transport Properties dialog, give the Uri property a unique value, like 'Tutorial1'.
   

   NOTE: This value is used for passing the message from FRENDS Iron to the correct endpoint, and is needed for configuring the FRENDS Iron task later on.

8. Click Ok when done.
9. In the Receive Location Properties dialog, set the Receive Pipeline to ‘XmlReceive’, so the message in FRENDS Iron will be parsed and the properties promoted.
10.  Click Ok. The receive port and location should be available.

Troubleshooting

While developing FRENDS Iron solutions is rather easy, there are many things that can go wrong in the process. This section gives some guidance on what to do in case of errors while executing FRENDS Iron processes.

For troubleshooting concerning FRENDS Iron configuration see FRENDS Iron Configuration Tool Documentation.

Finding the reason for the error: viewing logs

The first step in fixing an error is to find out what caused it. The FRENDS Iron user interface shows the user simple error messages when it encounters an error, but the technical details of the errors are written to a log file. For the FRENDS Iron process engine, no user interface is available, so all error and informational messages are written to a log.

All in all, the log entries are written in two locations.

• Critical errors from the FRENDS Iron process engine service are logged to the Windows Event log.
• Informational and debug events are logged to files located under the directory Logs\ in the FRENDS Iron installation folder:
  • FRENDSAccService.log for FRENDS Iron process engine events, and
  • FRENDSAccManagementConsole.log for FRENDS Iron UI events.
  • In debug builds, the general trace log listener is also configured on by default for the FRENDS Iron process engine service . It logs the following information to the file TraceOutput.log:
    • All informational, debug and trace messages of the process engine
    • All messages from the WF runtime

Checking the event log for critical process engine errors

FRENDS Iron process engine exceptions are logged to the event log, under the event source ‘FRENDS.Acc.Service’. The log entries contain the exception message along with execution trace.

Checking the log files for execution details

Both the FRENDS Iron process engine service and the FRENDS Iron Management Console write their informational messages to a log file. These files are located in the Logs\ directory under the FRENDS Iron installation directory.

Just open the log files using a text editor. For diagnosing errors, it is usually best to navigate to the end of the file to see the most recent messages, and look especially for WARN and ERROR entries.

In some situations, checking the trace output log can also be beneficial, at least in diagnosing where the actual error happened.

Contacting FRENDS Support

If the following common solutions do not provide the necessary assistance, contact our support: support@frends.com. They can provide you with additional support and debugging symbols if necessary.

Common errors and fixes

BizTalk reports a routing failure when sending a message from FRENDS Iron

You try to use the ‘BizTalk One-Way call’ or ‘BizTalk Two-Way call’ task to send a message to BizTalk, and the message seems to have been sent, but BizTalk reports the message could not be routed because no subscriptions were found.

BizTalk routing failures can be caused by multiple reasons. The following causes, with simple fixes, are probably the most common:

The BizTalk receive location uses the PassThru Receive pipeline

If the BizTalk receive location uses the PassThruReceive pipeline, the schema of the message is not recognized and no subscriptions that depend on it will match the message.

Set the FRENDS Iron receive location to use the XmlReceive pipeline.

The message sent is empty

The message sent to BizTalk is defined by the InMsg property in the routine parameters. Check the property value from the routine properties window. If the property is empty, fill a valid value, such as a connection point data reference to it. For instance, for sending the entire CP data structure to BizTalk, as is usually done, set this parameter to ‘{CP:/}’.

Timeout when running Biztalk Two-Way Call

You try to use the ‘BizTalk Two-Way call’ task to send a message to BizTalk and wait for a response. BizTalk does not respond within the specified timeout and the call is terminated.

There can be many reasons for the call to BizTalk not returning within the specified timeout. If the processing of the message simply takes long, you should adjust the timeout to a large enough value.

If the timeout is reasonably long (e.g. 60 seconds) but the process still times out, then it is likely there was some error when processing the message instance within BizTalk. Check the Event log, BizTalk Administration Console or Health and Activity Tracking tools for possible error messages. If the reason was a routing failure, see above for possible solutions. However, if the error was internal to the BizTalk process, please refer to the BizTalk documentation for troubleshooting guidance.

WF Tracking service throws an exception when a workflow has been changed

You have made a modification to a workflow used by a task or condition, and replaced the assembly with the new version. When executing the task or condition, an exception is thrown from the System.Workflow.Runtime.Tracking namespace (see the stack trace).

If you have made a modification to a workflow that has been used in FRENDS Iron, and tracked to the tracking database, you need to clear the database from previous instances of the same workflow instance. The easiest way of achieving this is to recreate the tracking database. For details on this, please see the .NET Framework 3.0 SDK documentation.

FRENDS Iron process engine does not start

FRENDS Iron process engine service does not start.

There are many reasons why the FRENDS Iron process engine service may refuse to start correctly. Common reasons are disabled FrendsAccService, database connection problems, invalid configuration file, or expired license. See the event log for more detailed information and contact support if the issue cannot be resolved.

If the service is disabled, please enable it from the Services applet by finding the Frends Acc Service and changing its Startup type to something else than Disabled from the service properties.

If the problem is with the database connection, please check that the database server is not disabled, is running and not being blocked by a firewall. The error message in the event log indicating a database connection problem will likely look like this:

Service cannot be started. System.ArgumentException: Unable to open database connection
Parameter name: connectionString ---> System.Data.SqlClient.SqlException: 
	A network-related or instance-specific error occurred while establishing a connection to SQL Server. 
	The server was not found or was not accessible. Verify that the instance name is correct and that SQL Server 
	is configured to allow remote connections. 
	(provider: Named Pipes Provider, error: 40 - Could not open a connection to SQL Server)
   at System.Data.SqlClient.SqlInternalConnection.OnError(SqlException exception, Boolean breakConnection)...

If the configuration file is invalid, please backup the old configurations mmc.exe.config and FRENDSAccService.exe.config and rerun the configuration tool FRENDS Iron Configuration.

With license issues please contact our support.

NOTE: Starting the FRENDS Iron process engine service may take over a minute, especially on hosts with little processing resources. This may cause the service applet or the ‘net start’ commands to return a timeout error, even though the service is started.
Before diagnosing startup problems further, please make sure the service really could not be started, and the reason for that from the event log or service log files.

HTTP Endpoint could not be registered

If the FRENDS Iron Service is not running as the built-in Administrator, it can throw a System.ServiceModel.AddressAccessDeniedException, caused by the security settings of the HTTP.SYS component. This error basically means that the Windows Communication Foundation service hosted by FRENDS Iron Service could not open an HTTP port, because the account the service is running on does not have the necessary rights.

The FRENDS Iron installer should set these rights during the install; if the rights do not seem to be set correctly, you could either:

• Add the account running the service to the Administrators group (on Windows Server 2003 or Windows XP), or change the account to using the built-in Administrator account (only this will work on Windows Vista). This is not recommended, however.
• Explicitly give the necessary rights to the account, using HTTPCFG.EXE. For details on how to do this, see the documentation onTechNet or the blog post by Dominic Baier.

Database connection error

A common reason for startup failures is that the connection to the FRENDS Iron control database could not be established.

In the configuration file FrendsAccService.exe.config, in directory \Program Files\Frends Technology\FRENDS Iron, there are two places where the database connection information is given:

• Under the section /configuration/nhibernate/, the FRENDS database connection string is stored in the key hibernate.connection.connection_string

  <nhibernate> 
      … 
      <add key="hibernate.connection.connection_string" 
      value="Data Source=(local); Initial Catalog=FRENDS; Integrated 
      Security=True;"/> 
      … 
      </nhibernate> 
  

• The other needed connection details, to the tracking database and the BizTalk database, are stored under the section /configuration/connectionStrings

  <connectionStrings> 
      <add name="Frends.Acc.Service.Properties.Settings.BizTalkMgmtDbConnectionString" 
          connectionString="Server=(local);Initial Catalog=BizTalkMgmtDb; 
      Integrated Security=SSPI" providerName="System.Data.SqlClient" /> 
      <add name="Frends.Acc.Service.Properties.Settings.TrackingConnectionString" 
          connectionString="Server=(local);initial catalog=WorkflowStore; 
      Integrated Security=SSPI" providerName="System.Data.SqlClient" /> 
      </connectionStrings>
  

Make sure these entries point to the right database locations.

Other Configuration errors

Errors in configuration can cause a number of other issues, too. Check the logs for the actual errors and see all configuration entries are ok.

FRENDS Iron process engine crashes after startig

The FRENDS Iron process engine service starts up, but crashes after starting up

If the FRENDS Iron service has started up correctly, but crashes after a while, the most probable reason is a database connection error. Check the Event log and service log files for details, and the sections above for possible solutions.

Cannot connect to the FRENDS Iron web services

The FRENDS Iron web services do not answer to web service calls.

The web services are hosted in the FRENDS Iron process engine service. First, make sure the service is running. If it is, check that the web service addresses are correct: check the FrendsAccService.exe.config file in \Program Files\Frends Technology\FRENDS Iron, and look for following kind of entry:

<system.serviceModel> 
    <services> 
        <service Configuration="returnFaults" name="Frends.Acc.Service.AccSvc"> 
        … 
            <host> 
                <baseAddresses> 
                    <add baseAddress="http://localhost:9999/FRENDSAccService/ControlWSOneWay"/> 
                </baseAddresses> 
            </host> 
         </service> 
    <service behaviorConfiguration="returnFaults" name="Frends.Acc.Service.AccSvcCP"> 
    … 
    <host> 
        <baseAddresses> 
            <add baseAddress="http://localhost:9999/FRENDSAccService/ControlCP" /> 
        </baseAddresses> 
    </host> 
  </service> 

If the address has been changed, use the correct address.

If you are not calling the service from the local machine, also make sure there are no firewalls blocking the connection and that you are using the correct machine name.

WorkflowStore database grows at an alarming rate

If you are using custom workflows with polling routines, your WorkflowStore probably is growing to many gigabytes in size. This is probably caused by a tracking profile that is enabled for the task. This profile will track all properties of all activities in the workflow. Therefore each execution of the workflow results in > 10 rows added to the WorkflowStore database tables (even more, if you have many properties or activities in the workflow).

If the database is growing too much because of this, it is recommended to disable the tracking profile for the workflow. To do this, simply uncheck the Enable tracking profile checkbox from the Task properties dialog and save the changes.

The other option would be to reduce the length of the tracking partition interval as described in http://msdn.microsoft.com/en-us/library/aa347868%28VS.85%29.aspx. The current default is monthly, but it could be changed to weekly or daily, if needed. Then the 'FRENDS Purge History' cleanup job will delete all instances later than this.

FRENDS Iron Management

FRENDS architecture

Technically FRENDS Iron consists of two functional modules, the FRENDS Iron process engine and the FRENDS Iron Management Console, i.e., the user interface. In addition to these, there are several installed resources, like the databases and the assemblies containing ready-made workflows for FRENDS Iron tasks (see Ready-made WF elements for details).

FRENDS Iron process engine

The FRENDS Iron process engine is a windows service, 'FRENDS Acc Service', that handles the actual work in FRENDS Iron:

• Hosts the WF workflow runtime and services
• Launches new routine executions according to schedule
• Creates and starts routine task executions, and expands execution groups when launching routine tasks using connection point groups
• Provides a Web Service interface for process control commands

NOTE: If you are wondering what “Acc” in the service name means, FRENDS Iron was previously called FRENDS Acc. To preserve backwards compatibility, the name of the service or assemblies used was not changed.

The service provides a BizTalk adapter implementation that is registered to BizTalk Server as an isolated adapter

NOTE: For the isolated adapter to communicate with BizTalk, the service needs to be installed on the same host as BizTalk.

The user account and startup type of the service is defined during installation. By default, the service is set to start automatically, which is also the recommended option as the service needs to be running for the scheduling and triggering to work. The service user account is automatically granted access to the FRENDS Iron databases.

The configuration of the service is defined in the FRENDSAccService.exe.config file.

Controlling the service

You can start and stop the FRENDS Iron process service from the Windows Services applet or from the FRENDS Iron Management Console: Right-click on the FRENDS Iron node, and choose Start FRENDS Iron service to start the service.

NOTE: You can only control the service installed on the same computer.

FRENDS Iron process engine commands

The FRENDS process engine has a number of commands that can be used to control routine status from outside the main engine process.

The commands are provided as a Web Service interface, available at the port and location specified during installation (see Installing FRENDS Iron for details). The WSDL description of the service can be accessed by navigating to the Web Service endpoint by default.

Start Routine

StartRoutine creates a new routine instance of the given routine and starts it up immediately. Possible schedules are ignored.

Start Routine With Parameters

StartRoutineWithParameters also starts a new routine instance, but also accepts parameters, given as name-value pairs. These values will be used instead of the values given in the routine parameters. If no value is given in the call, the value given in the routine parameters will be used as the default.

Start Routine By Name And With Parameters

StartRoutineByNameAndWithParameters works the same way as StartRoutineWithParameters, but the routine is defined by name instead of routine ID. This makes deploying routines on other hosts easier: when you import a routine, the ID will be initialized to a value unique in the database at that time – therefore the IDs will most likely not be equal to the original ID.

Stop Routine

StopRoutine terminates all instances of a routine that are currently executing. See StopRoutineInstance below for details on what happens when a routine instance is terminated.

Stop RoutineInstance

StopRoutineInstance terminates a single instance of a routine workflow. The WorkflowInstance.Terminate() call is used for this, so the execution cannot be resumed anymore after it has been terminated.

It is recommended a workflow terminates as soon as possible when a stop command is issued, but the workflow may want to do some cleanup before terminating. For an example of this, see the provided BizTalkTwoWayActivity, which cancels the wait for a response from BizTalk.

Activate Routine

By default, when a routine is created, it is left in the 'Deactivated' state, meaning it will not be triggered according to a schedule, but it must be started manually. To change this behavior, you need to activate the routine, which is done with the ActivateRoutine command. The command changes the state of the routine to 'Waiting'.

Deactivate Routine

The DeactivateRoutine command in turn changes the state of a routine to 'Deactivated'.

Reschedule Routine

Routines are scheduled only once for each time window in their schedule, meaning that a routine with the default schedule 'Always' will execute once a day, at midnight. If you change the schedule of a routine or otherwise want to make the FRENDS Iron process engine re-evaluate the schedule, you can use the RescheduleRoutine command.

FRENDS Iron management console

The FRENDS Iron Management Console is meant to be the tool for operators for managing FRENDS Iron operations. It allows for:

• Creating, viewing, updating, deleting and parametrizing all FRENDS Iron elements
• Manually starting and stopping(terminating) routines
• Monitoring the status of executed processes

The UI is a Microsoft Management Console 3.0 snap-in, which makes it possible to integrate it to the same console view with other Management Console snap-ins, such as the BizTalk Server Administration console (2006, 2006 R2 or 2009) or the event log viewer.

NOTE: Currently, as with BizTalk orchestrations, creating or editing workflow processes is meant to be handled by developers. This means the Management Console UI does not support editing entire workflow processes.

FRENDS Iron databases

FRENDS Iron stores all the information on its elements and their parameters to its own control database, named 'FRENDS'.

All routine execution data (execution times, parameters, results) is stored in a single database table in the FRENDS control database (ROUTINE_INSTANCE). This makes generating reports from the data very easy, e.g. by utilizing SQL Server Reporting Services. A sample of this is provided in Tutorial 2.

As FRENDS Iron also utilizes the Windows Workflow Foundation SqlTrackingService and SqlWorkflowPersistenceService, a separate database instance for these services is also installed by default to the same database server as the FRENDS Iron control database.

Data maintenance

When running FRENDS Iron, routine history data (parameters, start and stop times, results), as well as workflow tracking data is stored to the database. Eventually, this data will fill up the database, unless you clean it up periodically.

For cleaning up the data, parameterized stored procedures are installed with the databases (corresponding scheduled jobs in parentheses):

• BackupFullDB (FRENDS Full Backup) for backing up the FRENDS database.
• BackupLog (FRENDS Transaction Log Backup) for backing up the FRENDS database transaction log.
• PurgeRoutineHistory (FRENDS Purge History) for removing routine history and dropping the inactive workflow tracking data partitions.

Location for database backup files are provided during FRENDS Iron configuration sequence and database jobs are enabled by default. If jobs are not enabled automatically for some reason or you need to disable or adjust them, see Readme.

For more details on cleaning up old WF tracking data, see the .NET Framework 3.0 documentation

Providing high availability for FRENDS Iron host

You can increase the availability of an FRENDS Iron system in two major ways: Firstly, you can create an SQL Server cluster. Secondly, you can run FRENDS Iron services concurrently on multiple hosts, i.e. in a server farm.

SQL Server Clustering

All FRENDS Iron schedule and task information is stored in the FRENDS database on an SQL Server. Also all task workflow tracking and persistence data is stored in the WorkflowStore database. This means that the SQL Server availability is critical for FRENDS Iron to function.

The recommended way to increase the availability of the SQL Server is to create a server cluster. FRENDS Iron will resume operations after a cluster failover: The scheduling loop as well as the persistence and tracking services cannot work while the connection is down, but will retry automatically, and continue after the connection to the database is resumed (more on MSDN ).

Farming

For additional redundancy and better performance, FRENDS Iron can be installed on many servers, all using the same control database. This allows scheduled tasks to run when one of the servers is down as well as distributing task executions to multiple hosts.

For details on how to install FRENDS Iron on multiple hosts, see the installation documentation in Readme

You also need to enable locks on the workflow persistence store, so the workflows are executed on a single host at a time. To do this, you need to define a value to the WFPersistenceInstanceOwnershipDuration and WFPersistenceLoadingInterval settings in the FRENDS Iron service configuration file, FRENDSAccService.exe.config – see the section Configuration files for more details. The persistence instance ownership duration must be longer than the idle timeout – otherwise, there will be errors when the workflow runtime tries to persist an instance that has been running for a while.

There are some things you need to consider when running FRENDS Iron on multiple hosts:

• The load between the different servers is spread randomly: all services are polling for the common database, and the first one to notice a task instance that is ready to launch, starts executing it. This means:
  • The load may be uneven for the different servers at any point in time.
  • All hosts should have identical deployments, i.e. have same versions of assemblies, have the same parameters for routines etc, because you cannot be sure which host will execute the individual task instances.
    Note: This means that also all references to files must be accessible from every node, e.g. a file used by multiple tasks in a routine must be stored in a file share accessible from each node, not in the local file system.
• Task instances will be started in batches. A single batch will run on one FRENDS Iron host. The content of the batches is random, i.e. there may be task instances from different routines / routine instances.
• Once a task instance has been started on one host, it will execute on that host as long as the workflow runtime has ownership on it (see this blog post for more). If the server goes down while executing the task, the other servers will not be able to resume the execution of that task, until the ownership duration has ended.
• If you want to use the BizTalk integration features of FRENDS Iron, like the ready-made BizTalk tasks or the party integration, BizTalk needs to be installed on the same host. This is because the features require BizTalk assemblies to work.
  If you don’t want to install FRENDS Iron on the same host as BizTalk, you can use e.g. custom WCF tasks for communication: expose a WCF endpoint on BizTalk and create a custom workflow and task that uses the WCF send activity.
• The FRENDS Iron management console can only be configured to manage a single FRENDS Iron service instance (the local instance by default). This means:
  • You cannot terminate routines running on other service instances.
  • You cannot restart the FRENDS Iron service instances on other hosts.
  • You can only start routines on the managed service instance

Configuring FRENDS Iron

Configuration files

Most of the operational FRENDS Iron configuration is defined in XML configuration files:

• FRENDSAccService.exe.config for the FRENDS Iron service
• mmc.exe.config for the user interface

These files contain the database connection strings, WCF endpoint configuration, log level configuration and other settings. It is recommended to use the configuration tool for changing most of the settings. The functionality of the configuration tool is described in the next section.

However, some settings can currently only be changed by directly modifying the values in the files. The defaults are usually good enough, but you may want to update the settings by hand in some cases, e.g. when installing FRENDS Iron in a high availability environment on a server farm. These settings are defined in the <applicationSettings> section of the configuration file.

For the FRENDS Iron service, the most important settings change how the workflow engine works (in FRENDSAccService.exe.config):

• WFMaxSimultaneousWorkflows – The maximum number of workflows executed at one time by the workflow runtime. If the value is defined, it is given directly as a parameter to the DefaultWorkflowSchedulerService constructor, where it sets the MaxSimultaneousWorkflows setting. If the value is not given, the default constructor is used, which will mean that roughly 4 workflows at a time per processor core will be executed.
• WFMaxTotalRunningInstances – The maximum number of task instances that can be in the running state simultaneously, by default 100. This setting limits the queue on the workflow runtime, reducing the possibility that a huge queue of instances is created to memory. The WFMaxSimultaneousWorkflows setting sets the limit on how many workflows are executing at one time – the routine instances may be started and left to wait for execution as soon as there are free slots.
• WFMaxRunningInstancesPerRoutine – The maximum number of task instances under a single routine that can in the running state simultaneously, by default 50. As the WFMaxTotalRunningInstances, this setting is also meant for limiting excessive load on the workflow runtime.
• WFPersistenceInstanceOwnershipDuration – The length of time that locks are maintained on idle workflows.
  You should only define this value if you are running multiple FRENDS Iron services using the same database, i.e. in a server farm situation. See the section Farming for more on this.
  If the value is defined, it is given directly as a parameter to the SqlWorkflowPersistenceService constructor. If no value is given, the default constructor is used, which will not set a lock on idle workflows
• WFPersistenceLoadingInterval – The frequency at which the persistence service will poll the database for workflows with expired timers.

  You should only define this value if you are running multiple FRENDS Iron services using the same database, i.e. in a server farm situation. See the section Farming for more on this.

  If the value is defined, it is given directly as a parameter to the SqlWorkflowPersistenceService constructor. If no value is given, the default constructor is used, which will use a 2 minute delay between database polls.

• WFBatchSize – (Deprecated) The amount of routine instances that are processed in a single batch. By default 50.
  In FRENDS Iron 3.0, the processing is done at the task instance level, and this limit is set by the TaskInstanceBatchSize setting.
• TaskInstanceCheckBatchSize – The maximum number of task instances processed at a time. By default 1000.
  If you have many routines scheduled to run at the same time that also use large CP groups, you may want to increase this limit: if there are over 1000 waiting or launched task instances at a time, only the first 1000 of them will be processed. This may leave some task instances waiting long to be launched or started. However, increasing this limit too high may cause the scheduler loop to take long to execute.
• PollDelay – The delay between processing loops, in milliseconds, by default 1000 ms. Note that there only a single batch can be processed at once, so making the loop shorter may not improve performance.
• LicensePath – The path to the folder where the license file, FrendsAcc.lic is located.
• LicenseWarningPeriod – The time (in days) a warning is written to the event log before the license ends.
• ScheduleFullCheckIntervalSeconds - The interval for doing schedule checks for all schedules, in seconds. By default 60, i.e. one minute.
  Once the interval has passed, the schedule of each active routine will be checked. This makes the possible schedule changes to take effect.
  This limit also limits the minimum polling interval for polling schedules: if you have a schedule that should execute every 10 seconds, you should also set the ScheduleFullCheckIntervalSeconds to less than or equal 10 seconds. Also note that if you have many routines, reducing the interval too low may cause the schedule loop take long to execute.
• CheckTaskInstancesForZombiesRunningLongerThan – FRENDS Iron service will periodically check whether there are task instances running whose workflow is no longer existing and mark those workflow executions as zombies. This time limit (in minutes) controls the time for how long the task instance with no corresponding workflow can run before marking it as zombie.

  By default, the value is 30 minutes. If set to 0, health check is disabled.

  Note: In FRENDS Iron server farm environments a task may actually be running on some other FRENDS Iron node than the one which is performing the health check. In such case the health check node may see the task instance as a potential zombie. Therefore the value should be large enough in which all of the worklows should be able to finish. Also the value should be the same on each of the FRENDS Iron nodes.

For the user interface (in mmc.exe.config), the settings are mostly related to the license handling or the BizTalk integration:

• LicensePath – The path to the folder where the license file, FrendsAcc.lic is located.
• LicenseWarningPeriod – The time (in days) a warning is written to the event log before the license ends.
• EnableBizTalkIntegration – If true, the features related to BizTalk, like party support are enabled.
• HATQueryTemplateFile – the file used for running custom queries on HAT for a specific routine. By default ServiceQueryTemplate.trq.
• FrontPageUri – the URI of the page to show in the front page.
• IsFrontPageUriReportingServerUri – If true, the query parameters needed for showing a SQL Server reporting server report in the front page are added to the URI before showing the page.

Configuration tool

You configure FRENDS Iron with the FRENDS Iron Configuration wizard tool. You need to run it to initialize the configuration before you can use FRENDS Iron.

The tool:

• Installs the FRENDS Iron process service
• Registers the FRENDS Iron Management Console
• Installs the FRENDS Iron control and tracking databases
• Configures web service endpoint settings.
• Configures automatic error reporting settings.
• Exports and imports configuration settings.

For more details on all these actions, see the FRENDS Iron Configuration Tool Documentation. The next sections give a quick view on how to configure FRENDS Iron for the first time as well as how to configure logging

First time configuration

For the basic configuration with the default settings, you can just go through the dialogs, giving the basic information:

• The license file - You need to obtain a license to run FRENDS Iron.
  • You can get an evaluation license from the Frends web site at http://www.frends.com/. There you can also find the contacts for purchasing a production license.
• The user account and password to use for running the service – This account is used for connecting to the database and BizTalk. In order to send messages from FRENDS Iron to BizTalk, the user account needs to belong to the BizTalk Isolated Host Users group.
• The name of the FRENDS and BizTalk database servers – The FRENDS databases will be created or updated on the server given. The BizTalk database will be used for registering the adapter. 
  • If you are using remove database servers, you need to take into account some special considerations. See section Installing on a remote database server in Readme.htm for details.  

See the configuration tool documentation for details on all the options available.

The actual configuration settings are stored in text files in the FRENDS Iron installation directory:

• mmc.exe.config for the user interface
• FRENDSAccService.exe.config for the process engine

It is recommended that you do not edit these files yourself.

Logs

FRENDS Iron writes log entries to a file during its operation, and these files can be used to check for possible problems or issues. The log files are written to the /Logs subdirectory of the installation directory.

The default log files are:

• FRENDSAccService.log - Information messages from the process engine service
• FRENDSAccManagementConsole.log - Information messages from the FRENDS Iron Management Console

FRENDS Iron internally uses the log4net logging library. You can control the level of logging and where the log messages will be written to in the management console:

1. In the FRENDS Iron Management Console, right-click on the FRENDS node and choose Configure logging in the menu.
   
2. You can change the logging levels for the FRENDS Iron internal logging (“FRENDS messages”) and database diagnostic logging (“NHibernate messages”). The defaults are usually fine, but if you want to diagnose errors, it may help to e.g. set FRENDS Iron messages level to “DEBUG”.
3. By checking the Log everything to trace stream checkbox all messages are written to the system trace stream in real time. This allows you to see what is happening at runtime using a tool like DebugView
4. The Log file settings allow you to define a folder where the log files will be written to.
   NOTE: the FRENDS Iron service user needs to have write rights to this directory.
5. Click OK to apply the changes. The changes will be written to the configuration files and taken into use immediately – you don’t need to restart the service or UI.

Version history