Sign in
< Back to User Guide Top

Creating and Defining FTP Adapters

Creating FTP Adapters

Create an FTP Adapter to coordinate communication between Clarify and an FTP server.

  1. Select File | New | FTP Adapter from the main menu. The New FTP Adapter window appears.
    Note: If you select the Package in which the File Adapter should reside before creating it, some parameters are automatically populated in the New Data Source window.
  2. Select a type (Get, MGet, Put, or MPut)
  3. Provide the Source folder, Package, and Name.
  4. Click Finish. An editor appears.

Defining FTP Get Adapters

Determine how Clarify connects to an FTP server and the file to download.

The following steps take place in the FTP Get Adapter editor, which has these sections: Template, Parameters, Connection, Get, and Custom Commands.
  1. (Optional) To use a template to create this adapter, under the Template section's Template FTP Adapter field, select an existing Adapter. Use of an Adapter Template is tied directly to the number and types of parameters the Adapter uses. For more information, see Using Adapter Templates.
  2. (Optional) If you need to add a parameter, under the Parameters section, click the Add button to add a row, then define the parameter. By default, an FTP Get Adapter has one parameter: storageNodes. The storageNodes parameter represents the data in the file.
  3. In the Host field, specify the URL or IP address of the FTP Server. The URL or IP address should be supplied to you by your Trading Partner or VAN service.
    • Example IP Address: 123.456.789.0
    • Example URL: ftp.myco.com
  4. In the Port field, specify the communications port. Commonly, the port is 21.
  5. In the Username field, specify the user name given to you by your Trading Partner for authenticating your permission to access the FTP server.
  6. In the Password field, specify the password given to you to further authenticate permission to the FTP server.
  7. In the Connection Timeout field, instruct the adapter how long it should wait for a connection response from the FTP server before it terminates the session. A "connection response" is the FTP server's response to a connection request. Network failures or FTP server downtime are common explanations for unresponsive connection requests.
  8. In the Inactivity Timeout field, instruct the adapter how long it should wait for a command response from the FTP server before terminating the session. A "command response" is the FTP server's response to an FTP command issued by Clarify. For example, the FTP Get Adapter will issue a "get" command to the server in order to download the file. If the response to the "get" command exceeds the length of time specified, Clarify will terminate the communication session.
  9. (Optional) If you need to disable remote host verification, click Disable remote host verification.
  10. In the Connection Type field, indicate the mode of FTP communication.
    • FTP - Plain FTP
    • FTPS - FTP over implicit TLS/SSL
    • FTPES - FTP over explicit TLS/SSL
  11. Under the Get section, in the Remote Server Path field, specify the path to the folder by:
    • Typing a specific "<directory name>" ( "invoices" for example).
    • Clicking the Global Variable button to select a Global Variable. The value of the Global Variable will be substituted when the Adapter executes.
    • Clicking the Substitution Variable button to create or select a Substitution Variable. The value will be generated by the Adapter (if appropriate) or supplied by the Business Process.
  12. In the Remote Server File field, specify the file name by:
    • Typing a specific file name ( "invoice.edi", or "order.xml" for example).
    • Clicking the Global Variable button to select a Global Variable. The value of the Global Variable will be substituted when the Adapter executes.
    • Clicking the Substitution Variable button to create or select a Substitution Variable. The value will be generated by the Adapter (if appropriate) or supplied by the Business Process.
  13. (Optional) To configure communication behavior, choose any of the following options:
    • Binary: treat the data in the file as binary. Encrypted files (for security purposes), digital photos, and executables are examples of files for which you need binary data transfer.
    • Passive: Allows the Studio to initiate both connections to the server (recommended). This prevents firewall issues with incoming server communication.
    • Disable Persistent Storage: By default, downloaded files are saved within Clarify. By checking this option, you can disable the automatic saving of downloaded files.
    • Delete file from server: When checked, the FTP Adapter will download the file and then delete it from the FTP server. If the file is deleted, subsequent connections to the FTP server will not pick it up.
  14. In the Delete Fail Action field, provide instruction to the calling Business Process about how it should treat an FTP Adapter failure. In some cases FTP Adapter failures are expected and can be safely ignored. For example, sometimes an FTP Server will respond with a 500-level error when no files exist in the target folder. Most businesses do not consider this a "true" error condition, and most times want to ignore this "false-positive".
  15. In the Local Archive Directory URL field, specify a back-up archive directory for downloaded files.
  16. In the Archive Collision Action field, instruct the Adapter what to do when it detects a filename collision between a downloaded file and a file already in the Local Archive Directory.
    • Overwrite: the contents of the file in the Archive Directory will be overwritten with the contents of the downloaded file.
    • Append : the contents of the file in the Archive Directory will be appended with the contents of the downloaded file.
    • Generate Unique Name : a unique filename will be generated and the contents of the downloaded file will be written to the Archive Directory. The unique filename is a combination of the file name that was downloaded plus a 32 character hexadecimal string. For example, if the downloaded file name is "invoices.x12", the generated unique filename will look something like "invoices.xml_1a3bc3240da983a3487aefcb32159eac245", where the hexadecimal suffix guarantees uniqueness.
  17. (Optional) To execute custom FTP commands before and after the "get" operation, specify Custom Commands . Click the Enabled button to enable custom commands.
    • Before transfer: Use the green Add button to enter commands that will execute before the "get" command. Use the red Remove button to remove commands.
    • After transfer: Use the green Add button to enter commands that will execute after the "get" command. Use the red Remove button to remove commands.
    • Error Fails Business Process: When enabled, this option instructs the FTP Adapter to fail the communication session when failures in the custom commands occur.

Defining FTP MGet Adapters

Determine the methods to which Clarify connects with an FTP server and downloads files.

The following steps take place in the FTP MGet Adapter editor, which has these sections: Template, Parameters, Connection, MGet, and Custom Commands.

  1. (Optional) To use a template to create this adapter, under the Template section's Template FTP Adapter field, select an existing Adapter. Use of an Adapter Template is tied directly to the number and types of parameters the Adapter uses. For more information, see Using Adapter Templates..
  2. (Optional) If you need to add a parameter, in the Parameters section, click the Add button to add a row, then define the parameter. By default, an FTP MGet Adapter has two parameters: storageNodes, which represents the data in the files, and filenames, which is an array of the filenames retrieved.
  3. In theHost field, specify the URL or IP address of the FTP Server. The URL or IP address should be supplied to you by your Trading Partner or VAN service.
    • Example IP Address: 123.456.789.0
    • Example URL: ftp.myco.com
  4. In the Port field, specify the communications port. Commonly, the port is 21.
  5. In the Username field, specify the user name given to you by your Trading Partner for authenticating your permission to access the FTP server.
  6. In the Password field, specify the password given to you to further authenticate permission to the FTP server.
  7. In the Connection Timeout field, instruct the adapter how long it should wait for a connection response from the FTP server before it terminates the session. A "connection response" is the FTP server's response to a connection request. Network failures or FTP server downtime are common explanations for unresponsive connection requests.
  8. In the Inactivity Timeout field, instruct the adapter how long it should wait for a command response from the FTP server before terminating the session. A "command response" is the FTP server's response to an FTP command issued by Clarify. For example, the FTP MGet Adapter will issue a "get" command to the server in order to download the files. If the response to the "mget" command exceeds the length of time specified, Clarify will terminate the communication session.
  9. (Optional) If you need to disable remote host verification, click Disable remote host verification.
  10. In the Connection Type field, indicate the mode of FTP communication.
    • FTP - Plain FTP
    • FTPS - FTP over implicit TLS/SSL
    • FTPES - FTP over explicit TLS/SSL
  11. Under the MGet section, in the Remote Server Path field, specify the path to the folder by:
    • Typing a specific directory( "/" or "/myco/invoices" for example).
    • Clicking the Global Variable button to select a Global Variable. The value of the Global Variable will be substituted when the Adapter executes.
    • Clicking the Substitution Variable button to create or select a Substitution Variable. The value will be generated by the Adapter (if appropriate) or supplied by the Business Process.
  12. In the Remote Server File Pattern field, specify the file name by:
    • Typing a specific file name ( "invoice.edi", "order.xml" for example).
    • Clicking the Global Variable button to select a Global Variable. The value of the Global Variable will be substituted when the Adapter executes.
    • Clicking the Substitution Variable button to create or select a Substitution Variable. The value will be generated by the Adapter (if appropriate) or supplied by the Business Process.
  13. (Optional) To configure communication behavior, choose any of the following options:
    • Binary: treat the data in the file as binary. Encrypted files (for security purposes), digital photos, and executables are examples of files for which you need binary data transfer.
    • Passive: Allows the Studio to initiate both connections to the server (recommended). This prevents firewall issues with incoming server communication.
    • Disable Persistent Storage: By default, downloaded files are saved within Clarify. By checking this option, you can disable the automatic saving of downloaded files.
    • Delete file from server: When checked, the FTP Adapter will download the file and then delete it from the FTP server. If the file is deleted, subsequent connections to the FTP server will not pick it up.
  14. In the Delete Fail Action field, provide instruction to the calling Business Process about how it should treat an FTP Adapter failure. In some cases, FTP Adapter failures are expected and can be safely ignored. For example, sometimes an FTP Server will respond with a 500-level error when no files exist in the target folder. Most businesses do not consider this a "true" error condition, and most times want to ignore this "false-positive".
  15. In the Local Archive Directory URL field, specify a back-up archive directory for downloaded files.
  16. In the Archive Collision Action field, instruct the Adapter what to do when it detects a filename collision between a downloaded file and a file already in the Local Archive Directory.
    • Overwrite: the contents of the file in the Archive Directory will be overwritten with the contents of the downloaded file.
    • Append: the contents of the file in the Archive Directory will be appended with the contents of the downloaded file.
    • Generate Unique Name: a unique filename will be generated and the contents of the downloaded file will be written to the Archive Directory. The unique filename is a combination of the file name that was downloaded plus a 32 character hexadecimal string. For example, if the downloaded file name is "invoices.x12", the generated unique filename will look something like "invoices.xml_1a3bc3240da983a3487aefcb32159eac245", where the hexadecimal suffix guarantees uniqueness.
  17. (Optional) To execute custom FTP commands before and after the "mget" operation, specify Custom Commands . Click the Enabled button to enable custom commands.
    • Before transfer: Click the Add button to enter commands that will execute before the "get" command. Use the red Remove button to remove commands.
    • After transfer: Click the Add button to enter commands that will execute after the "get" command. Use the red Remove button to remove commands.
    • Error Fails Business Process: When enabled, this option instructs the FTP Adapter to fail the communication session when failures in the custom commands occur.

Defining FTP MPut Adapters

Determine the method to which Clarify connects with and places one or more files onto an FTP server.

The following steps take place in the FTP MPut Adapter editor, which has these sections: Template, Parameters, Connection, MPut and Custom Commands.
  1. (Optional) To use a template to create this adapter, under the Template section's Template FTP Adapter field, select an existing Adapter. Use of an Adapter Template is tied directly to the number and types of parameters the Adapter uses. For more information, see Using Adapter Templates.
  2. (Optional) If you need to add a parameter, under the Parameters section, click the Add button to add a row, then define the parameter. By default, an FTP MPut Adapter has two parameters: storageNodes, which represents the data in the files, and filenames, which is an array of the filenames to be uploaded.
  3. In the Host field, specify the URL or IP address of the FTP Server. The URL or IP address should be supplied to you by your Trading Partner or VAN service.
    • Example IP Address: 123.456.789.0
    • Example URL: ftp.myco.com
  4. In the Port field, specify the communications port. Commonly, the port is 21.
  5. In the Username field, specify the user name given to you by your Trading Partner for authenticating your permission to access the FTP server.
  6. In the Password field, specify the password given to you to further authenticate permission to the FTP server.
  7. In the Connection Timeout field, instruct the adapter how long it should wait for a connection response from the FTP server before it terminates the session. A "connection response" is the FTP server's response to a connection request. Network failures or FTP server downtime are common explanations for unresponsive connection requests.
  8. In the Inactivity Timeout field, instruct the adapter how long it should wait for a command response from the FTP server before terminating the session. A "command response" is the FTP server's response to an FTP command issued by Clarify. For example, the FTP MPut Adapter will issue a "mput" command to the server in order to upload the files. If the response to the "mput" command exceeds the length of time specified, Clarify will terminate the communication session.
  9. (Optional) If you need to disable remote host verification, click Disable remote host verification.
  10. In the Connection Type field, indicate the mode of FTP communication.
    • FTP - Plain FTP
    • FTPS - FTP over implicit TLS/SSL
    • FTPES - FTP over explicit TLS/SSL
  11. Under the MPut section, in the Remote Server Path field, specify the path to the folder by:
    • Typing a specific directory( "/" - to indicate the root path of the FTP server - or "/myco/invoices" for example).
    • Clicking the Global Variable button to select a Global Variable. The value of the Global Variable will be substituted when the Adapter executes.
    • Clicking the Substitution Variable button to create or select a Substitution Variable. The value will be generated by the Adapter (if appropriate) or supplied by the Business Process.
  12. In the Remote Server File Pattern field, specify the file name by:
    • Typing a specific file name ( "invoice.edi", "order.xml" for example).
    • Clicking the Global Variable button to select a Global Variable. The value of the Global Variable will be substituted when the Adapter executes.
    • Clicking the Substitution Variable button to create or select a Substitution Variable. The value will be generated by the Adapter (if appropriate) or supplied by the Business Process.
  13. (Optional) To configure communication behavior, choose any of the following options:
    • Binary: treat the data in the file as binary. Encrypted files (for security purposes), digital photos, and executables are examples of files for which you need binary data transfer.
    • Passive: Allows the Studio to initiate both connections to the server (recommended). This prevents firewall issues with incoming server communication.
    • Append: If a file with the same name as the file you are attempting to upload already exists on the FTP server, you can instruct the Adapter to append the contents of the uploading file to the existing file.
  14. (Optional) To execute custom FTP commands before and after the "mput" operation, specify Custom Commands. Click the Enabled button to enable custom commands.
    • Before transfer: Click the Add button to enter commands that will execute before the "mput" command. Use the red Remove button to remove commands.
    • After transfer: Click the Add button to enter commands that will execute after the "mput" command. Use the red Remove button to remove commands.
    • Error Fails Business Process: When enabled, this option instructs the FTP Adapter to fail the communication session when failures in the custom commands occur.

Defining FTP Put Adapters

Determine the method to which Clarify connects with and places a file onto an FTP server.

The following steps take place in the FTP Put Adapter editor, which has five sections: Template, Parameters, Connection, Put, and Custom Commands.
  1. (Optional) To use a template to create this adapter, in the Template section's Template FTP Adapter field, select an existing Adapter. Use of an Adapter Template is tied directly to the number and types of parameters the Adapter uses. For more information, see Using Adapter Templates 
  2. (Optional) If you need to add a parameter, in the Parameters section, click the Add button to add a row, then define the parameter. By default, an FTP Get Adapter has one parameter: storageNodes. The storageNodes parameter represents the data in the file.
  3. In the Host field, specify the URL or IP address of the FTP Server. The URL or IP address should be supplied to you by your Trading Partner or VAN service.
    • Example IP Address: 123.456.789.0
    • Example URL: ftp.myco.com
  4. In the Port field, specify the communications port. Commonly, the port is 21.
  5. In the Username field, specify the user name given to you by your Trading Partner for authenticating your permission to access the FTP server.
  6. In the Password field, specify the password given to you to further authenticate permission to the FTP server.
  7. In the Connection Timeout field, instruct the adapter how long it should wait for a connection response from the FTP server before it terminates the session. A "connection response" is the FTP server's response to a connection request. Network failures or FTP server downtime are common explanations for unresponsive connection requests.
  8. In the Inactivity Timeout field, instruct the adapter how long it should wait for a command response from the FTP server before terminating the session. A "command response" is the FTP server's response to an FTP command issued by Clarify. For example, the FTP Put Adapter will issue a "put" command to the server in order to upload the file. If the response to the "put" command exceeds the length of time specified, Clarify will terminate the communication session.
  9. (Optional) If you need to disable remote host verification, click Disable remote host verification.
  10. In the Connection Type field, indicate the mode of FTP communication.
    • FTP - Plain FTP
    • FTPS - FTP over implicit TLS/SSL
    • FTPES - FTP over explicit TLS/SSL
  11. Under the Put section, in the Remote Server Path field, specify the path to the folder by:
    • Typing a specific directory ( "/" - to indicate the root path of the FTP server - or "/myco/invoices" for example).
    • Clicking the Global Variable button to select a Global Variable. The value of the Global Variable will be substituted when the Adapter executes.
    • Clicking the Substitution Variable button to create or select a Substitution Variable. The value will be generated by the Adapter (if appropriate) or supplied by the Business Process.
  12. In the Remote Server File field, specify the file name by:
    • Typing a specific file name ( "invoice.edi", "order.xml" for example).
    • Clicking the Global Variable button to select a Global Variable. The value of the Global Variable will be substituted when the Adapter executes.
    • Clicking the Substitution Variable button to create or select a Substitution Variable. The value will be generated by the Adapter (if appropriate) or supplied by the Business Process.
  13. (Optional) To configure communication behavior, choose any of the following options:
    • Binary: treat the data in the file as binary. Encrypted files (for security purposes), digital photos, and executables are examples of files for which you need binary data transfer.
    • Passive: Allows the Studio to initiate both connections to the server (recommended). This prevents firewall issues with incoming server communication.
    • Append: If a file with the same name as the file you are attempting to upload already exists on the FTP server, you can instruct the Adapter to append the contents of the uploading file to the existing file.
  14. (Optional) To execute custom FTP commands before and after the "put" operation, specify Custom Commands. Click the Enabled button to enable custom commands.
    • Before transfer: Use the green Add button to enter commands that will execute before the "put" command. Use the red Remove button to remove commands.
    • After transfer: Use the green Add button to enter commands that will execute after the "put" command. Use the red Remove button to remove commands.
    • Error Fails Business Process: When enabled, this option instructs the FTP Adapter to fail the communication session when failures in the custom commands occur.

Related articles

Comments

0 comments

Please sign in to leave a comment.