SecureTransport Version 5.3.0 3 April 2019 Developer's Guide
Copyright © 2015 Axway
All rights reserved.
This documentation describes the following Axway software:
Axway SecureTransport 5.3.0
No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of the copyright owner, Axway.
This document, provided for informational purposes only, may be subject to significant modification. The descriptions and information in this document may not necessarily accurately represent or reflect the current or planned functions of this product. Axway may change this publication, the product described herein, or both. These changes will be incorporated in new versions of this document. Axway does not warrant that this document is error free.
Axway recognizes the rights of the holders of all trademarks used in its publications.
The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to these sites are provided for your convenience only. Axway does not control, endorse or guarantee content found in such sites. Axway is not responsible for any content, associated links, resources or services associated with a third-party site.
Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content. Contents
Preface 8 Who should read this document 8 Related documentation 8 Get more help 9 Training 10
Accessibility 11 Documentation accessibility 11 Keyboard-only navigation 11 Screen reader support 11 Support for high contrast and accessible use of colors 11
1 Overview 12
2 Customizing SecureTransport 13 About customization 13 Transaction Manager 14 When to customize 14 How rules work 15 Conditions 15 Actions 15 Precedence 16 Using NextPrecedence 16 SecureTransport built-in rules packages 16 Custom rules 18 Using built-in agents 21 NextPrecedence 21 Continue 23 SetExitValue 24 SecureTransport Software Development Kit 25 SecureTransport APIs 25 Sample agents and applications 26
3 Developing external agents 27 External agent overview 27 Developing and triggering external agents 27 Calling interface 28 Running external agents 29 Chaining external agents 30
Axway SecureTransport 5.3.0 Developer's Guide 3 Installing external agents 31 External agent examples 32 Mail notification on file receipt 32 Permissions 33
4 Developing in-process agents 34 Developing in-process agents overview 34 Creating in-process agents 35 Agent creation at a glance 35 In-process agent interface 36 Installing in-process agents 37 In-process agent examples 38 Installing the examples 38 Mail notification on file receipt 39 Denying permission to upload specific file types 41 Deleting a file after it is transferred to a destination 42 About the Transaction Manager API 43 BaseAgent class 43 Events class 45 Logging 46
5 Using the application framework 47 About the application framework 47 Using the application framework or custom rules 48 Key terms 49 Application framework classes and interfaces 50 Pluggable UI overview 54 Custom JSP files 54 Implementing data handlers 57 Creating custom applications 62 Defining application settings 63 Defining subscription settings 65 Defining application agents 66 ApplicationRuntime interface 67 Using ApplicationManager 69 Custom attributes 71 Post-transfer actions 72 Certificate Manager 73 CertificateReference 74 CertificateDetails 74 CertificateManager 75 Working with AccountManager 76 Working with transfer sites 78 Working with template accounts 80
Axway SecureTransport 5.3.0 Developer's Guide 4 Working with business units 81 Example 81 Working with data transformations 82 Data transformation overview 82 Developing data transformation modules 83 Installing transformation modules 88 Transformation example 88 Working with ConfigurationManager 88 Working with InvocationManager 91 Utility script: option_value_change 92 ChangeConfigurationOption.java 93 DefaultResult.java 97 OptionValueChangeInvocableTask.java 99 Working with NavigationManager 101 Working with ServiceCheck 104 Working with ClusteredManager 105
6 Working with event types 106 Authentication and session management events 106 Sessions 107 Certificate Verification event 108 User Configuration event 110 Password Authentication event 114 Login event 116 Logout event 116 SessionEnd event 117 File transfer authorization and audit events 117 Incoming Start event 118 Incoming End event 119 Incoming Error event 120 Incoming Abort event 120 Outgoing Start event 121 Outgoing End event 122 Outgoing Error event 122 Outgoing Abort event 123 File transfer upload and download events 123 FTP Cmd - STOR event 124 FTP Cmd - RETR event 125 FTP Cmd - REST event 126 FTP Cmd - MDTM event 126 FTP Cmd - SIZE event 127 FTP Cmd - RTCK event 128 File and directory management events 129 FTP Cmd - LIST event 130
Axway SecureTransport 5.3.0 Developer's Guide 5 FTP Cmd - NLST event 132 FTP Cmd - CWD event 133 FTP Cmd - DELE event 134 FTP Cmd - MKD event 135 FTP Cmd - PWD event 135 FTP Cmd - RMD event 136 FTP Cmd - RNFR event 136 FTP Cmd - RNTO event 137 FTP Cmd - CHMOD event 138 FTP Cmd - MIRR event 139 Server extension events 139 HTTP Cmd - POST event 139 FTP Cmd - SITE event 140 Application framework events 140 Application - Init event 140 Application - Schedule event 141 Application - Incoming event 142 Server-initiated transfer events 142 Server Transfer - Pull event 143 Server Transfer - Push event 143 Schedule event 144 Environment variables 144 Exit codes 145 Transformation event 145 Environment variables 145 Exit codes 145 Password Change event 146 FTP Cmd - CHPWD event 146 Arguments 146 Exit codes 146 PeSIT transfer state coordination events 147 PeSIT Pause event 147 PeSIT Resume event 148 PeSIT SaveMap event 148 PeSIT GetMap event 148 PeSIT ClearMap event 149 PeSIT Ack event 149 Mailbox folder event 149 PMfolderSummary event 150 Environment variable 150 Exit codes 150 Output stream 150 Address book events 150 AddressBook - CreateContact event 151
Axway SecureTransport 5.3.0 Developer's Guide 6 AddressBook - DeleteContact event 151 AddressBook - RetrieveContact event 152 AddressBook – UpdateContact event 153
7 Using environment variables 155 Predefined environment variables 155 Common environment variables 155 Session environment variables 156 Application framework object environment variables 159 Additional environment variables 168 LDAP session state variables 173 Adding custom environment variables 174 Displaying custom environment variables 175
8 File services interface 177 File services interface introduction 177 Registering a file services interface protocol 177 Example 179 Enabling PeSIT message parameters 180 Standard file services interface connectors 180 FileServicesInterfaceScriptBasedConnector 181 FileServicesInterfaceFileBasedConnector 182 Implementing a file services interface connector 184
9 REST API 185 REST API overview 185 REST API examples 186 Create an account 186 Push a file 209 Custom HTML template 211 Java file transfer library 218
Appendix A: Agent execution order 224 Client-initiated transfers 224 Server-initiated transfers 225
Appendix B: Developing condition functions 226 Condition functions overview 226 Condition functions 226 File content search example 226 Installing condition functions 227
Axway SecureTransport 5.3.0 Developer's Guide 7 Preface
The SecureTransport Developer's Guide describes the components and tasks associated with customizing the Axway SecureTransport Server. It provides background, conceptual, and procedural information for creating and modifying rules, including creating agents. Before implementing the tasks described in this manual, make sure that SecureTransport is installed as described in the SecureTransport Installation Guide.
Who should read this document This guide is intended for developers who create customizations for SecureTransport. Developers can use a scripting language such as Perl or Python to create external agents or Java to create in- process agents when customizing SecureTransport. Some topics cover information dealing with system administration connected with customization.
Related documentation SecureTransport provides the following documentation:
l SecureTransport Installation Guide – This guide explains how to install, upgrade, and uninstall SecureTransport Server on UNIX-based platforms, Microsoft Windows, and Axway Appliances.
l SecureTransport Getting Started Guide – This guide explains the initial setup and configuration of SecureTransport using the SecureTransport Administrator setup interface.
l SecureTransport Administrator's Guide – This guide describes how to use the SecureTransport Administration Tool to configure and administer your SecureTransport Server. The content of this guide is also available in the Administration Tool online help.
l SecureTransport Web Client User Guide – This guide describes how to use the SecureTransport Browser Client and Web Access Plus to transfer files between your local machine and your SecureTransport Server. The Web Access Plus content of this guide is also available in the Web Access Plus online help.
l SecureTransport Release Notes – This document contains information about new features and enhancements, late-breaking information that could not be included in one of the other documents, and a list of known and fixed issues.
l SecureTransport Developer's Guide – (This document) This guide explains how to use rules, rule packages, and agents to customize SecureTransport. Additional information includes an explanation of how to use the application framework.
l SecureTransport Capacity Planning Guide – This guide provides information useful when planning your production environment for SecureTransport.
Axway SecureTransport 5.3.0 Developer's Guide 8 Preface
l SecureTransport Security Guide - This guide provides security information necessary for the secure operation of the SecureTransport product.
l Axway Appliance Quick Start – This document provides instructions for unpacking, mounting, connecting, and powering up an appliance, provides instructions for installing and deploying an Axway Appliance, plus technical specifications and references to safety, regulatory, and recycling information.
l Axway Email Plug-ins Installation Guide – This guide provides instructions for installing and deploying the Axway Microsoft Outlook add-in and the Axway Lotus Notes plug-in.
l Axway Email Plug-ins Release Notes – This document contains information about installation and upgrade packages, new features, and a list of known limitations.
l Axway Outlook Add-in Installation Guide – This guide provides instructions for installing and deploying the Axway Microsoft Outlook add-in .
l Axway Outlook Add-in Release Notes – This document contains information about installation and upgrade packages, new features, and a list of known limitations.
l Axway Integrator and SecureTransport interoperability Guide – This guide describes the interface between Axway Integrator and Axway SecureTransport and how to configure those products to interoperate.
l SecureTransport Software Developer Kit (SDK) online help – The SDK includes an HTML-based API reference developers can use while customizing SecureTransport.
l SecureTransport REST API online reference – The SecureTransport Server hosts an HTML-based API reference developers can use while developing integrations for SecureTransport.
Go to Axway Sphere at support.axway.com to view or download documentation. The website requires login credentials and is for customers with active support contracts.
Get more help Go to Axway Sphere at support.axway.com to get technical support, download software, documentation, and knowledgebase articles. The website requires login credentials and is for customers with active support contracts.
The following support services are available:
l Official documentation
l Product downloads, service packs and patches
l Information about supported platforms
l Knowledgebase articles
l Access to your cases When you contact Axway Support with a problem, be prepared to provide the following information for more efficient service:
l Product version and build number
l Database type and version
l Operating system type and version
Axway SecureTransport 5.3.0 Developer's Guide 9 Preface
l Service packs and patches applied
l Description of the sequence of actions and events that led to the problem
l Symptoms of the problem
l Text of any error or warning messages
l Description of any attempts you have made to fix the problem and the results
Training Axway offers training across the globe, including on-site instructor-led classes and self-paced online learning
training.axway.com
Axway SecureTransport 5.3.0 Developer's Guide 10 Accessibility
Axway strives to create accessible documentation for users. The following describes the accessibility features of SecureTransport documentation.
Documentation accessibility The product documentation provides the following accessibility features:
l Keyboard-only navigation on page 11
l Screen reader support on page 11
l Support for high contrast and accessible use of colors on page 11
The accessibility of the documentation has been tested with JAWS.
Keyboard-only navigation
l The documentation source code contains ARIA (Accessible Rich Internet Applications) to improve the natural tab order and add focus where needed.
l ARIA landmarks are used to identify the main elements of the online help windows.
Screen reader support
l The documentation structure is clear and the source code of the online help can be interpreted by JAWS.
l Alternative text is provided for images whenever necessary.
l The PDF documents are tagged to provide a logical reading order.
Support for high contrast and accessible use of colors
l The documentation can be used in high-contrast mode.
l There is sufficient contrast between the text and the background color.
l The graphics have the right level of contrast and take into account the way color-blind people perceive colors.
Axway SecureTransport 5.3.0 Developer's Guide 11 Overview 1
Axway SecureTransport is part of the Axway family of managed file transfer (MFT) products. SecureTransport allows organizations to adeptly control and manage the transfer of files inside and outside of the corporate firewall in support of mission-critical business processes, while satisfying policy and regulatory compliance requirements. SecureTransport serves as a hub and router for moving files between humans, systems and more. SecureTransport also completes tasks related to moving files (push or pull), hosting files in mailboxes or "FTP-like" folders, and provides portal access with configurable workflow for file handling and routing. SecureTransport delivers user- friendly governance and configuration capabilities, including delegated administration and pre- defined and configurable workflows, while providing the highest possible level of security.
Axway SecureTransport 5.3.0 Developer's Guide 12 Customizing SecureTransport 2
This section provides information about using rules and agents to customize SecureTransport.
The following topics describe customizing SecureTransport:
l About customization on page 13 - Describes customizing SecureTransport.
l How rules work on page 15 - Describes how customization rules work.
l Using built-in agents on page 21 - Describes using predefined built-in agents for customizing SecureTransport.
l SecureTransport Software Development Kit on page 25 - Describes the Software Development Kit (SDK) containing the SecureTransport API reference, code samples, and JAR files for creating application types and custom rules.
About customization Since you might have different uses for SecureTransport over time, you can customize the software to perform various tasks using the following:
l SecureTransport supports creating custom applications that allow you to automate business processes that require data transfers. For more information about creating custom applications through the application framework, see Using the application framework on page 47.
l Using rules and agents executed by the Transaction Manager. The Transaction Manager is based on a powerful rules-based execution engine. Rules are defined with simple or compound conditions, which include SecureTransport events, environment variable evaluations, and external functions. Each rule also specifies one or more agents to be executed when conditions are met. An agent is code that implements all or part of the business logic associated with an event. Examples of how the Transaction Manager can be used include: File Processing, Automation, Single Sign-On Integration, EDI, File Distribution and Routing, Database Integration, Streaming File Processing, Notification and Alerting, File Tracking, and Customized Access Controls. In SecureTransport, agents are available only on SecureTransport Server and not on SecureTransport Edge.
The following topics provide descriptions of the Transaction Manager and provide examples of when to customize:
l Transaction Manager on page 14 - Describes the Transaction Manager and Transaction Manager rules.
l When to customize on page 14 - Provides a list of examples of when to customize.
Axway SecureTransport 5.3.0 Developer's Guide 13 2 Customizing SecureTransport
Transaction Manager Rules are grouped together into a rules package. Once the rules package is created, you can enable it for use by Transaction Manager. Transaction Manager, a component of the SecureTransport Server, executes the agents in an action by verifying that the rule conditions have been met.
The SecureTransport Administration Tool includes a web-based rule editor to define and manage rules and group application process or policy-related rules into rules packages. At run time, the Transaction Manager rules engine evaluates all enabled rules in the system and triggers actions for rules whose conditions have been satisfied.
Figure 1. Transaction Manager architecture
When to customize The following list shows some examples of tasks that require customization:
l To send an email notification after a file transfer failed, write a custom agent to implement the mail functionality for the "Outgoing Error" event.
l To copy the transferred file to an external system, write a custom agent implementing the push logic for the "Incoming End" event.
l To perform a directory cleanup at the end of an outgoing transfer, write a custom agent implementing the cleanup logic for the "Outgoing End" event.
l To copy or move a transferred file at the end of an incoming file transfer, write a custom agent for routing this file for the "Incoming End" event.
l To integrate with a third party directory product and use it as a source of user records, customize the "User Configuration' and 'Password Authentication' events by writing custom agents with the integration logic.
Some examples of complex customizations you can do using SecureTransport include: Providing custom UI forms for HTTP users or Enforcing custom password-policy rules.
Axway SecureTransport 5.3.0 Developer's Guide 14 2 Customizing SecureTransport
The Professional Services Organization can help you customize SecureTransport. Contact your account representative for more information.
How rules work A rule consists of a set of conditions and actions. The conditions contain events and the actions contain one of two types of agent: external or in-process. For more information about creating and using rules in the Administration Tool and the rule syntax, see the SecureTransport Administrator's Guide.
The following topics describe how rules work and how to build custom rules:
l Conditions on page 15 - Describes using rule conditions to customize.
l Actions on page 15 - Describes using rule actions to customize.
l Precedence on page 16 - Describes setting rule precedence.
l Using NextPrecedence on page 16 - Describes using NextPrecedence to switch precedence levels.
l SecureTransport built-in rules packages on page 16 - Describes the SecureTransport built-in rules packages.
l Custom rules on page 18 - Describes and provides how to instructions for building custom rules.
Conditions You can set the type of event or other attributes to be considered in the condition. You can select more than one attribute in a condition. A full list of events and environment variables can be found in Working with event types on page 106, and Using environment variables on page 155.
Actions An action calls one or more agents. Each agent consists of code that accomplishes a task you want controlled by the rule. You can use more than one agent in an action. The order in which you add the agent to the action controls the order the agents are executed.
l External Agents – External agents are called by a rule. External agents are typically created using a scripting language.
l In-process Agents – In-process agents are also called by a rule. In-process agents are created using Java.
In-process agents offer greater scalability and provide better performance. External agents offer more flexibility but can affect performance.
All rules also have a precedence setting which determines whether the rule will be executed when more than one rule is triggered.
Axway SecureTransport 5.3.0 Developer's Guide 15 2 Customizing SecureTransport
Precedence Each rule has a numeric value that defines the rule precedence. Many built-in processing rules have a precedence setting of 100. If a rule is set with a precedence to a number lower than 100, the rule will have a greater precedence than those rules with 100 or higher.
Using NextPrecedence Different precedence levels are linked using the NextPrecedence agent. This agent allows you to execute rules at the next lower precedence level after the current rule. For more information about the agent, see NextPrecedence on page 21.
SecureTransport built-in rules packages SecureTransport contains several rules packages that provide the default functionality. This functionality is critical for the proper operation of SecureTransport. Customization should be used with caution to make sure that the default functionality is not broken. For more information about the built-in rules packages, see the SecureTransport Administrator's Guide.
Note The built-in rules packages should not be copied or modified.
SecureTransport has reserved the following ranges of precedence for the three main types of rules:
Range Description
10 - 29 Pre-processing rules
30 - 49 Post-processing rules
100 - 500 Main processing rules
Rules within the pre-processing range are set up to execute the actions that perform pre-processing tasks, then execute the NextPrecedence action. The rules within the post-processing range are evaluated next. These rules execute the NextPrecedence action before executing the actions that perform post-processing tasks. Because the NextPrecedence action was executed, the rules within the main processing range are evaluated and the appropriate actions are performed before the post- processing rule actions. The following example illustrates this principle.
The following topic provides a built-in rule example:
l A built-in rule example on page 17
Axway SecureTransport 5.3.0 Developer's Guide 16 2 Customizing SecureTransport
A built-in rule example To illustrate the sequence of events, imagine a remote user wants to upload some files to the server. Several rules are used to process the upload. The Streaming rules package contains the rule VirtualAccessCheck that pre-processes the request. The InStreaming rules package contains the rule Incoming_Start that performs the main processing task for this request. The Streaming rules package contains the rule TransferLog_Start that performs post-processing upon the request.
The following example shows how the rules work:
1. The SecureTransport server receives a request to upload files from a remote user.
2. The Incoming start event is sent to the Transaction Manager.
3. After checking the precedence setting, Transaction Manager selects the VirtualAccessCheck rule from the Streaming rules package.
4. Transaction Manager executes the agents VirtualAccessCheckAgent and NextPrecedence as specified in the action for the rule. The NextPrecedence agent locates all rules that match the conditions and looks for the rule with the precedence level set to the closest value that is greater than 20. The TransferLog_Start rule is executed.
Axway SecureTransport 5.3.0 Developer's Guide 17 2 Customizing SecureTransport
5. The first action in the TransferLog_Start rule calls the NextPrecedence agent, which locates the first rule that meets the condition and has a precedence setting greater than 30. The Incoming_Start rule meets the condition and is executed.
After the Incoming_Start rule executes, the request is returned to the TransferLog_ Start rule where the remaining actions are executed. The TimeStamp agent records the time the transfer starts and TransferLogAgent creates a log entry.
6. Since there is no NextPrecedence agent at the end of the chain, the Transaction Manager returns the execution status to the protocol server. In this example, Transaction Manager returns an exit code specifying that files can be uploaded.
Custom rules Although SecureTransport is a fully functional protocol server out of the box, you can customize it to integrate with third party applications. Customization is handled inside rules created using the SecureTransport Administration Tool. SecureTransport allows you to create new rules and agents. You can also modify existing rules you created in the past, however, you should not modify the predefined rules built into SecureTransport. How to create a custom rule is explained in the SecureTransport Administrator's Guide.
The following topics describe how built-in and custom rules interact and provide how to instructions for customizing and creating custom rules:
l How built-in rules and custom rules interact on page 18
l Custom agents in a rule on page 19
l Customization at a glance on page 19
l Creating a custom rule on page 20
l A custom rule example on page 20
How built-in rules and custom rules interact The custom rules you create should be added into the appropriate stage of the default functionality process by controlling the rule precedence. Each built-in rule is given a precedence setting based on the type of task it performs: pre-processing, main processing, or post-processing. Typically custom rules are inserted before or after main processing.
Axway SecureTransport 5.3.0 Developer's Guide 18 2 Customizing SecureTransport
Different precedence levels are linked using the NextPrecedence agent. This agent allows you to execute rules at the next precedence level after the current rule.
Custom rules can have precedence scores outside the reserved ranges:
Range Description
0 - 9 Rules that completely override the default logic or perform custom pre-processing tasks.
50 - 99 Custom rules that insert logic before the main processing or override it.
To ensure the proper execution of the default rules, custom rules should always use the 50 - 99 range. You can do one of three things within this range to control how the custom rule is processed:
l If you want your custom agent executed before the built-in rules perform the main processing actions, include NextPrecedence after your custom agent.
l If you want to execute your custom agent after the built-in main processing, include NextPrecedence before your custom agent.
l If you want to override the built-in processing completely do not include NextPrecendence and only include your custom agent in the rule.
Note Do not use a custom agent before the built-in pre-processing rules or after the built-in post- processing rules.
You must allow the built-in pre-processing rules to be executed before the custom rules because they set up the requirements necessary for the proper handling of events. Built-in post-processing rules are also required for proper clean-up and completion of the event handling. The environment for handling events might be destroyed by the built-in post- processing rules.
Custom agents in a rule You can add an agent to an existing custom rule or to a newly created rule. Custom agents can be one of two types: in-process or external. External agents are developed using a scripting language and are explained in Developing external agents on page 27. In-process agents are developed in Java using the Transaction Manager API and are explained in Developing in-process agents on page 34.
Customization at a glance The following steps outline the high level process involved in customization tasks:
1. Determine which event type or rule condition suits your needs. 2. Determine the precedence level to use for the rule. Decide whether you need to use NextPrecedence in the rule.
Axway SecureTransport 5.3.0 Developer's Guide 19 2 Customizing SecureTransport
3. Implement the custom agent according to the event type interface described in Working with event types on page 106. 4. Install the agent. 5. Create the associated custom rule. 6. Test the new rule.
Creating a custom rule Here is an overview of the steps used to create a custom rule:
1. Create a rules package. This automatically opens rule creation page. 2. Type a rule name. Use a descriptive name, such as one that indicates the event type used. 3. Set the precedence value. For more information about setting the precedence for a rule, see Precedence on page 16. 4. Modify the condition that triggers the rule. 5. Modify the actions triggered by the rule. 6. Add any new custom agents with proper invocation parameters if needed. Add the NextPrecedence agent when required.
7. Click Save and enter a name for the new rules package. For information about creating rules and rules packages, see the SecureTransport Administrator's Guide.
Note Rules created for customization purposes should be created in their own rules package, the default built-in packages should not be modified.
A custom rule example If you do not want to allow users to upload files of a specific type, such as executables, from a remote user to the server, you can create a rule that prevents specific file types from uploading. This rule has a precedence setting of 50 so it will override the default Incoming_Start rule found in the InStreaming package.
Axway SecureTransport 5.3.0 Developer's Guide 20 2 Customizing SecureTransport
The following example shows how the custom rule works:
1. The SecureTransport server receives a request to upload files from a remote user.
2. The Incoming start event is sent to the Transaction Manager.
3. After checking the Precedence setting and determining that this rule has a greater precedence than other rules, Transaction Manager selects the custom rule, BlockExecutables from the custom rules package.
4. The DXAGENT_TARGET condition is evaluated by Transaction Manager which looks at the file extensions of all files being uploaded for a match.
5. If there are any files with an .exe extension, Transaction Manager executes the agent, DenyPermissionAgent as specified in the action for the rule.
6. DenyPermissionAgent is an in-process agent, so the action calls a Java class.
7. The Transaction Manager returns the execution status to the protocol server. In this example, Transaction Manager returns an exit code specifying that permission is denied and no .exe files can be uploaded.
Using built-in agents The predefined rules use agents that are built-in to SecureTransport. Almost all of these agents carry out a specific function and are not intended for use in custom rules. However, there are also agents that are generic and are designed for use in custom rules.
This following topics describe three of those agents:
l NextPrecedence on page 21 - Describes the NextPrecedence agent.
l Continue on page 23 - Describes the Continue agent.
l SetExitValue on page 24 - Describes the SetExitValue agent.
NextPrecedence When an event is evaluated against the rules packages, rules might be executed that span multiple levels of precedence.Normally, the Transaction Manager executes the rules with the highest level of precedence and discards all other rules.
By calling NextPrecedence, the Transaction Manager can switch to another precedence level and execute rules that match the evaluated conditions. The default behavior of NextPrecedence is to move to the next lower level of precedence and execute rules that match the conditions determined when the event was originally submitted. Rules are not reevaluated.
NextPrecedence is available as an in-process agent and as part of the API. Using NextPrecedence in combination with the precedence range definitions allows you to easily override, interlace, or extend the built-in rules.
The following example demonstrates how NextPrecedence works:
Axway SecureTransport 5.3.0 Developer's Guide 21 2 Customizing SecureTransport
Rule 1:
Precedence 80 if (EventType == e) then (A, NextPrecedence, B)
Rule 2:
Precedence 90 if (EventType == e) AND (e.account == MYACCOUNT) then (D, E)
1. Rule 1 meets the condition evaluation criteria and action A is executed. 2. Then NextPrecedence is executed and rules with a precedence of 90, the next lower precedence value, are evaluated. 3. Rule 2 meets the conditions and the actions D and E are executed. 4. Finally, since Rule 1 is still active, action B is executed after action E is finished.
There are situations when you might want to reevaluate the rules after some information is available in the event context. This situation can occur when one of the currently executing agents adds information to the event context that must be propagated to other rules at lower precedence levels. When you call NextPrecedence in an action, you can choose whether you want to trigger rule reevaluation by setting the reevaluateRules parameter.
If the reevaluateRules parameter for NextPrecedence is set to true, the Transaction Manager does the following tasks in the order listed:
l Discard all agents queued at precedence levels lower than the current precedence.
l Reprocess the event through the rules engine. This results in the regeneration of agent jobs at lower precedence levels using the changed event context as the condition to meet.
l Transaction Manager steps down to the next precedence level and continues execution. From this point, the behavior of Transaction Manager will be the same as that of the NextPrecedence agent without reevaluation.
The following example demonstrates how NextPrecedence works with the reevaluateRules parameter set to true:
Rule 1:
Precedence 80 if (EventType == e) then (A, NextPrecedence (reevaluateRules=true), B)
Rule 2:
Precedence 90 if (EventType == e) AND (e.account == OTHER) then (C)
Rule 3:
Axway SecureTransport 5.3.0 Developer's Guide 22 2 Customizing SecureTransport
Precedence 90 if (EventType == e) AND (e.account == MYACCOUNT) then (D, E)
1. Rule 1 meets the condition evaluation criteria and action A is executed. When action A executes, the associated agent sets the account variable equal to MYACCOUNT.
2. Then NextPrecedence is executed with the reevaluateRules parameter set to true. Rules with a precedence of 90, the next lower precedence value, are evaluated for the condition account = MYACCOUNT.
3. Rule 3 meets the condition and the actions D and E are executed. 4. Finally, since Rule 1 is still active, action B is executed when action E is finished.
Rule 2 containing action C is skipped since the account variable did not meet the new condition.
Continue Rule actions are composed of agents that are executed in a sequential chain. In-process agents have a choice to continue executing the agent chain or not through a return value. If an in-process agent returns false, the Transaction Manager breaks the chain and stops executing any other agents listed in the action. External agents can only return an exit code, but cannot control the chaining. The next agent in the chain is always executed.
The Continue agent is an in-process agent that facilitates communication between an external agent and the Transaction Manager. External agents can exit with any value, but the value must be interpreted by a Continue agent to determine whether or not the Transaction Manager should run the remaining agents in the chain. Without a Continue agent an external agent can fail, but the Transaction Manager does not stop the execution chain.
In-process agents normally do not require the use of Continue agent. If the agent has multiple exit codes to deal with, these might be interpreted internally within the agent and result in either a true or false outcome. In some situations, this might not be convenient. You can choose to have the in- process agent always return true and have a Continue agent following that to interpret the exit codes.
The Continue agent uses two parameters; stop and continue. The stop parameter is used to prevent further agent execution in a chain. Use the continue parameter when you want agents to keep executing. The values for the parameters are set in the rule and consist of space-delimited lists of values. You only need to specify one of the two parameters.
Use the Continue agent when you are using a mix of in-process and external agents or when you are using only external agents. For more information about using the Continue agent with external agents alone, Precedence on page 16.
The Continue agent can be used after a NextPrecedence agent. The following example from the Streaming rules package demonstrates this usage:
Axway SecureTransport 5.3.0 Developer's Guide 23 2 Customizing SecureTransport
In the TransferLog_Start rule, the actions TimeStamp and TransferLogAgent execute only if there are no error exit codes resulting from executing NextPrecedence.
Note This single NextPrecedence action at precedence level 30 can set off a whole chain of agent executions at several levels of precedence. Since control eventually returns back to the calling NextPrecedence, make sure you check that the event is successfully processed.
SetExitValue Use the SetExitValue agent when you want to pass a specific exit value during event execution. The exitCode parameter allows you to set the specific return code that is sent in response to the event. Unless the exitCode is set to 0, the agent also terminates the agent chain. For the exit codes associated with each event, see Working with event types on page 106.
Axway SecureTransport 5.3.0 Developer's Guide 24 2 Customizing SecureTransport
SecureTransport Software Development Kit SecureTransport provides a Software Development Kit (SDK) containing the SecureTransport API reference, code samples, and JAR files for creating application types and custom rules. Contact Axway Global Support to request the SDK. See Get more help on page 9.
The SecureTransport SDK is stored in a compressed file that uses the following naming convention: STEE-
l x - major version
l y - minor version
l z - maintenance version
l n - (Optional) Service Pack number
The SDK contains the following directories:
l doc – This folder contains the HTML files that comprise the API reference for SecureTransport.
l lib – This folder contains the JAR files necessary for compiling custom code and samples included in the SDK. The jar files in this folder are already deployed in the SecureTransport installation. They are provided here to help set up development environment. The main JAR file is st-server-api.jar. Make sure the JAR files are added to the CLASSPATH of your development environment.
l samples – This folder contains the source code for sample customizations. The full source code of many of the examples used in this guide can be found in this location. The sample application type, Sample Application, is also located in this folder.
Unzip the SDK on the computer where you are developing customizations for SecureTransport to access the samples, the API reference, and to set up the development environment using the included JAR files.
The following topics describes how to access the SecureTransport APIs and list the sample agents and applications:
l SecureTransport APIs on page 25 - Describes how to access the SecureTransport APIs.
l Sample agents and applications on page 26 - Lists the sample agents and applications.
SecureTransport APIs The SecureTransport API reference provides information on agents, events, environment variables, the application framework, the account manager, and the factory interface. Use this as a reference when designing and creating your applications, agents, and rules. The SecureTransport APIs are accessible through the JAR files.
Axway SecureTransport 5.3.0 Developer's Guide 25 2 Customizing SecureTransport
Sample agents and applications Study the sample agents and applications to learn how to use the API to implement your own customizations. Each sample includes a README.txt file with more information.
Sample Agents
Name Description
Anonymous Allows anonymous user to login in ST and act as a virtual user. Login
Cleanup Delete a file after it has been successfully transferred.
Notify Sends an e-mail notification when a file is uploaded to the server. Demonstrates how to use email logic and agent invocation parameters.
Permission Prevent upload of files when the file name matches a pattern set in a rule condition.
Sample Applications
Name Description
Password A non-subscribeable application that notifies users that their password will Expiration expire. Demonstrates the use of a scheduled application. Notify
Sample A simplified version of the Standard Router application.
Send to Sends a file to multiple users. Multiple
Zip Unzips an uploaded file. Demonstrates data transformation. Transformation
Axway SecureTransport 5.3.0 Developer's Guide 26 Developing external agents 3
The following topics provide an external agent overview, how to procedures for developing, chaining, and installing external agents. and external agent examples:
l External agent overview on page 27 - Provides an overview of external agents.
l Developing and triggering external agents on page 27 - Describes how to develop and trigger external agents.
l Chaining external agents on page 30 - Provides how to instructions for chaining external agents.
l Installing external agents on page 31 - Provides how to instructions for installing external agents.
l External agent examples on page 32 - Provides external agent examples.
External agent overview In the Transaction Manager, rules are used to trigger actions that are performed when certain conditions are met. Each action calls one or more agents. Multiple actions can be triggered as a result of a single condition.
There are two agent types:
l External Agents that run as separate processes and are managed by Transaction Manager.
l In-process Agents that run within the Transaction Manager process. For more details on In- process Agents, see Developing in-process agents on page 34.
External agents can be created using Java or a scripting language such as Perl or a shell script. This chapter discusses how to create external agents using a scripting language. All examples shown use Perl.
Developing and triggering external agents You can develop external agents using any programming or scripting language, for example, Java or Perl.
To trigger external agents, you have to define the agent in the Action Editor window when creating a rule. For more information, see the SecureTransport Administrator's Guide. When the rules are triggered, the agents get executed in a separate process.
The following topics describe how external agents receive input data and send back results and how to run external agents:
Axway SecureTransport 5.3.0 Developer's Guide 27 3 Developing external agents
l Calling interface on page 28 - Describes how your agent receives the input data and sends back the results.
l Running external agents on page 29 - Describes how to run external agents.
Calling interface When Transaction Manager executes your agent, input data is passed to the agent, and your agent should produce a set of results. The following topics describes how your agent receives the input data and sends back the results:
l Input data on page 28
l Results on page 28
Input data Agents can receive input data as:
l Environment variables – Environment variables pass contextual information to the agent, such as the current user and the target directory. For more information, see Using environment variables on page 155.
l Input parameters – Input parameters are specified as part of the command line for your agent. For example, if your agent is called deny.pl and your first parameter is Access_ Denied, then you would specify this as follows: deny.pl Access_Denied
l Standard input stream (STDIN) – STDIN is used in a few agents. In the upload agent, it is used to receive the input stream for the contents of a file being sent from the client. In the certificate agent, it receives the client certificate.
l Session variables – Session variables are set using the Perl module state.pm. The module state.pm uses get and set functions to configure the session variables. Session variables can also be retrieved using the state.pm Perl module. For example,
use SecureTransport::State; my $state = new SecureTransport::State; my CONFIG_PASSWD = $state->get("CONFIG_PASSWD");
Results Agents can return results using a combination of the following:
l Exit Value – When an external agent returns, the exit value is interpreted by the server. Each event type defines specific exit values. Refer to the documentation for the specific event to understand what the exit values mean in a particular context.
Axway SecureTransport 5.3.0 Developer's Guide 28 3 Developing external agents
l Standard output stream (STDOUT) – STDOUT is used in a number of agents. In the download agent, it is used to stream the file content back to the client. In other agents, it is used to return configuration information and server side cookies.
Running external agents All external agents need to be executed using the runas program (runas.exe on Windows.) runas will run an agent in the security context of the logged-in user which initiated the execution of the agent.
Format: runas [options]
Arguments: the agent command and its arguments
Note You can pass command event arguments to external agents as command line arguments by appending $DXAGENT_EXTRAARGS to the agent’s command line specification.
Options:
l -r – Causes the agent to run in the security context of a privileged user, root in UNIX and System in Microsoft Windows
l -u
When an agent is run, it uses the user ID that the server is using. If the server is running as a non- root user, the -r and -u switches are ignored.
When an external agent is executed through runas (runas.exe on Microsoft Windows), then errors reported on standard error are logged to the tm_agent_error.log file, otherwise stderr is not available and agent should redirect its error output to a custom log file.
Examples:
l
External agent is run in the security context of user
l
External agent is run in the security context of Local System user.
l
External agent is run in the security context of logged in user.
In the above examples, replace runas with runas.exe for Microsoft Windows operating systems.
Axway SecureTransport 5.3.0 Developer's Guide 29 3 Developing external agents
Note To create portable rules packages that run on both Windows and UNIX-based servers, use runas.exe as the command wrapper and create a link from runas.exe to runas while installing the package on a UNIX-based server.
Chaining external agents A rule can contain a number of actions. Once the external agent is executed the next action in the chain invoked. To stop execution of other agents in the chain when you want to, SecureTransport provides an agent called Continue. This agent allows you to use the exit value of the previously executed agent to determine if you want to continue or stop running agents in a rule.
When the external agent exit value equals a continue value, the associated Continue agent returns true and the Transaction Manager continues to the next agent in the chain. When the external agent exit value equals a stop value, the associated Continue agent returns false and the Transaction Manager exits the action. For more information about the Continue agent, see Using built-in agents on page 21.
The following example shows how the built-in rule, ExtPermissionsCheck, uses the Continue agent to control whether the next agent can run or the rule will stop processing the agents. The ExtPermissionsCheck rule is located in the ExtPermissionsCheck rules package.
Axway SecureTransport 5.3.0 Developer's Guide 30 3 Developing external agents
1. If the condition for the ExtPermissionsCheck rule is met, the fscheck agent executes.
2. The Continue agent executes and regardless of the exit code, Transaction Manager executes the next agent in the chain.
Note Use Start in Windows or &/nohup in UNIX-based platforms in an external agent to run a command in the background.
Installing external agents After you have created the external agent file, you must install it in order to use the agent.
During the install process a ^M character is appended to each line of the script file. If you are using a Perl or shell script you need to convert the scripts to a UNIX format before installing.
Axway SecureTransport 5.3.0 Developer's Guide 31 3 Developing external agents
1. In the Administration Tool, Select Transaction Manager > Install Agents. The Install Agents page is displayed.
2. Browse your local file system and choose the agent’s script file.
3. Select the External Java Agent checkbox if the external agent you are installing is a .jar or .class file.
4. Click Install. If the file already exists on the server, you must confirm to overwrite it. 5. Make necessary changes to the SecureTransport Agents section so that the event is handled by the Transaction Manager. 6. Select Operations > Server Control. 7. Stop and restart the TM Server.
External agent examples The topic contains a few examples that illustrate how external agents can be used:
l A mail notification is sent upon receiving a file.
l A user is prevented from uploading an executable file.
Note You should have a working knowledge of Perl to fully understand these examples.
The following topics provide external agent examples:
l Mail notification on file receipt on page 32 - Provides an example of email notification on file receipt.
l Permissions on page 33 - Provides an example of executable file upload denial.
Mail notification on file receipt In this example, the Perl agent sends an email notification when a file is uploaded to the server. It demonstrates the use of the predefined environment variables, DXAGENT_TARGET and DXAGENT_LOGINNAME, containing the file name and the login name respectively. These variables are incorporated into the email.
Axway SecureTransport 5.3.0 Developer's Guide 32 3 Developing external agents
my $sendmail = $ENV{'MAILER'};
if($#ARGV eq -1) { $MAILTO = "root\@localhost"; } else { $MAILTO = @ARGV; }
open(SENDMAIL, "|$sendmail -s $subject ${MAILTO}") or die "Cannot run sendmail"; print SENDMAIL $MAILTO,"\n"; print SENDMAIL "Confirmation of your file upload\n"; print SENDMAIL "File $ENV{'DXAGENT_TARGET'} has been uploaded successfully by $ENV{'DXAGENT_LOGINNAME'}\n" close(SENDMAIL);
exit 0;
Permissions In this example, the agent, triggered by the incoming start event, prevents the user from uploading files with an .exeextension.
To trigger this agent:
1. Create a rule that matches files that have an .exe extension.
2. In the action part of the rule, invoke an agent called deny.pl. This agent writes an error message to STDERR and returns an exit status of -1. This error message is written into the agent error log file. The error message is defined as an environment variable called MSG. The variable is set within the action part of the rule in the environment variable section.
print STDERR $ENV{‘MSG’}; exit -1;
Note If you see the exit code -128 in the log file after trying to execute an agent, the agent is unable to access a Perl module. This code is applicable to external agents written in Perl. The agent is running as a specific user, not as root.
The specific user assigned to the agent needs to have read/execute access to
Axway SecureTransport 5.3.0 Developer's Guide 33 Developing in-process agents 4
The following topics provide information about implementing in-process agents:
l Developing in-process agents overview on page 34 - Provides an overview of developing in- process agents.
l Creating in-process agents on page 35 - Provides how to instructions for creating in-process agents.
l Installing in-process agents on page 37 - Provides how to instructions for installing in-process agents.
l In-process agent examples on page 38 - Provides in-process agent examples.
l About the Transaction Manager API on page 43 - Describes the basic Java APIs and provides a summary of how to implement an in-process agent
Developing in-process agents overview In the Transaction Manager, rules are used to trigger actions that are performed when certain conditions are met. Each action calls one or more agents. Multiple actions can be triggered as a result of a single condition.
There are two agent types:
l External Agents that run as separate processes and are managed by Transaction Manager. For more details on external agents, see Developing external agents on page 27.
l In-process Agents that run within the Transaction Manager process.
The following topics discuss creating and installing in-process agents.
To develop an in-process agent, you must use the Java programming language and follow the Transaction Manager framework. This framework includes the IInprocessAgent Java interface, a Java class called BaseAgent for basic implementation of IInprocessAgent and a session API for data that is persistent across agent execution. For details on the BaseAgent class, see About the Transaction Manager API on page 43.
Note Additional information about the Transaction Manager framework can be found in the API reference that ships with SecureTransport. For more information about the API reference and the SDK, see Customizing SecureTransport on page 13.
If you are creating an agent that communicates with outside machines and you want to go through a proxy, you will need to modify the configuration.xml file located in
Axway SecureTransport 5.3.0 Developer's Guide 34 4 Developing in-process agents
Add the appropriate user agent classes or classes that open a socket to the SocksClasses element using the Include element. You can use a package mask wildcard to specify the packages.
Creating in-process agents The code for an in-process agent can be either a java class (.class) file or contained within a .jar file. This .jar or .class file must be installed on the same machine as the SecureTransport Server which contains the Transaction Manager.
An in-process agent defines an executeAgent method that is called when the agent is invoked by extending the BaseAgent class. Parameters passed to the agent define the context for invoking the agent. After execution of a set of actions, the agent returns a value indicating that agent execution is complete.
In-process agents can retain state information between agent calls. The state information can be persisted either globally or relative to an end-user login session.
The following topics provide how to instructions for creating an in-process agent and describe how the in-process agent receives input data and produces results:
l Agent creation at a glance on page 35 - Provides how to instructions for creating an agent.
l In-process agent interface on page 36 - Describes how the in-process agent receives the input data and produces the results.
Agent creation at a glance The following is a summary of the steps used to implement an in-process agent:
Axway SecureTransport 5.3.0 Developer's Guide 35 4 Developing in-process agents
1. Create a class MyAgent extending BaseAgent.
2. Override the executeAgent method to implement your business logic.
The following topic provides how to instructions for compiling an in-process agent:
l Compiling an in-process agent on page 36
Compiling an in-process agent To set up the development environment for building in-process agents install the SDK by unzipping the archive on the computer where you will develop the agents. For more information about the SDK, see Customizing SecureTransport on page 13.
In-process agent interface When Transaction Manager executes an agent, input data is passed to the agent, and the agent returns a set of results. The following topics describe how the in-process agent receives the input data and produces the results:
l Input data on page 36
l Results on page 37
Input data The in-process agent receives input data in the following ways:
l Environment variables – Environment variables provide context information to the agent, such as the current user and the target directory. For more information, see Using environment variables on page 155.
l Input Stream – The InputStream is used by the in-process agents to read the data stream associated with the event. For example, In the upload agent, the InputStream is used to receive the input stream for the contents of a file being sent from the client. In the certificate agent, the InputStream receives the client certificate data.
The input stream can only be read by one agent. Once the input stream has been read, no other agent can access it. Additionally, an input stream must be read completely before writing to an output stream.
l Invocation parameters – Provides the parameters to the agent. Invocation parameters are passed as name value pairs. For example, you have an agent with two parameters:
Parameter Value
name user
emailid [email protected]
Axway SecureTransport 5.3.0 Developer's Guide 36 4 Developing in-process agents
The parameters are specified in the class description file:
l name=user, [email protected]
Results The agent returns results using a combination of the following:
l Return Code – A boolean value returned from the agent method executeAgent:
o true – Causes Transaction Manager to continue executing agents in the chain.
o false – Causes Transaction Manager to stop execution of the agent chain.
l Exit Value – The in-process agent can set the exit value using the method setEventExitValue. Each event type defines specific exit values. Refer to the documentation for the specific event to understand what the exit values mean in context. If an agent does not set the exit value, the exit value from the previous agent is used. If there is no previous agent, an exit value of 0 is used. For an agent for where 0 means an error; the agent must set the exit value.
l Output Stream – The output stream is used by the in-process agents to return information to the server. The input stream must be read completely before writing to the output stream.
Installing in-process agents After developing an in-process agent, you must install it in order to use the agent. You can install multiple agents in one jar file or install each agent in a separate class file. If you have additional jar files that an agent calls, install each jar file once only. Agents have access to all uploaded files, and will call any class specified in the agent that is available.
Classes installed using the Install Agents page can be selected from the Agent Class Name field when creating an in-process agent.
1. In the Administration Tool, Select Transaction Manager > Install Agents. The Install Agents page is displayed.
2. Type the name of the .class or .jar file of the agent or click Browse to select the .class or .jar file of the agent from your local system.
Note Make sure External Java Agent is not selected when installing in-process
Axway SecureTransport 5.3.0 Developer's Guide 37 4 Developing in-process agents
agents.
3. Click Install. If the file already exists on the server, you will be prompted for a confirmation to overwrite it. Class files are uploaded to the
If you do not see the new in-process agent when editing an action, perform the following steps:
1. Log in to the SecureTransport Server as the user who installed and is running SecureTransport.
2. Edit
3. Add the class name using the qualified path with package name like the following example: com.myexample.agents.NotifyAgent
4. Save the agentlist file and log out.
In-process agent examples The following topics provide a few examples to illustrate how agents can be installed and used:
l Installing the examples on page 38 - Describes how to install the in-process agent examples.
l Mail notification on file receipt on page 39 - Provides an example of an in-process agent sending an email notification when a file is uploaded to the server.
l Denying permission to upload specific file types on page 41 - Provides an example of an in- process agent preventing the uploading of executable files.
l Deleting a file after it is transferred to a destination on page 42 - Provides an example of an in- process agent deleting a transferred file after it is downloaded.
Note All the examples included in this chapter are included in the SecureTransport SDK. The SDK includes the Java classes and rules packages you can import to see how in-process agents work.
Installing the examples Each example is accompanied by a README text file containing a detailed description of building, installing, and testing the agent. Each example has an XML file for the rules package and the .java source files.
Axway SecureTransport 5.3.0 Developer's Guide 38 4 Developing in-process agents
Mail notification on file receipt This in-process agent sends an email notification when a file is uploaded to the server. It demonstrates the use of the predefined environment variables, DXAGENT_TARGET and SMTP_ HOST, containing the file name and the SMTP host name respectively. These variables are incorporated into the email.
To create a mail notification upon file receipt:
1. Define the class
public class IncomingEndNotifyAgent extends BaseAgent { ... }
2. Define an executeAgent method for this class. Transaction Manager executes this method when the agent is invoked. A return code of true instructs the Transaction Manager to continue executing other agents in the sequence.
protected boolean executeAgent() { try { ... } catch (AddressException exception) { return false; } catch (MessagingException exception) { return false; }
return true; }
The first step of the status method is to extract the invocation parameters.
String fileName = getEnvironmentVariable(Events.DXAGENT_TARGET); String smtpHost = getInvocationParameter(SMTP_HOST); if (smtpHost == null) { return false; }
String toAddress = getInvocationParameter(RECIPIENT_ADDRESS, "[email protected]"); String fromAddress = getInvocationParameter(SENDER_ADDRESS, "[email protected]"); String subject =
Axway SecureTransport 5.3.0 Developer's Guide 39 4 Developing in-process agents
getInvocationParameter(NOTIFY_SUB, "Upload successful"); String smtpUser = getInvocationParameter(SMTP_USER, ""); String smtpPass = getInvocationParameter(SMTP_PASS, "");
The remaining steps involve setting up a mail message to be sent using the javax.mail package. 3. Define the message content.
String content = getInvocationParameter(NOTIFY_MSG, "File " + fileName + " uploaded successfully\n" + "Have a good day.\n");
4. Define the mail session object.
Properties props = new Properties(); props.put("mail.smtp.host", smtpHost); Session session = Session.getDefaultInstance(props, null);
5. Create the MIME message.
Message message = new MimeMessage(session); Address addressList[] = {new InternetAddress(fromAddress)};
message.setFrom(new InternetAddress(fromAddress)); message.setReplyTo(addressList); message.setSubject("Upload successful"); message.setSentDate(new Date()); message.setText(content);
6. Send the message to the recipients. Set the smtpUser and smtpPass strings using the sender user name and password for the SMTP mail server.
Address toList[] = {new InternetAddress(toAddress)}; String smtpUser=""; // fill in this variable with specific value String smtpPass=""; // fill in this variable with specific value
Transport transport = session.getTransport("smtp"); transport.connect(smtpHost, smtpUser, smtpPass); transport.sendMessage(message, toList);
The email is sent.
Axway SecureTransport 5.3.0 Developer's Guide 40 4 Developing in-process agents
Denying permission to upload specific file types This agent, triggered by the Incoming Start event, prevents uploading of files with an .exe extension.
To create a filter to deny permission to a specific file type:
Note If you import the rule for this example from the SecureTransport SDK, you can skip the first two steps.
1. Create or modify a rule that matches files that have .exe extensions.
2. In the action part of the rule, invoke an agent named DenyPermissionAgent.
3. To implement the agent, define the class.
public class DenyPermissionAgent extends BaseAgent { protected boolean executeAgent() { getAgentAccess().logAgentError(getEnvironmentVariable("MSG")); setExitValue(1);
return false; } }
4. Define an executeAgent method for this class. Transaction Manager executes this method when the agent is invoked.
protected boolean executeAgent() {
The status method writes an error message to the agent log file using the logAgentError method. The error message is defined in an environment variable called MSG. The variable is set within the action part of the rule in the environment variable section. It then sets the event exit value to 1.
getAgentAccess().logAgentError(getEnvironmentVariable("MSG")); setExitValue(1);
5. The final step of the execute method is to return a code of false. A return code of false instructs the Transaction Manager to stop executing other agents in the sequence.
return false;
Axway SecureTransport 5.3.0 Developer's Guide 41 4 Developing in-process agents
Deleting a file after it is transferred to a destination This agent, triggered by the Outgoing end event, shows how to delete a transferred file after you finish downloading it. The example also shows how to implement logging using log4j. Log entries are created and stored in the tm.log file located in the
To configure cleanup:
1. To implement this agent, define the class and create a logger instance.
public class OutgoingEndCleanupAgent extends BaseAgent { private static Logger sLogger = Logger.getLogger (OutgoingEndCleanupAgent.class); ... }
2. Define the executeAgent method of this class. Transaction Manager executes this method when the agent is invoked.
protected boolean executeAgent() { ... }
Extract the environment variable and make a log entry. You are also defining the file name to delete.
String fileName = getEnvironmentVariable(Events.DXAGENT_FULLTARGET);
sLogger.debug("OutgoingEndCleanupAgent called for " + fileName); File transferredFile = new File(fileName);
3. Attempt to delete the transferred file. If the deletion fails, an error message is written in the log, and the agent stops execution.
if (!transferredFile.delete()) { sLogger.error("OutgoingEndCleanupAgent: failed to delete the file."); return false; }
Axway SecureTransport 5.3.0 Developer's Guide 42 4 Developing in-process agents
4. The final step of the execute method is to return a value of true. A return code of true instructs the Transaction Manager to continue executing other agents in the sequence.
return true;
About the Transaction Manager API The following topics describe the basic Java APIs and provide a summary of how to implement an in-process agent:
l BaseAgent class on page 43 - Describes the BaseAgent class.
l Events class on page 45 - Describes the Events class.
l Logging on page 46 - Describes Transaction Manager logging.
Note Additional information about the Transaction Manager API can be found in the API reference that ships with SecureTransport.
BaseAgent class The BaseAgent class is a direct implementation of IInprocessAgent interface. This class provides an easy to use base implementation for accessing Transaction Manager framework abstractions. Subclass BaseAgent to start the in-process agent. The main function in BaseAgent class is:
protected boolean executeAgent ();
This method should be overridden to implement specific business logic. The return value from the executeAgent method determines whether Transaction Manager should continue to execute agents. Return true to continue agent execution, return false to stop agent execution.
The following topics describe event-based methods, session-based methods, and impersonation:
l Event-based methods on page 43
l Session-based methods on page 44
l Impersonation on page 45
Event-based methods The following methods are used with events in an agent:
l Environment Variables – Agent environment variables can be accessed through the following methods:
protected String getEnvironmentVariable (String variableName,
Axway SecureTransport 5.3.0 Developer's Guide 43 4 Developing in-process agents
String default) protected String getEnvironmentVariable (String variableName)
For details about the environment variable agent interface, see the API reference.
l Input Stream – Agent input stream can be accessed through this method:
protected InputStream getInputStream();
If the input data is not very large, it can also be accessed by the following method:
protected String input ();
l Arguments – Invocation Parameters can be accessed through the following methods:
protected String getInvocationParameter (String parameterName, int index, String defaultValue) protected String getInvocationParameter (String parameterName, String defaultValue) protected String getInvocationParameter (String parameterName, int index) protected String getInvocationParameter (String parameterName)
l Output Stream – Agent output stream can be directly accessed through two methods
public void print (String s); public void println (String s);
The agent output stream can also be accessed directly through this method:
protected OutputStream getOutputStream ()
l Exit Codes – The Event exit code is set by calling the method:
protected void setEventExitValue(int status)
setEventExitValue sets the event exit value used to determine the result of processing the agent. To know what exit code your agent should set, see Working with event types on page 106. If another agent is executed following the event exit code, the exit code might be overridden.
Session-based methods The Session State API gives access to storage for data which should be persistent across agent execution. Functionality is implemented through methods in the BaseAgent class. You can use the following:
Axway SecureTransport 5.3.0 Developer's Guide 44 4 Developing in-process agents
public String readSessionString (String name) public String readOptionalSessionString (String name) public void writeSessionString (String name, String value)
For more information, see the API reference.
Using this API, you can store data during execution of the first agent and read it during execution of the last agent for the same event. Or you can store data during the agent execution for event A and read data during the agent execution of event B, provided event A and B are happening during the same session.
The session state is shared between in-process and external agents. To learn about accessing the session state from an external agent, see Developing and triggering external agents on page 27.
Some session state variables are defined by built-in agents but can be used by custom agents. Those variables are defined in com.tumbleweed.st.server.api.SessionVariables. For more information, see Sessions on page 107.
Impersonation BaseAgent supports an impersonation invocation parameter. This parameter allows the agent method executeAgent to run in the security context of the particular OS user. This only works on Microsoft Windows. On UNIX-based systems, use the runas utility that allows impersonation for the external agents.
Since impersonation is implemented in BaseAgent, any agent that is implemented as a subclass of BaseAgent can be configured to run impersonated. If your custom agent accesses system resources, consider enabling impersonation in your rules.
Events class The Events class in the package com.tumbleweed.st.server.api contains definitions related to the content of events. Included are definitions of event types, as well as event environment variables and values. Environment variable names are particularly useful when writing agents to make sure you correctly specify the name when accessing an environment variable. The Events class also contains definitions for the agent exit codes.
For example, an agent executeAgent method can use the Events class to retrieve the value of a user's login name and set the exit code based on the value returned:
protected boolean executeAgent() { if("bob".equals(getEnvironmentVariable(Events.DXAGENT_LOGINNAME))) { setEventExitValue(Events.EXIT_PERMISSION_DENIED); return false; } else { setEventExitValue(Events.EXIT_OK);
Axway SecureTransport 5.3.0 Developer's Guide 45 4 Developing in-process agents
return true; } }
Logging In-process agents can use the log4j framework for flexible logging. Transaction Manager uses the log4j configuration file
Axway SecureTransport 5.3.0 Developer's Guide 46 Using the application framework 5
The following topics describe the application framework, provide a sample use case, and explain how to create and register application types:
l About the application framework on page 47 - Discusses how to develop custom applications in the context of the application framework.
l Pluggable UI overview on page 54 - Provides an overview of the Pluggable user interface.
l Creating custom applications on page 62 - Describes how to create custom applications.
l CertificateManager on page 75 - Describes the CertificateManager interface.
l Working with AccountManager on page 76 - Describes working with the AccountManager.
l Working with business units on page 81 - Describes working with business units.
l Working with data transformations on page 82 - Describes working business transformations.
l Working with ConfigurationManager on page 88 - Describes working with the ConfigurationManager.
l Working with InvocationManager on page 91 - Describes working with the InvocationManager.
l Working with NavigationManager on page 101 - Describes working with the NavigationManager.
l Working with ServiceCheck on page 104 - Describes working with the ServiceCheck.
l Working with ClusteredManager on page 105 - Describes working with the ClusteredManager.
About the application framework This topic discusses how to develop custom applications in the context of the application framework. For more information about how to use accounts, applications, and subscriptions in the Administration Tool, see the SecureTransport Administrator's Guide.
The application framework is an integral part of SecureTransport that allows development of custom applications. The custom applications integrate seamlessly with the built-in functionality. Custom applications can implement processing of data sent or received through SecureTransport to support specific business needs of an organization while allowing the administrator to specify who can use the applications, how data is transferred and how application needs to be configured.
The separation of the administration and application logic allows development of very generic applications. Some applications are provided as built-in components of SecureTransport Server such as the Standard Router, the Site Mailbox and the Basic application. For more information on the built-in applications, see the SecureTransport Administrator's Guide.
Axway SecureTransport 5.3.0 Developer's Guide 47 5 Using the application framework
The application framework facilitates custom application development by providing the following features:
l Exchanging data with accounts
l Defining an application-specific GUI integrated with the SecureTransport Administration Tool.
l Storing custom data associated with an application in SecureTransport-maintained storage.
l Using certificates stored in the SecureTransport certificate store for application purposes.
l Using the built-in scheduler for application-specific recurring tasks.
The following topics compare the application framework to using custom rules and agents alone and list the application framework key terms, classes, and interfaces:
l Using the application framework or custom rules on page 48 - Compares using the application framework to using custom rules and agents alone.
l Key terms on page 49 - Lists the application framework key terms.
l Application framework classes and interfaces on page 50 - Lists the application framework classes and interfaces.
Using the application framework or custom rules This topic compares using the application framework to using custom rules and agents alone. For example, how is a custom application different from a custom agent when using the Incoming End event? First, the application framework is not independent from custom rules and agents. In fact, creating a custom application involves creating a custom rule and custom agents.
Using the application framework has some advantages and disadvantages compared to defining custom agents and rules.
Advantages include:
l Better separation of responsibilities between a developer and SecureTransport administrator. A team of developers with different skill sets can develop and package generic data processing logic in a custom application. The application can be deployed, configured, and applied by an administrator as day-to-day business needs demand. The administrator can change how the files are sent or received by the application, what users can access the application, or when to schedule recurring application-specific tasks without having to change the application logic or change any rules.
l Better separation of custom logic and better management of different types of custom applications. When defining traditional custom rules and packages, great care must be taken not to override default processing. Also, you must manage different types of custom cases. This can lead to complicated rule conditions or implementing multiple unrelated requirements in a single agent. By comparison, the application custom rule and application custom agent are defined in such a way that the application logic must be implemented by a specific application agent allowing different types of applications to run in a single deployment without interfering with each other. None of the applications need to be aware of the presence of other applications.
Axway SecureTransport 5.3.0 Developer's Guide 48 5 Using the application framework
l Custom application administration is integrated with SecureTransport administration and can be tailored to the needs of the application. This allows the application to provide a user-friendly configuration interface. By comparison, custom agents and rules are configured using the generic rule editor interface.
l Custom applications are provided with custom storage for the configuration data, but custom agents have to either rely on parameters passed in the rules or define a separate storage component.
l The application framework allows SecureTransport administrators to define a schedule for recurring application tasks through a user interface in the Administration Tool.
l The application framework allows custom applications to take advantage of the built-in SecureTransport Certificate Management. For example, an application can request usage of a certificate associated with the account subscribed to the application.
Disadvantages include:
l Applications cannot be used for all customization types. For example, an application cannot be used to implement Single Sign On (SSO).
l Custom applications must follow the design rule imposed by the application framework. If the application framework design does not address a particular use case, other custom rules and agents might have to be used. For example, one such limitation is when a user uploads a file, the application that processes the file is determined based on which directory the file is uploaded into. If custom processing should be triggered by a file name or extension, regardless of the directory the file is uploaded into, a general custom rule must be used.
Key terms The following application framework concepts are relevant to custom application development:
l Application type – An application type identifies what processes the custom application performs. Developing a custom application consists of defining the application type and implementing the components required for the application type to function.
l Application instance – An application instance is created by the SecureTransport administrator based on the application type. An administrator can create multiple instances of the same application type and provide different configuration settings and subscriptions for each instance.
l Application events – Events designed to trigger application processing. These events should be handled by an application agent. For example, when data arrives in a folder, an event can trigger the application.
l Application agent – An agent designed to implement the application logic. The agent is created by the custom application developer. You can choose to create a single agent to handle all types of application events or create several agents. An application agent handles application events associated with the application instances of a particular application type.
l Application rule – A rule that triggers the application agent for the application events associated with the application type.
Axway SecureTransport 5.3.0 Developer's Guide 49 5 Using the application framework
l Application attributes – A set of attributes associated with the application instance. The custom application developer defines the kinds of attributes applicable to the given application type. The SecureTransport administrator through the developer-provided UI chooses the values for the attributes when configuring the application instance.
l Subscription – A persistent object maintained by SecureTransport that links an account with an application instance. Subscription objects are used to represent user account subscriptions to the applications. A SecureTransport administrator can subscribe multiple user accounts to the application instance. Subscription objects are also used to represent the application instance connection to a service account. The custom application developer defines how many service accounts the custom application needs and what purpose each service account serves. A SecureTransport administrator subscribes the service accounts when creating the application instance.
l Application-specific subscription attributes – A set of attributes associated with the User Account subscriptions whose meaning is specific to the application type the subscription is used for. The developer of the custom application defines the kinds of attributes applicable to the given application type. The system administrator provides the values for these attributes when configuring the subscription. This enables the application to associate some custom data with each user subscription. For example, a banking application can use this mechanism to associate a bank account number with the user subscription.
l Transfer configuration – Part of a subscription describing how files are sent or received through the subscription. Transfer configurations include an identifying tag. Subscriptions to user accounts have two transfer configurations: one for sending files to the user and one for receiving files from the user. These transfer configurations are identified by the tags Partner-Out and Partner-In. Subscriptions to the service account have one transfer configuration. The custom application developer must define the tag for the transfer configuration.
l Application schedule – A persistent object maintained by SecureTransport that defines a schedule for a recurring application-specific task. Application schedules have an identifying tag. The custom application developer defines one or more recurring tasks for an application and assigns a tag to each task. The SecureTransport administrator defines how often each task is performed when creating the application instance.
Application framework classes and interfaces The Application Framework offers a number of java classes and interfaces located in the package com.tumbleweed.st.server.api. The API reference in the SDK contains information on the classes and interfaces. The following topics provide a brief introduction:
l Factory on page 51
l Managers on page 51
l Persistent objects on page 52
l ID interfaces on page 52
l Criterion interfaces on page 53
Axway SecureTransport 5.3.0 Developer's Guide 50 5 Using the application framework
l ApplicationRuntime on page 53
l Data handlers on page 54
Factory A factory class that represents the entry point for the SecureTransport Server API. The factory is used to get the instances of specific components, such as managers. The Factory method getInstance is used to get the instance of the Factory class itself.
Managers Manager interfaces allow the use or manipulation of persistent objects maintained in the SecureTransport store. The following manager interfaces are available:
l AccountManager – creates, modifies, deletes, and searches accounts. This manager also contains a method related to authenticating accounts. For more information, see Working with AccountManager on page 76.
l AdministratorManager – creates, updates, deletes and lists administrators.
l ApplicationManager – creates, modifies, deletes, and searches subscriptions and application configurations. For example, the application agent can get the list of all user account subscriptions for a particular application instance. For more information, see Using ApplicationManager on page 69.
l BusinessUnitManager – creates, modifies, deletes, and searches business units. For more information, see Working with business units on page 81.
l CertificateManager – creates, modifies, deletes, and searches information about the certificates in the SecureTransport certificate store. For more information, see CertificateManager on page 75.
l ClusterManager – administers cluster management.
l ConfigurationManager – manipulates server configuration options and export rules. For more information, see Working with ConfigurationManager on page 88.
l Dmz*Manager – manage network zones, SecureTransport Edge configuration including IP addresses and protocols.
l InvocationManager – executes tasks on all nodes in a cluster. For more information, see Working with InvocationManager on page 91.
l LdapManager – manipulates LDAP domains and servers.
l MailTemplateManager – manipulates mail templates.
l NavigationManager – creates, updates, and deletes menus, pages, and navigation menus. For more information, see Working with NavigationManager on page 101.
l ResubmitManager – manages resubmitting failed transfers and canceling new attempts.
l ServerControllerManager – starts, stops, enables, and disables SecureTransport service. (To check if a service is functional, see Working with ServiceCheck on page 104.)
Axway SecureTransport 5.3.0 Developer's Guide 51 5 Using the application framework
l StPackageManager – stores, retrieves, and lists ad hoc file transfer packages.
l UserClassManager – creates, updates, deletes,and lists user classes.
Note SecureTransport uses a database to store persistent objects. The database schema used to store objects is subject to change in future releases. Avoid writing custom agents that rely directly on the database schema.
Persistent objects SecureTransport maintains a number of objects in its store. These interfaces provide access to the information stored in the those objects. The interfaces have getters to retrieve the information in the fields and setters for the fields that can be modified. Please note that invoking a setter method does not change the object in the persistent store. It simply modifies the in-memory copy of the object. Objects are modified persistently by either calling a manager method to modify an account object or by implementing a data handler. The persistent objects include:
l Account – represents a user or service account.
l Application – represents an application instance.
l CertificateReference – a reference to a certificate in the SecureTransport certificate store. Custom applications can use certificates from the SecureTransport certificate store. The certificate reference can be a part of the application attributes or application-specific subscription attributes. You need to define the number, type, and purpose of the certificates used by the application. The SecureTransport administrator chooses a specific certificate when configuring the application instance or user account subscription.
l CertificateDetails – represents detailed information about certificates such as expiration time and certificate data.
l Subscription – represents user or service account subscriptions to the application.
l CustomAttributes – represents application-specific attributes for an application instance or subscription. Custom attributes are designed to hold application-specific values. There are three types of custom attributes:
o Binary data – unstructured data. For example, it can be used to store application configuration in XML format.
o Properties – name/value pairs.
o Certificate References – named references to certificates.
ID interfaces The API includes ID interfaces a program can use to identify a persistent object uniquely. The ID interfaces available in the API are:
l Account.Id
l Application.Id
l BusinessUnit.Id
l CertificateReference.Id
Axway SecureTransport 5.3.0 Developer's Guide 52 5 Using the application framework
l CertificateRequest.Id
l DataTransformation.Id
l Site.Id
l SiteTemplate.Id
l Subscription.Id
l TransferConfiguration.Id
l User.Id
The other interfaces include methods to get the ID of an object, to get an object from its ID, and as a parameter to identify an object. For an example of the use of an ID object, see the example code in Using ApplicationManager on page 69.
Criterion interfaces Criterion is a special group of interfaces that define search criteria when looking for a persistent object. A criterion instance is obtained through the corresponding manager interface. Methods from the criterion interface are used to place conditions to determine the objects that should be returned. Each method invocation places a condition on a particular field of the object. the object must match the conditions on all fields. Placing a condition on the same field twice adds another condition to that field; it does not replace the previous condition. A manager interface has methods that return the list of objects matching the criterion. Typically, there is an option to retrieve a certain number of matching objects starting from a given offset to allow processing of a large number of matched objects. The criterion interfaces available in the API are:
l AccountCriterion – Used in AccountManager to filter and sort account searches.
l BusinessUnitCriterion – Used in BusinessUnitManager to filter and sort business unit searches.
l CertificateReferenceCriterion – Used in CertificateManager to filter and sort certificate searches.
l SiteCriterion – Used in AccountManager to filter and sort site searches.
l SiteTemplateCriterion – Used in AccountManager to filter and sort site template searches.
l SubscriptionCriterion – Used in ApplicationManager to filter and sort site subscription searches.
l TransferConfigurationCriterion – Used in ApplicationManager to filter and sort transfer configuration searches.
For an example of using a criterion object, see Using ApplicationManager on page 69.
ApplicationRuntime A Java interface implemented by SecureTransport and used by the application agent to get information about the application instance the agent is invoked to handle, send or request files to and from subscribed users, and perform other operations.
Axway SecureTransport 5.3.0 Developer's Guide 53 5 Using the application framework
Data handlers Data handlers are interfaces implemented by you to convert configuration data between the user interface and persistent object. For more information, see Pluggable UI overview on page 54. The API defines six data handler interfaces:
l ApplicationHandler – Customizes the application instance.
l ApplicationUpdateHandler – Extends ApplicationHandler to add methods that are called before and after an application instance is updated.
l DataTransformationHandler – Parses data associated with a data transformation.
l SiteHandler – Parses data associated with a site.
l SiteTemplateHandler – Parses data associated with a site template.
l SubscriptionHandler – Supports application-specific subscription attributes.
For more information, see Implementing data handlers on page 57.
Pluggable UI overview The pluggable UI is a part of the application framework that enables development of a custom user interface (UI) integrated with the built-in functionality in the Administration Tool. There are two types of custom UI pages: the Application UI which defines the UI for application instance settings and the Subscription UI which defines application-specific subscription settings
The following elements are involved in developing custom UI pages:
l Custom JSP Files – A Java Server Page (JSP) or JSP document (JSPX) used to display custom settings.
l Data Handler – The Java class accompanying the JSP to convert the settings from the UI to a persistent object or from the persistent object to the UI.
l CustomBean – A JavaBean used to exchange information between the data handler and the JSP page.
The following topics
l Custom JSP files on page 54 - Describes the custom JSP files.
l Implementing data handlers on page 57 - Provides how to instructions for implementing data handlers.
Custom JSP files JSP files provide a way for developers to include Java code in a web page. For SecureTransport, JSP files are used to provide a UI for your custom types. SecureTransport uses the pluggable UI framework to interact with the JSP and display the UI. Most of the code in the JSP uses XML tags.
Axway SecureTransport 5.3.0 Developer's Guide 54 5 Using the application framework
The main purpose of the custom JSP file is to display the form elements for custom settings. The values for the settings are prepared by a data handler and are made available to the JSP through the customBean object. In a typical J2EE web application JSPs are used to provide the content for the entire web page. However, the custom page is displayed within a built-in page and provides just the form fields for the custom settings. Also, the application framework can display multiple custom JSP files in the same web page. Due to these criteria, some rules for custom JSP pages must be followed:
l Pages cannot contain ,
, or