- Click on the browse (...) button.
- Select "Frends_Cobalt_CP.xsd" from the installation folder, default: C:\Program Files\Frends Technology\FRENDS Iron.
These Terms of Delivery and Use (“Terms”) shall apply to FRENDS Cobalt software in object code form and any related documentation (“Product”) ordered and delivered to the licensee (“you”) by Frends Technology Inc (“FRENDS”).
You agree to be legally bound by these Terms by selecting the accepting option below or by using the Product. If you do not agree to these Terms do not download or use the Product.
You may download an evaluation version of the Product, in which case you are entitled only to evaluate the Product before purchasing a commercial version of the Product. When you download and purchase the commercial version of the Product, you shall first pay an applicable license fee with your credit card or other payment methods available. After the due payment, FRENDS shall deliver you a registration code, which enables the operation of the Product.
It is important, and therefore you represent and warrant, that the identification and contact information you have provided to FRENDS in connection with your order for the Product is accurate and complete. Otherwise FRENDS may not be able to verify your payments and deliver you the necessary registration code. All identification and contact information will be subject to the privacy policy of FRENDS.
You shall be responsible for acquiring at your own expense all necessary software, equipment and telecommunications for using the Product.
The Product is neither intended nor fit for the use of consumers but companies only. Furthermore, the Product is not designed to be fault-tolerant and therefore it is not intended for use in hazardous environments that require fail-safe performance, such as in connection with life critical applications and systems.
You have a limited, non-exclusive and non-transferable right to install and use one (1) copy of the Product on one (1) server or workstation.
If you have downloaded an evaluation version of the Product, you are entitled to use the Product, free-of-charge, strictly for the sole purpose of evaluating the features and usability of the Product, during a period of thirty (30) days from the day you downloaded the Product.
If you have downloaded a commercial version of the Product, you are entitled to use the Product, subject to the payment of an applicable license fee, strictly for your internal business purposes only.
In addition, you shall not (i) make other one (1) back-up copy, modify, work around any technical limitations, decompile, disassemble, reverse-engineer, or create derivative works based on, the Product; or (ii) assign, transfer, sublicense, rent, or otherwise distribute or make available, the Product or your limited right to use the Product; save to the extent that otherwise expressly provided for by mandatory provisions of applicable law.
The Product is licensed strictly “AS IS” without any warranty, express or implied, whatsoever, including but without limitation to warranties of merchantability, fitness for any particular purpose, performance or non-infringement. You shall assume the entire risk for your use of the Product. FRENDS shall have no obligation to provide you with maintenance, support or other consulting services, or upgrades of the Product.
However, if you have downloaded, and duly paid for, the commercial version of the Product, but there have been errors in the transmission that prevent the operation of the Product, and you are not able to reload the Product, you should inform FRENDS without delay. FRENDS shall then make the Product available for a new downloading over Internet, or send the Product via email or ordinary mail to you. In case of an ordinary mail, you shall bear the costs of shipping.
Title, ownership and all intellectual property rights to the Product belong exclusively to FRENDS or any supplier of FRENDS. You are granted only a limited right to use the Product.
Aspects of the Product, including the specific design and structure, and registration codes enabling the use of the Product, are confidential and trade secrets of FRENDS or any supplier of FRENDS. You shall maintain such information as strictly confidential, and shall not disclose them to any third party or use them for any unauthorized purpose.
Due to the fact that the Product is licensed to you strictly on an “AS IS” basis without any warranty, to the maximum event permitted by the applicable law neither FRENDS nor any supplier of FRENDS shall be liable for any damages whatsoever, including but without limitation to direct, indirect, special, consequential, punitive or incidental damages, and loss of revenue, profit or data. In any case the maximum liability of FRENDS shall be EUR 100.00. These limitations of liability constitute an essential part of these Terms. However, should your authorized use of the Product violate any third party intellectual property rights, FRENDS shall compensate you for the license fee you have paid provided that you inform FRENDS of the suspected or actual violation without undue delay and discontinue the use of the Product.
This Agreement shall be governed by substantial laws of Finland. Any and all disputes arising out of these Terms shall be intended to be settled amicably. In case an amicable settlement is not reached, the dispute shall be submitted to the District Court of Helsinki, Finland.
Please note that you must use the Product in compliance with applicable export and import laws, regulations and rules, if any.
Each license to the Product shall terminate immediately and without notice in case you are in breach of these Terms, with the exception of such provisions that by their nature are intended to survive the termination of these Terms. Furthermore, FRENDS shall not be obligated to refund the license fee to you.
These Terms constitute the entire agreement between you and FRENDS, and shall supersede any previous written or oral agreements and understandings, in relation to the subject matter of these Terms. Any and all amendments to these Terms shall be made in writing and expressly accepted by both you and FRENDS.
FRENDS Cobalt is a Windows Workflow Foundation (WF) solution built on top of FRENDS Iron for scheduled transfer of files.
With FRENDS Cobalt you can easily automate recurring file transfers within the enterprise. The transfers are configured as a single XML structure from the FRENDS Iron management console. The same console can be used to run and monitor the transfers as well.
FRENDS Cobalt can read files from and deliver files to file system, FTP, FTPS and SFTP servers. Text file encoding can be changed and XML files can be converted using XSLT in message processing steps. Files can naturally be transferred without conversions as well.
Possible errors in FRENDS Cobalt executions are reported to the Windows EventLog and in FRENDS Iron as well, so operators can take action as required. There is also a sample transfer log database that can be used to log transfer details and show reports on failed and successful transfers. In addition, FRENDS Cobalt uses Log4Net for logging purposes that can be configured to e.g. send reports as needed.
ActionSkipped state. See FRENDS Iron documentation for more information on ActionSkipped state.
FRENDS Cobalt is installed and configured with FRENDS Iron.
Unzip the FRENDS Iron package and run the Windows Installer installation package. Check the prerequisites and follow the instructions in readme.rtf
The installer installs the needed libraries and executables. After installing, you need to run the FRENDS Iron Configuration Tool to set up the Windows services, databases and other settings. The installer suggests you do this at the end of the installation.
FRENDS Cobalt is configured together with FRENDS Iron with the FRENDS Iron Configuration tool. For details on this, see the FRENDS Iron configuration tool manual and the FRENDS Iron readme.rtf.
In order to configure FRENDS Cobalt, you need to make sure the checkbox for "Import FRENDS Radon/Cobalt sample routines" is checked. This will import the sample routines, tasks and CPs, as well as copy the needed assemblies to the FRENDS Iron installation directory.
If previous versions of the assemblies are already installed in the FRENDS Iron directory, the configuration tool will ask for confirmation before copying the files. If you choose to continue, the existing assemblies will be overwritten. In this case, if the sample tasks are also installed, new copies of them will be imported using new names like "FRENDS Cobalt Sample Routine (2)"
You can log details of the file transfers and the transferred files to a database. However, because reporting needs vary greatly, the database logging is not turned on by default. To turn it on:
Create the needed database structures to a database. Logging expects there to be
a stored procedures named sp_InsertTransferInfo and sp_Signal_TransferComplete.
For details on these, see the section Stored procedures
below
You can create the sample database structures with the included SQL script file
CreateTransferLogDatabaseStructure.sql, as described in the guide SampleTransferLogDatabaseAndReportsInstallation.html
Please note that the sample database tables and reports that come with FRENDS Cobalt are only meant as samples on how to use database reporting. You should review the database scripts and modify them if needed.
For instance, the sample stored procedures will automatically remove data older than one month. If you want to change this period, or change the simple way the cleanup is currently done, you need to change the stored procedure.
In any case, you should make sure the database is backed up and cleaned up regularly.
Frends.Cobalt.Properties.Settings.FileTransferLogConnectionString.
For example:<add name="Frends.Cobalt.Properties.Settings.FileTransferLogConnectionString"
connectionString="Server=(local);initial catalog=FRENDS;Integrated Security=SSPI"
providerName="System.Data.SqlClient" />
If the database transfer logging is enabled (the connection string is defined), Cobalt calls two separate stored procedures:
@BatchId as a parameter, and can
be used to do some post processing for the batch of files. You could e.g. move the
data to a more suitable reporting structure.If calling either of these stored procedures fails, Cobalt will retry the write once after one second, if it fails again the failure is logged with the same logger as other workflow errors, by default to the event log.
log4net can be used to help with logging / notifications on file transfers. All succeeded file transfers are logged as INFO level events and all failures are logged as ERROR level events.
The name of the logger used is provided in the routines task parameter "TransferLoggerName" and the logger can be configured in the FrendsAccService.exe.config file.
Example logger configuration with SmtpAppender for log4net:
<appender name="CobaltSmtpAppender" type="log4net.Appender.SmtpAppender">
<to value="to@domain.com" />
<from value="from@domain.com" />
<subject value="Cobalt transfer result" />
<smtpHost value="SMTPServer.domain.com" />
<bufferSize value="1" />
<lossy value="true" />
<evaluator type="log4net.Core.LevelEvaluator">
<threshold value="ERROR"/>
</evaluator>
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%newline%date [%thread] %-5level %logger [%property{NDC}] - %X{transfername} file: %X{sourcefile} ended with result %X{result} - %message%newline%newline%newline " />
</layout>
</appender>
<logger name="FileTransferSmtpLog">
<appender-ref ref="CobaltSmtpAppender" />
<level value="ERROR" />
</logger>
The following variables can be accessed in the conversionPattern with the %X{variableName}:
Log4net is designed to fail silently if it fails while trying to write to the log appender. This should be taken into account when creating reporting with log4net.
Upgrading from 1.5 or older versions requires you to recreate the transfer configuration CP's with the new schema versions as well as use the newer versions of the Cobalt routines.
Routines and CPs from 1.6 are compatible with the latest 1.7 version: even though the schemas have been changed, the old schema is still accepted and e.g. the encoding operations are dynamically converted to corresponding message processing steps.
Please note that the Rebex.Net assemblies have been updated from 1.0.2896 to 1.0.3723, and you cannot use the old Rebex versions with the newer Cobalt versions or vice versa - unless you deploy the older Rebex.Net versions first to the Global Assembly Cache (GAC).
Also please note the changed CP schema requires you use Iron 2.4 SR1 or later. On previous Iron versions the existing schemas may not update correctly, and MessageProcessingStep nodes will get duplicated every time you edit the CP. This issue was fixed in 2.4 SP1.
The API references were modified since the 1.7 beta, so upgrading to the final 1.7 version requires you to update and recompile possible extensions made against the 1.7 beta. Also, since 1.7 beta used the same old Rebex.net assemblies as 1.6, upgrading to the final 1.7 version means you need to update all workflows using the Rebex assemblies at the same time.
You may not want to upgrade all existing Cobalt workflows to use the latest workflow, e.g. if you have made extensions that rely on a specific version of Cobalt. To do this, you need to deploy the different Cobalt versions to the Global Assembly Cache (GAC), where they can be loaded to different workflows as needed.
Because the latest version of Cobalt requires many improvements and fixes to FRENDS Iron, the recommended way to upgrade Cobalt is to upgrade Iron (and Cobalt with it) to the latest version. This way, there should be no compatibility problems or issues with bugs already fixed.
However, if you absolutely cannot update Iron, and accept that you will likely encounter problems, you can update Cobalt manually as follows:
\Program Files\Frends Technology\FRENDS
Iron\Program Files\Frends Technology\FRENDS.
Normally these are updated with Iron, but you can find the latest assemblies
also from the zip file, in folder Frends.Cobalt.Extensions\libFRENDSCobalt-Routine.xml file.
Now the created FRENDS Cobalt transfer is ready to be run from the routines view. Just right click and select "Run Once".
If so desired the routine can be scheduled to be run with the regular FRENDS Iron scheduling tools.
FRENDS Cobalt is implemented as a Windows Workflow Foundation 3.5 workflow that is run in a FRENDS Iron routine. The next section describes the steps in the workflow of a typical file transfer.
The file transfer workflow is depicted in the diagram above. The overall process goes as follows (the step names correspond to the activity names in the diagram):
If the opening of the connection to the source endpoint fails, or the listing of
the source files fails, the transfer is immediately aborted and an error is logged
to the event log.
Note: This error will not be logged to the database.
If the source connection is opened correctly, but the transfer of a single file
fails, the workflow will try to continue from the next file until all the files
have been processed.
Note: This means there may be many redundant tries to move files if e.g.
the user does not have rights to write to the destination. There will be a separate
error for each attempt.
On connection errors FTP(S) and SFTP endpoints will try to reopen the connection
and retry the failed operation once per operation.
While in most cases the core functionality FRENDS Cobalt provides for file transfer is sufficient, you may have cases which require more functionality. If, for example, the file conversion options are not sufficient enough, you could create a custom MessageProcessingStep for handling the required conversion for transferred files. You may also want to use a completely different protocol for transferring files than what are available in FRENDS Cobalt by default. Support for different protocols and other custom endpoint behavior can be achieved by creating a custom endpoint. Information on how to extend FRENDS Cobalt and some samples can be found Extending FRENDS Cobalt.
There are two places where transfer parameters can be set:
The Cobalt task takes four parameters: the transfer configuration as XML, and a set of optional technical parameters for the transfer:
The transfer configuration as XML string. It is recommended the configuration is
given as a CP reference, i.e. {CP:/}
Folder that FRENDS Cobalt uses to store local working copies of files. If empty, the FRENDS Iron service user account's temporary directory is used. Note: If you define the WorkDir, make sure the FRENDS Iron Service user account has read, write and modify access to the directory.
Free-form name describing the transfer. It is shown in error and transfer log reports, and can be used to group many different transfers together in the reports
Name for the log4net transfer logger, if one is used. For details on this, see section "Configure logging file transfers with log4net"
[File | Ftp | Ftps | Sftp | Custom]
The protocol type to use. The type specific configuration is defined in the sections
below
Directory on server where the transferred files are located. You can also use relative
paths, in which case the path will be resolved relative to the initial working directory.
For FTP/SFTP, this directory is the user's home directory, and relative paths should
work OK. However, for File endpoints, it will be \Windows\System32\
by default. As this almost certainly is not correct, you must always use absolute
paths for File endpoints.
Note: When using FTP transfer the FTP user must have read, write and modify permissions to source/destination folder. If local directory is used, read, write and modify permissions to the source/destination directory must be assigned to FrendsAccService user.
Macros can be also used for defining the directory. See Macro reference for details on how to use macros.
Name of the file(s) to be transferred. File masks can also be used here for transferring several files. The file mask uses regular expressions, but for convenience, it has special handling for '*' and '?' wildcards. See the table below for examples.
| Mask | Matches | Does not match |
|---|---|---|
| *t.txt | text.txt, t.txt | foo.txt, text.foo |
| ?t.txt | 2t.txt | t.txt, tt.foo |
| test.(txt|xml) | test.txt, test.xml | test.foo, foo.txt |
| test.[^t][^x][^t] | test.xml, test.foo | test.txt, test.tii |
| test\d{4,4}.txt | test1234.txt, test6789.txt | test123.txt |
| <regex>^(?!prof).*_test.txt | pro_test.txt, pref_test.txt, _test.txt | prof_test.txt, pro_tet.txt |
Note: Because regular expressions are used, you need to escape special characters
such as parentheses in your filenames with a backslash(\).
E.g. Filename: "customer\(123\)_Q1.xml" to only match the file: customer(123)_Q1.xml.
By default, the regular expressions are compiled as case-insensitive, which means
that a regular expression: file\d{6,6}env.dta would match both filenames
file123456env.dta and FILE445566ENV.DTA. If you want to
use pure regular expressions for matching, like if you want your regular expression
to be compiled as case sensitive or you want to avoid the special handlings for
'*' and '?' characters you have to use <regex> keyword at the
beginning of your regular expression. If, for example, you want to make the previous
example to match only the uppercase filenames, you would use a regular expression
like: <regex>(?-i)(FILE\d{6,6}ENV.DTA).
Common server parameters for the transfer types that fetch files from a remote server.
Address of the server.
Port number for server.
Username to logon to server. NOTE: File endpoint only supports username for remote shares and needs that the username must be in the format DOMAIN\Username.
Password for user on the server.
FTP specific settings
[Ascii | Binary]
[Passive | Active]
FTP connection mode.
SFTP specific settings
[Username-Password | Username-PrivateKey | Username-Password-PrivateKey]
Location of private key file to be used for authentication if public key authentication is used on the server.
Password for private key file.
Fingerprint for SFTP server. When using Username-Password authentication it is recommended to use server fingerprint in order to be sure of the server you are connecting.
FTPS specific settings
[Ascii | Binary]
[Passive | Active]
FTP connection mode.
[true | false]
Is protection of transferred data required.
[Explicit | Implicit]
[true | false]
If client authentication is enabled both client and server are authenticated. The client certificate is searched from user's certificate store.
Required if client authentication is enabled. The ServerName must be exactly the same as in server certificate.
Timeout for FTP operations is 60 seconds. This means that data transfer is timed out after 60 seconds of inactivity and not from the start of the transfer.
You can provide your own custom endpoint implementation as a compiled assembly, and pass initialization parameters to it via this section. For more details on how to do this, see the Extending FRENDS Cobalt guide.
NOTE: The implementation must extend the EndPointBase base class, and provide the necessary constructors in order to work.
Assembly name where the custom class resides in, e.g. Frends.Cobalt.Extensions,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
Class name of custom class, e.g. Frends.Cobalt.Extensions.FileLogger
Custom parameter string to be passed as is to the custom implementation constructor. This parameter can be e.g. a connection string or any other custom parameters
Destination parameter section contains same parameters as in Source section, so same descriptions generally apply to them too with exception in FileName parameter.
File name or file mask for the remote file. '?' characters are not allowed in file mask. If no file name is given the original file name is used for destination file name.
Examples of usage:
Macros can also be used for destination file names. See Macro reference for details on how to use macros.
General parameters for the transfer
[true | false]
Should the source file be renamed with a temporary file name before transferring
the file. This is a way to prevent other users to access the file with its original
name while transfer is in progress. Set this to false if the used source
endpoint implementation doesn't support source file renaming. Default value is true.
The temporary file name is created using the following scheme: cobalt_[current time in ticks][random 8 character file name].8CO
For example: cobalt_634509139954167644lomy3uzg.8CO
[true | false]
Should the file be transferred to destination endpoint with a temporary file name
and rename it after the transfer is completed. This is a way to prevent other users
to access the file at the destination endpoint with its actual name before the transfer
is completed. Set this to false if the used destination endpoint implementation
doesn't support file renaming. Default value is true.
The temporary file name is created using the same scheme as
for the source file: cobalt_[current time in ticks][random 8 character file name].8CO
[Append | Overwrite | Error]
What to do if destination file exists. By default throws an error.
[Error | Info | Ignore]
What to do if the source file is not found. By default throws an error.
NOTE: This error is not logged by log4net transfer logger, neither is it written in the file transfer log database
What to do to the source file after a successful transfer
[Delete | Rename | Move | Nothing]
Defines the operation to perform to source file(s) after successful transfer. By
default deletes the file from the source directory.
To parameter) can use file macros (and file masks, although
they are not recommended). From 1.6 onwards, you can also move the renamed files
to another directory, by giving a directory path.
To parameter) using the original file names.
The path to move or to rename the files to.
/subdir/%Date%file.txt. If you don't define a directory
path, the source directory is used. When using rename, the To-parameter must always
contain a file name.
You can define steps for processing messages after they have been fetched from the source endpoint but before they are sent to the destination endpoint.
The default Cobalt CP schema has three steps you can use. However, you can have as many steps you like, if you just create a custom CP schema.
[PassThrough | Xslt | Encoding | Custom]
The message processing step type. By default PassThrough.
Parameters for the backup step that takes a local backup of the transferred files.
Root directory for the backups. Must be an absolute local path or network share,
like "E:\Backup\" or "\\store\backup".
For each transfer, a new backup directory named after the file transfer start time
and the batch ID is created underneath the root directory. Copies of all files transferred
in the single transfer will be put to this transfer specific directory.
Number of days to keep the backups. Backup subdirectories older than this are deleted. Dates are compared by the last write time of the directory.
[true|false]
Whether or not the automatic cleanup is enabled. If false (default), the files will
not be cleaned up by the step. Note that if the automatic cleanup is disabled, you
must clean up the files in some other way.
XSLT processing step parameters
Absolute path to the XSL transformation file
Encoding step parameters
Source file character encoding from which to convert.
Destination file character encoding to which to convert.
You can provide your own custom message processing step implementation as a compiled assembly, and pass initialization parameters to it via this section. For more details on how to do this, see the Extending FRENDS Cobalt guide.
Assembly name where the custom message processing step implementation class resides
in, e.g. Frends.Cobalt.Extensions, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
Class name of custom class, e.g. Frends.Cobalt.Extensions.FileLogger
NOTE: The implementation must extend the MessageProcessingStepBase base class,
and provide the necessary constructors in order to work.
Custom parameter string to be passed as is to the custom implementation constructor. This parameter can be e.g. a connection string or any other custom parameters
Can be used to give a descriptive name to a single transfer.
Macros can be used to dynamically configure source directory, destination directory or destination file name for a file transfer.
Generally the following rules apply for macros:
The following macros can be used with all of dynamically configurable locations for file transfer:
Note:With destination file name it is recommended to only use file macros, since in future the usage of file masks for such purpose will be deprecated. Especially, if you want to add a time stamp to a transferred file name, you can only do this with file macros.
Below are some examples with imaginary sample.txt file:
Not recommended:
Recommended:
If the Cobalt workflow is running when the FRENDS Iron service is being stopped,
the workflow runtime tries to pause and persist its state to the WorkflowStore database.
Unfortunately, due to the way the Cobalt workflow is structured, it cannot be serialized
and therefore persisted. This causes the System.Workflow.Runtime.Hosting.PersistenceException
to be thrown, which also blocks stopping the workflow runtime and the FRENDS Iron
service. On the other hand, the Cobalt transfer would not be able to resume the
transfer anyways, so it is good to allow the transfer to finish.
Therefore, you should wait until all current Cobalt transfers have been completed before stopping the FRENDS Iron service.
When renaming or moving source the source files with SourceOperation with FTP, you should note that existing files may get overwritten. At least Microsoft's IIS FTP Server overwrites existing files renaming/moving files, this may happen on other servers as well.
If you want to store the original source files somewhere, and do not want to use
the backup operation, it is recommended to append e.g. the datetime to the moved
or renamed file name by using a file name like %DateTime%*
SourceFileOperations Delete or Nothing are executed only after the actual file transfer has been completed. There is a possibility that they will fail (e.g. another file with the original source file name has been created in the directory, so renaming the temporary file back to the original name (option Nothing) will fail). This error will be logged as a failed file transfer, even though the file has been transferred to the destination. In this case, the logged error description will mention that only the source operation has failed and the file has been transferred.
If you get these kinds of errors, you should fix the original error, e.g. not writing a new file to the source directory with always the same name
The transfer log only logs individual file transfers that have succeeded or failed. If fetching the source files fails, e.g. because the server cannot be accessed, or there are no files and the SourceFileNotFoundAction is set to Error, the transfer will fail, but nothing will be logged to the transfer log.
This issue will be fixed in future versions of FRENDS Cobalt.
While Cobalt 1.8 is technically backwards compatible with Cobalt 1.7, message processing steps or custom endpoints built against Cobalt 1.7 cannot be used by Cobalt 1.8, because the Cobalt reference is strong-named.
There are three ways to fix or work around this issue:
FRENDSAccService.exe.config and
adding the following configuration block into the file.
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="Frends.Cobalt"
publicKeyToken="7d5d218da670e3aa"
culture="neutral" />
<bindingRedirect oldVersion="1.7.0.0-1.7.9999.9999" newVersion="1.8.0.0" />
</dependentAssembly>
</assemblyBinding>
<runtime>
FRENDS Iron service needs to be restarted in order to configuration changes to take effect.