Tuesday, 10 May 2016

Cast Iron Integration process

Cast Iron Installation (Prerequisites)
-   Java version: 6.1.0_67
-   Adobe  flash player(Default)
-   Firefox version: 43.0.1

Java Installation process





Creating Orchestration in cast iron
Click
Enter the project name
Save the project
Create end points
Configure the end points

Create http end point
FTP end point and configure
Test the test conncetion
FTP configuration setup below screens
  

Varible creation
 
Salesforce end point and configure
Proxy setting
Check the test connection
Salesforce configuration
Select the object

Select the xml file and maping the input file.

Mapping the out put file resulting executeing in xml foemat.
Full veiw of Orcehestration
Falt file schema creation.
Goto->project ->Falt file wizard


Browse the file
Next  to next to finish
Parsing the data
Browse -> select file
  
Using  Activities:
Read Flat file
Send email activity
Select send email activity and doble click configure all
 

Check the test conncetion
Send email configure
Mapping the fields

Log message
Mapping the message



Read XML  summary

Browse and select the xml schema data
Mapping data
If Then  condition

Error Logs
Customizing columns in System log and Job log
You can customize the columns displayed in the System log and Job log pages, respectively.
You can customize the columns to be displayed in the System Log and Job Log pages by editing the column display settings. To customize the log page columns, complete the following steps:
Procedure
1.     From the navigation pane, select Logs System Log or Job Log. The System Log page or the Job Log page is displayed.
2.     Click Edit Columns. The Log Columns Settings window is displayed.
3.     Select the columns that need to be displayed on the System Log or Job Log page. By default, all the columns are selected in the Log Columns Settings window.
4.     Click Save. Only those columns selected by you will be displayed in the System Log or Job Log page.

 

Specify System Log Settings

You can specify the level of details that appears in the system logs. The log level you specify affects alerts for notification policies. Alerts are only sent for events that meet or exceed the log level you specify.
Note: If you do not receive notifications for events, it might be that you do not have the system log level set to produce entries that would trigger a notification.

Procedure

1.     In the Navigation pane, select Logs > System Log. The System Log page is displayed.
2.     Click Settings. The System Log Settings dialog box is displayed.
3.     From the list, select a log level for each system.
4.     Click Save.

Results

A confirmation message displays. The system log logs all events that occur at the level you specified or higher for the specific system. For example, if you chose the Error level for Deployment, all events that were Error or Critical level in the Deployment system are logged.

Viewing System Logs

You can view system logs from the Management Console and use the system log filters to sort through system log entries.
When you upgrade, the Management Console does not persist system logs. To retain system log information, export system logs before you upgrade.
Note: The Management Console displays a maximum of 99,999 system log entries. When the number of system log entries exceeds 99,999, the oldest log entry is deleted from the system log.

Procedure

1.     From the navigation pane, select Logs > System Log. The System Log page is displayed.
2.     Choose the filter values from the lists at the top of the System Log page.
You can filter the log entries according to the level of severity for the event, the environment system that generated the log event, dates, and resolution state. The filters use AND logic.

 

 

System Log Content

The system log provides the following information:
System Log Content
Description
Level
Identifies the level of severity of the log event:
  • Critical
  • Error
  • Warning
  • Info
System
Identifies the system where the log event occurred.
Message
Text messages that provides details about the log event.
Job
When available displays Job ID information for log events that occur in the Orchestration system.
When
Records the time when the log event occurred.
Resolved On
Provides a time stamp of when you resolved a log event.
Resolved By
Identifies which user resolved a log event.
Resolved
Select this checkbox to acknowledge that you have resolved a log event. When a user resolves a log event, a time stamp documents the date and time the issue was resolved. Information about the user who resolved the log event is tracked in the Resolved By column. You can resolve all the system log issues, by clicking Resolve All. Clear the checkbox next to any log events that are not resolved and the Resolved On and Resolved By values are cleared.


 

Viewing Job Logs

You can view job logs from the Cloud Management Console and use the job log filters to sort through job log entries.

Procedure

1.     From the navigation pane, select Logs > Job Log. The Job Log page is displayed.
2.     Choose the filter values from the lists at the top of the Job Log page.




Creating or editing an email endpoint

Studio and the Integration Appliance use the connection information that email endpoints provide to connect to POP3 or SMTP servers.
Note: For some email systems, the POP3 server and the SMTP server can have the same name, for example: mail.acmecompany.com.

Creating or editing an email endpoint

1.     In the Create Endpointor Edit Endpoint pane, configure the fields as described in the following table.
Note: Changing the configuration properties of an endpoint affects all orchestrations that use that endpoint in the project. The edits are global, not local.
2.     When complete, click Test Connection to confirm that you can connect to the POP3 or SMTP server. The Get Email activity connects to a POP3 server while the Send Email activity connects to a SMTP server.
3.     Click OK.
Table 1.
Field Name
Description
Location

Get Email From Server
Get Email activity - The Get Email From Server option is automatically selected for an email endpoint used with the Get Email activity. During run time, the Get Email activity gets email from the specified POP3 server.
Send Email To Server
Send Email activity - The Send Email To Server option is automatically selected for an endpoint used with the Send Emailactivity. During run time, the Send Email activity sends email to the specified SMTP server.
Host Name
Get Email activity - The Host Name or IP address for the POP3 server.
Send Email activity- The Host Name or IP address for the SMTP server.
Port
Specify the port number to access the POP3 or SMTP Server. By default, the port for a POP3 server is 110.  
Login

User Name and Password not required
Get Email activity - This is option not available for an endpoint of a Get Email activity. You must specify a User Name and Password for an email endpoint used with the Get Email activity.
Send Email activity - Select this option if you want connect to the SMTP server using an anonymous login instead of a username and password.  Select this option only if SMTP server the supports anonymous logins (where a user account is not required).
Log In to the Server Using a User Name and Password
Get Email activity - This option is automatically selected for an email endpoint used with the Get Email activity. To connect to the POP3 server using a user account, you must enter values into the User Name and Password fields to specify the account used to connect to the POP3 Server.
Send Email activity - Select this option to connect to the SMTP server using a user account. If this option is selected, you must enter values into the User Name and Password fields for the account used to connect to the SMTP Server.
User Name  
Get Email activity - Enter the User Name for the account used to connect to the POP3 Server.
Send Email activity - Enter the User Name for the account used to connect to the SMTP Server.
Password  
Get Email activity - Enter the Password for the account used to connect to the POP3 Server.
Send Email activity - Enter the Password for the account used to connect to the SMTP Server.
Security

Normal Email
Specifies that email runs without SSL.
Email over SSL
Specifies that email runs with SSL. For more information, see Testing an SSL email connection.
Implicit or Explicit
Implicit means that SSL is turned as soon as a connection is made. Explicit requires that the client issue a command to the server requesting that SSL be used.
Client Certificate Alias Name  
Specifies the client alias used to access the trusted certificate in the keystore.  Must be enabled for client authorization by the server. By default, when you select the Client Certificate Alias Name option, Studio provides the following name: Factory Supplied Identity. The alias name you specify in this field should match the value you created when creating the certificate in the keystore.
Additional Parameters
Specifies additional parameters for SMPT processing. The following table lists the parameters:
smtpNewConnEveryTime
Default: false
Description: Specifies creation of a  new connection everytime. If set to true, does not use a connection pool
smtpPoolMinConnections
Default: 1
Description: Connection pool option - Minimum Connections
smtpPoolMaxConnections
Default: 25
Description: Connection pool option - Maximum Connections
smtpPoolMaxIdleTime
Default: 7200
Description: Connection pool option - Maximum  Idle Time  in seconds
smtpPoolMaxWaitTime
Default: 300
Description: Connection pool option - Max Wait Time in seconds
smtpPoolReclaimConnections
Default: 60
Description: Connection pool option - Reclaim Connections Time in seconds

When using Get Email, choose a polling frequency so that the email server does not close the connection between polls (GetMail activity >Delivery Rules). Some email servers will lock the account or not permit log in if there are frequent openings and closings of connections. Read your email providers documentation to ensure that you set the properties correctly for your email server. To enable a connection pool, you must first set smtpNewConnEveryTime to false, and then set the required connection pool properties.
Connection Timeout

Time out after ___ second(s)
when establishing a connection to the endpoint.
Specifies the number of seconds before a timeout occurs between the Integration Appliance attempting to establish a connection to the endpoint and the time it takes for the endpoint to respond to the connection request. For email activities, the amount of time the Integration Appliance attempts to establish a connection to the SMTP or the POP3 server before timing out.
A connection timeout is different from an activity timeout because an activity timeout occurs after the connection to the endpoint has already been established. An activity timeout specifies the amount of time in seconds before a timeout occurs between the activity invoking a request on an endpoint and the time it takes the endpoint to respond.
You set the activity timeout in Retry task of the Get Email activity orSend Email activity.

 

Get Email activity

The Get Email activity is a starter activity. When an orchestration that starts with an Get Email activity is deployed to the Integration Appliance, the Integration Appliance polls the POP3 server for email message or messages for the specified account at the specified interval.
Note: The Get Email activity requires the POP3 server to support the TOP and UIDL commands. While these are optional in the POP3 protocol, most servers will support these.
The polled POP3 server and email account is defined in the email endpoint associated with the Get Email activity.
During run time, the Get Email activity polls a POP3 server for incoming email messages of a particular email account, as shown in the following diagram.
If any email messages are found the following action occurs for each email message: The regular expression defined for the Subject field is checked against the subject of the incoming mail message and the regular expression defined for the From field is checked against the sender email account of the incoming mail message. If both regular expressions match, an orchestration job is created to process the email, and the mail is marked for deletion on POP3 Server. When the process is completed, the email is deleted from the POP3 server. For more information about regular expression matching, see the Configuring the activity procedure.
Note: Two Get Email activities should not poll from the same POP3 server at the same time using the same email account even if the regular expressions specified in the Configure task of the activity are different. If two Get Email activities are attempting to get email using the same email account, when the first Get Email activity process the email from the POP3 server and removes the email from the server, the second Get Email activity keeps retrying to retrieve the email from the POP3 server and the following exception may be thrown:
Protocol exception: com.jscape.inet.pop.PopException: 
Error in TOP 671 0: -ERR The requested message is no 
longer available; it may have been deleted.

Accessing an email message attachment

To access the attachment of a incoming email message, you must add a Read MIME activity in the orchestration after the Get Email activity as shown in the preceding figure. In addition, you must map the two output parameters of the Get Email activity to variables in the orchestration and then map those variables to the input parameters of the Read MIME activity. During run time, the Read MIME activity reads the MIME Header and the body of the message and then breaks up the attachments contained in the body of the message and places the result into the parts XML output parameter. For more information, see Read MIME Activity.

Adding a Get Email activity to the orchestration

1.     Create or open an orchestration. A graphical representation of the orchestration is displayed.
2.     Select the Activities tab and expand the Email folder.
3.     Drag the Get Email activity onto the orchestration.
4.     Select the activity. The Checklist is displayed.

Creating, selecting, or editing an email endpoint

 

1.     Click Pick Endpoint task from the Checklist and choose from one of the following actions:
o    Select an existing endpoint:
a.     Select Browse. The Project Explorer is displayed.
b.    Select an existing endpoint and click OK. Complete theConfiguring the activity steps.
o    Select an existing endpoint and edit the endpoint:
a.     Select Browse. The Project Explorer is displayed.
b.    Select an existing endpoint and click OK.
c.     Click Edit. The Edit Endpoint pane is displayed.
o    Create a new endpoint: Select New. The Create Endpoint pane is displayed.
2.     Create or edit an email endpoint. For more information, see Creating or editing an email endpoint.

Configuring the activity

 

1.     Select the Configure task from the Checklist. The Configure pane is displayed.
2.     Configure all the fields in this pane as described in the following table. In this task, you specify the regular expressions used to match against theSubject and From fields of polled email messages. A regular expression must be specified for both of these fields, even if the regular expression is equal to *, which means that all strings match. In order for a incoming mail to be processed, both the Subject and the From strings of the mail must match their respective regular expressions. In each of the regular expression fields, the following wildcards are supported:
o    * (asterisk) - for zero or more characters
o    ? (question mark) - for zero or one character
Table 1.
Field
Description
Subject matches
Enter a regular expression that matches the subjects of email messages that start an orchestration job to process the email message. In the regular expression,  you can specify a combination of characters and wildcards.
From matches  
Enter a regular expression defines the sender email address of the email messages that start an orchestration job to process the email message. In the regular expression,  you can specify a combination of characters and wildcards.
3.     The following table shows some example regular expressions and the result of matching the regular expressions to sample text.
Table 2.
Regular Expression
Sample Text
Result
*test*
test
matches
*test*
ttttesttt
matches
test
test
matches
test
ttttesttt
does not match, has to exactly match the regular expression string: test
test
est
does not match, has to exactly match the regular expression string: test
?est
test
matches
?est
best
matches
?est
est
matches

Specifying the delivery rules

 

1.     Select the Delivery Rules task from the Checklist. The Delivery Rules pane is displayed.
2.     Specify the time interval to poll the POP3 server for new email messages:
a.     Select a time unit from the menu: seconds, minutes, hours, or days.
b.    Specify the amount of time using one of the following input options:
§  By clicking in the Poll for changes every field and entering a new value.
§  Using the up and down arrows.

Specifying the retry options

 

1.     Select the Retry task from the Checklist. The Retry pane is displayed.
2.     Configure the retry options for connecting to a POP3 server. The following table defines the retry options for a connection to an POP3 server:
3.      
Table 3.
Field
Description
Retry

1) Wait __ second(s) between each retry.
Specifies the number of seconds that the Integration Appliance waits before trying to establish a connection to the POP3 server.
2) Try to connect __ times before failing.
Specifies the retry count - the maximum number of times the Integration Appliance attempts to establish a connection to the POP3 server before issuing an error.
If an orchestration that starts with a Get Email activity is deployed and the Integration Appliance cannot connect to the specified POP3 server, the Integration Appliance logs the connections errors as warnings in the system log until the retry count value is reached. When the retry count is reached, the Integration Appliance logs an error in the system log, resets the connection error count to zero, and continues to attempt to establish a connection to the POP3 server.
For example, you set the retry count to 3. The first, second, and third connection errors appear in the system log as Warnings. The Integration Appliance logs the fourth connection error as an error and resets the connection error count to zero. Therefore, the fifth connection error generates a warning in the system log. The Integration Appliance continues to attempt to establish a connection to the POP3 server.

Mapping the output of the activity

 

1.     Select the Map Outputs task in the Checklist. The output parameters of the activity are displayed in the From Activity pane.
2.     In this task, you map the mailheader (of type XML) and body (of type string) output parameters to variables. You must map the output parameters of the activity in order for the orchestration to be valid. See Creating a map for general instructions on mapping. The mailheader output parameter contains meta information about the email message, for example the email addresses that the message is being sent to and the MIME header of the message itself. The body output parameter contains the body of the email message and associated attachments.
CAUTION:
The order of the attachments and the body in the body output depend on the email client that sent the message and the type of message (plain text or HTML.).
Note: When using a non-English payload, the mailheader, mimeHeader and otherheaders need to be mapped into the orchestration in the getEmailactivity, and mapped from the orchestration back into the sendMail activity.

 

 

Send Email activity

An orchestration that contains the Send Email activity is acting as an email client during run time.
The Send Email activity connects to the SMTP server, and sends a message to the server as shown in the following figure.
The steps for adding and configuring a Send Email activity are described in the following procedures.

Adding a Send Email activity to the orchestration

1.     Create or open an orchestration. A graphical representation of the orchestration is displayed.
2.     Select the Activities tab and expand the Email folder.
3.     Drag the Send Email activity onto the orchestration.
4.     Select the activity. The Checklist is displayed.

Creating, selecting, or editing an email endpoint

1.     Click Pick Endpoint task from the Checklist and choose from one of the following actions:
o    Select an existing endpoint:
a.     Select Browse. The Project Explorer is displayed.
b.    Select an existing endpoint and click OK. Complete the Configuring the activity steps.
o    Select an existing endpoint and edit the endpoint:
a.     Select Browse. The Project Explorer is displayed.
b.    Select an existing endpoint and click OK.
c.     Click Edit. The Edit Endpoint pane is displayed.
o    Create a new endpoint: Select New. The Create Endpoint pane is displayed.
2.     Create or edit an email endpoint. For more information, see Creating or editing an email endpoint.

Configuring the activity

1.     Select the Configure task from the Checklist. The Configure pane is displayed.
2.     Configure all the fields in this pane as described in the following table:
Table 1.
Field
Description
From Address
Specifies the sender address for the email message. You must specify the email address using the standard email format: email@domain.extension. This field is required.
To
Specifies the recipient's addresses for the email message. You must specify the email addresses using the standard email format: email@domain.extension. One or more addresses can be specified. Separate the addresses with commas or semicolons. You must specify at least one address. This field is required.
CC
Specifies the carbon copy's addresses for the email message. You must specify the email addresses using the standard email format: email@domain.extension. One or more addresses can be specified. Separate the addresses with commas or semicolons. This field is optional.
Subject
Specifies the subject of the email message.

Specifying the retry options

1.     Select the Retry task from the Checklist. The Retry pane is displayed.
2.     Configure the retry options for connecting to an SMTP Server. The following table describes the retry options for connecting to an SMTP Server:
Table 2.
Field
Description
Retry

1) Wait ___ second(s) between each retry.
Specifies the number of seconds that the Integration Appliance waits before trying to establish a connection to the SMTP Server.
2) Try to connect ___ times before failing.
Specifies the retry count - the maximum number of times the Integration Appliance attempts to establish a connection to the SMTP Server before issuing an error and stopping the processing of the current orchestration job.
If you deploy an orchestration that contains an Send Email activity and the Integration Appliance cannot connect to the specified SMTP Server, the Integration Appliance logs the connections errors as warnings in the system and orchestration logs until the retry count value is reached. When the retry count is reached, the Integration Appliance logs an error in the system and orchestration logs and the stops processing the current orchestration job.
For example, you set the retry count to 3. The first, second, and third connection errors appear in the system log as warnings. The Integration Appliance logs the fourth connection error as an error and stops processing the current orchestration job.
3.      

Mapping the input of the activity

1.     Select the Map Inputs task in the Checklist. The input parameters of the activity are displayed in the To Activity pane.
2.     In this task, you map variables to the following input parameters of the activity:
o    The body input parameter contains the body of the email message and associated attachments. The body input parameter is of type string. You must map a variable or assign a default value to the body input parameter.
o    The optional mailheader input parameter contains meta information about the email message, for example the email addresses that the message is being sent to and the mimeHeader of the message itself. The mailheader input parameter is optional, you do not have to map a variable or assign default values to the mailheader input parameter.
If the optional mailheader input parameter is not listed in the To Activity pane of the Map Inputs pane, select Map > Show Optional Parameters from the toolbar menu or right-click in the To Activity pane and select the Show Optional Parameters option. If the Map > Show Optional Parameters option is not selectable in the toolbar menu, click on a node in the Map Inputs pane to make this option active.
You can optionally override the settings you specified in the Configure task of the Checklist dynamically during run time by passing in values from variables into the nodes specified in the following table. For example during run time, you can override the setting for the From Addressfield by mapping a variable to the from node of the mailheader input parameter. During run time, the value of the variable is the from address in the sent email message.
Table 3.
Nodes of the mailheader Input Parameter
Description
Overrides what settings in the Configuring task?  
from
Specifies the sender address for the email message. You must specify the email address using the standard email format:email@domain.extension.
The from node of the mailheaderinput parameter overrides the From Address field specified in theConfigure task.
to
Specifies the recipient addresses for the email message. You must specify the email addresses using the standard email format:email@domain.extension. One or more addresses can be specified. Separate the addresses with commas or semicolons.
The to node of the mailheader input parameter overrides the To field specified in the Configure task.
cc
Specifies the carbon copy addresses for the email message. You must specify the email addresses using the standard email format:email@domain.extension. One or more addresses can be specified. Separate the addresses with commas or semicolons.
The cc node of the mailheader input parameter overrides the CC field specified in the Configure task.
subject
Specifies the subject of the email message.
The subject node of the mailheaderinput parameter overrides the Subjectfield specified in the Configure task.
mimeHeader
Specifies the MIME header of the email message.
None.
otherHeaders
Specifies an element that contains a set of MIME headers as name/value pairs not already specified in themimeHeader node. For example the MIME header: Content-Location is not specified in the MIME header, so the following headerItem node could be equal to the following values:otherheaders/headerItem/name is equal to Content-LocationotherHeaders/headerItem/value is equal to the value of the Content-Location MIME header, for example the string: RN-Preamble Multiple MIME headers can be specified, so this is a recurring node.
None.
Note: You can use the Write MIME activity to build the contents of the mimeHeader node of the optional mailheader input parameter. For example, you could add a Write MIME activity to the orchestration before the Send Email activity and have the Write MIME activity populate the contents of the mimeHeader XML variable and then passes the mimeHeader variable to the Send Email activity.
See Creating a map for more information
Note: When using a non-English payload, the mailheader, mimeHeader and otherheaders need to be mapped into the orchestration in thegetEmail activity, and mapped from the orchestration back into the sendMail activity.

Testing an SSL email connection

After creating an endpoint for an email server, you must import the CA certificate for the email server into Studio and then test the SSL connection to the email server.
Complete the following procedure to import the email servers CA certificate and then test the SSL connection to the email server:

Procedure

1.     Open a command window.
2.     Navigate to the email server, and locate the certificate file ca-cert stored in the server.
3.     Copy this file and then navigate to the workstation where Studio is installed.
4.     Using the command window, paste the ca-cert copy in the home directory of Studio: C:\Program Files\IBM\WebSphere Cast Iron Studio x.x.x
5.     Browse to the security directory of Studio: C:\Program Files\IBM\WebSphere Cast Iron Studio x.x.x\security
6.     Run the following command to import the ca-cert file into Studio: ..\jre\bin\keytool.exe -import -v -keystore cacerts -storepass changeit -file ..\castiron_ca_cert.pem -alias alias_name  Where alias_name is the alias of the email servers CA certificate.
7.     When you are prompted for a yes or no, enter 'Y'.
8.     Exit the command window.
9.     Open the endpoint for the email server.
10.  Verify the following login credentials for the email connection: Email server, Port, User, and Password.
11.  Click Test Connection.
12.  If the connection is successful, use this endpoint in Studio orchestrations, then use the Verify tab features to evaluate the orchestration.

Creating or Editing an FTP endpoint

FTP endpoints provide the connection information that Studio and the Integration Appliance use to connect to FTP Servers.
1.     In the Create Endpoint or Edit Endpoint pane, configure the fields as described in the following table.
Note: Changing the configuration properties of an endpoint affects all orchestrations that use that endpoint in the project as the edits are global, not local.
2.     When you had entered the field values, click Test Connection to confirm that you can connect to the FTP Server.
3.     Click OK.
Table 1.
Field Name
Description
Location

Host Name
Specifies the Host Name or IP address for the FTP Server.
Port
Specifies the port number for the specified host name. The default is 21, the standard port for FTP traffic. The default port for SFTP traffic is 22.
Login
Description
Log into the Server as an Anonymous User
This option is only available with the Normal FTP option. Select this option only if the FTP Server allows anonymous logins (where a user account is not required).
Log into the Server with User Name and Password
Select this option to specify a user account to log in into the FTP Server. Enter the user name and password for the account used to connect to the FTP Server.
Security
Description
Normal FTP
Select the Normal FTP option for an unsecured connection.
Secure FTP
Select the Secure FTP option to secure the communication between the Integration Appliance and the FTP Server by sending and receiving the data over SSH. The SSH File Transfer Protocol (SFTP) is a network protocol that provides file transfer over a reliable data stream.
Note: Certificate authentication for SFTP is not supported.
FTPS
Select the FTPS option to secure the communication between the Integration Appliance and the FTP Server using the SSL protocol. The SSL protocol supports mutual authentication between the Integration Appliance and FTP Server using an authenticated and encrypted connection. Choose one of the following authentication modes:
  • Implicit
  • Explicit (SSL) - Starts an FTP session and uses SSL security to authenticate an endpoint and encrypts data before transfer.
  • Explicit (TLS) - Starts an FTP session and uses TLS security to authenticate the endpoint and encrypts data before transfer.
Important: Before you can deploy a project using FTPS, you must upload and register a certificate on the Integration Appliance. For more information about uploading and registering a certificate, see the CLI Command Reference.
Client Certificate Alias Name
When the FTPS server is configured to authenticate a client, select this option and specify a client certificate alias name. By default, when you select the Client Certificate Alias Name option, Studio provides the following name: Factory Supplied Identity
The client certificate alias name that you specify in this field should match the value you specified for the client certificate name using the Cast Iron® command line interface (CLI), when you uploaded or imported the certificate. In the CLI, if you mapped the client certificate name to the default alias name, accept the default name that Studio provides and configure the Connection Timeout for the endpoint.
FTP Mode
Description
If your FTP Server supports Active mode transfers, you can configure an FTP endpoint in Studio to use the Active mode to transfer data to and from an FTP Server and the Integration Appliance. By default, FTP endpoints support passive mode transfers.
Note: Active mode is not supported for SFTP.
Active FTP
Select this option to enable the Active mode. When you enable the Active mode option, you can specify the external IP and port range for incoming connections.  By default, this option is not selected and the FTP endpoint supports passive mode transfers.
External IP
(Optional) Specifies the client IP address from which the FTP Server will respond to connection attempts.
Port Range/Start Port
(Optional) Specifies the lowest port number of the predetermined range assigned to incoming connections. If you enter a start port number, you must also enter the end port number.
Important: This number cannot be less than 1024.
Port Range/End Port
(Optional) Specifies the highest port number of the predetermined range assigned to incoming connections. If you enter an end port number, you must also enter the start port number.
Important: This number cannot be greater than 65535.
Connection Timeout
Description
Time out after ___ second(s) when establishing a connection to the Endpoint.
The number of seconds before a timeout occurs between the Integration Appliance attempting to establish a connection to the endpoint and the time it takes for the endpoint to respond to the connection request. For an FTP activity, the amount of time the Integration Appliance attempts to establish a connection to the FTP Server before timing out. A connection timeout is different from an activity timeout because an activity timeout occurs after the connection to the endpoint has already been established. An activity timeout specifies the amount of time in seconds before a timeout occurs between the activity invoking a request on an endpoint and the time it takes the endpoint to respond.  You set the activity timeout in Retry task of the following FTP activities:
  • FTP Poll Directory activity
  • FTP Put File activity
  • FTP Get File activity
  • FTP Delete File activity
  • FTP List Files activity
  • FTP Rename File activity
Note: For some of the fields in the endpoint, you can define configuration properties to supply the values for these fields.  The
icon is displayed when you click in a field that supports a configuration property and a configuration property of the same type has already been configured for the project.

Configuring the FTP endpoint for the Parse Directory Listing Example

To run the Parse Directory Listing Example in your environment, configure the values of the configuration properties used by the FTP Endpoint to point to your FTP Server. In addition, your FTP Server must produce the directory listing in the same format as expected by the Flat File Schema.

About this task

Complete following steps only if you plan on running the Parse Directory Listing Example:
To only view and learn more about the example, complete the procedure in the Parse Directory Listing Example section.
Edit and test the FTP configuration properties of the FTPParseDirListingExample in Studio: 

Procedure

1.     Open FTPParseDirListingExample. For instructions see steps 1-2 in Parse Directory Listing Example.
2.     From the toolbar menu, select Project > Configuration Properties. The Configuration Properties dialog box is displayed.
3.     Edit the values of the properties to reflect your FTP Server.
4.     In the Project tab, double-click the FTP Endpoint. The FTP Endpoint tab is displayed.
5.     To verify that you entered the correct FTP information, click Test. If Studio connects to your FTP Endpoint, an Information dialog box is displayed with the message that you have successfully connected to the endpoint.
6.     In the Project tab, double-click on the processBids orchestration. The processBids orchestration tab is displayed.

What to do next

Configure the root directory of the FTP Server:
1.     Add the additional directories to your FTP Server. Mirror the directory structure and also provided in the FTPServerDirStructure directory. If you accepted the defaults during the installation of Studio, this directory is located in the following location: C:\Program Files\IBM\WebSphere Cast Iron Studio 3.X\Samples\FTPParseDirListing\FTPServerDirStructure
During run time, the Parse Directory Listing Example expects the root directory of the FTP Server to contain the following directory structure:
\input
\processFailed
\processWidgetRUs
\processAcmeInc
\processNewCompany
2.     Move a copy of the bid*.txt files to the \input directory on your FTP Server. If you accepted the defaults during the installation of Studio, these files provided in the following directory location: C:\Program Files\IBM\WebSphere Cast Iron Studio 3.X\Samples\FTPParseDirListing\FTPServerDirStructure\input
Before running the example, a copy of the following files must be located in the \input directory of the FTP Server.
o    bidAcmeInc.txt
o    bidCrankCo.txt
o    bidWidgetRUs.txt
o    bidBudgetManufacture.txt
o    bidSamAndSons.txt
Determine if your FTP Server generates the file listing in the same format as the Flat File Schema included in this example:
1.     Open FTPParseDirListingExample. For instructions see steps 1-2 in Parse Directory Listing Example.
2.     In the Project tab, double-click the processBids orchestration. The processBids orchestration tab is displayed.
3.     Click the FTP List Files activity labeled List Files Full Dir Listing.
4.     Click Test.
5.     Determine if the format of the directory listing matches the following directory listing:
6.  -rw-r--r--   1 551      551            65 May  3 11:39 bidAcmeInc.txt
7.  -rw-r--r--   1 551      551            43 May  3 11:39 bidBudgetManufacture.txt
8.  -rw-r--r--   1 551      551             0 May  3 11:39 bidCrankCo.txt
9.  -rw-r--r--   1 551      551            73 May  3 11:39 bidSamAndSons.txt
-rw-r--r--   1 551      551            33 May  3 11:39 bidWidgetRUs.txt
If the directory format is different, you can alter the Flat File Schema called parseDirListing.
CAUTION:
Changing the nodes of the Flat File Schema may affect other entities in the orchestration. You may need to update the orchestration to reflect these changes.
For more information, see Flat File Schema Editor Overview.
To open the Flat File Schema used in this example, in the Project tab, double-click on the parseDirListing in the Flat File Schema folder. Copy and paste the output of the Test button of the FTP List Files activity to a file and then open the file in the Test tab of the Flat File Schema Editor. Change the nodes of the Flat File Schema to reflect the directory listing. The size node is used by the "If size less or equal 0" branch of the If..Then activity. Make sure a value is provided for the size node during run time.
Run the FTPParseDirListingExample:
1.     From Studio, publish the FTPParseDirListingExample project. From the Studio toolbar, select File > Publish Project... .
2.     From the Web Management Console (WMC), deploy the FTPParseDirListingExample project. For more information, see the WMC Online help or Step 11: Publish and Deploy the Completed Integration Project in the Developing the BookOrder Project section of the Getting Started Guide.

FTP Get File activity

During run time, the FTP Get File activity connects to an FTP Server and attempts to get a single file at the specified location. You can configure the FTP Get File activity to return the contents of the file into a variable of the orchestration.  In addition, you can configure the FTP Get File activity to return the timestamp of the file returned by the FTP Server into a variable of the orchestration.
The FTP Get File activity differs from the FTP Poll Directory activity in the following ways:
  • The FTP Get File activity does not poll for a file or files in the specified directory. Instead the FTP Get File activity checks for the file a single time and if the file is not found, it throws an error and the orchestration job continues to processing.
  • The FTP Get File activity is not a starter activity, so it cannot be the first activity in an orchestration.
  • The FTP Get File activity does not move or delete files on the FTP server.

Symbolic link

The support for symbolic links by the FTP Get File activity during run time is dependant on the following factors:  
  • The types of symbolic links supported by operating system that hosts the FTP Server.
  • The types of symbolic links supported by the FTP Server itself.
  • The types of symbolic links supported by the FTP Get File activity, as listed in the following table:
Table 1.
Symbolic Links to...
Hard Symbolic Links
Soft Symbolic Links
Notes®
Files
Not Supported
Not Supported
The FTP Get File activity does not interpret symbolic links to files as files and therefore symbolic links to files are not processed by the FTP Get File activity during run time.
Directories
Supported
Supported

To determine the specific symbolic link support for a specific FTP Server on a specific operating system, see your operating system and FTP Server documentation.

Adding an FTP Get File activity in the orchestration

1.     Create or open an orchestration. A graphical representation of the orchestration is displayed.
2.     Select the Activities tab and expand the FTP folder.
3.     Drag the Get File activity onto the orchestration.
4.     Select the activity. The Checklist is displayed.

Creating, selecting, or editing an FTP endpoint

1.     Click Pick Endpoint task from the Checklist and choose from one of the following actions:
o    Select an existing endpoint:
a.     Select Browse. The Project Explorer is displayed.
Attention: Specifying a new FTP Endpoint with a different directory structure than the original FTP Endpoint can cause the orchestration job to fail during run time. You must either specify a new FTP Server that matches the directory structure of the originally specified FTP Server or change the configured directory of the In Directory field by clicking Browse as described in the Configuring the activity procedure.
b.    Select an existing endpoint and click OK. Skip to the "Configure the activity" procedure.
o    Select an existing endpoint and edit the endpoint:
a.     Select Browse. The Project Explorer is displayed.
b.    Select an existing endpoint and click OK.
Attention: Specifying a new FTP Endpoint with a different directory structure than the original FTP Endpoint can cause the orchestration job to fail during run time. You must either specify a new FTP Server that matches the directory structure of the originally specified FTP Server or change the configured directory of the In Directory field by clicking Browse as described in the "Configure the activity" procedure.
c.     Click Edit. The Edit Endpoint pane is displayed.
o    Create a new endpoint: Select New. The Create Endpoint pane is displayed.
2.     Create or edit an FTP endpoint: Creating or Editing an FTP endpoint

Specifying the delivery rules

1.     Select the Delivery Rules task from the Checklist. The Delivery Rules pane is displayed. If security is not enabled for the FTP endpoint, theTransfer as Text (ASCII) and Transfer as Binary (BINARY) options are enabled. If security is enabled for the FTP endpoint, the file transfer type is always binary.
2.     Select the type of file transfer between the Integration Appliance and the FTP Server from one of the following options:
o    Transfer as Text (ASCII) - Only seven bits of each character in the file is transferred by the Integration Appliance to the FTP Server. This option is used for transferring ASCII files such as HTML and text files.
CAUTION:
Using this option with binary files can result in a loss of data.
o    Transfer as Binary (BINARY) - All eight bits of each byte in the file is transferred by the Integration Appliance to the FTP Server. This option is used for transferring binary files.
Note: Setting the transfer mode in the Delivery Rules task is equivalent to setting the transfer mode via a command line session with an FTP Server using the following commands:
o    ascii
o    binary

Configuring the activity

1.     Select the Configure task from the Checklist. The Configure pane is displayed.
2.     Configure all the fields in this pane as described in the following table:
Table 2.
Field
Description
File Named
This field is not used for this activity. You specify the name of the output file using the filename input parameter of the Map Input task.
From Directory
Specifies the directory on the FTP server where the Integration Appliance places the file generated in this activity. You can specify a directory using one of the following options:
o    Directly enter directory path by clicking in the field and typing in one of the following directory paths:
§  Relative directory path, for example: /output.  (Assumes that FTP home has been configured for the user account that connects to the FTP Server. See "Note" for more information.)
§  Complete directory path, for example on a UNIX machine: /home/user/output.
o    Click Browse... to populate the drown-down list of available directories. Select the appropriate directory from the drop-down list.
Note: UNIX: If you specify a relative directory path when connecting to an FTP Server on a UNIX machine, verify that the FTP home directory has been correctly specified in the /etc/password file for the user account connecting to the FTP Server.
Of Type
Specifies how to read in the contents of the file - either as binary data or encoded text. If the Text option is selected, set the encoding type using one of the following options:
o    From the encoded with drop-down list, select one of the default encoding types.  
o    Enter your encoding type directly by clicking in the encoded with field and typing in your encoding type.

Attention: You must specify the Transfer as Text (ASCII) option for FTP activities when retrieving text files and placing text files on an FTP Server for Endpoints that manipulate text data while transferring data from/to the FTP Endpoint in ASCII mode. For example, mainframe and DOS FTP Endpoints manipulate ASCII data when passing data in ASCII mode.
For example, if your orchestration retrieves ASCII files using the FTP Poll Directory activity and places ASCII files using the FTP Put File activity to a mainframe FTP Server, you must specify the options in the following tasks in Studio:
o    In the Configure task of an FTP Poll Directory activity, for the Of Type field select the Text option.
o    In the Delivery Rules task of an FTP Poll Directory activity, for the File Transfer Type field select the Transfer as Text (ASCII) option.
o    In the Configure task of an FTP Put File activity, for the Of Type field select the Text option.
o    In the Delivery Rules task of an FTP Put File activity, for the File Transfer Type field select the Transfer as Text (ASCII) option.

Specifying the retry options

1.     Select the Retry task from the Checklist. The Retry pane is displayed.
2.     Configure the retry options for connecting to an FTP Server. The following table defines the retry options for a connection to an FTP Server:
Table 3.
Field
Description
Retry

1) Wait ___ second(s) between each retry.
The number of seconds that the Integration Appliance waits before trying to establish a connection to the FTP Server.
2) Try to connect ___ times before failing.
Specifies the retry count - the maximum number of times the Integration Appliance attempts to establish a connection to the FTP Server before issuing an error and stopping the processing of the current orchestration job.
If you deploy an orchestration that contains an FTP Get File activity and the Integration Appliance cannot connect to the specified FTP Server, the Integration Appliance logs the connections errors as warnings in the system and orchestration logs until the retry count value is reached. When the retry count is reached, the Integration Appliance logs an error in the system and orchestration logs and the stops processing the current orchestration job.
For example, you set the retry count to 3. The first, second, and third connection errors appear in the system log as warnings. The Integration Appliance logs the fourth connection error as an error and stops processing the current orchestration job.

Mapping the input into the activity

1.     Select the Map Inputs task in the Checklist. The input parameters of the activity are displayed in the To Activity pane.
2.     The filename parameter is the only parameter you are required to provide an value in the activity. All other parameters are optional. The filename parameter specifies the name of the file to get from the FTP Server. You provide a value for the filename parameter by either by creating a link from the filename input parameter to a variable or by defining a default value for the filename input parameter.
If the optional input parameter listed in the following table are not displayed in the To Activity pane of the Map Inputs pane, select Map > Show Optional Parameters from the toolbar menu or right-click in the To Activity pane and select the Show Optional Parameters option. If the Map > Show Optional Parameters option is not selectable in the toolbar menu, click on a node in the Map Inputs pane to make this option active.
You can optionally override the settings you specified in the Configure and Pick Endpoint task of the Checklist dynamically during run time, using the input parameters defined in the following table.
For example, the directory on the FTP Server where the Integration Appliance gets the file, could be set in the Configure task to the directory called input. During run time, the directory name: inputXML could be passed into the activity using the directory input parameter. The directory name specified dynamically during run time overrides the original setting specified in the Configure pane. In this example, the Integration Appliance attempts to get the file from the inputXML directory.
Table 4.
Input Parameter Name/Node
Description
Overrides the Setting in Task?
directory
Specifies the directory on the FTP server where the Integration Appliance places the file generated in this activity.
The directory input parameter overrides the From Directory field of the Configure task.
encoding
Specifies how the outgoing data is written out to the file:
  • If no encoding is required, specify the string:binary .
  • If encoding is required, specify the encoding type that should be used to encode the outgoing data, for example:UTF-8, US-ASCII,ISO_8859-1, EBCDIC-US, orSHIFT-JIS.
The encoding input parameter overrides the encoding specified in  the Of Type field of the Configure task but if theBinary option is selected in the Of Type field of the Configure task, the encoding specified by the encoding input parameter is ignored.
connection/timeout
Specifies the connection timeout — the number of seconds before a timeout occurs between the Integration Appliance attempting to establish a connection to the endpoint and the time it takes for the endpoint to respond to the connection request. For theFTP Get Fileactivity, the amount of time the Integration Appliance attempts to establish a connection to the FTP Server before timing out.  
The timeout node of the connection input parameter overrides theConnection Timeout -Time out after ___ second(s) when establishing a connection to the Endpointfield of the FTP endpoint.  
connection/host
Specifies the Host Name or IP address for the FTP server.
The host node of the connection input parameter overrides the Host Name field of the FTP endpoint.
connection/port
Specifies the port number for the specified host name. The standard port for FTP traffic is 21. The default port for SFTP traffic is 22.
The port node of the connection input parameter overrides the Port field of the FTP endpoint.
connection/username
Specify a user name for the account used to connect to the FTP Server.
The username node of the connection input parameter overrides the User Name field of the FTP endpoint.
connection/password
Specify a password for the account used to connect to the FTP Server.
The password node of the connection input parameter overrides the Password field of the FTP endpoint.

Mapping the output of the activity

1.     Select the Map Outputs task in the Checklist. The output parameters of the activity are displayed in the From Activity pane as described in the following table:
Table 5.
Output Parameter Name
Description
data
Contains the contents of the file.
timestamp
Contains the timestamp for the file returned from the FTP Server, typically the creation date or last modified date of the file.  
2.     Map the desired output parameters to variables.













































No comments: