Upload
others
View
33
Download
0
Embed Size (px)
Citation preview
iWay Service Manager ComponentReference GuideVersion 8.0 and Higher
September 17, 2018
Active Technologies, EDA, EDA/SQL, FIDEL, FOCUS, Information Builders, the Information Builders logo, iWay, iWaySoftware, Parlay, PC/FOCUS, RStat, Table Talk, Web390, WebFOCUS, WebFOCUS Active Technologies, and WebFOCUSMagnify are registered trademarks, and DataMigrator and Hyperstage are trademarks of Information Builders, Inc.
Adobe, the Adobe logo, Acrobat, Adobe Reader, Flash, Adobe Flash Builder, Flex, and PostScript are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.
Due to the nature of this material, this document refers to numerous hardware and software products by theirtrademarks. In most, if not all cases, these designations are claimed as trademarks or registered trademarks by theirrespective companies. It is not this publisher's intent to use any of these names generically. The reader is thereforecautioned to investigate all claimed trademark rights before using any of these names other than to refer to the productdescribed.
Copyright © 2018, by Information Builders, Inc. and iWay Software. All rights reserved. Patent Pending. This manual, orparts thereof, may not be reproduced in any form without the written permission of Information Builders, Inc.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Help Us to Serve You Better . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
User Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
iWay Software Training and Professional Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1. iWay Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Services Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Available Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Accum EOS Agent (com.ibi.agents.XDAccumEOSAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Accumulates Document Iterations (com.ibi.agents.XDAccumIterAgent). . . . . . . . . . . . . . . . . .30
Activity Log Business Error Message (com.ibi.agentsXDXALogBizErr). . . . . . . . . . . . . . . . . . . 31
Activity Log Control Service (com.ibi.agents.XDXalogControlAgent). . . . . . . . . . . . . . . . . . . . . 33
Activity Log Entry Service (com.ibi.agents.XDXALogEvent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Add Attachment From File Service (com.ibi.agents.XDAddAttachmentFromFileAgent). . . . . . 37
Add Attachment Service (com.ibi.agents.XDAddAttachmentAgent). . . . . . . . . . . . . . . . . . . . . .40
Add Correl Entry Service (com.ibi.agents.XDAddCorrelEntryAgent). . . . . . . . . . . . . . . . . . . . . . 42
Alt Route IP Service (com.ibi.agents.XDAltRouteIP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Append Stream to File Service (com.ibi.agents.XDFileAppendAgent). . . . . . . . . . . . . . . . . . . . 44
AQ Emit Service (com.ibi.agents.XDAQEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
AS2 Nonblocking Emit Service (com.ibi.agents.XDNAS2EmitAgent). . . . . . . . . . . . . . . . . . . . .49
AS 1 Emit Service (com.ibi.agents.AS1EmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
AS 2 Emit Service (com.ibi.agents.AS2EmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
AS 2 Nonblocking Send MDN Service (com.ibi.agents.XDMDNSendNowAgent). . . . . . . . . . . 65
Attachment Iterator Service (com.ibi.agents.XDIterAttachments). . . . . . . . . . . . . . . . . . . . . . . 66
Attachment Operations Service (com.ibi.agents.XDAttachOps). . . . . . . . . . . . . . . . . . . . . . . . .68
Attachment to Document Service (com.ibi.agents.XDAttachmentToDocAgent). . . . . . . . . . . .69
Attachment to File Service (com.ibi.agents.XDAttachmentToFileAgent). . . . . . . . . . . . . . . . . . 71
Authenticate/Impersonate Service (com.ibi.agents.XDPrincipalAgent). . . . . . . . . . . . . . . . . . 73
BAM Receiver Service (com.ibi.agents.BAMReceiver). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Base64 Operation Service (com.ibi.agents.XDBase64Agent). . . . . . . . . . . . . . . . . . . . . . . . . . 76
iWay Service Manager Component Reference Guide 3
Bearer Token Agent Service (com.ibi.agents.XDBearerTokenAgent). . . . . . . . . . . . . . . . . . . . .78
Blank Elimination Service (com.ibi.agents.XDBlankWalk). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Cancel Service (com.ibi.agents.XDCancelAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Catch Service (com.ibi.agents.XDCatchAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Channel Information Service (com.ibi.agents.XDChanInfoAgent). . . . . . . . . . . . . . . . . . . . . . . 89
Check Schema Service (com.ibi.agents.XDCheckSchema). . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Commit or Rollback within a Flow (com.ibi.agents.XDCommitAgent). . . . . . . . . . . . . . . . . . . . 96
Constant Service (com.ibi.agents.XDConstantAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Controls Listeners Service (com.ibi.agents.XDControlAgent). . . . . . . . . . . . . . . . . . . . . . . . . 100
Control Activity Log Exit Service (com.ibi.agents.XDXalogControlAgent). . . . . . . . . . . . . . . . 103
Cookie Store Agent Service (com.ibi.agents.XDCookieStoreAgent). . . . . . . . . . . . . . . . . . . . 104
Correl Inquiry By State Service (com.ibi.agents.XDCorrelInquiryByStateAgent). . . . . . . . . . .105
Correl Inquiry Service (com.ibi.agents.XDCorrelInquiryAgent). . . . . . . . . . . . . . . . . . . . . . . . . 107
Correl Set Inquiry Service (com.ibi.agents.XDCorrelSetInquiryAgent). . . . . . . . . . . . . . . . . . .108
C Char Filter Service (com.ibi.agents.CCharFilter). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Cross-Origin Resource Sharing Service (com.ibi.agents.XDCorsAgent). . . . . . . . . . . . . . . . . 111
Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Data Quality Center Service (Non-Pooling, Deprecated) (com.ibi.agents.XDDQAgent). . . . .117
Deflate Service (com.ibi.agents.XDDeflateAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Deidentification Service (com.ibi.agents.XDDeidentifyAgent). . . . . . . . . . . . . . . . . . . . . . . . . 119
Delete an Item (com.ibi.agents.XDDynamoDBDeleteItem). . . . . . . . . . . . . . . . . . . . . . . . . . . 128
destroy status Service (com.ibi.agents.XDTwitterDestroyStatus). . . . . . . . . . . . . . . . . . . . . . 130
Document Copy Service (com.ibi.agents.XDCopyAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Document Insert Service (com.ibi.agents.XDDocInsertAgent). . . . . . . . . . . . . . . . . . . . . . . . .133
Example 1: Charter Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Example 2: Creating the Parent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Example 3: Inserting an Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Example 4: Inheriting XML Namspaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Document state modification Service (com.ibi.agents.XDDocAgent). . . . . . . . . . . . . . . . . . . 140
Document Update Service (com.ibi.agents.XDDocUpdateAgent). . . . . . . . . . . . . . . . . . . . . . 141
Example 1: Find/Replace Then Build Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Example 2: Build Document Then Find/Replace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Example 3: Only Find/Replace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Contents
4 Information Builders
Example 4: Only Build Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Example 5: Find/Replace Then Build Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Example 6: Build Document Then Find/Replace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Example 7: Only Find/Replace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Example 8: Only Build Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Document to Attachment Service (com.ibi.agents.XDAttachmentFromDocAgent). . . . . . . . 154
DQC Batch Executor Service (com.ibi.agents.XDDQBatchExec). . . . . . . . . . . . . . . . . . . . . . . 156
DQC/MDC Flow Linkage Service (com.ibi.agents.MdcAgentISM). . . . . . . . . . . . . . . . . . . . . . 157
Data Quality Center Service (Document-Driven, Pooling) (com.ibi.agents.XDDQAgent2). . .159
Configuring Data Quality Runtime Providers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Data Quality Center Service (User Parameter-Driven, Pooling)
(com.ibi.agents.XDDQAgent2UserParm). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Using the Data Quality Center Service (User Parameter-Driven, Pooling). . . . . . . . . . 165
EDI Accumulator Service (com.ibi.agents.EDIAccumulator). . . . . . . . . . . . . . . . . . . . . . . . . . . 168
EDI Rule Router Service (com.ibi.agents.XDRuleRouterAgent). . . . . . . . . . . . . . . . . . . . . . . . 169
EDIFACTAckAgent (com.ibi.agents.XDEDIFACTAckAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
EDIFACT ValidationReportAgent (com.ibi.agents.XDEDIFACTValidationReportAgent). . . . . .171
EDIHL7AckAgent (com.ibi.agents.XDEDIHL7AckAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
EDIHL7 ValidationReport Agent (com.ibi.agents.XDEDIHL7ValidatioReportAgent). . . . . . . . 173
EDIWrapperAgent Service (com.ibi.agents.EDIWrapperAgent). . . . . . . . . . . . . . . . . . . . . . . . .174
EDIX12TransformAgent Service (com.ibi.agents.XDEDITransformAgent). . . . . . . . . . . . . . . .175
EDIX12AckAgent Service (com.ibi.agents.XDX12AckAgent). . . . . . . . . . . . . . . . . . . . . . . . . . .176
Email Emit Service (com.ibi.agents.XDEmailEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Entag Service (com.ibi.agents.XDEntagAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
Ethereum Call Agent Service (com.ibi.agents.XDEthereumCallAgent). . . . . . . . . . . . . . . . . . 183
Ethereum Call Constant Function Agent Service
(com.ibi.agents.XDEthereumCallConstantAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Ethereum Deploy Agent Service (com.ibi.agents.XDEthereumDeployAgent). . . . . . . . . . . . . 186
Ethereum Transfer Agent Service (com.ibi.agents.XDEthereumTransferAgent). . . . . . . . . . 187
Excel reader Service (com.ibi.agents.XDReadExcel). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Execute ETL Service (com.ibi.agents.XDETLAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Fail Service (com.ibi.agents.XDFailAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192
File Accumulator Service (com.ibi.agents.XDFileAccumAgent). . . . . . . . . . . . . . . . . . . . . . . . 195
Contents
iWay Service Manager Component Reference Guide 5
File Append Accumulation (com.ibi.agents.XDFileAppendAgent). . . . . . . . . . . . . . . . . . . . . . .197
File Directory Contents Service (com.ibi.agents.XDFileDirListAgent). . . . . . . . . . . . . . . . . . . 198
File Emit Service (com.ibi.agents.XDFileEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
File operations Service (com.ibi.agents.XDPFFileOpsAgent) . . . . . . . . . . . . . . . . . . . . . . . . . .206
File read (com.ibi.agents.XDPFFileReadAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208
File Read Service (com.ibi.agents.XDFileReadAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Form Data Agent Service (com.ibi.agents.XDFormDataAgent). . . . . . . . . . . . . . . . . . . . . . . . .213
FTP and SFTP Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
HTTP Client Service (com.ibi.agents.XDNHttpEmitWithOAuth). . . . . . . . . . . . . . . . . . . . . . . . .215
HTTP Cookie Agent Service (com.ibi.agents.XDCookieAgent). . . . . . . . . . . . . . . . . . . . . . . . . 219
HTTP Client Pool Manager Service (com.ibi.agents.XDHttpClientManager). . . . . . . . . . . . . .221
HTTP Emit Service (com.ibi.agents.XDHTTPEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
HTTP Nonblocking Emit Service (com.ibi.agents.XDNHttpEmitAgent). . . . . . . . . . . . . . . . . . .227
HTTP Read Service (com.ibi.agents.XDHTTPReadAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
HTTP ReST Routing Service (com.ibi.agents.XDReSTRouteAgent). . . . . . . . . . . . . . . . . . . . . 236
HTTP Session Invalidator Agent Service (http_session_invalidator_agent). . . . . . . . . . . . . . 238
Hyperledger Fabric Key History Agent Service (com.ibi.agents.XDFabricKeyHistoryAgent). 239
Hyperledger Fabric Query Agent Service (com.ibi.agents.XDFabricQueryAgent). . . . . . . . . . 240
Hyperledger Fabric Query Block Agent Service
(com.ibi.agents.XDFabricQueryBlockAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Hyperledger Fabric Transaction Agent Service (com.ibi.agents.XDFabricAgent). . . . . . . . . . 243
IEI Feed Agent Service (com.ibi.agents.IEIFeedAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Inflate Service (com.ibi.agents.XDInflateAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Inserts data inside an XML document Service (com.ibi.agents.XDDocInsertAgent). . . . . . .248
Insert SAML Assertion Service (com.ibi.agents.XDInsertSAMLAssertionAgent). . . . . . . . . . 250
Insert WSSE Timestamp Service (com.ibi.agents.XDInsertWSSETimestampAgent). . . . . . .251
Insert WSSE Token Service (com.ibi.agents.XDInsertWSSETokenAgent). . . . . . . . . . . . . . . 251
Internal Emit Service (com.ibi.agents.XDInternalEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . 251
Is Reachable Service (com.ibi.agents.XDIsReachable). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
iWay Adapter (com.ibi.agents.XDAdapterAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Using iWay Functional Language With Adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
JDBC Service (com.ibi.agents.XDJdbcAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
JDBC via iWay JNDI Datasource Service (com.ibi.agents.XDJdbcDSAgent). . . . . . . . . . . . . .271
Contents
6 Information Builders
JMSQ Browse Service (com.ibi.agents.XDJMSBrowse). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
JMSQ Emit Service (com.ibi.agents.XDJMSQEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
JMS Read Agent (com.ibi.agents.XDJMSReadAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
JSON Conversion Service (com.ibi.agents.XDJSONAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
iWay JSON to XML Transformation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
iWay XML to JSON Transformation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
iWay Transformation Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
iWay Transformation XPath Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
Standard JSON to XML Transformation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Standard XML to JSON Transformation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Standard Transformation Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Standard Transformation XPath Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
JSON Insertion Service (com.ibi.agents.XDJsonInsertAgent). . . . . . . . . . . . . . . . . . . . . . . . . .291
LDAP Reader Service (com.ibi.agents.LDAPReader). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Legacy Record to XML Converter Service (com.ibi.agents.XDLegacyRecordToXMLAgent). .294
Using the Copybook Option File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
Additional Usage Examples for the Copybook Option File. . . . . . . . . . . . . . . . . .301
Local Master Service (com.ibi.agents.LocalMasterAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Mail Attach Service (com.ibi.agents.XDMailAttachAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Mark Attach Service (com.ibi.agents.XDMarkAttachAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Marshall Service (com.ibi.agents.XDMarshallAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306
MLLP Emit Service (com.ibi.agents.XDMLLPEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .308
Move Service (com.ibi.agents.XDMoveAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
MQ Emit Service (com.ibi.agents.XDMQEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
MQ JMS Emit Agent Service (com.ibi.agents.XDMQJMSEmitAgent). . . . . . . . . . . . . . . . . . . . 312
MQ Read Service (com.ibi.agents.XDMQReadAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
MQTT Emit Agent Service (com.ibi.agents.XDMqttEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . .316
MSMQ Emit Service (com.ibi.agents.XDMSMQEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . .318
MTOM Service (com.ibi.agents.XDMTOMAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Node Set Extract Service (com.ibi.agents.XDNodeSetExtractAgent). . . . . . . . . . . . . . . . . . . 322
NTCP Emit Agent Service (com.ibi.agents.XDNTCPEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . 323
NTCP Client Write Agent Service (com.ibi.agents.XDNTCPClientWriteAgent). . . . . . . . . . . . .325
NTCP Emit Agent Service (com.ibi.agents.XDNTCPEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . 326
Contents
iWay Service Manager Component Reference Guide 7
NTCP Read Agent Service (com.ibi.agents.XDNTCPReadAgent). . . . . . . . . . . . . . . . . . . . . . . 328
NTCP Respond Agent Service (com.ibi.agents.XDNTCPRespondAgent). . . . . . . . . . . . . . . . .330
OAuth 1.0 Authentication Service (com.ibi.agents.XDOAuth1Agent). . . . . . . . . . . . . . . . . . . 331
OAuth 2.0 Authentication Service (com.ibi.agents.XDOAuth2Agent). . . . . . . . . . . . . . . . . . . 332
OpenRules Decision Service (com.ibi.agents.XDOpenRulesDecisionAgent). . . . . . . . . . . . . 333
Parallel Execution: Counted iteration Service (com.ibi.agents.XDParallelCountAgent). . . . 334
Parallel Execution: JSON iteration Service (com.ibi.agents.XDParallelJsonSplitAgent). . . . 335
Parallel Execution: XML iteration Service (com.ibi.agents.XDParallelXMLSplitAgent). . . . . 337
Parse to XML Service (com.ibi.agents.XDToXML). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
PDF Form Field Reader Service (com.ibi.agents.XDPdfFormFieldReader). . . . . . . . . . . . . . . 341
PF File Operations Service (com.ibi.agents.XDPFFileOpsAgent). . . . . . . . . . . . . . . . . . . . . . . 341
PF File Read Service (com.ibi.agents.XDPFFileReadAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . 343
PGP Decryption and Verification Service (com.ibi.agents.PGPDecryptAgent). . . . . . . . . . . . 345
PGP Encryption and Signature Service (com.ibi.agents.PGPEncrypt). . . . . . . . . . . . . . . . . . . 346
PGP Sign Only Service (com.ibi.agents.XDPGPSignAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
PGP Verify Signature Only Service (com.ibi.agents.XDPGPVerifySignAgent). . . . . . . . . . . . . 351
Preemitter in Flow Service (com.ibi.agents.XDPreemitAgent). . . . . . . . . . . . . . . . . . . . . . . . . 352
Print Emit Service (com.ibi.agents.XDPrintEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Properties File Updater Service (com.ibi.agents.XDPropertyUpdater). . . . . . . . . . . . . . . . . . .355
Protocol Business Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
P Flow Service (com.ibi.agents.XDPFlowAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
P Flow Test Service (com.ibi.agents.XDPFlowTestAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
QA Service (com.ibi.agents.XDQAAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
RabbitMQ Emit Service (com.ibi.agents.XDRabbitMQEmitAgent). . . . . . . . . . . . . . . . . . . . . . 363
RabbitMQ Read Service (com.ibi.agents.XDRabbitMQReadAgent). . . . . . . . . . . . . . . . . . . . . 367
Route Service (com.ibi.agents.XDRouteAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Rule Router Service (com.ibi.agents.XDRuleRouterAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . .372
Run OS Shell Command Service (com.ibi.agents.XDRunCmdAgent). . . . . . . . . . . . . . . . . . . 373
RVI Relay: send message to gateway service Service (com.ibi.agents.RVIRelay). . . . . . . . 377
RVI Response: return iterations to the RVI Iterator Service
(com.ibi.agents.XDRVIGatewayAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
RVI Stream Relay Service (com.ibi.agents.RVIStreamRelay). . . . . . . . . . . . . . . . . . . . . . . . . . 379
Save/Restore Document Value Service (com.ibi.agents.XDSREGDocAgent). . . . . . . . . . . . 380
Contents
8 Information Builders
Save/Restore XML Tree Service (com.ibi.agents.XDSREGTreeAgent). . . . . . . . . . . . . . . . . . 383
Schema Validation Service (com.ibi.agents.XDSchemaValidationAgent). . . . . . . . . . . . . . . .384
Scripting Agent Service (com.ibi.agents.XDScriptingAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . 385
search Service (com.ibi.agents.XDTwitterSearch). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387
Security: Authenticate/Impersonate Service (com.ibi.agents.XDPrincipalAgent). . . . . . . . . 391
Server Statistics Service (com.ibi.agents.XDChanInfoAgent). . . . . . . . . . . . . . . . . . . . . . . . . 392
Set Document State (com.ibi.agents.XDDocAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Set special registers Service (com.ibi.agents.XDSREGAgent). . . . . . . . . . . . . . . . . . . . . . . . .395
SFTP Connection Cache Service (com.ibi.agents.XDSFTPConnectionCacheAgent). . . . . . . 397
SFTP Direct Transfer Service (com.ibi.agents.XDSFTPDirectFileTransfer). . . . . . . . . . . . . . . 399
SFTP Emit Agent Service (com.ibi.agents.XDSFTPEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . 402
SFTP File Ops Agent Service (com.ibi.agents.XDSFTPFileOpsAgent). . . . . . . . . . . . . . . . . . . 405
SFTP Read Agent Service (com.ibi.agents.XDSFTPReadAgent). . . . . . . . . . . . . . . . . . . . . . . . 408
show status Service (com.ibi.agents.XDTwitterShowStatus). . . . . . . . . . . . . . . . . . . . . . . . . .411
SMIME Packer Agent Service (com.ibi.agents.XDSMIMEPackerAgent). . . . . . . . . . . . . . . . . 413
SMIME Unpacker Agent Service (com.ibi.agents.XDSMIMEUnpackerAgent). . . . . . . . . . . . .415
Snip Service (com.ibi.agents.XDSnipAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Sonic Emit Service (com.ibi.agents.XDSonicEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
Sonic Queue Browser Service (com.ibi.agents.XDSonicBrowseAgent). . . . . . . . . . . . . . . . . .424
Sonic Read Service (com.ibi.agents.XDSonicReadAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Split Service (com.ibi.agents.XDSplitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428
Split To MQ Service (com.ibi.agents.XDSplitToMQAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
SP Router Service (com.ibi.agents.XDSPRouter). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .431
SQL Batch Row Insert Service (com.ibi.agents.XDSQLInsert). . . . . . . . . . . . . . . . . . . . . . . . . 432
SQL Service (com.ibi.agents.XDSQLAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Examples of Using the SQL Service With Stored Procedure Calls and Output
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Calling a Stored Procedure With Input and Output Parameters. . . . . . . . . . . . . 452
Calling a Stored Procedure With an IN OUT Parameter. . . . . . . . . . . . . . . . . . . . 454
Calling an Oracle Procedure With an Input and a Cursor Output Parameter. . .455
SREG FTP: Pass register settings to iWay FTP Server Service
(com.ibi.agents.XDNFTPSREGAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
SREG Insert Service (com.ibi.agents.XDSregInsertToDocAgent). . . . . . . . . . . . . . . . . . . . . . .460
Contents
iWay Service Manager Component Reference Guide 9
SREG Namespace Service (com.ibi.agents.XDSREGNamespaceAgent). . . . . . . . . . . . . . . . 463
SREG: Save/Restore Document Value Service (com.ibi.agents.XDSREGDocAgent). . . . . . 465
SREG: Save/Restore XML tree Service (com.ibi.agents.XDSREGTreeAgent). . . . . . . . . . . . 466
SREG Service (com.ibi.agents.XDSREGAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .468
SWIFT Out Report Service (com.ibi.agents.SWIFTOutReportAgent). . . . . . . . . . . . . . . . . . . . 474
SWIFT Transform Service (com.ibi.agents.XDSWIFTTransformAgent). . . . . . . . . . . . . . . . . . .475
SWIFT Validation Service (com.ibi.agents.XDSWIFTValidationReportAgent). . . . . . . . . . . . . 476
SWIFT XML Transform Service (com.ibi.agents.XDIWAYSWIFTXMLTransformAgent). . . . . . 477
TCP Emit Service (com.ibi.agents.XDTCPEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .478
TIBCO RV Emit Service (com.ibi.agents.XDTIBRVEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . 481
Trace Message Writer Service (com.ibi.agents.XDTraceAgent). . . . . . . . . . . . . . . . . . . . . . . . 484
Transaction Completion Registration Service (com.ibi.agents.XDTxAgent). . . . . . . . . . . . . . 486
Transform Service (com.ibi.agents.XDTransformAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Tree Evaluator Service (com.ibi.agents.EvalWalk). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .491
UDP Emit Service (com.ibi.agents.XDUDPEmitAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Unmarshall Service (com.ibi.agents.XDUnmarshallAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Update Correl Entry Service (com.ibi.agents.XDUpdateCorrelEntryAgent). . . . . . . . . . . . . . . 495
Uuencode (com.ibi.agents.XDUUPreEmitter). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Verify WSSE Timestamp Service (com.ibi.agents.XDWSSETimestampVerifyAgent). . . . . . . 499
Web Service Client Service (com.ibi.agents.XDWSClientAgent). . . . . . . . . . . . . . . . . . . . . . . 500
Web Service HTTP Client Service (com.ibi.agents.XDWSHttpClientAgent). . . . . . . . . . . . . . .503
X12 Validation Service (com.ibi.agents.XDX12ValidationReportAgent). . . . . . . . . . . . . . . . . 506
XA Log Inquiry By Context Service (com.ibi.agents.XDXALogInquiryByContextAgent). . . . . .507
XA Log Inquiry By Date Service (com.ibi.agents.XDXALogInquiryByDateAgent). . . . . . . . . . . 508
XA Log Inquiry By Partner Service (com.ibi.agents.XDXALogInquiryByPartnerAgent). . . . . . 509
XA Log Inquiry By Transaction ID Service (com.ibi.agents.XDXALogInquiryByTIDAgent). . . .510
XA Log Message Service (com.ibi.agents.XDXALogMsg). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
XAdES Digital Signature Create Service (com.ibi.agents.XDXAdESCreateAgent). . . . . . . . . 513
XAdES Digital Signature Verify Service (com.ibi.agents.XDXAdESVerifyAgent). . . . . . . . . . . 521
XDTwitterGetHomeTimeline Service (com.ibi.agents.XDTwitterGetHomeTimeline). . . . . . . .524
XDTwitterUpdateStatus Service (com.ibi.agents.XDTwitterUpdateStatus). . . . . . . . . . . . . . .526
xCal and iCalendar Conversion Service (com.ibi.agents.XDXCalAgent). . . . . . . . . . . . . . . . . 529
Example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .532
Contents
10 Information Builders
Example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .541
XML Decryption Service (com.ibi.agents.XDXMLDecryptionAgent). . . . . . . . . . . . . . . . . . . . . 541
XML Digital Signature Create Service (com.ibi.agents.XDXMLDSigCreateAgent). . . . . . . . . 543
XML Digital Signature Verify Service (com.ibi.agents.XDXMLDSigVerifyAgent). . . . . . . . . . . 544
XML Encryption Service (com.ibi.agents.XDXMLEncryptionAgent). . . . . . . . . . . . . . . . . . . . . .544
XML Extract Service (com.ibi.agents.XDXMLExtract). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .549
XMLtoEDIFACTTransformAgent Service (com.ibi.agents.XMLToEDIFACTTransformAgent). .550
XMLtoEDIHL7TransformAgent Service (com.ibi.agents.XMLtoEDIHL7TransformAgent). . . .552
XMLtoHIPAATransformAgent Service (com.ibi.agents.XMLToHIPAATransformAgent). . . . . . 553
XMLtoX12TransformAgent Service (com.ibi.agents.XMLToX12TransformAgent). . . . . . . . . 555
XQuery Expression Evaluation (com.ibi.agents.XDXQueryAgent). . . . . . . . . . . . . . . . . . . . . . .558
External Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Zip Out Service (com.ibi.agents.XDZipOutAgent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .566
Parallel Control Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
Cancellation Concerns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .573
Developer Cautions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
XDParallelCountAgent Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .574
XDParallelJsonSplitAgent Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
XDParallelXMLSplitAgent Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
2. iWay Preparsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Preparser Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Available Preparsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Append Preparser (com.ibi.preparsers.XDAppend). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
C Char Filter Preparser (com.ibi.preparsers.CCharFilter). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Char Repl Preparser (com.ibi.preparsers.XDCharRepl). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .585
Cross-Origin Resource Sharing Preparser (com.ibi.preparsers.XDCorsPreparser). . . . . . . . 586
EDIFACTPreParser (com.ibi.preparsers.XDEDIFACTPreParser). . . . . . . . . . . . . . . . . . . . . . . . .587
EDIH7PreParser (com.ibi.preparsers.XDEDIHL7PreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . 587
EDIX12PrePreparser (com.ibi.preparsers.XDEDIpreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . 587
EDIX12 XML Validator (com.ibi.preparsers.XDXMLEDIValidator). . . . . . . . . . . . . . . . . . . . . . .588
En Tag Preparser (com.ibi.preparsers.XDEnTag). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
Error Filter Preparser (com.ibi.preparsers.ErrorFilter). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Contents
iWay Service Manager Component Reference Guide 11
Excel Preparser (com.ibi.preparsers.XDExcelpreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .591
ExtractPreparser (com.ibi.preparsers.XDExtractPreparser). . . . . . . . . . . . . . . . . . . . . . . . . . . 594
HIPAAPreParser (com.ibi.preparsers.XDHIPAAPreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . . .599
HTTP Preparser (com.ibi.preparsers.XDHTTPpreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599
Inflate Preparser (com.ibi.preparsers.XDInflate). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
JMS Object Preparser (com.ibi.preparsers.XDJMSObjectPreParser). . . . . . . . . . . . . . . . . . . .601
Legacy Record Preparser (com.ibi.preparsers.LegacyRecordPreparser). . . . . . . . . . . . . . . . 602
Multipart Preparser (com.ibi.preparsers.XDMultiPart). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
Multipart for nHTTP Preparser (com.ibi.preparsers.XDMultiPartForNHTTP). . . . . . . . . . . . . . 605
PGP Decrypt Preparser (com.ibi.preparsers.PGPDecrypt). . . . . . . . . . . . . . . . . . . . . . . . . . . . .606
PGP Verify Signiture Only (com.ibi.preparsers.XDPGPVerifySignPreparser). . . . . . . . . . . . . . 607
Replace characters on a one for one basis Preparser (com.ibi.preparsers.XDCharRepl). . 607
Smime Preparser (com.ibi.smime.XDSmimePreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
SOAP Preparser (com.ibi.preparsers.XDSOAPPreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
SREG Preparser (com.ibi.preparsers.XDSREGPreparser). . . . . . . . . . . . . . . . . . . . . . . . . . . . .609
SWIFTPreParser (com.ibi.preparsers.SwiftPreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
SWIFTAckPreParser (com.ibi.preparsers.SwiftBPP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .611
SWIFTSystemMessagePreParser (com.ibi.preparsers.XDSWIFTSysMsgPreParser). . . . . . . 612
Transform Preparser (com.ibi.preparsers.XDTransformPP). . . . . . . . . . . . . . . . . . . . . . . . . . . 612
Unmarshalls a message Preparser (com.ibi.preparsers.XDUnmarshall). . . . . . . . . . . . . . . . 613
XDSWIFTPreParser (com.ibi.preparsers.XDSWIFTpreParser). . . . . . . . . . . . . . . . . . . . . . . . . . 613
Streaming Preparsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Concatenated XML Document Stream Preparser
(com.ibi.preparsers.XDXMLStreamPreParser). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Create Stream Doc PP (com.ibi.preparsers.CreateStreamDocPP). . . . . . . . . . . . . . . . . . . . . 615
Delimited Value Stream Preparser (com.ibi.preparsers.XDDelValStream). . . . . . . . . . . . . . 616
Flat Stream Preparser (com.ibi.preparsers.XDFlatStreamPreParser). . . . . . . . . . . . . . . . . . . 618
Stream Passthrough (com.ibi.preparsers.XDStreamPassthrough). . . . . . . . . . . . . . . . . . . . . 620
Splitter Preparsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
Delimited Value Splitter Preparser (com.ibi.preparsers.XDDelVal). . . . . . . . . . . . . . . . . . . . . 621
EDIBatchSplitter Preparser (com.ibi.preparsers.XDEDIBatchSplitter). . . . . . . . . . . . . . . . . . .623
EDIFACTBatchSplitterPreparser (com.ibi.preparsers.XDEDIFACTBatchSplitter). . . . . . . . . . 624
EDIH7BatchSplitter (com.ibi.preparsers.EDIHL7BatchSplitter). . . . . . . . . . . . . . . . . . . . . . . . 624
Contents
12 Information Builders
EDIX12SplitterPreParser (com.ibi.preparsers.EDIHL7BatchSplitter). . . . . . . . . . . . . . . . . . . 624
HIPAABatchSplitter (com.ibi.preparsers.XDHIPAABatchSplitter). . . . . . . . . . . . . . . . . . . . . . . 625
HIPAASplitterPreParser (com.ibi.preparsers.HIPAASplitPP). . . . . . . . . . . . . . . . . . . . . . . . . . . 625
SWIFTBatchSplitter (com.ibi.preparsers.XDSWIFTBatchSplitter). . . . . . . . . . . . . . . . . . . . . . .625
XML Splitter Preparser (com.ibi.preparsers.XDXMLSplit). . . . . . . . . . . . . . . . . . . . . . . . . . . . .625
3. iWay Preemitters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
Overview of Preemitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
Available Preemitters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
Constant PE (com.ibi.preemit.XDConstantPE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .634
Deflate (com.ibi.preemit.XDDeflate) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
EDIX12 Preemitter (com.ibi.preemit.XDX12PreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .636
Entity Repl Preemitter (com.ibi.preemit.XDEntityRepl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .636
File read Preemitter (com.ibi.preemit.XDFilePreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
Flat Delim Preemitter (com.ibi.preemit.XDFlatDelimPreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . .638
HIPAA Preemitter (com.ibi.preemit.XDHIPAAPreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter) . . . . . . . . . . . . . . . . . . . . . 640
Legacy Record Preemitter (com.ibi.preemit.LegacyRecordPreemitter) . . . . . . . . . . . . . . . . . . . . . . 647
Marshalls a message Preemitter (com.ibi.preemit.XDMarshall) . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
Multi Part (com.ibi.preemit.XDMultiPart) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
PGPEncrypt Preemitter (com.ibi.preemit.PGPEncrypt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
PGP Sign Only Preemitter (com.ibi.preemit.XDPGPSignPreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . 653
QA Print (com.ibi.preemit.XDQAPrint) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Remove Outer Tag (com.ibi.preemit.XDDeTag) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Replaced Paired Characters (com.ibi.preemit.XDCharRepl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
SWIFT Preemitter (com.ibi.preemit.SwiftPreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
UUEncodePreEmitter (com.ibi.preemit.XDUUEncodePreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
XDEDIFACT Preemitter (com.ibi.preemit.XDEDIFACTPreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . .661
XDSWIFT Preemitter (com.ibi.preemit.XDSwiftpreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .661
XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
4. iWay Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671
Understanding Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Iterator Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .672
Contents
iWay Service Manager Component Reference Guide 13
Available Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Attachment Iterator (com.ibi.agents.XDIterAttachments). . . . . . . . . . . . . . . . . . . . . . . . . . . . .675
Chunk Iterator (com.ibi.agents.XDIterChunk). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .675
Condition Iterator (com.ibi.agents.XDIterCond). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Counter Iterator (com.ibi.agents.XDIterCount). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .677
Delimited Value Iterator (com.ibi.agents.XDIterDelVal). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
FTP Emit Iterator (com.ibi.agents.XDIterNFTPEmitStdAgent). . . . . . . . . . . . . . . . . . . . . . . . . . 680
Island Iterator (com.ibi.agents.XDIterIsland). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
Iter RVI Relay Iterator (com.ibi.agents.XDIterRVIRelay). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
JSON Iterator (com.ibi.agents.XDIterJsonSplit). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
Line Iterator (com.ibi.agents.XDIterLine). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
SQL Batch Insert Iterator (com.ibi.agents.XDIterSQLBatchAdd). . . . . . . . . . . . . . . . . . . . . . . 689
SQL Select Iterator (com.ibi.agents.XDIterSQLSelect). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
Sibling Iterator (com.ibi.agents.XDIterSibSplit). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Test Iterator (com.ibi.agents.XDIterTest). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
XML Iterator (com.ibi.agents.XDIterXMLSplit). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Iterator Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
A. Additional SQL Service Reference Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .701
SQL Service Edge Returns Sorted by XOPEN Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
Transaction Isolation Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
B. Apache Avro Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Avro File Read Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Avro File Emit Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Avro File Iterator Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .720
Avro File Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .722
Avro RPC HTTP Emit Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
Avro RPC Over HTTP Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .730
Contents
14 Information Builders
Preface
This documentation provides a reference for predefined components of iWay Service Manager.These components include services (also referred to as agents), preparsers, and preemitters.This documentation is intended for developers, application and enterprise architects, businessanalysts, and system administrators who want to integrate new XML-based applicationsseamlessly with existing enterprise transactions, procedures, and application packages.
How This Manual Is Organized
This manual includes the following chapters:
Chapter/Appendix Contents
1 iWay Services Provides a reference for all the predefined servicesthat are supplied with iWay Service Manager.
2 iWay Preparsers Provides a reference for all the predefinedpreparsers that are supplied with iWay ServiceManager.
3 iWay Preemitters Provides a reference for all the predefinedpreemitters that are supplied with iWay ServiceManager.
4 iWay Iterators Provides an overview of iterators and their usagewithin iWay Service Manager process flows.
A Additional SQL ServiceReference Information
Provides additional reference information for theSQL Service (com.ibi.agents.XDSQLAgent).
B Apache Avro Components Describes the available components in iWay ServiceManager (iSM) that have been developed tointegrate with Apache Avro.
Documentation Conventions
The following table describes the documentation conventions that are used in this manual.
Convention Description
THIS TYPEFACE orthis typeface
Denotes syntax that you must enter exactly as shown.
iWay Service Manager Component Reference Guide 15
Convention Description
this typeface Represents a placeholder (or variable), a cross-reference, or animportant term. It may also indicate a button, menu item, or dialogbox option that you can click or select.
underscore Indicates a default setting.
Key + Key Indicates keys that you must press simultaneously.
{ } Indicates two or three choices. Type one of them, not the braces.
| Separates mutually exclusive choices in syntax. Type one of them,not the symbol.
... Indicates that you can enter a parameter multiple times. Type onlythe parameter, not the ellipsis (...).
.
.
.
Indicates that there are (or could be) intervening or additionalcommands.
Related Publications
Visit our Technical Documentation Library at http://documentation.informationbuilders.com. Youcan also contact the Publications Order Department at (800) 969-4636.
Customer Support
Do you have any questions about this product?
Join the Focal Point community. Focal Point is our online developer center and more than amessage board. It is an interactive network of more than 3,000 developers from almost everyprofession and industry, collaborating on solutions and sharing tips and techniques. AccessFocal Point at http://forums.informationbuilders.com/eve/forums.
Related Publications
16 Information Builders
You can also access support services electronically, 24 hours a day, with InfoResponseOnline. InfoResponse Online is accessible through our website, http://www.informationbuilders.com. It connects you to the tracking system and known-problemdatabase at the Information Builders support center. Registered users can open, update, andview the status of cases in the tracking system and read descriptions of reported softwareissues. New users can register immediately for this service. The technical support section of http://www.informationbuilders.com also provides usage techniques, diagnostic tips, andanswers to frequently asked questions.
Call Information Builders Customer Support Services (CSS) at (800) 736-6130 or (212)736-6130. Customer Support Consultants are available Monday through Friday between 8:00a.m. and 8:00 p.m. EST to address all your questions. Information Builders consultants canalso give you general guidance regarding product capabilities. Please be ready to provide yoursix-digit site code number (xxxx.xx) when you call.
To learn about the full range of available support services, ask your Information Buildersrepresentative about InfoResponse Online, or call (800) 969-INFO.
Help Us to Serve You Better
To help our consultants answer your questions effectively, be prepared to providespecifications and sample files and to answer questions about errors and problems:
The following tables list the environment information our consultants require.
Platform
Operating System
OS Version
JVM Vendor
JVM Version
The following table lists the deployment information our consultants require.
Adapter Deployment For example, iWay Business Services Provider, iWayService Manager
Container For example, WebSphere
Preface
iWay Service Manager Component Reference Guide 17
Version
Enterprise Information System(EIS) - if any
EIS Release Level
EIS Service Pack
EIS Platform
The following table lists iWay-related information needed by our consultants.
iWay Adapter
iWay Release Level
iWay Patch
The following table lists additional questions to help us serve you better.
Request/Question Error/Problem Details or Information
Did the problem arise througha service or event?
Provide usage scenarios orsummarize the application thatproduces the problem.
When did the problem start?
Can you reproduce thisproblem consistently?
Describe the problem.
Describe the steps toreproduce the problem.
Specify the error message(s).
Help Us to Serve You Better
18 Information Builders
Request/Question Error/Problem Details or Information
Any change in the applicationenvironment: softwareconfiguration, EIS/databaseconfiguration, application, andso forth?
Under what circumstance doesthe problem not occur?
The following is a list of error/problem files that might be applicable.
Input documents (XML instance, XML schema, non-XML documents)
Transformation files
Error screen shots
Error output files
Trace files
Service Manager package/archive to reproduce problem
Custom functions and services in use
Diagnostic Zip
Transaction log
User Feedback
In an effort to produce effective documentation, the Technical Content Management staffwelcomes your opinions regarding this document. Please use the Reader Comments form atthe end of this document to communicate your feedback to us or to suggest changes that willsupport improvements to our documentation. You can also contact us through our website, http://documentation.informationbuilders.com/connections.asp.
Thank you, in advance, for your comments.
iWay Software Training and Professional Services
Interested in training? Our Education Department offers a wide variety of training courses foriWay Software and other Information Builders products.
Preface
iWay Service Manager Component Reference Guide 19
For information on course descriptions, locations, and dates, or to register for classes, visitour website, http://education.informationbuilders.com, or call (800) 969-INFO to speak to anEducation Representative.
Interested in technical assistance for your implementation? Our Professional Servicesdepartment provides expert design, systems architecture, implementation, and projectmanagement services for all your business integration projects. For information, visit ourwebsite, http://www.informationbuilders.com/support.
iWay Software Training and Professional Services
20 Information Builders
Chapter1iWay Services
iWay Service Manager includes many predefined services that you can use to enhancethe business logic of a message. You can add these services to simple or complexbusiness logic configurations using the iWay Service Manager Administration Console.
For reference purposes, this section lists and describes all the services that are suppliedwith iWay Service Manager.
In this chapter:
Services Overview
Available Services
Parallel Control Services
Services Overview
Services are executable Java procedures that are used to handle the business logic of amessage in iWay Service Manager (iSM).
A service is the business layer that incorporates the logic for encapsulating the businessprocess which interacts with other distributed component services to provide transactions forbusiness state information. This business layer incorporates the application business logic. Inan iSM environment, business logic consists of one or more services acting on an inputdocument. Services can be stacked, such that the output of one service is passed to the nextservice, or multiple services can be executed in parallel.
Services are written in standard Java language and can make use of any available Javalibraries or services. iWay Software supplies a comprehensive set of predefined services withiSM that you can use as part of your business logic.
Services are configured within process flows using the Process Flow Designer in iWayIntegration Tools (iIT). iIT is an Eclipse-based design-time environment that allows you todevelop and manage scalable integration applications within the iWay Service Manager (iSM)framework requiring little to no coding. It is recommended to use the available Process FlowDesigner objects to create your process flows.
iWay Service Manager Component Reference Guide 21
Most of the services described in this document are implemented by a corresponding object inthe Process Flow Designer. For example, consider the File object, which is available from theProcess Flow Designer Palette, under the Connectors group, as shown in the following image.
Services Overview
22 Information Builders
The following image shows a simple process flow in the workspace area, where the File objectwas added (dragged and dropped) between the Start and End nodes.
1. iWay Services
iWay Service Manager Component Reference Guide 23
The Properties tab is where you configure the parameters for any object that you add to yourprocess flow, as shown in the following image.
Notice the Configuration tab in the left pane, which contains a Select Action drop-down list. Allof the available actions that are listed represent a supported File service. In this example, thelist directory contents action is selected, which is actually the File Directory Contents Service(com.ibi.agents.XDFileDirListAgent) as described in this document. Once an action is selected,all of the configuration parameters for that specific service are displayed.
This same behavior applies to other object types that are available from the Process FlowDesigner Palette and their corresponding actions/services.
Services Overview
24 Information Builders
For example, the following image shows the supported actions (services) for the FTP object.
The following image shows the supported actions (services) for the Email object.
1. iWay Services
iWay Service Manager Component Reference Guide 25
Available Services
The following section provides a comprehensive reference for all the predefined services thatare supplied with iWay Service Manager.
Accum EOS Agent (com.ibi.agents.XDAccumEOSAgent)
Syntax:
com.ibi.agents.XDAccumEOSAgent
iIT Service Object:
accumulation: Accum EOS Agent
Description:
This service accumulates document pieces and emits a full document at End of Stream (EOS).
Parameters:
Parameter Description
Final Root * The name and description of this parameter is derived from viewing XMLdocuments as trees of element objects. A well-formed XML document hasexactly one root element (also called document element). When youconfigure the Accumulate service, the name of the root element for theresulting document must be provided as the parameter. This means thatthe result of the processing must be enclosed between a root start-tag anda corresponding end-tag with the specified name. The root element of thisdocument tree is serving as a wrapper for the accumulated document parts,combining them into a well-formed XML document. For example:
<Final Root Parameter Value> <Accumulated Piece> … </Accumulated Piece> <Accumulated Piece> ... </Accumulated Piece> …</Final Root Parameter Value >
Available Services
26 Information Builders
Edges:
The following table lists the available line edges for the Accumulate EOS Service(com.ibi.agents.XDAccumEOSAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
The best application of the Accumulate EOS Service would be to merge the documentsproduced by the splitter for the final output. The architecture of a sample channel wouldcontain an inlet with a File listener and a splitter (for example, XML Splitter preparser). Theroute would contain a process flow with the Accumulate EOS Service object.
In this example, the following iWay response document is used as the incoming document:
1. iWay Services
iWay Service Manager Component Reference Guide 27
<?xml version="1.0" encoding="UTF-8"?><iway><response totalrows="3"><cncresult><result format="field"><resultset rowcount="3"><colinfo><col type="4" length="11" offset="0">Document_Link_ID</col><col type="12" length="50" offset="11">Value</col></colinfo> <row> <Document_Link_ID type="4">103</Document_Link_ID> <Value type="12">invoice</Value> </row> <row> <Document_Link_ID type="4">103</Document_Link_ID> <Value type="12">Milestone</Value> </row> <row> <Document_Link_ID type="4">103</Document_Link_ID> <Value type="12">Work Order</Value> </row></resultset></result></cncresult><timestamp>2007-01-10T17:02:48Z</timestamp><execstatus>0</execstatus></response></iway>
In this incoming document, notice that the <row> element loops three times. Therefore, asplitter can be used on this tag to split the incoming document into three individualdocuments, where each document corresponds to one loop iteration of the <row> element.
The XML Splitter preparser is configured to split the iWay response document into multipleXML documents, each containing one row, as shown in the following image:
Notice that a counter is being added to each row. This is configured in the event that there is aneed to merge the rows again into a single document after performing certain operations.
Available Services
28 Information Builders
The Accumulate service can be used to assemble these individual documents into one mergeddocument. In this case, the root element iway would be specified as a value for the Final Rootparameter.
The following is the assembled output of the channel:
<?xml version="1.0" encoding="ISO-8859-1" ?><iway> <eda count="1"> <response totalrows="3"> <cncresult> <result format="field"> <resultset rowcount="3"> <colinfo> <col type="4" length="11" offset="0">Document_Link_ID</col> <col type="12" length="50" offset="11">Value</col> </colinfo> <row> <Document_Link_ID type="4">103</Document_Link_ID> <Value type="12">invoice</Value> </row> </resultset> </result> </cncresult> </response> </eda> <eda count="2"> <response totalrows="3"> <cncresult> <result format="field"> <resultset rowcount="3"> <colinfo> <col type="4" length="11" offset="0">Document_Link_ID</col> <col type="12" length="50" offset="11">Value</col></colinfo> <row> <Document_Link_ID type="4">103</Document_Link_ID> <Value type="12">Milestone</Value> </row> </resultset> </result> </cncresult> </response> </eda>
1. iWay Services
iWay Service Manager Component Reference Guide 29
<eda count="3"> <response totalrows="3"> <cncresult> <result format="field"> <resultset rowcount="3"> <colinfo> <col type="4" length="11" offset="0">Document_Link_ID</col> <col type="12" length="50" offset="11">Value</col> </colinfo> <row> <Document_Link_ID type="4">103</Document_Link_ID> <Value type="12">Work Order</Value> </row> </resultset> </result> </cncresult> </response> </eda></iway>
Note the differences between the incoming and outgoing document. In the outgoing document,the structure is slightly rearranged and a loop counter is represented by the <eda> elementwith an incrementing count attribute. This counter is used to mark each iteration of the loop.
Accumulates Document Iterations (com.ibi.agents.XDAccumIterAgent)
Syntax:
com.ibi.agents.XDAccumIterAgent
iIT Service Object:
iterator: AccumIterAgent
Description:
Accumulates by gathering during iteration and releasing after iteration.
Parameters:
Parameter Description
Stage Gathering adds to the accumulation during the iteration.
Releasing emits an accumulated document to the flow.
Available Services
30 Information Builders
Parameter Description
Correlation Key Correlates gather and release side. Both must have thesame key name.
accum
Edges:
The following table lists the available line edges for the Accumulate Iteration Service(com.ibi.agents.XDAccumIterAgent).
Line Edge Description
OnCompletion Complete
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_notfound
Activity Log Business Error Message (com.ibi.agentsXDXALogBizErr)
Syntax:
com.ibi.agents.XDXALogBizErr
iIT Service Object:
operations: Activity Log Business Error Message
Description:
1. iWay Services
iWay Service Manager Component Reference Guide 31
A business error is an error detected by a process relating to the business activity beingperformed. It is not a hardware or software error. Business errors can be added to the activitylog by this agent.
Parameters:
Parameter Description
Transactional Determines whether this event record will beincluded in the log based on thetransaction. If set to true, the event islogged only if the process flow rolls back. Toachieve transactional recording, the channelmust be declared to control the localtransaction.
Message The text message to be logged.
Severity The severity of the error being logged. Thetwo defined values are:
bizerror
bizfatal.
Edges:
The following table lists the available line edges for the Activity Log Business Error MessageService (com.ibi.agentsXDXALogBizErr).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
32 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Activity Log Control Service (com.ibi.agents.XDXalogControlAgent)
Syntax:
com.ibi.agents.XDXalogControlAgent
iIT Service Object:
iterator: AccumIterAgent
Description:
Control (Start or Stop) the specified activity log Provider(s).
Parameters:
Parameter Description
Name The name of a deployed activity log exit tobe controlled. This log may be active orinactive.
Action Actions to take.
Start: Start an activity log exit that is instop state.
Stop: Stop an activity log exit that isstarted.
1. iWay Services
iWay Service Manager Component Reference Guide 33
Parameter Description
Wanteos When using a streaming preparser in achannel, the last call is made AFTER thelast document service exit is called.
False
True
Edges:
The following table lists the available line edges for the Activity Log Business Error MessageService (com.ibi.agentsXDXALogBizErr).
Line Edge Description
OnCompletion Complete
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
success
fail_parse
fail_notfound
fail_duplicate
fail_operation
Activity Log Entry Service (com.ibi.agents.XDXALogEvent)
Syntax:
Available Services
34 Information Builders
com.ibi.agents.XDXALogEvent
iIT Service Object:
operations: Activity Log Entry
Description:
This service is used to record events to the system log during a process flow. It can recordsecurity events and arbitrary user event codes. Each message that is logged has a type, code,and optional message.
Parameters:
Parameter Description
Transactional Determines whether this event record will be included in the log basedon the transaction. If set to true, the event is logged only if the entireprocess flow is successful. For transactional recording, the channel mustbe declared to control the local transaction.
Event The event class to be included in the log. Select one of the followingvalues from the drop-down list:
emit {emit}
security {security} (default)
emit {signature}
crypto {crypto}
user {user}
You can also type an arbitrary, user-defined value in the Event field thatmust be greater than 1000.
1. iWay Services
iWay Service Manager Component Reference Guide 35
Parameter Description
Code A code that further describes the event. Select one of the followingvalues from the drop-down list:
start {start} (default)
end {end}
fail {fail}
sign {sign}
encrypt {encrypt}
decrypt {decrypt}
verify {verify}
You can also type an arbitrary, user-defined value in the Code field thatmust be greater than 1000.
Message An arbitrary message that you want to associate with this event record.
Available Response Edges for XDXALogEvent
When you connect the XDXALogEvent object to an End object using the OnCustom buildrelation in a process flow, the available edges are provided in the Line Configuration dialogbox.
Edges:
The following table lists the available line edges for the Activity Log Entry Service(com.ibi.agents.XDXALogEvent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
36 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_Parse
Add Attachment From File Service (com.ibi.agents.XDAddAttachmentFromFileAgent)
Syntax:
com.ibi.agents.XDAddAttachmentFromFileAgent
iIT Service Object:
attachments: Add Attachment From File
Description:
This service adds a new attachment with the contents determined by the contents of a file.This service is convenient to provide binary data without first going through a Java characterset encoding. The attachment headers are specified by the special registers of type HDR in theMIME Header Namespace.
There are also four parameters to specify the most common MIME headers. When used, theseparameters override special registers of the same name. Notice the value of the Content-IDheader is taken as is, so the value must contain the surrounding angle brackets. For example,a valid value for Content-ID might be <cid>. This service follows the OnSuccess edge uponsuccessful execution, otherwise it follows OnError.
Attachments can have an optional Content_Disposition header, which can be generated andformatted by this service. For example, given a body payload of:
<body>body data</body>
and a file containing:
<mime>attachment data</mime>
1. iWay Services
iWay Service Manager Component Reference Guide 37
Setting the Specific Name of Attachment and Content-Disposition parameters will provide aresult as summarized in the following table.
ContentDisposition
Specific Name Result
none none ------=_Part_0_29701819.1486739647460Content-Type: application/xml<body>body data</body>------=_Part_0_29701819.1486739647460Content-Type: application/xmlContent-Transfer-Encoding: 7bitContent-Length: 32<mime>attachment data</mime>------=_Part_0_29701819.1486739647460--
none my_content_name.txt ------=_Part_2_1555061314.1486739752724Content-Type: application/xml<body>body data</body>------=_Part_2_1555061314.1486739752724Content-Type: application/xmlContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=my_content_name.txtContent-Length: 32<mime>attachment data</mime>------=_Part_2_1555061314.1486739752724--
my_disposition none ------=_Part_4_811251587.1486739819946Content-Type: application/xml<body>body data</body>------=_Part_4_811251587.1486739819946Content-Type: application/xmlContent-Transfer-Encoding: 7bitContent-Disposition: my_dispositionContent-Length: 32<mime>attachment data</mime>------=_Part_4_811251587.1486739819946--
my_disposition my_content_name.txt invalid combination
Available Services
38 Information Builders
Parameters:
Parameter Description
Input Data * Path to the file that contains the attachment data.
Content-Type * Value of the Content-Type MIME header.
Content Description Value of the Content-Description MIME header.
Content-Disposition Value of the Content-Disposition MIME header.
Content-ID Value of the Content-ID MIME header.
MIME HeaderNamespace
Special register namespace from which additional MIME headersfor the attachment are taken. If no value is specified, no MIMEheaders are added beyond those generated by the header-specificagent parameters.
Specific Name ofAttachment
The name to be added into a Content_Disposition header if notoverridden by the Content Disposition operand. For attachments,this is often a file name.
Edges:
The following table lists the available line edges for the Add Attachment From File Service(com.ibi.agents.XDAddAttachmentFromFileAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
1. iWay Services
iWay Service Manager Component Reference Guide 39
Line Edge Description
fail_notfound File cannot be located or loaded into theattachment.
fail_operation Other error in creating the attachment.
Add Attachment Service (com.ibi.agents.XDAddAttachmentAgent)
Syntax:
com.ibi.agents.XDAddAttachmentAgent
iIT Service Object:
attachments: Add Attachment
Description:
This service adds a new attachment with the contents determined by the value of a stringexpression. The Java Character Set parameter specifies how the Java characters in the stringare converted to bytes in the body of the attachment. The attachment headers are specified bythe special registers of type HDR in the MIME Header Namespace.
There are also four parameters available to specify the most common MIME headers. Whenused, these parameters override special registers of the same name. Notice the value of theContent-ID header is taken as is, so the value must contain the surrounding angle brackets.For example, a valid value for Content-ID might be <cid>. This service follows the OnSuccessedge upon successful execution, otherwise it follows OnError.
The use of the specific name of the attachment and Content Disposition operates the same asit does for the Add Attachment From File Service(com.ibi.agents.XDAddAttachmentFromFileAgent). However the content of the attachment istaken from the environment of the service. Often this is through the iWay Functional Language(iFL).
Parameters:
Parameter Description
Input Data * An expression that returns the contents of the attachment.
Available Services
40 Information Builders
Parameter Description
Java Character Set The character set used to convert from Java characters to anarray of bytes. If no value is specified, the default character setwill be used.
Content-Type * Value of the Content-Type MIME header.
Content-Transfer-Encoding
Value of the Content-Transfer-Encoding MIME header.
Content Description Value of the Content-Description MIME header.
Content-Disposition Value of the Content-Disposition MIME header.
Content-ID Value of the Content-ID MIME header.
MIME HeaderNamespace
Special register namespace from which additional MIME headersfor the attachment are taken. If no value is specified, no MIMEheaders are added beyond those generated by the header-specificagent parameters.
Specific Name ofAttachment
The name to be added into a Content_Disposition header if notoverridden by the Content Disposition operand. For attachments,this is often a file name.
Edges:
The following table lists the available line edges for the Add Attachment Service(com.ibi.agents.XDAddAttachmentAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 41
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Add Correl Entry Service (com.ibi.agents.XDAddCorrelEntryAgent)
Syntax:
com.ibi.agents.XDAddCorrelEntryAgent
iIT Service Object:
misc: Add Correl Entry Agent
Description:
Uses a correlation management bus to initialize a correlated process. For more information,see the Correlation Facility topic in the iWay Service Manager User's Guide.
Edges:
The following table lists the available line edges for the Add Correl Entry Service(com.ibi.agents.XDAddCorrelEntryAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
42 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_operation
fail_duplicate
fail_reissue
fail_closed
fail_notfound
Alt Route IP Service (com.ibi.agents.XDAltRouteIP)
Syntax:
com.ibi.agents.XDAltRouteIP
iIT Service Object:
operations: Alt Route IP
Description:
This service is used to check for a primary host. If that host is not reachable, an alternate hostis checked. This is useful for alternate routing.
Parameters:
Parameter Description
Host * The primary host to be checked for reachability.
Alternate * The secondary host to be checked for reachability.
Sreg * Name of the special register to hold the name of the reachable host.
Timeout * A timeout period to attempt to reach the host. The default value is 3seconds.
1. iWay Services
iWay Service Manager Component Reference Guide 43
Edges:
The following table lists the available line edges for the Alt Route IP Service(com.ibi.agents.XDAltRouteIP).
Edge Description
OnSuccess
OnError
OnFailure
A route could be obtained.
fail_parse Neither host is reachable.
fail_partner The host is not known. For example, the host is not identifiable in theDNS.
fail_unreachable Neither host nor alternate can be reached.
Append Stream to File Service (com.ibi.agents.XDFileAppendAgent)
Syntax:
com.ibi.agents.XDFileAppendAgent
iIT Service Object:
format: Append Stream to File
Description: Appends a stream of data to an open file .
Parameters:
Parameter Description
Source of Data Source of the data to write. If omitted, the document will be used,unless you specify a data source location via xpath() function or anyother function
Destination FilePath *
The path to the destination file.
Available Services
44 Information Builders
Parameter Description
Close File * When set to true, the cached file connection is closed. Often iFL suchas _iseos(). No data is written on the true value.
Return Return from this agent.
status - the status document will be the output document.
input - the input document will become the output document.
Call at EOS In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
Edges:
The following table lists the available Line Edges for the Append Stream to File Service(com.ibi.agents.XDFileAppendAgent).
Line Edges Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnNotFound The resource was not found and this isconsidered an error.
OnFailedOperation Could not perform the operation requested.
AQ Emit Service (com.ibi.agents.XDAQEmitAgent)
Syntax:
com.ibi.agents.XDAQEmitAgent
iIT Service Object:
1. iWay Services
iWay Service Manager Component Reference Guide 45
misc: AQ Emit Agent
Description:
This service sends a message to an Oracle AQ queue.
Parameters:
Parameter Description
Queue Name * Name of the input queue to be monitored.
Host Host of the server connection.
SID * SID of the server connection.
Port Port to use for the server connection.
Driver * Driver to use for the server connection.
User * User login ID at the broker machine.
Password * User password at the broker machine.
Table Owner/Schema *
Usually the same as the login.
Table Name Table in which the queue resides.
Connection Type * Connection to Oracle JMS or Oracle AQ.
aq
jms
AQ
Message Type Select one of the following message type formats to send or create(when creating a dynamic queue on the listener):
clob
raw
Payload Class When using custom defined objects, specify a class that is in theclasspath.
Available Services
46 Information Builders
Parameter Description
Payload Object When using custom defined objects, specify the Oracle object that theclass will map to. The owner of the schema will be prepended.
Object Owner Name of the input queue to be monitored.
RAC
RAC Hosts Enter additional hosts for RAC failover/load balancing (host1:port,host2:port, host3:port).
RAC Load balance Use the RAC connection for load balancing.
false
true
RAC Failover Use the RAC connection for failover.
false
true
ONS Hosts Hosts emitting ONS information, for example host:port, host:port.
Cache Minimum The minimum number of connections to the queue to be held in thecache.
Cache Maximum The maximum number of connections to the queue to be held in thecache.
Cache Initial The initial number of connections to create in the cache.
Cache InactiveTimeout
The maximum time a cached physical connection can remain idle.
Cache AbandonedTimeout
The maximum time that a connection can remain unused before theconnection is closed and returned to the cache.
Cache MaximumStatements
The maximum number of statements that a connection keeps open.
1. iWay Services
iWay Service Manager Component Reference Guide 47
Parameter Description
Cache PropertyInterval
Sets the time interval at which the cache manager inspects andenforces all specified cache properties.
JMS
Message Priority The outgoing message priority. If no value is specified, the incomingmessage priority is used.
Message Type Select one of the following message type formats to send or create(when creating a dynamic queue on the listener):
bytes
text
Set ReplyCorrelation ID
If set to a value, this is used as the correlation ID of the response.
Delivery Mode Retention of a message at the destination until its receipt isacknowledged is not guaranteed by a PERSISTENT delivery mode.
JMSReplyTO Queue or Topic (used for JNDI lookup).
Time to Live The lifetime of a message (in milliseconds). The default is themessage will live forever.
Agent Specific Parameters
Return * Return from this agent.
response
status
Preemitter Determines if any preemitter be avoided.
true
false
Available Services
48 Information Builders
Edges:
The following table lists the available line edges for the AQ Emit Service(com.ibi.agents.XDAQEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_connect
The result of the Oracle AQ post appears in the <native> section of the <emitstatus> result.For more information, see the iWay Adapter for OracleAQ User's Guide.
AS2 Nonblocking Emit Service (com.ibi.agents.XDNAS2EmitAgent)
Syntax:
com.ibi.agents.XDNAS2EmitAgent
iIT Service Object:
emit: AS2 Nonblocking Emit
http: AS2 Nonblocking Emit
Description:
Emits AS2 messages to a client without interrupting a configured business process. For moreinformation, see the iWay Service Manager Protocol Guide.
1. iWay Services
iWay Service Manager Component Reference Guide 49
Parameters: - Configuration Parameters
Parameter Description
Destination URL that is used to post this information.
HTTP Client Provider HTTP client provider that is used to manage connections forthis emitter.
AS2-From A textual value identifying the sender of data exchange.
AS2-To A textual value identifying the receiver of data exchange.
Subject Sets the Subject header.
Request Receipt Tells the emitter to send a request for receipt in the form of aMessage Disposition Notification (MDN).
Asynchronous ReceiptURL
If an asynchronous receipt should be requested, specify theURL to which the receipt should be sent.
Supported values are in the form:
mailto:user@host. For asynchronous receipt by email.
http://host[:port]/. For asynchronous receipt by HTTP.
https://host[:port]/. For asynchronous receipt by HTTPS.
Receipt Destination Directory into which synchronous MDNs are stored. Specificfile name is optional. Use * in file name to add a timestampand use # to add a sequential counter.
Content-Type Specifies the content-type of data to be sent. Select from thedrop-down list or provide your own.
Message ID Set this to control the emitted message ID. Usually this is leftblank to let the system generate a unique ID meeting therequirements of RFC 822. Use this only to override the default.This is not recommended.
Content Disposition File name to put in the Content-Disposition header value.
User ID User ID for Basic Authentication challenges.
Available Services
50 Information Builders
Parameter Description
Password Password for Basic Authentication challenges.
Domain Domain for NTLM authentication challenges. To use NTLM, youmust enable connection persistence.
Request HeaderNamespace
Special register namespace from which HTTP headers for theoutgoing request will be taken.
Default Namespace. To send HDR type registers.
Supply a namespace prefix here to indicate which headersto send.
None. Means that no special registers will be sent as HTTPheaders.
Request Main PartHeader Namespace
Special register namespace from which MIME headers for theoutgoing request will be taken. Provide a prefix to control therequest Main BodyPart headers in the presence ofattachments. Selecting none means that no special registerswill be sent as MIME headers.
Response HeaderNamespace
Special register namespace into which HTTP headers for theincoming response will be saved.
Default Namespace. To create special registers with nonamespace.
Supply a namespace prefix here to indicate headernamespace.
MDN Header Namespace Special register namespace into which MIME headers of themultipart/report entity will be saved. This namespace isignored if the MDN is unsigned since all headers will be in theResponse Header Namespace.
MDN Field Namespace Special register namespace into which MDN fields will besaved.
1. iWay Services
iWay Service Manager Component Reference Guide 51
Parameter Description
Excluded Headers A comma delimited list (case-insensitive) of headers thatshould not be sent with the request, even if they are found inthe request header namespace.
Ask for CompressedResponse
If set, requests will set the Accept-Encoding header to indicatethat the client can accept a compressed response, asdescribed in RFC-2616. If the response has a compressedcontent encoding, the client will automatically inflate.
Compress Request If set, the HTTP request entity will be compressed using theselected encoding and the Content-Encoding header will be setaccordingly.
Replace Connection? If set to false, the connection will not be returned to theconnection pool immediately. The identifier of the connectionwill be stored in the HTTP client-key special register and theconnection can be handled by the HTTP Client Manager agent.
Maximum HTTP ClientManager Delay
Maximum time the HTTP Client Manager can take to address aparticular connection before it is automatically aborted. Theformat is [xxh][xxm]xx[s]. The default is 60 seconds.
Maximum Request Size Maximum size, after compression, of a request entity that canbe sent with this emitter. 0 means no maximum and blank willdefault to 256KB.
Maximum Response Size Maximum size of a response entity that can be received by thisemitter. 0 means no maximum and blank will default to256KB.
Try Expect/ContinueHandshake?
If checked, client will send the HTTP Expect: 100-continueheader and await the HTTP 100 response before sending therequest body.
Parameters: - S/MIME
Parameter Description
S/MIME
Available Services
52 Information Builders
Parameter Description
Packaging Tells the emitter how the document should be packaged fortransmission. Select from the drop-down list:
Encrypted
Signed
Signed and Encrypted
Un-encrypted
Compression Determines when message compression should be applied.Select from the drop-down list:
Compress After Signature
Compress Before Signature
No Compression
S/MIME KeystoreProvider
Provider for the Keystore used to sign and encrypt messages.
S/MIME TruststoreProvider
Provider for the Keystore containing the S/MIME CertificateAuthorities.
S/MIME Certificate StoreProviders
Comma-separated list of Keystore, Directory CertStore, orLDAP providers for the certificate stores used to completesigner certificate chains when the signed message containsfewer certificates than needed.
S/MIME JCECryptography Provider
JCE Provider for S/MIME Cryptography services.
S/MIME Verification JCECrypto Provider
JCE Provider for S/MIME verification cryptography services.Normally left blank. Defaults to S/MIME JCE Provider.
S/MIME PKIX JCEProvider
JCE Provider for S/MIME PKIX services. If left blank, thedefault JCE provider for PKIX will be used.
Recipient Public Key Alias The alias for the recipient public key entry used for encryption.
1. iWay Services
iWay Service Manager Component Reference Guide 53
Parameter Description
Signature Key Alias The alias for the private key entry used for signing.
Signature Key password Password to access the signature private key. If left blank, thepassword used to access the Keystore will be used.
Digest Algorithm Algorithm to be used for signing.
Encryption Algorithm Algorithm to be used for encrypting.
Include Certificate Chain Determines how much of the signer certificate chain isincluded in the message. Select from the drop-down list:
Complete Certificate Chain
No Certificate
Signer Certificate only
Enforce KeyUsageExtension
If set to on, verify certificates used for signing allow the digitalSignature KeyUsage extension, and certificates used forencryption allow the key Encipherment KeyUsage extension.
Enable CertificateRevocation
If set to true, use the CRLs from the CertStores to checkwhether the signer's certificate has been revoked.
Unrecognized CertsLocation
Directory to store unrecognized certificates found in S/MIMEmessages.
Parameters: - IP Properties
Parameter Description
IP Properties
Persistence If checked, ask the server to maintain the connection.
Response Timeout valuein seconds
Seconds to wait for a response before signaling an error.
Available Services
54 Information Builders
Parameters: - Agent Specific parameters
Parameter Description
Return Return from this agent. Select one of the following optionsfrom the drop-down list:
input
status
response
Preemitter Determines whether any preemitter should be avoided. If set totrue, preemitters will not run.
Response Wrapper Tag The tag name with which to wrap the response if the responseis non-XML and must be XML.
Response Base64Encoded
If set to true, Response will be Base64 encoded.
Edges:
The following table lists the available line edges for the AS2 Nonblocking Emit Service(com.ibi.agents.XDNAS2EmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 55
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_connect
fail_info
fail_redirection
fail_client
fail_server
fail_operation
fail_parse
fail_request_too_large
fail_response_too_large
fail_unsigned
AS 1 Emit Service (com.ibi.agents.AS1EmitAgent)
Syntax:
com.ibi.agents.AS1EmitAgent
iIT Service Object:
misc: AS 1 Emit Agent
Description:
Emits AS1 (email) messages. For more information, see the iWay Service Manager ProtocolGuide.
Available Services
56 Information Builders
Parameters:
Parameter Description
Send To * Address to receive this message.
Outgoing Mail Host * Destination email host to which outgoing email is sent.
SMTP User Logon user ID for SMTP host.
SMTP Password Logon password for SMTP host.
Subject of Msg Subject for messages.
Sender Address * Email address of sender.
Copy To Copy this message to these locations (can be comma delimitedlist).
Blind Copy To Blind copy this message to these locations (can be a commadelimited list).
Content Type * Overrides content type of the message.
application/XML
application/EDIFACT
application/EDI-X12
Return Status * status. A status document will become the output document.
input. Input document will become the output document.
Avoid Preemitter Checks to see if any preemitter should be avoided.
true
false
1. iWay Services
iWay Service Manager Component Reference Guide 57
Parameters: - SMIME
Parameter Description
Packaging * Tells the emitter how the document should be packaged fortransmission. For S/MIME packaging, it will use configure for S/MIME system properties.
regular (unsigned/unencrypted)
smime_sign (signed only)
smime_encrypt (encrypted only)
smime_sign_encrypt (signed and encrypted)
Compression * If checked, compression will be applied.
false
true
Request Receipt * Tells the emitter to send a request for receipt, for example,MDN(Message Disposition Notification).
none
signed
unsigned
Deliver Receipt To The address where receipt should be sent to (user@mail_host).
Public Key Alias Alias for public key entry. Used for encryption.
Private Key Alias Alias for private key entry. Used for signing and decryption.
Private Key Password Password for key access. If omitted, store password is used.
Digest Algorithm Digest algorithm.
SHA-1
MD5
Available Services
58 Information Builders
Parameter Description
Encrypt Algorithm * Encryption algorithm.
CAST5
DES-EDE3
IDEA
RC2
Edges:
The following table lists the available line edges for the AS 1 Emit Service(com.ibi.agents.AS1EmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
AS 2 Emit Service (com.ibi.agents.AS2EmitAgent)
Syntax:
com.ibi.agents.AS2EmitAgent
iIT Service Object:
misc: AS 2 Emit Agent
Description:
1. iWay Services
iWay Service Manager Component Reference Guide 59
General AS2 emitter for use within the service stack. For more information, see the iWayService Manager Protocol Guide.
Parameters:
Parameter Description
Destination * The URL where information is posted.
Content-Type * Specifies the content-type of data to be sent.
application/XML
application/EDIFACT
application/EDI-X12
Response timeout value in seconds Seconds to wait for response before signalingerror.
Content Disposition File name to put in the Content-Disposition headervalue.
User ID User ID for Basic Authentication challenges.
Password Password for Basic Authentication challenges.
Packaging * Tells the emitter how the document should bepackaged for transmission. For encrypted and/orsigned packaging, configure S/MIME systemproperties.
encrypted
signed
signed and encrypted
un-encrypted
Compression If checked, compression will be applied.
true
false
Available Services
60 Information Builders
Parameter Description
AS2-From * A textual value identifying the sender of dataexchange.
AS2-To * A textual value identifying the receiver of dataexchange.
Subject Sets the subject header.
Request Receipt * Tells the emitter to send a request for receipt, forexample, MDN(Message Disposition Notification).
None. No MDN Returned
Signed. Signed MDN Returned
Unsigned. Unsigned MDN Returned
Asynchronous receipt URL If an asynchronous receipt should be requested,specify the URL to which the receipt should besent. Supported values are in the form:
mailto:<user>@<host> for asynchronousreceipt by email
http://<host>/... for asynchronous receipt byHTTP
https://<host>/... for asynchronous receipt byHTTPS
Receipt Destination Encryption algorithm.
CAST5
DES-EDE3
IDEA
RC2
Public Key Entry Alias The alias for the public key entry used forencryption.
1. iWay Services
iWay Service Manager Component Reference Guide 61
Parameter Description
Private Key Entry Alias The alias for the private key entry used for signing.
Private Key Password Password to access the private key. If left blank,password used to access Keystore will be used.
Digest Algorithm Digest algorithm used for signing.
SHA-1
MD5
Encryption Algorithm Algorithm to be used for encrypting.
CAST5
DES-EDE3
IDEA
RC2
IP Interface Host Local IP Interface from which the outgoing IPsocket originates.
IP Interface Port Local IP Port from which the outgoing IP socketoriginates.
Parameters - Proxy
Parameter Description
Proxy If on, emit through proxy server.
true
false
Proxy URL URL of the proxy server.
Proxy User ID User ID for Basic Authentication challenges issuedby Proxy.
Available Services
62 Information Builders
Parameter Description
Proxy Password Password for Basic Authentication challengesissued by Proxy.
Parameters - HTTPS
Parameter Description
Secure Connection Use a secure connection. You may need toconfigure the Keystore under HTTPS section of thesystem properties if client authentication isrequired. Note, if keystore is configured in systemproperties make sure it has the CA certificate orthe client certificate of the server you areconnecting to. If keystore is not configured insystem properties, default truststore located underJRE_HOME/lib/security/cacerts will be used.
true
false
Use 128-bit Encryption Enforces the use of 128-bit encryption.
true
false
1. iWay Services
iWay Service Manager Component Reference Guide 63
Parameter Description
Security Protocol Security protocol.
SSL. Supports some version of SSL. Maysupport other versions.
SSLv2. Supports SSL version 2 or higher.
SSLv3. Supports SSL version 3. May supportother versions.
TLS. Supports some version of TLS. Maysupport other versions.
TLSv1. Supports TLS version 1. May supportother versions.
Parameters - Agent Specific Parameters
Parameter Description
Return * Checks to see if it should return from this agent.
true
false
Avoid Preemitter Check to see if any preemitter be avoided.
true
false
Response Wrapper Tag The tag name with which to wrap the response ifthe response is non-XML and must be XML.
Response Base64 Encoded Checks to see if the response needs to be Base64encoded.
true
false
Available Services
64 Information Builders
Edges:
The following table lists the available line edges for the AS 2 Emit Service(com.ibi.agents.AS2EmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
AS 2 Nonblocking Send MDN Service (com.ibi.agents.XDMDNSendNowAgent)
Syntax:
com.ibi.agents.XDMDNSendNowAgent
iIT Service Object:
misc: AS2 Nonblocking Send MDN
Description:
The AS 2 nonblocking send MDN service is a new service that is available in the NAS2 adapterconfiguration. For more information, see the iWay Service Manager Protocol Guide.
Edges:
The following table lists the available line edges for the AS 2 Nonblocking Send MDN Service(com.ibi.agents.XDMDNSendNowAgent).
Line Edge Description
OnError Error
1. iWay Services
iWay Service Manager Component Reference Guide 65
Line Edge Description
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
Attachment Iterator Service (com.ibi.agents.XDIterAttachments)
Syntax:
com.ibi.agents.XDIterAttachments
iIT Service Object:
iterator: Attach Iterator
Description:
Handle each attachment of the current document per iterative.
Parameters:
Parameter Description
Handle Option How to handle identified attachments
delete: removes each attachment from current document afterprocessing.
replace: replaces the original attachment with a the modifieddocument.
leave: leaves original attachments unchanged.
Start Index Index of the first attachment to process in the mail object. Thefirst attachment to the main document has an index of 0 (zero).
Available Services
66 Information Builders
Parameter Description
Header Namespace The special register namespace where MIME headers for thecurrent attachment will be stored. If replace handling option isselected, registers in the namespace will be added to thereplaced attachment.
Main Body PartHeader Namespace
If the current attachment is itself a multipart, then this is thespecial register namespace where the MIME headers for the mainbody part will be stored.
Keep Document Flat Keeps the body of the document as an array of bytes.
True
False
Edges:
The following table lists the available line edges for the Attachment Iterator Service(com.ibi.agents.XDIterAttachments).
Line Edge Description
OnCompletion Complete
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
fail_notfound
1. iWay Services
iWay Service Manager Component Reference Guide 67
Attachment Operations Service (com.ibi.agents.XDAttachOps)
Syntax:
com.ibi.agents.XDAttachOps
iIT Service Object:
attachments: Attachment Operations
operations: Attachment Operations
Description:
This service performs operations on document attachments.
Parameters:
Parameter Description
Operation * Determines which operation should be performed on thisdocument. Select one of the following options from the drop-downlist:
deleteAll (default)
deleteOne
Attachment Number For operations on a specific attachment, which one, base 0. If avalue is specified, this parameter takes precedence over theContent-ID parameter.
Content-ID For operations on a specific attachment, the Content-ID of theattachment. This parameter is ignored if a value for theAttachment Number parameter is specified.
Although the specification of the Content-ID header requires thevalue to be enclosed in angle brackets, you must not use theangle brackets in this property.
Available Services
68 Information Builders
Edges:
The following table lists the available line edges for the Attachment Operations Service(com.ibi.agents.XDAttachOps).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
fail_parse
fail_notfound
Attachment to Document Service (com.ibi.agents.XDAttachmentToDocAgent)
Syntax:
com.ibi.agents.XDAttachmentToDocAgent
iIT Service Object:
attachments: Attachment to Document
Description:
This service finds an attachment and makes it the body of the document. The attachment canbe selected by index or by Content-ID. If the Attachment Number is specified, it takesprecedence over the Content- ID. The attachment index is base 0. If present, the Content- IDmust NOT contain the surrounding angle brackets.
1. iWay Services
iWay Service Manager Component Reference Guide 69
For example, the value cid for the Content-ID parameter will match an attachment with aContent-ID header equal to <cid>. The Header Namespace is the special register namespacewhere MIME headers for the selected attachment will be stored. The attachment will be storedas bytes if the Keep Document Flat parameter is enabled. Otherwise, the attachment will beparsed XML or JSON, depending on the MIME subtype (for example, application/json orapplication/xml). If the attachment is itself a Multipart, then the document will contain theparse of the Main Body Part and the other parts will appear as document attachments.
The MIME headers of the Main Body Part will be saved as registers in the Main Body PartHeader Namespace. This is needed to keep them distinct from the Multipart headers. TheDelete Attachment parameter determines what to do with the selected attachment when it isnot a Multipart: the attachment can be preserved or deleted. This service follows OnSuccessupon successful execution, otherwise, it follows fail_notfound if the attachment cannot befound, or it follows fail_operation if there is another error.
Parameters:
Parameter Description
Attachment Number The number of the attachment to be retrieved. If specified, ittakes precedence over the Content-ID.
Content-ID The Content-ID of the attachment to be retrieved. This value isignored if the attachment number is specified.
Header Namespace Special register namespace where MIME headers for the selectedattachment will be stored.
Main Body PartHeader Namespace
If the current attachment is itself a Multipart, this is the specialregister namespace where the MIME headers for the main bodypart will be stored.
Keep Document Flat Determines whether to keep the body of the document as an arrayof bytes. This parameter is set to false by default.
Delete Attachment Determines whether to delete the attachment after it becomesthe body of the document. This parameter is set to false bydefault.
Available Services
70 Information Builders
Edges:
The following table lists the available line edges for the Attachment to Document Service(com.ibi.agents.XDAttachmentToDocAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
fail_parse
fail_notfound
Attachment to File Service (com.ibi.agents.XDAttachmentToFileAgent)
Syntax:
com.ibi.agents.XDAttachmentToFileAgent
iIT Service Object:
format: Attachment to File
Description: Writes the contents of an attachment to a file.
Parameters:
Parameter Description
Attachment Number The number of the attachment to be retrieved. If specified, it takesprecedence over the Content-ID.
1. iWay Services
iWay Service Manager Component Reference Guide 71
Parameter Description
Content-ID The Content-ID of the attachment to be retrieved. It is ignored ifthe Attachment Number is specified.
Delete Attachment Specifies whether to delete the attachment after it becomes thebody of the document.
File
Target Directory * The target output directory.
File Pattern * The output file name, which can contain a '*' which getsexpanded to a fine timestamp.
Output DocumentType
Specifies whether the output document emitted should be theoriginal input document (original) or a status document (status).
Output Encoding The encoding to apply to the output file being written. Does notapply when the output is base 64.
Base64 Decode If set, the value is assumed to be in base64 notation. Onlyapplicable if a specific write value is specified.
RespectTransactionality *
If set, the emit respects the transactionality of the channel. If notset, the emit is always done.
Append If set, the output will be appended to the file if it already exists.
Append CRLF If set, a line termination sequence will be written after thedocument.
Emit Zero LengthFiles?
If true, emit empty files if the process creates them.
Edges:
Available Services
72 Information Builders
The following table lists the available Line Edges for the Attachment to File Service(com.ibi.agents.XDAttachmentToFileAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnNotFound The resource was not found and this isconsidered an error.
OnFailedOperation Could not perform the operation requested.
Authenticate/Impersonate Service (com.ibi.agents.XDPrincipalAgent)
Syntax:
com.ibi.agents.XDPrincipalAgent
iIT Service Object:
operations: Security: Authenticate/Impersonate
security: Security: Authenticate/Impersonate
Description:
This service allows a process to authenticate and/or impersonate a user based on credentialsin a message or message context.
For more information about the Authenticate/Impersonate service, see the iWay ServiceManager Security Guide.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 73
The following table lists the available line edges for the Authenticate/Impersonate Service(com.ibi.agents.XDPrincipalAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_security
fail_parse
BAM Receiver Service (com.ibi.agents.BAMReceiver)
Syntax:
com.ibi.agents.BAMReceiver
iIT Service Object:
objectgroup: BAM Receiver
Description:
This is the BAM Receiver.
Parameters:
Parameter Description
File Name andLocation
File name and location in the form of a full path entry. Forexample, C:/Temp/Datafile.xml
Available Services
74 Information Builders
Parameter Description
Real-time collectionperiod (sec)
Frequency by which the real-time performance metrics are to bewritten, where a lower number will have a greater impact onsystem performance. The default setting is set to 5 seconds.
File Backup Should the original file be backed up before creating a new logfile.
You can select either True or False.
No of Files to Backup The number of real-time performance metric files to back up. Allbacked up files are numbered and kept in the same directorywhere the original file is written. The default setting is set to 15minutes.
User defined Metrics Special Registers and time based performance aggregate function(COUTN, SUM, MIN, MAX, and AVG) to monitor in real-time andthen archive. Multiple values should be separated by commas,and the aggregate function should be supplied as:FUNCTION(SREGNAME).
Choose ArchiveFrequency
The Archive Frequency at which the data is persisted in thedatabase. You can select either:
RealTime
Minutes
Hours
Time (in seconds)since last execution
Specify the time (in seconds) since the last execution occurred.This will generate events in case of inactivity in iSM.
Channel Monitor Type Select which channels should be monitored. You can selecteither:
Active Only
All Channels (active, inactive, config)
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 75
The following table lists the available line edges for the BAM Receiver Service(com.ibi.agents.BAMReceiver).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
Base64 Operation Service (com.ibi.agents.XDBase64Agent)
Syntax:
com.ibi.agents.XDBase64Agent
iIT Service Object:
format: Base64 Operation
Description:
This service encodes or decodes a portion of a document using Base64 encoding. Base64 is aspecific content transfer encoding scheme that translates binary data into a base 64representation. Base 64 is set of 64 characters that is part of the subset common to mostencodings, and also printable. It is possible to store non-unicode fields within an internaldocument even though under XML rules such a document cannot be parsed. The Base64service enables these fields, or the entire incoming document, to be replaced with bytes, andthese bytes to be translated into a base 64 representation.
Parameters:
Parameter Description
Encode or Decode * Encode to a base 64 representation or decode from a base 64representation. The default value is encode.
Available Services
76 Information Builders
Parameter Description
XPATH expression toData
The value of the XPath expression within the input document thatwill be used as the input data to encode or decode.
If no value is specified, the entire input document is used.
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
Edges:
The following table lists the available line edges for the Base64 Operation Service(com.ibi.agents.XDBase64Agent).
Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
In a use case scenario, the Base64 service can be used to handle binary data from a pictureor image. For example, you can use it to decode a picture that is temporarily stored in base64format within the picture tag of an incoming XML document. The data can be placed in a fileand later saved with the appropriate extension to be viewed by a photo editor.
1. iWay Services
iWay Service Manager Component Reference Guide 77
The following image is an example of configuration settings for a Base64 service object in iITDesigner:
Refer to the Pictures sample that is packaged with iWay Service Manager for the sample inputfile. For example, the input document that is used by theSamples.Pictures.CreatePictureInsertRequest.1 transformation.
Bearer Token Agent Service (com.ibi.agents.XDBearerTokenAgent)
Syntax:
com.ibi.agents.XDBearerTokenAgent
iIT Service Object:
format: Bearer Token Agent
Description: Create the authorization header with a bearer token.
Parameters:
Parameter Description
Token Store Provider*
Name of the Token Store Provider where tokens will be cached.
Authorization HeaderNamespace
Special register namespace where the Authorization HTTP headerwill be stored. If not supplied, the default namespace will be used.
Token Field Name of the field that holds the token in the JSON response.
Available Services
78 Information Builders
Parameter Description
Expiration Field Name of the field in the JSON response that specifies the length oftime (in seconds) for which the token is valid.
Default ExpirationTime
Time in seconds a token can stay in the token store. Applies onlyto tokens without a specific expiration time.
Authorization Server
Authorization ServerURL *
URL where a new access token can be retrieved. The URL shouldbe fully specified, including the https scheme.
HTTP Client Provider*
HTTP Client Provider (Pooling Provider) that manages HTTPconnections for this emitter.
HTTP Method POST sends a URL encoded entity, GET sends the request withouta request entity.
User ID User ID for authentication challenges.
Password Password for authentication challenges.
Request HeaderNamespace
Special register namespace from which HTTP headers for theoutgoing request will be taken. Choose Default Namespace to sendHDR type registers with no namespace prefix, or supply anamespace prefix here. None means that no special registers willbe sent as HTTP headers.
Response HeaderNamespace
Special register namespace into which HTTP headers from theincoming response will be saved. Choose Default Namespace tocreate special registers with no namespace prefix, or supply anamespace prefix here.
Excluded Headers A comma delimited list (case insensitive) of headers that shouldnot be sent with the request, even if found in request headernamespace.
Maximum ResponseSize
Maximum size of a response entity that can be received by thisemitter. 0 means no maximum and blank will default to 256KB.
Persistence If checked, have the server maintain the connection.
1. iWay Services
iWay Service Manager Component Reference Guide 79
Parameter Description
Response Timeoutvalue in Seconds *
Number of seconds to wait for a response before signalling anerror.
POST Request
Grant Type Specifies the requested response type. Usually client_credentials.
Client ID The Client ID of the caller.
Client Secret The Key registered for the caller.
Resource The App ID URI of the receiving web service.
Resource OwnerUsername
The username to encode in the POST body when grant type ispassword.
Resource OwnerPassword
The Password to encode in the POST body when grant type ispassword.
Special RegisterNamespace forAdditional RequestFields
If specified, registers in this namespace will be included as fieldsin body of a POST request.
Edges:
The following table lists the available Line Edges for the Bearer Token Agent Service(com.ibi.agents.XDBearerTokenAgent).
Line Edges Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
Available Services
80 Information Builders
Blank Elimination Service (com.ibi.agents.XDBlankWalk)
Syntax:
com.ibi.agents.XDBlankWalk
iIT Service Object:
sreg: Blank [whitespace] elimination
transform: Blank [whitespace] elimination
Description:
The XML standard calls for preserving blanks in element values. As a compliant parser, theiWay Service Manager preserves these spaces as per the standard. In some cases, however,users add superfluous spaces to document element values. This often arises when an XMLdocument is formatted to resemble a printed document and is then passed into the system.
The Blank Elimination service trims these extraneous blank spaces to make future XPATHs oranalysis easier.
Parameters:
Parameter Description
Method Select one of the following options to remove blank spaces:
All. Trims leading and trailing whitespaces from all element textvalues. This option is selected by default.
Empty. Trims whitespace-only element values; does not trim otherelement text values.
Edges:
The following table lists the available line edges for the Blank Elimination Service(com.ibi.agents.XDBlankWalk).
Line Edge Description
OnError Error
OnSuccess Success
1. iWay Services
iWay Service Manager Component Reference Guide 81
Line Edge Description
OnFailure Failure
OnCustom
OnError OnFailure
OnSuccess
Example:
For example, given the following input XML document:
<root> <sub> <sub2> hello </sub2> </sub> <sub3>![CDATA[ ]]</sub3></root>
When the Method parameter is set to All, the following result is generated:
<root><sub><sub2>hello</sub2></sub><sub3>![CDATA[ ]]</sub3></root>
The value of the <sub2> element was trimmed and the whitespace content of the <root> and<sub> elements was eliminated. Notice, however, that the whitespace inside the CDATA nodewas ignored.
When the Method parameter is set to Empty, the following result is generated:
<root><sub><sub2> hello </sub2></sub><sub3>![CDATA[ ]]</sub3></root>
The document is treated just as above, except that in this case, the value of the <sub2>element is not trimmed.
Cancel Service (com.ibi.agents.XDCancelAgent)
Syntax:
com.ibi.agents.XDCancelAgent
iIT Service Object:
operations: Cancel a Service
Description:
Available Services
82 Information Builders
The execution of one or more services on other execution edges of a process flow can becancelled by using the Cancel Service (com.ibi.agents.XDCancelAgent). This service acceptsthe name of one or more target services. Upon execution, a cancellation request is sent to thenamed service(s).
The cancellation capability facilitates the construction of caches, in which a slower operation(such as accessing a remote database) is run in parallel with a faster, local cache search. Ifthe cache finds the required entry in the local database, then it can cancel the sloweroperation.
A cancel operation can only be directed to a service node (agent) that supports cancellation. Inaddition, that service must be able to actually cancel. For example, the SQL Object used inprocess flows can issue a cancel operation, but the effectiveness of the cancellation willdepend upon the underlying database interfaces.
Parameters:
Parameter Description
Service to cancel*
Upon execution, the identified service(s) in this field will be sent acancellation request. The service(s) specified here should offer anOnCancel/cancellation edge to terminate the execution thread. You canspecify an individual service name, a comma-delimited list of servicenames, or a space-delimited list of service names. Service names withspaces, commas, or other special characters must be enclosed inquotes.
Edges:
The following table lists the available line edges for the Cancel Service(com.ibi.agents.XDCancelAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 83
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
In the following cache example, the CancelReal node represents the Cancel Service(com.ibi.agents.XDCancelAgent).
In this process flow, the CancelReal node is configured to cancel the AccessReal databaseaccess, which is anticipated to be slower than the AccessCache operation.
Although the local and remote sides of this process flow each go to the Junction node and thusto the End node, only one side will reach it.
Caches are very timing dependent. As a result, this example is simplified and is not intendedto show a fully working cache.
Available Services
84 Information Builders
Catch Service (com.ibi.agents.XDCatchAgent)
Syntax:
com.ibi.agents.XDCatchAgent
iIT Service Object:
operations: Catch errors in flows
Description:
Error handling in iWay Service Manager (iSM) process flows can be accomplished in a numberof different ways. Supported method and techniques include:
Explicitly checking for an error, post-service execution, by conditioning the edge with onErroror onFailure.
Including an outlet conditioned with _iserror().
Including a Catch service at the beginning of the channel. This channel has two edges onthe output side that are used for processing. The first is the onCompletion edge. Thesecond is the onCustom edge, with the onError and onFailure cases selected.
The concept of the Catch service is similar to a try-catch block in other programminglanguages.
In other programming languages, a block of code is enclosed between the braces of a trystatement. Following the try block is a catch block of code that is enclosed in braces. The codein the catch block has statements that handle any errors that might occur in the try block.
When the thread of execution starts, each line in the try block of code is executed. If eachstatement is successful, execution continues at the statement following the closing brace ofthe catch block (assuming that there is not a finally block). If an error occurs within the tryblock, the thread of execution jumps to the code inside the catch block.
In a process flow, you can add a Catch node in front of the services in which an error mightoccur. There are five edges off this service:
onCompletion
onCustom
onSuccess
onError
onFailure
1. iWay Services
iWay Service Manager Component Reference Guide 85
The completion edge is the thread of execution in which everything works in a perfect scenario.All the edges after the service connected by the onCompletion edge are then connected to theonSuccess edge.
The onCustom edge has three selected cases (onError, onFailure, and error_retry). Any errorsor failures that occur within the path of the process flow are directed down the onError andonFailure edge. The logic in this branch contains any services necessary to handle errors. Theerror_retry edge is followed when there is a retry exception. For example, when a SQL Objectcontains an invalid URL in the process flow, the onCustom/error_retry edge will be followed.
Think of the onCompletion path as the try block and the onCustom edge as the catch block.
You can add multiple Catch nodes in a process flow. The error branch is taken off the closestCatch node previous to where the error occurred. In this manner, you can add multiple errorconditions for a given process flow if required.
The catch is hierarchical and each catch is considered nested in the prior Catch node. When aCatch node is triggered, the Special Register (SREG) iway.catchname is set to the name of theCatch node that first catches the error. The register is not replaced as succeeding Catch nodessee the error. This allows higher scopes to ascertain the scope under which the original error iscaught. For example, if Task3 fails and the error is caught by CatchScope3, the register will beset to CatchScope3 even though the error may cascade through higher scopes.
Parameters:
Parameter Description
Maximum Errors The maximum number of times a Catch will be effected per forwardentry.
The Catch facility can also be configured to allow only a specified count of catches. This helpsto deal with errors in the error handler reached through the catch itself. For example, considerwhat happens in the process flow shown in Example 2 if the Write Error node fails. In thiscase, because the Write Error node does not itself provide an OnFailure edge and handle thefailure, the failure is propagated upward, where it reaches the Catch node. That node passesthe error down its failure edge, back to the Write Error node, which might again fail. If thiscontinues, a loop situation arises.
The Maximum Errors parameter allows a count of the number of times a Catch node will passthe error to an error handler (the default value is three). If the number of errors reaching theCatch node exceeds this specified count, then the Catch node does not handle the error, butrather allows the error to be propagated upward to the next higher Catch node, or (if none isencountered) terminates the process flow.
Available Services
86 Information Builders
The count is reset each time a document passes through the Catch node in the forwarddirection, so that the catch count applies only to the specific error handling situation.
It is possible to use this facility to add logic to the error handler itself. For example, you maywant to apply error handing for up to six times, but only every five seconds. Doing so wouldprovide an external system with time to accept the error. In this case, you might set theMaximum Errors parameter to six, and add a five second delay (using a Document CopyService, XDCopyAgent) into the error handler logic before attempting to deal with the error.
Example 1
In this example, consider a process flow in where three tasks are performed serially (calledTask1, Task2, and Task3). The process flow performs three tasks, as shown in the followingimage.
There is a requirement to handle errors in each task separately. So in our updated processflow, a Catch node precedes each Task node to handle errors in that task.
In this example, assume Report1 to Report3 are each an SQL object recording failures. IfTask3 (on the main line of the process flow) fails, then the failure is caught by CatchScope3.Report3 records the failure and control passes to Fail3. Fail3 is a Fail service, which has aBypass Catch Processing parameter set to true. For more information on the Fail service, see Fail Service (com.ibi.agents.XDFailAgent) on page 192.
1. iWay Services
iWay Service Manager Component Reference Guide 87
However, if Report3 fails, then the failure will be caught by CatchScope2. The Catch node forscope three does not catch the Report3 failure as it has already caught a failure. The scope inthis example tests to determine whether the failure was in its scope, in which case Report2will record the failure within the scope, or in a lower scope. It does this by the NotMe2 test,which evaluates the scope. This is a test node, which is set to the following parameter values:
This causes the extra report to be bypassed. In this case, or example uses a Trace service(Trace1, Trace2) to report the error in the lower scope to a simple trace message. Followingthe trace message reporting a failure in a lower scope, the process flow uses a Fail service toissue the fail that did not get issued in the lower scope. This maintains the statistics of thechannel.
In the multiple Catch node use case, setting the Bypass Catch Processing parameter of theFail node to true will cause the failure request to bypass upper-level Catch nodes, avoiding theneed for scope testing (such as with the example in the My Scope tests in upper scopes).
Example 2
In this example, a file is put into a directory after its creation from a previous channel. Thesample process flow is responsible for transmitting the file to the customer FTP site.
Since this is an FTP site, it is subject to network and site availability and other possibleoutside issues. An error handling strategy is required so that none of the documents beingprocessed are lost because of an outside issue.
Available Services
88 Information Builders
In process flow, the Catch node immediately follows the Start block. An onCompletion edgeconnects the Catch Errors block to the FTP Write block. The FTP Write block is an FTP emitterthat is set up to write the file to an FTP site. The service directly following the XDCatchAgent(Catch Errors) must have an onCompletion edge for this to work correctly.
Following the FTP Write block is the End block. The edge connecting these two services is anonSuccess edge. If a different edge were used and an error occurred, the error edge off ofCatch Errors may not be executed.
The onCustom edge of Catch Errors has the onError and onFailure cases selected for theproperties. This edge leads to a file write service, Write Error, that puts the file into a holddirectory for later reprocessing. Following Write Error, there is an End with a Terminate since nofurther processing is required at this point. In a real world scenario, a requirement might bethat an email is sent if the site is down.
When the target FTP site is up and available, the files are written to the FTP site. If the FTP siteis down or you cannot connect to it, the FTP write service will generate an error. This errorcauses the next execution point to be the File Write to save the file for further processing.
Channel Information Service (com.ibi.agents.XDChanInfoAgent)
Syntax:
com.ibi.agents.XDChanInfoAgent
iIT Service Object:
operations: Server Statistics
Description:
This service returns an XML document that contains the current status information for thesystem. The service is also available for use in process flows. Each channel (represented by amaster tag) is included in the XML output, along with statistics on its current state.
Properties:
Property Description
Info Root of the information tree.
Channels The configured runtime channels.
Properties of statistics per channel (master)
1. iWay Services
iWay Service Manager Component Reference Guide 89
Property Description
name Name of the channel. There is one master for each defined channel,regardless of its state.
state State of the channel (active for started channel), runnable for deployed(not started) channel, stopping for the channel that is stopping.
Begin. Channel has been started, but has not yet completed theinitialization.
Config. Errors were found during the initialization and the channelcannot start.
Retry. The channel initialization (or sometimes the execution phase)found a condition that is an error not related to the configuration. Thechannel can be automatically restarted at a later time.
failed Number of times the channel execution failed.
completed Number of times the channel execution completed.
active Indicates whether the channel is active.
Properties of statistics per execution
user User CPU time statistics.
cpu CPU time statistics.
name Name of the thread (required). Thread masters always have workerthreads to execute messages.
Properties of statistics per transaction
variance Variance of transaction time.
ehrlang Ehrlang coefficient.
mean Mean (average) time of transactions.
internalqs
Internal listeners are associated with queues. This section describes the queuesthemselves.
Available Services
90 Information Builders
Property Description
queue The name of this queue. Usually this is the name of the internal listenerthat defines the queue (optional).
size Number of messages waiting to be processed.
Edges:
The following table lists the available line edges for the Channel Information Service(com.ibi.agents.XDChanInfoAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
1. iWay Services
iWay Service Manager Component Reference Guide 91
Example:
The following is a sample of an XML document that is returned by the service:
<info> <channels> <master name="internal" state=" active " type="Internal" completed="0"failed="0" active="0" available="1"> <user mean="0.0" variance="0.0" ehrlang="1.0"/> <cpu mean="0.0" variance="0.0" ehrlang="1.0"/> <threads group="internal"> <thread name="W.internal.1"/> </threads> </master> <master name="file1" state=" active " type="FILE" completed="0"failed="0" active="0" available="4"> <user mean="0.0" variance="0.0" ehrlang="1.0"/> <cpu mean="0.0" variance="0.0" ehrlang="1.0"/> <threads group="file1"> <thread name="W.file1.1"/> <thread name="W.file1.2"/> <thread name="W.file1.3"/> <thread name="W.file1.4"/> </threads> </master> </channels> <internalqs> <queue name="internal1" size="0"/> </internalqs></info>
Check Schema Service (com.ibi.agents.XDCheckSchema)
Syntax:
com.ibi.agents.XDCheckSchema
iIT Service Object:
misc: Check Document Against External Schema
Description:
The XDCheckSchema service evaluates an input document against a specified schema. Inscenarios where a schema represents an agreement between the sender of a document andthe receiver (for example, iWay Service Manager), schema checking is important for debuggingpurposes. It has lesser importance during actual production. However, this is ultimately anapplication design decision.
Note: Checking a schema can consume system resources and processing time. As a result, itis not recommended during operation in production environments.
Available Services
92 Information Builders
Parameters:
Parameter Description
Schema File The source of the schema to be applied to the incoming document. You canspecify a file path directly in this field, or select one of the following valuesfrom the drop-down list:
route {$route}. A schema published to the selected route that iscurrently managing the channel.
start node {$start}. A schema specified on the Start object of theprocess flow.
SchemaName
If the schema is packaged in a .zip archive file, which is specified in theSchema File field, then the name of the schema file (for example, xyz.xsd)must be provided.
Strictness * Determines the level of schema testing that should be applied. Select oneof the following values from the drop-down list:
strict (default). The document must validate. Failure to validate resultsin a fail_parse result.
optional. If the schema is located, then the document must validate. Ifthe schema cannot be located, then the document validation is ignored.
Is TargetNamespaceEnabled
false (default). There is no namespace to apply.
true. There is a namespace to apply.
TargetNamespaceLocation
Target Namespace location. This property is mandatory if the preceedingproperty is set to true.
When When to perform this operation.
Always (default) at each execution.
On debug, when running in debug mode.
1. iWay Services
iWay Service Manager Component Reference Guide 93
Edges:
The following table lists and describes the edges that are returned by the XDCheckSchemaservice.
Edge Description
success Successful.
fail_parse The schema could not be parsed or the document failed the schemacheck.
fail_missingschema The schema could not be found.
fail_format The format of the input document was not compatible (for example,not in XML format).
Available Services
94 Information Builders
Example:
In this example, an absolute path to a schema is specified for the Schema File property.
Instead of providing an absolute path to the schema, you can also specify the location of a .ziparchive file where the schema is packaged. In this case, you must also provide a value for theSchema Name property, which will direct this service to the root schema in the .zip archive file.For example:
Schema File. c:\temp\abc.zip
Schema Name. sample1.xsd
1. iWay Services
iWay Service Manager Component Reference Guide 95
Strictness. strict
You can also select route or start node from the Schema File drop-down list. If route isselected, then the schema is retrieved from the route that is currently managing the channel. Ifstart node is selected, then the schema is retrieved from the process flow Start object, asshown in the following image.
When the process flow is executed, the input file is validated against the specified schemaand an appropriate output document is generated.
Commit or Rollback within a Flow (com.ibi.agents.XDCommitAgent)
Syntax:
com.ibi.agents.XDCommittAgent
iIT Service Object:
operations: Commit/Rollback during flow
Available Services
96 Information Builders
Description:
Like the XDCatchAgent, this service serves as a placeholder for a process flow function.Unless the Supports Local Transaction attribute is set in the listener of the channel, this nodeis a functional NOP.
When operating in Local Transaction mode, database and other operations begun by nodeswithin the flow are committed or rolled back based on the final status of the flow itself. Thecommit or rollback is performed within the constraints of the local transaction capability of theserver.
The XDCommitAgent, when encountered in a flow, causes a commit or a rollback operation totake place immediately. This allows two or more transactions in a single flow. Use of thiscapability is dependent on application design.
The agent is configured for commit or rollback. This is not possible using iFL.
When encountered, the commit handler awaits completion of all other threads in the flow, ifany. It then calls the commit manager to commit or roll back work established to date. This inturn causes all open connections to be released. The specific action on a commit or roll backis dependent on the resource being affected. Note that mis-specification of set or synch waitscan cause the flow to enter a deadlock condition.
Once committed, the data cannot be rolled back, regardless of the manner in which the flowactually ends. The node is a punctuation within the flow, and users should consider actionssubsequent to the commit or rollback as a separate flow.
A common use of such a capability is with a Catch node. If catch traps an error, the error edgemight issue a roll back and then proceed to take other action to record or recover from theerror.
Edges:
The following table lists the available line edges for the Channel Information Service(com.ibi.agents.XDChanInfoAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 97
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_operations
Constant Service (com.ibi.agents.XDConstantAgent)
Syntax:
com.ibi.agents.XDConstantAgent
iIT Service Object:
misc: Constant Agent
Description:
Replaces the input document with a constant document. Because all parameters are evaluatedwith the iWay Functional Language (iFL), this service is frequently used to modify the input orload a file from a disk, and so on.
Parameters:
Parameter Description
Constant Output ToEmit *
The value that will be emitted by the Constant service. If theOutput Format parameter value is set to xml, this value needs tobe valid XML, otherwise the original input document can beemitted based on the Input Criterion parameter value.
Output Format * The output format of the result.
Select one of the following values from the drop-down list:
xml (default). This value emits a valid XML output.
flat This value emits output as flat text.
Available Services
98 Information Builders
Parameter Description
Output as Error Determines whether the input should be emitted as an errordocument. Select true or false (default) from the drop-down list.
Input Criterion Emit status criteria based on input type, else copy. Select one ofthe following values from the drop-down list:
always (default). Emits the constant regardless of the inputdocument's format.
xmlonly. If the input document is XML, emit the constant,otherwise emit the original input document.
flatonly. If the input document is flat, emit the constant,otherwise emit the original input document.
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
Edges:
The edges returned are listed in the following table.
Edge Description
success Successful.
fail_parse An iFL expression could not be evaluated.
Example:
If you run this service using any input document, the same constant document output isreturned. For example, if you are using <a>aaa</a> as a constant, the following is the result:
<?xml version="1.0" encoding="UTF-8" ?><a>aaa</a>
1. iWay Services
iWay Service Manager Component Reference Guide 99
Controls Listeners Service (com.ibi.agents.XDControlAgent)
Syntax:
com.ibi.agents.XDControlAgent
iIT Service Object:
control: Controls Listeners
Description:
The Controls Listeners service enables or disables one or more listeners or channels. Thisfunctionality enables logical control of the server configuration from within a process flow. Thefollowing are the supported control operations/actions:
start
pause
pulse
stop
Using the Controls Listeners service, the activity on one listener can control another. Forexample, the detection of a message in an MQ Series queue can trigger an RDBMS listener tobegin working with a relational table.
Parameters:
Parameter Description
Listener(s) Fully qualified name of listener(s) or channel(s) to control (for example,group:inlet:listenername), can be comma-separated list. Partial names canbe entered with an ending asterisk character (*), meaning all with namesstarting with the entry characters.
Available Services
100 Information Builders
Parameter Description
Action Select one of the following operations/actions from the drop-down list:
start. Named listener or channel is started, if necessary. It is enabledfor acquiring messages. This action is selected by default.
pause. Named listener or channel is disabled for acquiring messages.This may not take effect immediately. The listener or channel remainsactive and no resources are released.
pulse. Named listener or channel is started (or enabled) to acquiremessages. It runs through one acquisition cycle (for example, reading allrows in a RDBMS table) and is then stopped.
Note: The pulse action can be used with pull and poll types of listeners(for example, JMS, SQL, and File). Applications that depend upon pulsingshould be designed with care.
stop. Named listener or channel is stopped. All resources are released.
Call at EOS? In a streaming environment, EOS (End of Stream) is the short message thatis sent after the last document, which signifies the EOS. This parameterdetermines whether this service should be called for the EOS message. Thedefault value is false.
Edges:
The following table lists the available line edges for the Controls Listeners service(com.ibi.agents.XDControlAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 101
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
Example:
You can use the Controls Listeners service to stop a channel that is currently running in iWayService Manager (iSM). In a process flow, configure a Service object using the ControlsListeners service (com.ibi.agents.XDControlAgent). Click the Properties tab. For the Listener(s)parameter, specify the name of the channel that you want to stop (for example, default).
Available Services
102 Information Builders
Invoke the channel that contains the Controls Listeners service process flow in the route with avalid XML document. The stop command for the default channel will be issued. If the defaultchannel is currently running, then it will be stopped.
You can verify this action by examining the status change for the default channel in theChannel Management pane after successfully passing the XML document through the ControlsListeners service channel.
Notice that the default channel is now stopped.
Control Activity Log Exit Service (com.ibi.agents.XDXalogControlAgent)
Syntax:
com.ibi.agents.XDXalogControlAgent
iIT Service Object:
xalog: Activity Log Control
contol: Activity Log Control
Description:
Activity log exits accept messages pertaining to activities in the server, and report theseactivities to some external media. A common exit is the BAMActivityProvider. Other exits relateto SNMP, time tracking, and so on. The exits are defined and deployed for the configuration,and may initially be defined as being in an active or inactive state. Active state refers, as in allcomponents, to whether the exit is initialized and started automatically when the server isinitialized.
These exits can be configured for the server in the Activity Facility section of the iSMAdministration Console.
This service can be used in a process flow to start or stop the named activity log exit. Youmight use this, for example, in a BAM error recovery flow to restart the exit that has beenstopped due to a database error.
1. iWay Services
iWay Service Manager Component Reference Guide 103
Parameters:
Parameter Description
Exit The name of the Activity Facility exit to be controlled. This exit must beavailable.
Action Determines the action to be taken. Select one of the following actions fromthe drop-down list:
start
stop
Call at EOS? In a streaming environment, EOS (End of Stream) is the short message thatis sent after the last document, which signifies the EOS. This parameterdetermines whether this service should be called for the EOS message. Thedefault value is false.
Edges:
The edges returned by the Control Activity Log Exit service(com.ibi.agents.XDXalogControlAgent) are listed and described in the following table.
Edge Description
success The requested action has been initiated. Theoperation of the server is generally asynchronous, sothis only means that the start activity has beeninitiated.
fail_parse The configuration parameters cannot be understood.
fail_notfound The named exit cannot be located in the set ofdeployed exits.
fail_operation The requested action failed for some other reason.
Cookie Store Agent Service (com.ibi.agents.XDCookieStoreAgent)
Syntax:
Available Services
104 Information Builders
com.ibi.agents.XDCookieStoreAgent
iIT Service Object:
format: Cookie Store Agent
Description: Performs an action on a cookie store.
Parameters:
Parameter Description
Action * The action to perform.
HTTP Client Provider The action will be performed on a cookie store within this HTTPClient Provider.
Cookie Store Name The action will be performed on this cookie store. Leave empty forthe default cookie store of the specified HTTP Client Provider.
Edges:
The following table lists the available Line Edges for the Cookie Store Agent Service(com.ibi.agents.XDCookieStoreAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
Correl Inquiry By State Service (com.ibi.agents.XDCorrelInquiryByStateAgent)
Syntax:
com.ibi.agents.XDCorrelInquiryByStateAgent
iIT Service Object:
1. iWay Services
iWay Service Manager Component Reference Guide 105
misc: Correl Inquiry By State Agent
Description:
Returns a document listing all correlation IDs in the requested state. For more information, seethe Correlation Facility topic in the iWay Service Manager User's Guide.
Parameters:
Parameter Description
Namespace Namespace for Correlation ID. IDs will normally be unique within anamespace.
Correlation Status * Return correlation IDs in this state.
Inquire By * Which date should be used in search?
Updated Since * Where record has been inserted or updated within this duration.
Include History? * If set to true, correlation history is included in the report.
Edges:
The following table lists the available line edges for the Correl Inquiry By State Service(com.ibi.agents.XDCorrelInquiryByStateAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
Available Services
106 Information Builders
Correl Inquiry Service (com.ibi.agents.XDCorrelInquiryAgent)
Syntax:
com.ibi.agents.XDCorrelInquiryAgent
iIT Service Object:
misc: Correl Inquiry Agent
Description:
Returns an XML report on the specified correlation ID. For more information, see theCorrelation Facility topic in the iWay Service Manager User's Guide.
Parameters:
Parameter Description
Correlation ID * Identifier for the correlated process. This is normally a runtimefunction, such as XPATH() or SREG().
Namespace Namespace for Correlation ID. IDs will normally be unique within anamespace.
Output Type * Should agent simply output its input, or should it output an XMLcorrelation report?
Include History? * If set to true, correlation history is included in the report.
Edges:
The following table lists the available line edges for the Correl Inquiry Service(com.ibi.agents.XDCorrelInquiryAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 107
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
open
closed
notfound fail_operation
Correl Set Inquiry Service (com.ibi.agents.XDCorrelSetInquiryAgent)
Syntax:
com.ibi.agents.XDCorrelSetInquiryAgent
iIT Service Object:
misc: Correll Set Inquiry Agent
Description:
Returns a document describing the status of the requested correlation set ID. For moreinformation, see the Correlation Facility topic in the iWay Service Manager User's Guide.
Parameters:
Parameter Description
Correlation Set ID Identifies the set with which this correlation ID is associated. This istypically a batch or envelope identifier, expressed using a runtimefunction.
Namespace Namespace for Correlation ID. IDs will normally be unique within anamespace.
Available Services
108 Information Builders
Edges:
The following table lists the available line edges for the Correl Set Inquiry Service(com.ibi.agents.XDCorrelSetInquiryAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
open
closed
notfound
fail_operation
C Char Filter Service (com.ibi.agents.CCharFilter)
Syntax:
com.ibi.agents.CCharFilter
iIT Service Object:
misc: C Char Filter
Description:
Some input documents contain control characters such as tabs or bells. This service replacesor removes such characters.
1. iWay Services
iWay Service Manager Component Reference Guide 109
Parameters:
Parameter Description
Linefeed * Determines whether to remove linefeed characters (\r). Select true(default) or false.
Carriage Return*
Determines whether to remove carriage returns (\n). Select true(default) or false.
Tab * Determines whether to remove tab (\t) characters. Select true (default)or false.
End of File * Determines whether to remove DOS end of file (0x1a) characters.Select true (default) or false.
Bell * Determines whether to remove bell (0x07) characters. Select true(default) or false.
Control
Replace With * Replace removed characters with this character. Select none (default),space, or period (.) from the drop-down list.
Edges:
The following table lists the available line edges for the C Char Filter Service(com.ibi.agents.CCharFilter).
Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
Available Services
110 Information Builders
Example:
If you need to replace a new line character in an incoming document with a period (.), thisservice needs to be configured with default parameter values, except for the Replace Withparameter value, which must be set to period (.). The result of passing the incoming documentwith a new line character inside the <Test> tags is:
<?xml version="1.0" encoding="UTF-8" ?><Test>.</Test>
Cross-Origin Resource Sharing Service (com.ibi.agents.XDCorsAgent)
Syntax:
com.ibi.agents.XDCorsAgent
iIT Service Object:
http: Cross-Origin Resource Sharing
Description:
This service implements the server-side processing of Cross-Origin Resource Sharing (CORS)as described in http://www.w3.org/TR/cors/.
Normally, browsers forbid cross-origin requests for security reasons. CORS specifies amechanism that allows browsers to make cross-origin requests to resources that opt in toprovide access. CORS defines a set of HTTP headers and the rules to process them. Mostcommon browsers implement CORS natively. It is expected that the user agent making therequest will be a browser. The CORS service implements the server-side rules to respond toCORS requests received by an nHTTP listener.
If the request is simple (such as GET, HEAD, or POST), then the user agent (for example, thebrowser) can make the request directly. The user agent adds the Origin header to indicatewhich site is asking for this resource. The syntax of an origin is:
scheme "://" host [ ":" port ]
The same syntax is used to configure the allowed origins in the service.
If the request is not simple, then the user agent must send a pre-flight request before theactual request to authorize it. The pre-flight request is an OPTIONS request for the same URL.The Access-Control-Request-Method header indicates the method of the actual request (forexample, PUT). The optional Access-Control-Request-Headers header indicates which headerswill be used in the actual request. Depending on the response of the pre-flight request, theuser agent can abort or make the actual request following the same rules as a simple request.
1. iWay Services
iWay Service Manager Component Reference Guide 111
The CORS service analyzes the request, and depending on its configuration, will report one ofthe following results:
The request is allowed (allowed).
The request is not allowed (notallowed).
The request is not CORS compliant (notcompliant).
In accordance with the specification, the CORS service adds the CORS response headers onlyif the request is allowed. The new headers appear as Special Registers (SREGs) in theResponse Header Namespace.
The CORS service sets the output document of an OPTIONS request to a zero-length byte array.This will return an empty body with Content-Length equal to 0. This is the most appropriateresult, but an application can modify the output document afterwards if necessary. For otherrequests, the CORS service returns the input document as the output document. Unlike theheaders, the output document will be the same irrespective of the actual outcome (allowed,notallowed, or notcompliant).
The nHTTP listener must be configured carefully to make CORS processing possible. TheOPTIONS Handling property must be set to event. This instructs the listener to pass therequest to the channel instead of responding directly. The Request Header Namespace andthe Response Header Namespace must not be none, and they must be different from eachother. This makes the request headers available to the CORS service, and allows the responseheaders be sent with the response. Of course, the Excluded Headers property should not listthe CORS headers. The HTTP Response Code must be 200 for a CORS pre-flight response. TheAuthentication Scheme and the Authentication Realm properties should be consideredcarefully. CORS is a mechanism used to relax security. It does not replace the need for usercredentials to protect sensitive data.
Available Services
112 Information Builders
Parameters:
The following table describes the parameters for the Cross-Origin Resource Sharing Service.
Parameter Description
Allowed Origins List of origins that are allowed access to the resource. Leave empty orenter * to allow all origins. The syntax of an origin is:
scheme "://" host [ ":" port ]
This property is used to validate the Origin header in the request andinfluences the value of the Access-Control-Allow-Origin header in theresponse. The return value of the Access-Control-Allow-Origin headerwill be * if the Allowed Origins is * and Supports Credentials is false.
Allowed Methods Comma-separated list of HTTP methods that are supported by theresource. Leave empty to allow all methods. This is used to validatethe Access-Control-Request-Method header in the pre-flight requestand to initialize the Access-Control-Allow-Methods header in the pre-flight response.
SupportedHeaders
Comma-separated list of HTTP header field names that are supportedby the resource. Leave empty to claim support for all headers. This isused to validate the Access-Control-Request-Headers header in thepre-flight request and to initialize the Access-Control-Allow-Headersheader in the pre-flight response.
Exposed Headers Comma-separated list of HTTP header field names of headers (otherthan the simple response headers) that the resource might use andcan be exposed. This is used to initialize the Access-Control-Expose-Headers header in the response of the actual request.
SupportsCredentials
Indicates whether the resource supports user credentials in therequest. This is used to initialize the Access-Control-Allow-Credentialsheader in the response. Notice the return value of the Access-Control-Allow-Origin header will never be * for a resource that supportscredentials.
1. iWay Services
iWay Service Manager Component Reference Guide 113
Parameter Description
Max Age Specifies the amount of seconds the user agent (for example, thebrowser) is allowed to cache the result of the pre-flight request. Thevalue 0 means unbounded. This is used to initialize the Access-Control-Max-Age header in the response of the pre-flight request.
Edges:
The following table lists the available line edges for the Cross-Origin Resource Sharing Service(com.ibi.agents.XDCorsAgent).
Line Edge Description
OnError Error
OnSuccess Success: The message was successfullyanalyzed. The cors Special Registercontains the result.
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation: the service is notexecuting a request received by annHTTP listener.
open
closed
notfound
Available Services
114 Information Builders
Special Registers:
The following table describes the Special Register (SREG) that is assigned upon a successfulexecution.
SpecialRegister
Description
cors The outcome of analyzing the request. This will be one of the followingvalues:
allowed
notallowed
notcompliant
Note: These values are lowercase and do not contain any spaces.
Examples
The following examples show the result of executing the Cross-Origin Resource Sharing Serviceon various HTTP requests. The following table lists the parameter values for the Cross-OriginResource Sharing Service that are used by the examples.
Parameter Value
Allowed Origins http://host1.com http://host2.com:8080
Allowed Methods GET,POST
Supported Headers ReqHdr1,ReqHdr2,ReqHdr3
Exposed Headers RespHdr1,RespHdr2
Supports Credentials true
Max Age 30
1. iWay Services
iWay Service Manager Component Reference Guide 115
Example 1
This HTTP request is missing the Origin header. When analyzing this request, the service wouldset the cors Special Register to notcompliant and return success. No response headers wouldbe added. The output document is the input document.
GET /app/page1 HTTP/1.1Host: example.com
Example 2
Since the Allowed Origins is not empty or *, the origin must match exactly one of the listedorigins. When analyzing this request, the service would set the cors Special Register tonotallowed and return success. No response headers would be added. The output document isthe input document.
GET /app/page1 HTTP/1.1Host: example.comOrigin: http://host.com
Example 3
When analyzing this request, the service would set the cors Special Register to allowed andreturn success. The output document is the input document.
GET /app/page1 HTTP/1.1Host: example.comOrigin: http://host1.com
The following response headers will be added:
Access-Control-Allow-Origin: http://host1.comAccess-Control-Expose-Headers: RespHdr1,RespHdr2Access-Control-Allow-Credentials: true
Example 4
This pre-flight request is missing the Access-Control-Request-Method header. When analyzingthis pre-flight request, the service would set the cors Special Register to notcompliant andreturn success. No response headers would be added. The output document is a zero-lengthbyte array.
OPTIONS /app/page1 HTTP/1.1Host: example.comOrigin: http://host1.com
Available Services
116 Information Builders
Example 5
The actual request method HEAD is not allowed. When analyzing this pre-flight request, theservice would set the cors Special Register to notallowed and return success. No responseheaders would be added. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1Host: example.comOrigin: http://host1.comAccess-Control-Request-Method: HEAD
Example 6
The header names in Access-Control-Request-Headers are all supported headers. Whenanalyzing this pre-flight request, the service would set the cors Special Register to allowed andreturn success. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1Host: example.comOrigin: http://host1.comAccess-Control-Request-Method: GETAccess-Control-Request-Headers: ReqHdr1,ReqHdr2
The following response headers will be added:
Access-Control-Allow-Origin: http://host1.comAccess-Control-Allow-Methods: GET,POSTAccess-Control-Allow-Headers: ReqHdr1,ReqHdr2,ReqHdr3Access-Control-Allow-Credentials: trueAccess-Control-Max-Age: 30
Data Quality Center Service (Non-Pooling, Deprecated) (com.ibi.agents.XDDQAgent)
Syntax:
com.ibi.agents.XDDQAgent
iIT Service Object:
DQS: Data Quality Service Agent (non-pooling, deprecated)
Description:
This service marshals data and processes data using an iWay Data Quality Provider.
Note: This service is deprecated. The Data Quality Center Service (Document-Driven, Pooling),com.ibi.agents.XDDQAgent2, should be used instead.
1. iWay Services
iWay Service Manager Component Reference Guide 117
Parameters:
Parameter Description
Data Quality Provider * The name of the configured Data Quality provider that shouldbe invoked by this service.
XPath Expression * Specify an XPath expression that will return one or moreelements from the input document that will be used as inputrecords when the iWay Data Quality Center (DQC) plan isinvoked.
XPath Namespace Map If the input document contains namespaces, then thisparameter specifies the configured namespace map to beused when evaluating XPath expressions.
Replace or Preserve? * Determines whether the children of the record element in theoutput document should be preserved (appending the resultof the iWay DQC plan execution as new child elements), orshould the original children be replaced with the iWay DQCplan results.
Select one of the following options from the drop-down list:
Replace
Preserve
By default, replace is selected.
Deflate Service (com.ibi.agents.XDDeflateAgent)
Syntax:
com.ibi.agents.XDDeflateAgent
iIT Service Object:
exit_preemit: Deflate Agent
misc: Deflate Agent
Description:
Available Services
118 Information Builders
This service is used to compress the document for transmission or storage. The document isflattened to a byte stream, and compression algorithms are applied. The output of this serviceis a flat document.
Parameters:
Parameter Description
Method ofcompression to use *
Determines what format of compression should be used on theoutput. Select one of the following options from the drop-downlist:
none (default). No compression is used.
smallest. The smallest possible output, regardless of theexecution time.
fastest. The fastest possible execution time, even if thedegree of deflation is reduced.
standard. A compromise between smallest and fastest isused.
Huffman. An entropic encoding scheme is applied.
Edges:
The edges returned are listed in the following table.
Edge Description
success Successful operation.
fail_operation The decompression could not be performed. The data is probably notdeflated.
Deidentification Service (com.ibi.agents.XDDeidentifyAgent)
Syntax:
com.ibi.agents.XDDeidentifyAgent
iIT Service Object:
1. iWay Services
iWay Service Manager Component Reference Guide 119
transform: De-identify an XML Document
Description:
The Deidentification service provides algorithms that can be used to implement the de-identification of protected health information in accordance with the Health InsurancePortability and Accountability Act (HIPAA) Privacy Rule. Multiple algorithms can be configuredsince a combination of algorithms will be needed to deidentify the data correctly.
The Deidentification service takes an XML document as input. The first configured algorithmtakes this document as input and modifies it in place. The result is fed into the next configuredalgorithm and so on. The result of the last configured algorithm is the XML document returnedby the service.
Parameters:
The following table lists and describes the parameters common to all algorithm instances.
Parameter Description
XML Namespace Provider Provider for the mapping between XML namespace prefixand namespace URI in XPath expressions. If left blank,XPath expressions cannot contain namespaces.
Xpath Syntax Determines which syntax level of XPath should be used.The default option selects the syntax level as set in theconsole global settings.
The following table lists and describes the parameters for the first algorithm instance.
Parameter Description
Name1 Determines the de-identification algorithm to perform.
Argument1 The argument value for de-identification algorithms that takean argument .
Targetnodes1 An XPath expression that returns a nodeset. The de-identification algorithm will be applied to each node in thenodeset. If XML Namespace prefixes are used, they mustbe declared in the XML Namespace Provider.
Available Services
120 Information Builders
For more information about the available algorithms and the meaning of the argument, see thefollowing section.
Edges:
The following table lists the available line edges for the Deidentification Service(com.ibi.agents.XDDeidentifyAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
The Deidentification service offers explicit parameters for up to 5 algorithm instances:Algorithms 1 to 5. Extra instances can be created if more than five algorithm instances areneeded. Instances for algorithm 6 and above can be created with user parameters named:
algorithmNNargNNtargetNN
Where:
NN
Is the instance number.
For example, the sixth algorithm instance can be created with the user parameters:argument6, arg6, and target6. There is no limit on the value of NN, though the instancenumbers must be consecutive to be recognized. The service stops looking for more algorithminstances as soon as it finds one that is not configured. For example, if Algorithm 3 is notconfigured, Algorithm 4 and 5 will be ignored.
1. iWay Services
iWay Service Manager Component Reference Guide 121
Algorithms:
The following table describes the available alogrithms in the Deidentification service.
Algorithm Argument Description
Encrypt FormattedDigits
encryption key Maps the digits in a formatted string with 4x4Playfair algorithm. The encryption key shouldcontain only digits, and is padded if necessaryto make it 16 digits long. Playfair works withpairs of characters. When the number of digitsin the input is odd, the input is padded by onecharacter and one character is ignored in theoutput. There is no validation of the resultingnumber. The algorithm will always produce thesame output for the same input when usingthe same key. The mapping is not reversible.Different input might map to the same output,though this is not common. Only the digits aremapped, the other characters are preserved atthe same position. For example,(212)223-3333 might map to (655)887-2424with the format characters preserved.
Available Services
122 Information Builders
Algorithm Argument Description
Encrypt SSN encryption key Maps Social Security Numbers by encryptingthem with 4x4 Playfair algorithm. Theencryption key should contain only digits, andis padded if necessary to make it 16 digitslong. Playfair works with pairs of characters.The input is padded by one character. Theoutput is 10 digits long and the last characteris eliminated to make it 9 digits long. Thealgorithm will never produce a Social SecurityNumber starting with 9, starting with 666, orwith all zeroes in any of the three groups: 000-xx-xxxx, xxx-00-xxxx, and xxx-xx-0000. If theresulting Social Security Number is invalid, theoutput is re-encrypted until it becomes valid.The algorithm will always produce the sameencrypted SSN for the same input SSN whenusing the same key. The mapping is notreversible. Different input SSN might map tothe same encrypted SSN. Only the digits aremapped, while the other characters arepreserved at the same position. For example,111-22-3333 might map to 655-88-2233 withthe hyphens preserved.
1. iWay Services
iWay Service Manager Component Reference Guide 123
Algorithm Argument Description
Sequential SSN unused Maps Social Security Numbers to numbers inconsecutive increasing order starting with001010001. The numbers produced adhere tothe rule used by Social Security Administrationon June 25, 2011 and later. The algorithm willnever produce a Social Security Number withall zeroes in any of the three groups: 000-xx-xxxx, xxx-00-xxxx, and xxx-xx-00000. Only thedigits are mapped, while the other charactersare preserved at the same position. Forexample, 111-22-3333 might map to001-01-0035 with the hyphens preserved.Within a single run, a previously mapped SSNwill map to the same number it was assignedearlier. The mapping is not preserved acrossruns.
Text Constant new text Replaces the contents of an element by astring constant. The element keeps itsattributes, but all existing mixed contentchildren are removed. The argument isevaluated once to obtain the string constant.
Random Day date pattern Parses a date using the pattern in theargument, replaces the day and month withrandom values, and clips the year to at most90 years ago. The argument is evaluated onceto obtain the date pattern inSimpleDateFormat syntax.
Available Services
124 Information Builders
Algorithm Argument Description
Text Eval iFL expression Replaces the contents of an element by astring obtained by evaluating an iFLexpression. The element keeps its attributes,but all existing mixed content children areremoved. The argument is evaluated for eachtarget node processed. The existing text valueof the element is stored in the special registeriway.value. The new value can depend on theexisting value by calling _sreg (iway.value)within the iFL expression.
XML Constant XML String Replaces the contents of an element by aconstant XML fragment. The element keeps itsattributes, but all existing mixed contentchildren are removed. The argument isevaluated once to obtain an XML string. TheXML string is parsed for each target node,using the XML Namespace context of thatnode.
XML Delete unused Deletes the XML target nodes. The node itself,its attributes, and all mixed content childrenare removed.
XML Eval iFL expression Replaces an XML element by the result of aniFL expression parsed as XML. The node itself,its attributes, and all mixed content childrenare removed. The argument is evaluated foreach target node processed. The resultingXML String is parsed using the XMLNamespace context of the parent node. Thefirst element of the resulting XML fragment isthe new element replacing the target node.The new value can depend on the old valuebecause the old element is passed as the rootof the document during evaluation. Forexample, the _XPATH() function can be calledto extract values from the old node.
1. iWay Services
iWay Service Manager Component Reference Guide 125
Algorithm Argument Description
XML Replace XML String Replaces an element by a constant XMLelement. The node itself, its attributes, and allmixed content children are removed. Theargument is evaluated once to obtain an XMLstring. The XML string is parsed for each targetnode, using the XML Namespace context ofthe parent of that node. The first element ofthe resulting XML fragment is the new elementreplacing the target node.
Zip Keep First 3 unused Keeps the first three digits of the five digit zipcode followed by 00. The four digit code afterthe hyphen is ignored when present. Forexample, 10121-2898 becomes 10100.
Zip Keep last 2 unused Keeps the last two digits of the five digit zipcode preceded by 000. The four digit codeafter the hyphen is ignored when present. Forexample, 10121-2898 becomes 00021.
Example:
The following example shows the effect of various algorithms. The following table lists theparameter values.
Parameter Value
Name 1 Sequential SSN
Target Nodes 1 /workforce/employee/ssn
Name 2 Text Constant
Argument 2 John Doe
Target Nodes 2 /workforce/employee/name
Name 3 Text Eval
Available Services
126 Information Builders
Parameter Value
Argument 3 _sreg(iway.value) - _imod(_sreg(iway.value),10)'-'_sreg(iway.value) - _imod(_sreg(iway.value),10) + 9
Target Nodes 3 /workforce/employee/age
Name 4 XML Constant
Argument 4 <street>1731 Technology Drive</street><city>San Jose</city><state>CA</state><zip>95110</zip>
Target Nodes 4 /workforce/employee/address
Name 5 XML Delete
Target Nodes 5 /workforce/employee/title
The following is a sample input document.
<workforce> <employee> <name>Harry Smith</name> <address> <street>2 Penn Plaza</street> <city>New York</city> <state>NY</state> <zip>10121</zip> </address> <title>Marketing Director</title> <age>48</age> <ssn>078-05-1120</ssn> </employee> <employee> <name>Mary Dickens</name> <address> <street>10375 Richmond</street> <city>Houston</city> <state>TX</state> <zip>77042</zip> </address> <title>Sales Engineer</title> <age>48</age> <ssn>165-16-7999</ssn> </employee></workforce>
The resulting service output is shown below.
1. iWay Services
iWay Service Manager Component Reference Guide 127
<workforce> <employee> <name>John Doe</name> <address> <street>1731 Technology Drive</street> <city>San Jose</city> <state>CA</state> <zip>95110</zip> </address> <age>40-49</age> <ssn>001-01-0001</ssn> </employee> <employee> <name>John Doe</name> <address> <street>1731 Technology Drive</street> <city>San Jose</city> <state>CA</state> <zip>95110</zip> </address> <age>30-39</age> <ssn>001-01-0002</ssn> </employee></workforce>
Delete an Item (com.ibi.agents.XDDynamoDBDeleteItem)
Syntax:
com.ibi.agents.XDDynamoDBDeleteItem
iIT Service Object:
format: Delete an Item
Description: Deletes an item from the table.
Parameters:
Parameter Description
Access key * The access key provided by Amazon.
Secret Key * The secret key provided by Amazon.
Region * AWS Region is a separate geographic area, for example"US_EAST_1".
Available Services
128 Information Builders
Parameter Description
Request Timeout * Sets the amount of time to wait (in milliseconds) for the request tocomplete before giving up and timing out.
ConnectionTimeout * Sets the amount of time to wait (in milliseconds) when initiallyestablishing a connection before giving up and timing out.
Execution Timeout * Sets the amount of time (in milliseconds) to allow the client tocomplete the execution of an API call.
Max Idle Timeout * Sets the maximum amount of time that an idle connection may sitin the connection pool and still be eligible for reuse.
Socket Timeout * Sets the amount of time to wait (in milliseconds) for data to betransferred over an established, open connection before theconnection times out and is closed.
Max Connections * Sets the maximum number of allowed open HTTP connections.
Max Retry Policy * Sets the maximum number of retry attempts for failed retriablerequests.
Endpoint Provide a DynamoDB endpoint, for example "http://localhost:8000,us-east-1".
Use End Point The server URL.
Table Name * The DynamoDb table name.
Item primary key * The Item primary key name.
Item primary keyvalue *
The Item primary key value.
Item sort key value The Item sort key value.
Item sort key The Item sort key name.
Item primary key type The Item primary data key type.
Item sort key type The Item sort data key type,
1. iWay Services
iWay Service Manager Component Reference Guide 129
Edges:
The following table lists the available Line Edges for the Delete an Item(com.ibi.agents.XDDynamoDBDeleteItem).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
destroy status Service (com.ibi.agents.XDTwitterDestroyStatus)
Syntax:
com.ibi.agents.XDTwitterDestroyStatus
iIT Service Object:
format: destroy status
Description: Destroys the status specified by the required ID parameter. The authenticatinguser must be the author of the specified status. Returns the destroyed status if successful.
Parameters:
Parameter Description
Tweet/Status Id * The numerical ID of the desired status.
Consumer Key * Is your Twitter Application Consumer Key. If you don't have thisinformation, please go to http://dev.twitter.com. Sign in with yourTwitter account, Choose My Applications and click Create a NewApplication then follow the prompts to get Consumer Key,Consumer Secret, Access Token, and Access Token Secret.
Available Services
130 Information Builders
Parameter Description
Consumer Secret * Is your Twitter Application Consumer Secret. If you don't have thisinformation, please go to http://dev.twitter.com. Sign in with yourTwitter account, Choose My Applications and click Create a NewApplication then follow the prompts to get Consumer Key,Consumer Secret, Access Token, and Access Token Secret.
Access Token * Is your Twitter Application Access Token. If you don't have thisinformation, please go to http://dev.twitter.com. Sign in with yourTwitter account, Choose My Applications and click Create a NewApplication then follow the prompts to get Consumer Key,Consumer Secret, Access Token, and Access Token Secret.
Access Token Secret*
Is your Twitter Application Access Token Secret. If you don't havethis information, please go to http://dev.twitter.com. Sign in withyour Twitter account, Choose My Applications and click Create aNew Application then follow the prompts to get Consumer Key,Consumer Secret, Access Token, and Access Token Secret.
Enabled * If on, emits through the proxy server.
Host The HTTP proxy server host name.
Port The HTTP proxy server port.
User The HTTP proxy server user name.
Password The HTTP proxy server password.
Connection Timeout The HTTP connection timeout in milliseconds.
Read Timeout The HTTP read timeout in milliseconds.
Streaming ReadTimeout
The Streaming API's HTTP Read timeout in milliseconds.
Retry Count The number of HTTP retries.
Retry Interval * The HTTP retry interval in seconds.
Pretty Debug Prettifies JSON debug output if set to true.
1. iWay Services
iWay Service Manager Component Reference Guide 131
Parameter Description
Stream Base URL The Streaming API base URL.
Site Stream BaseURL
The Site Streams API base URL.
Edges:
The following table lists the available Line Edges for the destroy status Service(com.ibi.agents.XDTwitterDestroyStatus).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
OnFailTwitterException Twitter threw an exception.
OnFailTwitterOperation Could not perform the Twitter operationrequested.
Document Copy Service (com.ibi.agents.XDCopyAgent)
Syntax:
com.ibi.agents.XDCopyAgent
iIT Service Object:
control: Document copy
Description:
This service is used to duplicate an existing document. The service also allows a comment tobe emitted and a delay to be configured. Unless a delay or comment is required, it isrecommended to use the Move service instead.
Available Services
132 Information Builders
Note: The delay parameter can be specified for benchmarking purposes, while the commentparameter is typically used during troubleshooting.
Example:
If running it with <test/> as the incoming message, the following is the result:
<?xml version="1.0" encoding="UTF-8" ?><test />
Edges:
The following table lists the available line edges for the Document Copy Service(com.ibi.agents.XDCopyAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
cancelled
fail_parse
Document Insert Service (com.ibi.agents.XDDocInsertAgent)
Syntax:
com.ibi.agents.XDDocInsertAgent
Description:
The Document Insert service is used to insert data within an XML Document. The data can betext or parsed XML content. The insertion point is specified by an XPath expression.
Parameters:
The following table lists and describes the parameters for the Document Insert Service.
1. iWay Services
iWay Service Manager Component Reference Guide 133
Parameter Description
Data Source The text or XML data to insert in the document.
Data Format Determines how the Data Source is interpreted.
The Text format treats the Data Source as character Data.
The XML format parses the Data Source as an XML fragment withinthe XML Namespace context of the Parent Element.
ReplaceContent
Determines whether the existing children of the parent node are removedbefore the data is inserted.
XMLNamespaceProvider
Provider for the mapping between the XML namespace prefix and thenamespace URI in the XPath expressions. If left blank, the XPathexpressions in the Parent Element and the Next Sibling cannot containnamespaces.
XPath Syntax Determines which syntax level of XPath should be used. The defaultoption selects the syntax level as set in the console global settings.
Create ParentElement
Determines whether the parent element is created if it is missing.
Parent Element Path to the element where the data will be inserted. If left blank, theparent is the root element. If Create Parent Element is set to true, thenthe expression must adhere to the Restricted XPath syntax, or else theexpression may adhere to the full syntax of the XPath engine selected bythe XPath Syntax parameter. The Restricted XPath has the form /step1/step2/... where a step has the form ns:elem[predicate] or a pairof consecutive steps that has the form *[1]/self::ns:elem[predicate] to indicate that the element must be thefirst child of its parent. The namespace prefixes are optional, but ifpresent they must be declared in the XML Namespace provider. Thepredicate is optional, but if present it has the form[@ns1:attr1='val1' and @ns2:attr2='val2' and ...]. If noelement matches the Restricted XPath expression and Create ParentElement is set to true, then the necessary elements and attributes willbe created such that the expression would match successfully.
Available Services
134 Information Builders
Parameter Description
Next Sibling Path to the next sibling node. If the sibling node is found, the data will beinserted before this node. Otherwise, the data is added as the last childof the Parent Element.
The Data Source is evaluated to obtain a string. If the Text format is selected, the stringbecomes the value of a text node that will be inserted. If the XML format is selected, the stringis parsed as an XML fragment within the XML Namespace context of the Parent Element. AnXML fragment can have multiple root nodes. All the XML Namespace declarations active on theParent Element will be available without the need to redeclare them explicitly in the DataSource. This reduces surprises in case the resulting document is serialized and reparsed later.For the XML format, this service does not reparse the whole input document. Only the DataSource and a small wrapper containing the Namespace declarations are parsed.
If the XML Namespace declarations in the input document are unknown or unpredictable, it isrecommended to explicitly declare all namespace declarations in the Data Source. Inparticular, the default namespace might have to be undeclared if the Data Source containselements in the global namespace.
The Replace Content parameter is Boolean. When selected, the existing children of the parentnode are removed before the data is inserted. In particular, this option is required when youwish to assign a new text value to a Parent Element that already has a value.
The XML Namespace Provider is optional. It is the name of the provider that gives the mappingbetween XML Namespace prefixes and XML Namespace URIs. If left blank, the Parent Elementand Next Sibling path expressions cannot contain namespace prefixes.
The Parent Element is an XPath expression pointing to the element where the data will beinserted.
The Next Sibling is an XPath expression that points to a child of the parent element. The datawill be inserted before this node. If the parameter is left blank or the sibling is not found, thedata is added as the last child of the parent. This parameter is ignored if Replace Content isselected. The operation will fail if the Next Sibling is not a child of the Parent Element.
When the Create Parent Element parameter is true, the Parent Element will be created ifneeded, but the XPath expression must adhere to the Restricted XPath syntax. When theCreate parent Element parameter is false, the parent element must exist but the expressionmay adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter. Formore information on the Restricted XPath, see the Way Service Manager Security Guide.
1. iWay Services
iWay Service Manager Component Reference Guide 135
Edges:
The following table lists and describes the line edges that are returned by the Document InsertService (com.ibi.agents.XDDocInsertAgent).
Edge Description
success The iteration completed successfully.
fail_parse An iFL expression could not be evaluated.
fail_operation The operation could not be completed.
Example 1: Charter Data
This example shows how to set the text value of an element.
The table below lists the parameters and values for the Charter data.
Parameter Value
Data Source NewValue
Data Format text
Replace Content True
Create Parent Element false
Parent Element /root/elem
The following is a sample input document.
<root><elem>OldValue</elem></root>
The following syntax is the resulting output document.
<root><elem>NewValue</elem></root>
Without Replace Content, the output document would contain two text nodes in the elemelement, as shown below:
<root><elem>OldValueNewValue</elem></root>
Available Services
136 Information Builders
The following is another sample input document.
<root><sib>val</sib></root>
The service will return the edge fail_operation with an error document indicating that the ParentElement is missing. The service cannot create the parent element because that parameter isfalse.
Example 2: Creating the Parent
This example shows how to use Restricted XPath to create the parent element if it is absentfrom the input document.
The following table lists the parameters and values for creating the parent.
Parameter Value
Data Source NewValue
Data Format text
Replace Content true
Create Parent Element true
Parent Element /root/*[1]/self::elem
When the parent element already exists, it will then be updated as usual. The following syntaxshows a sample input document.
<root><elem>OldValue</elem></root>
The following is the sample output document.
<root><elem>NewValue</elem></root>
When the parent element is missing, the service will create it. The following syntax shows asample input document.
<root><sib>val</sib></root>
The output document for it will be:
<root><elem>NewValue</elem ><sib>val</sib ></root>
1. iWay Services
iWay Service Manager Component Reference Guide 137
Notice how the elem element is created before the sib element. This is the result of thecarefully crafted Restricted XPath expression. With the simpler expression /root/elem, theelem element is created as the last child of the root element.
Example 3: Inserting an Element
This example shows how to insert an element before a sibling.
The following table lists the parameters and values for inserting an element.
Parameter Value
Data Source _concat(<newelem,_sreg(newval),</newelem>)
Data Format xml
Replace Content false
XML NamespaceProvider
xmlnsprov
Create ParentElement
false
Parent Element /ns:root
Next Sibling /ns:root/sib2
This assumes that the value of the special register newval is 123 and the XML Namespaceprovider xmlnsprov maps the prefix ns to http://ns.com.
The Data Source expression must not start with the less than (<) symbol to be evaluated,otherwise it is considered an XML constant.
The following example shows an input document.
<n:root xmlns:n=http://ns.com><sib1/><sib2/></n:root>
Its output document is shown in the following syntax.
<n:root xmlns:n=http://ns.com><sib1/><newelem >123</newelem><sib2/></n:root>
If the Next Sibling is not found in the input document, the operation still succeeds but the datais inserted as the last child of the Parent Element. The following syntax shows a sample inputdocument.
Available Services
138 Information Builders
<n:root xmlns:n=http://ns.com><sib/><n:root>
The output document is shown below.
<n:root xmlns:n=http://ns.com><sib/><newelem >123</newelem></n:root>
Example 4: Inheriting XML Namspaces
This example shows how the XML namespace declarations are inherited from the context ofthe Parent Element. It also demonstrates a Data Source containing an XML fragment with tworoot nodes.
The following table lists the parameters and values of the XML namespaces.
Parameter Value
Data Source <n:newelem/><def/>
Data Format xml
Replace Content true
Create ParentElement
true
Parent Element /root/sub
The following example shows an input document.
<root xmlns:n=http://ns.com><sub/></root>
The corresponding output document is:
<root xmlns:n=http://ns.com><sub><n:newelem/ ><def/></root>
Note that he newelem element inherited its namespace prefix from an ancestor node in theinput document.
The following example shows an input document.
<root xmlns:n=http://ns.com xmlns=http://default.com></sub></root>
The corresponding output document is:
<root xmlns:n=http://ns.com xmlns=http://default.com><sub><n:newelem/ ><def/></sub></root>
1. iWay Services
iWay Service Manager Component Reference Guide 139
The def element is now in the http://default.com namespace. If you do not wish to have theelement in the namespace, then the default namespace must be explicitly undeclared in theData Source, as shown in the following syntax:
<n:newelem/><def xmlns=/>
If the application does not control the exact content of the input document, then it isrecommended to explicitly declare all XML Namespaces in the Data Source, as shown in thefollowing syntax.
<n:newelem xmlns:n=http://ns.com/><def xmlns=/
Document state modification Service (com.ibi.agents.XDDocAgent)
Syntax:
com.ibi.agents.XDDocAgent
iIT Service Object:
format: Document state modification
Description: Modifies the incoming document state, setting status, encoding, format, etc. .
Parameters:
Parameter Description
Document ErrorState
Controls the document error state. The error statesends the document to the errorTo destination and canbe tested by _iserror().
Schema ErrorState
Controls the schema error state. The schema errorstate can be tested the by _hasschemaerr() iFLfunction.
Encoding * The IANA character set to be used for this document.Select from the standard list or enter an encodingname.
Output
Message Format*
Changes the format of the message in this document. Ifflat string, you can apply an iFL expression.
Available Services
140 Information Builders
Parameter Description
Apply iFL Applies this iFL to the flattened form of the messagecontent. Applies when flattening to a string only.
XML Version Sets the XML version. This affects the XML declaration.
Suffix Type Forces the type to the entered value, for example, pdf.Used for emits. If blank, it does not change the value. Ina file system the type can be the suffix, which in somesystems triggers the appropriate visualizer for the file.
Edges:
The following table lists the available Line Edges for the Document state modification Service(com.ibi.agents.XDDocAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnCancelled The service has responded to a cancellationrequest.
fail_encoding Invalid character encoding.
Document Update Service (com.ibi.agents.XDDocUpdateAgent)
Syntax:
com.ibi.agents.XDDocUpdateAgent
iIT Service Object:
document: Doc Update Agent
sreg: Doc Update Agent
1. iWay Services
iWay Service Manager Component Reference Guide 141
transform: Activity Log Control
Description:
The Document Update service can be used to run find and replace procedures, and modifydata based on static or dynamic parameters.
Note: This service requires a highly technical method to achieve the desired result. The samefunctionality can be performed through the use of a configured Transform component, whichcan be called by a Transform service. For more information, see Transform Service(com.ibi.agents.XDTransformAgent) on page 488.
Parameters:
Parameter Description
Document Output * The manner in which to process documents. XML can beprocessed as flat text, but the output document will result asdesignated. Select one of the following options from the drop-down list:
Process to Flat text. Treats the incoming and outgoing dataas flat text.
Process to XML. Parses the document as XML.
Processing Method * Modify document data before or after the find/replace operation.Select one of the following options from the drop-down list:
Find/Replace then Build Document. Performs a find/replaceoperation then parses the document.
Build Document then Find/Replace. Parses the documentthen performs a find/replace operation.
Only Find/Replace. Performs a find/replace operation only.
Only Build Document. Parses the document as XML or flat (noreplace is performed).
Available Services
142 Information Builders
Parameter Description
Document AssemblyInstructions
A comma-separated field used to describe how the document isassembled. The build text is evaluated from left to right. iFLfunctions (for example, _SREG and _CONCAT) are evaluated atdocument build time. The following special text values are alsoused:
DS0 - document at time of build, DS#
where:
#
Represents one of the four data sources.
DS1 Data source 1, which is evaluated when the component is called.This field may contain any iFL functions (for example, _SREG and_CONCAT) and text. This field is represented in the DocumentAssembly Instructions parameter as DS1.
DS2 Data source 2, which is evaluated when the component is called.This field may contain any iFL functions (for example, _SREG and_CONCAT) and text. This field is represented in the DocumentAssembly Instructions parameter as DS2.
DS3 Data source 3, which is evaluated when the component is called.This field may contain any iFL functions (for example, _SREG and_CONCAT) and text. This field is represented in the DocumentAssembly Instructions parameter as DS3.
DS4 Data source 4, which is evaluated when the component is called.This field may contain any iFL functions (for example, _SREG and_CONCAT) and text. This field is represented in the DocumentAssembly Instructions parameter as DS4.
Find/Replace
Search Text to search for. Use a comma (,) to repeat searches (forexample, search1,search2,search3).
Replace Text to replace search text. Multiple searches must have an equalnumber of replacements.
1. iWay Services
iWay Service Manager Component Reference Guide 143
Parameter Description
Encoding Specifies the encoding when converting a flat document to XMLformat. Platform encoding is used by default.
Note: The Encoding parameter is required for the DocumentUpdate service to function properly.
Data Sources Data used to build the document. Use a comma (,) to repeat datasources (for example:_SREG(VAR_A),_SREG(VAR_B),_SREG(VAR_C)). Use DS0 toinclude the original incoming document.
The following image shows the New Service Object dialog in iIT Designer and the correspondingparameters that displays when you add a new Document Update service object to a processflow.
Edges:
Available Services
144 Information Builders
The following table lists the available line edges for the Document Update Service(com.ibi.agents.XDDocUpdateAgent).
Line Edge Description
OnError Error: Returned by the service if any of thefollowing fields contain an invalid iFLstatement:
Document Assembly Instructions
DS1
DS2
DS3
DS4
Search
Replace
If Process to XML was selected and thedocument created is not a well formed XMLdocument.
OnSuccess Success: The service generated asuccessful output. Either a flat documentwas generated by the service (if Process toFlat text was selected), or a well formedXML document (if Process to XML wasselected) was produced.
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 145
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation: An unexpected erroroccurred while processing the documentor the parameters of the service. Checkthe iSM logs for further details.
fail_notfound
Example 1: Find/Replace Then Build Document
This example performs a Find/Replace operation then parses the document. In this example,DS0, DS1, DS2, DS3, and DS4 are used to append the text this is a bill to the end of thedocument (DS0 represents the input document of the service). Because the Find/Replaceoperation is performed prior to compiling the output document, the second occurrence of bill isnot replaced with buster.
Document:
<Test>joe bill mike<Test>
Parameters:
Parameter Value
Document Output Process to Flat text
Processing Method Find/Replace then Build Document
Document Assembly Instructions ds0,ds1,ds2,ds3,ds4
DS1 _concat(this,' ')
Available Services
146 Information Builders
Parameter Value
DS2 _concat(is,' ')
DS3 _concat(a,' ')
DS4 bill
Search bill
Replace buster
Encoding UTF-8
Results:
<Test>joe buster mike<Test>this is a bill
Example 2: Build Document Then Find/Replace
This example parses the document then performs a Find/Replace operation. In this example,DS0, DS1, DS2, DS3, and DS4 are used to append the text this is a bill to the end of thedocument (DS0 represents the input document of the service). Because the Find/Replaceoperation is performed after compiling the output document, the second occurrence of bill isreplaced with buster.
Document:
<Test>joe bill mike<Test>
Parameters:
Parameter Value
Document Output Process to Flat text
Processing Method Build Document then Find/Replace
Document Assembly Instructions ds0,ds1,ds2,ds3,ds4
DS1 _concat(this,' ')
1. iWay Services
iWay Service Manager Component Reference Guide 147
Parameter Value
DS2 _concat(is,' ')
DS3 _concat(a,' ')
DS4 bill
Search bill
Replace buster
Encoding UTF-8
Results:
<Test>joe buster mike<Test>this is a buster
Example 3: Only Find/Replace
This example only performs a Find/Replace operation. In this case, only the documentpresented to the service is searched and any occurrence of bill is replaced with buster.
Document:
<Test>joe bill mike<Test>
Parameters:
Parameter Value
Document Output Process to Flat text
Processing Method Only Find/Replace
Document Assembly Instructions
DS1 _concat(this,' ')
DS2 _concat(is,' ')
DS3 _concat(a,' ')
Available Services
148 Information Builders
Parameter Value
DS4 bill
Search bill
Replace buster
Encoding UTF-8
Results:
<Test>joe buster mike<Test>
Example 4: Only Build Document
This example parses the document as XML or flat (no replace is performed). The assemblyinstructions indicate that DS1, DS2, DS3, and DS4 are used to create the document that theservice will output. There will be no replacements performed by the service.
Document:
<Test>joe bill mike<Test>
Parameters:
Parameter Value
Document Output Process to Flat text
Processing Method Only Build Document
Document Assembly Instructions ds1,ds2,ds3,ds4
DS1 _concat(this,' ')
DS2 _concat(is,' ')
DS3 _concat(a,' ')
DS4 bill
1. iWay Services
iWay Service Manager Component Reference Guide 149
Parameter Value
Search bill
Replace buster
Encoding UTF-8
Results:
this is a bill
The assumption for the examples to follow is that the iSM SREG called xmlrecord is set to:
<root><Joe>QA</Joe>
Example 5: Find/Replace Then Build Document
This example performs a Find/Replace operation then parses the document. In this example,the iSM iFL function _SREG and DS0 (the document presented to the service) are used in thedocument assembly process. Because the Find/Replace operation is performed prior tocompiling the output document, only the second occurrence of QA is replaced with QualityAssurance.
Document:
<Michael>QA</Michael></root>
Parameters:
Parameter Value
Document Output Process to XML
Processing Method Find/Replace then Build Document
Document Assembly Instructions _sreg(xmlrecord),DS0
DS1
DS2
DS3
Available Services
150 Information Builders
Parameter Value
DS4
Search QA
Replace Quality Assurance
Encoding UTF-8
Results:
<?xml version="1.0" encoding="ISO-8859-1" ?><root> <Joe>QA</Joe> <Michael>Quality Assurance</Michael></root>
Example 6: Build Document Then Find/Replace
This example parses the document then performs a Find/Replace operation. In this example,the iSM iFL function _SREG and DS0 (the document presented to the service) are used in thedocument assembly process. Because the Find/Replace operation is performed aftercompiling the output document, both occurrences of QA are replaced with Quality Assurance.
Document:
<Michael>QA</Michael></root>
Parameters:
Parameter Value
Document Output Process to XML
Processing Method Build Document then Find/Replace
Document Assembly Instructions _sreg(xmlrecord),DS0
DS1
DS2
1. iWay Services
iWay Service Manager Component Reference Guide 151
Parameter Value
DS3
DS4
Search QA
Replace Quality Assurance
Encoding UTF-8
Results:
<?xml version="1.0" encoding="ISO-8859-1" ?><root> <Joe>Quality Assurance</Joe> <Michael>Quality Assurance</Michael></root>
Example 7: Only Find/Replace
This example only performs a Find/Replace operation. In this case, only the document that ispresented to the service is searched and any occurrence of QA is replaced with QualityAssurance.
Document:
<Michael>QA</Michael>
Parameters:
Parameter Value
Document Output Process to XML
Processing Method Only Find/Replace
Document Assembly Instructions
DS1
DS2
Available Services
152 Information Builders
Parameter Value
DS3
DS4
Search QA
Replace Quality Assurance
Encoding UTF-8
Results:
<?xml version="1.0" encoding="ISO-8859-1" ?><Michael>Quality Assurance</Michael>
Example 8: Only Build Document
This example parses the document as XML or flat (no replace is performed). In this example,the iSM iFL function _SREG and DS0 (the document presented to the service) are used in thedocument assembly process. There will be no replacements performed by the service.
Document:
<Michael>QA</Michael></root>
Parameters:
Parameter Value
Document Output Process to XML
Processing Method Only Build Document
Document Assembly Instructions _sreg(xmlrecord),DS0
DS1
DS2
DS3
1. iWay Services
iWay Service Manager Component Reference Guide 153
Parameter Value
DS4
Search QA
Replace Quality Assurance
Encoding UTF-8
Results:
<?xml version="1.0" encoding="ISO-8859-1" ?><root> <Joe>QA</Joe> <Michael>QA</Michael></root>
Document to Attachment Service (com.ibi.agents.XDAttachmentFromDocAgent)
Syntax:
com.ibi.agents.XDAttachmentFromDocAgent
iIT Service Object:
attachments: Document to Attachment
Description:
This service adds a new attachment with the contents determined by the input document. Theattachment headers are specified with user parameters. The name and value of the userparameter become the name and value of the header. Notice the value of the Content-IDheader is taken as is, so the value must contain the surrounding angle brackets.
For example, a valid value for Content-ID might be <cid>. The Attachment Type parameterspecifies the attachment Content-Type. If the Attachment Type is omitted, a Content-Type ischosen based on the document data:
application/binary if the document contains bytes
text/plain if the document is flat
application/xml otherwise
Available Services
154 Information Builders
The optional Attachment Name parameter controls the name sub-parameter of the Content-Type header. The Content-Type name can also be given directly in the Content-Type headervalue if desired.
The Body Result parameter specifies what to return in the output document: keep copies theinput document to the output document, empty returns an empty document instead. Thisservice follows OnSuccess upon successful execution, otherwise it follows the fail_attachedge.
Parameters:
Parameter Description
Attachment Name The name of this attachment, for example, file name.
Attachment Type The MIME type. If no value is specified, the attachment type isgenerated based on the data format.
Body Result Specify how to handle the body of this document by selecting oneof the following values from the drop-down list:
keep (default)
empty
Edges:
The following table lists the available line edges for the Document to Attachment Service(com.ibi.agents.XDAttachmentFromDocAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 155
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_attach
fail_parse
DQC Batch Executor Service (com.ibi.agents.XDDQBatchExec)
Syntax:
com.ibi.agents.XDDQBatchExec
iIT Service Object:
DQS: DQS Batch Executor
Description:
This service is used to execute a batch command, which starts an iWay Data Quality Center(DQC) plan.
Parameters:
Parameter Description
DQC runtimecommand file *
The path to the runtime command file for iWay DQC. For example,on Windows installations:
DQC_Home\runtime\bin\runcif.bat
where:
DQC_Home
Is the root installation directory for iWay DQC.
Plan File Location * The fully qualified path to the iWay DQC plan file that must beexecuted.
Available Services
156 Information Builders
Parameter Description
Runtime ConfigurationFile Location *
The fully qualified path to the default runtime configuration file.
Additional PathVariable Name(s)
A comma-separated list of additional path variable names. Usethis to add additional path variables to the default configuration.
Additional PathVariable Value(s)
A comma-separated list of additional path variable values. Usethis to add additional path variable values.
Timeout Time in seconds for iWay DQC timeout. A value of zero (0)indicates no timeout, which is the default setting.
Edges:
The following table lists the available line edges for the DQC Batch Executor Service(com.ibi.agents.XDDQBatchExec).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
fail_parse
fail_timeout
DQC/MDC Flow Linkage Service (com.ibi.agents.MdcAgentISM)
Syntax:
com.ibi.agents.MdcAgentISM
1. iWay Services
iWay Service Manager Component Reference Guide 157
iIT Service Object:
DQS: DQS/MDS Flow Linkage
Description:
This service is used to invokes services in iWay Master Data Center (MDC).
Parameters:
Parameter Description
XPath Expression An XPath expression whose evaluation will retrieve one or moreelements, each of which will be sent to iWay MDC. Leave blank tosend the input document as is.
XPath Syntax * Determines the syntax level of XPath that should be used. Thedefault option selects the syntax level as set in the GeneralSettings section of the iSM Administration Console. Select one ofthe following levels from the drop-down list:
Default {default}
iWay abbreviated syntax {iway}
XPath 1.0 full syntax {xpath1}
MDC host * The host on which the iWay MDC listener is running.
MDC port * The port on which the iWay MDC listener is running.
Timeout * Time in seconds for connection timeout. A value of zero (0)indicates no timeout. The default setting is 300 seconds.
Edges:
The following table lists the available line edges for the DQC/MDC Flow Linkage Service(com.ibi.agents.MdcAgentISM).
Line Edge Description
OnError Error
OnSuccess Success
Available Services
158 Information Builders
Line Edge Description
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operations
fail_parse
notfound
Data Quality Center Service (Document-Driven, Pooling) (com.ibi.agents.XDDQAgent2)
Syntax:
com.ibi.agents.XDDQAgent2
iIT Service Object:
DQS: Data Quality Service Agent - Document Driven (pooling)
Description:
This service marshals data from an input document and processes data using an iWay DataQuality Runtime Provider.
Parameters:
Parameter Description
Data Quality RuntimeProvider *
Specify the configured iWay Data Quality Runtime Providerthat should be invoked.
DQC plan file * Specify the location of the iWay Data Quality Center (DQC)plan file containing the logic for the data quality operation.
1. iWay Services
iWay Service Manager Component Reference Guide 159
Parameter Description
Runtime Config File(Optional)
Specify the location of the iWay DQC runtime configurationfile. This file is used to define an iWay DQC runtime variable,such as JDBC data sources or folder shortcuts used in theplan.
XPath Expression * Specify an XPath expression that will return one or moreelements from the input document that will be used as inputrecords when the iWay DQC plan is invoked.
XPath Namespace Map If the input document contains namespaces, then thisparameter specifies the configured namespace map to beused when evaluating XPath expressions.
Replace or Preserve? * Determines whether the children of the record element in theoutput document should be preserved (appending the resultof the iWay DQC plan execution as new child elements), orshould the original children be replaced with the iWay DQCplan results.
Select one of the following options from the drop-down list:
Replace
Preserve
By default, replace is selected.
Edges:
The following table lists the available line edges for the Data Quality Center Service (Document-Driven, Pooling) (com.ibi.agents.XDDQAgent2).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
160 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_partner
fail_parse
fail_notfound
Configuring Data Quality Runtime Providers
In the iWay Service Manager (iSM) Administration Console, the Data Quality Providers area nowincludes a second group called Defined Data Quality Runtime Providers, as shown in thefollowing image.
1. iWay Services
iWay Service Manager Component Reference Guide 161
The former group (Defined Data Quality Providers) is now deprecated. It is recommended tomigrate to the new provider (Data Quality Runtime Provider). The original Data Quality Providerrepresented a single iWay DQC plan. This required you to configure one Data Quality Providerfor each iWay DQC plan The new Data Quality Runtime Provider represents iWay DQC runtime.A single Data Quality Runtime Provider can be used to manage all iWay DQC plans.
The new Data Quality Runtime Provider is configured by setting pooling parameters for the localinstance of iWay DQC that is installed with iSM. In a future iSM release, it will be possible toconfigure a remote instance of iWay DQC.
The following image shows the Data Quality Runtime Provider Settings pane.
The pools enable iSM to optimize access to iWay DQC, consistent with the reentrancy of theiWay DQC subsystem in use. Note that these pool settings apply to each iWay DQC plan that ismanaged by the provider. Thus, if the iWay DQC runtime loads 3 separate plans and theMaximum Pool Size parameter is set to 3, then a maximum of 9 execution threads will bepooled.
The Data Quality Runtime Provider supports the following services:
Data Quality Center Service (Document-Driven, Pooling)
com.ibi.agents.XDDQAgent2
Data Quality Center Service (User Parameter-Driven, Pooling)
com.ibi.agents.XDDQAgent2UserParm
Available Services
162 Information Builders
The document-driven version of the service has the same functionality as the deprecated DataQuality Center Service (com.ibi.agents.XDDQAgent), except:
It uses the new Data Quality Runtime Provider.
Because the Data Quality Runtime Provider represents the iWay DQC runtime, rather than aspecific iWay DQC plan, the service must be configured with the path to the plan file (andoptional runtime configuration file).
For more information about using Data Quality Runtime Providers with one of the supportedservices, see Using the Data Quality Center Service (User Parameter-Driven, Pooling) on page165.
Data Quality Center Service (User Parameter-Driven, Pooling)(com.ibi.agents.XDDQAgent2UserParm)
Syntax:
com.ibi.agents.XDDQAgent2UserParm
iIT Service Object:
DQS: Data Quality Service Agent - User Parm Driven (pooling)
Description:
This service executes an iWay DQC plan and passes user parameters as input data. The planis dynamic and called by name.
Parameters:
Parameter Description
Data Quality RuntimeProvider *
Specify the configured iWay Data Quality Runtime Provider thatshould be invoked.
DQC plan file * Specify the location of the iWay Data Quality Center (DQC) planfile containing the logic for the data quality operation.
Runtime Config File(Optional)
Specify the location of the iWay DQC runtime configuration file.This file is used to define an iWay DQC runtime variable, such asJDBC data sources or folder shortcuts used in the plan.
1. iWay Services
iWay Service Manager Component Reference Guide 163
Parameter Description
Include Input? * Determines whether the input data (from user parameters),should be included in the output document that is generated bythis service. Select true or false.
Include Messages? * Determines whether messages generated during the execution ofthe iWay DQC plan should be included in the output documentthat is generated by this service. Select true or false.
Edges:
The following table lists the available line edges for the Data Quality Center Service (UserParameter-Driven, Pooling) (com.ibi.agents.XDDQAgent2UserParm).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_partner
fail_parse
fail_notfound
Available Services
164 Information Builders
Using the Data Quality Center Service (User Parameter-Driven, Pooling)
The following image shows the configuration settings pane for the Data Quality Center Service(User Parameter-Driven, Pooling).
1. iWay Services
iWay Service Manager Component Reference Guide 165
The record that is passed to the iWay DQC plan is defined using user parameters. This can beconfigured using iWay Integration Tools Designer, or you can create a parameter set in theRegistry under the Variables section, and then attach the parameter set to the configuredservice.
The names of these parameters will be passed to iWay DQC as field names and the evaluatedparameter values as the field values. Typically, the parameter values will be set using iFLexpressions, using special registers or XPath to extract values from the input document of theservice. The parameters are treated a single record to pass to the iWay DQC plan.
The service outputs a simple XML document containing the output record from iWay DQC, andoptionally including the input record and/or any messages generated by iWay DQC runtime.
For example, you can use this service to invoke the sample (hello_customer) iWay DQC plan.
Available Services
166 Information Builders
Procedure: How to Use the Data Quality Center Service (User Parameter-Driven, Pooling) to Invokea Sample Plan
To invoke the sample hello_customer plan using the Data Quality Center Service (UserParameter-Driven, Pooling):
1. Configure a Data Quality Runtime Provider as described in Configuring Data QualityRuntime Providers on page 161.
For this example, do not be concerned about the pooling options. You can leave thedefault value, which pools one execution thread. Specify DQRuntime as the name for theData Quality Runtime Provider. After this provider is created, you must restart iSM.
2. Add the Data Quality Center Service (User Parameter-Driven, Pooling)(com.ibi.agents.XDDQAgent2UserParm) to a process flow. Specify parameter values forthis service as indicated in the following table:
Parameter Value
Data Quality Runtime Provider DQRuntime
DQC plan file Specify the path to the iWay DQChello_customer.plan file.
Runtime Config File <leave blank>
Include Input? true
Include Messages? true
3. Add the following user parameters to the service:
firstname
_xpath(//customerGreeting/customers[1]/firstname)
lastname
_xpath(//customerGreeting/customers[1]/lastname)
Note: The XPath expression specifies that you want the element of the first customer nthe input document. Remember, this service only processes one record at a time.
1. iWay Services
iWay Service Manager Component Reference Guide 167
4. Test the process flow in the configuration where you created the Data Quality RuntimeProvider using the following input document:
<customerGreeting> <customers> <firstname>Daniel</firstname> <lastname>Deutsch</lastname> </customers> <customers> <firstname>Alain</firstname> <lastname>Perez</lastname> </customers></customerGreeting>
The resulting output should be structured as shown in the following example:
<?xml version="1.0" encoding="ISO-8859-1" ?><DQC planFile="c:\working\dqc\hello_customer.plan"> <input> <field name="lastname">Deutsch</field> <field name="firstname">Daniel</field> </input> <output> <field name="greeting">Hello, Daniel Deutsch!</field></output><messages/></DQC>
Note: The input record is included and the document also includes an element formessages. However, since this iWay DQC plan completed without any messages fromiWay DQC, there are no messages here.
EDI Accumulator Service (com.ibi.agents.EDIAccumulator)
Syntax:
com.ibi.agents.EDIAccumulator
iIT Service Object:
format: EDI Accumulator
Description: Accumulates transactions until EOS (End of Stream).
Parameters:
Parameter Description
Name * The name of the new Service object definition.
Available Services
168 Information Builders
Parameter Description
Description The description for the new Service object definition.
Edges:
The following table lists the available Line Edges for the EDI Accumulator Service(com.ibi.agents.EDIAccumulator).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
EDI Rule Router Service (com.ibi.agents.XDRuleRouterAgent)
Syntax:
com.ibi.agents.XDRuleRouterAgent
iIT Service Object:
format: EDI Rule Router
Description: Routes EDI documents based on defined rules, decorating output based on ruleresults.
Parameters:
Parameter Description
Error Location * The error output directory.
Error Mask * The error file name with possible wild cards.
Valid Location A valid output directory.
Valid Mask A valid file name with possible wild cards.
1. iWay Services
iWay Service Manager Component Reference Guide 169
Parameter Description
ACK Location The acknowledgement output directory.
ACK Mask The acknowledgement file name with possible wild cards.
Original Location The original data output directory.
Original Mask The original data file name with possible wild cards.
Status Location * The status document output directory.
Status Mask * The status document file name with possible wild cards.
Edges:
The following table lists the available Line Edges for the EDI Rule Router Service(com.ibi.agents.XDRuleRouterAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
EDIFACTAckAgent (com.ibi.agents.XDEDIFACTAckAgent)
Syntax:
com.ibi.agents.XDEDIFACTAckAgent
iIT Service Object:
format: EDIFACTAckAgent
Description: Creates EDIFACT 'APERAK' or 'CONTRL' acknowledgment message.
Parameters:
Available Services
170 Information Builders
Parameter Description
AcknowledgmentType
The EDIFACT Acknowledgment Type.
Interchange ControlReference
The element location.
Message ReferenceNumber
The element location.
Version The EDIFACT syntax version.
Edges:
The following table lists the available Line Edges for the EDIFACTAckAgent(com.ibi.agents.XDEDIFACTAckAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
Success The operation was successful.
EDIFACT ValidationReportAgent(com.ibi.agents.XDEDIFACTValidationReportAgent)
Syntax:
com.ibi.agents.XDEDIFACTValidationReportAgent
iIT Service Object:
format: EDIFACT ValidationReportAgent
Description: Creates a validation report after validating an inbound EDIFACT/outbound XMLmessage.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 171
Parameter Description
Input Message Adds the input message to the report.
Output Message Adds the output message to the report.
Line Edges:
The following table lists the available Line Edges for the EDIFACT ValidationReportAgent(com.ibi.agents.XDEDIFACTValidationReportAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
Success The operation was successful.
EDIHL7AckAgent (com.ibi.agents.XDEDIHL7AckAgent)
Syntax:
com.ibi.agents.XDEDIHL7AckAgent
iIT Service Object:
format: EDIHL7AckAgent
Description: Creates EDIFACT 'APERAK' or 'CONTRL' acknowledgment message.
Parameters:
Parameter Description
Sending Application * The name of the sending application.
Sending Facility * The name of the sending facility.
Control ID * The Message Control ID.
Available Services
172 Information Builders
Parameter Description
Mode * The acknowledgment mode.
Acknowledgment * Sends an acknowledgment.
Edges:
The following table lists the available Line Edges for the EDIFACTAckAgent(com.ibi.agents.XDEDIFACTAckAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
EDIHL7 ValidationReport Agent (com.ibi.agents.XDEDIHL7ValidatioReportAgent)
Syntax:
com.ibi.agents.XDEDIHL7ValidatioReportAgent
iIT Service Object:
format: EDIHL7 ValidationReport Agent
Description: Creates a Validation Report after validating inbound HL7/outbound XML message.
Parameters:
Parameter Description
Input Message Adds the input message to the report.
Output Message Adds the output message to the report.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 173
The following table lists the available Line Edges for the EDIHL7 ValidationReport Agent(com.ibi.agents.XDEDIHL7ValidatioReportAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
Success The operation was successful.
EDIWrapperAgent Service (com.ibi.agents.EDIWrapperAgent)
Syntax:
com.ibi.agents.EDIWrapperAgent
iIT Service Object:
format: EDIWrapperAgent
Description: This agent wraps an EDI document.
Parameters:
Parameter Description
Wrapper length The length of the line.
Wrapper style ` The line terminator style.
Wrapper end Adds style to the end of document.
Wrapper terminator The character that replaces the segment terminator with code 10or code 13.
Available Services
174 Information Builders
Edges:
The following table lists the available Line Edges for the EDIWrapperAgent Service(com.ibi.agents.EDIWrapperAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
EDIX12TransformAgent Service (com.ibi.agents.XDEDITransformAgent)
Syntax:
com.ibi.agents.XDEDITransformAgent
iIT Service Object:
format: EDIX12TransformAgent
Description: Transforms an EDI XML formatted document to an EDI document .
Parameters:
Parameter Description
Base Path * The base path to the transform template.
Version Year * The Swift version.
Edges:
The following table lists the available Line Edges for the EDIX12TransformAgent Service(com.ibi.agents.XDEDITransformAgent).
Line Edge Description
OnError An exception occurred during execution.
1. iWay Services
iWay Service Manager Component Reference Guide 175
Line Edge Description
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
EDIX12AckAgent Service (com.ibi.agents.XDX12AckAgent)
Syntax:
com.ibi.agents.XDX12AckAgent
iIT Service Object:
format: EDIX12AckAgent
Description: Produces a 997 document after validating the incoming EDI document. Used intandem with EDI Preparser.
Parameters:
Parameter Description
Protocol The protocol on which to make ACK copies.
Location The location for the ACK copies.
End Tag The surrounding XML tag.
Preemitter Whether the preemitter runs on ACK output.
Error Wheter to send an error to the error log.
ISA Control Number The element location.
GS Control Number The element location.
ST Control Number The element location.
StreamAcknowledgment
Acknowledgment the stream.
Available Services
176 Information Builders
Parameter Description
AcknowledgmentLevel
Acknowledgment level.
Run at EOS Enforce IEA02 and GE02.
Edges:
The following table lists the available Line Edges for the EDIX12AckAgent Service(com.ibi.agents.XDX12AckAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
Email Emit Service (com.ibi.agents.XDEmailEmitAgent)
Syntax:
com.ibi.agents.XDEmailEmitAgent
iIT Service Object:
emit: Email Emit Agent
Description:
Emits an email to a specified mail host with various options, including the option to input dataas an attachment.
Parameters:
Parameter Description
Outgoing Mail Host * Outgoing email host used to route outgoing email (add:port fornon-standard port).
1. iWay Services
iWay Service Manager Component Reference Guide 177
Parameter Description
To * Message recipient as an email address. Use a semicolon (;) todelimit multiple addresses.
Subject of Msg Subject of the message.
Sender address Sender of this email.
Copy To Carbon copy recipient of this email. Use a semicolon (;) to delimitmultiple addresses.
Blind Copy To Blind Carbon copy recipient of this email. Use a semicolon (;) todelimit multiple addresses.
Reply-to Address to reply to, for this email. Use semicolon (;) to delimitmultiple addresses.
Content Contains the data for the email body, default (blank) is theinbound document.
Attachment Tag Tag name that holds a path to a file to be attached. This is anexact element name and not an XPATH expression. If theadd_attachment tag is defined in the incoming XML document,then provide add_attachment as the value for this parameter andnot the XPATH expression to the destination.
Add As Attachment If set to true, the inbound document is treated as an attachment.An attachment name is then required.
Document AttachmentName
Name of the inbound document attachment.
Attachment ContentType
Content Type of the attachment.
User ID Is the valid user ID to log on to the SMTP host server.
Password Is a valid password to authenticate the SMTP user ID.
Content Type The content type of the data.
Available Services
178 Information Builders
Parameter Description
Return Select one of the following options from the drop-down list:
status. Status document will become the output document.
input. Input document will become the output document
Security Protocol Select one of the following options from the drop-down list:
none - Clear SMTP connection.
SSLv2 - SMTPS - Connect to secure SMTP server.
STARTTLS - Connect to an unsecured SMTP server, thennegotiate SSL/TLS connection.
Edges:
The following table lists the available line edges for the Email Emit Service(com.ibi.agents.XDEmailEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_connect
1. iWay Services
iWay Service Manager Component Reference Guide 179
Example:
To configure the Email Emit service, you must first specify the URL for your email server andthe appropriate security level. The following example shows security settings that areconfigured for the Microsoft Exchange Server:
Available Services
180 Information Builders
If your connection parameters are valid, you will receive an email notification that wouldcontext the incoming document and a response document from running the service, in thefollowing format:
<?xml version="1.0" encoding="UTF-8" ?><emitStatus> <protocol>EMAIL</protocol> <parms>password=****, [email protected], userid=js77777, docattachname=test.xml, usessl=STARTTLS, docattach=false, host=IBIUSMBSA.ibi.com, return=status, [email protected], subject=Email Emit Test</parms><status>0</status><msg /><timestamp>2009-05-01T21:27:51.824Z</timestamp><attempts>1</attempts><name>[email protected]</name></emitStatus>
The following is an example of configuration settings for an Email Emit service object thatincludes an attachment in iIT Designer:
1. iWay Services
iWay Service Manager Component Reference Guide 181
If your connection parameters are valid, you will receive an email attachment (test.doc) and aresponse document from running the service, in the following format:
<?xml version="1.0" encoding="UTF-8" ?><emitStatus> <protocol>EMAIL</protocol><parms>password=****, [email protected], userid=js77777, docattachname=test.doc, usessl=STARTTLS, docattach=true, host=IBIUSMBSA.ibi.com, return=status, [email protected], subject=Email Emit Attch, docattachctype=text/plain, body=see attached</parms><status>0</status><msg /><timestamp>2009-05-05T22:43:59.032Z</timestamp><attempts>1</attempts><name> [email protected]</name></emitStatus>
Entag Service (com.ibi.agents.XDEntagAgent)
Syntax:
com.ibi.agents.XDEntagAgent
iIT Service Object:
misc: Entag Agent
Description:
Adds an element tag around a flat document, and optionally base64 encodes the document. Ifthe input document is not flat, this service is ignored.
Parameters:
Parameter Description
Tag Name * The name of the tag which wraps the data.
Base64 Encoding * Determines whether the data requires Base64 encoding, so thatvalid XML could be formed. Select true or false from the drop-down list.
Available Services
182 Information Builders
Edges:
The following table lists the available line edges for the Entag Service(com.ibi.agents.XDEntagAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
If you run this service with picture as a value for the Tag Name parameter, Base64 Encodingset to true, and incoming data as <test/>, the following result is returned:
<?xml version="1.0" encoding="UTF-8" ?><picture>PFRlc3QvPg==</picture>
If Base64 Encoding is set to false, the result would be:
<picture><test/></picture>
Ethereum Call Agent Service (com.ibi.agents.XDEthereumCallAgent)
Syntax:
com.ibi.agents.XDEthereumCallAgent
iIT Service Object:
format: Ethereum Call Agent
Description: Calls a function in an Ethereum smart contract.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 183
Parameter Description
Client Address * The URL to the Ethereum client.
Wallet File * The path to the wallet file containing the account credentials.
Password * The password to read the wallet file.
Gas Price The gas price in wei.
Gas Limit The maximum amount of gas that can be spent.
Smart ContractAddress *
The address of the smart contract to call.
Value The amount of Ether (in wei) you wish to deposit in the smartcontract (if the function is payable).
ABI File * The path to the smart contract ABI file.
Function * The name of the function to call in the smart contract.
Sleep Duration the time in milli-seconds between attempts to get the transactionreceipt.
Number of Attempts The number of attempts to get the transaction receipt.
Return Determines the contents of the output document.
Edges:
The following table lists the available Line Edges for the Ethereum Call Agent Service(com.ibi.agents.XDEthereumCallAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
Available Services
184 Information Builders
Line Edge Description
fail_parse Could not parse a document.
fail_timeout The operation timed out.
fail_operation Could not perform the operation requested.
Ethereum Call Constant Function Agent Service (com.ibi.agents.XDEthereumCallConstantAgent)
Syntax:
com.ibi.agents.XDEthereumCallConstantAgent
iIT Service Object:
format: Ethereum Call Constant Function Agent Description: Calls a constant function to querythe state of an Ethereum smart contract.
Parameters:
Parameter Description
Client Address * The URL to the Ethereum client.
Wallet File * The path to the wallet file containing the account credentials.
Password * The password to read the wallet file.
Smart ContractAddress *
The address of the smart contract to call.
ABI File * The path to the smart contract ABI file.
Function * The name of the function to call in the smart contract.
Output Format The syntax of the output document holding the function returnparameters.
1. iWay Services
iWay Service Manager Component Reference Guide 185
Edges:
The following table lists the available Line Edges for the Ethereum Call Constant FunctionAgent Service (com.ibi.agents.XDEthereumCallConstantAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
fail_parse Could not parse a document.
fail_operation Could not perform the operation requested.
Ethereum Deploy Agent Service (com.ibi.agents.XDEthereumDeployAgent)
Syntax:
com.ibi.agents.XDEthereumDeployAgent
iIT Service Object:
format: Ethereum Deploy Agent
Description: Deploys a new Ethereum smart contract.
Parameters:
Parameter Description
Client Address * The URL to the Ethereum client.
Wallet File * The path to the wallet file containing the account credentials.
Password * The password to read the wallet file.
Gas Price The gas price in wei.
Gas Limit The maximum amount of gas that can be spent.
Available Services
186 Information Builders
Parameter Description
Value The amount of Ether (in wei) you wish to deposit in the smartcontract. This value must be 0 if the contract does not acceptEther.
ABI File * The path to the smart contract ABI file.
Binary File * The path to the smart contract binary file.
Sleep Duration The time in milli-seconds between attempts to get the transactionreceipt.
Number of Attempts The number of attempts to get the transaction receipt.
Return Determines the contents of the output document.
Edges:
The following table lists the available Line Edges for the Ethereum Deploy Agent Service(com.ibi.agents.XDEthereumDeployAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
fail_parse Could not parse a document.
fail_timeout The operation timed out.
fail_operation Could not perform the operation requested.
Ethereum Transfer Agent Service (com.ibi.agents.XDEthereumTransferAgent)
Syntax:
com.ibi.agents.XDEthereumTransferAgent
1. iWay Services
iWay Service Manager Component Reference Guide 187
iIT Service Object:
format: Ethereum Transfer Agent
Description: Transfers Ether from one Ethereum account to another.
Parameters:
Parameter Description
Client Address * The URL to the Ethereum client.
Wallet File * The path to the wallet file containing the account credentials.
Password * The password to read the wallet file.
Gas Price The gas price in wei.
Gas Limit The maximum amount of gas that can be spent.
Destination WalletAddress *
The destination account where the funds will be deposited.
Value The amount of Ether (in wei) you wish to send to the destinationaddress.
Sleep Duration The time in milli-seconds between attempts to get the transactionreceipt.
Number of Attempts The number of attempts to get the transaction receipt.
Return Determines the contents of the output document.
Edges:
The following table lists the available Line Edges for the Ethereum Transfer Agent Service(com.ibi.agents.XDEthereumTransferAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
Available Services
188 Information Builders
Line Edge Description
OnFailure A fail condition occurred during execution.
success The operation was successful.
fail_parse Could not parse a document.
fail_timeout The operation timed out.
fail_operation Could not perform the operation requested.
Excel reader Service (com.ibi.agents.XDReadExcel)
Syntax:
com.ibi.agents.XDReadExcel
iIT Service Object:
format: Excel reader
Description: Reads an Excel workbook sheet to XML.
Parameters:
Parameter Description
Workbook The full path to the workbook file to be processed. Leave blank toread from the message input stream or bytes form.
DIF * Determines if this (or every) worksheet top row contain headings.
Sheet Name The name of the sheet to access. Omit or set to * to read allsheets.
Terminate * Terminate the agent when an error occurs.
1. iWay Services
iWay Service Manager Component Reference Guide 189
Edges:
The following table lists the available Line Edges for the Excel reader Service(com.ibi.agents.XDReadExcel).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
OnParseError Could not parse a document.
OnInvalidFormat Format of the messages was invalid for theoperation requested.
OnNotFound The resource was not found and this isconsidered an error.
Execute ETL Service (com.ibi.agents.XDETLAgent)
Syntax:
com.ibi.agents.XDETLAgent
Description:
Executes EDA ETL procedures and returns ICM codes to specified edges. You can invoke thisservice from a process flow. For more information, see the iWay Integration Tools DesignerUser's Guide.
Parameters:
Parameter Description
SQL DML * SQL statement.
Data Source URL * URL to reach the data source.
Available Services
190 Information Builders
Parameter Description
Document Return Type*
Document to return. Select one of the following options from thedrop-down list:
Status
Original Input
Statistics
User ID Default user ID for the connection.
Password Default password for the connection.
Search Code Search code to search for (for example, XXX,YYY,ZZZ).
Statistic Handler The RPC to call to fetch ETL statistics. Called only when returndocument is set to Statistics.
Handler Parameters Parameters passed to the Statistic Handler.
Stats Wait The amount of time in seconds to wait after an unsuccessfulattempt to retrieve statistics.
Stats Retry The number of attempts to try retrieving ETL statistics.
Edges:
The following table lists the available line edges for the Execute ETL Service(com.ibi.agents.XDETLAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 191
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_connect
fail_parse
Fail Service (com.ibi.agents.XDFailAgent)
Syntax:
com.ibi.agents.XDFailAgent
iIT Service Object:
misc: Fail or cause retry of the message of the flow
Description:
The failure business service always returns an XDException. If the retry option is selected forthe Type of failure parameter, the exception calls for a retry of the input, if possible. Thisservice is useful when debugging rollback logic in a customer business service.
Parameters:
Parameter Description
Type of failure The type of failure to be thrown. Select one of the followingvalues from the drop-down list:
fail
retry
The default value is fail.
Message The message to be issued to the user.
Available Services
192 Information Builders
Parameter Description
Bypass Catch Processing On failure, determines whether to bypass upper-level Catchnodes. Select one of the following values from the drop-downlist:
true. Immediately ends this process thread with anuncatchable termination, bypassing error processing.
false. Allows the Fail service to participate in normal catcherror handling.
The default value is true.
The setting of this parameter has no effect on process flowswith no Catch nodes, or when issued within the execution of asingle Catch node. When multiple Catch nodes are employedin a process flow, the use of this parameter can impact theexecution flow after failure. In this case, the usual settingshould be true to cause the fail node to have immediateeffect. Setting false will cause the failure request to beprocessed by upper-level Catch nodes.
Bypass Error Message Indicates not to trace at the error level when this serviceterminates the process. This is useful for cases where thetrace log is being monitored by an external program for errors.The termination will be traced at the debug level.
The default value is false.
Add Transaction LogReport Message
When set, a transaction log entry (XALOG) is written with thefailure message. This causes a message to appear in thetransaction log analysis.
The default value is false.
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifiesthe EOS. This parameter determines whether this serviceshould be called for the EOS message.
The default value is false.
1. iWay Services
iWay Service Manager Component Reference Guide 193
Edges:
The following table lists the available line edges for the Fail Service(com.ibi.agents.XDFailAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
This service can be used in situations where a failure must be reported or simulated (forexample, if a certain fatal condition is reported). If you run this service in a process flow using<test/> as the incoming message and the retry option is selected for the Type of failureparameter, the following document is returned:
<?xml version="1.0" encoding="UTF-8" ?><eda> <error code="6" timestamp="2009-06-05T19:56:59Z" source="com.ibi.agents.XDFailAgent" stage="AGENT">XD[RETRY] cause: 0 subcause: 0 message: Retry requested from XDFailAgent</error></eda>
Otherwise, a retry is silent and the incoming message is retried later.
If the fail option is selected for the Type of failure parameter, the process flow handles thetermination as an error condition by searching upward on the execution edge to locate a Catchnode. If no Catch node is found, then the process flow is terminated. If a Catch node is found,then standard catch logic is bypassed unless the Bypass Catch Processing parameter is set tofalse.
Available Services
194 Information Builders
It is not recommended to design process flows in which failure indications are used to controlexecution logic (for example, simulating a long jump). Failure indications should only be used inthe event of actual failures.
File Accumulator Service (com.ibi.agents.XDFileAccumAgent)
Syntax:
com.ibi.agents.XDFileAccumAgent
iIT Service Object:
accumulation: File Accumulator
emit: File Accumulator
file: File Accumulator
Description:
The file accumulator service adds records to a file for the duration of the local transaction. Bystoring the output links to the file system, this service is able to achieve a level of highperformance when a significant amount of data is being written to the file.
The service can only function in a local transaction situation. For example, the channel isdesignated as a local transaction channel. The first record to reach the accumulator in theprocess flow opens the file and prepares for operation. Subsequent entries to the servicecontinue to write to the same file. A common case is either a streaming preparser or aniterator that presents multiple records to the accumulator.
The full path to the file created for the accumulation is available after each execution of thisservice in the emit.file.accum.filename special register.
Parameters:
Parameter Description
Source of Data Determines how the data is located. If this parameter is omitted, thecontent of the current input document is used.
Target Directory Directory to which the file is written.
File Pattern Standard iWay file pattern. If the file exists when the agent begins theoperation, the new data is appended to the existing file.
1. iWay Services
iWay Service Manager Component Reference Guide 195
Parameter Description
Return Determines what is placed on the outgoing document. Can be status(status document) or input (input document).
Base64 Decode If set to true, the incoming value is presumed to be in the Base64encoding. By default, this parameter is set to false.
Append CRLF If set to true, a line termination sequence is written after thedocument.
Call at EOS? In a streaming environment, EOS (End of Stream) is the short messagethat is sent after the last document, which signifies the EOS. Thisparameter determines whether this service should be called for theEOS message.
Edges:
The edges returned are listed in the following table:
Edge Description
success The item was added to the file. If the file did not exist, it was created.
fail_operation Write could not be completed.
fail_parse The configuration could not be performed. Often this is generated by aninvalid iFL statement.
fail_notfound The file to be written could not be located. This may be a path issue.
The following table lists the available line edges for the File Accumulator Service(com.ibi.agents.XDFileAccumAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
196 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse: The configuration could not be performed.Often this is generated by an invalid iFL statement.
fail_operation: The write could not be completed. Thismay be a file access issue.
fail_notfound: The file to be written could not be located.This may be a path issue
File Append Accumulation (com.ibi.agents.XDFileAppendAgent)
Syntax:
com.ibi.agents.XDFileAppendAgent
Description:
As information is presented to this agent, it is appended to a named file.
Parameters:
Parameter Description
Source of Data If empty, the input data is used. Otherwise, the source of thedata to write can be specified, for example, as an xpathexpression.
Destination File Path The full path to the file where the data is to be appended. If thefile is not open for the append operation, it is created or openedas appropriate.
1. iWay Services
iWay Service Manager Component Reference Guide 197
Parameter Description
Close File A value that, when true, causes the file to be closed. In astreaming mode, the iFL expression _iseos() can close the file atthe end of a stream, however other expressions can be used. Nodata is stored when this value is true.
Return Shows what should be returned from the agent. For example:
status. A status document from the flow.
input. Emit the original input received by this agent.
Want EOS Asks whether this agent be called at EOS. If the Close File parmis configured to test EOS, then this must be true. If anotherapproach is used, such as detecting the end of a batch of input,then this may not need to be set to true.
Available Response Edges:
Line Edge Description
success The data was appended to the file.
fail_parse Invalid iFL expression.
fail_notfound The file path cannot be located.
fail_operation The append operation failed.
This service agent differs from the appending agent offered by the file accumulation agent andthe file ops agent, in that the target file remains open. It is the responsibility of the applicationto close the file, checking with the Close File configuration value set to true.
File Directory Contents Service (com.ibi.agents.XDFileDirListAgent)
Syntax:
com.ibi.agents.XDFileDirListAgent
iIT Service Object:
file: File Directory Contents
Available Services
198 Information Builders
Description:
This service lists the contents of a file directory that is accessible through the file system. Youmay select to view files, subdirectories, or both.
Parameters:
Parameter Description
Directory The directory to be listed. This service does not descenddirectories.
Include Determines what items should be included in the listing. Selectone of the following options from the drop-down list:
Files (default)
Subdirectories
All
Selection Expression If present, this is a Java regular expression used for selection ofthe file or subdirectory. For example, to select only .xml files, youmight use ".*\.xml" as the pattern (the quotes are not includedin the pattern).
Note: The expression, .*\.xml is deconstructed as follows. Theleading dot means any character, and the asterisk means anynumber of them, until a suffix of .xml is reached. The problemwith the .xml is that the dot would mean any character, so it isescaped. Because this is not iFL syntax, the backslash does notneed to be escaped.
Pattern Type If the Selection Expression is supplied, indicate whether it shouldbe interpreted as a regular expression (regex) or a DOS stylewildcard (wildcard).
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
1. iWay Services
iWay Service Manager Component Reference Guide 199
The resulting document contains information on each entry in the directory.
Entry Description
type Identifies whether this is a file or a directory entry.
lastmod An integer value of the time the file was last modified. This is the last-modified time, measured in milliseconds since the epoch (00:00:00 GMT,January 1, 1970).
lastmodstr The last modified time as a string.
The following is an example of a generated document:
<dir base="c:\iway70" count="9"> <item type="directory" lastmod="1254257984133" lastmodstr="29 Sep 2009 20:59:44 GMT">bin</item> <item type="directory" lastmod="1256932227299" lastmodstr="30 Oct 2009 19:50:27 GMT">config</item> <item type="directory" lastmod="1254257982321" lastmodstr="29 Sep 2009 20:59:42 GMT">etc</item> <item type="file" lastmod="1256738729576" lastmodstr="28 Oct 2009 14:05:29 GMT">failagent_repro.zip</item> <item type="file" lastmod="1254256456000" lastmodstr="29 Sep 2009 20:34:16 GMT">iway70.cmd</item> <item type="directory" lastmod="1254846509643" lastmodstr="6 Oct 2009 16:28:29 GMT">lib</item> <item type="file" lastmod="1254258028321" lastmodstr="29 Sep 2009 21:00:28 GMT">license.xml</item> <item type="directory" lastmod="1254257973414" lastmodstr="29 Sep 2009 20:59:33 GMT">tools</item> <item type="file" lastmod="1254257983852" lastmodstr="29 Sep 2009 20:59:43 GMT">uninstall.exe</item></dir>
Edges:
The following table lists the available line edges for the File Directory Contents Service(com.ibi.agents.XDFileDirListAgent).
Line Edge Description
OnError Error
OnSuccess Success: the directory document wasproduced.
Available Services
200 Information Builders
Line Edge Description
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_notfound: The directory to be listedwas not found.
fail_operation: The directory to be listedwas not reachable. This can come aboutif a relative directory cannot be resolvedor the directory was not specified.Access permissions will also producethis edge.
File Emit Service (com.ibi.agents.XDFileEmitAgent)
Syntax:
com.ibi.agents.XDFileEmitAgent
iIT Service Object:
emit: File Emit Agent
file: File Emit Agent
Description:
This service writes the contents of the current document or other specified information to thefile system. The source specification can be blank or can specify any iWay expression,including XPATH(). If the document is XML and the xpath() function is specified, each valuemeeting the XPATH() criteria is written as a file. The assigned names are allocated sequentiallybased on the entered pattern.
1. iWay Services
iWay Service Manager Component Reference Guide 201
Parameters:
Parameter Description
Source of Data Determines the source of data to emit. If you require a documentto be emitted, then enter the corresponding system path for thisdocument. If no value is specified, then the current document isused by default. You can also specify an iWay expression,including the xpath() function to specify a data source location (forexample, if an XML document is used).
Target Directory * The target output directory.
File Pattern * The file name pattern. In the pattern, an asterisk (*) character isreplaced by the current timestamp. So T*.out might becomeT2002-06- 25_12:02:24:43.out. A # character is considered aunique number. The number of # characters controls the length.
Avoid Preemitter If a preemitter exists on this route for output, this allows it to bebypassed for this emit operation. Perform this action to enablethe output file to include non-processed (raw) information. Selectone of the following options from the drop-down list:
true (default)
false
Return Select one of the following options from the drop-down list:
status (default). Status document will be the outputdocument.
input. Input document will become the output document.
swap. As input, but replace written data in the source nodeswith the file name to which the data was written.
Available Services
202 Information Builders
Parameter Description
Base64 Decode If set, the value is assumed to be in base64 notation. Onlyapplicable if a specific write value is specified. Select one of thefollowing options from the drop-down list:
true
false (default)
RespectTransactionality *
If set, the emit respects the transactionality of the channel. If notset, the file is always written. Select one of the following optionsfrom the drop-down list:
true
false (default)
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
Edges:
The following table lists the available line edges for the File Emit Service(com.ibi.agents.XDFileEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 203
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
notfound
Available Services
204 Information Builders
Example:
The following is an example of configuration settings for a File Emit service object in iITDesigner:
1. iWay Services
iWay Service Manager Component Reference Guide 205
If your connection parameters are valid, after running a process flow with the File Emit service,you will find the incoming document from your process flow copied to the target directory (forexample, c:/out), with its name formatted according to the value that was specified for the FilePattern parameter (for example, testsvc[date/time mask].xml). The return document of theprocess flow would be an update from running the service, which indicates that the File Emitservice worked successfully. For example:
<?xml version="1.0" encoding="UTF-8" ?><emitstatus status="0"><protocol>FILE</protocol><parms> <parm name="directory">c:/out</parm> <parm name="return">status</parm> <parm name="wanteos">false</parm> <parm name="pattern">testsrvc*.xml</parm> <parm name="b64">false</parm> <parm name="trans">false</parm> <parm name="nopreemit">true</parm></parms><timestamp>2009-05-04T22:16:39.566Z</timestamp><status>0</status><count>1</count><name>c:\out\testsrvc2009-05-04T22_16_39.551Z.xml</name></emitstatus>
File operations Service (com.ibi.agents.XDPFFileOpsAgent)
Syntax:
com.ibi.agents.XDPFFileOpsAgent
iIT Service Object:
format: File operations
Description: Performs operations on the specified file(s) including copy, move, rename,prepend, append, delete, size, and exist.
Parameters:
Parameter Description
Operation * The command to execute when the agent goes active.
File (from) * The originating file to be operated on. Relative or absolute filepaths are supported explicitly or through iFL.
Available Services
206 Information Builders
Parameter Description
File (from) Pattern * Select from the pattern to use when searching for files.
none - the file (from) is the literal name.
dos - the file (from) contains only a DOS-like pattern syntax(*, ?).
regex - the file (from) contains full Java Regular Expressionsyntax.
File (to) The destination file to be operated on. Wild cards are accepted.Required except for delete, size, and exists.
File (to) a directoryname
File (to) references a directory. If it is unclear whether the pathnames a directory or a file name, Service Manager will assume thepath names a file.
File (to) CreateDirectories
Creates directories if they doesn't exist. Used only for copy, move,rename, and append operations.
Size A special register designated to hold size. Required for the sizeoperation.
Out Document * The document returned by the operation (bad input defaults toresult).
Action on Failure * Determines whether an input document or status document isreturned on failure.
Retry If non-zero, will retry the operation n times at one-second intervals.
Edges:
The following table lists the available Line Edges for the File operations Service(com.ibi.agents.XDPFFileOpsAgent).
Line Edge Description
OnError An exception occurred during execution.
1. iWay Services
iWay Service Manager Component Reference Guide 207
Line Edge Description
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedOperation Could not perform the operation requested.
OnNotFound The resource was not. This may or may notbe an failure.
OnParseError Could not parse a document.
File read (com.ibi.agents.XDPFFileReadAgent)
Syntax:
com.ibi.agents.XDPFFileReadAgent
iIT Service Object:
format: File read
Description:
Embeds a specified binary, xml or text file in the input document
Parameters:
Parameter Description
Name of File * The f ile to be read. Relative or absolute file paths are supportedexplicitly or through a SREG or XPath expression evaluated using theincoming document.
Delete After Read Determines whether the file is deleted on a successful read.
Available Services
208 Information Builders
Parameter Description
Format Format of the input data. Select one of the following options from thedrop-down list:
flat (default)
XML
json
stream
Tag The name of the node in which to wrap the data read, in flat format.
Character SetEncoding
The character set encoding to be performed on input. Base 64 isrequired for flat binary data.
Base64 Encode * Base64 encode the read in document when embedding.
Embed * Determines whether to embed the data from the read operation intothe input document.
Parent Tag Determines where in the input document the input data should beembedded.
Retry If non-zero, will retry the operation n times at one-second intervals.
Edges:
The following table lists the available Line Edge for the File read(com.ibi.agents.XDPFFileReadAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
1. iWay Services
iWay Service Manager Component Reference Guide 209
Line Edge Description
OnFailedOperation Could not perform the operation requested.
OnNotFound The resource was not found and this isconsidered an error.
File Read Service (com.ibi.agents.XDFileReadAgent)
Syntax:
com.ibi.agents.XDFileReadAgent
iIT Service Object:
file: File Read Agent
read: File Read Agent
Description:
The local file input accepts a request to read a file from the local file system and outputs thisrequest as an XDTextDocument. The transform business service and standard output canaccept and operate upon this output. The input business service can operate on flat or XMLdata, and can emit data in either form.
Parameters:
Parameter Description
File Name Tag * Tag of input document whose value is the file name to read. The inputdocument must be:
<filename>pathToFile</filename>
This assumes that the tagname is set to filename. If the input formatis XML or an entag parameter is used, the output is in XML form.Otherwise, the output is a flat document.
Note: The File Read Service assumes that the input data format is flatby default, or if the entag option is set to any value even if the XMLinput data format is selected.
Base Path Optional directory to be used if the incoming name is not absolute.
Available Services
210 Information Builders
Parameter Description
Input Data Format Format of the input data. Select one of the following options from thedrop-down list:
flat (default)
XML
Enclose Tag The name of the tag in which to enclose that data that is read. Ifomitted, no tagging is performed. If used, the output is XML.
Encoding Encoding to be performed on the input. Can be as is or base64. Ifomitted, no encoding is performed.
Delete After Read Determines whether the file is deleted after it is read. Select one ofthe following options from the drop-down list:
true (default)
false
Edges:
The following table lists the available line edges for the File Read Service(com.ibi.agents.XDFileReadAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 211
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
locked
directory
notfound
fail_parse
fail_operation
Example:
To configure a File Read service, you must specify the tag name that contains the path to thefile you want to read. The following is an example of configuration settings for a File Readservice object in iIT Designer. This example assumes that the path to the file is containedwithin the <Test> tag of the incoming document:
Run this service with a document such as the following:
<Test>c:/out/input.xml</Test>
The contents of the input.xml file will be received as the output.
Available Services
212 Information Builders
Form Data Agent Service (com.ibi.agents.XDFormDataAgent)
Syntax:
com.ibi.agents.XDFormDataAgent
iIT Service Object:
format: Form Data Agent
Description: Transforms key=value form data into an XML string with <post> as the root.
Parameters:
Parameter Description
Name * The name of the new Service object definition.
Description The description for the new Service object definition.
Edges:
The following table lists the available Line Edges for the Form Data Agent Service(com.ibi.agents.XDFormDataAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
failed_operation Could not perform the operation requested.
FTP and SFTP Services
iWay FTP and SFTP (SSH/secure) services provide tools that simplify the development andimplementation of applications where file transport services are required. iWay ServiceManager (iSM) provides the following FTP and SFTP services.
1. iWay Services
iWay Service Manager Component Reference Guide 213
FTP Services
FTP Connection Cache Service
com.ibi.agents.XDNFTPConnectionCacheAgent
FTP Direct Transfer to Disk Service
com.ibi.agents.XDNFTPDirectFileTransferAgent
FTP Directory Contents Service
com.ibi.agents.XDNFTPDirListAgent
FTP File Emit Service
com.ibi.agents.XDNFTPEmitAgent
FTP File Operations for Process Flows Service
com.ibi.agents.XDNPFFTPOpsAgent
FTP File Read for Process Flows Service
com.ibi.agents.XDNPFFTPReadAgent
FTP Read Document Service
com.ibi.agents.XDNFTPReadAgent
FTP SREG Service (com.ibi.agents.XDFTPSREGAgent)
com.ibi.agents.XDFTPSREGAgent
SFTP Services
SFTP Connection Cache Service
com.ibi.agents.XDSFTPConnectionCacheAgent
SFTP Direct Transfer to Disk Service
com.ibi.agents.XDSFTPDirectFileTransferAgent
SFTP Directory Contents Service
com.ibi.agents.XDSFTPDirListAgent
SFTP Emit Service
Available Services
214 Information Builders
com.ibi.agents.XDSFTPEmitAgent
SFTP File Ops Service
com.ibi.agents.XDSFTPFileOpsAgent
SFTP Read Service
com.ibi.agents.XDSFTPReadAgent
For detailed information on each of these FTP and SFTP services, see the iWay FTP SolutionsDevelopment Guide .
HTTP Client Service (com.ibi.agents.XDNHttpEmitWithOAuth)
Syntax:
com.ibi.agents.XDNHttpEmitWithOAuth
iIT Service Object:
format: HTTP Client
Description: A general HTTP client with support for two-legged OAuth 2.0.
Parameters:
Parameter Description
Target URL * The URL to which to post this information, for example, http://thehost:9876.
Action Method POST sends current document as a request entity. GET andHEAD will send a request to a configured URL. HEAD willalways return a status document.
HTTP Client Provider * The HTTP Client Provider (Pooling Provider) that manages HTTPconnections for this emitter.
Request Content Type The content type for HTTP requests to be sent by this emitter.
1. iWay Services
iWay Service Manager Component Reference Guide 215
Parameter Description
Request HeaderNamespace
The special register namespace from which HTTP headers forthe outgoing request will be taken. Choose Default Namespaceto send HDR type registers with no namespace prefix, orsupply a namespace prefix here. None means that no specialregisters will be sent as HTTP headers.
Response HeaderNamespace
The special register namespace into which HTTP headers fromthe incoming response will be saved. Choose DefaultNamespace to create special registers with no namespaceprefix, or supply a namespace prefix here.
Authentication
User ID User ID for authentication challenges
Password Password for authentication challenges
Domain Domain for NTLM authentication challenges; Note that to useNTLM, you must enable connection persistence.
OAuth 2.0
Authorization Server URL The URL where a new access token can be retrieved. The URLshould be fully specified, including the https scheme.
HTTP Method for TokenRequest
POST sends a URL-encoded entity, GET sends the requestwithout a request entity.
Token Field The name of the field that holds the token in the JSONresponse.
Expiration Field The name of the field in the JSON response that specifies thelength of time (in seconds) for which the token is valid.
Grant Type Specifies the requested response type. Usuallyclient_credentials.
Client ID The client or App ID for the caller. This will be sent as the userID in basic authentication credentials with the authorizationrequest, and, if specified, encoded in the body of a POSTrequest to the authorization server.
Available Services
216 Information Builders
Parameter Description
Client Secret The client or App secret for the caller. This will be sent as thepassword in basic authentication credentials with theauthorization request, and, if specified, encoded in the body ofa POST request to the authorization server.
Encode Client Credentialsin Request Body
If true, the client ID and client secret will be encoded in thebody of a POST request to the authorization server, in additionto being used as basic authentication credentials.
Resource The App ID URI of the receiving web service.
Resource OwnerUsername
The username to encode in the POST body when grant type ispassword.
Resource OwnerPassword
The password to encode in the POST body when grant type ispassword.
Special RegisterNamespace for AdditionalRequest Fields
If specified, registers in this namespace will be included asfields in body of a POST request.
Default Expiration Time The time in seconds a token can stay in the token store.Applies only to tokens without a specific expiration time.
Advanced
Persistence If checked, ask the server to maintain the connection.
Response Timeout valuein Seconds *
Time in seconds to wait for a response before signalling error.
Ask for CompressedResponse
If set, requests will set the Accept-Encoding header to indicatethat the client can accept a compressed response, asdescribed in RFC-2616. If the response has a compressedcontent encoding, the client will automatically inflate.
Compress Request If set, the HTTP request entity will be compressed using theselected encoding and the Content-Encoding header will be setaccordingly.
1. iWay Services
iWay Service Manager Component Reference Guide 217
Parameter Description
Try Expect/ContinueHandshake?
If checked, client will send the HTTP Expect: 100-continueheader and await HTTP 100 response before sending requestbody.
Chunk Encoded Request? If true, a request entity will be sent with chunk encoding.
Maximum Request Size The maximum size, after compression, of a request entity thatcan be sent with this emitter. 0 means no maximum and blankwill default to 256KB.
Maximum Response Size The maximum size of a response entity that can be receivedby this emitter. 0 means no maximum and blank will default to256KB.
Edges:
The following table lists the available Line Edges for the HTTP Client Service(com.ibi.agents.XDNHttpEmitWithOAuth).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailConnection Could not connect to the external system.
OnFailRedirection Redirection status code between 300 and399.
OnFailClientError Client error status code between 400 and499.
OnFailServerError Server error status code between 500 and599.
OnFailedOperation Could not perform the operation requested.
Available Services
218 Information Builders
Line Edge Description
OnParseError Could not parse a document.
OnFailLargeRequest Request entity size exceeds configuredmaximum.
OnFailLargeResponse Response entity size exceeds configuredmaximum.
OnHTTP-201 Created The request was successful, we created anew resource and the response bodycontains the representation.
OnHTTP-400 Bad Request The data given in POST or PUT failedvalidation. Inspect the response body fordetails.
OnHTTP-401 Unauthorized The supplied credentials, if any, are notsufficient to create or update the resource.
OnHTTP-404 Not Found Resource not found.
OnHTTP-405 Method Not Allowed You can't POST or PUT to the resource.
OnHTTP-405 Too Many Requests Your application is sending too manysimultaneous requests.
OnHTTP-500 Server Error We could not create or update the resource.Please try again.
HTTP Cookie Agent Service (com.ibi.agents.XDCookieAgent)
Syntax:
com.ibi.agents.XDCookieAgent
iIT Service Object:
format: HTTP Cookie Agent
Description: Adds a cookie to the HTTP Response.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 219
Parameter Description
Cookie Name * The name of the cookie.
Cookie Value The value of the cookie; the value set must comply with RFC6265.
Path Attribute The value of the path attribute in the generated cookie. Thevalue "/" matches any path.
Domain Attribute The value of the domain attribute in the generated cookie.Leave empty to match the originating server.
Max-Age Attribute The value of the Max-Age attribute in the generated cookie.This indicates the maximum lifetime of the cookie,represented in number of seconds. Leave blank to omit theattribute, which lets the user agent determine when the cookieexpires.
Secure Attribute Determines whether to add the secure attribute in thegenerated cookie. Automatic adds the attribute only if thelistener is secure.
HttpOnly Attribute Determines whether to add the HttpOnly attribute in thegenerated cookie.
Edges:
The following table lists the available Line Edges for the HTTP Cookie Agent Service(com.ibi.agents.XDCookieAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedOperation Could not perform the operation requested.
OnParseError Could not parse a document.
Available Services
220 Information Builders
HTTP Client Pool Manager Service (com.ibi.agents.XDHttpClientManager)
Syntax:
com.ibi.agents.XDHttpClientManager
iIT Service Object:
format: HTTP Client Pool Manager
Description: Given a key (usually received in register httpclient-key from emit service) forhttpclient in the pool, replace or terminate it. Used to manually manage the client pool.
Parameters:
Parameter Description
Type * The available Service types.
Edges:
The following table lists the available Line Edges for the HTTP Client Pool Manager Service(com.ibi.agents.XDHttpClientManager).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseErrorOperation Could not parse a document.
HTTP Emit Service (com.ibi.agents.XDHTTPEmitAgent)
Syntax:
com.ibi.agents.XDHTTPEmitAgent
iIT Service Object:
emit: HTTP Emit Agent
http: HTTP Emit Agent
1. iWay Services
iWay Service Manager Component Reference Guide 221
Description:
This service is a general HTTP emitter for use within the service stack. The document is postedusing HTTP to a designated server.
Parameters:
Parameter Description
Target URL * Specify a URL to post this information.
Action Method Select one of the following methods from the drop-down list:
GET. Data on the URL and URL encoded.
POST (default). Content-Length header.
Response contenttype
Overrides content type of response. Select one of the followingoptions from the drop-down list:
application/EDI-X12
application/EDIFACT
application/XML
text/html
text/plain
User ID User ID for Basic Authentication challenges.
Password Password for Basic Authentication challenges.
Response timeoutvalue in seconds
Seconds to wait for response before signaling error.
IP Interface Host Local IP Interface from which the outgoing IP socket originates.
IP Interface Port Local IP Port from which the outgoing IP socket originates.
Available Services
222 Information Builders
Parameter Description
Relay Inbound ContentType
If set to true, relay headers as received (content type). Select oneof the following options from the drop-down list:
true
false (default)
Proxy
Proxy If set to true, emit through proxy server. Select one of thefollowing options from the drop-down list:
true
false (default)
Proxy URL URL of the proxy server.
Proxy User ID User ID for proxy challenges.
Proxy Password Password to access the proxy server.
HTTPS
Secure Connection Use a secure connection. You may need to configure the Keystoreunder HTTPS section of the system properties if clientauthentication is required. Note, if keystore is configured insystem properties make sure it has the CA certificate or the clientcertificate of the server you're connecting to. If keystore is notconfigured in system properties default truststore located underJRE_HOME/lib/security/cacerts will be used. Select one of thefollowing options from the drop-down list:
true
false (default)
1. iWay Services
iWay Service Manager Component Reference Guide 223
Parameter Description
Use 128-bit Encryption Enforces the use of 128-bit encryption. Select one of the followingoptions from the drop-down list:
true
false (default)
Security Protocol Select one of the following security protocols from the drop-downlist:
SSL. Supports some version of SSL; may support otherversions.
SSLv2. Supports SSL version 2 or higher.
SSLv3. Supports SSL version 3; may support other versions.
TLS (default). Supports some version of TLS; may supportother versions.
TLSv1. Supports TLS version 1; may support other versions.
Agent Specific Parameters
Return * Return from this agent. Select one of the following options fromthe drop-down list:
input
response (default)
status
Use Preemitters If set to true, preemitters will be used for this emit. Select one ofthe following options from the drop-down list:
true (default)
false
Response WrapperTag
The tag name with which to wrap the response if the response isnon-XML and must be XML
Available Services
224 Information Builders
Parameter Description
Response Base64Encoded
Determines whether the response should be Base64 encoded.Select one of the following options from the drop-down list:
true
false (default)
The result of the post appears in the <native> section of the <emitstatus> result. If the Returnparameter value is STATUS, the status message is always generated. If it is RESPONSE (thedefault) the actual information returned from the POST is emitted, except in the cases of anerror in which case the status information is emitted. The POST is considered successful if thePOST can reach its destination and a 200 status is received. A successful return response isconsidered to be XML if the first character is a <. Otherwise, a flat document is created.
Edges:
The following table lists the available line edges for the HTTP Emit Service(com.ibi.agents.XDHTTPEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_connect
1. iWay Services
iWay Service Manager Component Reference Guide 225
Example:
The following is an example of configuration settings for an HTTP Emit service object in iITDesigner:
Available Services
226 Information Builders
A simple way to test your HTTP Read service is to first configure a channel that uses an HTTPlistener as the inlet and a File emitter as the outlet to examine the messages that are receivedby the listener. Your HTTP listener configuration settings would look similar to the followingexample, where an HTTP port and a document root are specified.
After you deploy and start the channel with the HTTP listener and File emitter, you can test runyour process flow, which contains an HTTP Emit service object. You must supply an incomingdocument with the appropriate content (for example, HTML):
<html> <head> <title>my iWay http</title> </head> <body> Testing HTTP Emit Service! </body></html>
If the service runs successfully, you will receive this HTML document in the output folder thatis specified by your File emitter. The HTTP listener channel picks up the document that isemitted by the HTTP Emit service.
HTTP Nonblocking Emit Service (com.ibi.agents.XDNHttpEmitAgent)
Syntax:
com.ibi.agents.XDNHttpEmitAgent
1. iWay Services
iWay Service Manager Component Reference Guide 227
iIT Service Object:
emit: HTTP Nonblocking Emit
http: HTTP Nonblocking Emit
Description:
Emits HTTP messages to a client without interrupting a configured business process. For moreinformation, see the iWay Service Manager Protocol Guide.
Parameters:
Parameter Description
Configuration Parameters
Target URL URL that is used to post this information.
HTTP Client Provider HTTP client Provider that is used to manage connections forthis emitter.
Cookie Store Name Allows thread-specific management of cookies. If notspecified, a cookie store global to the HTTP Client provider willbe used.
Action Method Select one of the following supported methods from the drop-down list:
GET method with data on the URL and URL Encoded.
POST method with a Content-Length header.
Request Content Type Content type for the HTTP request to be sent by this emitter.Select a value from the drop-down list or provide your own.
User ID User ID for Basic Authentication challenges.
Password Password for Basic Authentication challenges.
Domain Domain for NTLM authentication challenges. Note that to useNTLM, you must enable connection persistence.
Available Services
228 Information Builders
Parameter Description
Request HeaderNamespace
Special register namespace from which HTTP headers for theoutgoing request will be taken. Choose Default Namespace tosend HDR type registers with no namespace prefix, or supplya namespace prefix here. None means that no specialregisters will be sent as HTTP headers.
Default Namespace. Sends HDR type registers with nonamespace prefix.
Supply a namespace prefix here to indicate which headersto send.
none. Means that no special registers will be sent as HTTPheaders.
Request Main Part HeaderNamespace
Special register namespace from which MIME headers for theoutgoing request will be taken. Provide a prefix to control therequest Main BodyPart headers in the presence ofattachments. Selecting none means that no special registerswill be sent as MIME headers.
Response HeaderNamespace
Special register namespace into which HTTP headers from theincoming response will be saved. Choose Default Namespaceto create special registers with no namespace prefix, orsupply a namespace prefix here. None means that no specialregisters will be created.
Default Namespace. Creates special registers with nonamespace prefix.
Supply a namespace prefix here to indicate headernamespace.
Empty namespace prefix will be treated as default.
Excluded Headers A comma delimited list (case insensitive) of headers thatshould not be sent with the request, even if they are found inthe request header namespace.
1. iWay Services
iWay Service Manager Component Reference Guide 229
Parameter Description
Ask for CompressedResponse
If set to true, the request will set the accept-encoding toindicate that the client can accept a compressed response. Ifthe response has a compressed content encoding, the clientwill automatically inflate the response.
Compress Request If set to true, the request entities will be compressed usingthe selected encoding and the content-encoding header willbe set accordingly.
Replace Connection? If set to false, the connection is not returned to theconnection pool immediately. The identifier of the connectionwill be stored in the HTTP client-key special register and theconnection can be handled by the HTTP Client Manager agent.
Maximum HTTP ClientManager Delay
Maximum time the HTTP Client Manager can take to handle aparticular connection before it is automatically aborted. Theformat is [xxh][xxm]xx[s]. The default is 60 seconds.
Try Expect/ContinueHandshake?
If checked, client will send the HTTP Expect: 100-continueheader and await HTTP 100 response before sending requestbody.
Chunk Encoded Request? If set to true, request entity will be sent with chunk encoding.
Maximum Request Size Maximum size, after compression, of a request entity that canbe sent with this emitter. A value of 0 means no maximumand if no value is specified, the parameter defaults to 256KB.
Maximum Response Size Maximum size of a response entity that can be received bythis emitter. 0 means no maximum and blank will default to256KB.
TCP Properties
Persistence If checked, ask the server to maintain the connection.
Response Timeout valuein Seconds
The value in seconds to wait for a response before generatingan error.
Agent Specific Parameters
Available Services
230 Information Builders
Parameter Description
Return Return from this agent. Choose input to return inputdocument, status for an XML document with transactionparameters and status, or response to capture output fromthe server.
Preemitter If set to true, the preemitters will not run.
Response Wrapper Tag The tag name with which to wrap the response if the responseis non-XML and must be XML.
Response Base64Encoded
If set to true, the response will use Base64 encoding.
Edges:
The following table lists the available line edges for the HTTP Nonblocking Emit Service(com.ibi.agents.XDNHttpEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 231
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_connect
fail_info
fail_redirection
fail_client
fail_server
fail_operation
fail_parse
fail_request_too_large
fail_response_too_large
HTTP Read Service (com.ibi.agents.XDHTTPReadAgent)
Syntax:
com.ibi.agents.XDHTTPReadAgent
iIT Service Object:
http: HTTP Read Agent
read: HTTP Read Agent
Description:
This service reads an HTTP source using HTTP GET and returns a result. The GET facility inputaccepts a URL in the incoming document and issues an HTTP GET through that URL. Thetransform business service and standard output can accept and operate upon this output. It ispresumed that some output is returned, otherwise an error is generated.
Available Services
232 Information Builders
In a use case scenario, the HTTP Read service can be part of an architecture for a web searchengine, similar to the Google search engine. The service could be used to traverse or spiderthe contents of webpages for indexing purposes.
Parameters:
Parameter Description
URL Tag Name * Tag name is the input document containing the URL.
The input document might be the following assuming that the tagname parameter is set toinurl:
<?xml version="1.0"?><inurl>http://localhost:1234/xmlone.xml</inurl>
Edges:
The following table lists the available line edges for the HTTP Read Service(com.ibi.agents.XDHTTPReadAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 233
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_1xx
fail_2xx
fail_3xx
fail_4xx
fail_5xx
fail_6xx
fail_connect
fail_operation
fail_parse
fail_timeout
cancelled
Available Services
234 Information Builders
Example:
The following is an example of configuration settings for an HTTP Read service object in iITDesigner:
A simple way to test your HTTP Read service is to first configure a channel that uses an HTTPlistener. Your HTTP listener configuration settings would look similar to the following example,where an HTTP port and a document root are specified.
1. iWay Services
iWay Service Manager Component Reference Guide 235
After you deploy and start the channel with the HTTP listener, you can test run your processflow, which contains an HTTP Read service object. You must ensure that the file name yousupply within the <Test> tag of your incoming document is valid and is also contained withinthe document root folder specified for your HTTP listener configuration settings. A sample HTTPread incoming document can have the following format:
<Test>http://localhost:1234/index1.htm</Test>
If the service ran successfully, you will receive the contents of index1.hml as the output fromthe service. For example:
HTTP ReST Routing Service (com.ibi.agents.XDReSTRouteAgent)
Syntax:
com.ibi.agents.XDReSTRouteAgent
iIT Service Object:
http: HTTP ReST Routing Service
Description:
This service routes a ReST request to a process flow based on the request method and path.An HTTP ReST Routing Reviewer (com.ibi.reviewer.XDReSTRouteReviewer) is also provided,which shares the same parameters as the service.
Available Services
236 Information Builders
The main purpose of these components is to identify a process flow to execute, given a URIpath and the type of the HTTP request. The name of the process flow will be stored in a specialregister (SREG). In addition to this routing function, some elements in the URI path, and allkeys and values in the URI query string, will be stored as SREGs. This functionality will bemade available as a service for use within a process flow, but also as a reviewer. This allowsfor earlier execution in the processing stage to allow conditional routing to handle theexecution of the identified process flow.
Parameters:
Parameter Description
Route File Path * The path to the XML file describing the route. The file is loadedwhen the service is first executed and remains in effect until thelistener is restarted.
ReST Verb * The HTTP verb (PUT, POST, DELETE, or GET).
Hint: In nHTTP this is in the SREG called reqType.
URI * The URI of the incoming HTTP request. In nHTTP, this is stored inthe SREG called url. This may include a path and a query string.
Flow Name Register * An SREG of this name will be created with the name of theprocess flow to run.
Route Namespace SREG namespace prefix to use when creating SREGs from pathsteps, including the process flow name register.
Query Namespace SREG namespace prefix to use when creating SREGs from thequery string portion of the URI.
Output Type Determines in the event of a routing error, what document shouldbe output from this service. Select one of the following documenttypes:
status
input
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 237
The following table lists the available line edges for the HTTP ReST Routing Service(com.ibi.agents.XDReSTRouteAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_notfound
fail_route
fail_security
HTTP Session Invalidator Agent Service (http_session_invalidator_agent)
Syntax:
http_session_invalidator_agent
iIT Service Object:
format: HTTP Session Invalidator Agent
Description: Invalidates an HTTP Session.
Parameters:
Parameter Description
Expire Cookie Determines whether an expired JSESSIONID cookie is sent todelete the cookie in the client.
Edges:
Available Services
238 Information Builders
The following table lists the available Line Edges for the HTTP Session Invalidator AgentService (http_session_invalidator_agent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedOperation Could not perform the operation requested.
OnParseError Could not parse a document.
Hyperledger Fabric Key History Agent Service (com.ibi.agents.XDFabricKeyHistoryAgent)
Syntax:
com.ibi.agents.XDFabricKeyHistoryAgent
iIT Service Object:
format: Hyperledger Fabric Key History Agent
Description: Queries a Hyperledger Fabric Channel for the history of a key.
Parameters:
Parameter Description
Fabric Channel Provider * The name of the Fabric Channel Provider.
Namespace * The namespace of the key. This is usually the chaincodename.
Key * The name of the key.
Block Number * The number of a block containing a transaction with a write ofthe key. This is a non-negative integer block number, or anegative integer block number relative to the current blockheight (-1 is the latest block).
1. iWay Services
iWay Service Manager Component Reference Guide 239
Parameter Description
Transaction Number * The index of the transaction within the selected block.
Encoding Determines how the value will be converted to a string.Choose UTF-8, type a Charset name to convert the bytes tostring, or choose Hex to convert the ByteString to a hex-encoded string with two hex characters per byte.
Early Limit The format is yyyy-MM-dd'T'HH:mm:ss.SSSXXX where XXX isan ISO 8601 time zone. Limit the key history depth to keywrites timestamped earlier than the early limit. Timestampsare created by clients without a central clock. It is thereforerecommended to specify a date earlier than necessary bysome margin.
Maximum Depth The maximum number of versions of the key to report.
History Format The format of the history in the output document,
Edges:
The following table lists the available Line Edges for the Hyperledger Fabric Key History AgentService (com.ibi.agents.XDFabricKeyHistoryAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedOperation Could not perform the operation requested.
OnFailParse Could not parse a document.
Hyperledger Fabric Query Agent Service (com.ibi.agents.XDFabricQueryAgent)
Syntax:
com.ibi.agents.XDFabricQueryAgent
Available Services
240 Information Builders
iIT Service Object:
format: Hyperledger Fabric Query Agent
Description: Calls chaincode to query a blockchain in the Hyperledger Fabric.
Parameters:
Parameter Description
Fabric Channel Provider * The name of the Fabric Channel Provider.
Chaincode Name * The name of the chaincode to call.
Chaincode Path * The path of the chaincode to call.
Chaincode Version * The version of the chaincode to call.
Return Value Format How the ByteString return value should be interpreted.
Call
Argument Type The data type of all the chaincode arguments, either a regularstring, or a byte array encoded as a hex string with twoconsecutive hexadecimal characters per byte.
Argument 0 The value of the first argument.
Argument 1 The value of the second argument.
Argument 2 The value of the third argument.
Argument 3 The value of the fourth argument.
Argument 4 The value of the fifth argument.
Edges:
The following table lists the available Line Edges for the Hyperledger Fabric Query AgentService (com.ibi.agents.XDFabricQueryAgent).
Line Edge Description
OnError An exception occurred during execution.
1. iWay Services
iWay Service Manager Component Reference Guide 241
Line Edge Description
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedOperation Could not perform the operation requested.
OnFailParse Could not parse a document.
Hyperledger Fabric Query Block Agent Service (com.ibi.agents.XDFabricQueryBlockAgent)
Syntax:
com.ibi.agents.XDFabricQueryBlockAgent
iIT Service Object:
format: Hyperledger Fabric Query Block Agent
Description: Queries a Hyperledger Fabric Channel for block information.
Parameters:
Parameter Description
Fabric Channel Provider * The name of the Fabric Channel Provider.
Query Type Determines the search criteria for the block query.
Query Argument * When querying by block number, this is a non-negative integerblock number, or a negative integer block number relative tothe current block height (-1 is the latest block). When queryingby block hash, this is a hex-encoded string with two hexcharacters per byte. When querying by transaction ID, this isthe transaction ID.
Output Format The format of the result.
Batch Mode
Available Services
242 Information Builders
Parameter Description
Early Limit The format is yyyy-MM-dd'T'HH:mm:ss.SSSXXX where XXX isan ISO 8601 time zone. Specifying an Early Limit turns onbatch mode which will always return the queried block, andalso includes the previous blocks up to but not including thefirst encountered block with all transactions timestampedearlier than the early limit. Timestamps are created by clientswithout a central clock. It is therefore recommended to specifya date earlier than necessary by some margin. The batch isalso limited by the Batch Size when defined.
Batch Size Specifying a batch size turns on batch mode which will returnup to that many blocks, starting from the queried block and itsprevious blocks, within the limits of the Early Limit if defined orthe origin of the chain.
Edges:
The following table lists the available Line Edges for the Hyperledger Fabric Query Block AgentService (com.ibi.agents.XDFabricQueryBlockAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedOperation Could not perform the operation requested.
OnFailParse Could not parse a document.
Hyperledger Fabric Transaction Agent Service (com.ibi.agents.XDFabricAgent)
Syntax:
com.ibi.agents.XDFabricAgent
iIT Service Object:
format: Hyperledger Fabric Transaction Agent
1. iWay Services
iWay Service Manager Component Reference Guide 243
Description: Calls chaincode to execute a transaction on a blockchain in the HyperledgerFabric.
Parameters:
Parameter Description
Fabric Channel Provider * The name of the Fabric Channel Provider.
Chaincode Name * The name of the chaincode to call.
Chaincode Path * The path of the chaincode to call.
Chaincode Version * The version of the chaincode to call.
Minimum SuccessfulProposals
The minimum number of successful proposals required tosend the transaction to the orderers.
Maximum FailedProposals
The maximum number of failed proposals tolerated. Thetransaction will not be sent to the orderers if there are morefailed proposals.
Return Determines the contents of the output document. Ignored ifasynchronous mode is selected.
Call
Argument Type The data type of all the chaincode arguments, either a regularstring, or a byte array encoded as a hex string with twoconsecutive hexadecimal characters per byte.
Argument 0 The value of the first argument.
Argument 1 The value of the second argument.
Argument 2 The value of the third argument.
Argument 3 The value of the fourth argument.
Argument 4 The value of the fifth argument.
Asynchronous
Available Services
244 Information Builders
Parameter Description
Is Asynchronous? In asynchronous mode, the input document is returnedimmediately after the proposal request. The TransactionEventresponse is sent to an internal queue when it arrives.
Queue Name The name of the internal queue where the asynchronousTransactionEvent will be sent.
Event Format The format of the document sent to the internal queue.
Want User Registers User registers are processing variables and their values. If youwant these registers to be emitted with the message, set thisto true. In resubmit operations, this is usually set to false.
Priority The priority is an integer between 0 and 9 inclusive. Thelowest priority is 0. The highest most expedited priority is 9.
Put Timeout Time, in milliseconds, to wait for queue to become availablewhen attempting to put a message on the queue. You canenter 0 for an unlimited wait, but this is not recommended. Ifno value is supplied, timeout will be set to 3000 milliseconds.
Request ContextNamespace
For synchronous or asynchronous processing, namespace orlist of namespaces containing registers that will be madeavailable to the internal listener. Select Default for all registersin default (no prefix) namespace or None to send no registersat all. Enter '*' for registers from all namespaces.
Edgehs:
The following table lists the available Line Edges for the Hyperledger Fabric Transaction AgentService (com.ibi.agents.XDFabricAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
1. iWay Services
iWay Service Manager Component Reference Guide 245
Line Edge Description
OnFailedOperation Could not perform the operation requested.
OnFailParse Could not parse a document.
IEI Feed Agent Service (com.ibi.agents.IEIFeedAgent)
Syntax:
com.ibi.agents.IEIFeedAgent
iIT Service Object:
format: IEI Feed Agent
Description: Posts input to a search appliance with a specified query string.
Parameters:
Parameter Description
Search Appliance URL * The URL for the search appliance.
Feed Datasource * The datasource for search appliance feeds.
Base URL * The base URL for indexed feeds.
Batch Size * the number of records to add to the feed before submitting tothe search appliance.
Secure Search? * If checked, use HTTP basic authentication to secure the feedand queries.
Feed Type * FULL replaces all previous data in the index from thisdatasource. INCREMENTAL adds new data to index, leavingexisting data.
Action * The action to be applied to this record in the search appliance.If add, the URL and content will be added to the index. Ifdelete, the URL is removed from the index.
Available Services
246 Information Builders
Parameter Description
Content Type * The mime type of the content that will be indexed. Use text/plain for XML.
Idle Limit * The maximum time in seconds that a feed containing recordscan wait before posting to the search appliance.
Strip XML Tags? * Determines whether < and > and quote characters be strippedfrom feed. The search appliance will not index text inside ofXML tags, so this option is useful when indexing XML data.
Output Type * Determines whether the agent simply outputs its input, orwhether it outputs an XML status document.
Edges:
The following table lists the available Line Edges for the IEI Feed Agent Service(com.ibi.agents.IEIFeedAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedOperation Could not perform the operation requested.
Inflate Service (com.ibi.agents.XDInflateAgent)
Syntax:
com.ibi.agents.XDInflateAgent
iIT Service Object:
misc: Inflate Agent
Description:
This service is used decompress the data that is compressed by the Deflate service(com.ibi.agents.XDDeflateAgent).
1. iWay Services
iWay Service Manager Component Reference Guide 247
Parameters:
Parameter Description
Inflated Format * Determines the format of the inflated output. Select one of thefollowing options from the drop-down list:
bytes (default)
xml
If xml is selected, the output will be parsed.
Edges:
The edges returned are listed in the following table.
Edge Description
success Successful operation.
fail_operation The decompression could not be performed. The data is probably notdeflated.
fail_parse The compressed data could not be accessed.
Inserts data inside an XML document Service (com.ibi.agents.XDDocInsertAgent)
Syntax:
com.ibi.agents.XDDocInsertAgent
iIT Service Object:
format: Inserts data inside an XML document
Description: Inserts data inside an XML document. This is a specialized, high-speedtransformation for special situations.
Parameters:
Available Services
248 Information Builders
Parameter Description
Data Source * The text or XML data to insert in the document.
Data Format Determines how the Data Source is interpreted. The Textformat treats the Data Source as character data. The XMLformat parses the Data Source as an XML fragment within theXML Namespace context of the Parent Element.
Replace Content Determines whether the existing children of the parent nodeare removed before the data is inserted.
XML Namespace Provider The provider for the mapping between XML namespace prefixand namespace URI in XPath expressions. If left blank, theXPath expressions in the Parent Element and the Next Siblingcannot contain namespaces.
XPath Syntax Determines which syntax level of XPath should be used. Thedefault option selects the syntax level as set in the consoleglobal settings.
Create Parent Element Determines whether the parent element is created, if it ismissing.
Parent Element The path to the element where the data will be inserted. If leftblank, the parent is the root element. If Create Parent Elementis true, the expression must adhere to Restricted XPathsyntax, otherwise the expression may adhere to the full syntaxof the XPath engine selected by the XPath Syntax parameter.Restricted XPath has the form /step1/step2/... where a stephas the form ns:elem[predicate] or a pair of consecutive stepsthat has the form *[1]/self::ns:elem[predicate] to indicate theelement must be the first child of its parent. The namespaceprefixes are optional, but if present they must be declared inthe XML Namespace provider. The predicate is optional, whenpresent it has the form [@ns1:attr1='val1' and@ns2:attr2='val2' and ...]. If no element matches theRestricted XPath expression and Create Parent Element istrue, then the necessary elements and attributes will becreated such that the expression would match successfully.
1. iWay Services
iWay Service Manager Component Reference Guide 249
Parameter Description
Next Sibling The path to the next sibling node. If the sibling node is found,the data will be inserted before this node, otherwise the datais added as the last child of the Parent Element.
Edges:
The following table lists the available Line Edges for the Inserts data inside an XML documentService (com.ibi.agents.XDDocInsertAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedOperation Could not perform the operation requested.
OnParseError Could not parse a document.
Insert SAML Assertion Service (com.ibi.agents.XDInsertSAMLAssertionAgent)
Syntax:
com.ibi.agents.XDInsertSAMLAssertionAgent
iIT Service Object:
security: Insert SAML Assertion
Description:
This service is used to generate a WSSE SecurityTokenReference containing an embeddedSAML assertion.
For more information about the Insert SAML Assertion service, see the iWay Service ManagerSecurity Guide.
Available Services
250 Information Builders
Insert WSSE Timestamp Service (com.ibi.agents.XDInsertWSSETimestampAgent)
Syntax:
com.ibi.agents.XDInsertWSSETimestampAgent
iIT Service Object:
security: Insert WSSE Timestamp
Description:
This service is used to generate a WSSE Timestamp.
For more information about the Insert WSSE Timestamp service, see the iWay Service ManagerSecurity Guide.
Insert WSSE Token Service (com.ibi.agents.XDInsertWSSETokenAgent)
Syntax:
com.ibi.agents.XDInsertWSSETokenAgent
iIT Service Object:
security: Insert WSSE Token
Description:
This service is used to generate a WSSE Binary Security Token containing an X509 certificate.
For more information about the Insert WSSE Token service, see the iWay Service ManagerSecurity Guide.
Internal Emit Service (com.ibi.agents.XDInternalEmitAgent)
Syntax:
com.ibi.agents.XDInternalEmitAgent
iIT Service Object:
emit: Internal Emit Agent
Description:
This service is used to send a message to an internal queue. The message is marshaled withits context and placed on the queue for execution by the internal queue listener and channel.The messages are picked up from the queue to be processed in the order they arrived.Messages can be intermixed where appropriate with pending messages that are waiting to beprocessed.
1. iWay Services
iWay Service Manager Component Reference Guide 251
Parameters:
Parameter Description
Queue Name * The name of the internal queue that is serviced by an internal queuelistener. The queue is created when the channel is started and existsas long as the server is running.
Want UserRegisters
If set to true, user-type registers are passed to the destination queue.DOC and HDR registers are always transferred with the message. Bydefault, this parameter is set to false.
Priority Determines the relative priority of the message. Use this parameter toreorder the execution of messages. Only the relative numbers matter.Higher numbers do not execute messages faster, only the acquisitionorder by the internal channel is affected. By default, this parameter isset to 4.
Put Timeout Determines the amount of time that the emit will wait for the internalchannel to accept the message. If the destination queue is inhibited,the emit is paused until the message can be accepted. If the timeoutperiod expires, a status message is sent down the timeout edge, whereyour application might chose to pend the message. For moreinformation on using inhibition to provide cascading flow congestionmanagement, see Chapter 1, Introducing iWay Service Manager in theiWay Service Manager User's Guide.
Request ContextNamespace
By specifying a namespace, registers in that namespace will be sent tothe destination queue. This is used to limit the registers to those ofinterest to the message process.
ResponseContextNamespace
This parameter is used only for synchronous emits. If set, registersreturned from the internal channel are placed into this namespace.
Available Services
252 Information Builders
Parameter Description
Return * Select one of the following options from the drop-down list:
status (default). A status document is returned showing thesuccess of the queuing operation.
input. The input document that originally came into the emit serviceis returned.
response. The response from the execution through the internalchannel is returned. When response is set, the emitter waits for theresponse from the internal channel, making this a synchronous call.
Avoid Preemitter Determines whether any preemitter should be avoided. Select one ofthe following options from the drop-down list:
true (default)
false
RespectTransactionality
Determines whether this emitter should post messages regardless ofthe commit or rollback state of the transaction. For example, you maynot want to respect transactionality when passing messages thatreflect the progress of an application or errors within the application. Bydefault, this parameter is set to true.
Call at EOS? In a streaming environment, EOS (End of Stream) is the short messagethat is sent after the last document, which signifies the EOS. Thisparameter determines whether this service should be called for theEOS message. By default, this parameter is set to false.
Timeout Determines how many seconds to wait for a synchronous response. Setto 0 or leave blank to wait indefinitely.
Edges:
The edges returned are listed in the following table.
1. iWay Services
iWay Service Manager Component Reference Guide 253
Edge Description
success The message was enqueued for execution by the listener and channelthat is servicing the destination queue.
fail_parse The iFL used to configure this service contained an error.
fail_notfound The queue was not available.
timeout The message could not be placed onto the destination queue in the timeperiod specified in the Put Timeout parameter. This signifies that thequeue was inhibited and could not receive messages.
cancelled A cancel order was received while the service was in operation.
fail_operation The message could not be marshaled or could not be enqueued for someother reason.
notfound The queue was not available. In some applications this may not beconsidered an error, so this edge is provided along with the fail_notfoundedge.
Available Services
254 Information Builders
Example:
In a sample use case, an Internal Emit service is used to forward incoming documents to aninternal queue. The architecture for this use case consists of two channels. The first channelfeeds incoming documents to the internal queue and the second channel is used to processthe internal queue. The first channel also contains a route that is associated with a processflow where an Internal Emit service is used. For example:
1. iWay Services
iWay Service Manager Component Reference Guide 255
Every time an incoming document is processed by the first channel, the document is added tothe internal queue, for example, queue1. The second channel contains an inlet that isassociated with an Internal listener to access queue1. For example:
The second channel also contains a Move route, which routes the documents that reside onqueue1 to the appropriate outlet. This outlet can consist of a File or Email Emitter. Forexample:
Available Services
256 Information Builders
As documents are picked up by the first channel, they are processed by the first channel andthen by the second channel. When the processing is finished, the documents will appear at thefinal location, which is specified by the second channel's emitter. For example:
Is Reachable Service (com.ibi.agents.XDIsReachable)
Syntax:
com.ibi.agents.XDIsReachable
iIT Service Object:
operations: Is Reachable
http: Is Reachable
Description:
This service is used to test whether a specific IP target is reachable. If the target can bereached, the service returns success. This service is useful for supporting alternate routes,such that a message can be directed to a primary or a backup host.
Parameters:
Parameter Description
Host * Host to be checked for reachability.
Timeout * A timeout period to attempt to reach the host. The default value is 3seconds.
Edges:
The edges returned are listed in the following table.
1. iWay Services
iWay Service Manager Component Reference Guide 257
Edge Description
OnSuccess The host is reachable.
fail_unreachable The host is not reachable.
fail_partner The host is not known. For example, the host is notidentifiable in the DNS.
iWay Adapter (com.ibi.agents.XDAdapterAgent)
Syntax:
com.ibi.agents.XDAdapterAgent
iIT Service Object:
defined by adapter
Description:
This service is used to call a preconfigured iWay adapter.
Note: This service should be used as adapters are defined. To use this service, an adaptermust first be configured using iWay Explorer.
Parameters:
Available Services
258 Information Builders
Parameter Description
iBSP URL * Select an available iBSP URL from the drop-down list or type aURL using the following format:
http://host:port
where:
host
Is the name of the machine where iWay Service Manager isinstalled.
port
Is the port on which iBSP listens for SOAP requests. Thedefault port is 9000.
The iBSP URL allows you to access targets defined in the iBSPrepository.
Adapter * The name of the configured adapter you are working with, forexample, RDBMS.
Target * The name of the user-defined target that is associated with theconfigured adapter, for example, Oracle11.
Class The name of the Java class that implements the adapterassociated with the service. This field is populated by iWayService Manager when you create the Adapter service and shouldnot be modified.
Descriptor Key used by iWay Service Manager to locate the adapter targetparameters to associate with the service. This field is populatedby iWay Service Manager when you create the Adapter service andshould not be modified.
Keys Key used by iWay Service Manager to locate the adapterpersistence keys associated with the service. This field ispopulated by iWay Service Manager when you create the Adapterservice and should not be modified.
1. iWay Services
iWay Service Manager Component Reference Guide 259
Parameter Description
Persist Connection If enabled, the adapter connection is reused between executionattempts. Select one of the following options from the drop-downlist:
none (false). Each invocation of this service will create a newinstance of the adapter. Thus, for simple processing, oneinstance of the adapter is used for each requested operation.When streaming, one adapter instance will be reused for allmessages in the stream. In a transaction, each createdadapter instance receives the commit or rollback.
persist (true). This refers to persistence at the process flowinstance level. When an instance of the adapter is firstencountered for a target, the service creates a new instance ofthe adapter that is specific to that target.
This adapter instance is reused by subsequent invocations ofthe service, within an iterator loop and across invocations ofthe worker, including use within a streaming preparsersituation.
At the end of the process flow, the adapter instance is nolonger available.
pool. An adapter with a specific set of parameters and aspecific target will be cached at the worker (sub-channel) level.This means that multiple services within a process flow willshare an adapter and that multiple invocations of the processflow or a different process flow requiring the same adapter ortarget will reuse that adapter. If you have a threading count ofn, then there will be n instances of the cached adapter.
Note: The term target refers to an evaluated target in whichany iFL has been replaced with the value of that iFL. Forexample, a target with a port in a special register will betreated as the port value after the register value is obtained.
Promote OnFailure If set to false, failure edges, such as fail_connect, are promotedto OnError. This is used for upward compatibility purposes.
Available Services
260 Information Builders
Parameter Description
Emit OnFailure If the Promote OnFailure parameter is set to false, this parameterdetermines the type of document to emit on failures. Select oneof the following options from the drop-down list:
status. A status document will become the output document.This option is selected by default.
input. The input document will become the output document.
Edges:
The edges returned are listed in the following table.
Edge Description
success Successful operation of the adapter.
fail_operation The adapter failed and did not report the direct cause.
fail_security The adapter has returned a security violation.
fail_partner The adapter reports that it cannot reach the needed external system orthat system has returned an error.
cancelled The operation has been cancelled due to a timeout or other cause.
Example:
It is recommended to use an iWay Adapter as a Service object for connection with adaptersrather than this service. For more information, see the Configuring the Adapter in iWay Designerchapter in the iWay adapter documentation that corresponds to the specific adapter you aretrying to add or define (for example, iWay XML Adapter for RDBMS User's Guide).
1. iWay Services
iWay Service Manager Component Reference Guide 261
Using iWay Functional Language With Adapters
A frequent requirement is to use iFL to adjust the target of an adapter, for example, to changethe URL of a server to be reached. The example in this section discusses that issue.
Assume two MS SQL Server databases, smd1 and smd2, each of which contains a tablenamed testtable. The two tables have the same structure, but contain different data. Theapplication designer wants to create a flow using the RDBMS adapter that executes the SQLstatement, select * from testable, against either the table in smd1 or the one in smd2,depending on the input document.
Available Services
262 Information Builders
1. iWay Services
iWay Service Manager Component Reference Guide 263
Using Application Explorer, create an RDBMS adapter target pointing at either of the twodatabases, as shown in the following image.
Available Services
264 Information Builders
In the target, create the statement, which can be named stmt1.
Now, add the adapter to the iSM registry.
1. iWay Services
iWay Service Manager Component Reference Guide 265
Edit the parameter values imported from the target to use iFL expressions.
Note that the expression combines the _property and _sreg functions. Since there are severalconnection parameters that are required to be set dynamically for each destination, you canstore the values you need in a properties file using property names that follow a namingconvention. Thus, if you can set the dest special register, then you can use the value of thisregister to get the values that are required to make a connection. For this example, theproperties file has the following structure:
smd1.host=localhostsmd1.port=1433smd1.dbname=smd1smd1.id=sasmd1.password=harrisonsmd1.url=jdbc:sqlserver://localhost:1433;databaseName=smd1smd2.host=sdewitt4smd2.port=1433smd2.dbname=smd2smd2.id=sasmd2.password=harrisonsmd2.url=jdbc:sqlserver://localhost:1433;databaseName=smd2
Available Services
266 Information Builders
Save the adapter in the registry as DynamicRDBMS.
Other ways to store specific information includes the iWay Trading Profile Manager or anothertable reachable using the _jdbc() function call.
Now you need to create a flow that uses the DynamicRDBMS adapter. Since the adapter isdefined in the registry, you must work in a registry based project. To keep things simple, theflow will contain two components. The XDSREGAgent service will set the dest special registerto either smd1 or smd2, depending on the value of an attribute in the input document. To keepthings simple, you will just add this attribute to the standard RDBMS adapter input message,so the value of dest can be:
_xpath(/AdapterParams/@dest)
The next step is to add the DynamicRDBMS adapter.
Now, you can test the flow using the following input:
<AdapterParams location="RDBMS/Statements/stmt1" dest="smd2"/>
1. iWay Services
iWay Service Manager Component Reference Guide 267
Since the dest attribute is set to smd2, you should use the correct properties to connect tothe smd2 database.
Finally, you can retest the flow using the following input:
<AdapterParams location="RDBMS/Statements/stmt1" dest="smd1"/>
Available Services
268 Information Builders
Now, the dest attribute is smd1, which means the adapter should connect to the smd1database and retrieve different data.
Notice that all the bar values from the first result have changed to foo.
JDBC Service (com.ibi.agents.XDJdbcAgent)
Syntax:
com.ibi.agents.XDJdbcAgent
iIT Service Object:
misc: JDBC via driver
Description:
This service uses industry-standard JDBC to generate the standard <eda> <response> result.Because JDBC standards limit the available database operations that can be performed, thisservice is correspondingly limited. For example, this service cannot process the <focus> tag ofthe input document. However, this service can avail itself of any configured JDBC driver. Thisincludes the iWay SAP, IMS, and transaction server drivers as well as drivers from third-partyproviders.
Note: This service is deprecated. As an alternative it is recommended to use the SQL service.
1. iWay Services
iWay Service Manager Component Reference Guide 269
Parameters:
Parameter Description
Output Format * The format of the result.
Transaction Isolation Level Transaction isolation level to be set if possible.
User ID The user ID if it is not specified in the document.
Password The password if it is not specified in the document.
JNDI name * JNDI name for the requested data source.
Edges:
The following table lists the available line edges for the JDBC Service(com.ibi.agents.XDJdbcAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
Available Services
270 Information Builders
The JDBC Data Server properties must be configured before you can use the JDBC service. Ifyou already configured a server, for example, localDB, you can run this service using thefollowing input document:
<eda> <request> <connection> <dsn>local_DB</dsn> <user>iway</user> <password>iway</password> <sql> <query>select * from BALLS</query> </sql> </connection> </request></eda>
If your connection parameters are valid and the JDBC driver is configured, you will receive aresponse document from your local database in the following format (for the row output type):
<?xml version="1.0" encoding="UTF-8" ?><eda><response> <timestamp>2009-04-29T22:53:44Z</timestamp> <cncresult> <result format="std"> <resultset><colinfo> <col type="1" length="100" offset="0" nullable="1">name</col> <col type="1" length="10" offset="100" nullable="1">color</col> <col type="4" length="11" offset="110" nullable="1">amt</col> <col type="3" length="20" scale="0" offset="121" nullable="1">diameter</col> <col type="1" length="10" offset="141" nullable="1">type</col></colinfo><row>Old tennis ball grey 5 3 tennis</row><row>New swim ball blue 2 5 pool</row><row>Swift golf ball white 10 1 golf</row><row>Leather soccer ball checkered 1 20 soccer</row> </resultset> </result> </cncresult><execstatus>0</execstatus></response></eda>
JDBC via iWay JNDI Datasource Service (com.ibi.agents.XDJdbcDSAgent)
Syntax:
com.ibi.agents.XDJdbcDSAgent
iIT Service Object:
1. iWay Services
iWay Service Manager Component Reference Guide 271
format: JDBC via iWay JNDI Datasource
Description: Uses an iWay request to drive a named JDBC data source adapter.
Parameters:
Parameter Description
Output Format * The format of the result.
Transaction IsolationLevel
The transaction isolation level to be set, if possible.
User ID The user id, if not in document.
Password the default password, if not in document.
Use iWay JNDI * Set to true if using the iWay server as the JNDI server.Otherwise set to false.
JNDI name * The JNDI name for the requested data source. If using theiWay JNDI (provider), the name takes the form 'jndi/'
Edges:
The following table lists the available Line Edges for the JDBC via iWay JNDI DatasourceService (com.ibi.agents.XDJdbcDSAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
JMSQ Browse Service (com.ibi.agents.XDJMSBrowse)
Syntax:
com.ibi.agents.XDJMSBrowse
Available Services
272 Information Builders
Description:
This service browses a JMS (Java Messaging Server) queue. It returns the message read fromthe queue but does not delete the messages on the queue. For more information on JMS, seethe Queuing Adapters chapter in the iWay Service Manager Protocol Guide.
Parameters
Parameter Description
Use local JNDI If set, use local context, else remote JNDI.Select one of the following values from thedropdown list:
true
false
JNDI URL URL needed to reach the JNDI provider.
JNDI Factory Object name in the JNDI (example:jndi.openjms.InitialContextFactory).
Connection Factory JMS Queue connection factory
User ID User ID to log onto queue manager.
Password Password to log onto queue manager.
Queue Name Name of the queue to browse.
Filter Selection filter.
Namespace prefix Message properties are prefixed with this inspecial registers (separated by a period (.) ).
Output format How the output is provided. Select one ofthe following values from the drop-down list:
Status
Xml
Asread
1. iWay Services
iWay Service Manager Component Reference Guide 273
Edges:
The following table lists the available line edges for the JMSQ Browse Service(com.ibi.agents.XDJMSBrowse).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_nomessage
fail_connect
fail_partner
fail_parse
JMSQ Emit Service (com.ibi.agents.XDJMSQEmitAgent)
Syntax:
com.ibi.agents.XDJMSQEmitAgent
iIT Service Object:
emit: JMSQ Emit Agent
jms: JMSQ Emit Agent
queue: JMSQ Emit Agent
Description:
This service emits an input document to a JMS (Java Messaging Server) queue. It returns astatus document or the original input document as the output document. For more informationon JMS queue, see the Queuing Adapters chapter in the iWay Service Manager Protocol Guide.
Available Services
274 Information Builders
Parameters:
Parameter Description
Connection factory * The object store name.
Receiver queue * The name of the receiver queue.
Messaging type The message type.
JNDI URL * The JNDI URL.
JNDI factory * The JNDI factory class name.
Correlation ID The correlation ID.
Correlation ID tag The correlation ID tag.
User ID A valid user ID for challenges.
Password A valid password for challenges.
Acknowledgement Acknowledgement mode, or transactional.
Preemitter Should any preemitter be avoided?
Return document Select one of the following options from the drop-down list:
status. Status document will be the output document.
input. Input document will become the output document.
Output message type Select an output message type.
JMS Reply-to Queue or Topic (used for JNDI lookup).
Edges:
The following table lists the available line edges for the JMSQ Emit Service(com.ibi.agents.XDJMSQEmitAgent).
Line Edge Description
OnError Error
1. iWay Services
iWay Service Manager Component Reference Guide 275
Line Edge Description
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_connect
fail_parse
JMS Read Agent (com.ibi.agents.XDJMSReadAgent)
Syntax:
com.ibi.agents.XDJMSReadAgent
Description:
This service reads a message from a JMS (Java Messaging Server) queue or topic. For moreinformation on JMS, see the Queuing Adapters chapter in the iWay Service Manager ProtocolGuide.
Parameters:
Parameter Description
Name The name of the queue or topic to be read.
JMS Message Model Type of JMS Message Model to use. Selectone of the following values from the drop-down list:
queue
topic
Available Services
276 Information Builders
Parameter Description
Durable Subscriber A durable subscriber is a virtual messageconsumer for the specified topic, identifiedby the unique combination of a clientidentifier and subscriber name. When amessage arrives for the topic and nomessage consumer is currently active for it,the message will be retained for laterdelivery.
Message Type The type of JMS Message the system is toexpect. Select one of the following valuesfrom the dropdown list:
text
bytes
map
dynamic
Timeout The timeout period in seconds.
Tag Name of the XML tag to wrap the data readin. Required if data is flat.
Embed Whether to embed the data from the readoperation into the input document. Selectone of the following values from thedropdown list:
true
false
Parent Tag Where in the input document should theinput data be embedded,
1. iWay Services
iWay Service Manager Component Reference Guide 277
Parameter Description
Base64 Encode Base64 encode the read in document whenembedding. Select one of the followingvalues from the drop-down list:
true
false
Parse to XML Should the agent attempt to parse the inputinto XML:
true
false
Out Document Select one of the following values from thedrop-down list:
status. A status document will becomethe output document.
input. Input document will become theoutput document.
result. Message read will become theout document.
Action on Failure Whether input document or statusdocument returned on failure. Select one ofthe following values from the drop-down list:
input
status
Connection Factory The object store name.
Available Services
278 Information Builders
Parameter Description
Local Context True if connecting to an internal jndi store.Select one of the following values from thedrop-down list:
true
false
JNDI Factory Factory class name.
JNDI URL The JNDI URL.
User ID User ID for challenges.
Password Password for challenges.
Acknowledgement Acknowledgement or transactional. Selectone of the following values from the drop-down list:
Auto Acknowledge
Client Acknowledge
Dups OK Acknowledge
Edges:
The following table lists the available line edges for the JMS Read Agent(com.ibi.agents.XDJMSReadAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 279
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_connect
fail_partner
fail_parse
fail_operation
noMessage
unknownMessageType
JSON Conversion Service (com.ibi.agents.XDJSONAgent)
Syntax:
com.ibi.agents.XDJSONAgent
Description:
The JSON Conversion Service converts JSON to XML and vice-versa. This service offers achoice of two separate transformations that work in either of the following directions:
iWay transformation
Standard transformation
The iWay transformation is unusual because it does not have a preferred direction. It can takean arbitrary JSON object and convert it to XML, but it can also take an arbitrary XML documentand convert it to JSON. A round-trip will often produce the same input, but this is notguaranteed. JSON field names are reused as XML element names. This makes XPathexpressions look natural when they are evaluated against the resulting XML document.
The Standard transformation is described in section 22 of the XSLT3 specification. Thisalgorithm is simple because it is designed to express JSON objects in a specialized XML formthat conforms to a specific XML schema. This supports a perfect round trip of JSON objects toXML and back. XPath expressions to query the XML form is slightly more verbose becausepredicates are needed to match field names stored in attribute values.
Available Services
280 Information Builders
Parameters:
Parameter Description
Conversion Chooses the conversion from JSON to XML, or XML to JSON usingthe Standard transformation described in the XSLT3specification, or the iWay transformation.
Outer Tag When converting from JSON to XML using the iWaytransformation, the Outer Tag is the name of the root elementwrapper in XML. When absent, only JSON objects with a singlefield can be converted to XML, with the field name promoted tothe root element name. When converting from XML to JSON usingthe iWay transformation, this instructs to skip the root element ifthe name matches, thereby reversing the effect of the Outer Tag.This is ignored when using the Standard transformations.
JSON Literal Type When converting from XML to JSON using the iWaytransformation, this determines the data type of literal values inJSON. Dynamic will parse the XML text to discover the JSON type.This makes it convenient to use the values in JSON, but itassumes that everything that looks like a number is indeed anumber. String will always quote the literal value. This alwayspreserves the value without modification, but Boolean or numericvalues may have to be converted explicitly in JSON expressions.This is ignored when using the Standard transformation.
Encoding When converting from XML to JSON using the iWaytransformation, this is the encoding used to convert the JSONstring to bytes before storing in the document. This is ignoredwhen using the Standard transformation.
Edges:
The following table lists and describes the edges that are returned by the JSON ConversionService.
Line Edge Description
success The document was successfully converted.
1. iWay Services
iWay Service Manager Component Reference Guide 281
Line Edge Description
fail_parse An iFL expression could not be evaluated or a JSON document couldnot be parsed.
fail_format The format of the message was invalid for the operation requested.
fail_operation The operation could not be completed successfully.
iWay JSON to XML Transformation
The iWay transformation uses the JSON field names as XML element names and vice-versa.
The input of the JSON to XML iWay transformation can be a parsed JSON document or a flatdocument. A flat document will be parsed to a JSON value before being transformed. An XMLinput document is invalid and causes a fail_format error.
The output is a parsed XML document.
In JSON, a top level object is anonymous. The Outer Tag parameter (when specified) is thename generated for the corresponding top level Element in XML. It is always recommended todefine an Outer Tag but it is possible to leave the Outer Tag empty for backwards compatibility.In that case, the service assumes the top level JSON object has a single field and promotesthat field to top level. Without an Outer Tag, trying to convert a JSON object with zero or morethan one fields causes an error.
An array is represented in XML with multiple consecutive elements of the same name. Thisrequires an empty or singleton array be marked with the following attribute to indicate the arraytype for the round-trip:
json:force-array="true"
An array within an array is also anonymous and will be converted to a containing elementcalled array to preserve the array structure.
The namespace prefix json stands for the http://json.org/ namespace. The prefix isautomatically declared.
Available Services
282 Information Builders
JSON accepts more valid characters than XML. The iWay transformation handles this byreplacing an invalid character with the escape character underscore followed by a 4-digithexadecimal string. The underscore was chosen because it is a valid start character in XMLelement names. When a field name must be escaped, it is marked with the following XMLattribute:
json:escaped-key="true"
Similarly, when a string value must be escaped, it is marked with the following XML attribute:
json:escaped="true"
It is possible for an element to have both attributes. When absent, the default value of theseattributes is false. The underscore character is not escaped, unless another character must beescaped within the same string.
iWay XML to JSON Transformation
The input of the XML to JSON iWay transformation must be a parsed XML document. A JSONdocument or a flat document is invalid and causes a fail_format error. The input can be anyarbitrary XML document, but some conventions must be followed to produce desired JSONforms.
The output is a bytes document containing the serialized JSON object. The encoding used toconvert the characters to bytes is given by the Encoding parameter.
The root element is skipped if the Outer Tag is defined and it matches the root element name.That reverses the effect of the Outer Tag.
A sub-element that appears once within its parent and is not marked with json:force-array="true" becomes a JSON field with a JSON object, number or Boolean value.
Conversely, a sub-element that appears more than once or is marked with json:force-array="true" becomes a JSON field with an array value. The sub-elements are gathered byname, they do not have to be consecutive.
Multiple text-nodes within a mixed-content parent Element are converted to a JSON field calledcontent with an array value. This mapping is not reversible when going back to XML.
1. iWay Services
iWay Service Manager Component Reference Guide 283
The JSON Literal Type parameter determines the data type of literal values in the JSON output.Setting the parameter to Dynamic will parse the XML text to discover the JSON type. Stringliterals will be double-quoted whereas numbers and Booleans will not. This makes itconvenient to use the values in JSON but it assumes that everything that looks like a numberis indeed a number. Setting the parameter to String will always quote the literal value. Thisalways preserves the value without modification, but boolean or numeric values may have tobe converted explicitly in JSON expressions.
An element with the following attribute will have its name unescaped to produce the JSON fieldname:
json:escaped-key="true"
An element with the following attribute will have its value unescaped to produce the JSONstring value.
json:escaped="true"
iWay Transformation Examples
The following table shows the correspondence between JSON and XML. The Outer Tag isassumed to be JSON, and the JSON Literal Type is set to Dynamic.
Concept JSON XML
Non-object 1 <json>1</json>
Empty Object 0 <json/>
Null {"null1": null} <json><null1>null</null1></json>
Number {"num1": 1} <json><num1>1</num1></json>
String {"str1":"abc"} <json><str1>abc</str1></json>
Boolean {"bool1":true} <json><bool1>true</bool1></json>
Multiple Fields {"key1": "val1", "key2":"val2"}
<json><key1>val1</key1><key2>val2</key2></json>
Subobject {"obj1":{"sub1":1}} <json><obj1><sub1>1</sub1></obj1></json>
Available Services
284 Information Builders
Concept JSON XML
Empty Array {"array0":[]} <json xmlns:json="http://json.org/"><array0 json:force-array="true"/></json>
Singleton Array {"array1":[1]} <json xmlns:json="http://json.org/"><array1 json:force-array="true">1</array1></json>
Array {"array3":[1,2,3]} <json><array3>1</array3><array3>2</array3><array3>3</array3></json>
Subarray {"array2d":[[11,12],[21,22]]} <json><array2d><array>11</array><array>12</array></array2d><array2d><array>21</array><array>22</array></array2d></json>
RegularUnderscore
{"a_b":1} <json><a_b>1</a_b></json>
Escaped Key {"a:b":1} <json xmlns:json="http://json.org/"><a_003ab json:escaped-key="true">1</a_003ab></json>
EscapedUnderscore
{"a_\u0003":1} <json xmlns:json="http://json.org/"><a_005f_0003 json:escaped-key="true">1</a_005f_0003></json>
RegularUnderscore
{"a":"a_b"} <json><a>a_b</a></json>
Escaped Value {"a":"a_\u0003"} <json xmlns:json="http://json.org/"><a json:escaped="true">a_005f_0003</a></json>
Both Attributes {"a:b":"a_\u0003"} {"a:b":"a_\u0003"} <json xmlns:json="http://json.org/"><a_003ab json:escaped-key="true" json:escaped="true">a_005f_0003</a_003ab></json>
1. iWay Services
iWay Service Manager Component Reference Guide 285
The following table shows how JSON is transformed to XML when the Outer Tag is absent. Theconversion succeeds only when the input JSON object has a single field. To avoid this error, itis recommended to always define an Outer Tag.
Concept JSON XML
Non-Object 1 Error document with fail_operation
Empty Object {} Error document with fail_operation
Single Field {"key1": "val1"} <key1>val1</key1>
Multiple Fields {"key1": "val1","key2": "val2"}
Error document with fail_operation
The following table shows how XML is transformed to JSON when the JSON Literal Type is setto String. The Outer Tag is assumed to be JSON. All primitive literals become quoted strings.
Concept XML JSON
Null <json><null1>null</null1></json> {"null1":"null"}
Number <json><num1>1</num1></json> {"num1":"1"}
String <json><str1>abc</str1></json> {"str1":"abc"}
Boolean <json><bool1>true</bool1></json> {"bool1":"true"}
The following table shows some notable cases when XML is transformed to JSON. The OuterTag is assumed to be JSON.
Concept XML JSON
Simple Type <json><obj>abc</obj></json> {"obj":"abc"}
Mixed Content <json><obj>abc<sub>xyz</sub>def</obj></json>
{"obj":{"content":["abc","def"],"sub":"xyz"}}
Available Services
286 Information Builders
Concept XML JSON
Not Consecutive <json><a>a1</a><b>b1</b><a>a2</a></obj></json>
{"a":["a1","a2"],"b":"b1"}
iWay Transformation XPath Example
The iWay transformation produces XML documents that are intuitive to query with XPath. Forexample, the following JSON object:
{"obj":{"list":[11,22,33]}}
is transformed into:
<json><obj><list>11</list><list>22</list><list>33</list></obj></json>.
The XPath expression to extract the value 33 can be written as follows:
/json/obj/list[3]
Standard JSON to XML Transformation
The Standard transformation is described in section 22 of the XSLT3 specification. It supportsperfect round-trips from JSON to XML and back.
The input must be a parsed JSON document. An XML or a flat input document is invalid andcauses a fail_format error. The output is a parsed XML document.
JSON values are mapped to XML elements in the http://www.w3.org/2005/xpath-functionsnamespace based on the JSON data type, as defined in the following table.
JSON Type XML Element Name
Object map
Array array
String string
Number number
Boolean boolean
1. iWay Services
iWay Service Manager Component Reference Guide 287
A JSON object is mapped to an element called map as indicated in this table. Each field ismapped to an XML subelement named according to this table. The field name is stored in thekey attribute of the subelement.
An array item is mapped to an element called array. Each array item is mapped to an XMLsubelement named according to this table.
A string, number, or Boolean is converted to an element with a text node.
JSON accepts more valid characters than XML. The Standard transformation handles this byreplacing an invalid character with the escape character backslash followed by a 4-digithexadecimal string. When a field name must be escaped, it is marked with the following XMLattribute:
escaped-key="true"
Similarly, when a string value must be escaped, it is marked with the following XML attribute:
escaped="true"
These attributes are not within a namespace. It is possible for an element to have bothattributes. When absent, the default value of these attributes is false. The backslash characteris not escaped, unless another character must be escaped within the same string.
Standard XML to JSON Transformation
The input of the Standard XML to JSON transformation must be a parsed XML document in aspecific form, which means it must satisfy the expected XML schema. A parsed JSON or a flatinput document is invalid and generates a fail_format error.
The output is a parsed JSON document.
A JSON value is created based on the XML element name according to the table above. Formore information, see Standard JSON to XML Transformation on page 287.
Each sub-element of a map element corresponds to a field. The name of the field is given bythe key attribute. If the attribute escaped-key="true" is present, then the value of the keyattribute is unescaped first to produce the field name. It is an error if the key attribute ismissing.
Each sub-element of an array element corresponds to an item in the array.
An element with the following attribute, will have its name unescaped to produce the JSONfield name.
escaped-key="true"
Available Services
288 Information Builders
An element with the following attribute, will have its value unescaped to produce the JSONstring value:
escaped="true"
Standard Transformation Examples
The following table shows the correspondence between JSON and XML and back. Theexamples are perfectly symmetric.
Concept JSON XML
Non-Object 1 <number xmlns="http://www.w3.org/2005/xpath-functions">4</number>
Empty Object {} <map xmlns="http://www.w3.org/2005/xpath-functions"/>
Null {"null1": null} <map xmlns="http://www.w3.org/2005/xpath-functions"><null key="null1"/></map>
Number {"num1": 1} <map xmlns="http://www.w3.org/2005/xpath-functions"><number key="num1">1</number></map>
String {"str1":"abc"} <map xmlns="http://www.w3.org/2005/xpath-functions"><string key="str1">abc</string></map>
Boolean {"bool1":true} <map xmlns="http://www.w3.org/2005/xpath-functions"><boolean key="bool1">true</boolean></map>
Multiple Fields {"key1": "val1", "key2":"val2"}
<map xmlns="http://www.w3.org/2005/xpath-functions"><string key="key1">val1</string><string key="key2">val2</string></map>
Subobject {"obj1":{"sub1":1}} <map xmlns="http://www.w3.org/2005/xpath-functions"><map key="obj1"><number key="sub1">1</number></map></map>
1. iWay Services
iWay Service Manager Component Reference Guide 289
Concept JSON XML
Empty Array {"array0":[]} <map xmlns="http://www.w3.org/2005/xpath-functions"><array key="array0"/></map>
Singleton Array {"array1":[1]} <map xmlns="http://www.w3.org/2005/xpath-functions"><array key="array1"><number>1</number></array></map>
Array {"array3":[1,2,3]} <map xmlns="http://www.w3.org/2005/xpath-functions"><array key="array3"><number>1</number><number>2</number><number>3</number></array></map>
Subarray {"array2d":[[11,12],[21,22]]} <map xmlns="http://www.w3.org/2005/xpath-functions"><array key="array2d"><array><number>11</number><number>12</number></array><array><number>21</number><number>22</number></array></array></map>
Regular Backslash {"a\\b":1} <map xmlns="http://www.w3.org/2005/xpath-functions"><number key="a\b">1</number></map>
Escaped Key {"a\u0003":1} <map xmlns="http://www.w3.org/2005/xpath-functions"><number key="a\u0003" escaped-key="true">1</number></map>
Escaped Backslash {"a\\\u0003":1} <map xmlns="http://www.w3.org/2005/xpath-functions"><number key="a\\\u0003" escaped-key="true">1</number></map>
Regular Backslash {"a":"a\\b"} <map xmlns="http://www.w3.org/2005/xpath-functions"><string key="a">a\b</string></map>
Available Services
290 Information Builders
Concept JSON XML
Escaped Value {"a":"a_\u0004"} <map xmlns="http://www.w3.org/2005/xpath-functions"><string key="a" escaped="true">a_\u0004</string></map>
Both Attributes {"a\u0003":"a\u0004"} <map xmlns="http://www.w3.org/2005/xpath-functions"><string key="a\u0003" escaped-key="true" escaped="true">a\u0004</string></map>
Standard Transformation XPath Example
The Standard transformation produces XML documents that require slightly verboseexpressions to query with XPath. For example, the following JSON object:
{"str1":"abc","list":[11,22,33]}}
is transformed into:
<map xmlns="http://www.w3.org/2005/xpath-functions"><string key="str1">abc</string><array key="list"><number>11</number><number>22</number><number>33</number></array></map>
A fully developed XPath expression to extract the value 33 can be written as follows:
/json:map/json:array[@key="list"]/json:number[3]
Notice how a predicate is needed to test the key attribute against the desired field name.
This expression assumes the json prefix is declared in an XML Namespace provider with thefollowing value:
http://www.w3.org/2005/xpath functions
JSON Insertion Service (com.ibi.agents.XDJsonInsertAgent)
Syntax:
com.ibi.agents.XDJsonInsertAgent
Description:
The JSON Insertion Service inserts a value in a JSON document. The service requires a JSONinput document, since any other type of document will return a fail_operation edge.
1. iWay Services
iWay Service Manager Component Reference Guide 291
The data source can be left unparsed to be inserted as a string, or it can be parsed as a JSONliteral allowing the insertion of typed values (for example, a JSON object, JSON array, a quotedstring, a number, a Boolean, or null).
The value is inserted in one or more parents selected by a JsonPath expression. Selecting noparents causes the fail_notfound edge to be returned. Selecting more than one parent causesthe value to be duplicated. A parent can be a JSON object or an array.
The key determines where the value is inserted within the parent. If the parent is an object,then the key is the name of the field. If the field already exists, then the value replaces the oldvalue. Otherwise, a new field is created. If the parent is an array, then the key is the indexwithin the array and the value replaces the old value at that index. If the index is larger thanthe array length, then the array is first extended with null values. If the key is left blank, thenthe value is appended after the last element.
Parameters:
Parameter Description
Data Source The string or JSON data to insert in the document.
Data Format Determines how the Data Source is interpreted. The String formattreats the Data Source as character data. The JSON format parsesthe Data Source as a JSON value.
Parent Path A JsonPath expression returning one or more parents where toassign the JSON value. A parent can be a JSON object or a JSONarray.
Key Determines where to store the value in the parent. For a JSON objectparent, this is the key in the map. For a JSON array parent, this isthe index in the array, where an empty string means append to theend, which causes the array to grow by 1.
Edges:
The following table lists and describes the edges that are returned by the JSON InsertionService.
Edge Description
success The value was successfully inserted.
Available Services
292 Information Builders
Edge Description
fail_parse An iFL, JSON, or a JsonPath expression could not be evaluated.
fail_notfound No parents were selected.
fail_operation The operation could not be completed successfully.
Examples:
Inserting the unparsed string str with parent $.obj and key k in the JSON document{"obj":{"k1":1}} produces {"obj":{"k":"str","k1":1}}.
Inserting the parsed JSON value {"a":1} with parent $.arr and empty key in the JSONdocument {"arr":[1,2,3]} produces {"arr":[1,2,3,{"a":1}]}.
Inserting the parsed JSON value 5 with multiple parents $.arr[*] and key k5 in the JSONdocument {"arr":[{"k1":1},{"k2":2}]} produces {"arr":[{"k1":1,"k5":5},{"k2":2,"k5":5}]}.
LDAP Reader Service (com.ibi.agents.LDAPReader)
Syntax:
com.ibi.agents.LDAPReader
iIT Service Object:
LDAP: LDAP Reader
read: LDAP Reader
Description:
This service reads LDAP context that is based on a request document. For more information onconfiguring LDAP components using iWay Service Manager, see the iWay Service ManagerUser's Guide.
Parameters:
Parameter Description
Provider A URL to identify the LDAP service and the optional rootcontext.
1. iWay Services
iWay Service Manager Component Reference Guide 293
Parameter Description
User A valid user name for the LDAP connection.
Password A valid password that is associated with the user name for theLDAP connection.
Doc Can Carry Access * If set to true, then the request document is permitted to carryaccess information, which overrides the credentials that areset for the configuration of this service. By default, thisparameter is set to false.
Context The initial context from the URL point.
Filter A search filter that can be specified to limit the scope.
Edges:
The following table lists the available line edges for the LDAP Reader Service(com.ibi.agents.LDAPReader).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_connect
Legacy Record to XML Converter Service (com.ibi.agents.XDLegacyRecordToXMLAgent)
Syntax:
com.ibi.agents.XDLegacyRecordToXMLAgent
Available Services
294 Information Builders
iIT Service Object:
operations: Legacy Record to XML Converter
Description:
This service converts flattened bytes described by a copybook to an XML node.
Parameters:
Parameter Description
Copybook Location The full path to the COBOL copybook that describes the inputrecord.
Copybook Option FileLocation
Full path to the Copybook option file. This file specifies specialfiled handling rules. For more information, see Using theCopybook Option File on page 297.
Full FD? Set this parameter to true if COBOL group field headings arerequired to appear in the output XML. By default, false isselected.
Multiple Records? If set to true, then multiple CommArea records are produced ifthe input byte array is larger than the copybook size. Bydefault, false is selected.
Input
Source of Legacy Record The COBOL copybook formatted source. If no value isspecified, then the flattened input document is used.Otherwise, use iWay Functional Language (iFL) to specify thesource.
Base 64 Encoded Input Determines if the source input data is encoded using Base64.
Input Encoding The Internet Assigned Numbers Authority (IANA) character setfor the legacy record. You can select a value from the drop-down list or type the name of a code page directly in the field.By default, the leave option is selected, which uses the defaultencoding of the listener.
Output
1. iWay Services
iWay Service Manager Component Reference Guide 295
Parameter Description
Output Node An XPath expression to specify the node in the input documentto which the converted legacy record will be added as a child.XPath must point to an existing node, since new nodes are notcreated. If no value is specified, then the converted record isused as the output document. If the input document is in non-XML format, then the converted record is always returned asthe output document.
Edges:
The following table lists the available line edges for the Legacy Record to XML ConverterService (com.ibi.agents.XDLegacyRecordToXMLAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
Available Services
296 Information Builders
Using the Copybook Option File
The copybook option file is an XML document that allows the following data handling options tobe set:
1. Error handling options for packed (COMP-3), zoned, alphanumeric, and binary fields in bytesto XML conversion.
Special Character Handling. High values (X'FFFFFFFF'), low values (X'00000000'),blanks (X'40404040'), ampersands (X'50505050'), and number or pound signs(X'7b7b7b7b') may represent expected input in a customer application. These valuesmay be handled by a custom rule rather than be parsed (and possibly throw an error)according to the type of the field.
Invalid Data Handling. Data that is Invalid, but does not match the special characterhandling types indicated above, may also be handled by a rule. This can return anarbitrary string as the contents of the field, optionally reporting the raw error bytes as anattribute. Finally, it may be specified that invalid data should throw exceptions.
2. Leading zeros option for packed and zoned fields.
The Copybook option file is identified by the Copybook Option File Location parameter duringthe service configuration (com.ibi.agents.XDLegacyRecordToXMLAgent).
The format of the copybook option file is an XML file.
Alternatively, the service checks for the presence of a file with the full path of the copybookand if the _option suffix is appended. This copybook option file is then used. For example, ifthe copybook is c:\copybook.cbl, then c:\copybook.cbl_option would be its associatedcopybook option file.
The following is an example of a copybook option file.
1. iWay Services
iWay Service Manager Component Reference Guide 297
<?xml version=1.0" ?><Options> <FieldRules> <FieldRule> <GroupName>ExtremValueTEST</GroupName> <FieldName>Account</FieldName> <FieldType>COMP-3</FieldType> <Actions> <AcceptAs onValue="HIGHVALUE">1000<?acceptAs> <AcceptAs onValue="LOWVALUE"/> <AcceptAs onValue="INVALID" reportRawData="YES"> </Actions> </FieldRule> <!-- A general rule. If no "GroupName" and "FieldName", the rule applies to all the fields of the filed type specified. --> <FieldRule> <!-- required --> <FieldType>COMP-3</FieldType> <Actions> <AcceptAs onValue="LOWVALUE"/> <AcceptAs onValue="BLANK"></AcceptAs> <AcceptAs onValue="AMPERSAND"></AcceptAs> <AcceptAs onValue="POUND"></AcceptAs> <ThrowException onValue="INVALID"></ThrowException> </Actions> </FieldRule> </FieldRules></Options>
The root element is <Options>. You can define multiple <FieldRule> elements under the<FieldRules> parent element. The combination of these three elements, <GroupName>,<FieldName>, and <FieldType>, define the specific level of a rule. If a rule does not specify<GroupName> and <FieldName>, then it applies to all the fields of a particular field type.Currently the supported types are COMP-3, Zoned (PIC 9), Alpha (PIC X), and binary (PIC 9COMP). The <FieldType> element is required.
In the above sample copybook option file, the first <FieldRule> element is more specific thanthe second <FieldRule> element, because it only applies to one specific COMP-3 field withname Account under the ExtremValueTEST group. The second <FieldRule> element applies toall the COMP-3 fields in a COBOL record.
A <FieldRule> can have one <Actions> element, which can have multiple elements of thefollowing types:
<AcceptAs onValue="PATTERN" reportRawData="YES">nn</AcceptAs>
Available Services
298 Information Builders
Requires the onValue attribute. If the value of a field matches "PATTERN", substitute thevalue with nn. If nn is not provided, default to an empty XML element. The attribute,reportRawData, is optional. If this attribute is set to "YES" and a field value matches the"PATTERN", the raw hex data of the value will be reported as an attribute, rawData, to thefield in the XML output document. For example:
<Account rawData="0x10E000"></Account>
This provides a mechanism for an application to inspect invalid input and handle itprogrammatically. If this attribute is omitted, the raw data value of a field will not bereported in the XML document.
<ThrowException onValue="PATTERN"></ThrowException>
Requires the onValue attribute. If the value of a field matches "PATTERN", then anexception is generated.
<AcceptAs> and <ThrowException> should not both be specified for the same pattern for thesame field.
The predefined "PATTERN" strings for the onValue attribute include:
HIGHVALUE. All bytes are 0xFF.
LOWVALUE. All bytes are 0x00.
BLANK. All bytes are 0x40.
AMPERSAND. All bytes are 0x50.
POUND. All bytes are 0x7b.
INVALID. Not a valid data according to the field type.
In the above copybook option file example, if the Account field has a value with all 0xFF bytes,then the value of the field is set to 1000. If the field has a value with all 0x00 bytes, then thefield is set to empty. If the field has a blank value, then the field is set to empty. The blankrule is defined in the second <FieldRule> element.
If an options file has multiple actions that are applicable to a field, then the actions that aredefined in the most specific field rule applies. If the Account field has all 0xFF bytes, then thevalue of the field is set to 1000. This is because the first <FieldRule> element is more specificthan the second <FieldRule> element.
1. iWay Services
iWay Service Manager Component Reference Guide 299
If two applicable actions are defined at the same level in terms of field rule specificity, thenthe action that appears first in the options file will be applied. Once exception to this is theINVALID pattern. The INVALID pattern will be checked after the other patterns even if it appearsbefore the other patterns.
If there is no options file or no rules are defined for a field, then an exception is generated ifthe field value is not valid data.
<PreserveLeadingZeros> only applies to COMP-3 and Zoned fields. This action type specifieswhether the leading zeros in a number should be retained for the length of the field type. Thedefault behavior is to truncate any leading zeros. If you want to keep leading zeros to all theCOMP-3 and Zoned fields, then add the following <FieldRule> elements to an options file:
<FieldRule> <FieldType>COMP-3</FieldType> <Actions> <PreserveLeadingZeros>YES</PreserveLeadingZeros> </Actions></FieldRule>
<FieldRule> <FieldType>Zoned</FieldType> <Actions> <PreserveLeadingZeros>Y</PreserveLeadingZeros> </Actions></FieldRule>
If a copybook option file does not have <PreserveLeadingZeros> defined or if the value of<PreserveLeadingZeros> is not YES or Y, then the leading zeros of COMP-3 and Zoned fieldsare not preserved.
If only specific fields should preserver leading zeros, more specific <FieldRule> elements arerequired. To make a <FieldRule> element more specific, you need to specify <GroupName>and/or <FieldName>.
For example, if you want all of the Zoned fields to have leading zeros except one field balance,you must create the rules shown in the following example:
Available Services
300 Information Builders
<?xml version=1.0" ?><Options> <FieldRules> <FieldRule> <GroupdName>BankAccount</GroupName> <FieldName>balance</FieldName> <FieldType>Zoned</FieldType> <Actions> <PreserveLeadingZeros>NO</PreserveLeadingZeros> </Actions> </FieldRule>
<!-- more general rule --> <FieldRule> <FieldType>Zoned</FieldType> <Actions> <PreserveLeadingZeros>Y</PreserveLeadingZeros> </Actions> </FieldRule> </FieldRules></Options>
The more specific rule for the balance field will take precedence over the general rule.Therefore, the leading zeros of this field are not preserved.
Additional Usage Examples for the Copybook Option File
Example #1
The following copybook option file can be used to set a general policy of treating high values,low values, blanks as empty, and generate an exception for other format errors.
<?xml version="1.0" ?><Options> <FieldRules> <FieldRule> <FieldType>COMP-3</FieldType> <Actions> <AcceptAs onValue="LOWVALUE"/> <AcceptAs onValue="HIGHVALUE"></AcceptAs> <AcceptAs onValue="BLANK"</AcceptAs> </Actions> </FieldRule> </FieldRules></Options>
Example #2
The PACKED02 field is known to sometimes contain blanks, which should be interpreted as 0(zero). Sometimes, special non-packed escape data must be handled upstream by theapplication. In this scenario, the following copybook option file can be used.
1. iWay Services
iWay Service Manager Component Reference Guide 301
<?xml version="1.0" ?><Options> <FieldRules> <FieldRule> <FieldName>PACKED02</FieldName> <FieldType>COMP-3</FieldType> <Actions> <AcceptAs onValue="BLANK">0</AcceptAs> <AcceptAs reportRawData="YES" onValue="INVALID"></AcceptAs> </Actions> </FieldRule> </FieldRules></Options>
Local Master Service (com.ibi.agents.LocalMasterAgent)
Syntax:
com.ibi.agents.LocalMasterAgent
iIT Service Object:
Description:
Passes the document to a separate, named workflow and awaits the result. This serviceaccepts the name of a configured LOCAL protocol which can be configured in any mannerdesired. The routes are pooled for efficiency. Unlike using an internal emitter to route adocument to the internal protocol, this call is synchronous. Any errors reported by the namedworkflow are reflected in the calling flow, and any timeout configured for the flow includes timein the called flow. LocalMasterAgent differs from simply calling an external process flow in thenormal manner in that a complete workflow is available including preparsers, reviewers, and soon. It is strongly recommended that this agent not be used unless no other means areavailable to accomplish the application purposes.
Parameters:
Parameter Description
Name Name of the defined local master (channel) to be called.
Call at EOS? In a streaming environment, EOS (End of Stream) is the short messagethat is sent after the last document, which signifies the EOS. Thisparameter determines whether this service should be called for the EOSmessage. The default value is false.
Available Services
302 Information Builders
Edges:
The following table lists the available line edges for the Local Master Service(com.ibi.agents.LocalMasterAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
Mail Attach Service (com.ibi.agents.XDMailAttachAgent)
Syntax:
com.ibi.agents.XDMailAttachAgent
iIT Service Object:
misc: Mail Attach Agent
Description:
This service is used to process an email attachment.
Parameters:
Parameter Description
Attachment Tag * Tag used to identify an attachment (attachment is the default).
1. iWay Services
iWay Service Manager Component Reference Guide 303
Parameter Description
Encode If set to true, everything is base64 encoded. If false, only non-txt isencoded.
Target Target of attachments.
Output Directory The target output directory.
Output File Name The output file name, which can contain an asterisk character (*) andis expanded to a timestamp, if an empty attachment name is used.
Note: If you want to preserve the original name of the attachment, donot specify a value for this parameter.
Delete Mail Object If no other component needs the mail object, it should be deleted.
Edges:
The following table lists the available line edges for the Mail Attach Service(com.ibi.agents.XDMailAttachAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
Available Services
304 Information Builders
Example:
In a sample scenario, a channel can be configured that uses an Email listener as an inlet, anda Mail Attach service as a route. The Mail Attach service processes the attachment from theincoming email and places the resulting document within the attachment tag. The following isan example of configuration settings for a Mail Attach service object in iIT Designer:
When an email containing simple HTML <Test><hello>hi</hello></Test> with an attachmentfile (test.xml) is sent to the address specified for the email listener, the channel runs and theMail Attach service processes the email producing the following output document:
<?xml version="1.0" encoding="ISO-8859-1" ?><Test><hello>hi</hello><attachment mime="text/xml" file="c:\out\mailattch2009-05-13T20_05_57.986Z" name="test.xml"/></Test>
Notice that the attachment element was added to the original email, along with the location ofthe emitted attachment file, which you can locate as specified.
Mark Attach Service (com.ibi.agents.XDMarkAttachAgent)
Syntax:
com.ibi.agents.XDMarkAttachAgent
iIT Service Object:
misc: Mark Attach Agent
1. iWay Services
iWay Service Manager Component Reference Guide 305
Description:
This service makes the body of a document into an attachment.
Parameters:
Parameter Description
Attachment Name Name for this attachment, usually the file name.
Attachment Type Mime type; if omitted one is generated based on the data format.
Body Result * Determines how to handle the body of the document.
Edges:
The following table lists the available line edges for the Mark Attach Service(com.ibi.agents.XDMarkAttachAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_attach
Marshall Service (com.ibi.agents.XDMarshallAgent)
Syntax:
com.ibi.agents.XDMarshallAgent
iIT Service Object:
exit preemit: Marshall Agent
Available Services
306 Information Builders
misc: Marshall Agent
Description:
This service collects and serializes the content of a current document and its channel contextas a single message. The marshaled message can then be sent to another listener, where itwill automatically be unmarshaled to reconstruct the original channel.
For example, you can marshal a message and then use an MQ or File emit service to send themessage to another listener on that protocol. The next listener picks up the message, and theprocessing of the message resumes. The second channel can exist on another configuration oreven another host.
Sending a marshaled message insures that the continuation of execution is on the sametransaction ID (TID) as that of the originating channel.
You must not use this service when sending messages through server facilities that aremanaged internally. These include the internal emit service, the internal emitter, the RVIgateway relay facilities, and messages to be placed on pending queues. These servicesautomatically marshal their own messages, and marshaling a marshaled message wouldcreate an unpredictable error.
Note: This service is packaged with the iwgateway.jar extension.
Parameters:
Parameter Description
Compress Message During marshaling, the message body will be compressed.Compression works best with messages restricted to asmall set of octets (such as an XML message), but workspoorly when the message consists of randomly distributedoctets, such as a binary message.
Marshall User SpecialRegisters
Determines if marshaling should include the user-levelspecial registers. By default, DOC and HDR registers areincluded in the marshaled message, along with somespecific registers needed for Business Activity Monitor(BAM) and transaction tracking.
1. iWay Services
iWay Service Manager Component Reference Guide 307
Parameter Description
Namespace If a namespace is specified, only special registers in thedesignated namespace are included in the marshaledmessage, along with the specific registers needed for BAMand tracking. This can be helpful when preparing multiplemarshals for different targets, each of which needsdifferent header registers. Other services are available tomanipulate special register namespaces as required.
Use Encryption Determines if marshaled messages should be encrypted. Asecure AES cipher is used, and must be deciphered by thereceiver (using the Unmarshal service). Automaticunmarshaling cannot be performed on an encryptedmessage.
AES Key A cipher key shared between the marshal and unmarshalservices. Usually, this is specified as a special register orfrom a properties file.
The edges that are returned by this service are listed in the following table:
Edge Description
success The message has been marshaled and is ready for sending.
fail_operation The message could not be compressed, encrypted, ormarshaled.
For more information, see Unmarshall Service (com.ibi.agents.XDUnmarshallAgent) on page494.
MLLP Emit Service (com.ibi.agents.XDMLLPEmitAgent)
Syntax:
com.ibi.agents.XDMLLPEmitAgent
Available Services
308 Information Builders
Description:
This service emits a message using the Minimal Lower Layer Protocol (MLLP). This protocolallows you to wrap an HL7 message with a header and footer to ensure you know where amessage starts, where a message stops, and where the next message starts.
Parameters:
Parameter Description
Host * The machine name or IP address of the MLLP destination.
Port * The designated TCP/IP port that is being used to receiveMLLP messages.
Secure Connection Select true from the drop-down list if you want use a secureconnection through Secure Sockets Layer (SSL). By default,this parameter is set to false.
SSL Context Provider If configured, specify the name of an available iWay SecurityProvider for SSL Context. If the Secure Connectionparameter is set to true and the SSL Context Provider fieldis blank, then the default provider will be used.
Set TCP No Delay If set to true, then Nagle's Algorithm on the client socketwill be disabled. This will result in faster line turnaround atthe expense of an increased number of packets. By default,this parameter is set to false.
Socket Timeout The timeout value in seconds. When a non-zero timeoutvalue is specified, a read() function call on the socket willblock for only the amount of time specified (in seconds). Ifthe timeout expires, a java.net.SocketTimeoutException isgenerated. The default timeout is dependent on theoperating system being used.
Persistence If set to true, then iWay Service Manager (iSM) is instructedto maintain the connection.
Persistence Timeout value inMinutes
The maximum length of time (in minutes) that a connectioncan persist with no activity. If this parameter value is zero(0) or left blank, then the default is set to 60 minutes.
1. iWay Services
iWay Service Manager Component Reference Guide 309
Parameter Description
Retry Count The number of times to try to send the message after aninitial failure is encountered. By default, this parameter isset to 0.
Retry Pause The amount of time (in milliseconds) to wait between retryattempts. By default, this parameter is set to 1000.
Start Block Character The encoding of the Start of Block character in decimal,octal, or hexadecimal format. The default is 0x0B.
End Block Character The encoding of the End of Block character in decimal,octal, or hexadecimal format. The default is 0x1C.
Maximum Message Size The maximum size of a message that can be sent orreceived through this emitter. If this parameter value is zero(0) or left blank, then the default is set to 256KB.
Output Document Determines whether the output document is a responsedocument, status document, or the original input document.By default, this parameter is set to response.
Move Service (com.ibi.agents.XDMoveAgent)
Syntax:
com.ibi.agents.XDMoveAgent
iIT Service Object:
control: Move Agent transfers input to output
Description:
This service moves the input to the output without duplicating the information. This is thefastest means of copying from input to output.
In a use case scenario, the Move service can be used as a route in a channel. This channelmay need to parse an EDI document with a preparser or emit the document to a messagequeue.
Available Services
310 Information Builders
Edges:
The following table lists the available line edges for the Move Service(com.ibi.agents.XDMoveAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
cancelled
MQ Emit Service (com.ibi.agents.XDMQEmitAgent)
Syntax:
com.ibi.agents.XDMQEmitAgent
iIT Service Object:
misc: MQ Emit Agent
Description:
This service emits an input document to a Message Queuing (MQ) queue. It returns a statusdocument or the original input document as the output document. For more information on MQ,see the Queuing Adapters chapter in the iWay Service Manager Protocol Guide.
Parameters:
Parameter Description
correlid The correlation ID.
1. iWay Services
iWay Service Manager Component Reference Guide 311
Parameter Description
queuemanager The queue manager name.
queuename The queue name.
The message ID appears in the <name> element of the <emitstatus> result.
Edges:
The following table lists the available line edges for the MQ Emit Service(com.ibi.agents.XDMQEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_connect
fail_security
MQ JMS Emit Agent Service (com.ibi.agents.XDMQJMSEmitAgent)
Syntax:
com.ibi.agents.XDMQJMSEmitAgent
iIT Service Object:
format: MQ JMS Emit Agent
Description: Emits an input document to IBM MQ using the JMS API.
Available Services
312 Information Builders
Parameters:
Parameter Description
Receiver Name * The name of the queue or topic to be read.
Queue Manager The Websphere MQ queue manager name.
Host The host name or IP address. It is only needed for an MQclient connection.
Port The port number. It is only needed for an MQ clientconnection.
Channel The server connection channel name. It is only needed for anMQ client connection.
SSL CipherSpec The MQ CipherSpec determines that SSL is to be used. This isconfigured for the channel by the IBM Websphere MQAdministrator. SSL can be used only in client mode.
SSL Context Provider The iWay Security Provider for SSL Context. If the SSL ContextProvider is left blank, the SSL truststore and keystore comefrom global system properties which can easily lead toconflicts.
User The user logon id at broker.
Password The user's password at the broker machine.
Messaging Style Select queue for point-to-point or topic for publish-and-subscribe.
Output Message Type The class of message sent. Dynamic will selectBytesMessage, TextMessage or MapMessage depending onthe document contents.
JMSCorrelationID The value of the JMSCorrelationID header field.
Message Priority The outgoing message priority. Value must be between 0 and9, with 9 being the most expedited. If omitted, it uses theincoming priority.
1. iWay Services
iWay Service Manager Component Reference Guide 313
Parameter Description
JMSReplyTo The value of the JMSReplyTo header field.
JMSType The value of the JMSType header field.
Request HeaderNamespace
The special register namespace from which protocol headersfor the outbound request will be taken.
Acknowledgement Makes the JMS Session transactional or else specifies howreceived messages are acknowledged.
Delivery Mode Non-Persistent mode has low overhead but may losemessages. Persistent mode takes extra care to ensure themessage is not lost in transit, but makes no absoluteguarantee.
Time to Live The message's lifetime (in milliseconds). The default will liveforever
Delivery Delay The minimum length of time in milliseconds that must elapseafter a message is sent before the JMS provider may deliverthe message to a consumer. JMS 2 only.
Preemitter Determines if any preemitter be avoided.
Return Document Determines whether the output document will be a statusdocument or the input document.
Edges:
The following table lists the available Line Edges for the MQ JMS Emit Agent Service(com.ibi.agents.XDMQJMSEmitAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
Available Services
314 Information Builders
Line Edge Description
OnFailConnection Could not connect to the extenal system.
MQ Read Service (com.ibi.agents.XDMQReadAgent)
Syntax:
com.ibi.agents.XDMQReadAgent
iIT Service Object:
Description:
This agent reads one message on an MQ queue. Optionally the message can be selectedbased on a correlation ID.
If the message read appears to be XML the agent will attempt to parse it. Otherwise it will beadded as a flat document.
Parameters:
Parameter Description
Manager Name of the queue manager.
Queue Name Name of the queue to read.
Correlation ID If present, a message of this correlation ID will be read.
Host MQ Host if using MQ Client.
Port MQ Port if using MQ Client.
Channel MQ Server Channel if using MQ Client.
Timeout Timeout in seconds.
Browse If true, this is a browse operation. If false, this is a destructiveread.
1. iWay Services
iWay Service Manager Component Reference Guide 315
Return Description
success Read was successful.
fail_connect Could not connect to the queue.
fail_parse Could not convert message to XML.
fail_operation Could not read the message.
fail_timeout The read timed out.
Edges:
The following table lists the available line edges for the MQ Read Service(com.ibi.agents.XDMQReadAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_connect
fail_parse
fail_operation
fail_timeout
MQTT Emit Agent Service (com.ibi.agents.XDMqttEmitAgent)
Syntax:
com.ibi.agents.XDMqttEmitAgent
Available Services
316 Information Builders
iIT Service Object:
format: MQTT Emit Agent
Description: Publish a message to an MQTT server.
Parameters:
Parameter Description
MQTT Client Provider * The name of the MQTT Client Provider.
Time to Wait The time to wait in milliseconds for the action to complete. 0means the action will not timeout.
Topic Name The topic where the message will be delivered.
Quality of Service The quality of service when delivering this message.
Retain Message Determines whether the message should be retained by theserver as the last message published on the topic.
Return Document Determines whether the output document will be a statusdocument or the input document.
Edges:
The following table lists the available Line Edges for the MQTT Emit Agent Service(com.ibi.agents.XDMqttEmitAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailParse Could not parse a document.
OnFailOperation Could not perform the operation requested.
OnFailTimeOut The operation times out.
1. iWay Services
iWay Service Manager Component Reference Guide 317
MSMQ Emit Service (com.ibi.agents.XDMSMQEmitAgent)
Syntax:
com.ibi.agents.XDMSMQEmitAgent
iIT Service Object:
Description:
This service emits an input document to a Microsoft Message Queuing (MSMQ) queue. Itreturns a status document or the original input document as the output document. For moreinformation on MSMQ, see the Queuing Adapters chapter in the iWay Service Manager ProtocolGuide.
Parameters:
Parameter Description
Queue (required) The name of the output queue.
Correlation ID The Correlation ID that should be used.
Priority The outgoing message priority, which can also be specified asXPATH(). The value must be between 0 and 9, with 9 indicatingmost expedited.
Transactional If set to true, then the queue will be treated as Transactional.
The default value is false.
Delivery Method Specifies the delivery method that should be used. Selectingexpress does not guarantee arrival, but is processed faster.
The default value is recoverable.
Message Label The message label is equivalent to an email subject or JMS topic.
Preemitter Determines whether any preemitter be avoided.
The default value is true.
Available Services
318 Information Builders
Parameter Description
Return Select one of the following values from the drop-down list:
status {status}. The status document will become the outputdocument.
original {input}. The original input document will become theoutput document
The default value is status.
Edges:
The following table lists the available line edges for the MSMQ Emit Service(com.ibi.agents.XDMSMQEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
MTOM Service (com.ibi.agents.XDMTOMAgent)
Syntax:
com.ibi.agents.XDMTOMAgent
iIT Service Object:
attachments: MTOM Agent
1. iWay Services
iWay Service Manager Component Reference Guide 319
http: MTOM Agent
MTOM: MTOM Agent
Description:
The Message Transmission Optimization Mechanism (MTOM) service can be used to format adocument for MTOM transmission or to reconstruct a document received in MTOM format.Reconstruction converts the received MTOM message into a message format that can behandled by the attachment capabilities of the server.
Parameters:
Parameter Description
Operation Select one of the following specific operations to perform fromthe drop-down list:
Reconstruct the original message {reconstruct}
Reconstructs the original XML message document byreplacing the MTOM references with the actual binarycontent found in the attachments.
Create an MTOM package {create}
Creates an MTOM message by replacing the contents ofsome binary elements with references to body parts in anew multipart attachment.
Add an Include {include}
Assumes the document is already an MTOM message andreplaces one more binary element with a reference to anew body part.
Delete Attachments If the Reconstruct the original message option is selected forthe Operation parameter, the Delete Attachments parameterspecifies whether to delete the attachments that havereplaced xop:Include elements.
Available Services
320 Information Builders
Parameter Description
Element Path If the Create an MTOM package option is selected for theOperation parameter, you must specify an XPath expressionfor the Element Path parameter that returns the set ofbase64binary nodes to extract.
If the Add an Include option is selected for the Operationparameter, you must specify an XPath expression that returnsthe element where the xop:Include element will be added.
XML Namespace Provider A provider for the mapping between XML namespace prefixand namespace URI in the Element Path.
XPath Syntax Determines the syntax level of XPath that should be used. Thedefault option selects the syntax level as set in the GeneralSettings section of the iSM console. Select one of thefollowing syntax levels from the drop-down list:
Default {default}
iWay abbreviated syntax {iway}
XPath 1.0 full syntax {xpath1}
Attachment Content-Type If the Create an MTOM package option is selected for theOperation parameter, this is the Content-Type set on a newattachment when the xmlmime:contentType attribute isabsent on the extracted element.
Attachment Content-ID If the Add an Include option is selected for the Operationparameter, this value is the Content-ID of the existingattachment being referred to.
If the Create an MTOM package option is selected for theOperation parameter, the Content-ID of the new attachmentswill be the prefix specified here followed by a numeric suffix.
The edges returned are listed in the following table:
1. iWay Services
iWay Service Manager Component Reference Guide 321
Edge Description
success The operation completed successfully.
fail_parse Parameters to the service were invalid.
fail_operation The MTOM operation cannot be completed. This can be caused byattempting to reconstruct a non-MTOM message.
Node Set Extract Service (com.ibi.agents.XDNodeSetExtractAgent)
Syntax:
com.ibi.agents.XDNodeSetExtractAgent
iIT Service Object:
misc: Node Set Extract Agent
Description:
This service creates a new document based on a node or set of nodes in the original inputdocument.
Parameters:
Parameter Description
XPATH Expression * The XPath expression which represents the node set.
Root name Optional root for multiple children.
Edges:
The following table lists the available line edges for the Node Set Extract Service(com.ibi.agents.XDNodeSetExtractAgent).
Line Edge Description
OnError Error
OnSuccess Success
Available Services
322 Information Builders
Line Edge Description
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
The best application of the Node Set Extract service would be to extract the sub-part of anincoming XML document. If you provide the XPath location for the node where the extractionbegins, you will receive an output of the XML sub-tree from the original document with thespecified node as a root.
In the following example, the XPath expression is specified as Test/attachment/. The incomingdocument consists of the following:
<Test><hello>hi</hello><attachment><a>555</a></attachment></Test>
The Node Set Extract service will return a result of the edge as success, along with thefollowing output document:
<?xml version="1.0" encoding="UTF-8" ?><attachment> <a>555</a></attachment>
NTCP Emit AgentService (com.ibi.agents.XDNTCPEmitAgent)
Syntax:
com.ibi.agents.XDNTCPEmitAgent
iIT Service Object:
format: NTCP Emit Agent
Description: Emits over TCP using connections from the NTCP Connection Provider.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 323
Parameter Description
Host * The remote host to which TCP requests will be sent.
Port * The TCP port on the host to which TCP requests will be sent.
Cache Socket Locally * If true, cache the socket locally for reuse by other agents inthe same process flow. This option is not allowed with theMessage ends at EOS Message Protocol.
Return Document The type of output from this service. If response, the servicewill wait up to the Response Timeout for a response from theserver and will output this response as a bytes-type document.If status, the service will output a standard status documentimmediately after emitting to the server and will not attempt toretrieve any response.
Response Timeout The maximum time, in milliseconds, to block while waiting fora response from the server. 0 means no timeout. A negativevalue will use the system default.
TCP Connection Provider*
The name of the TCP Connection Provider to use for themessage emit.
Persist Connections? If true, use a connection from the TCP Connection Provider'spool and return the connection to the pool after emit. If false,a new connection will be created for this emit and closed afteremit is complete. Use of persistent connections is not allowedwith the Message ends at EOS Message Protocol.
Message Protocol * Choose one of the built-in options or use a custom handler.For the Message ends at EOS option, you must set PersistentConnections? to false and you must not use an SSLconnection. To use a custom handler, supply the fully qualifiedname of a class that implementscom.ibi.edaqm.IClientProtocolHelper and ensure that the classis on iSM's runtime classpath.
Maximum Incoming Size On receipt of an incoming message larger than the maximum,the message will be ignored and the connection is closed. 0means no maximum. Empty defaults to 256KB.
Available Services
324 Information Builders
Edges:
The following table lists the available Line Edges for the NTCP Emit Agent Service(com.ibi.agents.XDNTCPEmitAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailConnection Could not connect to the external system.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
NTCP Client Write Agent Service (com.ibi.agents.XDNTCPClientWriteAgent)
Syntax:
com.ibi.agents.XDNTCPClientWriteAgent
iIT Service Object:
format: NTCP Client Write Agent
Description: Writes data to a connection registered with an NTCPClient listener.
Parameters:
Parameter Description
Connection ID * The ID of a persistent connection to an NTCP Client listener,as stored in the ntcp_connectionid special register when theconnection is registered by the NTCP Client Register agent.
Return Document Type of output from this service. If input, the service willoutput its input document. If status, the service will output astandard status document after emitting to the specifiedconnection.
1. iWay Services
iWay Service Manager Component Reference Guide 325
Edges:
The following table lists the available Line Edges for the NTCP Client Write Agent Service(com.ibi.agents.XDNTCPClientWriteAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailConnection Could not connect to the external system.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
NTCP Emit Agent Service (com.ibi.agents.XDNTCPEmitAgent)
Syntax:
com.ibi.agents.XDNTCPEmitAgent
iIT Service Object:
format: NTCP Emit Agent
Description: Emits over TCP using connections from the NTCP Connection Provider.
Parameters:
Parameter Description
Host * The remote host to which TCP requests will be sent.
Port * The TCP port on Host to which TCP requests will be sent.
Cache Socket Locally * If true, cache the socket locally for reuse by other agents inthe same process flow. This option is not allowed with theMessage ends at EOS Message Protocol.
Available Services
326 Information Builders
Parameter Description
Return Document The type of output from this service. If response, the servicewill wait up to the Response Timeout for a response from theserver, and will output this response as a bytes-typedocument. If status, the service will output a standard statusdocument immediately after emitting to the server and will notattempt to retrieve any response.
Response Timeout The maximum time, in milliseconds, to block while waiting fora response from the server. 0 means no timeout. A negativevalue will use system default.
TCP Connection Provider*
The name of the TCP Connection Provider to use for messageemit.
Persist Connections? If true, use a connection from the TCP Connection Provider'spool and return the connection to the pool after emit. If false,a new connection will be created for this emit and closed afteremit is complete. Use of persistent connections is not allowedwith the Message ends at EOS Message Protocol.
Message Protocol * Choose one of the built-in options or use a custom handler.For the Message ends at EOS option, you must set PersistentConnections? to false and you must not use an SSLconnection. To use a custom handler, supply the fully qualifiedname of a class that implementscom.ibi.edaqm.IClientProtocolHelper and ensure that the classis on iSM's runtime classpath.
Maximum Incoming Size On receipt of an incoming message larger than the maximum,the message will be ignored and the connection is closed. 0means no maximum. Empty defaults to 256KB.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 327
The following table lists the available Line Edges for the NTCP Emit Agent Service(com.ibi.agents.XDNTCPEmitAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailConnection Could not connect to the external system.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
NTCP Read Agent Service (com.ibi.agents.XDNTCPReadAgent)
Syntax:
com.ibi.agents.XDNTCPReadAgent
iIT Service Object:
format: NTCP Read Agent
Description: Reads from a TCP connection until it receives a message or times out.
Parameters:
Parameter Description
Host * The remote host from which the service will attempt to read amessage.
Port * The TCP Port on Host from which the service will attempt toread a message.
Cache Socket Locally * If true, cache the socket locally for reuse by other agents inthe same process flow. This option is not allowed with theMessage ends at EOS Message Protocol.
Available Services
328 Information Builders
Parameter Description
Response Timeout The maximum time, in milliseconds, to block while waiting fora response from the server. 0 means no timeout. A negativevalue will use the system default.
TCP Connection Provider*
The name of the TCP Connection Provider to use for messageemit.
Persist Connections? If true, use a connection from the TCP Connection Provider'spool and return the connection to the pool after emit. If false,a new connection will be created for this emit and closed afteremit is complete. Use of persistent connections is not allowedwith the Message ends at EOS Message Protocol.
Message Protocol * Choose one of the built-in options or use a custom handler.For the Message ends at EOS option, you must set PersistentConnections? to false and you must not use an SSLconnection. To use a custom handler, supply the fully qualifiedname of a class that implementscom.ibi.edaqm.IClientProtocolHelper and ensure that the classis on iSM's runtime classpath.
Maximum Incoming Size On receipt of an incoming message larger than the maximum,the message will be ignored and the connection is closed. 0means no maximum. Empty defaults to 256KB.
Edges:
The following table lists the available Line Edges for the NTCP Read Agent Service(com.ibi.agents.XDNTCPReadAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailConnection Could not connect to the external system.
1. iWay Services
iWay Service Manager Component Reference Guide 329
Line Edge Description
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
NTCP Respond Agent Service (com.ibi.agents.XDNTCPRespondAgent)
Syntax:
com.ibi.agents.XDNTCPRespondAgent
iIT Service Object:
format: NTCP Respond Agent
Description: Sends input as a response back to a client of an NTCP listener.
Parameters:
Parameter Description
Connection ID The ID of a persistent connection to an NTCP listener, asstored in the ntcp_connectionid special register whenmessages are received by the NTCP channel. This value canbe passed to other channels as part of the message context,possibly as a correlation ID. If this service is running on anNTCP channel, leave blank to send a response to the clientwho originated the message being handled by the currentprocess flow. When used with other protocols, Connection IDis required.
Return Document Type of output from this service. If input, the service willoutput its input document. If status, the service will output astandard status document after emitting to the client.
Edges:
Available Services
330 Information Builders
The following table lists the available Line Edges for the NTCP Respond Agent Service(com.ibi.agents.XDNTCPRespondAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailConnection Could not connect to the external system.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
OAuth 1.0 Authentication Service (com.ibi.agents.XDOAuth1Agent)
Syntax:
com.ibi.agents.XDOAuth1Agent
iIT Service Object:
http: OAuth Authentication
security: OAuth Authentication
Description:
This service creates the HTTP Authorization header for OAuth 1.0a as specified in RFC5849.This RFC describes a 3-legged protocol where the user authorizes the client application toaccess a protected resource hosted by a service provider.
For more information on configuring and using the OAuth 1.0 Authentication Service(com.ibi.agents.XDOAuth1Agent), see the iWay Service Manager Security Guide.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 331
The following table lists the available line edges for the OAuth 1.0 Authentication Service(com.ibi.agents.XDOAuth1Agent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
OAuth 2.0 Authentication Service (com.ibi.agents.XDOAuth2Agent)
Syntax:
com.ibi.agents.XDOAuth2Agent
iIT Service Object:
http: OAuth 2.0 Authentication
security: OAuth 2.0 Authentication
Description:
This service emits an HTTPS request authenticated by OAuth 2.0 using the credentials of aGoogle service account. OAuth 2.0 is described in RFC6749 and RFC6750. It is anauthorization framework that enables an application to obtain access to an HTTP resource.
For more information on configuring and using the OAuth 2.0 Authentication Service(com.ibi.agents.XDOAuth2Agent), see the iWay Service Manager Security Guide.
Available Services
332 Information Builders
The following table lists the available line edges for the OAuth 2.0 Authentication Service(com.ibi.agents.XDOAuth2Agent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
OpenRules Decision Service (com.ibi.agents.XDOpenRulesDecisionAgent)
Syntax:
com.ibi.agents.XDOpenRulesDecisionAgent
Description:
This service executes the specified OpenRules decision using user-defined parameters asinput. Specify the parameters as:
<object>.<attribute>
Parameters:
Parameter Description
OpenRules File * The main .xls file that contains the decision to be executed.
Decision Name * The OpenRules decision to execute.
1. iWay Services
iWay Service Manager Component Reference Guide 333
Parameter Description
Decision ObjectsPackage *
The Java package where the decision classes reside.
Input Date Format The date format pattern to validate input date values. Use JavaSimpleDateFormat syntax or leave blank for the locale defaultpattern.
Parallel Execution: Counted iteration Service (com.ibi.agents.XDParallelCountAgent)
Syntax:
com.ibi.agents.XDParallelCountAgent
iIT Service Object:
format: Parallel Execution: Counted iteration
Description: Executes a sub-flow in parallel for each item returned by the embeddedXDIterCount iterator.
Parameters:
Parameter Description
Name of the PFLOW * The PFLOW to run.
Maximum Parallel Tasks*
The maximum number of tasks processed simultaneously. Ifan additional task must be performed, it will wait for aprevious task to complete. 0 means unbounded.
Timeout * The maximum time to wait for all tasks to complete, inseconds. 0 means unbounded.
Accumulation Version * Determins which version of accumulation is desired. Simpleuses less memory, but handles only a single result from thesubflow.
Iterations * The number of times to repeat the loop.
Edges:
Available Services
334 Information Builders
The following table lists the available Line Edges for the Parallel Execution: Counted iterationService (com.ibi.agents.XDParallelCountAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
cancel The service has responded to a cancellationrequest.
OnParseError Could not parse a document.
OnNotFound The resource was not found and this isconsidered an error.
OnTimeOut The operation timed out.
OnFailedOperation Could not perform the operation requested.
failed_incomplete An operation failed before all the taskscould be completed.
Parallel Execution: JSON iteration Service (com.ibi.agents.XDParallelJsonSplitAgent)
Syntax:
com.ibi.agents.XDParallelJsonSplitAgent
iIT Service Object:
format: Parallel Execution: JSON iteration
Description: Executes a sub-flow in parallel for each item returned by the embeddedXDIterJsonSplit iterator.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 335
Parameter Description
Name of the PFLOW * The PFLOW to run.
Maximum Parallel Tasks*
The maximum number of tasks processed simultaneously. Ifan additional task must be performed, it will wait for aprevious task to complete. 0 means unbounded.
Timeout * The maximum time to wait for all tasks to complete, inseconds. 0 means unbounded.
Accumulation Version * Determins which version of accumulation is desired. Simpleuses less memory, but handles only a single result from thesubflow.
Path Expression * The JsonPath expression that selects the items to iterate.
Edges:
The following table lists the available Line Edges for the Parallel Execution: JSON iterationService (com.ibi.agents.XDParallelJsonSplitAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
cancel The service has responded to a cancellationrequest.
fail_parse Could not parse a document.
fail_notfound The resource was not found and this isconsidered an error.
fail_timeout The operation timed out.
fail_operation Could not perform the operation requested.
Available Services
336 Information Builders
Line Edge Description
failed_incomplete An operation failed before all the taskscould be completed.
Parallel Execution: XML iteration Service (com.ibi.agents.XDParallelXMLSplitAgent)
Syntax:
com.ibi.agents.XDParallelXMLSplitAgent
iIT Service Object:
format: Parallel Execution: XML iteration
Description: Executes a sub-flow in parallel for each item returned by the embeddedXDIterXMLSplit iterator.
Parameters:
Parameter Description
Name of the PFLOW * The PFLOW to run.
Maximum Parallel Tasks*
The maximum number of tasks processed simultaneously. Ifan additional task must be performed, it will wait for aprevious task to complete. 0 means unbounded.
Timeout * The maximum time to wait for all tasks to complete, inseconds. 0 means unbounded.
Accumulation Version * Determins which version of accumulation is desired. Simpleuses less memory, but handles only a single result from thesubflow.
Snip levels * The number of top-down levels to be snipped from generateddocuments.
Expression * Describes the XPath location of the element on which to split.When Evaluate Expression is not set, enter an XPathexpression directly. When Evaluate Expression is set, enter anexpression that returns an XPath expression.
1. iWay Services
iWay Service Manager Component Reference Guide 337
Parameter Description
Evaluate Expression When not set, the Expression parameter contains an XPathexpression directly. When set, the Expression parameter isevaluated, and the returned value is the XPath expressionused for splitting.
XML Namespace MapProvider
If the XPath expression depends on namespaces, supply thename of an XML Namespace Map Provider that contains therequired namespace prefixes and URLs.
Cross Section * If set, the iterated portion is included with the remainder of thenon-iterated portion of the document. Otherwise only theparental path is included.
XPath Syntax Determines which syntax level of XPath should be used. Thedefault option selects the syntax level as set in the consoleglobal settings.
Edges:
The following table lists the available Line Edges for the Parallel Execution: XML iterationService (com.ibi.agents.XDParallelXMLSplitAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
cancel The service has responded to a cancellationrequest.
OnParseError Could not parse a document.
OnNotFound The resource was not found and this isconsidered an error.
OnTimeOut The operation timed out.
Available Services
338 Information Builders
Line Edge Description
OnFailedOperation Could not perform the operation requested.
failed_incomplete An operation failed before all the taskscould be completed.
Parse to XML Service (com.ibi.agents.XDToXML)
Syntax:
com.ibi.agents.XDToXML
iIT Service Object:
format: Parse to XML
operations: Parse to XML
Description:
This service parses a flat document into an XML document. If the input is already in XMLformat, this service performs no action. This service is useful if a flat (non-XML) inputdocument has been received and must be converted into XML format for additional processing.
Edges:
The following table lists the available line edges for the Parse to XML Service(com.ibi.agents.XDToXML).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 339
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse: the output will consist of theoriginal input document.
Example:
In a use case scenario, a response document is received from a web server using an HTTPemitter, which sends a request to the server. When the response is received from the webserver, it is unreadable by a File reader until it is converted to XML format. As a result, usingthe Parse to XML Service is required to convert the message, as shown in the following image.
On success, the output of this process flow is an XML message. If the response cannot beparsed as a valid XML file, an error is returned.
Available Services
340 Information Builders
PDF Form Field Reader Service (com.ibi.agents.XDPdfFormFieldReader)
Syntax:
com.ibi.agents.XDPdfFormFieldReader
iIT Service Object:
format: PDF Form Field Reader
Description: Extracts values from the fields of a PDF form, and returns an XML documentcontaining the form data.
Parameters:
Parameter Description
Original PDF Document Path to the original PDF document. If left blank, the PDFdocument is in the input document as an array of bytes.
Edges:
The following table lists the available Line Edges for the PDF Form Field Reader Service(com.ibi.agents.XDPdfFormFieldReader).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
PF File Operations Service (com.ibi.agents.XDPFFileOpsAgent)
Syntax:
com.ibi.agents.XDPFFileOpsAgent
iIT Service Object:
1. iWay Services
iWay Service Manager Component Reference Guide 341
misc: PF File Ops Agent
Description:
This service performs operations on the specified file(s) including copy, move, rename,prepend, append, delete, size, and exist.
Parameters:
Parameter Description
Operation * Command to execute when service goes active.
File (from) * Originating file to be operated on. Relative or absolute file paths aresupported explicitly or through a SREG or XPath expression evaluatedusing the incoming document.
File (to) Destination file to be operated on. Wild cards accepted. Requiredexcept for delete, size, exists.
Size Special register designated to hold size. Required for size.
Out Document * Document returned by operation (bad input defaults to result).
Action on Failure*
Determines whether input document or status document is returnedon failure.
Retry If non-zero, will retry the operation n times at one-second intervals.
Edges:
The following table lists the available line edges for the PF File Operations Service(com.ibi.agents.XDPFFileOpsAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
342 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_notfound
fail_operation
Example:
If running it using the move operation on a specified file, the result is:
<?xml version="1.0" encoding="UTF-8" ?><manager><status>OK</status><msg>Success</msg></manager>
PF File Read Service (com.ibi.agents.XDPFFileReadAgent)
Syntax:
com.ibi.agents.XDPFFileReadAgent
iIT Service Object:
misc: PF File Read Agent
Description:
This service embeds a specified binary, XML or text file in the input document.
Parameters:
Parameter Description
Name of File * File to be read. Relative or absolute file paths are supportedexplicitly or through a SREG or XPath expression evaluated using theincoming document.
1. iWay Services
iWay Service Manager Component Reference Guide 343
Parameter Description
Delete after read * Determines whether to delete the file read on a successful read.
Format * Format of the input data.
Tag Name of the XML tag to wrap the data read in. Required if data isflat.
Character SetEncoding
Character set encoding of the document to be read in. Defaultsystem encoding will be used if left blank.
Embed * Determines whether to embed the data from the read operation intothe input document.
Base64 Encode * Base64 encode the read in document when embedding.
Parent Tag Where in the input document the input data should be embedded.
Retry If non-zero, will retry the operation n times at one-second intervals.
Edges:
The following table lists the available line edges for the PF File Read Service(com.ibi.agents.XDPFFileReadAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Available Services
344 Information Builders
PGP Decryption and Verification Service (com.ibi.agents.PGPDecryptAgent)
Syntax:
com.ibi.agents.PGPDecryptAgent
iIT Service Object:
format: PGP Decryption and Verification
Description: Decrypts and verifies a PGP message.
Parameters:
Parameter Description
Decryption KeyPassphrase
A case sensitive passphrase to decrypt the session key. Thisis optional, it will be used when the session key has beenencrypted with a passphrase.
Secret Key Ring The location of the secret key ring containing the private keysto decrypt the session keys. This is optional, it will be usedwhen the session key has been encrypted with a public key.
Private Key Passphrase The case sensitive passphrase to unlock the DecryptionPrivate Key within the Secret Key Ring. This is optional, it willbe used when the session key has been encrypted with apublic key.
Signature Verification
Signature Required If set, incoming messages require a valid signature.
Public Key Ring The location of the public key ring containing the signaturepublic keys.
Acceptable HashAlgorithms
A space-separated list of hash names that can be used in PGPsignatures. Other hashes will cause a validation failure beforebeing evaluated. The intention is to forbid weak algorithmsdefined in the PGP specification. The default is SHA1 SHA224SHA256 SHA384 SHA512.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 345
The following table lists the available Line Edges for the PGP Decryption and VerificationService (com.ibi.agents.PGPDecryptAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailSecurity Could not operate due to a securityviolation.
fail_unsigned Signature not found.
PGP Encryption and Signature Service (com.ibi.agents.PGPEncrypt)
Syntax:
com.ibi.agents.PGPEncrypt
iIT Service Object:
format: PGP Encryption and Signature
Description: Encrypts and signs documents using PGP.
Parameters:
Parameter Description
Armor * Determines whether the binary message will be armored fortransfer in ASCII.
Literal Filename The filename to appear in the Literal Data Packet. Thereceiving program may use this name when storing the data todisk. The special value _CONSOLE means the data isunusually sensitive.
Signature
Available Services
346 Information Builders
Parameter Description
Sign Determines whether to sign the data in the PGP message.
Signature Hash Algorithm The algorithm to use for the signature digest.
Secret Key Ring The location of the secret key ring containing the signaturekey.
Signature Key User ID The User ID of the private key used for signing. The format canbe =name for the exact User ID, user@host to match only theemail address, or <user@host> optionally surrounded byignored comments to match only the value within anglebrackets against the email address. This property alsodetermines which User ID(s) will be listed in Signer's User IDsubpackets.
Signature Key ID The Key ID of the private key used for signing. The format canbe 8 hex digits for the short key ID, 16 hex digits for the longkey ID, or 40 hex digits for the fingerprint. Spaces are allowedand are not counted in the length. This property can be usedin place of or together with the Signature Key User ID to selecta more specific key.
Signature Key Passphrase The case-sensitive passphrase to unlock the Signature PrivateKey.
Signature Expiration The number of seconds after the signature creation time thatthe signature expires. The format is [xxh][xxm]xx[s]. If absentor has a value of zero, the signature never expires.
Compression
Compress Determines whether to compress the data in the PGPmessage.
Compression Algorithm The algorithm to use to compress the data in the PGPmessage.
Encryption
Encrypt Determines whether to encrypt the data in the PGP message.
1. iWay Services
iWay Service Manager Component Reference Guide 347
Parameter Description
Symmetric Algorithm A symmetric algorithm to be used for encryption.
Encryption Method Determines how the session key is encrypted, use Passphrasefor Password-Based Encryption (PBE), use Keypair to encryptwith a public key.
Encryption Passphrase The case-sensitive passphrase for when using the Passphraseencryption method. The passphrase will be used to generate akey encryption key to encrypt the session key.
Recipient 1
Public Key Ring 1 When using the Keypair encryption method, this is the locationof the public key ring containing the encryption public key forthe first recipient.
Encryption Key User ID 1 When using the Keypair encryption method, this is the User IDof the public key for the first recipient. The format can be=name for the exact User ID, user@host to match only theemail address, or <user@host> optionally surrounded byignored comments to match only the value within anglebrackets against the email address. For backwardscompatibility, this parameter defaults to the value of theEncryption Passphrase parameter.
Encryption Key ID 1 When using the Keypair encryption method, this is the Key IDof the public key for the first recipient. The format can be 8hex digits for the short key ID, 16 hex digits for the long keyID, or 40 hex digits for the fingerprint. Spaces are allowed andare not counted in the length. This property can be used inplace or together with the Encryption Key User ID 1 to select amore specific key.
Recipient 2
Public Key Ring 2 When using the Keypair encryption method with more than onerecipient, this is the Location of the public key ring containingthe encryption public key for the second recipient.
Available Services
348 Information Builders
Parameter Description
Encryption Key User ID 2 When using the Keypair encryption method with more than onerecipient, this is the User ID of the public key for the secondrecipient. The format can be =name for the exact User ID,user@host to match only the email address, or <user@host>optionally surrounded by ignored comments to match only thevalue within angle brackets against the email address.
Encryption Key ID 2 When using the Keypair encryption method with more than onerecipient, this is the Key ID of the public key for the secondrecipient. The format can be 8 hex digits for the short key ID,16 hex digits for the long key ID, or 40 hex digits for thefingerprint. Spaces are allowed and are not counted in thelength. This property can be used in place or together with theEncryption Key User ID 2 to select a more specific key.
Edges:
The following table lists the available Line Edges for the PGP Encryption and Signature Service(com.ibi.agents.PGPEncrypt).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailSecurity Could not operate due to a securityviolation.
PGP Sign OnlyService (com.ibi.agents.XDPGPSignAgent)
Syntax:
com.ibi.agents.XDPGPSignAgent
1. iWay Services
iWay Service Manager Component Reference Guide 349
iIT Service Object:
format: PGP Sign Only
Description: Signs a PGP message, this agent is deprecated in favor of PGPEncrypt.
Parameters:
Parameter Description
Armor * Determines whether the binary message will be armored fortransfer in ASCII.
Signature Hash Algorithm An algorithm to use for the signature digest.
Secret Key Ring The location of the secret key ring containing the signaturekey.
Signature Key User ID The User ID of the private key used for signing. The format canbe =name for the exact User ID, user@host to match only theemail address, or <user@host> optionally surrounded byignored comments to match only the value within anglebrackets against the email address. This property alsodetermines which User ID(s) will be listed in Signer's User IDsubpackets.
Signature Key ID The Key ID of the private key used for signing. The format canbe 8 hex digits for the short key ID, 16 hex digits for the longkey ID, or 40 hex digits for the fingerprint. Spaces are allowedand are not counted in the length. This property can be usedin place or together with the Signature Key User ID to select amore specific key.
Signature Key Passphrase A case-sensitive passphrase to unlock the Signature PrivateKey.
Signature Expiration The number of seconds after the signature creation time thatthe signature expires. The format is [xxh][xxm]xx[s]. If absentor has a value of zero, the signature never expires.
Edges:
Available Services
350 Information Builders
The following table lists the available Line Edge for the PGP Sign Only Service(com.ibi.agents.XDPGPSignAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailSecurity Could not operate due to a securityviolation.
PGP Verify Signature Only Service (com.ibi.agents.XDPGPVerifySignAgent)
Syntax:
com.ibi.agents.XDPGPVerifySignAgent
iIT Service Object:
format: PGP Verify Signature Only
Description: Verifies a signed PGP message, this agent is deprecated in favor ofPGPDecryptAgent.
Parameters:
Parameter Description
Location The location of the public key ring containing the signaturepublic keys.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 351
The following table lists the available Line Edges for the PGP Verify Signature Only Service(com.ibi.agents.XDPGPVerifySignAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailSecurity Could not operate due to a securityviolation.
fail_unsigned Signature not found.
Preemitter in Flow Service (com.ibi.agents.XDPreemitAgent)
Syntax:
com.ibi.agents.XDPreemitAgent
iIT Service Object:
emit: Preemitter in Flow
operations: Preemitter in Flow
Description:
Runs a specified preemitter. This service is usually used before an emit service.
Parameters:
Parameter Description
Preemitter Name of the defined preemitter to run. If blank, standard selection isused.
Available Services
352 Information Builders
Parameter Description
return* Output is the preemit result. If the preemitter fails:
status. Status document will become the output document.
input. Input document will become the output document
Call at EOS?*
In a streaming environment, EOS (End of Stream) is the short messagethat is sent after the last document, which signifies the EOS. Thisparameter determines whether this service should be called for the EOSmessage. The default value is false.
Edges:
The following table lists the available line edges for the Preemitter in Flow Service(com.ibi.agents.XDPreemitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_preemit
Example:
Running this service with XDCharRepl, the following result is provided:
1. iWay Services
iWay Service Manager Component Reference Guide 353
<?xml version="1.0" encoding="UTF-8" ?> <emitstatus status="1"><protocol>preemit</protocol><parms> <parm name="wanteos">false</parm> <parm name="return">status</parm> <parm name="name">com.ibi.preemit.XDCharRepl</parm></parms><timestamp>2009-01-28T00:26:14.113Z</timestamp><status>1</status> </emitstatus>
Print Emit Service (com.ibi.agents.XDPrintEmitAgent)
Syntax:
com.ibi.agents.XDPrintEmitAgent
iIT Service Object:
emit: Print Emit Agent
Description:
This service is a general print emitter for use within the service stack.
Parameters:
Parameter Description
Printer URL * The URL for the printer.
Server Name * Name of the printer at the URL.
Copies Number of copies.
Retries Number of retries if print server down.
Print format Print format.
Secure If enabled, secure connection will be used.
Secure 128-bit If enabled, use of 128-bit encryption will be enforced.
Proxy Server If enabled, emit through proxy server.
Proxy URL The URL of the proxy server.
Available Services
354 Information Builders
Parameter Description
User ID User ID for challenges.
Password Password for challenges.
Preemitter Determines whether any preemitter should be avoided.
Edges:
The following table lists the available line edges for the Print Emit Service(com.ibi.agents.XDPrintEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnSuccess
Properties File Updater Service (com.ibi.agents.XDPropertyUpdater)
Syntax:
com.ibi.agents.XDPropertyUpdater
iIT Service Object:
misc: Properties file updater
Description:
This service updates a properties file with one or more properties. The properties file can beread by the _property() iWay Functional Language (iFL) function, or by any appropriate tool.
1. iWay Services
iWay Service Manager Component Reference Guide 355
Parameters:
Parameter Description
Path* The full path to the properties file to be updated. The suffix .properties isappended if it is not included in the file name. If the file does not exist, thenit will be created.
Call atEOS?
In a streaming environment, End of Stream (EOS) is the short message thatis sent after the last document, which signifies the EOS. This parameterdetermines whether this service should be called for the EOS message. Bydefault this parameter is set to false.
The properties themselves are user parameters, each constituting of a name/value pair. Thevalues are evaluated by iFL before the file is updated. If the evaluation results in a null value,then the property is deleted from the file.
Edges:
The following table lists and describes the line edges that are returned by the Properties FileUpdater service (com.ibi.agents.XDPropertyUpdater).
Edge Description
success The properties file was updated.
fail_notfound The properties file was not found and could not be created.
fail_parse iFL could not be parsed.
fail_operation The properties file could not be read or written.
Example:
When using the Properties File Updater service (com.ibi.agents.XDPropertyUpdater) as anobject in a process flow, this service focuses on the user parameters that are defined withinthe input document. You can pass any input document to this service.
Consider the following user parameters, which consist of simple name/value pairs:
First = John
Second = Chris
Available Services
356 Information Builders
Third = Mary
The Properties File Updater service will create or update these specific user parameters in theinput document.
A typical use case would be to use XPath to set the values of the user parameters. Forexample, if your input document looked like the following:
<props><first>John</first><second>Chris</second><third>Mary</third></props>
You might define the user parameters as follows:
First = _xpath(/props/first)
Second = _xpath(/props/second)
Third = _xpath(/props/third)
Protocol Business Services
Protocol business services are standard business services that can emit a document to adesignated target or can read from a source. In the standard situation for output, a <replyto>should be used, however for some circumstances, a protocol business service can beemployed. In all cases, if an emitter can be used, it should be used in preference to a protocolbusiness service. Each protocol business service takes initialization parameters appropriate tothe protocol type.
Protocol Agents Result Document
<emitstatus><protocol>name</protocol><status>status code</status><parms>stringOfParms</parms><native>nativeSystemErrorCode</native><text>error descriptive text</text><name>nameOfCreatedFile</name><retries>numberOfRetries</retries><timestamp>timeOfCompletion</timestamp></emitstatus>
The output edges returned are listed in the following table.
Edge Description
success Standard success edge.
fail_parse Could not parse the XPath expression or other entered function.
1. iWay Services
iWay Service Manager Component Reference Guide 357
Edge Description
fail_operation File write failure occurred.
notfound No information meeting the source criteria was located.
P Flow Service (com.ibi.agents.XDPFlowAgent)
Syntax:
com.ibi.agents.XDPFlowAgent
iIT Service Object:
misc: P Flow Agent
Description:
This service passes the input document through a process defined in the System area.
Parameters:
Parameter Description
Name of the PFLOW * The name of the process flow to run. This value could be a stringvalue or a SREG reference for dynamic process flow invocation. Inorder for the service to be successful, the referenced process flowmust be deployed as a service during run time.
Called at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
Edges:
The following table lists the available line edges for the P Flow Service(com.ibi.agents.XDPFlowAgent).
Line Edge Description
OnError Error
Available Services
358 Information Builders
Line Edge Description
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_notfound
fail_timeout
Example:
In a use case scenario, the process flow service can be used to invoke a specified processflow. It can be used in situations where a specific process flow must be invoked dynamically,or when its parameters are being determined in the workflow. For example, you can call aprocess flow name stored as an SREG value.
The following is an example of configuration settings for a PFlow service object in iIT Designer:
1. iWay Services
iWay Service Manager Component Reference Guide 359
Using an SREG allows you to add or change the name or list of names for the process flow tobe called without modifying the original caller process flow.
The single or multiple process flows that are being called need to be deployed as services inorder to be found by the PFlow service. Services can be deployed using the iWay ServiceManager Administration Console from the Services category in the Deployments section, asshown in the following image.
P Flow Test Service (com.ibi.agents.XDPFlowTestAgent)
Syntax:
com.ibi.agents.XDPFlowTestAgent
iIT Service Object:
Available Services
360 Information Builders
Note: This agent is intended for internal use only.
QA Service (com.ibi.agents.XDQAAgent)
Syntax:
com.ibi.agents.XDQAAgent
iIT Service Object:
group Debug: QA Agent
Description:
This service emits a flattened copy of the input document to a file named in the init()parameters. The service outputs the document (XML or flat) in QA, ondebug, or always modes,depending on the configuration setting of the When parameter. If the QA mode is not enabled(by using the set command) and the always option is not set, then this service functions as amove service. This service is designed to work as a chained service for debugging purposes.The document and all special registers are included in the output.
The QA mode for iSM can be set by executing the following command to enable the QA modefor the configuration:
set qa on [-save]
To deactivate the QA mode, execute the following command:
set qa off [-save]
The QA mode must be enabled for the iSM configuration you are using in order for the QAservice to output documents when set to QA mode.
To enable the QA service to output documents on debug, set the iSM debug special register totrue. To deactivate the debug mode, set the debug special register to false.
Parameters:
Parameter Description
Where * File pattern to receive trace file.
1. iWay Services
iWay Service Manager Component Reference Guide 361
Parameter Description
When Determines when to emit the information. Select one of the followingoptions from the drop-down list:
qa (default)
always
ondebug
Name Identifier name to mark emitted trace document.
Emit input Location (file pattern} to which to emit actual input document. If omittedor empty, the incoming document is not emitted.
Base64 Decode If set to true, the value is assumed to be in base64 notation. Onlyapplicable when a specific write value is specified.
Starting Offset If set, this value represents the starting offset within the data block tostart the dump.
Note: The inbound document must be a flat file in order for thisparameter to function as described.
Maximum Length If set, this value represents the total number of bytes to dump. If notset, the dump starts from the value specified for the Starting Offsetparameter to the end of the buffer.
Edges:
The following table lists the available line edges for the QA Service(com.ibi.agents.XDQAAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
362 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse
RabbitMQ Emit Service (com.ibi.agents.XDRabbitMQEmitAgent)
Syntax:
com.ibi.agents.XDRabbitMQEmitAgent
Description:
This service emits a document to a RabbitMQ server using version 0-9-1 of the AdvancedMessage Queuing Protocol (AMQP). The Broker URI is the server address. The destination is acombination of the Outgoing Exchange Name and the Routing Key.
The Broker URI has the following format:
scheme://host:port/virtualhost
The scheme is AMQP for communication in clear with the port defaulting to 5672. For securecommunication over TLS, the scheme is AMQPS with the port defaulting to 5671. The virtualhost is a RabbitMQ concept that allows multiple configurations for the same RabbitMQ server.When /virtualhost is not specified, the virtual host defaults to /. The syntax scheme://host:port is the only way to specify / as the virtual host, since ending the URI with / is notallowed.
When using AMQPS, the TLS configuration is specified with an SSL Context provider. Thisprovider is created in the iSM Administration Console within the Security Provider page underthe Server tab.
The user name and password are the credentials to access the RabbitMQ server. The user iscreated in the RabbitMQ console within the Users page under the Admin tab. Make sure theuser is given permission to access the chosen virtual host. The RabbitMQ console can usuallybe accessed at:
http://host:15672
1. iWay Services
iWay Service Manager Component Reference Guide 363
In version 0-9-1 of AMQP, the message is not sent directly to a queue. Instead, the sendersends the message to an exchange and associates a Routing Key. It is the responsibility ofthe exchange to route the message to all the queues with a binding that matches the messageand the routing key. The queue bindings are part of the exchange configuration on the server.The matching rule depends on the exchange type as follows.
Exchange Type Matching Rule
direct The routing key must equal the binding key.
fanout The routing key is ignored and the binding always matches.
headers The routing key is ignored. The binding specifies a header name andthe value it must have to match. It is possible to specify multipleheaders at the same time, in which case the x match attributedetermines if 'any' or 'all' headers must match.
topic The routing key is matched with wildcards.
The Mandatory property determines what happens when the message does not match anyqueue bindings and therefore was routed to zero queues. When this happens, an error isreturned if mandatory is set, otherwise the message is silently discarded.
The RabbitMQ Emit Service expects the exchange, the queue bindings, and the destinationqueues to be pre-configured on the server. The service does not declare those objectsautomatically.
AMQP defines a set of properties that are always part of the message. Most properties areopen to interpretation by the receiving application. These are: App ID, Content Encoding,Content Type, Correlation ID, Message ID, Response Reply To, Timestamp, Type and User ID.For example, the RabbitMQ server considers the payload to be a byte string. The receivingapplication may use the Content Encoding and Content Type to reconstruct the message, butthat is just by convention.
The properties that affect the broker are: Delivery Mode, Expiration and Priority. The deliverymode is Persistent or Non-Persistent. Persistent messages held in a durable queue will survivea broker restart.
The Expiration is the time the message can remain in the queue before it expires. Expiredmessages are either discarded or dead-lettered, but only when they reach the head of thequeue. Until then, they occupy storage and are counted in the queue statistics. The Priorityaffects the order messages are delivered by a priority queue. The AMQP specification says thepriority is from 0 to 9 but RabbitMQ supports priorities from 0 to 255.
Available Services
364 Information Builders
Unlike message properties, message headers are not standardized. They are under thesending application control. When the Request Header Namespace is specified, every specialregister of type HDR it contains will create a message header of the same name. For example,if the Request Header Namespace is ns and there is special register of type HDR calledns.hdr1 with value v1, then a message header called hdr1 will be created with value v1.
The Avoid Preemitter parameter determines whether preemitters will be executed. The defaultis to skip the preemitters.
The Return Document parameter determines the contents of the output document. Choosestatus to return a status document, or input to return the input document of the service.
Parameters:
The following table describes the parameters of the RabbitMQ Emit service(com.ibi.agents.XDRabbitMQEmitAgent).
Parameter Description
Outgoing ExchangeName
The exchange where the outgoing message will be published.
Broker URI * The Broker URI, in the following format:
scheme://host:port/virtualhost
where:
scheme
Is AMQP or AMQPS.
port
Is optional defaulting to 5672 for AMQP and 5671 forAMQPS.
virtualhost
Is also optional.
SSL Context Provider The iWay Security Provider for SSL Context. If you are usingAMQPS and SSL Context Provider is left blank, then the defaultprovider will be used.
User * User ID for the Broker.
1. iWay Services
iWay Service Manager Component Reference Guide 365
Parameter Description
Password * Password that is associated with the user ID for the Broker.
Routing Key The routing key of the outgoing message.
Mandatory Determines what happens when a message is routed to zeroqueues. When set to true, an error is returned. When set tofalse, the message is discarded.
By default, this parameter is set to false.
App ID Creating application ID.
Content Encoding MIME Content Encoding of the payload.
Content Type MIME Content Type of the payload.
Correlation ID Application correlation identifier.
Delivery Mode Determines whether the message is persistent (2) or non-persistent (1).
By default, this parameter is set to 1 (persistent).
Expiration The message time to live in the queue, non-negative integralnumber of milliseconds.
Message ID Application message identifier.
Priority Message priority (0 to 255).
Response Reply To Destination to reply to this response.
Timestamp The value of the timestamp property in the outgoing message,in milliseconds since the epoch.
Type Message type name.
User ID Creating user ID.
Request HeaderNamespace
The special register namespace from which protocol headers forthe outbound request will be taken.
By default, this parameter is set to none.
Available Services
366 Information Builders
Parameter Description
Avoid Preemitter Determines whether any preemitter should be avoided.
By default, this parameter is set to true.
Return Document Determines whether the output document will be a statusdocument or the input document.
By default, this parameter is set to status.
Edges:
The following table lists and describes the line edges that are returned by the RabbitMQ Emitservice (com.ibi.agents.XDRabbitMQEmitAgent).
Line Edge Description
success The message was successfully sent.
fail_parse An iFL expression could not be evaluated.
fail_connect The service could not connect to the broker.
fail_operation The operation could not be completed successfully.
RabbitMQ Read Service (com.ibi.agents.XDRabbitMQReadAgent)
Syntax:
com.ibi.agents.XDRabbitMQReadAgent
Description:
This service reads a single message from a RabbitMQ queue using version 0-9-1 of theAdvanced Message Queuing Protocol (AMQP).
The Broker URI has the following format:
scheme://host:port/virtualhost
1. iWay Services
iWay Service Manager Component Reference Guide 367
The scheme is AMQP for communication in clear with the port defaulting to 5672. For securecommunication over TLS, the scheme is AMQPS with the port defaulting to 5671. The virtualhost is a RabbitMQ concept that allows multiple configurations for the same RabbitMQ server.When /virtualhost is not specified, the virtual host defaults to /. The syntax scheme://host:port is the only way to specify / as the virtual host, since ending the URI with / is notallowed.
When using AMQPS, the TLS configuration is specified with an SSL Context provider. Thisprovider is created in the iSM Administration Console within the Security Provider page underthe Server tab.
The user name and password are the credentials to access the RabbitMQ server. The user iscreated in the RabbitMQ console within the Users page under the Admin tab. Make sure theuser is given permission to access the chosen virtual host. The RabbitMQ console can usuallybe accessed at:
http://host:15672
The Queue Name identifies which queue will be read.
The Timeout is the period to wait in milliseconds for the message to become available. Whenthe timeout expires, the service returns the input document with the edge noMessage. A valueof zero (0) indicates to return immediately.
Available Services
368 Information Builders
Parameters:
The following table describes the parameters of the RabbitMQ Read service(com.ibi.agents.XDRabbitMQReadAgent).
Parameter Description
Broker URI * The Broker URI, in the following format:
scheme://host:port/virtualhost
where:
scheme
Is AMQP or AMQPS.
port
Is optional defaulting to 5672 for AMQP and 5671 forAMQPS.
virtualhost
Is also optional.
SSL Context Provider The iWay Security Provider for SSL Context. If you are usingAMQPS and SSL Context Provider is left blank, then the defaultprovider will be used.
User * User ID for the Broker.
Password * Password that is associated with the user ID for the Broker.
Queue Name * The name of the queue from which messages will be consumed.
Request HeaderNamespace
The special register namespace into which protocol headersfrom the incoming request will be saved.
By default, this parameter is set to Default Namespace.
Timeout Period to wait in milliseconds for the message to becomeavailable. A value of zero (0) indicates to return immediately.
By default, this parameter is set to 5000.
Special Registers (SREGs):
1. iWay Services
iWay Service Manager Component Reference Guide 369
There is a fixed list of message properties as documented in the AMQP specification. Theservice stores these properties in Special Registers (SREGs) in the AMQP namespace.
The following table describes the SREGs assigned by the RabbitMQ Read service based on theproperties in the message envelope.
SREG Name Description
amqp.deliveryTag The server-assigned and channel-specific delivery tag.
amqp.exchange The name of the exchange that routed this message.
amqp.routingKey The key used to route this message.
amqp.isRedeliver The boolean redelivery flag.
The following table describes the special registers assigned by the RabbitMQ Read servicebased on the properties in the message.
SREG Name Description
amqp.appId Creating application ID.
amqp.contentEncoding MIME content encoding.
amqp.contentType MIME content type.
amqp.correlationId Application correlation identifier.
amqp.deliveryMode A value of 1 indicates non-persistent. A value of 2 indicatespersistent.
amqp.exiration Message time to live in the queue, integer >= 0 in milliseconds.
amqp.messageId Application message identifier.
amqp.priority Message priority, 0 to 255.
amqp.replyTo Destination to reply to.
amqp.timestamp Message timestamp, number of seconds since the epoch.
amqp.type Message type name.
Available Services
370 Information Builders
SREG Name Description
amqp.userId Creating user ID.
Unlike message properties, message headers are not standardized. They are under thesending application control. When present, message headers are stored as special registers inthe specified Request Header Namespace. For example, if a header is named hdr1 and theRequest Header Namespace is ns, then the special register will be called ns.hdr1.
Edges:
The following table lists and describes the line edges that are returned by the RabbitMQ Readservice (com.ibi.agents.XDRabbitMQReadAgent).
Line Edge Description
success The message was successfully sent.
fail_parse An iFL expression could not be evaluated.
fail_connect The service could not connect to the broker.
fail_operation The operation could not be completed successfully.
fail_partner The operation failed because of an error from the peer.
noMessage The timeout expired before a message became available.
Route Service (com.ibi.agents.XDRouteAgent)
Syntax:
com.ibi.agents.XDRouteAgent
Description:
This service routes based on specified routing rules.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 371
Parameter Description
Routing Rules * Name of rules section to be used as basis of routing.
Special Register Name * Name of special register to set from selected destination.
Output Type Type of output from this service.
Edges:
The following table lists the available line edges for the Route Service(com.ibi.agents.XDRouteAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Rule Router Service (com.ibi.agents.XDRuleRouterAgent)
Syntax:
com.ibi.agents.XDRuleRouterAgent
iIT Service Object:
misc: EDI Rule Router
Parameters:
Available Services
372 Information Builders
Parameter Description
Error Location * The error output directory.
Error Mask * The error file name with possible wild cards.
Valid Location The valid output directory.
Valid Mask The valid file name with possible wild cards.
Ack Location The acknowledgement output directory.
Ack Mask The acknowledgement file name with possible wild cards.
Original Location The original data output directory.
Original Mask The original data file name with possible wild cards.
Status Location * The status document output directory.
Status Mask * The status document file name with possible wild cards.
Edges:
The following table lists the available line edges for the Rule Router Service(com.ibi.agents.XDRuleRouterAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
Run OS Shell Command Service (com.ibi.agents.XDRunCmdAgent)
Syntax:
1. iWay Services
iWay Service Manager Component Reference Guide 373
com.ibi.agents.XDRunCmdAgent
iIT Service Object:
operations: Runs a system (OS Shell) command if possible.
Description:
This service runs a system command.
Parameters:
Parameter Description
Command* The system command to execute. On Windows platforms, it iscommon to prepend cmd /C before the command.
Encoding* The Internet Assigned Numbers Authority (IANA) character setused to decode the command result. You can select a valuefrom the drop-down list or type an encoding name directly inthe field.
CData* Set this parameter to true if the command results areexpected to be in CDATA format.
Timeout The amount of time (in seconds) to wait before the commandtimes out. Enter 0 to set no timeout limit.
Detach If set to true, the command is executed in a separate thread,while the current process flow continues to execute. Since asuccess notification is not returned to the process flow,enabling this parameter is not recommended. As analternative, it is recommended to use the native backgroundprocessing of the operating system when possible.
Call at EOS In a streaming environment, a short message is deliveredafter the last document in the stream is sent to signify theEnd of Stream (EOS). The Call at EOS parameter determineswhether the service should be called for the EOS message. Bydefault, this parameter is set to false.
The Timeout and Detach parameters have entirely different and somewhat mutually exclusivefunctions.
Available Services
374 Information Builders
If defined, the Timeout parameter halts the current thread for the specified amount of timewhile a command is being executed or until a command result is returned. If a specifiedtimeout value is reached and a command is still being processed, then the process flowreturns the fail_timeout edge.
If the Detach parameter is set to true, then any timeout value becomes irrelevant because thecommand is executed in parallel by a separate thread. As a result, the process flow does notwait for command results from that thread in order to continue. The process flow resumes itsexecution without delay.
Edges:
The following table lists the available line edges for the Run OS Shell Command Service(com.ibi.agents.XDRunCmdAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
fail_timeout
Example #1
The following image shows a configured value for the Command parameter in the iWay ServiceManager Administration Console.
1. iWay Services
iWay Service Manager Component Reference Guide 375
cmd /C C:\CoreFTP\coreftp.exe -s -O -site ATST1 -u c:\file\ftpin\*.*
In this example, the Run OS Shell Command service runs a command prompt command toinvoke a third-party FTP program (CoreFTP) to perform a required file transfer. Similarly, you canalso use this service to run the supported commands in your shell environment as needed byreferring to third-party tools.
Example #2
In this example, a UNIX Perl script that takes a substantial amount of time to run must beexecuted by a customer. In addition, a process flow must be processed immediately, withoutwaiting for the execution of the UNIX Perl script to be completed.
To satisfy this requirement, a Service object for the Run OS Shell Command service(XDRunCmdAgent) can be configured in a process flow where the Detach parameter is set totrue, as shown in the following image.
This configuration allows the UNIX Perl script to be executed by a separate thread, while theprocess flow continues to run without any interruption.
Available Response Failure Edges for the Run OS Shell Command Service (XDRunCmdAgent)
Available Services
376 Information Builders
During the configuration of a process flow, when you connect a Service object for the Run OSShell Command service (XDRunCmdAgent) to an End object using the OnCustom build relation,the available line edges are provided (including response failure edges). For example:
RVI Relay: send message to gateway service Service (com.ibi.agents.RVIRelay)
Syntax:
com.ibi.agents.RVIRelay
iIT Service Object:
format: RVI Relay: send message to gateway service
Description: Relays messages for external execution.
Parameters:
Parameter Description
Service Name * The name of the service to execute the current message.
Tolerance The time to await circuit availability to access the namedservice, in seconds.
Timeout The time to await response from the gateway, in seconds.
1. iWay Services
iWay Service Manager Component Reference Guide 377
Parameter Description
Attempt Retry If true, a retry exception is thrown when no gatewayconnections are available, the message cannot be written togateway, or this service times out while awaiting response.The retry exception will activate the channel's pending system,when available. If false, this service will attempt to acquire anew connection if the message cannot be written to thegateway and, if a connection is available, will retryautomatically. If no connections are available, or if the servicetimes out or otherwise fails while reading the response, theservice will return a failure edge.
Output On Failure If relay operation is unsuccessful, determined whether theagent should return the standard error document, or return itsinput. If the input is selected, the error document will bestored in the rvi.status register [type: user].
Method of compressionto use *
The form of compression that should be used on the output.
Edges:
The following table lists the available Line Edges for the RVI Relay: send message to gatewayservice Service (com.ibi.agents.RVIRelay).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailPartner Generic or unknown server error. Somethingoccurred between the adapter and adapteecommunication.
OnFailTimeout The operation timed out.
Available Services
378 Information Builders
RVI Response: return iterations to the RVI Iterator Service (com.ibi.agents.XDRVIGatewayAgent)
Syntax:
com.ibi.agents.XDRVIGatewayAgent
iIT Service Object:
format: RVI Response: return iterations to the RVI Iterator
Description: On an RVI Gateway channel, sends a message to the relay.
Parameters:
Parameter Description
Message Type * The input sends the current document back to the relay. EOStells the relay iterator that no more data is coming. Fail sendsa message indicating that gateway processing has failed.
Edges:
The following table lists the available Line Edges for the RVI Response: return iterations to theRVI Iterator Service (com.ibi.agents.XDRVIGatewayAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
RVI Stream Relay Service (com.ibi.agents.RVIStreamRelay)
Syntax:
com.ibi.agents.RVIStreamRelay
iIT Service Object:
1. iWay Services
iWay Service Manager Component Reference Guide 379
format: RVI Stream Relay
Description: TK.
Parameters:
Parameter Description
Service Name * The name of the service to execute the current message.
Tolerance The time to await circuit availability to access the namedservice, in seconds.
Timeout The time to await response from the gateway, in seconds.
Edges:
The following table lists the available Line Edges for the RVI Stream Relay Service(com.ibi.agents.RVIStreamRelay).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested .
OnFailTimeout The operation timed out.
Save/Restore Document Value Service (com.ibi.agents.XDSREGDocAgent)
Syntax:
com.ibi.agents.XDSREGDocAgent
Available Services
380 Information Builders
iIT Service Object:
document:
SREG: Save/Restore Document Value
sreg:
SREG: Save/Restore Document Value
Description:
This service stores a document value in a special register (SREG), or reloads the documentfrom a SREG.
A document is the unit of information that passes through a process flow. There can be only asingle document on any line of the process flow at any time. Documents include payload andstate information. State information in the document is automatically managed by the serverand can be modified in a process flow using the Set Document State service(com.ibi.agents.XDDocAgent). For more information, see Set Document State(com.ibi.agents.XDDocAgent) on page 393.
The logic of some process flows requires that the current document be stored so that it can berecovered later on a process flow line. The Save/Restore Document Value Serviceaccomplishes this by storing the document (or its payload) in a SREG, and later recovering thedocument or its payload. The SREG is a user register of local scope.
Parameters:
Parameter Description
Register name*
The name of the register that is used as a storage location for thedocument.
Action to take * Determines the type of action that is taken by the service. Select one ofthe following values from the drop-down list:
Store to register {store} (default)
The requested document or its payload is stored in the SREG.
Load from register {load}
The current document is replaced by the one that is loaded in theSREG.
1. iWay Services
iWay Service Manager Component Reference Guide 381
Parameter Description
Level * Determines the level of information to be saved. Select one of thefollowing values from the drop-down list:
Full document {doc} (default)
The entire document.
Payload {payload}
Only the information stored in the document. The state is notaffected.
Note: This operand applies only to store actions. The load actionrestores the document based on what was stored.
Clear * Used only for load actions, this parameter determines if the contents ofthe register should be cleared when the load is completed. Thisparameter is set to true by default.
No Activity Log*
If set, this register will not be logged in an activity log. Some drivers willnot respect this setting.
True (default): activity will not be logged.
False: activity will be logged.
No Marshal * If set, this register will not be marshalled for transfer, for example,through a gateway, pending storage, or AFTI.
True (default): will not be marshalled.
False: will be marshalled.
The edges returned are listed in the following table.
Edge Description
success The operation completed successfully.
fail_notfound On a load operation, the register was not found or did not have theappropriate type of information loaded.
Available Services
382 Information Builders
Save/Restore XML Tree Service (com.ibi.agents.XDSREGTreeAgent)
Syntax:
com.ibi.agents.XDSREGTreeAgent
iIT Service Object:
document:
SREG: Save/Restore XML tree
sreg:
SREG: Save/Restore XML tree
Description:
This service stores XML to a special register (SREG), or reloads the XML tree from an SREG.Usually this agent is used to build an XML segment that is then added to the document on theedge at this moment.
Parameters:
Parameter Description
Target The name of the node of the desired subtree.
Type* The target type of the node. Select one of the following target types fromthe drop-down list:
parent
root (default)
Special Reg* Name of the SREG to be assigned.
Note: Register names must conform to the requirements used for XMLelement names.
1. iWay Services
iWay Service Manager Component Reference Guide 383
Parameter Description
Store or load Select one of the following target types from the drop-down list:
Store to register {store} (default)
Saves the tree into the SREG.
Load from register {load}
Sets the outbound document to the value of the SREG.
Edges:
The edges returned are listed in the following table.
Edge Description
success Operation completed successfully.
duplicate The node was found, but has siblings.
notfound The node to assign was not found.
Schema Validation Service (com.ibi.agents.XDSchemaValidationAgent)
Syntax:
com.ibi.agents.XDSchemaValidationAgent
iIT Service Object:
format: Schema Validation
Description: Checks the current document against its schema.
Parameters:
Parameter Description
Schema File * The absolute path of schema, for example, C:\schema\xyz.xsd.
Available Services
384 Information Builders
Parameter Description
Schema Name The schema name, for example, xyz.xsd, xyz.rng, or xyz.sch.
Schema validationTechnique *
The schema validation type.
Error Status Output status- a status document will be the out document.
input - the in document will become the out document.
Edges:
The following table lists the available Line Edges for the Schema Validation Service(com.ibi.agents.XDSchemaValidationAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested .
fail_missingschema The schema could not be found.
flatfile Input document cannot be flat.
schema_not_supported Schema is not supported.
Scripting Agent Service (com.ibi.agents.XDScriptingAgent)
Syntax:
com.ibi.agents.XDScriptingAgent
iIT Service Object:
format: Scripting Agent
1. iWay Services
iWay Service Manager Component Reference Guide 385
Description: Allows for the configuration and execution of scripts using the iSM ScriptingEngine.
Parameters:
Parameter Description
Schema File * The absolute path of schema, for example, C:\schema\xyz.xsd.
Scripting Engine Scripting engine to activate.
Location Location of where the script can be found:
external - The script field contains the path to the script filelocated somewhere on the server file system.
dynamic - The script field will contains the actual script tobe executed. An iSM iFL command (for example, _FILE,_XPATH) may be used to load the script to execute.
document - The script to execute is contained in theinbound document's element named script, SCRIPT, orScript.
Script The path to the script file or script document.
Script Parameters The script entry point and additional variables used to processthe script. To specify a script entry point enter the value as '-entry functionName'. The entry point value is followed by anyadditional parameters that the script needs to execute. If noentry point is specifies the Scripting Engine starts executionwith the first script statement not contained within a scriptfunction.
Output Document Type Determines whether the output document emitted should bethe original input document (input), the agent's results (result)or a status document (status).
Edges:
Available Services
386 Information Builders
The following table lists the available Line Edges for the Scripting Agent Service(com.ibi.agents.XDScriptingAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested .
OnFailSecurity Could not operate dues to a securityviolation..
search Service (com.ibi.agents.XDTwitterSearch)
Syntax:
com.ibi.agents.XDTwitterSearch
iIT Service Object:
format: search
Description: Returns a collection of relevant Tweets matching a specified query.
Parameters:
Parameter Description
Query * A UTF-8, URL-encoded search query of 500 charactersmaximum, including operators. Queries may additionally belimited by complexity.
Lang Restricts tweets to the given language, given by an ISO 639-1two-letter code. Language detection is best-effort.
1. iWay Services
iWay Service Manager Component Reference Guide 387
Parameter Description
Locale Specifies the language of the query you are sending (only ja iscurrently effective). This is intended for language-specificconsumers, and the default should work in the majority ofcases.
Max ID Returns results with an ID less than (that is, older than) orequal to the specified ID.
Since ID Returns results with an ID greater than (that is, more recentthan) the specified ID. There are limits to the number oftweets which can be accessed through the API. If the limit oftweets has occurred since the since_id, the since_id will beforced to the oldest ID available.
Count The number of tweets to return per page, up to a maximum of100. The defaults is 15. This was formerly the parameter inthe old Search API.
Result Type Optional. Specifies what type of search results you wouldprefer to receive. The current default is mixed. Valid valuesinclude:
mixed - Include both popular and real time results in theresponse.
recent - return only the most recent results in theresponse.
popular - return only the most popular results in theresponse.
Until Returns tweets created before the given date. Date should beformatted as YYYY-MM-DD. Keep in mind that the search indexhas a seven-day limit. In other words, no tweets will be foundfor a date older than one week.
Available Services
388 Information Builders
Parameter Description
Geocode Returns tweets by users located within a given radius of thegiven 'latitude,longitude'. The location is preferentially takenfrom the Geotagging API, but will fall back to their Twitterprofile. The parameter value is specified by'latitude,longitude,radius', where radius units must bespecified as either mi (miles) or km (kilometers). Note that youcannot use the near operator via the API to geocode arbitrarylocations. However, you can use this geocode parameter tosearch near geocodes directly. A maximum of 1,000 distinctsub-regions will be considered when using the radius modifier.
Radius The radius to be used in the geocode.
Units The unit of measurement of the given radius. Can be mi(miles) or km (kilometers). Miles is the default.
Consumer Key * Is your Twitter Application Consumer Key. If you don't havethis information, please go to http://dev.twitter.com. Sign inwith your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Consumer Secret * Is your Twitter Application Consumer Secret. If you don't havethis information, please go to http://dev.twitter.com. Sign inwith your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Access Token * Is your Twitter Application Access Token. If you don't have thisinformation, please go to http://dev.twitter.com. Sign in withyour Twitter account, Choose My Applications and click Createa New Application then follow the prompts to get ConsumerKey, Consumer Secret, Access Token, and Access TokenSecret.
1. iWay Services
iWay Service Manager Component Reference Guide 389
Parameter Description
Access Token Secret * Is your Twitter Application Access Token Secret. If you don'thave this information, please go to http://dev.twitter.com. Signin with your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Enabled * If on, emit through the proxy server.
Host The HTTP proxy server host name.
Port The HTTP proxy server port.
User The HTTP proxy server user name.
Password The HTTP proxy server password.
Connection Timeout The HTTP connection timeout in milliseconds.
Read Timeout The HTTP read timeout in milliseconds.
Streaming Read Timeout The streaming API's HTTP Read timeout in milliseconds.
Retry Count The number of HTTP retries.
Retry Interval * The HTTP retry interval in seconds.
Pretty Debug Prettifies JSON debug output if set to true.
Stream Base URL The streaming API base URL.
Site Stream Base URL The Site Streams API base URL.
Edges:
The following table lists the available Line Edges for the search Service(com.ibi.agents.XDTwitterSearch).
Line Edge Description
OnError An exception occurred during execution.
Available Services
390 Information Builders
Line Edge Description
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
onFailConnect Could not connect to Twitter.
onFailParse Could not parse a document.
OnFailTwitterException Twitter threw an exception.
OnFailTwitterOperation Could not perform the Twitter operationrequested.
Security: Authenticate/Impersonate Service (com.ibi.agents.XDPrincipalAgent)
Syntax:
com.ibi.agents.XDPrincipalAgent
iIT Service Object:
format: Security: Authenticate/Impersonate
Description: Authenticates and/or impersonates a user based on credentials in a message.
Parameters:
Parameter Description
Action * The action that this service should perform.
Realm * The security realm to be used to validate this user.
User The user identity to be validated.
Credential The credential (password) used to authenticate this user.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 391
The following table lists the available Line Edges for the Security: Authenticate/ImpersonateService (com.ibi.agents.XDPrincipalAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailSecurity Could not operate dues to a securityviolation..
OnParseError Could not parse a document.
Server Statistics Service (com.ibi.agents.XDChanInfoAgent)
Syntax:
com.ibi.agents.XDChanInfoAgent
iIT Service Object:
format: Server Statistics
Description: Generates an XML document of system statistics.
Parameters:
Parameter Description
Name * The name of the new service object definition.
Description The description of the new service object definition.
Available Services
392 Information Builders
Edges:
The following table lists the available Line Edges for the Server Statistics Service(com.ibi.agents.XDChanInfoAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
Set Document State (com.ibi.agents.XDDocAgent)
Syntax:
com.ibi.agents.XDDocAgent
iIT Service Object:
document: Document state modification
transform: Document state modification
Description:
Sets or resets the current state of the document. This includes error states, encoding andcurrent format.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 393
Parameter Description:
Error Sets whether the document is in error state. Documentsin error state are sent to the errorTo addresses. The errorstate can be tested by the iFL function iserr().
Leave . Do not change the error state.
Set. Set ON the error state.
Reset. Set OFF the error state.
Schema Error If the document has passed through a schema check, thisstate reflects whether an error was reported.
Leave. Do not change the error state.
Set. Set ON the error state.
Reset. Set OFF the error state.
Encoding Sets the current encoding. Select from the list or enter thecorrect IANA code. The encoding is used when thedocument is flattened or serialized for output. This doesnot affect the encoding in which the document is actuallycarried in the document.
Output Form Messages are carried in document in a form appropriateto their processing. Usually this is an XML tree. Use thisoption to change the form to either a binary byte arrayproduced according to the encoding set, or a Unicodestring. These formats are often called Flat in iSMdocumentation. Subsequent use of the document mustexpect that the message contained in the documentarrives in the specified format
iFL Applies only if output form is String. If present, this iFLexpression is applied to the flattened string.
Available Services
394 Information Builders
Edges:
The following table lists the available line edges for the Set Document State(com.ibi.agents.XDDocAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_cancelled
fail_encoding
Set special registers Service (com.ibi.agents.XDSREGAgent)
Syntax:
com.ibi.agents.XDSREGAgent
iIT Service Object:
format: Set special registers
Description: Sets one or more special registers of a given type. The registers are evaluated indefinition order.
Parameters:
Parameter Description
Type of variable The type of variable (headers appear in emitted documents asheader values). Use the del type to delete the register.
1. iWay Services
iWay Service Manager Component Reference Guide 395
Parameter Description
Scope of variable Determines at what level the variable is defined, and thereforecontrols its life span and visibility.
Data Type Determines the data type of the value stored in the register.The best choice is string even for integral values, except forspecial situations like JMS properties.
Lock Name The name of a serialization lock for this set of registeroperations.
Automatic evaluation Causes the contents to hold functions that are evaluated onaccess.
No Activity Log If set, this register will not be logged in an activity log (somedrivers may not respect this setting).
No Marshal If set, this register will not be marshalled for transfer via forexample, gateway, pending storage, or AFTI.
Call at EOS When using a streaming preparser in a channel, a last call ismade AFTER the last document. Determines whether thisService Exit should be called.
Edges:
The following table lists the available Line Edges for the Set special registers Service(com.ibi.agents.XDSREGAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailParse Could not parse a document.
Available Services
396 Information Builders
SFTP Connection Cache Service (com.ibi.agents.XDSFTPConnectionCacheAgent)
Syntax:
com.ibi.agents.XDSFTPConnectionCacheAgent
iIT Service Object:
format: SFTP Connection Cache
Description: Controls connection caching. If set to start, the connection referenced by thisservice is cached until stopped.
Parameters:
Parameter Description
Host Name * The DNS name (or IP address) of the SFTP server that youwant to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank fordefault port 22.
Buffer Size The size of the SFTP buffer to be used when sending orretrieving data. The default value of 32768 is used if this fieldis not set. A larger buffer may improve performance, butsetting this field to a value greater than 65536 will default to65536. The value must be entered as a whole number (forexample, 32768, 65536). iWay recommends leaving thebuffer size at 32768.
Proxy Settings
Proxy Type The proxy protocol to use.
Proxy Host Name The DNS name (or IP address) of the proxy server that youwant to connect to.
Proxy Port The port to connect to on the proxy site.
Proxy User ID The user ID on the proxy server.
Password The proxy user's password on the proxy server.
SSH Parameters
1. iWay Services
iWay Service Manager Component Reference Guide 397
Parameter Description
User Name The user ID on the SSH-enabled server.
Password The user's password on the SSH-enabled server.
Private Key The path to the private key file for public-key authentication..
Passphrase The passphrase used to protect the Private Key.
Provider The name of the SSH Client Security Provider to use. If noProvider name is specified, enter the user name and either apassword or a Private Key and passphrase values (Passphraseis required only if the Private Key file is passphrase protected).
Validate Host Keys If set to true, keys sent from SSH hosts are validated. If valid,the keys are cached by this server. If false, any host key willbe accepted by this server.
Host Key Repository The path to the Known Host Keys repository on this server.
Agent Parameters
Connection caching * If set to start, the connection referenced by this service iscached until stopped. If set to stop, the cached connection isclosed.
Edges:
The following table lists the available Line Edges for the SFTP Connection Cache Service(com.ibi.agents.XDSFTPConnectionCacheAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested .
Available Services
398 Information Builders
Line Edge Description
OnFailSecurity Could not operate dues to a securityviolation..
SFTP Direct Transfer Service (com.ibi.agents.XDSFTPDirectFileTransfer)
Syntax:
com.ibi.agents.XDSFTPDirectFileTransfer
iIT Service Object:
format: SFTP Direct Transfer
Description: Transfers file directly to or from the disk via SFTP or SCP protocol.
Parameters:
Parameter Description
Host Name * The DNS name (or IP address) of the SFTP server that youwant to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank fordefault port 22.
Buffer Size The size of the SFTP buffer to be used when sending orretrieving data. The default value of 32768 is used if this fieldis not set. A larger buffer may improve performance, butsetting this field to a value greater than 65536 will default to65536. The value must be entered as a whole number (forexample, 32768, 65536). iWay recommends leaving thebuffer size at 32768.
Proxy Settings
Proxy Type The proxy protocol to use.
Proxy Host Name The DNS name (or IP address) of the proxy server that youwant to connect to.
Proxy Port The port to connect to on the proxy site.
1. iWay Services
iWay Service Manager Component Reference Guide 399
Parameter Description
Proxy User ID The user ID on the proxy server.
Password The proxy user's password on the proxy server.
SSH Parameters
User Name The user ID on the SSH-enabled server.
Password The user's password on the SSH-enabled server.
Private Key The path to the private key file for public-key authentication..
Passphrase The passphrase used to protect the Private Key.
Provider The name of the SSH Client Security Provider to use. If noProvider name is specified, enter the user name and either apassword or a Private Key and passphrase values (Passphraseis required only if the Private Key file is passphrase protected).
Validate Host Keys If set to true, keys sent from SSH hosts are validated. If valid,the keys are cached by this server. If false, any host key willbe accepted by this server.
Host Key Repository The path to the Known Host Keys repository on this server.
Agent Parameters
Use SCP Use Secure Copy protocol for file copy. Not all servers supportthe use of SCP.
Name of File * The file to be read or written. Relative or absolute file pathsare supported explicitly or through an SREG or XPATHexpression evaluated using the incoming document.
Host Directory An optional directory to be used if Name of File is notabsolute.
Working Directory * The path to the iSM working directory.
Transfer Type * The direction of transfer. Select retrieve to retrieve the filefrom the server. Select send to send the file to the server.
Available Services
400 Information Builders
Parameter Description
Return status - a status document will be the out document.
input - the in document will become the out document.
File Protect Emit a temporary name, and then rename it to the desiredname.
Delete After Read This parameter configures the action to be taken after theread. The options are:
Keep - Do not delete the file (this is the default).
Delete - delete the file immediately after the read.
Delete on Success - This is a transactional delete if thelistener supports transactions. Otherwise the file is deletedimmediately after the file is read. If the listener supportstransactions, the file is not deleted unless the flow ends insuccess. Note: The connection to the SFTP server ismaintained until that time. Users are strongly cautionedthat use of this option within an iteration can result in aholding of connections to the server, which in turn cancause subsequent connection failures and resourcebuildup.
Action on Failure Determines whether an input document or status document isreturned on failure.
Connection Retry Determines the attempted failed connects to the SFTP server.
Retry Interval Retry interval in seconds (allows for xxhxxmxxs format). Omitor use 0 for no retry.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 401
The following table lists the available Line Edges for the SFTP Direct Transfer Service(com.ibi.agents.XDSFTPDirectFileTransfer).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedConnection Could not connect to the external system.
OnFailedOperation Could not perform the operation requested .
OnFailSecurity Could not operate dues to a securityviolation..
SFTP Emit Agent Service (com.ibi.agents.XDSFTPEmitAgent)
Syntax:
com.ibi.agents.XDSFTPEmitAgent
iIT Service Object:
format: SFTP Emit Agent
Description: Emit a message using SFTP to a specific directory on a defined host.
Parameters:
Parameter Description
Host Name * The DNS name (or IP address) of the SFTP server that youwant to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank fordefault port 22.
Available Services
402 Information Builders
Parameter Description
Buffer Size The size of the SFTP buffer to be used when sending orretrieving data. The default value of 32768 is used if this fieldis not set. A larger buffer may improve performance, butsetting this field to a value greater than 65536 will default to65536. The value must be entered as a whole number (forexample, 32768, 65536). iWay recommends leaving thebuffer size at 32768.
Proxy Settings
Proxy Type The proxy protocol to use.
Proxy Host Name The DNS name (or IP address) of the proxy server that youwant to connect to.
Proxy Port The port to connect to on the proxy site.
Proxy User ID The user ID on the proxy server.
Password The proxy user's password on the proxy server.
SSH Parameters
User Name The user ID on the SSH-enabled server.
Password The user's password on the SSH-enabled server.
Private Key The path to the private key file for public-key authentication..
Passphrase The passphrase used to protect the Private Key.
Provider The name of the SSH Client Security Provider to use. If noProvider name is specified, enter the user name and either apassword or a Private Key and passphrase values (Passphraseis required only if the Private Key file is passphrase protected).
Validate Host Keys If set to true, keys sent from SSH hosts are validated. If valid,the keys are cached by this server. If false, any host key willbe accepted by this server.
Host Key Repository The path to the Known Host Keys repository on this server.
1. iWay Services
iWay Service Manager Component Reference Guide 403
Parameter Description
Agent Parameters
Host Key Repository The path to the Known Host Keys repository on this server.
Remote Site Folder The folder or directory on the SFTP site that you want to useas a starting location when you connect. Blank designates thelogin directory.
File Protect Emit a temporary name and then rename it to the desiredname.
Emit Zero Bytes Allow the Emitter to transmit zero bytes to the server. This flagwill be ignored if the document to be emitted is a stream.
File Pattern The output file pattern (* = timestamp), for example,*.xml ,*.txt, etc. Note: *.* is unsupported.
Retry Interval The retry interval in seconds (allows for xxhxxmxxs format).Omit or use 0 for no retry.
Connection Retry Determines the attempted failed connects to the SFTP server.
Retry Interval Retry interval in seconds (allows for xxhxxmxxs format). Omitor use 0 for no retry.
Edges:
The following table lists the available Line Edges for the SFTP Emit Agent Service(com.ibi.agents.XDSFTPEmitAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnFailedConnection Could not connect to the external system.
OnFailedOperation Could not perform the operation requested .
Available Services
404 Information Builders
Line Edge Description
OnFailSecurity Could not operate dues to a securityviolation..
SFTP File Ops Agent Service (com.ibi.agents.XDSFTPFileOpsAgent)
Syntax:
com.ibi.agents.XDSFTPFileOpsAgent
iIT Service Object:
format: SFTP File Ops Agent
Description: Performs simple SFTP file operations.
Parameters:
Parameter Description
Host Name * The DNS name (or IP address) of the SFTP server that youwant to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank fordefault port 22.
Buffer Size The size of the SFTP buffer to be used when sending orretrieving data. The default value of 32768 is used if this fieldis not set. A larger buffer may improve performance, butsetting this field to a value greater than 65536 will default to65536. The value must be entered as a whole number (forexample, 32768, 65536). iWay recommends leaving thebuffer size at 32768.
Proxy Settings
Proxy Type The proxy protocol to use.
Proxy Host Name The DNS name (or IP address) of the proxy server that youwant to connect to.
Proxy Port The port to connect to on the proxy site.
1. iWay Services
iWay Service Manager Component Reference Guide 405
Parameter Description
Proxy User ID The user ID on the proxy server.
Password The proxy user's password on the proxy server.
SSH Parameters
User Name The user ID on the SSH-enabled server.
Password The user's password on the SSH-enabled server.
Private Key The path to the private key file for public-key authentication..
Passphrase The passphrase used to protect the Private Key.
Provider The name of the SSH Client Security Provider to use. If noProvider name is specified, enter the user name and either apassword or a Private Key and passphrase values (Passphraseis required only if the Private Key file is passphrase protected).
Validate Host Keys If set to true, keys sent from SSH hosts are validated. If valid,the keys are cached by this server. If false, any host key willbe accepted by this server.
Host Key Repository The path to the Known Host Keys repository on this server.
Agent Parameters
Operation * The command to execute when agent goes active.
File (from) * The originating file to be operated on. Relative or absolute filepaths are supported through an SREG or XPATH expressionevaluated using the incoming document.
File (to) The destination file to be operated on. Wild cards areaccepted. Required except for delete and size exist.
File (to) a directory name File (to) references a directory. If it is unclear whether the pathnames a directory or a filename, the Service Manager willassume the path names a file.
File (to) Create Directories Create if the directory doesn't exist. Used only for Copy, Move,Rename, and Append operations.
Available Services
406 Information Builders
Parameter Description
Remote Size orPermissions
The name of the Special Register designated to hold size (ifOperation is size), or the file's octal permissions (if Operationis chmod). This field is required when the Operation is eithersize or chmod.
Out Document * The document returned by operation (bad input defaults toresult).
Action on Failure * Determines whether an input document or status document isreturned on failure.
Retry * If non-zero, will retry the operation n times at one-secondintervals.
Edges:
The following table lists the available Line Edges for the SFTP File Ops Agent Service(com.ibi.agents.XDSFTPFileOpsAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedConnection Could not connect to the external system.
OnFailedOperation Could not perform the operation requested .
OnFailSecurity Could not operate dues to a securityviolation..
OnNotFound The resource was not found and this isconsidered an error.
1. iWay Services
iWay Service Manager Component Reference Guide 407
SFTP Read Agent Service (com.ibi.agents.XDSFTPReadAgent)
Syntax:
com.ibi.agents.XDSFTPReadAgent
iIT Service Object:
format: SFTP Read Agent
Description: Reads a file via SFTP and returns the read result.
Parameters:
Parameter Description
Host Name * The DNS name (or IP address) of the SFTP server that youwant to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank fordefault port 22.
Buffer Size The size of the SFTP buffer to be used when sending orretrieving data. The default value of 32768 is used if this fieldis not set. A larger buffer may improve performance, butsetting this field to a value greater than 65536 will default to65536. The value must be entered as a whole number (forexample, 32768, 65536). iWay recommends leaving thebuffer size at 32768.
Proxy Settings
Proxy Type The proxy protocol to use.
Proxy Host Name The DNS name (or IP address) of the proxy server that youwant to connect to.
Proxy Port The port to connect to on the proxy site.
Proxy User ID The user ID on the proxy server.
Password The proxy user's password on the proxy server.
SSH Parameters
Available Services
408 Information Builders
Parameter Description
User Name The user ID on the SSH-enabled server.
Password The user's password on the SSH-enabled server.
Private Key The path to the private key file for public-key authentication..
Passphrase The passphrase used to protect the Private Key.
Provider The name of the SSH Client Security Provider to use. If noProvider name is specified, enter the user name and either apassword or a Private Key and passphrase values (Passphraseis required only if the Private Key file is passphrase protected).
Validate Host Keys If set to true, keys sent from SSH hosts are validated. If valid,the keys are cached by this server. If false, any host key willbe accepted by this server.
Host Key Repository The path to the Known Host Keys repository on this server.
Agent Parameters
File Name * The name of the file or XML tag from the input document inwhich to find the file name.
File Name not aDocument Tag *
The File Name is not a tag. False if the File Name is adocument tag. Otherwise True if the File Name evaluates to avalid file name.
Base Path An optional directory to be used if the incoming name is notabsolute.
Enclose Tag The name of the tag in which to enclose the data read. Ifomitted, there is no entagging. If used, the output is XML.
Input Data Format The format of the input data. The default is flat.
Encoding The character set encoding to be performed on the input.
1. iWay Services
iWay Service Manager Component Reference Guide 409
Parameter Description
Delete After Read This parameter configures the action to be taken after theread. The options are:
Keep - Do not delete the file (this is the default).
Delete - Delete the file immediately after the read.
Delete on Success - This is a transactional delete if thelistener supports transactions. Otherwise the file is deletedimmediately after the file is read. If the listener supportstransactions, the file is not deleted unless the flow ends insuccess. Note: The connection to the SFTP server ismaintained until that time. Users are strongly cautionedthat use of this option within an iteration can result in aholding of connections to the server, which in turn cancause subsequent connection failures and resourcebuildup.
Special RegisterNamespace *
The prefix to give to any Special Register that is generated bythe agent (for example, ftp.read, sftp.read, etc.). Do notterminate the Namespace with a dot (.). That will be be doneautomatically by the Service Manager. If not specified, thedefault value of sftp will be used.
Edges:
The following table lists the available Line Edges for the SFTP Read Agent Service(com.ibi.agents.XDSFTPReadAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
Available Services
410 Information Builders
Line Edge Description
OnFailedConnection Could not connect to the external system.
OnFailedOperation Could not perform the operation requested .
OnFailSecurity Could not operate dues to a securityviolation..
OnNotFound The resource was not found and this isconsidered an error.
fail_delete Cannot delete the file.
show status Service (com.ibi.agents.XDTwitterShowStatus)
Syntax:
com.ibi.agents.XDTwitterShowStatus
iIT Service Object:
format: show status
Description: Returns a single Tweet, specified by the id parameter. The Tweet's author willalso be embedded within the Tweet.
Parameters:
Parameter Description
Tweet/Status Id * The numerical ID of the desired Tweet.
Consumer Key * Is your Twitter Application Consumer Key. If you don't havethis information, please go to http://dev.twitter.com. Sign inwith your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
1. iWay Services
iWay Service Manager Component Reference Guide 411
Parameter Description
Consumer Secret * Is your Twitter Application Consumer Secret. If you don't havethis information, please go to http://dev.twitter.com. Sign inwith your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Access Token * Is your Twitter Application Access Token. If you don't have thisinformation, please go to http://dev.twitter.com. Sign in withyour Twitter account, Choose My Applications and click Createa New Application then follow the prompts to get ConsumerKey, Consumer Secret, Access Token, and Access TokenSecret.
Access Token Secret * Is your Twitter Application Access Token Secret. If you don'thave this information, please go to http://dev.twitter.com. Signin with your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Enabled * If on, emit through the proxy server.
Host The HTTP proxy server host name.
Port The HTTP proxy server port.
User The HTTP proxy server user name.
Password The HTTP proxy server password.
Connection Timeout The HTTP connection timeout in milliseconds.
Read Timeout The HTTP read timeout in milliseconds.
Streaming Read Timeout The streaming API's HTTP Read timeout in milliseconds.
Retry Count The number of HTTP retries.
Retry Interval * The HTTP retry interval in seconds.
Available Services
412 Information Builders
Parameter Description
Pretty Debug Prettifies JSON debug output if set to true.
Stream Base URL The streaming API base URL.
Site Stream Base URL The Site Streams API base URL.
Edges:
The following table lists the available Line Edges for the show status Service(com.ibi.agents.XDTwitterShowStatus).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
onFailConnect Could not connect to Twitter.
onFailParse Could not parse a document.
OnFailTwitterException Twitter threw an exception.
OnFailTwitterOperation Could not perform the Twitter operationrequested.
SMIME Packer Agent Service (com.ibi.agents.XDSMIMEPackerAgent)
Syntax:
com.ibi.agents.XDSMIMEPackerAgent
iIT Service Object:
format: SMIME Packer Agent
Description: Packages input as S/MIME using configured settings.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 413
Parameter Description
Message ID Set this to control the emitted message ID. Usually this is leftblank to let the system generate a unique id meeting therequirements of RFC 822. Use this only to override the default.This is not recommended.
Content-Type * Specifies the content-type of the data to be sent.
Content Disposition The file name to put in the Content-Disposition header value.
SMIME
Packaging * Tells the emitter how the document should be packaged fortransmission.
Compression Determines when or if the S/MIME packager should compressthe message.
S/MIME KeystoreProvider
The provider for the keystore used to sign and encryptmessages.
S/MIME Digest JCEProvider
The JCE Provider for S/MIME Digest Cryptography services.Defaults to the S/MIME Signature JCE Provider.
S/MIME Signature JCEProvider *
The JCE Provider for S/MIME Signature Cryptography services.
Recipient Public Key Alias The alias for the recipient public key entry used for encryption.
Signature Key Alias The alias for the private key entry used for signing.
Signature Key Password The password to access the signature private key. If left blank,the password used to access Keystore will be used.
Digest Algorithm The algorithm to be used for signing.
Encryption Algorithm The algorithm to be used for encrypting.
Include Certificate Chain Determines how much of the signer certificate chain isincluded in the message.
Available Services
414 Information Builders
Parameter Description
Enforce KeyUsageExtension
Determines how the KeyUsage Extension is verified whenpresent in the certificate. The requirement for S/MIME digitalsignatures is followed by the requirement for S/MIMEencryption, separated by a slash.
Header Management
Payload HeaderNamespace
The special register namespace from which additional MIMEheaders for the payload are taken. If not supplied, no MIMEheaders are added beyond the content headers generated bythe packaging process.
Message HeaderNamespace
The Message Header Namespace.
Edges:
The following table lists the available Line Edges for the SMIME Packer Agent Service(com.ibi.agents.XDSMIMEPackerAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
fail_smime Problem processing S/MIME message.
SMIME Unpacker Agent Service (com.ibi.agents.XDSMIMEUnpackerAgent)
Syntax:
com.ibi.agents.XDSMIMEUnpackerAgent
iIT Service Object:
format: SMIME Unpacker Agent
1. iWay Services
iWay Service Manager Component Reference Guide 415
Description: Expects input in the form of an S/MIME multipart document.
Parameters:
Parameter Description
S/MIME KeystoreProvider *
The provider for the keystore used to decrypt incomingmessages.
S/MIME TrustStoreProvider *
The provider for the keystore containing the S/MIMECertificate Authorities.
S/MIME Certificate StoreProviders
A comma-separated list of Keystore, Directory CertStore, orLDAP providers for the certificate stores used to completesigner certificate chains when the signed message containsfewer certificates than needed.
S/MIME Signature JCEProvider *
The JCE Provider for S/MIME Signature Cryptography services.
S/MIME PKIX JCEProvider
The JCE Provider for S/MIME PKIX services. If left blank, thedefault JCE provider for PKIX will be used.
S/MIME Decryption KeyAlias
The private key alias used to decrypt incoming messages
S/MIME Decryption KeyPassword
The password for the decryption private key. If left blank, thepassword for accessing the keystore will be used.
Enforce KeyUsageExtension
Determines how the KeyUsage Extension is verified whenpresent in the certificate. The requirement for S/MIME digitalsignatures is followed by the requirement for S/MIMEencryption, separated by a slash.
Enable CertificateRevocation
Enables CRL or OCSP checking of the signer certificates
OCSP Responder The name of the OCSP Responder provider. This verifies thestatus of certificates online instead of relying on CertificateRevocation Lists.
Unrecognized CertsLocation
The directory to store unrecognized certificates found in S/MIME messages.
Available Services
416 Information Builders
Parameter Description
Signature Required If set, incoming documents require a valid signature.
Default Content TransferEncoding
The default encoding when the Content-Transfer-Encoding isabsent. For S/MIME, this is 7bit. For AS2, this must be set tobinary.
Error Return Determines which document is returned upon error.
Keep Message Flat Keep the body of the message as an array of bytes.
Header Management
Message HeaderNamespace
The special register namespace where message headers canbe found. If not supplied, HDR registers from the defaultnamespace will be used.
Payload HeaderNamespace
The special register namespace into which any headers on theextracted body part will be stored as HDR registers. If notsupplied, body part headers will be saved in the defaultnamespace.
Edges:
The following table lists the available Line Edges for the SMIME Unpacker Agent Service(com.ibi.agents.XDSMIMEUnpackerAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
fail_unsigned Signature not found.
fail_smime Problem processing S/MIME message.
1. iWay Services
iWay Service Manager Component Reference Guide 417
Snip Service (com.ibi.agents.XDSnipAgent)
Syntax:
com.ibi.agents.XDSnipAgent
Description:
This service moves an XML subtree or a JSON value from the input document to the root of theoutput document. This may be especially useful to pull the body payload from a surroundingenvelope with headers.
Parameters:
Parameter Description
Target Location of the desired XML subtree or JSON value, interpretedaccording to the Target Type.
Target Type Determines how the Target is interpreted. The Target can be anXPath expression, the name of the parent XML element, the nameof the XML element itself, or a JsonPath expression. A JsonPathexpression requires a JSON input document, otherwise the inputdocument must be XML.
XML NamespaceProvider
Provider for the mapping between XML namespace prefix andnamespace URI in XPath expressions. If left blank, then the XPathexpression in the Target cannot contain namespaces.
XPath Syntax Determines which syntax level of XPath should be used. Thedefault option selects the syntax level as set in the console globalsettings.
When snipping an XML subtree, the inherited XML namespaces from the ancestor elementsare redeclared on the target node to keep it well-formed.
The Target Type parameter determines how the Target is located. The possible values are:XPath, Parent, Root, or JsonPath.
Available Services
418 Information Builders
When the Target Type is XPath, the Target is an XPath expression that is evaluated against theinput XML document. The result must be a single element that is moved to the root of theoutput document. The service returns notfound if the result is empty, or duplicate if it containsmultiple elements. The XML Namespace Provider parameter is optional. When the provider isspecified, the XPath expression may contain namespace prefixes declared by that provider.You can choose the XPath engine with the XPath Syntax parameter. You can select from:
default
iWay abbreviated syntax
XPath 1.0 full syntax.
When the Target Type is Parent, the Target is the name of the parent element located with adepth-first search within the input XML document. The parent must contain a single childelement that is moved to the root of the output document. The service returns notfound if theparent is not found or if it does not contain a child element. The service returns duplicate if theparent contains multiple child elements.
When the Target Type is Root, the Target is the name of the target element located with adepth-first search within the input XML document. The target element is moved to the root ofthe output document. The service returns notfound if the target element is not found.
When the Target Type is JsonPath, then the Target is a JsonPath expression that is evaluatedagainst the input JSON document. The result must be a single JSON value that is moved to theroot of the output document. The service returns notfound if the result is empty, or duplicate ifit contains multiple values.
Edges:
The following table lists and describes the available edges for the Snip Service(com.ibi.agents.XDSnipAgent).
Line Edge Description
Success The XML subtree or JSON value was successfully snipped.
fail_parse An iFL or XPath expression could not be evaluated.
fail_format The input document is not in the required format for the Target Type.
duplicate The expression returned more than one object or the located nodeunder the parent has siblings.
1. iWay Services
iWay Service Manager Component Reference Guide 419
Line Edge Description
Notfound The XML subtree or JSON value was not found.
Example:
The following example selects the first element in the body of a SOAP envelope. This table liststhe parameter values that would be used.
Parameter Description
Target /soap:Envelope/soap:Body/*[1]
Target Type xpath
XMl Namespace Provider nsprov
XPath Syntax default
This example assumes the nsprov XML Namespace Provider declares the soap prefix to be:
http://schemas.xmlsoap.org/soap/envelope/
The following is a sample input document:
This sample input document produces the following output document:
Sonic Emit Service (com.ibi.agents.XDSonicEmitAgent)
Syntax:
com.ibi.agents.XDSonicEmitAgent
iIT Service Object:
misc: Sonic Emit Agent
Description:
Available Services
420 Information Builders
This service emits data using the Sonic version of JMS to a queue or topic. For moreinformation, see the iWay Service Manager Protocol Guide.
Parameters:
Parameter Description
Queue Name * The name of the receiver queue.
Broker URL * URL (address) used by the listener to connect to the Sonic broker.The format of the URL is Protocol://host:port. If Service Manageris listening on a Sonic broker configured to listen on TCP, theformat of the URL is tcp://host:port. The default TCP port onwhich Sonic listens is 2506. This value is configured in the Sonicbroker.ini file. When Service Manager listens to Sonic, the URL isin the form of http://host:port where the HTTP port is defined inthe Sonic broker.ini file.
The Sonic listener supports fail over if it is unable to reach aparticular broker. You must provide a comma-separated list ofbroker URLs. The client attempts to connect to brokers in the list,for example, tcp://host:port, tcp://host:port.
User ID User ID for challenges.
Password Password for challenges.
Messaging type The messaging type. Select one of the following options from thedrop-down list:
queue
topic
Output Message Type The output message type. Select one of the following optionsfrom the drop-down list:
bytes
text
dynamic
1. iWay Services
iWay Service Manager Component Reference Guide 421
Parameter Description
Ackmode The acknowledgement mode, or transactional. Select one of thefollowing options from the drop-down list:
auto
dupsok
client
trans
Send Persistently Support for persistent and non-persistent messages. In the eventof a network or system failure, the persistent option preventsmessages from being lost.
In the event of a broker or Service Manager failure, non-persistentmessages are volatile. Persistent messages are saved to disk.
Load balance Determines whether to load balance among brokers. Select trueor false.
Detect Determines whether to detect for duplicates. Select true or false.
Priority Priority of the message, which can also be specified usingXPATH(). The default is 3.
Correlation ID Correlation ID of the message, which can also be specified usingXPATH().
Preserve undelivered Determines whether to preserve undelivered documents. Selecttrue or false.
Notify undelivered Determines whether to notify if documents are undelivered. Selecttrue or false.
Preemitter Should any preemitter be avoided?
Available Services
422 Information Builders
Parameter Description
Fault Tolerant Determines whether the listener is connecting to the Sonic Brokeras a fault tolerant client or not. The default value is false, that is,the listener is not connecting as a fault tolerant client.
This feature is supported only when the Sonic Broker is installedwith a Sonic Fault Tolerance license code.
Sequential When multiple brokers listed, this parameter determines whetherthey are used sequentially or randomly. Select true or false.
Reconnect FaultTimeout
Determines how long to wait (in seconds) before trying toreconnect.
Initial ConnectTimeout
Determines how long to wait (in seconds) after failing initially,before trying to reconnect.
Return document Select one of the following options from the drop-down list:
status. Status document will be the output document.
input. Input document will become the output document.
Edges:
The following table lists the available line edges for the Sonic Emit Service(com.ibi.agents.XDSonicEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 423
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_connect
Sonic Queue Browser Service (com.ibi.agents.XDSonicBrowseAgent)
Syntax:
com.ibi.agents.XDSonicBrowseAgent
Description:
This service browses messages using the Sonic version of JMS from a queue or topic. It doesnot delete the message from the queue For more information on Sonic, see the QueuingAdapters chapter in the iWay Service Manager Protocol Guide.
Parameters:
Parameter Description
Queue Name The name of the receiver queue.
Broker URL URL of Sonic Broker. Broker url[protocol://]host:port (can be comma separated listused for failover). Protocols are TCP and HTTP.
User ID User ID for challenges.
Password Password for challenges
Filter Selection Filter
Available Services
424 Information Builders
Parameter Description
Output Format How the output is provided. Select one of thefollowing values from the drop-down list:
Status
Xml
Asread
Load balance Load balance among brokers. Select one of thefollowing values from the drop-down list:
true
false
Fault tolerant How the client is fault tolerant or not. (For example,should there be an attempt to recover from aconnection failure?) Select one of the followingvalues from the drop-down list:
true
false
Sequential When multiple brokers are listed, they are usedsequentially or randomly. Select one of the followingvalues from the drop-down list:
true
false
Reconnect Fault Timeout In seconds, how long to wait before trying to connectagain.
Initial Connect Timeout In seconds, how long to wait after failing initially,before trying to connect again.
1. iWay Services
iWay Service Manager Component Reference Guide 425
Edges:
The following table lists the available line edges for the Sonic Queue Browser Service(com.ibi.agents.XDSonicBrowseAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
Sonic Read Service (com.ibi.agents.XDSonicReadAgent)
Syntax:
com.ibi.agents.XDSonicReadAgent
iIT Service Object:
Description:
This service reads data using the Sonic version of JMS from a queue or topic. For moreInformation on Sonic, see the Queuing Adapters chapter in the iWay Service Manager ProtocolGuide.
Parameters:
Parameter Description
Name The name of the queue or topic to be read.
Broker URL URL of Sonic Broker. The format of the URLis Protocol://host:port.
User ID User ID for challenges.
Available Services
426 Information Builders
Parameter Description
Password Password for challenges.
Acknowledgement Acknowledgment mode, or transactional.Select one of the following options from thedropdown list:
Auto Acknowledge. The sessionautomatically acknowledges the clientreceipt of a message by successfullyreturning from a call to receive(synchronous mode) or when the sessionmessage listener successfully returns(asynchronous mode).
Client Acknowledge. An explicitacknowledge on a messageacknowledges the receipt of allmessages that were produced andconsumed by the session that gives theacknowledgement. When a session isforced to recover, it restarts with its firstunacknowledged message.
Dups OK Acknowledge - The sessionslowly acknowledges the delivery ofmessages to consumers, possiblyallowing some duplicate messages aftera system outage.
Edges:
The following table lists the available line edges for the Sonic Read Service(com.ibi.agents.XDSonicReadAgent).
Line Edge Description
OnError Error
1. iWay Services
iWay Service Manager Component Reference Guide 427
Line Edge Description
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
Split Service (com.ibi.agents.XDSplitAgent)
Syntax:
com.ibi.agents.XDSplitAgent
Description:
This service splits an incoming document to multiple documents according to XSLT transform.
Parameters:
Parameter Description
Directory * Path pattern for the split files.
Transform * XSLT file name and location.
Edges:
The following table lists the available line edges for the Split Service(com.ibi.agents.XDSplitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
428 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
Split To MQ Service (com.ibi.agents.XDSplitToMQAgent)
Syntax:
com.ibi.agents.XDSplitToMQAgent
Description:
This service splits an incoming document into multiple documents according to the documentformat and outputs resulting documents into the specified MQ/Series queue.
Parameters:
Parameter Description
Manager * Name of the local MQ Series queue manager to be used.
Queue name * Queue on which request documents are received.
Correlation ID The correlation ID linking messages.
Correlation ID tag The XML tag at which the correlation ID is located.
MQ host The MQ host, which is needed if you are using MQ client.
MQ port The MQ port, which is needed if you are using MQ client. Thedefault is 1414.
Channel The MQ server channel, which is needed if you are using MQclient.
Delivery Request confirmation of delivery.
Arrival Request confirmation of arrival.
1. iWay Services
iWay Service Manager Component Reference Guide 429
Parameter Description
Report Queue The name of the report queue. Required if COA or COD isrequested or msgtype is response.
Priority Priority of message, which can be specified using XPATH(). Thedefault is 3.
Format Name of MQ message format. The default is STRING.
Type Name of MQ message type.
Message persistence Message persistence. Default is as defined for the queue.
Expiry An expiry time expressed in tenths of a second. The default isunlimited.
MQ Character set MQ Character set, default as per queue manager.
Attributes Include user attributes in the emitted document.
Preemitter Should any preemitter be avoided?
SSL CipherSpec The SSL Cipher Specification being used.
Return document Select one of the following options from the drop-down list:
status. Status document will be the output document.
input. Input document will become the output document.
Join LocalTransaction?
If the listener is a transaction manager, should this emit be rolledback if the transaction fails?
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
Available Services
430 Information Builders
Edges:
The following table lists the available line edges for the Split To MQ Service(com.ibi.agents.XDSplitToMQAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_connect
SP Router Service (com.ibi.agents.XDSPRouter)
Syntax:
com.ibi.agents.XDSPRouter
Description:
This service stacks a stored procedure to handle an EDA doc SP tag.
Parameters:
Parameter Description
prefix The path to prepend to an agent (service) name.
1. iWay Services
iWay Service Manager Component Reference Guide 431
Edges:
The following table lists the available line edges for the SP Router Service(com.ibi.agents.XDSPRouter).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
SQL Batch Row Insert Service (com.ibi.agents.XDSQLInsert)
Syntax:
com.ibi.agents.XDSQLInsert
iIT Service Object:
SQL: SQL Batch Row Insert
Description:
The SQL Batch Row Insert service is designed to be used within an iteration process or aprocess that is being run from a splitting preparser. The batch inserter uses SQL batchoperations where supported to update the database efficiently. The actual performance can beinfluenced by the blocking factors configured for this service and the blocking factorsimplemented on the database.
The inserts will be queued and issued to the database in groups, depending on theconfiguration. Any outstanding inserts will be issued upon successful completion of theprocess flow. The process flow must be configured to operate under local channel transactioncontrol.
Available Services
432 Information Builders
When the SQL Batch Row Insert service is used in an iteration process, your applicationprocess flow must inform the service that the iteration has completed. Otherwise, the SQLBatch Row Insert service will not know that the (current) batch must be sent to the database.This is true regardless of whether your configuration requests sub-batches. The iterators (forexample, XML Split Iterator) provide a special service that must be configured to cause thisnotification to be made. This service takes the form of an end of iteration message thatpasses out of the iterator on the end_iteration edge. This is a custom edge that you mustconfigure in your process flow. It should pass into the SQL Batch Row Insert service through aJunction object. The example in this section shows how to configure such a process flow.Failure to provide an end of iteration message in the insert loop will result in a loss ofinsertions into the database.
Parameters:
Parameter Description
Output document type Determines whether this service generates a status document orpasses the input document to the process flow. Select one of thefollowing options from the drop-down list:
status
input
By default, status is selected.
Destination
Output Provider * The name of a database provider that has been configured. Theinsert operation will be performed on this database.
Output SQL * The Data Manipulation Language (DML) statement used toperform the insert into the database. Use the ?name parameterformat that is used for the SQL service.
Batch Size The number of statements in a batch. Enter zero (0) if all insertsare to be considered as one batch. If a value is entered, sub-batches may result, where commits are performed on the batchwhen the number of inserts reaches the specified value. Thedefault batch size is zero (0).
1. iWay Services
iWay Service Manager Component Reference Guide 433
Parameter Description
Commit Sub-batches If sub-batches are requested, this parameter determines whetherthey should be committed as they update. The default value is setto false.
Fail First If set to true and the first row of the first batch fails, then theoperation is terminated with a fail_insert edge. This usuallyindicates that the database cannot be reached or an insert cannotbe performed for some reason. If this is omitted, then thegenerated status document will indicate which rows weresuccessfully inserted. By default, false is selected.
Fail Count If greater than 0, if the specified number of inserts fail, theoperation terminates on the fail_insert edge. The default value is0.
Omit Test Performs the specified iFL operation. If the operation returns aresult as true, then the row is not inserted into the database.
Fail Key A specified key to save for inserts to identify failing insert rows.This value should consist of an iWay Functional Language (iFL)statement.
Note: This setting consumes system resources to save the keyand time to extract the key.
Available Services
434 Information Builders
Parameter Description
Out Encoding The Internet Assigned Numbers Authority (IANA) character set tobe used for the output database. Select one of the followingcharacter sets from the drop-down list or enter an encoding name:
Leave
Platform
US-ASCII
CP037/EBCDIC
ISO-8859-1
UTF-8
UTF-16BE
UTF-16LE
UTF-16
By default, Leave is selected.
Edges:
The edges returned by the SQL batch row insert service are listed in the following table.
Edge Description
success The insert was batched for execution. If the intermediate batchsize was reached, then the batch operation was completedsuccessfully.
cancelled A cancel was recognized.
fail_parse The parameters could not be parsed.
fail_connect A connection to the provider failed.
fail_connect_destination
A connection to the output database failed.
1. iWay Services
iWay Service Manager Component Reference Guide 435
Edge Description
fail_operation The insert operation failed to execute for some reason other thanthe error that is reported by the database. For example, the insertstatement could not be formatted.
fail_insert Failed on the actual commit if the number of invalid insertsexceeded a threshold value, or if configured, the first row fails.
fail_nullability The database reported a nullability failure.
In addition to these edges, SQL Code edges are available as described in SQL Service(com.ibi.agents.XDSQLAgent) on page 438.
Example:
In this scenario, a database must be updated with one row for each item in an incoming XMLmessage. An example might be an EDI message denoting shipped packages.
The iterator could be an XML Split Iterator to present a single set of values further into theprocess flow. The SQL Insert operation formats an insert statement and adds it to the batch.The operation then passes control to the loop (a move service) that passes control back forthe next row. The SQL insert service could have anchored the loop, but using a move service isa common idiom used to make the process flow easier to read.
When the last row being extracted by the iterator has been passed into the loop, the iteratorsends the end of iteration message on the end_iteration edge. This edge can be wired into theJunction object that leads to the inserter. Naturally, other logic can also appear on either edgefrom the iterator. When control returns to the iterator, control is passed to the End node. Asthe process flow ends, the database commit is performed to insert the rows into the database.If the process is running in transactional mode, then the commit will be performed on asuccessful completion of the process flow. If the process is not running in a transactionalmode, then the commit will be performed immediately.
If you have configured to commit on sub-batches, then it is possible that a transactionalrollback will not avoid updating the database. Also, the behavior in the event of an error maydiffer amongst databases and drivers themselves.
Available Services
436 Information Builders
For very simple types of insert operations, where no processing is to be done on the messageother than simply inserting it, you can wire the end_iteration and the success edge to thesame relation edge. The SQL Batch Row Insert service will sort out the messages.
If you intend to pass the message through an operation before the insert, you must separatethe edges so that the intermediate services (for example, the Transform object in the followingimage) need not see the end of the iteration message.
The status document includes the error information. The type and specific error descriptionsvary depending upon the capabilities of the specific JDBC driver currently in use.
1. iWay Services
iWay Service Manager Component Reference Guide 437
<emitstatus status="0"> <protocol>XDSQLInsert</protocol> <parms> <parm name="col1">100</parm> <parm name="col2">100</parm> <parm name="col3">aa</parm> <parm name="col4">02/01/2013</parm> <parm name="failcount">3</parm> <parm name="failfirst">false</parm> <parm name="failkey">100</parm> <parm name="outbatchsize">2</parm> <parm name="outencoding">leave</parm> <parm name="outomit"/> <parm name="outprov">LocalSQLServer</parm> <parm name="outsql">insert into TestHWM3 values (?col1, ?col2, ?col3, ?col4)</parm> <parm name="return">status</parm> <parm name="subcommit">false</parm> </parms> <timestamp>2013-02-06T17:02:11.179Z</timestamp> <status>0</status> <msg>after final batch</msg> <channel>ExecProcess</channel> <nodename>agent_Service</nodename> <batchstatus rowsread="3" batches="2" failures="1" omits="0"> <fails count="1"> <fail row="-1" key="100" text="SQLException while executing batch. Unable to determine which row caused it: Error converting data type nvarchar to bigint."/> </fails> </batchstatus></emitstatus>
SQL Service (com.ibi.agents.XDSQLAgent)
Syntax:
com.ibi.agents.XDSQLAgent
iIT Service Object:
SQL: SQL Agent
Available Services
438 Information Builders
Description:
The SQL Service enables you to execute an arbitrary SQL statement, specified as a serviceconfiguration parameter. The service returns an EDA response document, as definedelsewhere. This service differs from the more complete RDBMS services and adapters in that itdoes not interrogate an iWay response document to obtain its SQL. Instead, it accepts theSQL as a configuration parameter and modifies the statement based on the current documentor environment. The SQL expression can be modified during execution by iWay standardparameter expressions.
Using the SQL service instead of the RDBMS Adapter is preferred in cases where dynamicallybuilt queries are processed or when simple (non-looping) SQL statements need to beprocessed quickly. This service also provides conditional transactionality support, multi-parttransactional support, advanced SQL language capabilities, and error-handing features.
Parameters:
Parameter Description
SQL DML * The SQL Data Manipulation Language (DML) statement, which canalso evaluate an iFL expression to build an SQL statementdynamically. For example, inserting SREG(value) into the text ofyour query.
Evaluate SQL If set to true, an attempt is made to treat the SQL as anexpression. This may not be appropriate to all SQL. For example,quotes in evaluated strings must be escaped by doubling.
Output Format * The format of the result set for a select operation:
Field. A format designed for efficient XPath.
Column. A format that is effective for transformations.
Simple. A format that contains minimal metadata, andproduces simple JSON documents when converted.
Row. Deprecated. Returns the entire tuple as a single string.This format is not recommended for current JDBC operations.New configurations do not permit Row to be specified.
Examples are shown following this table.
1. iWay Services
iWay Service Manager Component Reference Guide 439
Parameter Description
Use JNDI * If set to true, a connection from a data source accessed throughJNDI is used. Otherwise, connect directly using JDBC drivermanager. When set to true, the Pool Connections configurationparameter should not be used, and pooling is handled in the JNDIdata source manager.
JNDI Name JNDI name for the requested data source. To use an iWay JDBCprovider, specify as jdbc/provider. This is required if you are usingJNDI.
JNDI Factory JNDI initial context factory class. Leave blank for default.
Transaction IsolationLevel
Transaction isolation level to be set if possible.
These are the standard transaction Isolation levels defined in theANSI/ISO SQL standard. For more information on these settings,see the DBMS, JDBC, or ODBC documentation. Based onstandard terminology, the following transaction isolation levelscan be selected:
As Is. Does not change the transaction isolation level. Thedefault is accepted, as it is found on the connection.
Read Uncommitted. Allows reading of a record that may berolled back later. Dirty reads, nonrepeatable reads, andphantom reads are possible.
Read Committed. Dirty reads are not possible, butnonrepeatable reads and phantom reads are possible.
Repeatable Read. Dirty reads and nonrepeatable reads arenot possible, but phantom reads are possible.
Serializable. This is the highest level of isolation. Phantomreads are not possible. Other users are prevented fromupdating or inserting rows into the data set until thetransaction is completed.
For more information on the terminology related to transactionisolation, see Transaction Isolation Terminology on page 707.
Available Services
440 Information Builders
Parameter Description
Pool Connections If set to true, connections are pooled. The default value is false.
Applies to non-local transactions only. This pools connectionswithin the flow itself. Connections can be reused acrossmessages, depending on the commit strategy and the specifics ofthe database being used. If used with JNDI data sources, thislocal service pooling may inhibit optimum use of any JNDI datasource pooling and connection management. In most cases, thePool Connections parameter for this service should not be setwhen using JNDI data sources.
Pooled connections are identified by connection URL and user ID.The pooled connection is shared by all instances of this serviceeither within the channel as a whole or within a single execution(worker) thread. To pool at the worker level, set the Need Commitparameter to true.
In local transactions, connections are always shared within thetransaction.
Attempt Read Only For select set JDBC read only flag. Some drivers cannot handlethis optimization and can give security failures.
Connection Properties Properties to apply to a connection.
1. iWay Services
iWay Service Manager Component Reference Guide 441
Parameter Description
Need Commit Determines how commits should be performed on completion.Select one of the following options from the drop-down list:
Immediate. Issue a commit immediately upon completion ofthe Data Manipulation Language (DML) execution, regardlessof whether or not the process is part of the local transaction.The connection is not pooled for commit purposes.
Transactional. If the process is running as a local transaction,the service will join that transaction. In this case a commit orrollback will be performed on the connection depending on thecompletion status of the process flow. If the process is notrunning in a local transaction, this defaults to the Immediateoption.
Never. No commit is ever issued by the service for thisstatement. This is the default for a select statement. For aDML that requires a commit, the process flow is responsiblefor committing the connection by use of DML in anotherservice. This gives the transaction complete control andresponsibility for the commit or rollback. A commit or rollbackis not executed by the use of the Commit service or by thetransactional status of the process flow.
Force. Always issue a commit before closing the connection.Use only in non-transactional mode. Setting the Force option isrequired only for certain JDBC drivers that require a commit inorder to close all resources. For example, some DB2 driverswill generate an error if a connection is closed without acommit. For other drivers, issuing a commit with nooutstanding work can generate an error. Users are cautionedto only use the Force option if it is required by your driver andapplication design.
Available Services
442 Information Builders
Parameter Description
Note: Prior to iSM version 6.1.4, the Boolean values true(Immediate) and false (Transactional) were provided as options forthis parameter. These internal settings continue to perform as inprevious releases.
Users are cautioned that commits are issued on connections,rather than statements. Selecting the Never option delegatesapplication responsibility for the connection to the applicationrather than the transaction manager of the process flow. Failureto execute an SQL service with never having a COMMIT WORK orROLLBACK WORK (as appropriate for the specific database), willleave the connection uncommitted.
For DML-based statements with the Never option selected, youwill require pooling enabled to insure that the TCL (TransactionControl Language) affects the proper connection. Pooling isautomatic when using JNDI-based connections.
Timeout Number of seconds this service will wait for an operation tocomplete. A value of 0 indicates no timeout check.
Max Rows Maximum rows if query DML (0 is all).
Make Siblings If set to true, sibling documents are created for each Max Rowsgroup.
Sibling documents are full documents that are chained to theemitted document from the service. They can be accessed by useof an iterator, and will be emitted automatically if they exist forthe final document that is output from the process flow.
Max Siblings Maximum siblings of maximum rows (if siblings selected).
Emit No Empty If set to true, empty documents are not emitted.
Issuance Strategy Issuance strategy: through SQL construction or through SQL bind.
Reply Node Name If entered, response is put at this fully qualified named node.
Base 64 if Needed If set to true, all fields are checked for base64.
1. iWay Services
iWay Service Manager Component Reference Guide 443
Parameter Description
xLOB Handling Determines how blobs and clobs should be handled. Select one ofthe following options from the drop-down list:
none (default)
external
inline
Want Generated Keys If set to true, generated keys on a non-bound INSERT statementare returned if available from the database in the 'iway.getkey'register. The default value is false.
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
JDBC Connection Properties
Data Source URL * The URL to reach the data source.
JDBC Driver * The JDBC driver to use.
User ID Default user ID for the connection.
Password Default password for the connection.
Passing Values to DML
When you create the SQL Data Manipulation Language (DML) statement, you can use namedtokens to represent the values to be used in the statement. For example:
Select name, address from addresses where zip='?zipval' and state = '?stateval'
Available Services
444 Information Builders
Then in the user properties, represent the values as name/value token pairs, as listed in thefollowing table.
Name Value
zipval _xpath(/root/user/zip)
stateval _sreg(state)
The SQL Service supports stored procedures containing a mix of input, output, and IN OUTparameters. To use a stored procedure with output parameters, you must describe eachoutput parameter that is expected. The values returned by these parameters are stored in theresponse document generated by this service. The syntax for an output parameter is:
?$type(options).name
where:
options
Is optional.
name
Is optional.
The syntax for an IN OUT parameter is:
?#type(option).name
The type must be set to one of the constants listed in the following table.
JDBC Type Constant Option
BLOB blob
CHAR char
CLOB clob
DATE date
INTEGER int
SQLXML xml
1. iWay Services
iWay Service Manager Component Reference Guide 445
JDBC Type Constant Option
TIMESTAMP tstamp
VARCHAR varchar
CURSOR (Oracle) cursor
Numeric numeric scale
Decimal decimal scale
Input parameters follow the normal syntax for passing information into the DML.
For example, call a stored procedure named sp1 with a string input (perhaps a key) andreceive an output of int, numeric, and a result set (Oracle):
{call ?int.result = sp1(?inkey,?$numeric(2).cost,?$cursor)}
This will return three output parameters (see formats below), indexed 1 (result), 2 (cost), and aresult set.
A stored procedure that uses an input parameter might accept a partial key, and return thecomplete key along with the other data. For example:
{call sp1(?#varchar.inkey,?$numeric(2).cost,?$cursor)}
In either case, you would configure inkey as an input parameter as if it were simply ?inkey, andthe value will also appear as an output parameter.
Examples of using out and IN OUT parameters with stored procedures are provided in Examplesof Using the SQL Service With Stored Procedure Calls and Output Parameters on page 452.
The _qval() function can be used to obtain a null value. For example:
Insert into nametable (first,middle,last) values('?first',?middle,'?last')
Assuming that the first and last values cannot be null, use the following name/value tokenpairs to represent the values.
Name Value
first _sreg('firstname')
middle _qval(_sreg('middle'),'\','empty')
Available Services
446 Information Builders
Name Value
last _sreg('lastname')
If a middle name is not present, then the text NULL is used in the SQL. Otherwise, the quotedstring of the middle name is used.
Edges:
The SQL service (and by extension the SQL object used in process flows) returns edges thatcan be used to analyze execution results at any required level of granularity. Any SQL servicefailure returns a fail_operation edge, but a duplicate or a missing result can also be used. Atthe finest granularity, any specific XOPEN code (or set of codes) can be tested.
The edges returned by the SQL service (com.ibi.agents.XDSQLAgent) are listed in the followingtable.
Edge XOPEN Description
success 00000 The operation was successful. ForSELECT operations, success can beconsidered as the join of found andnotfound edges.
found 00000 Rows were returned. Always issued inconjunction with the success edge. Youmay wire found or success edgesdepending on your applicationrequirements.
notfound 00000 No rows were returned. You may wirenotfound or success edges dependingon your application requirements.
Note: The notfound edge indicates asuccessful operation, as distinct fromthe fail_notfound edge, which indicatesthat some components, such as a tableor column, is not found in the database.
1. iWay Services
iWay Service Manager Component Reference Guide 447
Edge XOPEN Description
duplicate 3C000, 42S01,42S11, 42S21
Some item is duplicated, for example,insert to an existing unique key.
fail_notfound 42S02, 42S12,42S22
A component required in the DML, suchas a table or column, was not found.
fail_operation The SQL operation was not successful.
cancelled A cancellation through a flow timeout.
fail_timeout HYT00, HYT01,40001
The operation times out on the channel.
fail_parse Parameters cannot be parsed in iFL.
fail_syntax 4200, 22007 The SQL had syntax errors as reportedby the DBMS.
fail_other The SQL operation has failed for areason that is not included in any otheredge (for example, fail_notfound). Youcan use the sqlcode special register forfurther analysis.
<xopen code> all Specific XOPEN code. To use this edge,you must define your own custom edgein iIT Designer.
For more information on SQL Service edge returns sorted by XOPEN code, see SQL ServiceEdge Returns Sorted by XOPEN Code on page 701.
The following table lists the Special Register (SREG) set:
SREG Description
sqlcount Number of rows returned for a SELECT operation, or the numberof rows affected by an UPDATE or DELETE operation.
iway.genkey Generated key associated with an INSERT operation, ifappropriate to the database.
Available Services
448 Information Builders
SREG Description
sqlcode The XOPEN code for any unsuccessful operation.
Example:
An SQL Select statement returns a result set as an XML document. The service offers threeformats:
Field
Column
Row
1. iWay Services
iWay Service Manager Component Reference Guide 449
Field format is designed for efficient XPath. Within each row, the fields are presented aschildren. For example:
<?xml version="1.0" encoding="ISO-8859-1" ?><iway> <response totalrows="3" totalupdate="0"> <cncresult> <result format="field"> <resultset rowcount="3"> <colinfo> <col label="LNAME" length="8" offset="0" type="1" typename="char">LNAME</col> <col label="FNAME" length="8" offset="8" type="1" typename="char">FNAME</col> <col label="SSN" length="10" offset="16" type="2" typename="numeric">SSN</col> <col label="BDATE" length="11" offset="26" type="93" typename="tstamp">BDATE</col> <col label="SALARY" length="8" offset="37" type="2" typename="numeric">SALARY</col> </colinfo> <row> <LNAME type="1" typename="char">NARAYAN </LNAME> <FNAME type="1" typename="char">RAMESH </FNAME> <SSN type="2" typename="numeric">666884444</SSN> <BDATE type="93" typename="tstamp">1952-09-15 00:00:00</BDATE> <SALARY type="2" typename="numeric">38000</SALARY> </row> <row> <LNAME type="1" typename="char">SMITH </LNAME> <FNAME type="1" typename="char">JOHN </FNAME> <SSN type="2" typename="numeric">123456789</SSN> <BDATE type="93" typename="tstamp">1955-01-09 00:00:00</BDATE> <SALARY type="2" typename="numeric">30000</SALARY> </row> <row> <LNAME type="1" typename="char">ZELAYA </LNAME> <FNAME type="1" typename="char">ALICIA </FNAME> <SSN type="2" typename="numeric">999887777</SSN> <BDATE type="93" typename="tstamp">1958-07-19 00:00:00</BDATE> <SALARY type="2" typename="numeric">25000</SALARY> </row> </resultset> </result> </cncresult> <timestamp>TIME-QA-QA QA:QA:QA</timestamp> <execstatus>0</execstatus> </response></iway>
Available Services
450 Information Builders
Column format is often effective for transformations. For example:
<?xml version="1.0" encoding="ISO-8859-1" ?><iway> <response totalrows="3" totalupdate="0"> <cncresult> <result format="column"> <resultset rowcount="3"> <colinfo> <col label="LNAME" length="8" offset="0" type="1" typename="char">LNAME</col> <col label="FNAME" length="8" offset="8" type="1" typename="char">FNAME</col> <col label="SSN" length="10" offset="16" type="2" typename="numeric">SSN</col> <col label="BDATE" length="11" offset="26" type="93" typename="tstamp">BDATE</col> <col label="SALARY" length="8" offset="37" type="2" typename="numeric">SALARY</col> </colinfo> <row> <column label="LNAME" name="LNAME" type="1" typename="char">NARAYAN </column> <column label="FNAME" name="FNAME" type="1" typename="char">RAMESH </column> <column label="SSN" name="SSN" type="2" typename="numeric">666884444</column> <column label="BDATE" name="BDATE" type="93" typename="tstamp">1952 09-15 00:00:00</column> <column label="SALARY" name="SALARY" type="2" typename="numeric">38000</column> </row> <row> <column label="LNAME" name="LNAME" type="1" typename="char">SMITH </column> <column label="FNAME" name="FNAME" type="1" typename="char">JOHN </column> <column label="SSN" name="SSN" type="2" typename="numeric">123456789</column> <column label="BDATE" name="BDATE" type="93" typename="tstamp">1955-01-09 00:00:00</column> <column label="SALARY" name="SALARY" type="2" typename="numeric">30000</column> </row> <row> <column label="LNAME" name="LNAME" type="1" typename="char">ZELAYA </column> <column label="FNAME" name="FNAME" type="1" typename="char">ALICIA </column> <column label="SSN" name="SSN" type="2" typename="numeric">999887777</column> <column label="BDATE" name="BDATE" type="93" typename="tstamp">1958-07-19 00:00:00</column> <column label="SALARY" name="SALARY" type="2" typename="numeric">25000</column> </row> </resultset> </result> </cncresult>
<timestamp>TIME-QA-QA QA:QA:QA</timestamp> <execstatus>0</execstatus> </response></iway>
1. iWay Services
iWay Service Manager Component Reference Guide 451
Row format was originally designed for extremely fast retrieval, but your application isresponsible for extracting information for the rows through string manipulation. This formatmatches the format returned by the EDA API of the Full Function Server, and should only beused with that database. iWay Software does not recommend this format for most generalapplications.
<?xml version="1.0" encoding="ISO-8859-1" ?><iway> <response totalrows="3" totalupdate="0"> <cncresult> <result format="std"> <resultset rowcount="3"> <colinfo> <col label="LNAME" length="8" nullable="1" offset="0" type="1" typename="char">LNAME</col> <col label="FNAME" length="8" nullable="1" offset="8" type="1" typename="char">FNAME</col> <col label="SSN" length="10" offset="16" type="2" typename="numeric">SSN</col> <col label="BDATE" length="11" nullable="1" offset="26" type="93" typename="tstamp">BDATE</col> <col label="SALARY" length="8" offset="37" type="2" typename="numeric">SALARY</col> </colinfo> <row>NARAYAN RAMESH 666884444 1952-09-15 00:00:0038000 </row> <row>SMITH JOHN 123456789 1955-01-09 00:00:0030000 </row> <row>ZELAYA ALICIA 999887777 1958-07-19 00:00:0025000 </row> </resultset> </result> </cncresult> <timestamp>TIME-QA-QA QA:QA:QA</timestamp> <execstatus>0</execstatus> </response></iway>
Examples of Using the SQL Service With Stored Procedure Calls and OutputParameters
When using the SQL Service to execute any stored procedure with parameters, iWay Softwarerecommends that the service be configured to use the bind issuance strategy. However, whena procedure has output parameters, the bind strategy must be used.
Calling a Stored Procedure With Input and Output Parameters
The following Oracle procedure accepts a varchar as input and returns a varchar and a date asoutput values:
Available Services
452 Information Builders
Create or Replace Procedure HELLO_TODAY ( P_NAME IN VARCHAR2, P_HELLO OUT VARCHAR2, P_TODAY OUT DATE) AS BEGIN SELECT CURRENT_DATE INTO P_TODAY FROM DUAL; P_HELLO := 'Hello ' || P_NAME;END HELLO_TODAY;
To execute the procedure, the SQL DML is specified as:
{call HELLO_TODAY(?name, ?$varchar, ?$date)}
The following table describes how the three parameters are specified:
Parameter Description
?name An input parameter, to which the value of the user parameter name,evaluated at execution time will be bound.
?varchar An output parameter of type varchar. Note that no name is specified. Inthe response document, the value of this parameter can be identifiedfrom its index.
?date An output parameter of type date. Again, no name is specified, but theresulting value can be identified from the index of the parameter.
1. iWay Services
iWay Service Manager Component Reference Guide 453
If the procedure executes successfully, the SQL Service will generate the following type ofresponse document:
<iway> <response totalrows="0" totalupdate="-1"> <cncresult> <result format="column"> <outparm index="2" name="parm2" type="varchar" jdbctype="12">Hello Stephen</outparm> <outparm index="3" name="parm3" type="date" jdbctype="91">2013-03-08 10:46:10.0</outparm> </result> </cncresult> <timestamp>2013-03-08T15:46:11Z</timestamp> <execstatus>0</execstatus> </response></iway>
Note: The value of the index attribute on the outparm elements refers to the index of theparameter relative to all parameters, not just output.
Calling a Stored Procedure With an IN OUT Parameter
The following simple procedure uses the same parameter for both input and output:
Create or Replace Procedure INOUT_HELLO (P_HELLO_NAME IN OUT VARCHAR2) AS BEGIN P_HELLO_NAME := 'Hello ' || P_HELLO_NAME;END INOUT_HELLO;
The SQL DML for the service can be specified as:
{call INOUT_HELLO(?#varchar.name)}
The IN OUT parameter is specified as:
Parameter Description
??#varchar.name This time, the ?# prefix is used to indicate that this is an IN OUTparameter of type varchar. For input, you will bind the value of theuser parameter name and you will also use name to identify theoutput of this parameter in the response document. An IN OUTparameter must be defined with a name.
Available Services
454 Information Builders
If the procedure executes successfully, the SQL Service will generate the following type ofresponse document:
<?xml version="1.0" encoding="ISO-8859-1" ?><iway> <response totalrows="0" totalupdate="-2"> <cncresult> <result format="column"> <outparm index="1" name="name" type="varchar" jdbctype="12">Hello Stephen</outparm> </result> </cncresult> <timestamp>2013-03-08T19:49:04Z</timestamp> <execstatus>0</execstatus> </response></iway>
Calling an Oracle Procedure With an Input and a Cursor Output Parameter
The following procedure returns data from the iWay Business Activity Monitor (BAM) database,based on a pattern passed as an input parameter:
Create or Replace Procedure BAM_ACTIVITY_LIST ( P_TID IN VARCHAR2 , P_RC OUT SYS_REFCURSOR ) AS BEGIN open P_RC for select recordkey, recordtype, tstamp from BAM_Activity where TID like P_TID;END BAM_ACTIVITY_LIST;
To invoke the procedure with the SQL Service, the SQL DML parameter is set as:
{call BAM_ACTIVITY_LIST(?mytid, ?$cursor.tidresult)}
The following table describes how the two parameters are specified:
Parameter Description
?mytid An input parameter, to which the value of the user parametermytid, evaluated at execution time, will be bound.
??$cursor.tidresult
An output parameter that will have the cursor datatype and beidentified in the response document as tidresult.
1. iWay Services
iWay Service Manager Component Reference Guide 455
If the service succeeds in executing the procedure and is configured to output its result incolumn format, then the service will generate the following type of response document:
<?xml version="1.0" encoding="ISO-8859-1" ?><iway> <response totalrows="28" totalupdate="-1"> <cncresult> <result format="column"> <outparm index="2" name="tidresult" type="cursor" jdbctype="-10"> <resultset rowcount="28"> <colinfo> <col length="32" offset="0" type="1" typename="char" label="RECORDKEY">RECORDKEY</col> <col length="22" offset="32" type="2" typename="numeric" label="RECORDTYPE">RECORDTYPE</col> <col length="11" offset="54" type="93" typename="tstamp" label="TSTAMP">TSTAMP</col> </colinfo> <row> <column name="RECORDKEY" label="RECORDKEY" type="1" typename="char">5dc36681b5f742b09d7ebbb10a79ae7e</column> <column name="RECORDTYPE" label="RECORDTYPE" type="2" typename="numeric">101</column> <column name="TSTAMP" label="TSTAMP" type="93" typename="tstamp">2012-5-10.14.50. 40. 900000000</column> </row> </resultset> </outparm> </result> </cncresult>
<timestamp>2013-03-08T14:40:17Z</timestamp> <execstatus>0</execstatus> </response></iway>
Available Services
456 Information Builders
Note: The resultset is formatted in exactly the same way as if it had been returned from aSELECT statement, except that it becomes a child of the outparm element. Also, note that thename attribute of the output element holds the out parameter name as specified in the SQLDML.
SREG FTP: Pass register settings to iWay FTP Server Service (com.ibi.agents.XDNFTPSREGAgent)
Syntax:
com.ibi.agents.XDNFTPSREGAgent
iIT Service Object:
format: SREG FTP: Pass register settings to iWay FTP Server
Description: Set registers on the FTP Server.
Parameters:
Parameter Description
Host Name * The DNS name (or IP address) of the FTP server that you wantto connect to. Use host:port if not the standard port 21.
Remote Port The port to connect to on the FTP site. Leave blank to use thedefault port 21.
User Name * The valid user ID on the FTP server.
Password * The valid password for the FTP server.
Account Name The valid account for the FTP server.
Use Passive Command Uses PASV command if true, otherwise uses PORT command
Timeout The timeout interval for socket in seconds.
Port Restrictions If set, restricts the PORT/EPRT command to the followingrange of ports (for example, 1000-9999, 50000-60000, etc.).
Retry Interval The retry interval in seconds (allows for xxhxxmxxs format)Omit or use 0 for no retry.
Connection Retry The number of retry attempts after failed connection to FTPserver.
1. iWay Services
iWay Service Manager Component Reference Guide 457
Parameter Description
Sregs
Type of variable The type of variable (headers appear in emitted documents asheader values). Use del type to delete the register.
Return status - a status document will be the out document.
input - the in document will become the out document.
Proxy Settings
Proxy Type Select the proxy protocol to use.
Proxy Host Name The DNS name (or IP address) of the proxy server that youwant to connect to.
Proxy Port The port to connect to on the proxy site.
Proxy User ID The user ID on the proxy server.
Password The proxy user's password on the proxy server.
SSL Parameters
Use SSL If set, the connection is secured via Secure Sockets Layer(SSL).
Available Services
458 Information Builders
Parameter Description
Security Protocol Security protocol.
SSL - Supports some version of SSL. May support otherversions.
SSLv2 - Supports SSL version 2 or higher.
SSLv3 - Supports SSL version 3. May support otherversions.
TLS - Supports some version of TLS. May support otherversions.
TLSv1 - Supports TLS version 1. May support otherversions.
The field is not needed if Keystore is a SSL Provider.
Secure Data Connection Use a secure data connection, that is, transfer data securely.Used in conjunction with Secure Control Connection.
Use 128-bit Encryption Enforces the use of 128-bit encryption.
SSL Security * FTP Server connection type.
unknown - Defaults to Explicit Security then fails over toImplicit Security.
explicit - In order to establish the SSL link, explicit securityrequires that the FTP client issue a specific command tothe FTP server after establishing a connection. The defaultFTP server port is used.
implicit - Implicit security automatically begins with an SSLconnection as soon as the FTP client connects to an FTPserver. In implicit security, the FTP server defines a specificport for the client (typically 990) to be used for secureconnections.
1. iWay Services
iWay Service Manager Component Reference Guide 459
Parameter Description
Keystore File or SecurityProvider
The full path to the Keystore file, which provides certificatematerial to be used for SSL connection, the name of theSecurity Provider, or leave blank to use the configured defaultSecurity Provider.
Keystore Password The password to access Keystore file. Not needed if KeystoreFile or Security Provider is the name of a Security Provider.
Keystore Type The type of the Keystore. Not needed if the Keystore File orSecurity Provider is the name of a Security Provider.
Edges:
The following table lists the available Line Edges for the SREG FTP: Pass register settings toiWay FTP Server Service (com.ibi.agents.XDNFTPSREGAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailConnection Could not connect to the external system.
OnFailedOperation Could not perform the operation requested .
OnFailSecurity Could not operate dues to a securityviolation..
SREG Insert Service (com.ibi.agents.XDSregInsertToDocAgent)
Syntax:
com.ibi.agents.XDSregInsertToDocAgent
Available Services
460 Information Builders
iIT Service Object:
document:
SREG: Insert into Document
sreg:
SREG: Insert into Document
transform:
SREG: Insert into Document
Description:
This service inserts special register groups into the document. Select a prefix or a namespacefor a group of registers and insert them as elements under the specified node. Special registernames and values will be inserted as attributes. You can use this service if you need to inserta number of elements into your document, but you do not initially know how many of them willbe defined in runtime.
Parameters:
Parameter Description
XPATH for Parent Node The parent node.
Element name for the new nodes Element name for the new nodes.
SREG Prefix The namespace being used.
Attribute name for keys An attribute name for the SREG name.
Attribute name for values An attribute name for the SREG value.
Edges:
The following table lists the available line edges for the SREG Insert Service(com.ibi.agents.XDSregInsertToDocAgent).
Line Edge Description
OnError Error
1. iWay Services
iWay Service Manager Component Reference Guide 461
Line Edge Description
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
none
one
many
Example:
The following is a sample input document:
<root> <group> </group> <data> ... </data></root>
The following parameters are defined:
Parameter Value
XPATH for Parent Node /root/group
Element name for the new nodes sreg
SREG Prefix mysregs
Attribute name for keys name
Attribute name for values value
Available Services
462 Information Builders
The following special registers are defined:
mysregs.first = one
mysregs.second = two
mysregs.third = three
The following is a sample output document:
<root> <group> <sreg name="first" value="one" /> <sreg name="second" value="two" /> <sreg name="third" value="three" /> </group> <data> ... </data></root>
If running it with <Test>sreg(iwayhome)</Test>, the service successfully inserts iwayhome inthe document:
<?xml version="1.0" encoding="UTF-8" ?><Test> <META test="C:/IWAY70~3/" /></Test>
SREG Namespace Service (com.ibi.agents.XDSREGNamespaceAgent)
Syntax:
com.ibi.agents.XDSREGNamespaceAgent
iIT Service Object:
sreg:
SREG: Namespace Management Agent
Description:
This service performs the following operations on registers in namespaces:
Copy. Duplicates registers from a source namespace to a destination namespace. After acopy operation is performed, the registers are available in both namespaces.
Move. Moves registers from one namespace to another.
Delete. Deletes all registers in the namespace.
1. iWay Services
iWay Service Manager Component Reference Guide 463
Exist. If any registers exist in the name namespace, pass the flow down the success edge,else down the notfound edge.
The SREG namespace service offers from name and to name combo-box parameters. Each ofthese parameters offers the [listener] and [default] options which are interpreted as describedabove.
Parameters:
Parameter Description
Function * Determines which function should be performed by the service.Select one of the following options from the drop-down list:
copy (default)
move
delete
exist
From Namespace * Copy/move/exist/delete from namespace. Select [listener-xx] fromthe drop-down list to receive the values configured on the listener.
To Namespace Copy/move to namespace. Select [listener-xx] from the drop-downlist to receive the values configured on the listener.
Edges:
The following table lists the available line edges for the SREG Namespace Service(com.ibi.agents.XDSREGNamespaceAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
464 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_operation
notfound
Note: Namespace names must conform to the requirements used for XML element names.The names are further restricted for HDR registers if the namespace and the register name,when combined, will be used to form a message header for a protocol that itself has restrictedcharacter conventions. In many cases the namespace portion of the name will be removed foruse and then only the register name restrictions will apply.
SREG: Save/Restore Document Value Service (com.ibi.agents.XDSREGDocAgent)
Syntax:
com.ibi.agents.XDSREGDocAgent
iIT Service Object:
format: SREG: Save/Restore Document Value
Description: Stores the document value in a special register, or reloads the document from aspecial register.
Parameters:
Parameter Description
Register name * The name of the special register holding the document
Action to take * Store to register saves the value of the current document inthe named register.
Load from register restores it.
1. iWay Services
iWay Service Manager Component Reference Guide 465
Parameter Description
Level * Payload addresses only the message information.
Full document includes all state information such asaddresses, error status, etc.
Clear * Determines on load whether the register should be clearedafter loading.
No Activity Log * If set, this register will not be logged in an activity log (somedrivers may not respect this setting).
No Marshal * If set, this register will not be marshalled for transfer via, forexample, gateway, pending storage, or AFTI.
Edges:
The following table lists the available Line Edges for the SREG: Save/Restore Document ValueService (com.ibi.agents.XDSREGDocAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnNotFound The resource was not found and this isconsidered an error.
SREG: Save/Restore XML tree Service (com.ibi.agents.XDSREGTreeAgent)
Syntax:
com.ibi.agents.XDSREGTreeAgent
iIT Service Object:
format: SREG: Save/Restore XML tree
Description: Stores XML to a special register, or reloads the tree from a special register.
Available Services
466 Information Builders
Parameters:
Parameter Description
Target The location of the desired XML subtree or JSON value,interpreted according to the Target Type.
Target Type * Determines how the Target is interpreted. The Target can bean XPath expression, the name of the parent XML element,the name of the XML element itself, or a JsonPath expression.A JsonPath expression requires a JSON input document,otherwise the input document must be XML.
Special reg * The name of special register to be assigned.
Operation * The direction of operation, store document subtree into aspecial register, or load document subtree from a specialregister.
Edges:
The following table lists the available Line Edges for the SREG: Save/Restore XML tree Service(com.ibi.agents.XDSREGTreeAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnDuplicate The attempt resulted in duplication of aresource. This may or may not be a failure.
OnNotFound The resource was not found and this isconsidered an error.
OnFailedOperation Could not perform the operation requested.
1. iWay Services
iWay Service Manager Component Reference Guide 467
SREG Service (com.ibi.agents.XDSREGAgent)
Syntax:
com.ibi.agents.XDSREGAgent
Description:
This service sets one or more Special Registers (SREGs) under program control. The SREGscan be set to any of the supported scopes (Message, Flow, or Thread) and can belong to anydefined category (Header, User, or Document).
Setting SREGs above the Message scope requires specification of a lock to avoid raceconditions in a multithreading situation.
Parameters:
Parameter Description
Type of variable Type of variable (headers appear in emitted documents as headervalues). Select one of the following options from the drop-down list:
User. This variable is part of the process flow logic and is themost commonly used type.
Document. This variable is specific to the incoming document,such as the name of the input document.
Header. This variable is part of the document routinginformation, such as an HTTP header or an IBM MQSeriesdescriptor.
Metric. This variable is used to maintain statistics at the serveror channel (protocol) level. For example, the maximum value oftransactions received or the number of errors of a certain type.
Delete. This variable indicates the removal of the register setthat is used in a process flow.
Available Services
468 Information Builders
Parameter Description
Scope of variable For process flows, scope can be for all nodes or only nodes forwardon this edge. Select one of the following options from the drop-downlist:
Message
Flow
Thread
Channel
Server
Flow- and message-scoped variables have one shared copy for theentire process flow. Therefore, a change made to the variable will beseen on all parallel paths. Unless various points of the parallelprocess flows are synchronized, the results that are written to aglobal variable may leave the variable with an unpredictable value.
Flow-scoped variables are deleted at the termination of the processflow (or sub-flow) in which they are declared. If you need a variableto be available to the calling process flow (parent flow) or tosubsequent components, such as outlets and emitters, selectMessage as the scope.
Thread-scoped variables are duplicated for each parallel documentpath, allowing independent manipulation of each copy. After parallelpaths converge at a Join object, the value of the thread isundefined.
Channel-scoped variables are at the protocol level and can be usedin a metric to keep information across workers. Registers with achannel scope require a lock.
Server-scoped variables are above the channel level and can keepmetrics across the entire server. Registers with a server scoperequire a lock.
1. iWay Services
iWay Service Manager Component Reference Guide 469
Parameter Description
Lock A lock is a name that applies to one or more metrics being updatedor referenced as a whole. This allows synchronous values to beretained. For example, if metrics A and B are updated, it is a goodpractice to keep their settings in the same relationship to oneanother. You do not want to change them in such a way that metricsA and B are no longer related.
Automaticevaluation
Causes contents to be evaluated to hold functions. Select one ofthe following options from the drop-down list:
true. Evaluates an SREG every time it is retrieved.
false (default). Evaluates an SREG only once, as the value isstored.
To summarize, if you select false, the expression is not evaluatedupon storage into the SREG. If you select true, the contents of theSREG are evaluated every time it is retrieved.
For expressions that have different results at different times, thisoffers more functionality than storing the result once (for example,an expression that formats a timestamp saved to an SREG).
However, if the Automatic evaluation parameter is set to true for_flatof(), XPATH, or other operations that pertain to the documentitself, the result will always be NULL because access to “thedocument” is not available.
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message. The default value is false.
Available Services
470 Information Builders
Edges:
The following table lists the available line edges for the SREG Service(com.ibi.agents.XDSREGAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
The SREG Service can be used to save a state of the current document or a document specificparameter, such as an XPath value. For example, you need to run a transformation on adocument, but also want to capture the document first by saving it in a SREG value. In theevent of an error during the transformation, you can provide the original document that causedthe error.
1. iWay Services
iWay Service Manager Component Reference Guide 471
The service can be invoked using the typical parameter values, as shown in the followingimage:
Available Services
472 Information Builders
The user-defined parameters pane is where the SREGs must be defined, as shown in thefollowing image:
The SREGs are evaluated in the order they are defined in the pane. Therefore, one SREG canrefer to the value in another. For example:
one _xpath(/root/coms/@port)
two _sreg(one)+1
three _sreg(two)+1
Evaluation ordering applies only when using a Service object of type SREG Agent in a processflow.
The following SREG types are supported:
Boolean. Boolean values (true or false).
Duration. Date/time value.
Decimal. Decimal number value.
Integer. Integer number value.
1. iWay Services
iWay Service Manager Component Reference Guide 473
Password. Password (masked) text value.
String. String text value.
Note: Register names must conform to the requirements used for XML element names. Thenames are further restricted for HDR registers if the register will be used to form a messageheader for a protocol that itself has restricted character conventions. Use of the namespacedesignator '.' is supported for registers in which such namespaces are meaningful.
SWIFT Out Report Service (com.ibi.agents.SWIFTOutReportAgent)
Syntax:
com.ibi.agents.SWIFTOutReportAgent
iIT Service Object:
Description:
This service creates a SWIFT Validation Report for SWIFT outbound (XML to SWIFT) documents.When configured with a preemitter, this service creates an XML document that contains anyerrors in the generated SWIFT document. For more information, see the iWay IntegrationSolution for SWIFT User's Guide.
Parameters:
Parameter Description
Basic Header If set to true, a Basic Header is added to the report.
Application Header If set to true, an Application Header is added to the report.
User Header If set to true, a User Header is added to the report.
Edges:
The following table lists the available line edges for the SWIFT Out Report Service(com.ibi.agents.SWIFTOutReportAgent).
Line Edge Description
OnError Error
OnSuccess Success
Available Services
474 Information Builders
Line Edge Description
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
SWIFT Transform Service (com.ibi.agents.XDSWIFTTransformAgent)
Syntax:
com.ibi.agents.XDSWIFTTransformAgent
iIT Service Object:
Description:
This service transforms SWIFT FIN messages to SWIFT XML documents. For more information,see the iWay Integration Solution for SWIFT User's Guide.
Parameters:
Parameter Description
Base Path * Base path to the transform template.
Version * The SWIFT version.
Block 4 Delimiter If set to true, a delimiter is inserted into SWIFT Block 4.
Edges:
The following table lists the available line edges for the SWIFT Transform Service(com.ibi.agents.XDSWIFTTransformAgent).
Line Edge Description
OnError Error
1. iWay Services
iWay Service Manager Component Reference Guide 475
Line Edge Description
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
SWIFT Validation Service (com.ibi.agents.XDSWIFTValidationReportAgent)
Syntax:
com.ibi.agents.XDSWIFTValidationReportAgent
iIT Service Object:
Description:
This service creates a SWIFT Validation Report for SWIFT inbound (SWIFT to XML) documents.When configured with a preparser this service creates an XML document that contains anyerrors in the SWIFT document that is received. For more information, see the iWay IntegrationSolution for SWIFT User's Guide.
Parameters:
Parameter Description
Basic Header If set to true, a Basic Header is added to the report.
Application Header If set to true, an Application Header is added to the report.
User Header If set to true, a User Header is added to the report.
Available Services
476 Information Builders
Edges:
The following table lists the available line edges for the SWIFT Validation Service(com.ibi.agents.XDSWIFTValidationReportAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
SWIFT XML Transform Service (com.ibi.agents.XDIWAYSWIFTXMLTransformAgent)
Syntax:
com.ibi.agents.XDIWAYSWIFTXMLTransformAgent
iIT Service Object:
SWIFT: SWIFTXMLTransformAgent
Description:
This service transforms SWIFT XML documents to SWIFT FIN messages. For more information,see the iWay Integration Solution for SWIFT User's Guide.
Parameters:
Parameter Description
SWIFT FIN Message Version * The SWIFT FIN message version.
Transformation Template * The template used for the conversion.
Encoding The encoding type for the output.
1. iWay Services
iWay Service Manager Component Reference Guide 477
Parameter Description
Validation Off Enables or disables XMLG SWIFT validation.
Block 4 Delimiter If set to true, a delimiter is inserted into SWIFT Block 4.
Edges:
The following table lists the available line edges for the SWIFT XML Transform Service(com.ibi.agents.XDIWAYSWIFTXMLTransformAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
TCP Emit Service (com.ibi.agents.XDTCPEmitAgent)
Syntax:
com.ibi.agents.XDTCPEmitAgent
iIT Service Object:
misc: TCP Emit Agent
Description:
This service emits a document over TCP/IP.
Parameters:
Available Services
478 Information Builders
Parameter Description
Host * The machine name or IP address of the TCP host.
Port * The port to which to connect to the host.
Sending Type Select one of the following options from the drop-down list:
NONE. Sending XML.
MSB. 4-byte binary length prepended.
ASC. 6-byte ASCII length prepended.
CLOSE. Send non-XML and close the socket.
Return Select one of the following options from the drop-down list:
status. Status document will be the output document.
input. Input document will become the output document.
swap. As input, but replace written data in the source nodes withthe file name to which the data was written.
IP Interface Host Local IP interface host from which the outgoing IP socket originates.
IP Interface Port Local IP interface port from which the outgoing IP socket originates.
Timeout Timeout interval for socket. The protocol will test for STOP each cycle ofthis period.
Edges:
The following table lists the available line edges for the TCP Emit Service(com.ibi.agents.XDTCPEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 479
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
Example:
Available Services
480 Information Builders
A simple way to test your TCP emitted messages is to configure another running channel with aTCP listener and an appropriate emitter (for example, a File emitter) to consume the messagesthat are emitted by the service. The following image is an example of configuration settings fora TCP listener:
After deploying and starting the channel with the TCP listener and File emitter, you can test runyour process flow containing the TCP Emit service object. You must supply an incomingdocument that contains the appropriate content. For example, HTML:
<html><head> <title>my iWay tcp</title></head><body>Testing TCP Emit Service!</body></html>
If the service runs successfully, the TCP listener picks up the sample HTML document that isemitted by the TCP Emit service. The HTML document is then received in the destination folderthat is specified for the File emitter.
TIBCO RV Emit Service (com.ibi.agents.XDTIBRVEmitAgent)
Syntax:
1. iWay Services
iWay Service Manager Component Reference Guide 481
com.ibi.agents.XDTIBRVEmitAgent
iIT Service Object:
misc: TIBRV Emit Agent
Description:
This service sends the message to the TIBCO Rendezvous queue and waits for a response. Formore information, see the iWay Service Manager Protocol Guide.
Parameters:
Parameter Description
Send subject The subject to which the message will be emitted.
Reply subject The subject to which the message's response is to be sent.
Field name Field (message) name.
Service name The service name.
Network name The network name.
Daemon host:port Daemon host:port
Synchronous Send Send the message and wait for the response. Select one of thefollowing options from the drop-down list:
true
false (default)
Timeout Maximum time to wait for the answer (in seconds), -1 means infinitewait.
Available Services
482 Information Builders
Parameter Description
Data Type Reads a file and returns the read result. Select one of the followingoptions from the drop-down list:
Opaque (default)
String
TibrvMsg
TibrvXml
Preemitter Determines whether any preemitter should be avoided. Select one ofthe following options from the drop-down list:
true (default)
false
Return document Select one of the following options from the drop-down list:
status (default). Status document will be the output document.
input. Input document will become the output document.
Edges:
The following table lists the available line edges for the TIBCO RV Emit Service(com.ibi.agents.XDTIBRVEmitAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 483
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_connect
Trace Message Writer Service (com.ibi.agents.XDTraceAgent)
Syntax:
com.ibi.agents.XDTraceAgent
iIT Service Object:
operations: Trace Message Writer
Description:
This service writes a message to the trace log of the system. The trace log accumulatesmessages to record the progress of activity within the server. Usually the trace log is used fordebugging purposes.
Parameters:
Parameter Description
Trace Level The trace level at which the message is written to the trace log.Select one of the following trace levels from the drop-down list:
Error
Warn
Debug
Info
Category A category to be applied for this message. If omitted, then themessage will be logged in the standard logger category. If specified,then the name provided will appear as the log message category.
Available Services
484 Information Builders
Parameter Description
Isolate CategoryLogger
Applies only for error messages with a category name.
A trace to a named category logger is never deferred. By default, anerror trace is considered a general error causing a reset of the defermode of the standard logger. If isolated, then a category logger isconsidered independent and the defer mode of the standard loggeris not affected. If the standard logger is not in defer mode, then thisparameter has no effect.
isolate. Isolate the trace.
join. Remove defer trace on error.
The default is join, such that the category logger is not isolated.
Message The message to be written to the trace log.
Call at EOS? In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document, which signifies theEOS. This parameter determines whether this service should becalled for the EOS message.
The following table lists and describes the edges that are returned by the Trace MessageWriter Service.
Edge Description
success The line was successfully sent to the trace system.
fail_parse iFL used in the parameters was invalid.
The trace message is written to the trace log at the error or debug level. The trace systemmust be configured to accept the message on the issued level. Users must be made awarethat the use of a trace log can adversely affect server performance.
1. iWay Services
iWay Service Manager Component Reference Guide 485
Caution: The trace log is not the transaction log, which can hold messages regardingoperations within the server. Messages can be written to the transaction log using the ActivityLog Entry service (XDXALogEvent) and the Activity Log Business Error Message service(XDXALogBizErr). While trace messages are usually free format and designed to help debug aproblem, the XALog (transaction log) is more structured and often has externally imposedsecurity, event code, and format constraints.
Transaction Completion Registration Service (com.ibi.agents.XDTxAgent)
Syntax:
com.ibi.agents.XDTxAgent
iIT Service Object:
operations: Transaction Completion Registration
Description:
This service registers process flows to be executed at commit or rollback instances of the localtransaction. These process flows can include compensating logic when an application interactswith non-transactional systems. Input to the process flow will be a copy of input to this service.Any user-defined parameters will be available to the process flow as Special Registers (SREGs)in the process flow scope.
Parameters:
Parameter Description
Rollback Flow Process flow to execute if the local transaction is rolled back. Thisprocess flow must be published to the system level of the currentconfiguration.
Commit Flow Process flow to execute if the local transaction is committed. Thisprocess flow must be published to the system level of the currentconfiguration.
Available Services
486 Information Builders
Services capable of supporting transaction commit/rollback in a process flow automaticallyrespond the success of failure of the process flow as a whole by issuing a commit or rollbackaccordingly. Examples of such services are the SQL service, MQ Read service, and the MQEmit service. Other services do not so respond to commit or rollback, either because theunderlying service (for example, a Siebel system) does not support transactionality or theoperation required must rely on application logic. In such a situation, your flow can register aprocess flow to be run at transaction commit/rollback (end of the process flow) appropriate tothe transactional status. For the most common case (handling a failure by rolling back activity)this is usually referred to as a compensating transaction.
You can register one or more compensating or committing transactions by using theXDTxAgent. Each use will register an event process flow for rollback and/or commit handling.The process flow must be deployed as a system process flow to the configuration/application.
On entry, the process flow will be given the input document that was in effect when theregistration service registered the event flow.
You can also enter user variables (Special Registers) to the service, which will be available asflow-level registers when the commit or rollback event flow is invoked. The value seen by theprocess flow will be the current set that is defined during the registration for that flow.
Edges:
The following table lists the available line edges for the Transaction Completion RegistrationService (com.ibi.agents.XDTxAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_notfound
1. iWay Services
iWay Service Manager Component Reference Guide 487
Transform Service (com.ibi.agents.XDTransformAgent)
Syntax:
com.ibi.agents.XDTransformAgent
iIT Service Object:
transform: Transform Agent
Description:
This service applies a defined transform to each document. The transform name should be analias specified in the transforms section of the engine configuration. The transformation canbe an iWay transform or an XSLT transform. The transform service is especially useful as partof a sequence of business services in which the output is chained to another business serviceto execute a business process.
Note: The Transform service is only used to call a transform dynamically. Otherwise, you mustconfigure a Transform object using iIT Designer. In order for a transform to be called properlyduring run time, the transform must be contained in a process flow, which is deployed as aservice.
Parameters:
Parameter Description
Transform name * The name of the defined transform to execute.
Available Services
488 Information Builders
Parameter Description
Expected input The type of document to reach this service. The actual inputformat must match the type that is declared. Select one of thefollowing options:
All Types (default). Any payload received by the service ispassed to the transformation. Streams are not accepted.
Flat. A non-XML payload is expected.
XML. An XML payload is expected. It does not include an iWayerror status document, which will be rejected.
iWay Error. Only an iWay error status document will beaccepted. Other payloads will be rejected.
All XML. Any XML payload (including the iWay error format) isaccepted. Only flat formats are rejected.
Document type Type of output document being emitted by the transform. Selectone of the following options:
XML (default)
Flat
Engine Type of transformation. Select one of the following options:
iWay Transformer (default)
XSLT
Trim Determines whether data should be trimmed beforetransformation. By default, this parameter is set to false.
Error Status Output Sets the output format that is emitted by the service if an erroroccurs. Select one of the following options:
status (default). Sets the output format as an error statusdocument.
input. Sets the output format as the input document.
1. iWay Services
iWay Service Manager Component Reference Guide 489
Parameter Description
Call at EOS In a streaming environment, EOS (End of Stream) is the shortmessage that is sent after the last document is processed, whichsignifies the EOS. This parameter determines whether this serviceshould be called for the EOS message. By default, this parameteris set to false.
Error Masks
Input Side If set to true, all non-fatal errors that occur during transform inputparsing are suppressed. By default, this parameter is set to false.
Output Side If set to true, all non-fatal errors that occur during transformoutput parsing are suppressed. By default, this parameter is setto false.
If transformation is not able to finish or if there are function errors in the output document(TRANSFORM_FUNCTION_ERROR), the agent returns an error status document if Error StatusOutput parameter and follows the fail_transform edge instead.
Available Services
490 Information Builders
Edges:
The edges returned are listed in the following table.
Edge Description
success The transformation process completed successfully.
fail_transform The transformation process completed with errors.
fail_format The input document format does not match the expected inputtransform format.
The following is an example of an error status document that is returned:
<?xml version="1.0" encoding="UTF-8" ?><error status="1"><msg>Transform returned function errors</msg><parms> <parm name="engine">iway</parm> <parm name="inmask">false</parm> <parm name="intype">all</parm> <parm name="outmask">false</parm> <parm name="outtype">flat</parm> <parm name="shouldTrimParm">false</parm> <parm name="stat">status</parm> <parm name="transform">case_61862517_FWFOut_reg</parm> <parm name="wanteos">false</parm></parms><timestamp>2011-01-21T22:03:14.214Z</timestamp><status>1</status><channel>ExecProcess</channel><nodename>agent_FWF_JDBC_Xform</nodename><functionerrors><item>[FUNCTION] Function JDBCLOOKUP error: com.iwaysoftware.transform.common.function.FunctionException: JDBC driver com.mysql.jdbc.Driver cannot be loaded. Detail: com.mysql.jdbc.Driver</item></functionerrors></error>
Tree Evaluator Service (com.ibi.agents.EvalWalk)
Syntax:
com.ibi.agents.EvalWalk
iIT Service Object:
document: Tree Evaluator
1. iWay Services
iWay Service Manager Component Reference Guide 491
sreg: Tree Evaluator
transform: Tree Evaluator
Description:
This service passes an incoming XML tree and applies iFL evaluation to all or selected nodesof the tree. Element values and their attributes are evaluated.
Parameters:
Parameter Description
Filter Expression An XPath expression (optional) used to select items to beevaluated. If no value is provided, then all element values andtheir attributes will be evaluated.
XML Namespace MapProvider
Provider used to map between an XML namespace prefix and anamespace URI. If no value is provided, then elements in thedocument will use the default namespace.
XPath Syntax * Determines the implementation of XPath that should be used.Select one of the following implementations from the drop-downlist.
Default. Selects the syntax level as specified in the GeneralSettings section of the iSM Administration Console.
iWay abbreviated syntax. iWay implementation is fast, buthas limited language support.
Full XPath 1.0 syntax. XPath 1.0 provides full languagesupport, but is slower.
Edges:
The edges that are returned by this service are listed in the following table.
Edge Description
success The incoming XML tree has been evaluated.
Available Services
492 Information Builders
Edge Description
fail_parse The service configuration or the incoming XML tree containsinvalid iFL.
fail_operation The incoming document is not in XML format, or the requirednamespace provider cannot be located.
Example 1:
The following node, if selected for evaluation:
<node1/ATR1="_ISERROR()">SREG(ip)</node1>
might become:
<node1/ATR1="false">123.45.678.910</node1>
Example 2:
The following node, if selected for evaluation:
<Test><_sreg(iwayhome)</Test>
might become:
<Test>c:/iway70</Test>
Example 3:
Use XPath to identify a subtree within the incoming document to be evaluated:
/root/interesting_part//*
UDP Emit Service (com.ibi.agents.XDUDPEmitAgent)
Syntax:
com.ibi.agents.XDUDPEmitAgent
Description:
The UDP Emit service allows you to configure a service to transmit a User Datagram Protocol(UDP) message packet to a specified host.
1. iWay Services
iWay Service Manager Component Reference Guide 493
Parameters:
Parameter Description
Host The host name or IP address of the machine to which the UDPmessage packet will be sent.
Port The port number of the host to which the UDP message packetwill be sent.
Prepend PacketLength
Determines whether to prepend the data packet length. Selectone of the following values from the drop-down list.
true. The UDP message packet will contain a length prefix. Theemitter calculates the binary length of the message. Thislength is exclusive of the four byte packet length. The length isthen prepended to the packet.
false. The UDP message packet will not contain a lengthprefix.
By default, false is selected.
Note: Due to the nature of UDP, the only error checking that is performed is whether the hostmachine can be reached. Message packets are sent to the host with no guarantee that thepacket was received or was processed by the specified host system.
Unmarshall Service (com.ibi.agents.XDUnmarshallAgent)
Syntax:
com.ibi.agents.XDUnmarshallAgent
iIT Service Object:
exit preparse: Unmarshall Agent
misc: Unmarshall Agent
Description:
A message that is marshaled by the Marshal service (com.ibi.agents.XDMarshallAgent) isautomatically unmarshaled by the server, so that no application action is required. In somecases, the marshaled message must be specifically unmarshaled. These include the use ofencryption in the marshaling process and the acquisition of a marshaled message through achannel other than a listener.
Available Services
494 Information Builders
Note: This service is packaged with the iwgateway.jar extension.
Parameters:
Parameter Description
Use Encryption Determines whether the marshaled message will be encrypted. Asecure AES cipher is used and must be deciphered by thereceiver using the Unmarshal service. Automatic unmarshalingcannot be performed on an encrypted message.
AES Key A cipher key shared between the marshal and unmarshalservices. Commonly, this is specified as a special register(SREG) or from a properties file.
Edges:
The edges that are returned by this service are listed in the following table.
Edge Description
success The message has been unmarshaled and is ready for sending.
fail_operation The message could not be decompressed, decrypted, orunmarshaled.
Update Correl Entry Service (com.ibi.agents.XDUpdateCorrelEntryAgent)
Syntax:
com.ibi.agents.XDUpdateCorrelEntryAgent
iIT Service Object:
misc: Update Correl Entry Agent
Description:
This service uses the correlation management bus to update a correlated process.
1. iWay Services
iWay Service Manager Component Reference Guide 495
Parameters:
Parameter Description
Correlation ID * The identifier for the correlated process. Normally a runtimefunction such as XPATH() or SREG().
Namespace Namespace for the correlation ID. IDs will normally be uniquewithin a namespace.
Activity Type * Determines the type of update.
Close Correlated Process*
If set to true, the correlated process is closed.
Comment Any additional information associated with this correlatedprocess.
Edges:
The following table lists the available line edges for the Update Correl Entry Service(com.ibi.agents.XDUpdateCorrelEntryAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
closed
notfound
Available Services
496 Information Builders
Uuencode (com.ibi.agents.XDUUPreEmitter)
Syntax:
com.ibi.agents.XDUUPreEmitter
Description:
This pre-emitter allows you to Uuencode the document prior to it being emitted by iWay ServiceManager. If you are sending an email with an attachment and you suspect your recipient(s)may not have a MIME-compliant system (for example, an older PC or UNIX system), you canspecify Uuencode for the attachment to an email note.
Parameters:
Parameter Description
File Name File Name to be used in the UUENCODED header.
Note: This entry is informational only and does not necessarilyrepresent a physical file accessible to the Service Manager. Rather,it is included in the Uuencode header information that is generated.
Example:
The following example shows a simple flat text input document containing flat text:
Test!Gentle Reader:This is nothing more than a test file created to provide fodder for the various encoding schemes. If you are using it to test, congratulations onyour agility in cutting, pasting, saving, and decoding using WinZip.Enjoy!
1. iWay Services
iWay Service Manager Component Reference Guide 497
The output document appears as shown below:
begin 666 encoded.txtM5&5S="$-"@T*1V5N=&QE(%)E861E<CH-"@T*5&AI<R!I<R!N;W1H:6YG(&UOM<F4@=&AA;B!A('1E<W0@9FEL92!C<F5A=&5D('1O('!R;W9I9&4@9F]D9&5RM(&9O<B!T:&4@=F%R:6]U<R!E;F-O9&EN9R!S8VAE;65S+B!)9B!Y;W4@87)EM('5S:6YG(&ET('1O('1E<W0L(&-O;F=R871U;&%T:6]N<R!O;B!Y;W5R(&%GM:6QI='D@:6X@8W5T=&EN9RP@<&%S=&EN9RP@<V%V:6YG+"!A;F0@9&5C;V1I:;F<@=7-I;F<@5VEN6FEP+@T*#0I%;FIO>2$``end
iFL Function:
_uudecode
Using the uudecoding function converts a string from a uuencode buffer back into the originaltext (or data) representation. This function works on either a fixed uuencoded buffer or dataobtained from iWay Service Manager using an iFL function such as _FILE to read in the data.
The following table shows the values and descriptions of the _uudecode functions.
Parameters Descriptions
String Value to convert (optional).
Note: If a value is not provided, then the current documentwill be used for input.
String Encoding used to convert recovered bytes to a string.
Example:
The following example uses the _file iFL function to load the file data into the first parameter ofthe _uudecode function. This is shown in the uusample.dat file.
begin 644 encoded.txtM5&5S="$-"@T*1V5N=&QE(%)E861E<CH-"@T*5&AI<R!I<R!N;W1H:6YG(&UOM<F4@=&AA;B!A('1E<W0@9FEL92!C<F5A=&5D('1O('!R;W9I9&4@9F]D9&5RM(&9O<B!T:&4@=F%R:6]U<R!E;F-O9&EN9R!S8VAE;65S+B!)9B!Y;W4@87)EM('5S:6YG(&ET('1O('1E<W0L(&-O;F=R871U;&%T:6]N<R!O;B!Y;W5R(&%GM:6QI='D@:6X@8W5T=&EN9RP@<&%S=&EN9RP@<V%V:6YG+"!A;F0@9&5C;V1I:;F<@=7-I;F<@5VEN6FEP+@T*#0I%;FIO>2$!end
Available Services
498 Information Builders
The _uudecode function then converts the buffer into the following uudecoded string:
Test!Gentle Reader:This is nothing more than a test file created to provide fodder for the various encoding schemes. If you are using it to test, congratulations onyour agility in cutting, pasting, saving, and decoding using WinZip.Enjoy!
Verify WSSE Timestamp Service (com.ibi.agents.XDWSSETimestampVerifyAgent)
Syntax:
com.ibi.agents.XDWSSETimestampVerifyAgent
iIT Service Object:
format: Verify WSSE Timestamp
Description: Verifies that a WSSE Timestamp is still valid.
Parameters:
Parameter Description
XML Namespace Provider The provider for the mapping between XML namespace prefixand namespace URI. If left blank, the XPath expression for theTimestamp Element cannot contain namespaces.
XPath Syntax Determines which syntax level of XPath should be used. Thedefault option selects the syntax level as set in the consoleglobal settings.
Timestamp Element Path The path to the Timestamp XML element. If left blank, theagent will search throughout the document for an elementnamed Timestamp in the namespace http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd.
Time to Live The time allowed after the timestamp creation before thetimestamp is considered stale. Leave blank to accept anycreation time in the past. The format is [xxh][xxm]xx[s], forexample, 1m30s is 90 seconds.
1. iWay Services
iWay Service Manager Component Reference Guide 499
Parameter Description
Future Time to Live Determines how far in the future the timestamp creation isallowed to be. This option is useful to account for clock skew.Leave blank to accept any creation time in the future. Theformat is [xxh][xxm]xx[s], for example, 1m30s is 90 seconds.
Edges:
The following table lists the available Line Edges for the Verify WSSE Timestamp Service(com.ibi.agents.XDWSSETimestampVerifyAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
fail_verify Failed security validation.
Web Service Client Service (com.ibi.agents.XDWSClientAgent)
Syntax:
com.ibi.agents.XDWSClientAgent
iIT Service Object:
misc: WS Client Agent
Description:
This service executes a web service and allows a transformation to be applied to theresponse.
See Web Service HTTP Client Service (com.ibi.agents.XDWSHttpClientAgent) on page 503 for aversion of this service that manages HTTP connections through an HTTP Client provider. Thisprovider offers more security options and improves connection reuse.
Available Services
500 Information Builders
Parameters:
Parameter Description
End point * The location where the web service has been deployed.
SOAP Action Value of the SOAPAction header for HTTP.
Content-Type Value of the Content-Type MIME Header. The default value is:
text/xml
User ID User ID for Basic Authentication challenges.
Password Password for Basic Authentication challenges.
Timeout The timeout value in seconds. The default value is:
0
Header The header of the web service message. This value can be a filename, transform, or actual data with SREG, XPATH, and so on.
Body The body of the web service message. Can be a file name,transform, or actual data with SREG, XPath, and so on. Thedefault value is:
_flatof(false)
Fault Transform Transformation to apply when a web service fault occurs.
Strip SOAP Envelope If set to true, the SOAP envelope from the response document isremoved. By default, this parameter is set to false.
For more information on the behavior and usage of thisparameter, see the description that follows this table.
Response Transform Transformation to apply for the web service response document.
Proxy
Proxy If enabled, emit through proxy server. By default, this parameter isset to false.
Proxy URL The URL of the proxy server.
1. iWay Services
iWay Service Manager Component Reference Guide 501
Parameter Description
Proxy User ID User ID for Basic Authentication challenges issued by the proxy.
Proxy Password Password for Basic Authentication challenges issued by the proxy.
Edges:
The following table lists the available line edges for the Web Service Client Service(com.ibi.agents.XDWSClientAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
fail_connect
fail_security
fail_parse
fail_timeout
cancelled
Standard SOAP fault
Available Services
502 Information Builders
Strip SOAP Envelope Parameter
The Strip SOAP Envelope parameter moves namespaces to the payload node when a SOAPresponse is received. For example, assume that the target web service returns the followingmessage to the service:
<?xml version="1.0" encoding="UTF-8" ?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:somens="http://somens.com"> <SOAP-ENV:Body> <somens:payload>Hello</somens:payload> </SOAP-ENV:Body></SOAP-ENV:Envelope>
If set to true, then the Strip SOAP Envelope parameter cuts the child of the <SOAP-ENV:Body>element, which in this example, is <somens:payload>. The result is not, by itself, a well-formed XML document because the xmlns attribute that declares the somens namespaceprefix is lost during the cut.
Enabling the Strip SOAP Envelope parameter causes the service to ascend the XML treelooking for namespace declarations and copies these attributes to the payload node. Forexample, after the SOAP envelope is removed, the response document has the followingstructure:
<somens:payload xmlns:somens="http://somens.com">Hello</somens:payload>
Web Service HTTP Client Service (com.ibi.agents.XDWSHttpClientAgent)
Syntax:
com.ibi.agents.XDWSHttpClientAgent
iIT Service Object:
misc: WS HTTP Client Agent
Description:
This service executes a web service through an HTTP Client provider and allows atransformation to be applied to the response document.
Parameters:
Parameter Description
End point * The location where the web service has been deployed.
1. iWay Services
iWay Service Manager Component Reference Guide 503
Parameter Description
SOAP Action Value of the SOAPAction header for HTTP.
Content-Type Value of the Content-Type MIME Header. The default value is:
text/xml
User ID User ID for Basic Authentication challenges.
Password Password for Basic Authentication challenges.
Timeout The timeout value in seconds. The default value is:
0
Header The header of the web service message. This value can be a filename, transform, or actual data with SREG, XPATH, and so on.
Body The body of the web service message. Can be a file name,transform, or actual data with SREG, XPath, and so on. Thedefault value is:
_flatof(false)
Fault Transform Transformation to apply when a web service fault occurs.
Strip SOAP Envelope If set to true, then the SOAP envelope from the responsedocument is removed. By default, this parameter is set to false.
For more information on the behavior and usage of thisparameter, see the description that follows this table.
Response Transform Transformation to apply for the web service response document.
HTTP Client Provider * The HTTP Client provider that manages connections for this webservice agent.
Edges:
Available Services
504 Information Builders
The following table lists the available line edges for the Web Service HTTP Client Service(com.ibi.agents.XDWSHttpClientAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_connect
fail_operation
fail_security
fail_parse
fail_timeout
cancelled
Standard SOAP fault
Strip SOAP Envelope Parameter
The Strip SOAP Envelope parameter moves namespaces to the payload node when a SOAPresponse is received. For example, assume that the target web service returns the followingmessage to the service:
<?xml version="1.0" encoding="UTF-8" ?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:somens="http://somens.com"> <SOAP-ENV:Body> <somens:payload>Hello</somens:payload> </SOAP-ENV:Body></SOAP-ENV:Envelope>
1. iWay Services
iWay Service Manager Component Reference Guide 505
If set to true, then the Strip SOAP Envelope parameter cuts the child of the <SOAP-ENV:Body>element, which in this example, is <somens:payload>. The result is not, by itself, a well-formed XML document because the xmlns attribute that declares the somens namespaceprefix is lost during the cut.
Enabling the Strip SOAP Envelope parameter causes the service to ascend the XML treelooking for namespace declarations and copies these attributes to the payload node. Forexample, after the SOAP envelope is removed, the response document has the followingstructure:
<somens:payload xmlns:somens="http://somens.com">Hello</somens:payload>
X12 Validation Service (com.ibi.agents.XDX12ValidationReportAgent)
Syntax:
com.ibi.agents.XDX12ValidationReportAgent
iIT Service Object:
EDI: X12 Validation Report Agent
Description:
This service produces a validation report (from the EDI rules validation) after validating anincoming EDI X12 message in XML format. This service is used in tandem with the XML to X12transformation service.
Edges:
The following table lists the available line edges for the X12 Validation Service(com.ibi.agents.XDX12ValidationReportAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
Available Services
506 Information Builders
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
XA Log Inquiry By Context Service (com.ibi.agents.XDXALogInquiryByContextAgent)
Syntax:
com.ibi.agents.XDXALogInquiryByContextAgent
iIT Service Object:
misc: XA Log Inquiry By Context Agent
Description:
This service queries the activity bus driver by date and context.
Parameters:
Parameter Description
Start Date * Report records after this date.
End Date * Report records before this date.
Max Rows * Maximum number of rows to return. A value of 0 means no limit.
Name of specialregister to match *
Queries the activity bus driver by date and context.
Max Rows Maximum number of rows to return. A value of 0 means no limit.
Edges:
1. iWay Services
iWay Service Manager Component Reference Guide 507
The following table lists the available line edges for the XA Log Inquiry By Context Service(com.ibi.agents.XDXALogInquiryByContextAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
XA Log Inquiry By Date Service (com.ibi.agents.XDXALogInquiryByDateAgent)
Syntax:
com.ibi.agents.XDXALogInquiryByDateAgent
iIT Service Object:
Description:
This service queries the activity bus driver by date.
Parameters:
Parameter Description
Start Date * Report records after this date.
End Date * Report records before this date.
Max Rows Maximum number of rows to return. A value of 0 means no limit.
Edges:
Available Services
508 Information Builders
The following table lists the available line edges for the XA Log Inquiry By Date Service(com.ibi.agents.XDXALogInquiryByDateAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
XA Log Inquiry By Partner Service (com.ibi.agents.XDXALogInquiryByPartnerAgent)
Syntax:
com.ibi.agents.XDXALogInquiryByPartnerAgent
iIT Service Object:
misc: XA Log Inquiry By Partner Agent
Description:
This service queries the activity bus driver by date and partners.
Parameters:
Parameter Description
Start Date * Report records after this date.
End Date * Report records before this date.
Partner From Partner where the message is coming from. Leave empty if not used.
Partner To Partner where the message is going.
1. iWay Services
iWay Service Manager Component Reference Guide 509
Parameter Description
Max Rows Maximum number of rows to return. A value of 0 means no limit.
Edges:
The following table lists the available line edges for the XA Log Inquiry By Partner Service(com.ibi.agents.XDXALogInquiryByPartnerAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
XA Log Inquiry By Transaction ID Service (com.ibi.agents.XDXALogInquiryByTIDAgent)
Syntax:
com.ibi.agents.XDXALogInquiryByTIDAgent
iIT Service Object:
misc: XA Log Inquiry By TID Agent
Description:
This service queries the activity bus driver by transaction ID.
Parameters:
Available Services
510 Information Builders
Parameter Description
Transaction ID * The transaction ID to match.
Record Type The specific record type to match. A value of 0 matches any recordtype.
Edges:
The following table lists the available line edges for the XA Log Inquiry By Transaction IDService (com.ibi.agents.XDXALogInquiryByTIDAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation
notfound
XA Log Message Service (com.ibi.agents.XDXALogMsg)
Syntax:
com.ibi.agents.XDXALogMsg
iIT Service Object:
operations: XALOG Message
xalog: XALOG Message
Description:
This XA Log Message service writes a message to the transaction activity log system.
1. iWay Services
iWay Service Manager Component Reference Guide 511
The message is handled by the activity log system accordingly for the installed driver. In iWayBusiness Activity Monitor (BAM), the message will appear in the transaction display.
Parameters:
Parameter Description
Message level Determines the type of message that will be written to the log at theselected trace level. Select one of the following message levels fromthe drop-down list:
Information (info)
Business Error (bizerr)
Debug (debug)
Checkpoint (checkpoint)
The available message levels are described in more detail following thistable.
Transactional If set to true, then this message is written only as part of a rollback ofthe process flow.
Message text The descriptive text of the message to be written in the transactionactivity log.
Include contents If set to true, then the contents of the current message (document) areincluded in the record. This parameter must be set to true forcheckpoints. The contents of the message are not carried when themessage is written as a transaction.
The following message levels relate to the type of message that is created and the currentstate of the server:
Information (info). This is an informational message. These messages are always writtento the transaction activity log, provided that information messages are not masked by thesystem.
Business Error (bizerr). This is an error message and cannot be masked. It should be usedonly to record business errors or situations that relate to the purposes of the application.This service supersedes other services that write business error messages, but performsthe same service.
Available Services
512 Information Builders
Debug (debug). These messages are written only if the process flow is running in debugmode. Under normal circumstances, the debug mode is not set, and this level causes nomessage to be written.
Checkpoint (checkpoint). A checkpoint message is used only for iWay BAM recovery. Itallows you to store the current contents of the document being processed for laterrecovery. Checkpoint messages require that the Include contents parameter is set to true.
The message contents include the entire state of the process flow document. This canconstitute a large amount of data, and would normally not be included for informational ordebugging messages.
Edges:
The edges returned by the XA Log Message Service (com.ibi.agents.XDXALogMsg) are listedand described in the following table.
Edge Description
success A message was issued or a debug message wasrequested and the channel was not in debug mode.
fail_parse The message contained iFL, which resulted in asyntax or execution error.
XAdES Digital Signature Create Service (com.ibi.agents.XDXAdESCreateAgent)
Syntax:
com.ibi.agents.XDXAdESCreateAgent
iIT Service Object:
format: XAdES Digital Signature Create
Description: Creates an XML Advanced Electronic Signature.
Parameters:
Parameter Description
XAdES Form * The signature form determines which signed and unsignedproperties are added to the signature.
1. iWay Services
iWay Service Manager Component Reference Guide 513
Parameter Description
Signature Method * The signature algorithm used to convert the canonicalizedSignedInfo into the SignatureValue.
SignatureCanonicalization Method*
The algorithm used to canonicalize the SignedInfo elementbefore it is digested as part of the signature operation.
Reference Digest Method*
The digest algorithm applied to the data object references toyield the DigestValue.
Reference Property DigestMethod
The digest algorithm applied to the qualifying properties thatcontain references to certificates, CRLs and so on.
Time StampCanonicalization Method
The algorithm used to canonicalize the qualifying properties,when needed by a time stamp.
Time Stamp DigestMethod
The digest algorithm applied to the qualifying properties thatcontain time stamps.
Message Digest JCEProvider
The JCE Provider for the MessageDigest service.
Signature Key
KeyStore Provider * The provider for the keystore containing the signature privatekey.
Signing Key Alias * The private key alias used to sign the SignedInfo.
Signing Key Password The password for the signing private key. If left blank, thepassword for accessing the keystore will be used.
Signature Location
XML Namespace Provider The provider for the mapping between the XML namespaceprefix and the namespace URI in XPath expressions. If leftblank, the XPath expression in the Signature Parent Elementcannot contain namespaces.
Available Services
514 Information Builders
Parameter Description
XPath Syntax Determines which syntax level of the XPath should be used.The default option selects the syntax level as set in theconsole global settings.
Create Parent Element Determines whether the signature parent element is created ifit is missing.
Signature Parent Element The path to the element where the signature will be inserted. Ifleft blank, the signature parent is the root element. If CreateParent Element is true, the expression must adhere toRestricted XPath syntax, otherwise the expression may adhereto the full syntax of the XPath engine selected by the XPathSyntax parameter.
Restricted XPath has the form /step1/step2/... where a stephas the form ns:elem[predicate] or a pair of consecutive stepsthat has the form *[1]/self::ns:elem[predicate] to indicate theelement must be the first child of its parent.
The namespace prefixes are optional, but if present they mustbe declared in the XML Namespace provider.
The predicate is optional, when present it has the form[@ns1:attr1='val1' and @ns2:attr2='val2' and ...].
If no element matches the Restricted XPath expression andCreate Parent Element is true, then the necessary elementsand attributes will be created so that the expression wouldmatch successfully.
KeyInfo
Include Signing Certificate Indicates whether the signing certificate should be included ina ds:X509Certificate element within ds:KeyInfo.
Include Public Key Indicates whether a ds:KeyValue element containing the publickey's value should be included in ds:KeyInfo.
Qualifying Properties
1. iWay Services
iWay Service Manager Component Reference Guide 515
Parameter Description
All Signed Data ObjectsCommitment
The commitment type that applies to all the signed dataobjects.
All Signed Data ObjectsCommitment Description
The text description for the commitment type that applies toall the signed data objects. A default English description willbe used if a standard commitment type is chosen and thisproperty is left blank.
All Signed Data ObjectsTime Stamp
Adds a time stamp computed before the signature production,over the sequence formed by ALL the Reference elementswithin the SignedInfo referencing whatever the signer wants tosign except the SignedProperties element.
Sign Signing Certificate Indicates whether the signature should cover theds:X509Certificate element containing the signing certificate.This is only considered if Include Signing Certificate isselected.
Signing Time Specifies the time at which the signer purportedly performedthe signing process. Leave blank to use the current time.
Signer Roles A newline separated list of the roles claimed by the signer.
TSA URL The location of the Time Stamp Authority used to create timestamps.
Signature Production Place
City The purported city where the signer was at the time ofsignature creation.
State Or Province The purported state or province where the signer was at thetime of signature creation.
Postal Code The purported postal code where the signer was at the time ofsignature creation.
Country The purported country where the signer was at the time ofsignature creation.
Signature Policy
Available Services
516 Information Builders
Parameter Description
Signature Policy Identifier An Object Identifier that uniquely identifies a specific versionof the signature policy. Leave this property blank to specify anImplied policy in XAdES-EPES form and above.
Signature PolicyDocument
The path to the file containing a copy of the Signature PolicyDocument. Leave this property blank to specify an Impliedpolicy in XAdES-EPES form and above.
Complete Form
TrustStore Provider The provider for the keystore containing the CertificateAuthorities. This property is required for XAdES-C forms andabove.
Certificate Store Providers A comma-separated list of Keystore, Directory CertStore, orLDAP providers for the certificate stores used to retrieverevocation material. This property is required for XAdES-Cforms and above.
Reference 1
Reference 1 URI The URI to the first piece of data that will be digested andsigned. If left blank, the whole XML document will be digestedand signed.
Reference 1 Transform 1 The first transform algorithm to apply to the first referencedata.
Reference 1 Transform 1Parameters
The parameters for the first transform algorithm to apply to thefirst reference data. For Exclusive Canonical XML, this is aspace-separated list of XML namespace prefixes. For XSLT,this is the name of a defined transform. For XPathFilter, this isan XPath expression.
Reference 1 Transform 1XML Namespace Provider
The provider for the XML Namespace Map for XPathFiltertransforms.
Reference 1 Transform 2 The second transform algorithm to apply to the first referencedata.
1. iWay Services
iWay Service Manager Component Reference Guide 517
Parameter Description
Reference 1 Transform 2Parameters
The parameters for the second transform algorithm to apply tothe first reference data. For Exclusive Canonical XML, this is aspace-separated list of XML namespace prefixes. For XSLT,this is the name of a defined transform. For XPathFilter, this isan XPath expression.
Reference 1 Transform 2XML Namespace Provider
The provider for the XML Namespace Map for XPathFiltertransforms.
Reference 1 MimeType The MimeType element of the DataObjectFormat. Indicateshow a human should interpret the signed data in the firstreference (text, sound, video, etc.)
Reference 1 Encoding The Encoding element of the DataObjectFormat. Indicates theencoding of the signed data in the first reference. Ignored ifMimeType is left blank.
Reference 1 Description The Description element of the DataObjectFormat. Holdstextual information related to the signed data in the firstreference. Ignored if MimeType is left blank.
Reference 1Documentation URI
A DocumentationReference sub-element of the ObjectIdentifierelement of the DataObjectFormat. Points to a document whereadditional information about the nature of the data object canbe found. Ignored if MimeType is left blank.
Reference 1 Identifier The Identifier sub-element of the ObjectIdentifier element ofthe DataObjectFormat. Contains a permanent identifier of thenature of the object. Ignored if MimeType is left blank.
Reference 1 Commitment The commitment type that applies to this signed data object.
Reference 1 CommitmentDescription
The text description for the commitment type that applies tothis signed data object. A default English description will beused if a standard commitment type is chosen and thisproperty is left blank.
Available Services
518 Information Builders
Parameter Description
Reference 1 Time Stamp Requests a time stamp to be computed before the signatureproduction, over a sequence formed by some of theds:Reference elements within the ds:SignedInfo referencingwhatever the signer wants to sign except the SignedPropertieselement.
Reference 2
Reference 2 URI The URI to the second piece of data that will be digested andsigned. If you need more references, create user parametersnamed ref[X]uri, ref[X]transform[Y], ref[X]transform[Y]parms,ref[X]transform[Y]nsmap, ref[X]formatmime, ref[X]formatenc,ref[X]formatdesc, ref[X]formatdocuri, ref[X]formatident,ref[X]commitment, ref[X]timestamp, where X >= 3, Y >= 1. Forexample, ref3transform2 is the second transform of the thirdreference.
Reference 2 Transform 1 The first transform algorithm to apply to the second referencedata.
Reference 2 Transform 1Parameters
The parameters for the first transform algorithm to apply to thesecond reference data. For Exclusive Canonical XML, this is aspace-separated list of XML namespace prefixes. For XSLT,this is the name of a defined transform. For XPathFilter, this isan XPath expression.
Reference 2 Transform 1XML Namespace Provider
The provider for the XML Namespace Map for XPathFiltertransforms.
Reference 2 Transform 2 The second transform algorithm to apply to the secondreference data.
Reference 2 Transform 2Parameters
The parameters for the second transform algorithm to apply tothe second reference data. For Exclusive Canonical XML, thisis a space-separated list of XML namespace prefixes. ForXSLT, this is the name of a defined transform. For XPathFilter,this is an XPath expression.
1. iWay Services
iWay Service Manager Component Reference Guide 519
Parameter Description
Reference 2 Transform 2XML Namespace Provider
The provider for the XML Namespace Map for XPathFiltertransforms.
Reference 2 MimeType The MimeType element of the DataObjectFormat. Indicateshow a human should interpret the signed data in the secondreference (text, sound, video, etc.)
Reference 2 Encoding The Encoding element of the DataObjectFormat. Indicates theencoding of the signed data in the second reference. Ignored ifMimeType is left blank.
Reference 2 Description The Description element of the DataObjectFormat. Holdstextual information related to the signed data in the secondreference.
Reference 2Documentation URI
A DocumentationReference sub-element of the ObjectIdentifierelement of the DataObjectFormat. Points to a document whereadditional information about the nature of the data object canbe found.
Reference 2 Identifier The Identifier sub-element of the ObjectIdentifier element ofthe DataObjectFormat. Contains a permanent identifier of thenature of the object.
Reference 2 Commitment The commitment type that applies to this signed data object.
Reference 2 CommitmentDescription
The text description for the commitment type that applies tothis signed data object. A default English description will beused if a standard commitment type is chosen and thisproperty is left blank.
Reference 2 Time Stamp Requests a time stamp to be computed before the signatureproduction, over a sequence formed by some of theds:Reference elements within the ds:SignedInfo referencingwhatever the signer wants to sign except the SignedPropertieselement.
Edges:
Available Services
520 Information Builders
The following table lists the available Line Edges for the XAdES Digital Signature Create Service(com.ibi.agents.XDXAdESCreateAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
XAdES Digital Signature Verify Service (com.ibi.agents.XDXAdESVerifyAgent)
Syntax:
com.ibi.agents.XDXAdESVerifyAgent
iIT Service Object:
format: XAdES Digital Signature Verify
Description: Verifies an XAdES XML Digital Signature.
Parameters:
Parameter Description
XML Namespace Provider The provider for the mapping between the XML namespaceprefix and the namespace URI. If left blank, the XPathexpression in the Signature Element Path and RequiredSignature Coverage parameters cannot contain namespaces.
XPath Syntax Determines which syntax level of the XPath should be used.The default option selects the syntax level as set in theconsole global settings.
1. iWay Services
iWay Service Manager Component Reference Guide 521
Parameter Description
Signature Element Path The path to the signature XML element. If left blank, the agentwill search throughout the document for an element namedSignature in the namespace http://www.w3.org/2000/09/xmldsig#.
Remove Security ParentElement
After successful verification, determines whether to removethe WSSE Security parent element and all of its contents.
Signature Criteria
TrustStore Provider * The provider for the keystore containing the CertificateAuthorities.
Certificate Store Providers A comma-separated list of Keystore, Directory CertStore, orLDAP providers for the certificate stores used to complete thecertificate chain and to retrieve revocation material.
Enable CertificateRevocation
Enables CRL checking of signer certificates.
Maximum Path Length The maximum number of non-self-issued intermediatecertificates that may exist in a certification path. The lastcertificate in a certification path is not included in this limit. 0implies that the path can only contain a single certificate. -1implies that there is no maximum. If any of the CA certificatescontain the BasicConstraintsExtension, the value of thepathLenConstraint field of the extension overrides theMaximum Path Length parameter.
Enforce KeyUsageExtension
Determines how the KeyUsage Extension is verified whenpresent in the signer certificate.
Message Digest JCEProvider
The JCE Provider for the MessageDigest service.
Required SignatureCoverage
An XPath expression that returns a NodeSet, where each nodein the set must have been signed by the Signature to beconsidered valid.
Available Services
522 Information Builders
Parameter Description
Unsigned Attachment The action to perform when a document contains an unsignedattachment.
XAdES Criteria
Minimum XAdES Form Specifies the minimum acceptable XAdES form. Signaturessimpler than this form will cause a validation failure.
Signature Policy Provider The name of a Signature Policy Provider. This specifies themapping from ObjectIdentifier (URI or OID) to the policy file.The policy file is needed to verify signatures with an explicitpolicy. If left blank, only absent or implied policies can bevalidated.
Accept Implied Policy Indicates whether the verifier should accept an impliedsignature policy.
Accept UnknownProperties
Indicates whether the verifier should accept unknownproperties. This only affects the unsigned properties.
Edges:
The following table lists the available Line Edges for the XAdES Digital Signature Verify Service(com.ibi.agents.XDXAdESVerifyAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
failed_unsigned Signature not found.
failed_verify Failed security validation.
1. iWay Services
iWay Service Manager Component Reference Guide 523
Line Edge Description
failed_coverage Signature failed coverage verification.
XDTwitterGetHomeTimeline Service (com.ibi.agents.XDTwitterGetHomeTimeline)
Syntax:
com.ibi.agents.XDTwitterGetHomeTimeline
iIT Service Object:
format: XDTwitterGetHomeTimeline
Description: Returns the recent statuses, including retweets, posted by the authenticatinguser and that user's friends.
Parameters:
Parameter Description
Page * Specifies the page of results to retrieve.
Count * Specifies the number of records to retrieve. Must be less thanor equal to 200.
Since Id * Returns results with an ID greater than (that is, more recentthan) the specified ID.
Max Id * Returns results with under an Max ID.
Consumer Key * Is your Twitter Application Consumer Key. If you don't havethis information, please go to http://dev.twitter.com. Sign inwith your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Available Services
524 Information Builders
Parameter Description
Consumer Secret * Is your Twitter Application Consumer Secret. If you don't havethis information, please go to http://dev.twitter.com. Sign inwith your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Access Token * Is your Twitter Application Access Token. If you don't have thisinformation, please go to http://dev.twitter.com. Sign in withyour Twitter account, Choose My Applications and click Createa New Application then follow the prompts to get ConsumerKey, Consumer Secret, Access Token, and Access TokenSecret.
Access Token Secret * Is your Twitter Application Access Token Secret. If you don'thave this information, please go to http://dev.twitter.com. Signin with your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Enabled * If on, emit through the proxy server.
Host The HTTP proxy server host name.
Port The HTTP proxy server port.
User The HTTP proxy server user name.
Password The HTTP proxy server password.
Connection Timeout The HTTP connection timeout in milliseconds.
Read Timeout The HTTP read timeout in milliseconds.
Streaming Read Timeout The streaming API's HTTP Read timeout in milliseconds.
Retry Count The number of HTTP retries.
Retry Interval * The HTTP retry interval in seconds.
1. iWay Services
iWay Service Manager Component Reference Guide 525
Parameter Description
Pretty Debug Prettifies JSON debug output if set to true.
Stream Base URL The streaming API base URL.
Site Stream Base URL The Site Streams API base URL.
Edges:
The following table lists the available Line Edges for the XDTwitterGetHomeTimeline Service(com.ibi.agents.XDTwitterGetHomeTimeline).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
onFailConnect Could not connect to Twitter.
onFailParse Could not parse a document.
OnFailTwitterException Twitter threw an exception.
OnFailTwitterOperation Could not perform the Twitter operationrequested.
XDTwitterUpdateStatus Service (com.ibi.agents.XDTwitterUpdateStatus)
Syntax:
com.ibi.agents.XDTwitterUpdateStatus
iIT Service Object:
format: XDTwitterUpdateStatus
Description: Updates the authenticating user current status, also known as Tweeting. Theupdate text is compared with the authenticating user's recent Tweets. Any attempt that wouldresult in duplication will be blocked. A user cannot submit the same status twice in a row.
Parameters:
Available Services
526 Information Builders
Parameter Description
Tweet/Status * The text of your tweet/status update.
In Reply To The ID of an existing status that the update is in reply to. Thisparameter will be ignored unless the author of the Tweet thisparameter references is mentioned within the status text.Therefore, you must include username, where username is theauthor of the referenced Tweet, within the update.
Image Sends a Tweet with an image. This version only supports threetype image files: jpg, gif, and png.
Consumer Key * Is your Twitter Application Consumer Key. If you don't havethis information, please go to http://dev.twitter.com. Sign inwith your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Consumer Secret * Is your Twitter Application Consumer Secret. If you don't havethis information, please go to http://dev.twitter.com. Sign inwith your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
Access Token * Is your Twitter Application Access Token. If you don't have thisinformation, please go to http://dev.twitter.com. Sign in withyour Twitter account, Choose My Applications and click Createa New Application then follow the prompts to get ConsumerKey, Consumer Secret, Access Token, and Access TokenSecret.
Access Token Secret * Is your Twitter Application Access Token Secret. If you don'thave this information, please go to http://dev.twitter.com. Signin with your Twitter account, Choose My Applications and clickCreate a New Application then follow the prompts to getConsumer Key, Consumer Secret, Access Token, and AccessToken Secret.
1. iWay Services
iWay Service Manager Component Reference Guide 527
Parameter Description
Enabled * If on, emit through the proxy server.
Host The HTTP proxy server host name.
Port The HTTP proxy server port.
User The HTTP proxy server user name.
Password The HTTP proxy server password.
Connection Timeout The HTTP connection timeout in milliseconds.
Read Timeout The HTTP read timeout in milliseconds.
Streaming Read Timeout The streaming API's HTTP Read timeout in milliseconds.
Retry Count The number of HTTP retries.
Retry Interval * The HTTP retry interval in seconds.
Pretty Debug Prettifies JSON debug output if set to true.
Stream Base URL The streaming API base URL.
Site Stream Base URL The Site Streams API base URL.
Coordinates
Latitude The latitude of the location this Tweet refers to. Thisparameter will be ignored unless it is inside the range -90.0 to+90.0 inclusive (north is positive). It will also be ignored ifthere is no corresponding long parameter.
Longitude The longitude of the location this Tweet refers to. The validranges for longitude are -180.0 to +180.0 inclusive (east ispositive). This parameter will be ignored if outside that range,if it is not a number, if geo_enabled is disabled, or if there nocorresponding lat parameter.
Place
Place Id The ID of the place in the world.
Available Services
528 Information Builders
Edges:
The following table lists the available Line Edges for the XDTwitterUpdateStatus Service(com.ibi.agents.XDTwitterUpdateStatus).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
onFailConnect Could not connect to Twitter.
onFailParse Could not parse a document.
OnFailTwitterException Twitter threw an exception.
OnFailTwitterOperation Could not perform the Twitter operationrequested.
xCal and iCalendar Conversion Service (com.ibi.agents.XDXCalAgent)
Syntax:
com.ibi.agents.XDXCalAgent
iIT Service Object:
format: Converts between iCalendar and xCal
Description:
This service converts iCalendar to xCal and vice-versa. iCalendar is a format specification forthe exchange of calendaring and scheduling data. A common example is an email messagecontaining an iCalendar attachment for a meeting request. iCalendar is defined in the RFC5545 specification. xCal is the XML format for iCalendar, and is defined in the RFC 6321specification.
xCal is designed to support the round trip from iCalendar to xCal back into iCalendar withoutlosing semantic information. This allows the application query to update the information in themore convenient XML format, with no loss of information.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 529
Parameter Description
Operation Determines which of the following conversions should be performed:
iCalendar to xCal
xCal to iCalendar
Edges:
The following table lists the available line edges for the xCal and iCalendar Conversion Service(com.ibi.agents.XDXCalAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse: an iFL expression could not be evaluated.
fail_operation: the operation could not be completedsuccessfully.
This service requires iCalendar input to be stored as bytes or lines, directly within the inputdocument. As a result, you may require the execution of the Attachment to Document service(com.ibi.agents.XDAttachmentToDocAgent) or the SMIME Unpacker service(com.ibi.agents.XDSMIMEUnpackerAgent) on your input.
xCal input must be stored as parsed XML format within the input document. This servicestores iCalendar output as lines, and xCal output as parsed XML within the output document.
An iCalendar stream is composed of one or more VCALENDAR components. In xCal, this isrepresented by an <icalendar> element containing one or more <vcalendar> elements.iCalendar is mostly case-insensitive, but xCal requires lower-case formatting. For example:
Available Services
530 Information Builders
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0"> <vcalendar>
</vcalendar></icalendar>
Each component consists of optional properties and optional sub-components. A sub-component has the same structure as a component. In xCal, a component maps to an elementof the same name. When present, the properties are grouped within the <properties> element.Similarly, when present, the sub-components are grouped within the <components> element.The <properties> and <components> elements are omitted when empty. For example:
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0"> <vcalendar> <properties>
</properties> <components>
</components> </vcalendar></icalendar>
A property has optional parameters and a value. In xCal, a property maps to an element of thesame name. When present, the parameters are grouped within the <parameters> element. The<parameters> element is omitted when empty.
A parameter is a name-value pair. A parameter is converted to an element of the same name.
In general, a property value becomes an element that is named based on the value type, withthe textual value as contents. This approach is used because many properties accept valuesof multiple types. For some specific structured types, the value is converted to named sub-elements instead. A parameter value is treated similarly, but it is always textual.
The following is an example of the tzid parameter within the dtstart property.
<properties> <dtstart> <parameters> <tzid><text>US/Eastern</text></tzid> </parameters> <date-time>2006-01-02T12:00:00</date-time> </dtstart></properties>
1. iWay Services
iWay Service Manager Component Reference Guide 531
iCalendar defines a folding algorithm to limit the line length to under 75 octets. It also definesan escape mechanism for some characters. This service automatically unfolds and unescapeswhen parsing iCalendar input. Conversely, this service automatically folds and escapes whengenerating iCalendar output.
Example 1
This example shows how a calendar request can be converted to xCal. These instructionsdescribe how to configure a process flow to handle iCalendar attachments in an emailmessage.
Richard Smith is organizing a meeting with John Doe and Jane Roe. It is scheduled for March4, 2014 and runs weekly for another 5 weeks. He used a calendar application to send thiscalendar request to the attendees. The multipart/alternative message, is composed of twoparts:
A text or plain description.
A text or calendar part.
From: "Smith, Richard" <[email protected]>To: "Doe, John" <[email protected]>, "Roe, Jane" <[email protected]>Date: Mon, 3 Mar 2014 16:59:17 -0500Subject: group meetingContent-Type: multipart/alternative; boundary="_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_"MIME-Version: 1.0Return-Path: [email protected]_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_Content-Type: text/plain; charset="utf-8"Content-Transfer-Encoding: base64
Available Services
532 Information Builders
V2hlbjogT2NjdXJzIGV2ZXJ5IFR1ZXNkYXkgZnJvbSAxMDowMCBBTSB0byAxMTowMCBBTSBlZmZlY3RpdmUgMy80LzIwMTQgdW50aWwgNC8xLzIwMTQuIFRoZXJlIGFyZSA1IG1vcmUgb2NjdXJyZW5jZXMuIChHTVQtMDU6MDApIEVhc3Rlcm4gVGltZSAoVVMgJiBDYW5hZGEpDQpXaGVyZTogbGFyZ2UgY29uZmVyZW5jZSByb29tDQoNCip+Kn4qfip+Kn4qfip+Kn4qfioNCg==--_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_Content-Type: text/calendar; charset="utf-8"; method=REQUESTContent-Transfer-Encoding: base64QkVHSU46VkNBTEVOREFSDQpNRVRIT0Q6UkVRVUVTVA0KUFJPRElEOk1pY3Jvc29mdCBFeGNoYW5nZSBTZXJ2ZXIgMjAwNw0KVkVSU0lPTjoyLjANCkJFR0lOOlZUSU1FWk9ORQ0KVFpJRDpFYXN0ZXJuIFN0YW5kYXJkIFRpbWUNCkJFR0lOOlNUQU5EQVJEDQpEVFNUQVJUOjE2MDEwMTAxVDAyMDAwM
A0KVFpPRkZTRVRGUk9NOi0wNDAwDQpUWk9GRlNFVFRPOi0wNTAwDQpSUlVMRTpGUkVRPVlFQVJMWTtJTlRFUlZBTD0xO0JZREFZPTFTVTtCWU1PTlRIPTExDQpFTkQ6U1RBTkRBUkQNCkJFR0lOOkRBWUxJR0hUDQpEVFNUQVJUOjE2MDEwMTAxVDAyMDAwMA0KVFpPRkZTRVRGUk9NOi0wNTAwDQpUWk9GRlNFVFRPOi0wNDAwDQpSUlVMRTpGUkVRPVlFQVJMWTtJTlRFUlZBTD0xO0JZREFZPTJTVTtCWU1PTlRIPTMNCkVORDpEQVlMSUdIVA0KRU5EOlZUSU1FWk9ORQ0KQkVHSU46VkVWRU5UDQpPUkdBTklaRVI7Q049IlNtaXRoLCBSaWNoYXJkIjpNQUlMVE86UmljaGFyZF9TbWl0aEBpYmkuY29tDQpBVFRFTkRFRTtST0xFPVJFUS1QQVJUSUNJUEFOVDtQQVJUU1RBVD1ORUVEUy1BQ1RJT047UlNWUD1UUlVFO0NOPSJEb2UsIEpvaG4NCiAiOk1BSUxUTzpKb2huX0RvZUBpYmkuY29tDQpBVFRFTkRFRTtST0xFPVJFUS1QQVJUSUNJUEFOVDtQQVJUU1RBVD1ORUVEUy1BQ1RJT047UlNWUD1UUlVFO0NOPSJSb2UsIEphbmUNCiAiOk1BSUxUTzpKYW5lX1JvZUBpYmkuY29tDQpERVNDUklQVElPTjtMQU5HVUFHRT1lbi1VUzpXaGVuOiBPY2N1cnMgZXZlcnkgVHVlc2RheSBmcm9tIDEwOjAwIEFNIHRvIDExOjANCiAwIEFN
IGVmZmVjdGl2ZSAzLzQvMjAxNCB1bnRpbCA0LzEvMjAxNC4gVGhlcmUgYXJlIDUgbW9yZSBvY2N1cnJlbmNlcy4gKEdNVA0KIC0wNTowMCkgRWFzdGVybiBUaW1lIChVUyAmIENhbmFkYSlcbldoZXJlOiBsYXJnZSBjb25mZXJlbmNlIHJvb21cblxuKn4qfip+DQogKn4qfip+Kn4qfip+KlxuDQpSUlVMRTpGUkVRPVdFRUtMWTtDT1VOVD01O0lOVEVSVkFMPTE7QllEQVk9VFU7V0tTVD1TVQ0KU1VNTUFSWTtMQU5HVUFHRT1lbi1VUzpncm91cCBtZWV0aW5nDQpEVFNUQVJUO1RaSUQ9RWFzdGVybiBTdGFuZGFyZCBUaW1lOjIwMTQwMzA0VDEwMDAwMA0KRFRFTkQ7VFpJRD1FYXN0ZXJuIFN0YW5kYXJkIFRpbWU6MjAxNDAzMDRUMTEwMDAwDQpVSUQ6MDQwMDAwMDA4MjAwRTAwMDc0QzVCNzEwMUE4MkUwMDgwMDAwMDAwMDM2RDU1NkQyMkIzN0NGMDEwMDAwMDAwMDAwMDAwMDANCiAwMTAwMDAwMDAyMEFGO
DMwMjVEMjA1RDQ4QjY3OTNCMzhBNzFGQ0JCQg0KQ0xBU1M6UFVCTElDDQpQUklPUklUWTo1DQpEVFNUQU1QOjIwMTQwMzAzVDIxNTkxNloNClRSQU5TUDpPUEFRVUUNClNUQVRVUzpDT05GSVJNRUQNClNFUVVFTkNFOjANCkxPQ0FUSU9OO0xBTkdVQUdFPWVuLVVTOmxhcmdlIGNvbmZlcmVuY2Ugcm9vbQ0KWC1NSUNST1NPRlQtQ0RPLUFQUFQtU0VRVUVOQ0U6MA0KWC1NSUNST1NPRlQtQ0RPLU9XTkVSQVBQVElEOjIxMTIwMzUzODINClgtTUlDUk9TT0ZULUNETy1CVVNZU1RBVFVTOlRFTlRBVElWRQ0KWC1NSUNST1NPRlQtQ0RPLUlOVEVOREVEU1RBVFVTOkJVU1kNClgtTUlDUk9TT0ZULUNETy1BTExEQVlFVkVOVDpGQUxTRQ0KWC1NSUNST1NPRlQtQ0RPLUlNUE9SVEFOQ0U6MQ0KWC1NSUNST1NPRlQtQ0RPLUlOU1RUWVBFOjENCkJFR0lOOlZBTEFSTQ0KQUNUSU9OOkRJU1BMQVkNCkRFU0NSSVBUSU9OOlJFTUlOREVSDQpUUklHR0VSO1JFTEFURUQ9U1RBUlQ6LVBUMTVNDQpFTkQ6VkFMQVJNDQpFTkQ6VkVWRU5UDQpFTkQ6VkNBTEVOREFSDQo=--_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_--
The email listener (com.ibi.edaqm.XDPop3Master) reads this email message and stores themain body part in the document. The base64 data is automatically decoded. The listener isconfigured to keep the document in flat format because it is not XML. The calendar part is notshown in this example because it is stored as an attachment in the document.
1. iWay Services
iWay Service Manager Component Reference Guide 533
When: Occurs every Tuesday from 10:00 AM to 11:00 AM effective 3/4/2014 until 4/1/2014. There are 5 more occurrences. (GMT-05:00) Eastern Time (US & Canada)Where: large conference room*~*~*~*~*~*~*~*~*~*
The document attachments are processed one at a time with the help of the AttachmentIterator (com.ibi.agents.XDIterAttachments). The following table lists the parameter values thatare used.
Parameter Value
Start Index 0
Header Namespace attns
Keep Document Flat true
If the application knows there will always be one attachment and it will always be an iCalendarattachment, then it can extract it with the Attachment to Document service(com.ibi.agents.XDAttachmentToDocAgent) instead.
The base64 data is automatically decoded. For the first and only attachment, the result is aniCalendar request stored as bytes in the current document.
BEGIN:VCALENDARMETHOD:REQUESTPRODID:Microsoft Exchange Server 2007VERSION:2.0BEGIN:VTIMEZONETZID:Eastern Standard TimeBEGIN:STANDARDDTSTART:16010101T020000TZOFFSETFROM:-0400TZOFFSETTO:-0500RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=1SU;BYMONTH=11END:STANDARDBEGIN:DAYLIGHTDTSTART:16010101T020000TZOFFSETFROM:-0500TZOFFSETTO:-0400RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=2SU;BYMONTH=3END:DAYLIGHTEND:VTIMEZONEBEGIN:VEVENTORGANIZER;CN="Smith, Richard":MAILTO:[email protected];ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN="Doe, John
Available Services
534 Information Builders
":MAILTO:[email protected];ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN="Roe, Jane ":MAILTO:[email protected];LANGUAGE=en-US:When: Occurs every Tuesday from 10:00 AM to 11:0 0 AM effective 3/4/2014 until 4/1/2014. There are 5 more occurrences. (GMT -05:00) Eastern Time (US & Canada)\nWhere: large conference room\n\n*~*~*~ *~*~*~*~*~*~*\nRRULE:FREQ=WEEKLY;COUNT=5;INTERVAL=1;BYDAY=TU;WKST=SUSUMMARY;LANGUAGE=en-US:group meetingDTSTART;TZID=Eastern Standard Time:20140304T100000DTEND;TZID=Eastern Standard Time:20140304T110000UID:040000008200E00074C5B7101A82E0080000000036D556D22B37CF01000000000000000 01000000020AF83025D205D48B6793B38A71FCBBBCLASS:PUBLICPRIORITY:5DTSTAMP:20140303T215916ZTRANSP:OPAQUESTATUS:CONFIRMEDSEQUENCE:0LOCATION;LANGUAGE=en-US:large conference room X-MICROSOFT-CDO-APPT-SEQUENCE:0X-MICROSOFT-CDO-OWNERAPPTID:2112035382X-MICROSOFT-CDO-BUSYSTATUS:TENTATIVEX-MICROSOFT-CDO-INTENDEDSTATUS:BUSYX-MICROSOFT-CDO-ALLDAYEVENT:FALSEX-MICROSOFT-CDO-IMPORTANCE:1X-MICROSOFT-CDO-INSTTYPE:1BEGIN:VALARMACTION:DISPLAYDESCRIPTION:REMINDERTRIGGER;RELATED=START:-PT15MEND:VALARMEND:VEVENTEND:VCALENDAR
The xCal and iCalendar service can convert this data into XML format for easier processing.
Since the attachment can be any type, a Switch object is required to check the Content-Type.The expression defined for the Switch object can be:
_lcase(_token(_sreg("attns.Content-Type"), ";"))
Notice the register namespace attns is the Header Namespace configured on the AttachmentIterator. The _token() function is just a convenient way to extract the MIME type without anyparameters. The _lcase() function is needed to convert to lowercase format because MIMEtypes are case-insensitive. For example, the following expression returns text/calendar for thisContent-Type:
Content-Type: text/calendar; charset="utf-8"; method=REQUEST
1. iWay Services
iWay Service Manager Component Reference Guide 535
The value of the Switch expression becomes the outgoing edge name.The Switch object isbound to the xCal and iCalendar service by an OnCustom edge called text/calendar.TheOnDefault edge of the Switch object should also be bound to other services to handleattachments of other types.
The Operation parameter of the xCal and iCalendar service is set to iCalendar to xCal.Theoutput is a parsed XML tree in the current document (indented for display purposes only):
<?xml version="1.0" encoding="ISO-8859-1" ?><icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0"> <vcalendar> <properties> <method> <text>REQUEST</text> </method> <prodid> <text>Microsoft Exchange Server 2007</text> </prodid> <version> <text>2.0</text> </version> </properties>
<components> <vtimezone> <properties> <tzid> <text>Eastern Standard Time</text> </tzid> </properties> <components> <standard> <properties> <dtstart> <date-time>1601-01-01T02:00:00</date-time> </dtstart> <tzoffsetfrom> <utc-offset>-04:00</utc-offset> </tzoffsetfrom> <tzoffsetto> <utc-offset>-05:00</utc-offset> </tzoffsetto> <rrule> <recur> <freq>YEARLY</freq> <interval>1</interval> <byday>1SU</byday> <bymonth>11</bymonth> </recur> </rrule> </properties> </standard>
Available Services
536 Information Builders
<daylight> <properties> <dtstart> <date-time>1601-01-01T02:00:00</date-time> </dtstart> <tzoffsetfrom> <utc-offset>-05:00</utc-offset> </tzoffsetfrom> <tzoffsetto> <utc-offset>-04:00</utc-offset> </tzoffsetto> <rrule> <recur> <freq>YEARLY</freq> <interval>1</interval> <byday>2SU</byday> <bymonth>3</bymonth> </recur> </rrule> </properties> </daylight> </components> </vtimezone> <vevent>
<properties> <organizer> <parameters> <cn> <text>Smith, Richard</text> </cn> </parameters> <cal-address>MAILTO:[email protected]</cal-address> </organizer> <attendee> <parameters> <role> <text>REQ-PARTICIPANT</text> </role> <partstat> <text>NEEDS-ACTION</text> </partstat> <rsvp> <boolean>true</boolean> </rsvp> <cn> <text>Doe, John</text> </cn> </parameters>
1. iWay Services
iWay Service Manager Component Reference Guide 537
<cal-address>MAILTO:[email protected]</cal-address> </attendee> <attendee> <parameters> <role> <text>REQ-PARTICIPANT</text> </role> <partstat> <text>NEEDS-ACTION</text> </partstat> <rsvp> <boolean>true</boolean> </rsvp> <cn> <text>Roe, Jane</text> </cn> </parameters>
<cal-address>MAILTO:[email protected]</cal-address> </attendee> <description> <parameters> <language> <text>en-US</text> </language> </parameters> <text>When: Occurs every Tuesday from 10:00 AM to 11:00 AM effective 3/4/2014 until 4/1/2014. There are 5 more occurrences. (GMT-05:00) Eastern Time (US & Canada)Where: large conference room*~*~*~*~*~*~*~*~*~* </text> </description> <rrule> <recur> <freq>WEEKLY</freq> <count>5</count> <interval>1</interval> <byday>TU</byday> <wkst>SU</wkst> </recur> </rrule> <summary> <parameters> <language> <text>en-US</text> </language> </parameters> <text>group meeting</text> </summary>
Available Services
538 Information Builders
<dtstart> <parameters> <tzid> <text>Eastern Standard Time</text> </tzid> </parameters> <date-time>2014-03-04T10:00:00</date-time> </dtstart> <dtend> <parameters> <tzid> <text>Eastern Standard Time</text> </tzid> </parameters> <date-time>2014-03-04T11:00:00</date-time> </dtend> <uid> <text>040000008200E00074C5B7101A82E0080000000036D556D22B37CF0100000000000000001000000020AF83025D205D48B6793B38A71FCBBB</text> </uid> <class> <text>PUBLIC</text> </class> <priority> <integer>5</integer> </priority> <dtstamp> <date-time>2014-03-03T21:59:16Z</date-time> </dtstamp> <transp> <text>OPAQUE</text> </transp> <status> <text>CONFIRMED</text> </status> <sequence> <integer>0</integer> </sequence> <location> <parameters> <language> <text>en-US</text> </language> </parameters> <text>large conference room</text> </location>
1. iWay Services
iWay Service Manager Component Reference Guide 539
<x-microsoft-cdo-appt-sequence> <unknown>0</unknown> </x-microsoft-cdo-appt-sequence> <x-microsoft-cdo-ownerapptid> <unknown>2112035382</unknown> </x-microsoft-cdo-ownerapptid> <x-microsoft-cdo-busystatus> <unknown>TENTATIVE</unknown> </x-microsoft-cdo-busystatus> <x-microsoft-cdo-intendedstatus> <unknown>BUSY</unknown> </x-microsoft-cdo-intendedstatus> <x-microsoft-cdo-alldayevent> <unknown>FALSE</unknown> </x-microsoft-cdo-alldayevent> <x-microsoft-cdo-importance> <unknown>1</unknown> </x-microsoft-cdo-importance> <x-microsoft-cdo-insttype> <unknown>1</unknown> </x-microsoft-cdo-insttype> </properties> <components> <valarm> <properties> <action> <text>DISPLAY</text> </action> <description> <text>REMINDER</text> </description> <trigger> <parameters> <related> <text>START</text> </related> </parameters> <duration>-PT15M</duration> </trigger> </properties> </valarm> </components> </vevent> </components> </vcalendar></icalendar>
This document can be processed by more services (agents) according to the applicationrequirements.
The various processing paths within the Attachment iterator loop must converge into a singleJunction object. The loop edge points from the junction back to the iterator.
Available Services
540 Information Builders
Example 2
This example explains how to read an iCalendar request from an email message stored in afile.
The email and HTTP listeners can automatically parse the multipart/alternative messagebecause their underlying protocol requires the presence of headers. This step must also beadded explicitly to the process flow of a File listener.
The File listener is configured to keep the document flat.
The first object of the process flow should be the S/MIME Unpacker service. This object canhandle complex cryptographic messages, but also simple MIME messages like the multipart/alternative message in Example 1. The S/MIME KeyStore and S/MIME TrustStore providersare not used to parse simple MIME messages, but they must still be configured to satisfy theparameters that are required by the service. Any keystore provider is sufficient.
The Keep Message Flat parameter of the S/MIME Unpacker service must be set to false. Thisis required to parse the multipart message into the main body and its attachments. In thesample input message, the Content-Type of the main body is text/plain, therefore the servicewill not attempt to parse it as XML.
The remaining portions of the process flow can be configured as described in Example 1.
XML Decryption Service (com.ibi.agents.XDXMLDecryptionAgent)
Syntax:
com.ibi.agents.XDXMLDecryptionAgent
iIT Service Object:
format: XML Decryption
Description: Decrypts data with the rules of XML Encryption.
Parameters:
Parameter Description
XML Namespace Provider The provider for the mapping between the XML namespaceprefix and the namespace URI. If left blank, the XPathexpression in the Processed Elements property and theattribute declarations in the ID Attributes property cannotcontain namespaces.
1. iWay Services
iWay Service Manager Component Reference Guide 541
Parameter Description
XPath Syntax Determines which syntax level of the XPath should be used.The default option selects the syntax level as set in theconsole global settings.
Processed Elements The XPath expression returning the elements to be processed.The result must be a node set consisting of independentEncryptedData, EncryptedKey, and/or ReferenceList elements.If left blank, the agent will search throughout the document forall elements named EncryptedData in the namespace http://www.w3.org/2001/04/xmlenc#.
Remove ProcessedElements
Determines whether the processed elements are removedfrom the document after being processed. EncryptedDataelements are always replaced. EncryptedKey andReferenceList elements are removed only when this property istrue.
ID Attributes A space-separated list of attributes that are considered typeID. The value of an ID attribute can be used in a same-document reference with a URI of the form #idvalue.
Each attribute declaration has the form ns:*/@ns1:attrib or@ns1:attrib where ns: and ns1: are optional. If used, the nsand ns1 prefixes must be declared in the XML NamespaceProvider.
The form @ns1:attrib means an Attribute named attrib in XMLNamespace ns1. The form ns:*/@ns1:attrib is similar exceptthe attribute must also appear on an element of any name inthe XML Namespace ns. The default value is xml:id ds:*/@Idxenc:*/@Id wsu:Id.
JCE Provider The JCE provider that supplies the cryptographic needs.
KeyStore Provider * The provider for the keystore containing the key encryptionkey.
Available Services
542 Information Builders
Parameter Description
Key Encryption Key Alias The alias for keystore entry holding the key that will be used todecrypt the symmetric key. When left empty, the KeyEncryption Key is resolved based on the information in theKeyInfo element.
Key Encryption KeyPassword
The password for the keystore entry holding the key that willbe used to decrypt the symmetric key. If left blank, thepassword for accessing the keystore will be used.
Enforce KeyUsageExtension
If on, verify certificates used for encryption allow thekeyEncipherment KeyUsage extension.
Edges:
The following table lists the available Line Edges for the XML Decryption Service(com.ibi.agents.XDXMLDecryptionAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
XML Digital Signature Create Service (com.ibi.agents.XDXMLDSigCreateAgent)
Syntax:
com.ibi.agents.XDXMLDSigCreateAgent
iIT Service Object:
security: XML Output Signature Create
Description:
This service is used to generate an XML Digital Signature.
1. iWay Services
iWay Service Manager Component Reference Guide 543
For more information about the XML Digital Signature Create service, see the iWay ServiceManager Security Guide.
XML Digital Signature Verify Service (com.ibi.agents.XDXMLDSigVerifyAgent)
Syntax:
com.ibi.agents.XDXMLDSigVerifyAgent
iIT Service Object:
security: XML Output Signature Verify
Description:
This service is used to validate an XML Digital Signature.
For more information about the XML Digital Signature Verify service, see the iWay ServiceManager Security Guide.
XML Encryption Service (com.ibi.agents.XDXMLEncryptionAgent)
Syntax:
com.ibi.agents.XDXMLEncryptionAgent
iIT Service Object:
format: XML Encryption
Description: Encrypts data with the rules of XML Encryption.
Parameters:
Parameter Description
Encryption Algorithm * Describes how the data will be encrypted by the generatedsymmetric key.
JCE Provider The JCE provider that supplies the cryptographic needs.
XML Namespace Provider The provider for the mapping between the XML namespaceprefix and the namespace URI. If left blank, XPath expressionsin the Encrypted Data and EncryptedKey Parent propertiescannot contain namespaces.
Available Services
544 Information Builders
Parameter Description
XPath Syntax Determines which syntax level of the XPath should be used.The default option selects the syntax level as set in theconsole global settings.
Encrypted Data * An XPath expression that returns a nodeset containing theelements to be encrypted.
Encryption Type When encrypting an Element, determines whether the wholeelement or just the Element content is encrypted.
Minimum Count The minimum number of elements to encrypt. This must be anon-negative integer.
Manifest
Create EncryptedKeyParent
Determines whether the parent element of the EncryptedKey iscreated if it is missing. Ignored if the EncryptedKey isembedded in the EncryptedData.
1. iWay Services
iWay Service Manager Component Reference Guide 545
Parameter Description
EncryptedKey ParentElement
The path to the element where the independent EncryptedKeywill be inserted.
If left blank, the EncryptedKey is embedded in theEncryptedData.
If Create EncryptedKey Parent is true, the expression mustadhere to Restricted XPath syntax, otherwise the expressionmay adhere to the full syntax of the XPath engine selected bythe XPath Syntax parameter.
Restricted XPath has the form /step1/step2/... where a stephas the form ns:elem[predicate] or a pair of consecutive stepsthat has the form *[1]/self::ns:elem[predicate] to indicate theelement must be the first child of its parent.
The namespace prefixes are optional, but if present they mustbe declared in the XML Namespace provider. The predicate isoptional, when present it has the form [@ns1:attr1='val1' and@ns2:attr2='val2' and ...].
If no element matches the Restricted XPath expression andCreate EncryptedKey Parent is true, then the necessaryelements and attributes will be created such that theexpression would match successfully.
Create ReferenceListParent
Determines whether the parent element of ReferenceList iscreated if it is missing. Ignored if the ReferenceList isembedded in the EncryptedKey.
Available Services
546 Information Builders
Parameter Description
ReferenceList ParentElement
The path to the element where the independent ReferenceListwill be inserted.
If left blank, the ReferenceList is embedded in theindependent EncryptedKey if applicable.
If Create EncryptedKey Parent is true, the expression mustadhere to Restricted XPath syntax, otherwise the expressionmay adhere to the full syntax of the XPath engine selected bythe XPath Syntax parameter.
Restricted XPath has the form /step1/step2/... where a stephas the form ns:elem[predicate] or a pair of consecutive stepsthat has the form *[1]/self::ns:elem[predicate] to indicate theelement must be the first child of its parent.
The namespace prefixes are optional, but if present they mustbe declared in the XML Namespace provider. The predicate isoptional, when present it has the form [@ns1:attr1='val1' and@ns2:attr2='val2' and ...].
If no element matches the Restricted XPath expression andCreate ReferenceList Parent is true, then the necessaryelements and attributes will be created such that theexpression would match successfully.
Id Prefix A numeric suffix will be added to this prefix to create the Idattribute. The Id attribute is created only when the element isreferenced by another element.
Key Wrap
Key Wrap Algorithm * Describes how the symmetric key will be encrypted
KeyStore Provider * The provider for the keystore containing the key encryptionkey.
Key Encryption Key Alias*
The alias for keystore entry holding the key that will be used toencrypt the symmetric key.
1. iWay Services
iWay Service Manager Component Reference Guide 547
Parameter Description
Key Encryption KeyPassword
The password for the keystore entry holding the key that willbe used to encrypt the symmetric key. A trusted certificateentry does not need a password. If left blank, the password foraccessing the keystore will be used to access a private keyentry or a symmetric key entry.
Enforce KeyUsageExtension
If on, verify certificates used for encryption allow thekeyEncipherment KeyUsage extension.
KeyInfo
Include Issuer Serial Determines whether the X509IssuerSerial element is includedin the KeyInfo X509Data element when the Key Encryption Keyto describe came from an X509Certificate.
Include Subject Name Determines whether the X509SubjectName element isincluded in the KeyInfo X509Data element when the KeyEncryption Key to describe came from an X509Certificate.
Include Certificate Determines whether the X509Certificate element is included inthe KeyInfo X509Data element when the Key Encryption Key todescribe came from an X509Certificate.
Key Name Specifies the value of the KeyName element added to theKeyInfo element. This property is most useful when the KeyEncryption Key is a symmetric key. Usually left blank to omitthe KeyName element when using a public key.
Include WSSE SecurityToken Reference
Determines whether a WSSE SecurityTokenReference to a pre-existing BinarySecurityToken is included in the KeyInfoelement.
WSSE Security Token Id The value of the BinarySecurityToken ID Attribute referenced bythe WSSE SecurityTokenReference. If left blank, the defaultvalue is token.
Edges:
Available Services
548 Information Builders
The following table lists the available Line Edges for the XML Encryption Service(com.ibi.agents.XDXMLEncryptionAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnParseError Could not parse a document.
OnFailedOperation Could not perform the operation requested.
OnNotFound The resource was not found and this isconsidered an error.
XML Extract Service (com.ibi.agents.XDXMLExtract)
Syntax:
com.ibi.agents.XDXMLExtract
iIT Service Object:
format: XML Extract
Description: Uses an XPath expression to get a node list, and produce a subtree.
Parameters:
Parameter Description
XPath expression * The XPath expression (not XPath function) used to extract anode list.
Optional Root The optional root name of the extracted subtree.
XPath Syntax Determines which syntax level of the XPath should be used.The default option selects the syntax level as set in theconsole global settings.
1. iWay Services
iWay Service Manager Component Reference Guide 549
Parameter Description
XML Namespace MapProvider
If the XPath expression depends on namespaces, supply thename of an XML Namespace Map Provider that contains therequired namespace prefixes and URLs.
Edges:
The following table lists the available Line Edges for the XML Extract Service(com.ibi.agents.XDXMLExtract).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
OnNotFound The resource was not found and this isconsidered an error.
failed_structure Extracted multiple nodes, but no rootParmwas given.
XMLtoEDIFACTTransformAgent Service (com.ibi.agents.XMLToEDIFACTTransformAgent)
Syntax:
com.ibi.agents.XMLToEDIFACTTransformAgent
iIT Service Object:
format: XMLtoEDIFACTTransformAgent
Description: This agent transforms an EDIFACT XML document into an EDIFACT document.
Parameters:
Available Services
550 Information Builders
Parameter Description
template The XMLtoFACT_%_^.xch, where [%] represents the messagetype and [^] represents the release number. The pattern isused to lookup a document inside the EBIX. If the onlydocument in use was D08A ORDERS, and you were to hard-code for just that transformation, the value would beFACTtoXML_ORDERS_D08A.xch, which is the template namewithin the EBIX.
Timestamp Write a timestamp to the log file.
sTerminator The control character that marks the end of a specific variable-length segment.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
segSuffix The Segment Suffix marks the end of the Segment. This isused in combination with Segment Terminator Character.
Note: Users can select the character from the predefined listor enter a predefined SREG, whose value is resolved at runtime, or a function to retrieve the value from a Trading PartnerProfile.
eDelimiter The control character used to separate elements in asegment. It follows the segment identifier and each dataelement in a segment except the last.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
1. iWay Services
iWay Service Manager Component Reference Guide 551
Parameter Description
compDelimiter The control character used to separate sub-elements/components in a composite element.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
eCharacter The escape character is necessary if any of the EDI documentseparators are part of the actual value of an attribute. Thedefault value is '\'.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
InsertGroupLoop Inserts a Group Loop in the XML Document Structure.
Edges:
The following table lists the available Line Edges for the XMLtoEDIFACTTransformAgent Service(com.ibi.agents.XMLToEDIFACTTransformAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
XMLtoEDIHL7TransformAgent Service (com.ibi.agents.XMLtoEDIHL7TransformAgent)
Syntax:
com.ibi.agents.XMLtoEDIHL7TransformAgent
iIT Service Object:
Available Services
552 Information Builders
format: XMLtoEDIHL7TransformAgent
Description: This agent transforms an HL7 XML document into HL7 document.
Parameters:
Parameter Description
timestamp Writes a timestamp to the log file.
Edges:
The following table lists the available Line Edges for the XMLtoEDIHL7TransformAgent Service(com.ibi.agents.XMLtoEDIHL7TransformAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
XMLtoHIPAATransformAgent Service (com.ibi.agents.XMLToHIPAATransformAgent)
Syntax:
com.ibi.agents.XMLToHIPAATransformAgent
iIT Service Object:
format: XMLtoHIPAATransformAgent
Description: This agent transforms a HIPAA XML document into a HIPAA document.
Parameters:
1. iWay Services
iWay Service Manager Component Reference Guide 553
Parameter Description
template * The XMLtoHIPAA_%_^.xch, where [%] represents the messagetype and [^] represents the release number. The pattern isused to lookup a document inside the EBIX. For example, thevalue for the 4010 837 Professional template, if hard-coded,would be XMLtoHIPAA_837_004010X098A1.xch, which is thetemplate name within the EBIX.
debug * The transformation components are written to files in the localdirectory (very slow).
sTerminator The control character that marks the end of a specific variable-length segment.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
segSuffix The Segment Suffix marks the end of the Segment. This isused in combination with Segment Terminator Character.
Note: Users can select the character from the predefined listor enter a predefined SREG, whose value is resolved at runtime, or a function to retrieve the value from a Trading PartnerProfile.
eDelimiter The control character used to separate elements in asegment. It follows the segment identifier and each dataelement in a segment except the last.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
Available Services
554 Information Builders
Parameter Description
compDelimiter The control character used to separate sub-elements/components in a composite element.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
eCharacter The escape character is necessary if any of the EDI documentseparators is part of the actual value of an attribute. Thedefault value is '\'.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
timestamp Writes a timestamp to the log file.
InsertGroupLoop Inserts Group Loop in the XML Document Structure.
decodeBinSegment Decodes BIN02 element from BASE64 to binary.
Edges:
The following table lists the available Line Edges for the XMLtoHIPAATransformAgent Service(com.ibi.agents.XMLToHIPAATransformAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
XMLtoX12TransformAgent Service (com.ibi.agents.XMLToX12TransformAgent)
Syntax:
1. iWay Services
iWay Service Manager Component Reference Guide 555
com.ibi.agents.XMLToX12TransformAgent
iIT Service Object:
format: XMLtoX12TransformAgent
Description: This agent transforms an X12 XML document into an X12 document.
Parameters:
Parameter Description
template * The XMLtoX12_%_^.xch, where [%] represents the messagetype and [^] represents the release number. The pattern isused to lookup a document inside the EBIX. If the onlydocument in use was 4010 850, and you were to hard-codefor just that transformation, the value would beXMLtoX12_850_004010.xch, which is the template namewithin the EBIX.
debug * The transformation components are written to files in the localdirectory (very slow).
sTerminator The control character that marks the end of a specific variable-length segment.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
segSuffix The Segment Suffix marks the end of the Segment. This isused in combination with Segment Terminator Character.
Note: Users can select the character from the predefined listor can a predefined SREG, whose value is resolved at runtime, or a function to retrieve the value from a Trading PartnerProfile.
Available Services
556 Information Builders
Parameter Description
eDelimiter The control character used to separate elements in asegment. It follows the segment identifier and each dataelement in a segment except the last.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
compDelimiter The control character used to separate sub-elements/components in a composite element.
Note: Users can either select the character from thepredefined list or can a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
eCharacter The escape character is necessary if any of the EDI documentseparators is part of the actual value of an attribute. Thedefault value is '\'.
Note: Users can either select the character from thepredefined list or enter a predefined SREG, whose value isresolved at run time, or a function to retrieve the value from aTrading Partner Profile.
Edges:
The following table lists the available Line Edges for the XMLtoX12TransformAgent Service(com.ibi.agents.XMLToX12TransformAgent).
Line Edge Description
OnError An exception occurred during execution.
OnSuccess The operation was successful.
OnFailure A fail condition occurred during execution.
success The operation was successful.
1. iWay Services
iWay Service Manager Component Reference Guide 557
XQuery Expression Evaluation (com.ibi.agents.XDXQueryAgent)
Syntax:
com.ibi.agents.XDXQueryAgent
iIT Service Object:
misc: XQuery Agent
Description:
The XDXQueryAgent is used to evaluate an XQuery 1.0 expression against the incomingdocument. The results are available in an outgoing document. XQuery can be used to selectportions of the document or to transform the document as a whole.
XQuery is a query and functional programming language that is designed to query collections ofXML data. XQuery 1.0 was developed by the XML Query working group of the W3C. The workwas closely coordinated with the development of XSLT 2.0 by the XSL Working Group. The twogroups shared responsibility for XPath 2.0, which is a subset of XQuery 1.0.
Parameters:
Parameter Description
XQueryExpression
The XQuery expression to evaluate. To put the expression in a file, youcan use _file().
EvaluateExpression
When true, the XQuery Expression is evaluated by iFL to return theactual XQuery expression to use. The default is to take the XQueryexpression as is, which simplifies quoting considerably.
Available Services
558 Information Builders
Parameter Description
Return Determines how to return the result sequence in the output document.The following are examples:
Select value to return the value of each result sequence item in aflat document.
Select markup to return the serialization of each result sequenceitem in a flat document.
Select root to return the Element or Document in the first resultsequence item as the root of a tree document.
Select wrap to return a tree where each result sequence itemappears under an item element.
MinimumOccurrence
Minimum number of items in result sequence, otherwise return theedge fail_empty.
Include All Items Determines if all items in the result sequence are part of the returndocument, otherwise only the first item is included.
Separator The separator to insert between result sequence items when returninga flat document. The default is no separator.
Edges:
The following table lists the available line edges for the XQuery Expression Evaluation(com.ibi.agents.XDXQueryAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
1. iWay Services
iWay Service Manager Component Reference Guide 559
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse: The parameters are incorrect. Thisincludes syntax errors in the XQuery expression ormissing a value for an external variable. The outputdocument is an error status document.
fail_operation: Failed for another cause. The outputdocument is an error status document.
fail_empty: The application indicated that it requiresat least one item in the result sequence but theresult sequence was empty. The output document isan error status document.
When the Evaluate Expression parameter is false, the XQuery Expression parameter containsthe actual XQuery Expression. For example:
//elem[@attr="1"]
When the Evaluate Expression parameter is true, the XQuery Expression parameter contains aniFL expression that is evaluated to obtain the actual XQuery Expression to use.
The following example is similar to the previous expression except the value to match againstthe attr attribute now depends on the special register, reg1:
_concat("//elem[@attr=\"",sreg(reg1),"\"]")
Another example is to use the function _file() to read the XQuery expression from a file.
If the XQuery Expression cannot be parsed by the XQJ implementation, the agent returns anerror status document and it follows the fail_parse edge.
The returned value of an XQuery expression is always a result sequence. The Return parameterdetermines how the result sequence is stored in the output document. Selecting value ormarkup will return a string in a flat document. Selecting root or markup will return a parsedXML tree.
Available Services
560 Information Builders
Consider the input document <root><elem>e1</elem></root> and the XQuery Expression /root/elem. The following table shows the effect of the Return parameter.
Return Parameter
ReturnParameter
OutputDocument
Output Document Value
value flat "e1"
markup flat "<elem>e1</elem>"
root tree <elem>e1</elem>
wrap tree <XQueryResult><item><elem>e1</elem></item></XQueryResult>
The root option can only return the first item in the result sequence. That item must be anelement or a document. If the element inherits XML declarations from its ancestors, thoseXML Namespace declarations will be added directly to the element.
The wrap option can return zero or more items. The intermediate <item> element makes itpossible to return any node, including attributes. The XQueryResult Element will have exactlythe same number of item sub-elements as there are items in the result sequence. The ordersequence will be preserved, including returned attributes. When a returned item is an elementthat inherits XML declarations from its ancestors, those XML Namespace declarations will beadded directly to the element. When a returned item is an attribute in a namespace, the XMLnamespace declaration will be added to the enclosing item Element.
The Minimum Occurrence parameter is useful to reject empty results. When the applicationrequires a value, it can set the Minimum Occurrence parameter to 1. If the result sequence isempty, the agent returns an error status document and it follows the fail_empty edge.
The Include All Items parameter determines if all items in the result sequence are part of thereturn document, otherwise only the first item is included. When all items are returned in atree document, they must always be copied in case two items would overlap. When a singleitem is required in a tree document, the returned node can often be reparented instead.
The Separator parameter can be used to separate the values when Include All Items is trueand the return document is a flat String. For example, if the separator is |, the expressionis //e, the return selection is value and the input document is:
<root><e>1</e><e>2</e><e><3></e></root>,
1. iWay Services
iWay Service Manager Component Reference Guide 561
then the output string will be "1|2|3". Without the separator, the output would be "123".
External Variables
An XQuery expression can declare variables to be external. For example, the followingexpression declares two external variables, $v1 and $ns:v2.
declare namespace ns="http://ns";declare variable $v1 external;declare variable $ns:v2 external;<root><elem1>{$v1}</elem1><elem2>{$ns:v2}</elem2></root>
These variables must be given a value from the environment. The XDXQueryAgentaccomplishes this with the help of User Defined Properties. The name of the User Property isrelated to the external variable name in the following way:
If the external variable is not in a namespace, then the User Property name is the externalvariable name.
If the external variable is in a namespace, then the User Property name follows the pattern{nsuri}localname. The nsuri is the namespace URI that is obtained by expanding thenamespace prefix in the external variable name. This convention eliminates the need fornamespace declarations in the parameters since the URI is used instead.
For example, the $v1 variable above is not in a namespace, therefore the corresponding UserProperty is v1. The $ns:v2 variable above is in the namespace http://ns, therefore, thecorresponding User Property is {http://ns}v2.
Available Services
562 Information Builders
The User Properties can be given a value in iIT Designer. First, create a Service Object forXDXQueryAgent.
1. iWay Services
iWay Service Manager Component Reference Guide 563
Click Next twice and enter the agent parameters.
Available Services
564 Information Builders
Click Next to display the User Properties. Click the label Click here to add to add the UserProperties one at a time.
Click Finish to create the Service Object.
1. iWay Services
iWay Service Manager Component Reference Guide 565
The User Properties can be modified after the object is created. Double-click on the ServiceObject and select the User Defined Properties tab.
Click OK to save the changes.
Recall the XQuery expression presented earlier. If that expression is evaluated with the UserProperties shown, the result will be:
<root><elem1>one</elem1><elem2>two</elem2></root>
If an external variable does not have a corresponding User Property, the agent returns an errorstatus document and it follows the fail_parse edge instead.
XQuery Implementation
The evaluation engine is provided by a third-party XQJ implementation. By default, the agent isconfigured to call SaxonHE (Home Edition). The default can be modified by assigning a classname to the Java system property javax.xml.xquery.XQDataSource. The class specified mustimplement the XQDataSource interface. For example, this call to the java interpreter assignsthe same XQDataSource as the default:
java -Djavax.xml.xquery.XQDataSource=net.sf.saxon.xqj.SaxonXQDataSource
Zip Out Service (com.ibi.agents.XDZipOutAgent)
Syntax:
Available Services
566 Information Builders
com.ibi.agents.XDZipOutAgent
iIT Service Object:
misc: Zip Out Agent
Description:
This service converts an input document into a compressed .zip file.
Parameters:
Parameter Description
Entry name * The name of the output .zip file that will be generated.
Comment A comment associated with this entry.
Edges:
The following table lists the available line edges for the Zip Out Service(com.ibi.agents.XDZipOutAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
Example:
1. iWay Services
iWay Service Manager Component Reference Guide 567
The following image shows configuration settings specified in the Properties tab for a Zip Outservice object in iIT Designer:
You can test the Zip Out service by configuring a channel with a basic File listener as the inletand a route, which is associated with a process flow containing a Zip Out service object.
When you run this channel, the contents of the incoming message (picked up by the Filelistener) are added to a .zip file, which is placed in the destination folder specified by your Filelistener. The name of the entry that is added to the .zip file is composed from the value that isspecified for the Entry name parameter (for example, testzip.xml). When you configure the Filelistener, it is recommended to specify zip for the Suffix Out parameter. However, you canalways rename the extension of the output file that is generated to .zip and extract thecontents.
Parallel Control Services
You can run multiple operations in parallel within a flow. For example, you can query multipledata stores simultaneously, or update multiple databases. This can be accomplished withparallel edges (multiple matching edges coming out of a node), though it is difficult to design aflow that controls the concurrent execution and the orderly termination of these operations.
The parallel control agent solves these issues by controlling the execution of an arbitrarynumber of identical parallel operations. It will then proceed down its flow on its output edgeonly when all of the parallel operations are complete. All threading control is managed by theagent, so that the application flow designer need not consider any synchronization issues.
The number of operations is determined by an iterator embedded inside the agent. The iteratoris initialized with the input document reaching the agent. The agent uses each item returned bythe iterator as the input document of a subflow it runs in parallel. When all subflows havereturned, the agent itself terminates. The output is the accumulated result of all the subflows.
Parallel Control Services
568 Information Builders
Each subflow is independent. For example, the subflow can itself contain iterators or otherobjects that maintain state without interfering with other parallel flows. Subflows should bedesigned to be relatively quick to complete, as the parallel control agent cannot proceed untilall subflows either return or are timed out.
There are multiple variants of the parallel control agent depending on the type of iterator itembeds. For example, the XDParallelXMLSplitAgent embeds an XDIterXMLSplit iterator. TheXDParallelCountAgent embeds an XDIterCount iterator.
The following table shows parallel services with common parameters.
Parameter Description
Flow Name Name of the published subflow to run inparallel. This must have been published.
Maximum Parallel Tasks Used to throttle the execution to limit theamount of resources needed. It specifiesthe maximum number of subflows toprocess simultaneously. If an additionalsubflow must be executed, it will wait for aprevious subflow to complete. The value 0means unbounded, therefore all itemsreturned by the iterator will attempt to run inparallel.
Timeout Specifies the maximum time to wait for allsubflows to complete. The agent timeoutshould probably be bigger than the subflowtimeout if throttling is used. The value 0means there is no time limit.
Accumulation Version The parallelized result is accumulated. Theresult is either Simple or Multiple. Simplemeans that only a single, XML document isaccumulated from each parallel subflow.Multiple allows several documents of XMLor non-XML to be accumulated from eachparallel subflow. Simple uses less memory.Multiple allows a wider variety of parallelizedflows.
1. iWay Services
iWay Service Manager Component Reference Guide 569
The remaining parameters are specific to the embedded iterator.
The agent assigns a unique integer value to the special register iway.taskindex for eachsubflow that it executes. The value of taskIndex for the first subflow is 1, the value for thesecond subflow is 2 and so on, increasing by one.
The following edges are returned by the agent in this situation.
Edges Description
success Every subflow was completed successfully,or the iterator returned no items.
fail_parse Syntax error in one of the parameterexpressions.
fail_notfound Cannot find a subflow with that name.
fail_timeout The agent timed out or was cancelled.
fail_operation All of the subflows returned abnormally.
fail_incomplete At least one subflow completed successfullyand at least one returned abnormally. Usersare warned that fail_incomplete, if not wired,will be reflected as an error. Some flowsmay wish to wire this and the successedges to the same node, and do analysislater in the flow. Fail_incomplete is not areflection of decisions made in theexecution of the item, but rather of thesuccess of execution itself.
cancel The overall flow was cancelled.
Notice that if a subflow times out, it will appear to return abnormally. This will cause the agentto return fail_operation or fail_incomplete depending on the result of other process flows. Theagent returns the edge fail_timeout only if the agent itself times out.
For the Simple Accumulation version, the result has a format as shown in the followingexample.
Note: The XML output shown is for the <Test> element with a value of _sreg('iway.taskindex').
Parallel Control Services
570 Information Builders
<?xml version="1.0" encoding="UTF-8" ?><results> <result index="1" items="1" edge="success">> <Test>1</Test> </result> <result index="3" items="1" edge="success">> <Test>3</Test> </result> <result index="4" items="1" edge="success"> <Test>4</Test> </result> <result index="2" items="1" edge="backout" error='true'> <status>This is an error document from the subflow</status> </result></results>
The final result for Multiple Accumulation Version has the following form.
Note: The XML output shown is for the <Test> element with a value of _sreg('iway.taskindex').
<?xml version="1.0" encoding="UTF-8" ?><results> <result index="1" items="1"> <item edge="success" encoding="UTF-8" format="xml"> <Test>1</Test> </item> </result> <result index="3" items="1"> <item edge="success" encoding="UTF-8" format="string">value of string </item> </result> <result index="4" items="1"> <item edge="success" encoding="UTF-8" format="bytes">value in base64 </item> </result> <result index="2" items="1"> <item edge="backout" encoding="UTF-8" format="xml" error='true'> <status>This is an error document from the subflow</status> </item> </result></results>
In this example, the subflows terminated in the end nodes named success and backout. Thesubflow with index 2 returned an error, and the error status of the document is noted foranalysis. The subflows also returned different types of information. The application designer isresponsible for the data and the format in which it is returned.
1. iWay Services
iWay Service Manager Component Reference Guide 571
The following table shows informal attributes in the output accumulation.
Attribute Description
encoding The IANA encoding associated with thedocument. (Multiple format only)
format The payload type. See below for informationon the types. (Multiple format only)
edge The name of the end node in the subflowthat returned this document.
error If the returned document has the error stateset, this attribute will be set to true.
The following table shows the formats and how data values are returned in the outputaccumulation.
Format Description
xml The returned information is carried as a child (subtree) ofthe <item> node. In our example, it is a small XMLdocument rooted in the <Test> element.
string The information is returned as the value of the <item>node.
bytes The information is returned as the value of the <item>node. The information is base64 encoded.
It is legal if the iterator returns no item. In this case, no subflow will be executed and the<results> element will be empty.
Each <result> element contains the result of one subflow. The index attribute specifies thevalue of the taskIndex special register for that subflow. The <result> elements are not sortedsince they appear in the order that subflows terminate. The <result> element contains the oneor more documents returned by the subflow. The agent ignores documents that do not containinformation. If the subflow ended abnormally, an error document will appear instead.
Parallel Control Services
572 Information Builders
Once the parallel agent completes, the resulting accumulation is available to subsequent flownodes. These nodes can deal with the result in any manner appropriate to the application. Forexample, you can execute an XDIterXMLSplit iteration and process each result as needed. Inthis case, the agent did not remove the need for iteration. However, it executed a potentiallylengthy computation in parallel, saving a lot of time. Running iteration on a pre-computed resultis much faster.
You can also execute a transform to produce an appropriate output document.
As usual with subflows, it is also possible to assign special registers in the parent scope,enabling to pass information back to the flow of the agent if needed. The use of a register lockis advisable when the Maximum Parallel Tasks property is more than 1. The scope and LockName properties of the XDSREGAgent are designed for this.
Cancellation Concerns
If the outer flow is cancelled, the cancellation is passed to the subflows, and no furthersubflows are started. The parallel control agent awaits completion of the current set, and thenpasses the status document down the cancel edge.
Developer Cautions
Developers using the parallel control agent are reminded that several issues must beconsidered in use and tuning of the application.
1. Parallel operations are passed among the available execution threads of the computer. Ona computer with a large number of processors, this can result in significantly improvedperformance. However, on a computer with a few processors, control may be passed backand forth among the threads and little if any overall performance gain is achieved. It is easyto generate more computation/access requests than the system can satisfy.
2. The best use of parallel processing is when passing work off the system to another system,such as a database or another computer through a remote call. In this case, most of thesubflows will be waiting for results and many can be managed simultaneously.
3. Memory use is cumulative. Since each subflow receives a copy of the input document, andeach needs memory to do its work, memory considerations should be taken into account indesign of the application.
The services support a Maximum Parallel Tasks parameter. This is the number of executionsthat will take place in parallel. Managing use of iFL, coupled with an understanding of thedynamics of the application, can help in setting this parameter. For example, the followingcommand sets the number of attempted simultaneous parallel executions to a multiple of theavailable processors.
1. iWay Services
iWay Service Manager Component Reference Guide 573
_int(_ceil(_mul(_div(_sysinfo(processors),_chaninfo(*,'active')),8)))
XDParallelCountAgent Properties
The following image shows the configuration parameters for Parallel Execution: Countediteration service.
XDParallelJsonSplitAgent Properties
The following image shows the configuration parameters for Parallel Execution: JSON iterationservice.
Parallel Control Services
574 Information Builders
XDParallelXMLSplitAgent Properties
The following image shows the configuration parameters for Parallel Execution: XML iterationservice.
The following image shows the configuration parameters for Parallel Execution: XML iterationservice.
1. iWay Services
iWay Service Manager Component Reference Guide 575
Parallel Control Services
576 Information Builders
Chapter2iWay Preparsers
iWay Service Manager includes many predefined preparsers that you can use to convertincoming messages into processable documents. You can add these preparsers tosimple or complex business logic configurations using the iWay Service ManagerAdministration Console.
For reference purposes, this section lists and describes all the predefined preparsersthat are supplied with iWay Service Manager.
In this chapter:
Preparser Overview
Available Preparsers
Streaming Preparsers
Splitter Preparsers
Preparser Overview
A preparser is designed to convert incoming messages into processable documents. Thepreparsed document then passes through the standard transformation services to reach thedesignated processing service. An example of a preparser is a class that accepts an EDI-formatted document and converts it to XML for further processing. For more information on themethodology used in writing preparsers, see the iWay Service Manager Programmer's Guide.
Each preparser uses a class file that must be located in a directory which is in the Javaclasspath. iWay Service Manager includes preparsers that have been preconfigured.
Available Preparsers
The following section provides a comprehensive reference for all the predefined preparsersthat are supplied with iWay Service Manager.
iWay Service Manager Component Reference Guide 577
PreparserName
Class Name Streaming? Description
Append XDAppend No Used for appending text toan existing flat file.
C Char Filter CCharFilter No Eliminates controlcharacters from an incomingmessage.
Char Repl XDCharRepl No Performs characterreplacements in theincoming document.
Cross-OriginResourceSharing
XDCors No Implements the samefunctionality as the Cross-Origin Resource SharingService.
DelimitedValue
XDDelVal No Delimited value handler.
DelimitedValue Stream
XDDelValStream Yes Streamable delimited valuehandler.
EDIFACTBatch SplitterPreparser
XDEDIFACTBatchSplitter No Splits EDIFACT input filesthat contain multipletransactions or envelopes.
EDI BatchSplitter
XDEDIBatchSplitter Yes Splits a batch of EDIdocuments.
EDIFACT XDEDIFACTPreParser No Accepts a % in the templatename, which is filled in bymessage type.
EDIX12 XDEDIpreParser No After a batch of EDImessages is split, thispreparser converts each EDImessage into XML format.
Available Preparsers
578 Information Builders
PreparserName
Class Name Streaming? Description
EDIX12SplitterPreparser
EDISplitPP Yes Parses an EDI input file thatcontains one or moreinterchanges (ISA) andmultiple documents, andcreates multiple XML outputfiles. For more information,see the iWay IntegrationSolution for EDI User'sGuide.
EDIX12 XMLValidator
XDXMLEDIValidator No Takes EDI XML as input andreturns that input with thestructural errors sectionadded to be processed bythe appropriate rule.
En Tag XDEnTag No Surrounds the incomingmessage with a designatedtag.
Error Filter ErrorFilter No Obtains the original inputdocument from the errordocument.
Excel XDExcelpreParser No Transforms an Excelworksheet into an XMLformatted document.
ExtractPreparser
XDExractPreparser Yes Decompresses compressedfiles.
Flat Stream XDFlatStreamPreParser Yes Splits non-XML messagesthat are to be split on arecognized character.
HIPAA BatchSplitter
XDHIPAABatchSplitter No Splits a batch of HIPAAdocuments.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 579
PreparserName
Class Name Streaming? Description
HIPAAPreparser
XDHIPAAPreParser No Transform a HIPAAdocument into a HIPAA XMLdocument.
HIPAA SplitterPreparser
HIPAASplitPP No Parses a HIPAA input filethat contains one or moreinterchanges (ISA) andmultiple documents, andcreates multiple XML outputfiles. For more information,see the iWay IntegrationSolution for HIPAA User'sGuide.
HTTP XDHTTPpreParser No Transforms a key=valuequery string into an XMLstring with the POST actionas the root.
HTTPMultipart
XDHTTPMultipartPreparser No Transforms a key=valuequery string into an XMLstring with the POST actionas the root.
Inflate XDInflate No Inflates data produced bythe deflate preemitter.
JMS ObjectPreparser
XDJMSObjectPreParser No Used to convert a JMSObjectMessage to a suitableiSM message.
Legacy Record LegacyRecordPreparser No Converts an incoming legacyflat file (copybook) into anXML file. For moreinformation, see the iWayTransaction Adapter for CICSUser's Guide.
Available Preparsers
580 Information Builders
PreparserName
Class Name Streaming? Description
Multi Part XDMultiPart No Divides multipart documentsfor later use.
Multi Part forNHTTP
XDMultiPartForNHTTP No Divides multipart documentsinto body and attachments.
PgpDecrypt PGPDecrypt No Decrypts an incomingmessage on the channelinto the original unencryptedformat.
Safestore XDSafestorePreparser No Stores incoming HTTPmessages. By default,messages are written to thedisk.
SOAP XDSOAPPreParser No Accepts SOAP messagefrom any JMS listener.
SREGPreparser
XDSREGPreparser No Sets one or more specialregisters of a given type.
SWIFT ACK SwiftBPP No Transforms MT021 SystemsMessages to XML-formatteddocuments. For moreinformation, see the iWayIntegration Solution forSWIFT User's Guide.
SWIFT BatchSplitter
XDSWIFTBatchSplitter Yes Splits the input stream andproduces groups of byte[]'sas per the predefinedsplitting logic. For moreinformation, see the iWayIntegration Solution forSWIFT User's Guide.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 581
PreparserName
Class Name Streaming? Description
SWIFT SystemMessage
XDSWIFTSysMsgPreParser No Transforms SWIFT User-to -System and System-to-UserFIN Format Messages toXML-formatted documents.For more information, seethe iWay Integration Solutionfor SWIFT User's Guide.
XDSWIFT XDSWIFTpreParser No Accepts a % in the templatename, which is filled in bymessage type. For moreinformation, see the iWayIntegration Solution forSWIFT User's Guide.
XML Split XDXMLSplit No Splits an incoming XMLdocument based on anXPATH value.
XML Stream XDXMLStreamPreParser Yes Accepts an input filecontaining multiple XMLdocuments and createssingle XML documents fromthe original input file.
Append Preparser (com.ibi.preparsers.XDAppend)
Syntax:
com.ibi.preparsers.XDAppend
Available Preparsers
582 Information Builders
Description:
The Append preparser is used to append text to an existing flat file. This preparser should notbe the last in the chain before a route is called. You can use the En Tag preparser to enclosethe flat appended text into an XML structure or use iWay Transformer to convert a flat file toXML format.
In a use case scenario, the Append preparser is useful when two flat files need to beappended. However, to convert to XML, an additional preparser, such as En Tag ,should beused in order to process the flat file through the channel.
Parameters:
Parameter Description
Prefix Adds text to the head of the incoming document.
Suffix Adds text to the tail of the incoming document.
Example:
1. Select the Append (com.ibi.preparsers.XDAppend) preparser from the Type drop-down listand click Next.
The configuration parameters pane opens.
2. Enter test as a value for the Prefix parameter and click Next.
The name and description pane opens.
3. Enter a name for the new Append preparser and an optional description.
4. Click Finish.
This Append preparser adds a prefix (test) to the incoming flat document. To convert thisdocument to an XML file, you could use the En Tag preparser.
C Char Filter Preparser (com.ibi.preparsers.CCharFilter)
Syntax:
com.ibi.preparsers.CCharFilter
Description:
The C Char filter preparser is used to remove control characters from an incoming message.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 583
In a use case scenario, the C Char filter preparser can be used when an incoming message isunformatted and contains carriage returns. The C Char filter preparser can remove the carriagereturn and tab fields before sending it to a message flow for further processing.
Parameters:
Parameter Description
Linefeed * Indicates whether linefeed characters (\r) need to be removed.
Carriage Return * Indicates whether carriage returns (\n) need to be removed.
Tab * Indicates whether tab characters (\t) need to be removed.
End Of File * Indicates whether DOS end of file (0x1a) characters need to beremoved.
Bell * Indicates whether bell (0x07) characters need to be removed.
Control
Replace With * Indicates whether the removed characters are replaced with aspace, period, or none (remove).
Example:
In the following example, the C Char filter preparser is used to create a list of travel items,which were originally listed in a file separated by a line feed, into a list containing all the itemson a single line.
1. Select the C Char Filter (com.ibi.preparsers.CCharFilter) preparser from the Type drop-downlist and click Next.
The configuration parameters pane opens.
2. Select true for the Linefeed, Carriage Return, Tab, End Of File, and Bell parameters.
3. Select space for the Replace With parameter and click Next.
The name and description pane opens.
4. Enter a name (for example, XDCCharFilter) and an optional description.
5. Click Finish.
6. Construct an inlet, for example, PreparseInlet, which is associated with a file listener andthe new preparser (XDCCharFilter) to enclose each split flat file into an XML file.
Available Preparsers
584 Information Builders
7. Define a simple move route and a default outlet for the channel.
8. Build, deploy, and start the channel.
9. Create a simple input text document (for example, Travellist.txt), which contains thefollowing list of travel items:
suitcasetoothbrushtravel casecombsoap
When this input document is processed by the channel, an output document (for example,travellist_out.txt) is generated with the following contents:
suitcase toothbrush travel case comb soap
Char Repl Preparser (com.ibi.preparsers.XDCharRepl)
Syntax:
com.ibi.preparsers.XDCharRepl
Description:
The Char Repl preparser is used to perform character replacements in an incoming document.
In a use case scenario, if a name is misspelled in an incoming document as Rom instead ofTom, then the character R could be replaced with T in this document. It is analogous to thefind and replace function that can be found in most word processing applications.
Parameters:
Parameter Description
Input * String of individual characters to replace.
Replace with * String of characters to replace input with.
Example:
1. Select the Char Repl (com.ibi.preparsers.XDCharRepl) preparser from the Type drop-down listand click Next.
The configuration parameters pane opens.
2. Enter R for the Input parameter and T for the Replace with parameter.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 585
3. Click Next.
The name and description pane opens.
4. Enter a name (for example, XDCharRepl) and an optional description.
5. Click Finish.
6. Construct an inlet, for example, PreparseInlet, which is associated with a file listener andthe new preparser (XDCharRepl) to enclose each split flat file into an XML file.
7. Define a simple move route and a default outlet for the channel.
8. Build, deploy, and start the channel.
9. Create a simple input text document (for example, document2.txt), which contains thefollowing:
<a><t> <b name="rom"> <c>value of input element</c> </b> <b name="rom2"> <c>value of input element</c> </b> </t></a>
When this input document is processed by the channel, an output XML document isgenerated with the following contents:
<?xml version="1.0" encoding="ISO-8859-1" ?><a><t><b name="tom"><c>value of input element</c></b><b name="tom2"><c>value of input element</c></b></t></a>
Cross-Origin Resource Sharing Preparser (com.ibi.preparsers.XDCorsPreparser)
Syntax:
com.ibi.preparsers.XDCorsPreparser
Description:
This preparser implements the same functionality as the Cross-Origin Resource SharingService (com.ibi.agents.XDCorsAgent). For more information, see Cross-Origin Resource SharingService (com.ibi.agents.XDCorsAgent).
The preparser causes an error if the returned edge would be anything other than success.
Available Preparsers
586 Information Builders
EDIFACTPreParser (com.ibi.preparsers.XDEDIFACTPreParser)
Syntax:
com.ibi.preparsers.XDEDIFACTPreParser
Description:
After a batch of EDIFACT messages are split, the EDIFACTPreParser converts each EDIFACTmessage into XML format. For more information on how to configure the EDIFACTPreParser,see the iWay Integration Solution for UN/EDIFACT User's Guide.
EDIH7PreParser (com.ibi.preparsers.XDEDIHL7PreParser)
Syntax:
com.ibi.preparsers.XDEDIHL7PreParser
Description:
The EDIH7PreParser preparser accepts a % in the template name, which will get filled in by themessage type.
Parameters:
Parameter Description
Template The HL7_%_^toXML.xch, where [%] represents the message typeand [^] represents the version. The pattern is used to lookup adocument inside the EBIX.
Timestamp Writes a timestamp to the log file. (Trace level INFO or DEBUG).
Z-segment Makes a floating structure.
Segment Adds a name attribute.
Composite Adds a name attribute.
Element Adds a name attribute.
EDIX12PrePreparser (com.ibi.preparsers.XDEDIpreParser)
Syntax:
com.ibi.preparsers.XDEDIpreParser
2. iWay Preparsers
iWay Service Manager Component Reference Guide 587
Description:
After a batch of EDI messages is split, the EDIX12PreParser converts each EDI message intoXML format.
Note: The EDIX12PrePreparser is deprecated. As an alternative it is recommended to use theEDIX12SplitterPreParser (EDISplitPP)/
EDIX12 XML Validator (com.ibi.preparsers.XDXMLEDIValidator)
Syntax:
com.ibi.preparsers.XDXMLEDIValidator
Description:
The EDIX12 XML Validator preparser takes EDI XML as input and returns that input with thestructural errors section added to be processed by the appropriate rule.
En Tag Preparser (com.ibi.preparsers.XDEnTag)
Syntax:
com.ibi.preparsers.XDEnTag
Description:
The En Tag preparser surrounds the incoming message with a designated tag. Optionally, itpasses on the incoming message as CDATA to the tag. Additional features allow configurationof attributes including source, message ID, and correlation ID.
In a use case scenario, the En Tag preparser can be used when a flat file needs to beconverted into an XML file without changing the format of the flat file (using the entire contentof the flat file as is). For instance, if a flat file contained a list of names separated by carriagereturns, this preparser can be used to convert the file to XML format.
Parameters:
Parameter Description
Tag * Name of the tag used to surround the input.
Cdata If set to true, the input is enclosed as a CDATA value.
Protocol Determines whether to Include the protocol as an attribute.
Source Determines whether to Include the source as an attribute.
Available Preparsers
588 Information Builders
Parameter Description
Message ID Determines whether to Include the message ID as an attribute.
Correlation ID Determines whether to Include the correlation ID as an attribute.
Entity replace If set to true, the input will be XML entity replaced.
Base64 Determines whether the content should be encoded into base64form.
Result Form Specifies the type of output that is required. Select parsable ortree from the drop-down list.
Call at EOS? In streaming a last call is made after the last document.Determines whether this service should be called.
Example:
1. Select the En Tag (com.ibi.preparsers.XDEnTag) preparser from the Type drop-down list andclick Next.
The configuration parameters pane opens.
2. Enter testroot in the Tag field.
3. Select false from the Cdata field drop-down list.
4. Click Next.
The name and description pane opens.
5. Enter a name (for example, XDEntagPreparser) and an optional description.
6. Click Finish.
Note: This preparser can also be used in conjunction with the Append preparser toillustrate its use.
7. Construct an inlet, for example, PreparseInlet, which is associated with a file listener, anAppend preparser, and the new preparser (XDEntagPreparser).
8. Define a simple move route and a default outlet for the channel.
9. Build, deploy, and start the channel.
10.Create a simple input text document, which contains a line of text, for example, append.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 589
When this input document is processed by the channel, the contents are appended andenclosed. The following XML output document is generated:
<?xml version="1.0" encoding="ISO-8859-1" ?><testroot>testappend</testroot>
Error Filter Preparser (com.ibi.preparsers.ErrorFilter)
Syntax:
com.ibi.preparsers.ErrorFilter
Description:
The Error Filter preparser operates on iWay error documents. Error documents are a standardby which iWay Service Manager reports errors back to the user. These documents contain thecomplete incoming message associated with an error. The preparser extracts the originalmessage and passes it into the system for processing. Messages that are identified as notbeing error documents are passed along without any modifications.
In a use case scenario, the Error Filter preparser can be used to obtain the original documentfrom an error document if the user needs to retest a component, but does not have theoriginal document.
Example:
1. Select Error Filter (com.ibi.preparsers.ErrorFilter) from the Type drop-down list and click Next.
The configuration parameters pane opens.
2. Enter a name (for example, XDErrorFilter) and an optional description.
3. Click Finish.
4. Construct an inlet, for example, PreparseInlet, which is associated with a file listener andthe new preparser (XDErrorFilter).
5. Define a simple move route and a default outlet for the channel.
6. Build, deploy, and start the channel.
Available Preparsers
590 Information Builders
7. Create an input document, which contains the following:
<?xml version="1.0" encoding="ISO-8859-1" ?><eda> <error timestamp="2009-05-07T20:55:30Z" source="com.ibi.agents.XDSQLAgent" stage="AGENT">com.microsoft.sqlserver.jdbc.SQLServerException: Invalid column name 'ragv'. <data type="xml"><?xml version="1.0" encoding="ISO-8859-1"?><test> This is a detag preemitter test </test> </data> </error></eda>
When this input document is processed by the channel, the following XML output documentis generated:
<?xml version="1.0" encoding="ISO-8859-1" ?><test>This is a detag preemitter test </test>
Excel Preparser (com.ibi.preparsers.XDExcelpreParser)
Syntax:
com.ibi.preparsers.XDExcelpreParser
Description:
The Excel preparser transforms an Excel worksheet into an XML formatted document. Ifrequired, this preparser uses the header row in the Excel worksheet as XML tags for the dataelements.
In a use case scenario, the Excel preparser is useful when data in Excel must be transformedinto XML.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 591
Note: When using the Excel preparser to convert an Excel document to XML, it changes thedates from mm/dd/yyyy to mm/dd/yy. For example, if the Excel document has a cell format ofDate *03/14/2001 (with an asterisk), the date will convert to 03/14/01. If the cell format isDate 03/14/2001 (without an asterisk), it will convert to the proper format of 03/14/2001 .The image below shows the date selection that will not keep the original format and the dateselection that will keep the original format.
Parameters:
Parameter Description
hasheaders Determines whether the contents of the first row are the names tobe used for subsequent rows.
Example:
1. Select EXCELPreParser (com.ibi.preparsers.XDExcelpreParser) from the Type drop-down listand click Next.
The configuration parameters pane opens.
2. Select true from the hasheaders drop-down list.
3. Click Next.
The name and description pane opens.
4. Enter a name (for example, ExcelPreparser) and an optional description.
5. Click Finish.
Available Preparsers
592 Information Builders
6. Construct an inlet, for example, PreparseInlet, which is associated with a file listener, andthe new preparser (ExcelPreparser).
7. Define a simple move route and a default outlet for the channel.
8. Build, deploy, and start the channel.
9. Create a sample Excel document (for example, document2.xls) with the following data:
Character UseReturn typeExample
Use Example
y year yyyy=2006, yy=06
M Month of year MM=06, MMM=Jun, MMMM=June
w Week in year 26
W Week in month 26
h Day in year (Julian) 26
h Day in month 26
h Day of week 26
h Day of week inmonth
26
The output document [document_out]*.xml will have the following format:
<?xml version="1.0" encoding="ISO-8859-1" ?><workbook> <ism.pdf> <row> <RowNumber>2</RowNumber>
<Character_Use_Return_type_Example>y</Character_Use_Return_type_Example> <Use_>year</Use_> <Example>yyyy=2006,yy=06</Example> </row> <row> <RowNumber>3</RowNumber>
<Character_Use_Return_type_Example>M</Character_Use_Return_type_Example> <Use_>Month of year</Use_> <Example>MM=06, MMM=Jun, MMMM=June</Example> </row> <row> <RowNumber>4</RowNumber>
2. iWay Preparsers
iWay Service Manager Component Reference Guide 593
<Character_Use_Return_type_Example>w</Character_Use_Return_type_Example> <Use_>Week in year</Use_> <Example>26</Example> </row> <row> <RowNumber>5</RowNumber>
<Character_Use_Return_type_Example>W</Character_Use_Return_type_Example> <Use_>Week in month</Use_> <Example>26</Example> </row> <row> <RowNumber>6</RowNumber>
<Character_Use_Return_type_Example>h</Character_Use_Return_type_Example> <Use_>Day in year (Julian)</Use_> <Example>26</Example> </row> <row> <RowNumber>7</RowNumber>
<Character_Use_Return_type_Example>h</Character_Use_Return_type_Example> <Use_>Day in month</Use_> <Example>26</Example> </row> <row> <RowNumber>8</RowNumber>
<Character_Use_Return_type_Example>h</Character_Use_Return_type_Example> <Use_>Day of week</Use_> <Example>26</Example> </row> <row> <RowNumber>9</RowNumber>
<Character_Use_Return_type_Example>h</Character_Use_Return_type_Example> <Use_>Day of week in month</Use_> <Example>26</Example> </row> </ism.pdf></workbook>
ExtractPreparser (com.ibi.preparsers.XDExtractPreparser)
Syntax:
com.ibi.preparsers.XDExtractPreparser
Available Preparsers
594 Information Builders
Description:
Compressed files, such as .zip or TAR/GZ, can be decompressed using this preparser. Eachentry in the compressed file is presented sequentially to the channel for processing. Forexample, a .zip file containing a group of related HL7 documents could process thosedocuments one at a time as if they had arrived on the channel individually. All entries in the fileare presented on the same thread.
Parameters:
Parameter Description
Data Each decompressed file is presented as a Service Manager document.
Signal The signal option causes the preparser to decompress the entry to afile system location, and present the location in a Service ManagerSignal document and Special Registers. The application can elect toread the file if needed using agents such as XDFileOpsAgent andXDFileReadAgent. The channel should delete the file as part ofprocessing the file.
Stream The preparser can emit a decompressed file in stream format. Thispresents a single access stream for each entry in the archive (even ifthe archive is a single compressed file).
The preparser appears as any streaming preparser with an end of stream signal(<batch>EOT</batch>) document following the final decompressed file. The EOS signal of thepreparser is not associated with the individual file(s) streams. Rather, the EOS signalrepresents the end of the decompression process of the archive file. The channel may elect tohandle the end of stream if desired.
Special Registers
The following table lists and describes the Service Manager Special Registers that are set bythe preparser with each decompressed entry.
Special RegisterName
Description
archive Name of the archive file.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 595
Special RegisterName
Description
source File name and directory path.
If you select the Signal option, the file will be decompressed to thefile system with Service Manager, especially if the register containsthe absolute path of the file.
However, if you select either the Data or Stream option, then theregister will represent the directory structure within the archive file.
parent Directory that contains the file (or missing if there is no parentdirectory)
basename The file name without extension.
extension Only the file extension.
filename The file name and extension without a parent directory.
msgsize Size of the decompressed file.
Notes:
To maintain backwards compatibility for simple .zip compressed files, the File listener can beused to decompress this type of file upon receipt of the file. However the File listener is notcapable of decompressing anything other than .zip files.
This preparser is a streaming preparser. What this means is that one file (in this case the .ziparchive) is broken down into separate documents each representing a file contained in thearchive. For example, if the user is configuring a File listener channel to process the archivefile and uses the default.outlet as the channel outlet, then each extracted file is emitted to theconfigured Destination by default and will have the name of the archive (for example,archive.tar) not the name of the archive's extracted file.
If the user is required to extract the files to the file system of iSM using the output.defaultchannel outlet, then the File listener's configuration for Destination must be configured, asshown in the following image.
Available Preparsers
596 Information Builders
The back-tick character (`) is used by iSM to delay the evaluation of the iFL function SREG untilruntime. If the back-tick character is excluded, then the iFL evaluation is performed when thelistener is configured. This is very important to remember because the SREG source is only setwhen the .zip archive file is extracted. It is also important to remember the setting of the DataFormat parameter for this preparser and how the iSM SREGs are set:
Data Format Special Register
data source
This SREG contains the archived file's path which included thearchived file's directory structure. Therefore, if the archived file isdata/file1.xml when iSM evaluated the iFL c:/temp/SREG(source), the resulting Destination path is returned as c:/temp/out/data/file1.xml.
stream source
Like data this SREG contains the archived file's path which includedthe archived file's directory structure. Therefore if the archived file isdata/file1.xml when iSM evaluated the iFL c:/temp/SREG(source), the resulting Destination path is returned as c:/temp/out/data/file1.xml.
signal source
Unlike data and stream this SREG contains the actual path to theextracted archived file on the iSM file system. Using the iFL c:/temp/SREG(source) will generate an invalid destination.
filename
This SREG contains the extracted file's name and extension (if oneexists) only. If the user wants to save the iSM Signal document in theDestination, then the iFL must be changed to c:/temp/out/SREG(filename) when iSM evaluates the iFL and returns c:/temp/out/file1.xml.
The user can also provide an outlet that contains the File emitter. Using an outlet other thanoutput.default overrides the Destination parameter in favor of the outlet's File Emitterconfiguration. The use of iFL and SREGs would mirror the File listener's Destination parameterwithout the back-tick character. The back-tick character is not required at this point becausethe iSM SREGs already reflect the information about the archive's extracted file.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 597
Configuring the Extract Preparser
The following image shows the configuration screen for the Extract preparser.
The following table lists and describes the options in the Data Format drop-down list.
Parameter Description
Data The decompressed data is moved directly into the document.
This option takes up the most memory and may not beappropriate for decompressed files larger than a few megabytes.
Signal The decompressed file is stored on the file system of ServiceManager and a Signal document containing the information andlocation of the file is created.
This option takes up only the amount of memory needed for thesignal document itself. You can then obtain the location of thefile from the Signal document.
Note: You are responsible for deleting (if desired) thedecompressed archive file(s).
Stream The decompressed InputStream of the file is stored in thedocument. A Signal document is created containing informationabout the decompressed file.
This option takes up only the amount of memory needed for thesignal document itself and the data stream of the decompressedfile.
Available Preparsers
598 Information Builders
HIPAAPreParser (com.ibi.preparsers.XDHIPAAPreParser)
Syntax:
com.ibi.preparsers.XDEDIFACTPreParser
Description:
The HIPAAPreParser transforms a HIPAA document into a HIPAA XML document.
Note: The HIPAAPreParser is deprecated. As an alternative, it is recommended to use theHIPAASplitterPreParser (HIPAASplitPP)
HTTP Preparser (com.ibi.preparsers.XDHTTPpreParser)
Syntax:
com.ibi.preparsers.XDHTTPpreParser
Description:
The HTTP preparser transforms a key=value query string into an XML string with the GET actionas the root. This preparser can be used to construct an XML document with the HTTPparameters that are being passed as a query string. The HTTP preparser can only be used withan HTTP listener.
In a use case scenario, if you need to generate an XML document with the HTTP requestparameters, the HTTP preparser can be used to transform the HTTP GET request for a webapplication.
Example:
1. Select the HTTP (com.ibi.preparsers.XDHTTPpreParser) preparser from the Type drop-downlist and click Next.
The configuration parameters pane opens.
2. Enter a name (for example, HttpPreparser) and an optional description.
3. Click Finish.
4. Configure an HTTP listener (for example, http) that is listening on port 9984.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 599
5. Construct a simple index.html page. For example:
<html xmlns="urn:schemas-microsoft-com:xslt"><head><title>Posting a File</title></head><body><form id ="f" action="http://TestMachine:8080/newproject/postfile60.html" enctype="multipart/form-data"><input type="file" name="fdata"/></form></body></html>
6. In the Document Root field for the HTTP listener, specify the base directory from which thesample index.html page is served.
7. Construct an inlet, for example, HttpPreparseInlet, which is associated with the HTTPlistener (for example, http) and the new preparser (HttpPreparser).
8. Define a simple move route and a default outlet for the channel.
9. Build, deploy, and start the channel.
10.Invoke the following URL from a web browser:
http://informat-2a8d8e:9984/index.html?value1=4&value2=two
The following output is obtained:
<?xml version="1.0" encoding="ISO-8859-1" ?><post><value1>2</value1><value2>two</value2></post>
Inflate Preparser (com.ibi.preparsers.XDInflate)
Syntax:
com.ibi.preparsers.XDInflate
Description:
The Inflate preparser inflates data produced by the Deflate preemitter.
An example where the Deflate preemitter could be used is when a large file (for example, 5 MBin size) must be sent by email using an Email emitter. In this scenario, the destination emailserver does not accept messages that are greater than 3 MB in size. The Deflate preemittercould be used before the Email emitter to send the message in an email. The Inflate preparsercould be used once the email is read through an Email listener and subsequently picked up bythe Inflate preparser in the channel.
Available Preparsers
600 Information Builders
Example:
1. Select the Inflate (com.ibi.preparsers.XDInflate) preparser from the Type drop-down list andclick Next.
The configuration parameters pane opens.
2. Enter a name (for example, InflatePreparser) and an optional description.
3. Click Finish.
4. Define a simple move route and a default outlet for the channel.
5. Construct an inlet, for example, PreparseInlet, which is associated with a file listener andthe new preparser (InflatePreparser) to enclose each split flat file into an XML file.
6. Construct a channel (for example, Inflate).
7. Build, deploy, and start the Inflate channel.
The input file for this channel must be a deflated (compressed) document.
JMS Object Preparser (com.ibi.preparsers.XDJMSObjectPreParser)
Syntax:
com.ibi.preparsers.XDJMSObjectPreParser
Description:
The XDJMSObjectPreParser is used to convert a JMS ObjectMessage to a suitable iSMmessage. While the server can deal with most message type automatically, it needsapplication programming assistance to deal with the generic ObjectMessage. This preparser oran extension of it must be invoked by the channel to manage the ObjectMessage retrievedfrom the JMS Queue or Topic.
Parameters:
Parameter Description
Root Tag Root tag of the output XML document. If notspecified, the channel name will be used.
Example:
Procedure: How to Use the JMS Object Preparser
1. Select the JMS Object Preparser (com.ibi.preparsers.XDJMSObjectPreParser) from theType drop-down list and click Next.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 601
The configuration parameters pane opens.
2. Enter JMSOBJ as a value for the Root Tag parameter and click Next.The name and description pane opens.
3. Enter a name for the new JMS Object preparser and an optional description.
4. Click Finish.
This JMS Object preparser will produce an XML document representing the ObjectMessagethat was retrieved from the JMS Queue or Topic.
Below is a sample document returned by the XDJMSObjectPreParser.
<JMSOBJ type="object"> <JMSOBJ> <object name="test.TestSerial"/> <test.TestSerial userObjectConversion="default"> <fields> <field name="serialVersionUID">private static final long TestSerial.serialVersionUID</field> <field name="count">private int TestSerial.count</field> </fields> <methods> <method name="bumpCount">public void TestSerial.bumpBount()</method> <method name="getCount">public int TestSerial.getCount()</method> </methods> </test.TestSerial> </JMSOBJ></JMSOBJ>
For more information on the JMS Object preparser, see the iWay Service Manager ProtocolGuide .
Legacy Record Preparser (com.ibi.preparsers.LegacyRecordPreparser)
Syntax:
com.ibi.preparsers.LegacyRecordPreparser
Description:
Converts an incoming legacy flat file (copybook) into an XML file. For more information, see theiWay Transaction Adapter for CICS User's Guide.
Available Preparsers
602 Information Builders
Parameters:
Parameter Description
Copybook Location * The full path to the COBOL copybook.
Input Encoding * The Internet Assigned Numbers Authority (IANA) character set forthe legacy record. You can select a value from the drop-down listor type the name of a code page directly in the field. By default,the Leave option is selected, which uses the default encoding ofthe listener.
Full FD? * If set to true, then the COBOL record headings appear in theoutput XML. By default, false is selected.
Multiple Records? * If set to true, then multiple CommArea records are produced if theinput byte array is larger than the copybook size. By default, falseis selected.
Multipart Preparser (com.ibi.preparsers.XDMultiPart)
Syntax:
com.ibi.preparsers.XDMultiPart
Description:
The Multipart preparser divides multipart documents for later use. This preparser must be lastin the chain. When used, the multipart message is divided so that the body of the message ispart 0 and subsequent attachments are 1 to n. The multipart object is carried in the XMLdocument (XDDocument) and can be retrieved and interrogated by your own business serviceto obtain the individual parts for processing. If the body is a MIME type of _/XML, it is parsedand carried as an XML document.
In a use case scenario, an incoming document can consist of an email where specificinformation from the email message must be extracted, such as the attachment headers andthe attachment file name. The Multipart preparser can transform the message into a multipartformat that can be used to call functions on the email, such as _attcnt() (attachment count).
Example:
1. Select the Multi Part (com.ibi.preparsers.XDMultiPartpreparser) preparser from the Typedrop-down list and click Next.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 603
The configuration parameters pane opens.
2. Enter a name (for example, iwMULTIPART) and an optional description.
3. Click Finish.
4. Construct an inlet, for example, AttInlet, which is associated with a file listener and the newpreparser (iwMULTIPART).
5. Define a simple move route for the channel.
6. Test with COND to test the attachment header in the multipart document. Let the COND be:
COND(_atthdr(2,'Content-Id','mydata'),eq, 'mydata1')
7. Define an outlet, which is associated with a file emitter that emits an output document (forexample, a#.txt) to a specified output directory.
8. Build, deploy, and start the channel.
9. Create a multipart input document, which is generated from an email attachment. Forexample:
content-type: multipart/mixed; boundary="----=_Part_5_23514719.1234266657921"content-length: 571mime-version: 1.0message-id: <17237217.1234266657984.JavaMail.ksugauchi@kmaruyama>------=_Part_5_23514719.1234266657921Content-Type: application/xmlContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=a.xml<a>a</a>------=_Part_5_23514719.1234266657921Content-Type: text/documentContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=b.xmlContent-Id: mydata1<b>b</b>------=_Part_5_23514719.1234266657921Content-Type: text/documentContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=c.xmlContent-Id: mydata2<c>c</c>------=_Part_5_23514719.1234266657921-
When this multipart input document is processed by the channel, an output XML document(a#.txt) is generated with the following contents:
<?xml version="1.0" encoding="ISO-8859-1" ?>
Available Preparsers
604 Information Builders
Multipart for nHTTP Preparser (com.ibi.preparsers.XDMultiPartForNHTTP)
Syntax:
com.ibi.preparsers.XDMultiPartForNHTTP
Description:
The Multipart for nHTTP preparser divides multipart documents into body and attachments.This preparser can also be used with an nHTTP listener. This preparser must be last in thechain. When used, the multipart message is broken up so that the body of the multipartmessage is part 0 and subsequent attachments are 1 to n.
In a use case scenario, the Multipart for nHTTP preparser is useful when the incomingmessage is a multipart document and the headers and attachment portions of the documentneed to be extracted from the document for additional message processing.
Parameters:
Parameter Description
Payload HeaderNamespace
A special register namespace into which any headers on theextracted body part will be stored as HDR registers. If notsupplied, body part headers will be saved in the defaultnamespace.
Message HeaderNamespace
A special register namespace where message headers can befound. If not supplied, HDR registers from the default namespacewill be used.
Keep Message Flat Determines whether to keep the body of the message as an arrayof bytes. Select true or false from the drop-down list.
Example:
1. Select the Multi Part For NHTTP (com.ibi.preparsers.XDMultiPartForNHTTP) preparser fromthe Type drop-down list and click Next.
The configuration parameters pane opens.
2. Leave the Payload Header Namespace and Message Header Namespace fields blank.
3. Select false from the Keep Message Flat drop-down list and click Next.
The name and description pane opens.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 605
4. Enter a name (for example, nhttpmultipart) and an optional description.
5. Click Finish.
6. Construct an inlet, for example, FileInlet, which is associated with a file listener and thenew preparser (nhttpmultipart).
7. Define a simple move route.
8. Define an outlet that consists of a File emitter, which emits the output document(outmpart*.xml) to an output directory.
9. Build, deploy, and start the channel.
10.Use a multipart document for the input, which is generated from an email attachment. Forexample:
content-type: multipart/mixed; boundary="----=_Part_5_23514719.1234266657921"content-length: 571mime-version: 1.0message-id: <17237217.1234266657984.JavaMail.soumya@ibi>------=_Part_5_23514719.1234266657921Content-Type: application/xmlContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=a.xml<a>a</a>------=_Part_5_23514719.1234266657921Content-Type: text/documentContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=b.xmlContent-Id: mydata1<b>b</b>------=_Part_5_23514719.1234266657921Content-Type: text/documentContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=c.xmlContent-Id: mydata2<c>c</c>------=_Part_5_23514719.1234266657921-
When this input document is processed by the channel, an output document(outmpart*.xml) is generated with the following contents:
<?xml version="1.0" encoding="ISO-8859-1" ?>
PGP Decrypt Preparser (com.ibi.preparsers.PGPDecrypt)
Syntax:
com.ibi.preparsers.PGPDecrypt
Available Preparsers
606 Information Builders
Description:
The PGP Decrypt preparser decrypts an incoming message on the channel into the originalunencrypted format. For more information on how to configure the PGP Decrypt preparser, seethe iWay Service Manager Extensions User's Guide.
PGP Verify Signiture Only (com.ibi.preparsers.XDPGPVerifySignPreparser)
Syntax:
com.ibi.preparsers.XDPGPVerifySignPreparser
Description:
Verifies a signed PGP message. This agent is deprecated in favor of PGPDecryptAgent.
Parameters:
Parameter Description
Public Key Ring the location of the public key ring containing the signature publickeys.
Replace characters on a one for one basis Preparser (com.ibi.preparsers.XDCharRepl)
Syntax:
com.ibi.preparsers.XDCharRepl
Description:
Replaces characters on a one for one basis.
Parameters:
Parameter Description
Input A string of individual characters to replace. (|\0x|\n|\t)*
Replace with A string of characters to replace input with. Count must match thenumber in the input. (|\0x|\n|\t)*
End of LineConversion
Replaces carriage return (0x0d) and line feed (0x0a) patterns.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 607
Smime Preparser (com.ibi.smime.XDSmimePreParser)
Syntax:
com.ibi.smime.XDSmimePreParser
Description:
Reads S/MIME messages.
Parameters:
Parameter Description
S/MIME KeystoreProvider *
The provider for the keystore used to decrypt incoming messages.
S/MIME TrustStoreProvider *
The provider for the keystore containing the S/MIME CertificateAuthorities.
S/MIME CertificateStore Providers
A comma-separated list of Keystore, Directory CertStore or LDAPproviders for the certificate stores used to complete signercertificate chains when the signed message contains fewercertificates than needed.
S/MIME Signature JCEProvider *
The JCE Provider for S/MIME Signature Cryptography services.
S/MIME PKIX JCEProvider
The JCE Provider for S/MIME PKIX services. If left blank, thedefault JCE provider for PKIX will be used.
S/MIME DecryptionKey Alias
The private key alias used to decrypt incoming messages.
S/MIME DecryptionKey Password
The password for decryption private key. If left blank, thepassword for accessing the keystore will be used.
Enforce KeyUsageExtension
Determines how the KeyUsage Extension is verified when presentin the certificate. The requirement for S/MIME digital signatures isfollowed by the requirement for S/MIME encryption, separated bya slash.
Enable CertificateRevocation
Enables CRL or OCSP checking of the signer certificates.
Available Preparsers
608 Information Builders
Parameter Description
OCSP Responder The name of the OCSP Responder provider. This verifies thestatus of certificates online instead of relying on CertificateRevocation Lists.
Unrecognized CertsLocation
The directory to store unrecognized certificates found in S/MIMEmessages.
Default ContentTransfer Encoding
The default encoding when the Content-Transfer-Encoding isabsent. For S/MIME, this is 7bit. For AS2, this must be set tobinary.
Payload HeaderNamespace
The special register namespace into which any headers on theextracted body part will be stored as HDR registers. If notsupplied, body part headers will be saved in the defaultnamespace.
Keep Message Flat Keeps the body of the message as an array of bytes.
SOAP Preparser (com.ibi.preparsers.XDSOAPPreParser)
Syntax:
com.ibi.preparsers.XDSOAPPreParser
Description:
The SOAP preparser accepts a SOAP message from any JMS listener and removes the SOAPportion from the envelope. The preparser then parses the SOAP body by iterating through allchild nodes and constructs an XML document (XDDocument), which is used to pass betweencomponents in a process flow. For more information on how to configure the SOAP preparser,see the iWay Service Manager Extensions User's Guide.
SREG Preparser (com.ibi.preparsers.XDSREGPreparser)
Syntax:
com.ibi.preparsers.XDSREGPreparser
Description:
The SREG preparser sets one or more special registers of a given type.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 609
In a use case scenario, the SREG preparser is useful when the incoming message hasvariables associated with it and if changes need to be made to the special registers set at aglobal level, application level, or server level.
Parameters:
Parameter Description
Type of variable Type of variable (headers appear in emitted documents as headervalues). Type del to delete the register. Select one of the followingoptions from the drop-down list:
User
Document
Header
Metric
Scope of variable Determines at what level the variable is defined and thereforecontrols its life span and visibility. Select one of the followingoptions from the drop-down list:
Message
Channel
Server
Lock Name Name of a serialization lock for this set of register operations.
Call at EOS? In streaming a last call is made after the last document.Determines whether this service should be called.
Example:
1. Select the SREG (com.ibi.preparsers.XDSREGPreparser) preparser from the Type drop-downlist and click Next.
The configuration parameters pane opens.
2. From the Type of variable drop-down list, select User.
3. From the Scope of variable drop-down list, select Message.
Available Preparsers
610 Information Builders
4. Leave the Lock Name field blank.
5. Select false from the Call at EOS? drop-down list and click Next.
The name and description pane opens.
6. Enter a name (for example, sregpreparser) and an optional description.
7. Click Finish.
8. Construct an inlet, for example, FileInlet, which is associated with a file listener and thenew preparser (sregpreparser).
9. Define a simple move route.
10.Define an outlet that consists of a File emitter, which emits the output document(outmpart*.xml) to an output directory.
11.Build, deploy, and start the channel.
12.Create a simple input XML document, for example:
<test/>
SWIFTPreParser (com.ibi.preparsers.SwiftPreParser)
Syntax:
com.ibi.preparsers.SwiftPreParser
Description:
The SWIFTPreParser converts an incoming SWIFT message to XML format. If you require aSWIFT Validation Report, the SWIFTPreParser must be used. If you do not require a SWIFTValidation Report, the SWIFTPreParser or XDSWIFTPreParser can be used. When theSWIFTPreParser is used, an Ebix must be attached to the iSM channel. For more informationon how to configure the SWIFTPreParser, see iWay Integration Solution for SWIFT User's Guide.
SWIFTAckPreParser (com.ibi.preparsers.SwiftBPP)
Syntax:
com.ibi.preparsers.SwiftBPP
Description:
The SWIFTAckPreParser processes transforms MT021 Systems Messages to XML-formatteddocuments. For more information on how to configure the SWIFTAckPreParser, see the iWayIntegration Solution for SWIFT User's Guide.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 611
SWIFTSystemMessagePreParser (com.ibi.preparsers.XDSWIFTSysMsgPreParser)
Syntax:
com.ibi.preparsers.XDSWIFTSysMsgPreParser
Description:
The XDSWIFTSysMsgPreParser Transforms SWIFT User-to-System and System-to-User FINFormat Messages to XML formatted documents. For more information on how to configure theXDSWIFTSysMsgPreParser, see the iWay Integration Solution for SWIFT User's Guide.
Transform Preparser (com.ibi.preparsers.XDTransformPP)
Syntax:
com.ibi.preparsers.XDTransformPP
Description:
The Transform preparser.
Parameters:
Parameter Description
Transform name * The name of the defined transform to execute.
Expected Input The type of document expected to be received for transform.
Document type The type of document being emitted by the transformation.
Engine The type of transformation.
ParameterNamespace
The special register namespace from which XSLT stylesheetparameters will be taken. The default is to execute the XSLTtransform with no stylesheet parameters defined. The ParameterNamespace is unused by the iWay Transformer engine.
Trim Determines whether data should be trimmed before transforming.
Error Status Output In the event of an error, determines the form of the output to beemitted from the service.
Error Masks
Available Preparsers
612 Information Builders
Parameter Description
Input Side Mask intermediate errors on input side of iWay transformation.The special register 'iway.transform.errormask.in.format' whereformat is the input format (for example, 'fwf'), can also control themasking.
Output Side Mask intermediate errors on output side of iWay transformation.The special register 'iway.transform.errormask.out.format' whereformat is the output format (for example, 'fwf'), can also controlthe masking.
Unmarshalls a message Preparser (com.ibi.preparsers.XDUnmarshall)
Syntax:
com.ibi.preparsers.XDUnmarshall
Description:
Unmarshalls a document and context to send to from a marshalling channel. This allowsmessages to be sent cross-configuration.
Parameters:
Parameter Description
Use encryption * Set to true if the marshall and unmarshall messages are to beencrypted. Both the marshalling and unmarshalling channels mustbe set the same way.
AES Key If using an encrypted channel, set the AES key (maximum 16characters) to be used.
XDSWIFTPreParser (com.ibi.preparsers.XDSWIFTpreParser)
Syntax:
com.ibi.preparsers.XDSWIFTpreParser
2. iWay Preparsers
iWay Service Manager Component Reference Guide 613
Description:
The XDSWIFTPreParser converts an incoming SWIFT message to XML format. Use theXDSWIFTPreParser only if you do not require a SWIFT Validation Report. When theXDSWIFTPreParser is used, an Ebix must be attached to the iSM channel. For more informationon how to configure the XDSWIFTPreParser, see the iWay Integration Solution for SWIFT User'sGuide.
Streaming Preparsers
To handle large files, iWay Service Manager provides a streaming interface. You can usestreaming preparsers only with the HTTP, File, and JMS adapters. To use a streamingpreparser in conjunction with other preparsers, you must define it as the first preparser in thechain. The following streaming preparsers are available:
Concatenated XML Document Stream Preparser
Delimited Value Stream Preparser
Flat Stream Preparser
Concatenated XML Document Stream Preparser (com.ibi.preparsers.XDXMLStreamPreParser)
Syntax:
com.ibi.preparsers.XDXMLStreamPreParser
The Concatenated XML Document Stream preparser accepts input files containing multipleXML documents and creates single XML documents from the original input file.
For example, this preparser can process the following batch of XML documents:
<?xml version="1.0" encoding="UTF-8"?><hi>This is my document</hi><hi>This is my document</hi><hi>This is my document</hi><hi>This is my document</hi>
Procedure: How to Add a Concatenated XML Document Stream Preparser
To define a Concatenated XML Document Stream preparser:
1. In the left console pane of the Registry menu, select Preparsers.
The Preparsers pane opens.
2. Click Add.The Preparser Type pane opens.
Streaming Preparsers
614 Information Builders
3. In the Type field, select XML Stream PreParser {com.ibi.preparsers.XDXMLStreamPreParser}and click Next.
4. Provide a name and a description (optional) for the preparser, and click Finish.
The preparser is added to the list in the Preparsers pane.
Reference: XML Stream Preparser
The incoming XML document is divided into smaller documents, broken at a specifiedrepeating child, for example:
<a><b><c>one</c><b><b><c>two</c></b></a>
With a split specified as a/b, it results in three passes through the configured flow.
Pass 1
<a><b><c>one</c></b></a>
Pass 2
<a><b><c>two</c></b></a>
Pass 3
No data.
Create Stream Doc PP (com.ibi.preparsers.CreateStreamDocPP)
Syntax:
com.ibi.preparsers.CreateStreamDocPP
Description:
The Create Stream Doc PP preparser provides document stream pass through.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 615
Parameters:
Parameter Description
Name * The name of the new Preparser object definition.
Description The description for the new Preparser object definition.
Delimited Value Stream Preparser (com.ibi.preparsers.XDDelValStream)
Syntax:
com.ibi.preparsers.XDDelValStream
Description:
The Delimited Value Stream preparser is a delimited value handler, which is useful when theincoming message consists of a delimited value stream such as lines of comma separatedvalues. The first line can optionally hold field names (DIF format input). An XML document isgenerated from the input with a child node of each row, and children of that row in turn foreach value.
In a use case scenario, the Delimited Value Stream preparser can be used when an incomingmessage consists of a batch of flat files that are delimited by a special character, such as '|'.This message also needs to be converted to XML format.
Parameters:
Parameter Description
Root name * The element name of the outer tag.
Dif * Determines whether the first line should be treated as an elementname.
Delimiter * Determines the delimiter to be used. Select comma or tab fromthe drop-down list, or enter a specific character (for example, $)directly in the field. This is a single character, and can bespecified in hex form as \xvv where vv is a hexadecimal valuespecification (for example, \x31).
Rows The number of rows in each document.
Streaming Preparsers
616 Information Builders
Parameter Description
Trim values Determines whether all values should be trimmed.
Header Determines whether the first line should be ignored.
Quotes Determines whether surrounding quotes should be eliminated.
Empty elements Determines whether empty elements at the right should beeliminated.
Example:
1. Select the Del Val Stream (com.ibi.preparsers.XDDelValStream) preparser from the Typedrop-down list and click Next.
The configuration parameters pane opens.
2. Enter testroot in the Root name field.
3. Select false from the Dif field drop-down list.
4. Enter | in the Delimiter field and leave the default values selected for all the remainingfields.
5. Click Next.
The name and description pane opens.
6. Enter a name (for example, DelvalStreamPreparser) and an optional description.
7. Click Finish.
8. Construct an inlet, for example, PreparseInlet, which is associated with a file listener andthe new preparser (DelvalStreamPreparser).
9. Define a simple move route and a default outlet for the channel.
10.Build, deploy, and start the channel.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 617
11.Create a simple input text document (for example, TestData.txt), which contains thefollowing:
02|penny|copper|$0.0103|one dollar|paper|$1.0004|five dollars|paper|$5.0005|ten dollars|paper|$10.0006|twenty dollars|paper|$20.00
When this input document is processed by the channel, an output XML document isgenerated with the following contents:
<?xml version="1.0" encoding="ISO-8859-1" ?><testroot RowCount="4"> <row rowcnt="1"> <_nb02>03</_nb02> <penny>one dollar</penny> <copper>paper</copper> <_dlr0.01>$1.00</_dlr0.01> </row> <row rowcnt="2"> <_nb02>04</_nb02> <penny>five dollars</penny> <copper>paper</copper> <_dlr0.01>$5.00</_dlr0.01> </row> <row rowcnt="3"> <_nb02>05</_nb02> <penny>ten dollars</penny> <copper>paper</copper> <_dlr0.01>$10.00</_dlr0.01> </row> <row rowcnt="4"> <_nb02>06</_nb02> <penny>twenty dollars</penny> <copper>paper</copper> <_dlr0.01>$20.00</_dlr0.01> </row></testroot>
Flat Stream Preparser (com.ibi.preparsers.XDFlatStreamPreParser)
Syntax:
com.ibi.preparsers.XDFlatStreamPreParser
Description:
The Flat Stream preparser is used to split non-XML messages based on a recognizedcharacter. During configuration, the character can be specified as any character, a specialcharacter, or a HEX character.
Streaming Preparsers
618 Information Builders
The Flat Stream preparser is useful when handling individual lines of a large, delimited file.
Parameters:
Parameter Description
Delimiters List of possible delimiters (default is new line). Possible valuesinclude:
X. Any character.
\n. New line.
\r. Carriage return.
\t. Tab.
\xab. ab are HEX characters, such as 0A.
Example:
1. Select the Flat Stream (com.ibi.preparsers.XDFlatStreamPreParser) preparser from the Typedrop-down list and click Next.
The configuration parameters pane opens.
2. Enter \r as a value for the Delimiters parameter and click Next.
The name and description pane opens.
3. Enter a name (for example, FlatStreamPreparser) and an optional description.
4. Click Finish.
5. Construct an inlet, for example, PreparseInlet, which is associated with a file listener, thenew preparser (FlatStreamPreparser), and an En Tag preparser to enclose each split flat fileinto an XML file.
6. Define a simple move route and a default outlet for the channel.
7. Build, deploy, and start the channel.
8. Create a simple input text document (for example, document2.txt), which contains thefollowing:
First LineSecond LineThird LineFourth Line
2. iWay Preparsers
iWay Service Manager Component Reference Guide 619
When this input document is processed by the channel, the output document(document2_1.txt) contains the following:
<?xml version="1.0" encoding="ISO-8859-1" ?><testroot>First Line</testroot>
The output document (document2_2.txt) contains the following:
<?xml version="1.0" encoding="ISO-8859-1" ?><testroot>Second Line</testroot>
The remaining output follows the same format.
Stream Passthrough (com.ibi.preparsers.XDStreamPassthrough)
Syntax:
com.ibi.preparsers.XDStreamPassthrough
Description:
The Stream Passthrough preparser passes input stream through to the next process withoutdoing any processing.
Parameters:
Parameter Description
Name * The name of the new Preparser object definition.
Description The description for the new Preparser object definition.
Splitter Preparsers
Splitter preparsers divide an incoming document into smaller pieces based on a specifieddelimiter. The incoming document could be an XML document or a flat file. Different preparsershandle different types of incoming documents. All streaming preparsers are splitter preparsers,but all splitter preparsers are not streaming preparsers. The following splitter preparsers areavailable:
Delimited Value Splitter Preparser
XML Splitter Preparser
Splitter Preparsers
620 Information Builders
Delimited Value Splitter Preparser (com.ibi.preparsers.XDDelVal)
Syntax:
com.ibi.preparsers.XDDelVal
Description:
The Delimited Value preparser is a delimited value handler, which is useful when the incomingmessage consists of a delimited value stream such as lines of comma separated values. Thefirst line can optionally hold field names (DIF format input). An XML document is generatedfrom the input with a child node of each row, and children of that row in turn for each value.
In a use case scenario, the Delimited Value preparser can be used when an incomingmessage consists of a batch of flat files that are delimited by a special character, such as '|'.This message also needs to be converted to XML format.
Parameters:
Parameter Description
Root name * The element name of the outer tag.
Dif * Determines whether the first line should be treated as an elementname.
Delimiter * Determines the delimiter to be used. Select comma or tab fromthe drop-down list, or enter a specific character (for example, $)directly in the field. This is a single character, and can bespecified in hex form as \xvv where vv is a hexadecimal valuespecification (for example, \x31).
Trim values Determines whether all values should be trimmed.
Quotes Determines whether surrounding quotes should be eliminated.
Empty elements Determines whether empty elements at the right should beeliminated.
Include blanks * Determines whether a blank line should be treated as a row withall null elements, or ignored.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 621
Example:
1. Select the Del Val (com.ibi.preparsers.XDDelVal) preparser from the Type drop-down list andclick Next.
The configuration parameters pane opens.
2. Enter testroot in the Root name field.
3. Select false from the Dif field drop-down list.
4. Enter | in the Delimiter field and leave the default values selected for all the remainingfields.
5. Click Next.
The name and description pane opens.
6. Enter a name (for example, DelvalPreparser) and an optional description.
7. Click Finish.
8. Construct an inlet, for example, PreparseInlet, which is associated with a file listener andthe new preparser (DelvalPreparser).
9. Define a simple move route and a default outlet for the channel.
10.Build, deploy, and start the channel.
Splitter Preparsers
622 Information Builders
11.Create a simple input text document (for example, TestData.txt), which contains thefollowing:
02|penny|copper|$0.0103|one dollar|paper|$1.0004|five dollars|paper|$5.0005|ten dollars|paper|$10.0006|twenty dollars|paper|$20.00
When this input document is processed by the channel, an output XML document isgenerated with the following contents:
<?xml version="1.0" encoding="ISO-8859-1" ?><testroot RowCount="4"> <row rowcnt="1"> <_nb02>03</_nb02> <penny>one dollar</penny> <copper>paper</copper> <_dlr0.01>$1.00</_dlr0.01> </row> <row rowcnt="2"> <_nb02>04</_nb02> <penny>five dollars</penny> <copper>paper</copper> <_dlr0.01>$5.00</_dlr0.01> </row> <row rowcnt="3"> <_nb02>05</_nb02> <penny>ten dollars</penny> <copper>paper</copper> <_dlr0.01>$10.00</_dlr0.01> </row> <row rowcnt="4"> <_nb02>06</_nb02> <penny>twenty dollars</penny> <copper>paper</copper> <_dlr0.01>$20.00</_dlr0.01> </row></testroot>
EDIBatchSplitter Preparser (com.ibi.preparsers.XDEDIBatchSplitter)
Syntax:
com.ibi.preparsers.XDEDIBatchSplitter
Description:
Description: The EDIBatchSplitter preparser splits a batch of EDI documents. For moreinformation on how to configure the EDIBatchSplitter preparser, see the iWay IntegrationSolution for EDI User's Guide.
2. iWay Preparsers
iWay Service Manager Component Reference Guide 623
EDIFACTBatchSplitterPreparser (com.ibi.preparsers.XDEDIFACTBatchSplitter)
Syntax:
com.ibi.preparsers.XDEDIFACTBatchSplitter
Description:
The EDIFACTBatchSplitter preparser splits EDIFACT input files that contain multipletransactions or envelopes. This preparser should be used with the EDIFACTPreParser. For moreinformation on how to configure the EDIFACTBatchSplitter preparser, see the iWay IntegrationSolution for UN/EDIFACT User's Guide.
EDIH7BatchSplitter (com.ibi.preparsers.EDIHL7BatchSplitter)
Syntax:
com.ibi.preparsers.EDISplitPP
Description:
The EDIH7BatchSplitter preparser splits a batch of HL7 messages.
Parameters:
Parameter Description
Timestamp Writes a timestamp to the log file.
EDIX12SplitterPreParser (com.ibi.preparsers.EDIHL7BatchSplitter)
Syntax:
com.ibi.preparsers.EDIHL7BatchSplitter
Description:
The EDIX12SplitterPreParser parses an EDI input file that contains one or more interchanges(ISA) and multiple documents, and creates multiple XML output files. One XML output file isproduced for each document. For example, if the EDI input file contains three documentswithin one ISA, the EDIX12SplitterPreParser creates three XML output files, one per document.For more information on how to configure the EDIX12SplitterPreParser, see the iWay IntegrationSolution for EDI User's Guide.
Splitter Preparsers
624 Information Builders
HIPAABatchSplitter (com.ibi.preparsers.XDHIPAABatchSplitter)
Syntax:
com.ibi.preparsers.XDHIPAABatchSplitter
Description:
The HIPAABatchSplitter splits a batch of HIPAA documents. For more information on how toconfigure the HIPAABatchSplitter, see the iWay Integration Solution for HIPAA User's Guide.
HIPAASplitterPreParser (com.ibi.preparsers.HIPAASplitPP)
Syntax:
com.ibi.preparsers.HIPAASplitPP
Description:
The HIPAASplitterPreParser parses a HIPAA input file that contains one or more interchanges(ISA) and multiple documents, and creates multiple XML output files. One XML output file isproduced for each document. For example, if the HIPAA input file contains three documentswithin one ISA, the HipaaSplitterPreParser creates three XML output files, one per document.For more information on how to configure the HIPAASplitterPreParser, see the iWay IntegrationSolution for HIPAA User's Guide.
SWIFTBatchSplitter (com.ibi.preparsers.XDSWIFTBatchSplitter)
Syntax:
com.ibi.preparsers.XDSWIFTBatchSplitter
Description:
The SWIFTBatchSplitter preparser is used when the expected inbound SWIFT data containsmultiple SWIFT messages. The SWIFTBatchSplitter splits the input stream and produces byte[]groups as per the predefined splitting logic. For more information on how to configure theSWIFTBatchSplitter, see the iWay Integration Solution for SWIFT User's Guide.
XML Splitter Preparser (com.ibi.preparsers.XDXMLSplit)
Syntax:
com.ibi.preparsers.XDXMLSplit
2. iWay Preparsers
iWay Service Manager Component Reference Guide 625
Description:
The XML Splitter preparser is used to divide an incoming XML document into smallerdocuments at a specified, repeating child.
In a use case scenario, if the incoming XML document is large and has repeating segments,this document could be divided into smaller pieces to improve the speed at which messagesare processed.
Parameters:
Parameter Description
Level string * Define in dot of slash notation, the path to the element on whichto split. An asterisk character (*) specifies any tag at thatelement.
Sequence If set to true, a count attribute is set into each root.
Example:
1. Select the XML Splitter (com.ibi.preparsers.XDXMLSplit) preparser from the Type drop-downlist and click Next.
The configuration parameters pane opens.
2. Enter /a/b in the Level string field.
3. Click Next.
The name and description pane opens.
4. Enter a name (for example, PO.XMLSplit.Preparser) and an optional description.
5. Click Finish.
6. Construct an inlet, for example, OIA.861.PO.Split.Inlet, which is associated with a filelistener and the new splitter preparser (PO.XMLSplit.Preparser).
7. Define a simple move route and a default outlet for the channel.
8. Build, deploy, and start the channel.
Splitter Preparsers
626 Information Builders
9. Create a simple input text document (for example, a.xml), which contains the following:
<a> <b name="b1"> <c>value of input element a/b@name=b1/c is 1</c> <c>value of input element a/b@name=b1/c is 2</c> </b> <b name="b2"> <c>value of input element a/b@name=b2/c is 3</c> <c>value of input element a/b@name=b2/c is 4</c> </b></a>
When this input document is processed by the channel, the following output XML documentsare generated:
<?xml version="1.0" encoding="ISO-8859-1" ?><a> <b name="b1"> <c>value of input element a/b@name=b1/c is 1</c> <c>value of input element a/b@name=b1/c is 2</c> </b></a>
<?xml version="1.0" encoding="ISO-8859-1" ?><a> <b name="b2"> <c>value of input element a/b@name=b2/c is 3</c> <c>value of input element a/b@name=b2/c is 4</c> </b></a>
<?xml version="1.0" encoding="ISO-8859-1" ?><batch>EOT</batch>
2. iWay Preparsers
iWay Service Manager Component Reference Guide 627
Splitter Preparsers
628 Information Builders
Chapter3iWay Preemitters
iWay Service Manager includes many predefined preemitters that you can use to convertoutgoing messages into processable documents. You can add these preemitters tosimple or complex business logic configurations using the Administration Console.
For reference purposes, this section lists and describes all the predefined preemittersthat are supplied with iWay Service Manager.
In this chapter:
Overview of Preemitter
Available Preemitters
Constant PE(com.ibi.preemit.XDConstantPE)
Deflate (com.ibi.preemit.XDDeflate)
EDIX12 Preemitter(com.ibi.preemit.XDX12PreEmitter)
Entity Repl Preemitter(com.ibi.preemit.XDEntityRepl)
File read Preemitter(com.ibi.preemit.XDFilePreEmitter)
Flat Delim Preemitter(com.ibi.preemit.XDFlatDelimPreEmitter)
HIPAA Preemitter(com.ibi.preemit.XDHIPAAPreEmitter)
iWay Transformations Preemitter(com.ibi.preemit.XDXMLGpreEmitter)
Legacy Record Preemitter(com.ibi.preemit.LegacyRecordPreemitter)
Marshalls a message Preemitter(com.ibi.preemit.XDMarshall)
Multi Part (com.ibi.preemit.XDMultiPart)
PGPEncrypt Preemitter(com.ibi.preemit.PGPEncrypt)
PGP Sign Only Preemitter(com.ibi.preemit.XDPGPSignPreEmitter)
QA Print (com.ibi.preemit.XDQAPrint)
Remove Outer Tag(com.ibi.preemit.XDDeTag)
Replaced Paired Characters(com.ibi.preemit.XDCharRepl)
SWIFT Preemitter(com.ibi.preemit.SwiftPreEmitter)
UUEncodePreEmitter(com.ibi.preemit.XDUUEncodePreEmitter)
XDEDIFACT Preemitter(com.ibi.preemit.XDEDIFACTPreEmitter)
XDSWIFT Preemitter(com.ibi.preemit.XDSwiftpreEmitter)
iWay Service Manager Component Reference Guide 629
XSL Tpre(com.ibi.preemit.XDXSLTpreEmitter)
Overview of Preemitter
A preemitter is a component that can be called just prior to sending an output document.Normally it is used to convert an XML document into non-XML format. For more information onthe methodology used in writing preemitters, see the iWay Service Manager Programmer'sGuide.
Each preemitter uses a class file that must be located in a directory in the Java classpath.iWay Service Manager includes preemitters that have been preconfigured.
Available Preemitters
The following section provides a comprehensive reference for all the predefined preemittersthat are supplied with iWay Service Manager.
Preemitter Name Class Name Description
CharRepl Preemitter XDCharRepl Replaces paired characters in theinput stream.
ConstantPE Preemitter XDConstantPE Returns a constant document.
Deflate Preemitter XDDeflate Deflates data prior to emit.
Detag Preemitter XDDeTag Removes the outermost tag from theXML document and returns theremainder of the document.
Flat Delim Preemitter XDFlatDelimPreemitter Transforms an XML document into aflat file.
EDIX12 Preemitter XDX12PreEmitter Converts the XML formatted EDIdocument to an EDI-X12 formatteddocument.
EXIX12 Preemitter XDX12PreEmitter Transforms X12 XML document. Formore information, see the iWayIntegration Solution for EDI User'sGuide.
Overview of Preemitter
630 Information Builders
Preemitter Name Class Name Description
HIPAA Preemitter XDHIPAAPreEmitter Converts the XML formatted HIPAAdocument to a HIPAA formatteddocument.
HL7LLP HL7LLP Adds an LLP envelope to HL7messages. For more information, seeiWay Integration Solution for HL7User's Guide.
HL7 Preemitter HL7PreEmitter Converts from XML to HL7 format.For more information, see the iWayIntegration Solution for HL7 User'sGuide.
ISO8583PreEmitter ISO8583PreEmitter Transforms an XML document into anISO 8583 message. This is alsoperformed by the ISO8583 adapter.
Legacy RecordPreemitter
LegacyRecordPreemitter Converts COMMAREA XML nodes tobytes as described by a COBOLcopybook. For more information, seethe iWay Transaction Adapter for CICSUser's Guide.
MultiPart Preemitter XDMultipart Outputs a multipart document fromthe XML document.
PGP Encrypt preemitter PGPEncrypt Encrypts an outgoing message fromthe channel into an encrypted XMLdocument.
QAPrint Preemitter XDQAPrint Emits the input document to a filealong with additional run-timeinformation, such as SpecialRegisters, and so on.
SWIFT Preemitter SwiftPreEmitter Transforms a SWIFT XML documentinto a SWIFT Message.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 631
Preemitter Name Class Name Description
XDEDIFACT Preemitter XDEDIFACTPreEmitter Transforms an EDIFACT XMLdocument into an EDIFACT message.For more information, see the iWayIntegration Solution for UN/EDIFACTUser's Guide.
XDEntityRepl XDEntityRepl Eliminates XML entities (such as <.to < and > to >).
XDHIPAA XDHIPPAPreEmitter Transforms a HIPAA EDIX12 XMLdocument into a HIPAA EDIX12document. For more information, seethe iWay Integration Solution forHIPAA User's Guide.
XDHL7 Preemitter XDHL7NewPreEmitter Transforms a HL7 XML documentinto a HL7 message.
XD SWIFT Preemitter XDSwiftpreEmitter Transforms a SWIFT XML documentinto a SWIFT FIN Message. For moreinformation, see the iWay IntegrationSolution for SWIFT User's Guide.
XML GpreEmitter XDXMLGpreEmitter Transforms output using iWaytransformations tooling.
XSLT Preemitter XDXSLTpreEmitter Converts the XML document into aHTML document using the XSLT fileinput.
XMLtoASN1 preemitter XDXMLtoASN1pe Converts an XML message to ASN.1
Available Preemitters
632 Information Builders
Procedure: How to Add a Preemitter
1. In the left console pane of the registry menu, select preemitter as shown in the followingimage.
The Pre Emitter type pane opens as shown in the following image.
2. Click Add.
3. Select the type of preemitter from the list of protocols.
4. Click Next.
The configuration parameters pane for the preemitter opens.
5. Provide the required parameters for the preemitter.
6. Click Next.
7. Provide a name and an optional description for the preemitter.
8. Click Finish.
After a preemitter is added to iWay Service Manager, you can assign a preemitter to anoutlet that is used to construct a channel.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 633
Constant PE (com.ibi.preemit.XDConstantPE)
Syntax:
com.ibi.preemit.XDConstantPE
Description:
Replaces output with constant value (evaluated). This preemitter is used to return a constantdocument.
Use the Constant preemitter if the user needs to return a constant output, say for testingpurposes.
Parameters:
Parameter Description
Constant This value will after evaluation be emitted.
Procedure: How to Use a ConstantPE Preemitter
1. Select a ConstantPE preemitter from the list.
2. Click Next.
3. Enter the constant that you want to output for the field Constant to Emit.
In this example, the constant is XMLConst.
The Name and Description pane opens.
4. Provide a name and optionally, a description for the preemitter.
5. Click Finish.
6. Name the preemitter ConstantPE.
After the ConstantPE preemitter is added to iWay Service Manager, create an outlet, say,PreemitterOutlet. Create a file emitter which writes to a flat file a0.txt. Add the ConstantPEpreemitter and file emitter to this outlet.
Construct the channel PreemitChannel using a file listener case1 as inlet, a simple moveroute and the outlet created in the previous step.
Let the input to this channel be:
<test/>
Constant PE (com.ibi.preemit.XDConstantPE)
634 Information Builders
The output obtained is a file a0.txt output:
XMLConst.
Deflate (com.ibi.preemit.XDDeflate)
Syntax:
com.ibi.preemit.XDDeflate
Description:
This preemitter is used to deflate data prior to emit.
For example, use the deflate preemitter to email a huge file, say of size 5 MB, using an emailemitter. The destination email mailbox cannot accept greater than 3 MB. In this case thedeflate preemitter could be used before the email emitter to send the message in the email.
Parameter:
Parameter Description
Method of compressionto use
Determines what form of compression should be used on theoutput.
Procedure: How to Use a Deflate Preemitter
1. Select the Deflate preemitter from the list.
2. Click Next.
3. Select the Method of Compression to use for the new parameter. For this example, set theform of compression to smallest.
4. Click Next.
The Name and Description pane opens.
5. Provide a name and optionally, a description for the preemitter, and click Finish.
After you add the DeflatePreemitter to iWay Service Manager, create an outlet,DeflateOutlet and add the DeflatePreemitter to this outlet.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 635
Procedure: How to Construct a Channel Using a File Listener as an Inlet
In How to Use a Deflate Preemitter on page 635, you selected the type of action the DeflatePreemitter would take. You will now construct the channel Deflate using a file listener as inletis a simple move route.
EDIX12 Preemitter (com.ibi.preemit.XDX12PreEmitter)
Syntax:
com.ibi.preemit.XDX12PreEmitter
Description:
The EDIX12PreEmitter converts the XML formatted EDI document to an EDI-X12 formatteddocument. The XML structure must be compliant with the schema supplied in the Ebix. Formore information on how to configure the EDIX12PreEmitter, see the iWay Integration Solutionfor EDI User's Guide.
Entity Repl Preemitter (com.ibi.preemit.XDEntityRepl)
Syntax:
com.ibi.preemit.XDEntityRepl
Description:
This preemitter eliminates XML entities (such as <. to < and > to >). It returns an XMLformatted document.
Use the Entity Repl Preemitter if one XML document is enclosed inside another XML documentusing < and > characters, then the user can convert the enclosed XML document to XMLrepresentation using entity Repl preemitter.
Parameters:
Parameter Description
Name Name of the new Preemitter object definition.
Description Description for the new Preemitter object definition.
Procedure: How to Use an Entity Repl Preemitter
1. Select an Entity Repl Preemitter from the list.
EDIX12 Preemitter (com.ibi.preemit.XDX12PreEmitter)
636 Information Builders
2. Click Next.
The Name and Description pane opens.
3. Provide a name and optionally, a description for the preemitter and click Finish. Name thepreemitter EntityRepl.
4. After you add the EntityRepl preemitter to iWay Service Manager, create an outlet,PreemitterOutlet and add the EntityRepl to this outlet.
5. Construct the channel PreemitChannel using a file listener case1 as inlet, a simple moveroute and the outlet created in the previous step as shown in the following process.
Let the input to this channel be a.xml.
<?xml version="1.0" encoding="ISO-8859-1" ?><eda> <error timestamp="2009-04-02T20:53:55Z"source="Parser" code="3" stage="PARSE">Parser error in XML file: XD[FAIL] cause: 0 subcause: 0 message: Problems parsing XML file: XD[FAIL] cause: 0 subcause: 0 message: Parse failure ®) 3: org.xml.sax.SAXParseException: The markup in the document following the root element must be well-formed. (</c></b><b><c>two</c> </b></a>) <data type="xml"><a><b><c>one</c></b> <b><c>two</c></b></a></data> </error></eda>
The output obtained is a file with <b> replaced with XML notation <and>. -a.2009-04-29T17_34_41.324Z.xml is:
<?xml version="1.0" encoding="ISO-8859-1" ?><eda> <response errorcount="0"> <timestamp>2009-04-29T17:34:41Z</timestamp> </response></eda>
File read Preemitter (com.ibi.preemit.XDFilePreEmitter)
Syntax:
com.ibi.preemit.XDFilePreEmitter
Description:
The File read preemitter embeds a specified binary, xml, or text file in the input document.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 637
Parameters:
Parameter Description
Name of File * The file to be read. Relative or absolute file paths aresupported explicitly or through a SREG or XPath expressionevaluated using the incoming document.
Delete after read * Whether to delete the file read on a successful read.
Format * The format of the input data.
Tag The name of the node to wrap the data read in flat format.
Character Set Encoding The character set encoding to be performed on input. Base 64is required for flat binary data.
Base64 Encode * Base64 encode the read in document when embedding.
Embed * Whether to embed the data from the read operation into theinput document.
Parent Tag Where in the input document to embed the input data.
Retry If non-zero, will retry the operation n times at one-secondintervals.
Flat Delim Preemitter (com.ibi.preemit.XDFlatDelimPreEmitter)
Syntax:
com.ibi.preemit.XDFlatDelimPreEmitter
Description:
This preemitter transforms an XML document into a flat file. It does so by extracting the XMLdata values and separating them by pipe delimiters and discards the XML tags.
For example, you could use the Flat Delim preemitter if the user needs to perform processingand transformation of the XML data and send the data back to a legacy system then thispreemitter can transform the XML into a flat file using pile symbol as the delimiter.
Flat Delim Preemitter (com.ibi.preemit.XDFlatDelimPreEmitter)
638 Information Builders
Parameters:
Parameter Description
Name Name of the new Preemitter object definition.
Description Description for the new Preemitter object definition.
Procedure: How to Use a Flat Delim Preemitter
1. Select Flat Delim Pre emitter from the list.
2. Click Next.
The Name and Description pane opens.
3. Provide a name and optionally, a description for the preemitter.
4. Click Finish.
5. Name the preemitter FlatDelimPreemitter.
After you add the FlatDelimPreemitter to iWay Service Manager, create an outlet,PreemitterOutlet and add the FlatDelimPreemitter to this outlet.
Create a file emitter which writes to a flat file a*.txt. Also add the file emitter to thisoutlet.
Construct the channel PreemitChannel using a file listener case1 as inlet, a simple moveroute and the outlet created in the previous step.
The input to this channel is the following:
<?xml version="1.0"?><hello-world> <greeter>A SOA Programmer</greeter> <greeting>Hello World!</greeting></hello-world>
The output obtained is a file a0.txt output:
A SOA Programmer||Hello World!
HIPAA Preemitter (com.ibi.preemit.XDHIPAAPreEmitter)
Syntax:
com.ibi.preemit.XDHIPAAPreEmitter
3. iWay Preemitters
iWay Service Manager Component Reference Guide 639
Description:
The HIPAAPreEmitter converts the XML-formatted HIPAA document to a HIPAA formatteddocument. The XML structure must be compliant with the schema supplied in the Ebix. Formore information on how to configure the HIPAAPreEmitter, see the iWay Integration Solutionfor HIPAA User's Guide.
iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
Syntax:
com.ibi.preemit.XDXMLGpreEmitter
Description:
The iWay Transformations preemitter transforms output through the iWay Transformationstooling. Use this preemitter to transform the output into a desired user-defined format or anyother format, such as comma separated values or flat file.
Parameters:
Parameter Description
Template Template for conversion.
Encoding How to encode output.
The listed values in the Encoding parameter are as follows.
Document. Takes encoding of input document as encoding type.
File system. Takes encoding of file system as encoding type.
Config. Takes encoding of server configuration as encoding type.
Procedure: How to Use the iWay Transformation Preemitter
1. Select iWay transformations XDXMLGpreEmitter from the list.
2. Click Next.
3. Enter the transform template that you want to use in the field Template.
Name this example XML_to_XML_Sample2.
4. Select Document as the Encoding type.
The Name and Description pane opens.
iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
640 Information Builders
5. Provide a name and optionally, a description for the preemitter.
6. Click Finish.
Name the preemitter XMLG1preemitter.
Add the XMLG1preemitter to the iWay Service Manager. Create an outlet namedPreemitterOutlet. Add the XMLGPreemitter to this outlet.
Construct the channel PreemitChannel using a file listener case1 as inlet, a simple moveroute and the outlet created in the previous step.
This input to this channel is as follows.
<?xml version="1.0" encoding="UTF-8"?><!-- edited with XML Spy v4.1 (http://www.xmlspy.com) by Tarpan Roy (Home) --><!--This is an XML Input sample--><Sales> <Company name="Video and Sound Card Express" type="Computer Parts"> <Year value="2001"> <Quarter value="1st"> <Product type="Video Cards"> <Item name="Ultra Video 5500" manufacturer="Ultra Video" value="234.99" sold="24"/> <Item name="Video Plus" manufacturer="Video Enterprise" value="129.99" sold="13"/> <Item name="Video Plus II" manufacturer="Video Enterprise" value="169.99" sold="1"/> <Item name="3D Max-a-mum" manufacturer="3D Visuals and Sound" value="342.99" sold="8"/> <Item name="Cheap 3D" manufacturer="Cheapies" value="45.99" sold="4"/> </Product> <Product type="Sound Cards"> <Item name="Soundz" manufacturer="Cheapies" value="99.99" sold="33"/> <Item name="Super 3D Sound Pro" manufacturer="Sound World Inc." value="199.99" sold="3"/> <Item name="Mega-Base" manufacturer="Bass.com" value="22.99" sold="0"/> <Item name="Sound Maximizer 4600" manufacturer="Sage Hardware" value="85.99" sold="11"/> </Product> </Quarter>
3. iWay Preemitters
iWay Service Manager Component Reference Guide 641
<Quarter value="2nd"> <Product type="Video Cards"> <Item name="Ultra Video 5500" manufacturer="Ultra Video" value="199.99" sold="12"/> <Item name="Video Plus" manufacturer="Video Enterprise" value="139.99" sold="28"/> <Item name="Video Plus II" manufacturer="Video Enterprise" value="89.99" sold="0"/> <Item name="3D Max-a-mum" manufacturer="3D Visuals and Sound" value="292.99" sold="7"/> <Item name="Cheap 3D" manufacturer="Cheapies" value="39.99" sold="12"/> </Product> <Product type="Sound Cards"> <Item name="Soundz" manufacturer="Cheapies" value="79.99" sold="40"/> <Item name="Super 3D Sound Pro" manufacturer="Sound World Inc." value="159.99" sold="1"/> <Item name="Mega-Base" manufacturer="Bass.com" value="62.99" sold="2"/> <Item name="Sound Maximizer 4600" manufacturer="Sage Hardware" value="75.99" sold="8"/> </Product> </Quarter>
<Quarter value="3rd"> <Product type="Video Cards"> <Item name="Ultra Video 6500" manufacturer="Ultra Video" value="345.99" sold="24"/> <Item name="Vidz Gold Edition" manufacturer="Vid World" value="169.99" sold="13"/> <Item name="Video Plus II" manufacturer="Video Enterprise" value="169.99" sold="1"/> <Item name="3D Max-a-mum" manufacturer="3D Visuals and Sound" value="342.99" sold="8"/> <Item name="Cheap 3D" manufacturer="Cheapies" value="45.99" sold="4"/> </Product> <Product type="Sound Cards"> <Item name="Soundz" manufacturer="Cheapies" value="99.99" sold="33"/> <Item name="World of Sound" manufacturer="Joe's Computer Hardware" value="199.99" sold="3"/> <Item name="Sound Maximizer 4600" manufacturer="Sage Hardware" value="85.99" sold="11"/> <Item name="Master Sound Maker 0100" manufacturer="Sound Corp" value="139.99" sold="10"/> </Product> </Quarter> </Year>
iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
642 Information Builders
<Year value="2000"> <Quarter value="1st"> <Product type="Video Cards"> <Item name="Ultra Video 3500" manufacturer="Ultra Video" value="264.99" sold="12"/> <Item name="Viz-a-o" manufacturer="Video Enterprise" value="149.99" sold="13"/> <Item name="Video Plus" manufacturer="Video Enterprise" value="99.99" sold="36"/> <Item name="3D Min-a-mum" manufacturer="3D Visuals and Sound" value="222.99" sold="6"/> <Item name="Cheap 2D" manufacturer="Cheapies" value="25.99" sold="8"/> </Product> <Product type="Sound Cards"> <Item name="Sound" manufacturer="Cheapies" value="39.99" sold="8"/> <Item name="Super 3D Sound" manufacturer="Sound World Inc." value="139.99" sold="3"/> <Item name="Base" manufacturer="Bass.com" value="62.99" sold="1"/> <Item name="Sound Maximizer 2600" manufacturer="Sage Hardware" value="95.99" sold="7"/> </Product> </Quarter>
<Quarter value="2nd"> <Product type="Video Cards"> <Item name="Ultra Video 3500" manufacturer="Ultra Video" value="179.99" sold="15"/> <Item name="Video Plus" manufacturer="Video Enterprise" value="119.99" sold="18"/> <Item name="3D Min-a-mum" manufacturer="3D Visuals and Sound" value="159.95" sold="2"/> <Item name="Cheap 3D" manufacturer="Cheapies" value="39.99" sold="12"/> </Product> <Product type="Sound Cards"> <Item name="Sound" manufacturer="Cheapies" value="29.99" sold="10"/> <Item name="Super 3D Sound" manufacturer="Sound World Inc." value="159.99" sold="1"/> <Item name="Base" manufacturer="Bass.com" value="82.99" sold="1"/> <Item name="Sound Maximizer 2600" manufacturer="Sage Hardware" value="75.99" sold="11"/> </Product> </Quarter>
3. iWay Preemitters
iWay Service Manager Component Reference Guide 643
<Quarter value="3rd"> <Product type="Video Cards"> <Item name="Ultra Video 4000" manufacturer="Ultra Video" value="229.99" sold="8"/> <Item name="Video Plus" manufacturer="Video Enterprise" value="59.99" sold="0"/> <Item name="3D Min-a-mum" manufacturer="3D Visuals and Sound" value="159.95" sold="5"/> <Item name="Cheap 3D" manufacturer="Cheapies" value="10.99" sold="15"/> </Product> <Product type="Sound Cards"> <Item name="Sound" manufacturer="Cheapies" value="59.99" sold="11"/> <Item name="Box of Sound" manufacturer="Joe's Computer Hardware" value="179.99" sold="15"/> <Item name="Sound Maximizer 2600" manufacturer="Sage Hardware" value="65.99" sold="13"/> <Item name="Master Sound Maker" manufacturer="Sound Corp" value="229.99" sold="5"/> </Product> </Quarter>
<Quarter value="4th"> <Product type="Video Cards"> <Item name="Ultra Video 4500" manufacturer="Ultra Video" value="285.95" sold="32"/> <Item name="Vidz Gold Edition" manufacturer="Vid World" value="139.99" sold="15"/> <Item name="Video Plus II" manufacturer="Video Enterprise" value="119.90" sold="0"/> <Item name="3D Max-a-mum" manufacturer="3D Visuals and Sound" value="299.99" sold="16"/> <Item name="Cheap 3D" manufacturer="Cheapies" value="35.99" sold="1"/> </Product> <Product type="Sound Cards"> <Item name="Soundz" manufacturer="Cheapies" value="79.99" sold="15"/> <Item name="World of Sound" manufacturer="Joe's Computer Hardware" value="187.99" sold="4"/> <Item name="Sound Maximizer 3600" manufacturer="Sage Hardware" value="199.99" sold="6"/> <Item name="Master Sound Maker" manufacturer="Sound Corp" value="149.99" sold="5"/> </Product> </Quarter> </Year> </Company></Sales>
iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
644 Information Builders
The output obtained is a file a0.txt:
<?xml version="1.0" encoding="UTF-8" ?><!-- This Transformation shows the sales for --><!-- Cheapies based on the Input File. --><Sales_Totals name="Cheapies" type="Manufacturer" allTimeSales="95022.00"> <ProductList year="2001" value="1st"> <Products quarter="1st"> <Name>Cheap 3D</Name> <Value>45.99</Value> <Sold>4</Sold> </Products> <Products quarter="1st"> <Name>Soundz</Name> <Value>99.99</Value> <Sold>33</Sold> </Products> </ProductList> <ProductList year="2001" value="2nd"> <Products quarter="2nd"> <Name>Cheap 3D</Name> <Value>39.99</Value> <Sold>12</Sold> </Products> <Products quarter="2nd"> <Name>Soundz</Name> <Value>79.99</Value> <Sold>40</Sold> </Products> </ProductList>
3. iWay Preemitters
iWay Service Manager Component Reference Guide 645
<ProductList year="2001" value="3rd"> <Products quarter="3rd"> <Name>Cheap 3D</Name> <Value>45.99</Value> <Sold>4</Sold> </Products> <Products quarter="3rd"> <Name>Soundz</Name> <Value>99.99</Value> <Sold>33</Sold> </Products> </ProductList> <ProductList year="2000" value="1st"> <Products quarter="1st"> <Name>Cheap 2D</Name> <Value>25.99</Value> <Sold>8</Sold> </Products> <Products quarter="1st"> <Name>Sound</Name> <Value>39.99</Value> <Sold>8</Sold> </Products></ProductList>
iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
646 Information Builders
<ProductList year="2000" value="2nd"> <Products quarter="2nd"> <Name>Cheap 3D</Name> <Value>39.99</Value> <Sold>12</Sold> </Products> <Products quarter="2nd"> <Name>Sound</Name> <Value>29.99</Value> <Sold>10</Sold> </Products> </ProductList> <ProductList year="2000" value="3rd"> <Products quarter="3rd"> <Name>Cheap 3D</Name> <Value>10.99</Value> <Sold>15</Sold> </Products> <Products quarter="3rd"> <Name>Sound</Name> <Value>59.99</Value> <Sold>11</Sold> </Products> </ProductList> <ProductList year="2000" value="4th"> <Products quarter="4th"> <Name>Cheap 3D</Name> <Value>35.99</Value> <Sold>1</Sold> </Products> <Products quarter="4th"> <Name>Soundz</Name> <Value>79.99</Value> <Sold>15</Sold> </Products> </ProductList></Sales_Totals>
Legacy Record Preemitter (com.ibi.preemit.LegacyRecordPreemitter)
Syntax:
com.ibi.preemit.LegacyRecordPreemitter
Description:
Converts COMMAREA XML nodes to bytes as described by a COBOL copybook. For moreinformation, see the iWay Transaction Adapter for CICS User's Guide.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 647
Parameters:
Parameter Description
Copybook Location * The full path to the COBOL copybook that describes the outputrecord.
Input Encoding * The Internet Assigned Numbers Authority (IANA) character set forthe legacy record. You can select a value from the drop-down listor type the name of a code page directly in the field. By default,the Leave option is selected, which uses the default encoding ofthe listener.
Full FD? * If set to true, then the COBOL group field headings appear in theinput XML. By default, false is selected.
Marshalls a message Preemitter (com.ibi.preemit.XDMarshall)
Syntax:
com.ibi.preemit.XDMarshall
Description:
Marshalls a document and context to sent to a demarshalling channel. This allows messagesto be sent cross-configuration.
Parameters:
Parameter Description
Compress Messages * Compression reduces the size of the marshalled message.Compression is performed before encryption. Compression ismost valuable when the message is XML, and should not beused if large byte messages are being passed.
Marshall User SpecialRegisters
Set if the marshalling is to include user registers. Normally themarshaller passes header, document, and system registersassociated with the message.
Marshalls a message Preemitter (com.ibi.preemit.XDMarshall)
648 Information Builders
Parameter Description
Namespace If empty or set to asterisk, all namespaces are marshalled. Ifthere is a value, only registers in the specified namespace aremarshalled.
Security
Use encryption * Set to true if the marshall and unmarshall messages are to beencrypted. Both the marshalling and unmarshalling channelsmust be set the same way.
AES Key If using an encrypted channel, set the AES key (maximum 16characters) to be used.
Multi Part (com.ibi.preemit.XDMultiPart)
Syntax:
com.ibi.preemit.XDMultiPart
Description:
Multi Part Preemitter outputs a multipart document from the XML document. If the outgoingmessage is an email document, and if the user needs to create a multipart (.mpart) documentfrom the XML message which underwent processing, this preemitter can be used. This isuseful when the input message is an email message or a .mpart message which is processedby the iway channel and needs to be emailed back or written to the output as a multipartdocument. This could be used in conjunction with a multipart preparser which initially convertsthe input XML message into a format that can be used to call functions on the email such as_attcnt() (attachment count).
Parameters:
Parameter Description
Debug If true, debug mode is set.
Procedure: How to Use the Multi Part Preemitter
1. Select Multi Part Preemitter from the list.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 649
2. Click Next.
The Name and Description pane opens.
3. Provide a name and optionally, a description for the preemitter.
4. Click Finish.
5. Name the preemitter MultipartPreemitter.
After you add the MultipartPreemitter to iWay Service Manager, create an outlet,PreemitterOutlet and add the MultipartPreemitter to this outlet. Create a file emitter whichwrites to a file a*.mpart. Also add the file emitter to this outlet. Construct the channelPreemitChannel using a file listener case1 as inlet which accepts * type of file as input(any file type), a simple move route and the outlet created in the previous step.
Let the input to this channel be testmp1.mpart as shown below.
content-type: multipart/mixed; boundary="----=_Part_1_8573456.1237437239687"content-length: 578mime-version: 1.0message-id:<9116239.1237437239765.JavaMail.kkauser@shoko2>
------=_Part_1_8573456.1237437239687Content-Type: application/xmlContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=a.xml
<x>xxxx</x>------=_Part_1_8573456.1237437239687Content-Type: text/documentContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=b.xmlContent-Id: mydata1
<y>yyyyy</y>------=_Part_1_8573456.1237437239687Content-Type: text/documentContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=c.xmlContent-Id: mydata1
<y>zzzzz</y>------=_Part_1_8573456.1237437239687–
The output obtained is a file a*.mpart:-
content-type: multipart/mixed; boundary="----=_Part_1_8573456.1237437239687"content-length: 578mime-version: 1.0message-id: <9116239.1237437239765.JavaMail.kkauser@shoko2>
Multi Part (com.ibi.preemit.XDMultiPart)
650 Information Builders
------=_Part_1_8573456.1237437239687Content-Type: application/xmlContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=a.xml
<x>xxxx</x>------=_Part_1_8573456.1237437239687Content-Type: text/documentContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=b.xmlContent-Id: mydata1
<y>yyyyy</y>------=_Part_1_8573456.1237437239687Content-Type: text/documentContent-Transfer-Encoding: 7bitContent-Disposition: attachment; filename=c.xmlContent-Id: mydata1
<y>zzzzz</y>------=_Part_1_8573456.1237437239687-
The input multipart document is successfully moved through the channel and is written asa MIME output to the output directory.
PGPEncrypt Preemitter (com.ibi.preemit.PGPEncrypt)
Syntax:
com.ibi.preemit.PGPEncrypt
Description:
The PGPEncrypt preemitter encrypts an outgoing message from the channel into an encryptedXML document. This has to be the last preemitter in the chain as the channel cannot processthe encrypted document unless it is decrypted by a preparser.
For more information, see the section on PGP in iWay Extensions Guide.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 651
Parameters:
Parameter Description
Encrypt method* The encryption method being used. Select one of the followingencryption methods from the drop-down list:
Passphrase
Keypair
Pass Phrase or Alias* Case sensitive pass phrase key or alias.
armor* Determines whether messages should be armored for binarytransfer. Select true or false from the drop-down list.
Public key ring The location of the public key.
Secret key ring The location of the secret key ring.
Key Phrase Case sensitive pass phrase key for private key ring.
Sign Determines whether the message should be signed. Selecttrue or false from the drop-down list.
Algorithm* The type of algorithm being used. Select one of the followingalgorithms from the drop-down list:
cast5
tripledes
blowfish
safer
idea
none
FingerPrint Finger print of the Encryption Hex Decimal Key.
PGPEncrypt Preemitter (com.ibi.preemit.PGPEncrypt)
652 Information Builders
PGP Sign Only Preemitter (com.ibi.preemit.XDPGPSignPreEmitter)
Syntax:
com.ibi.preemit.XDPGPSignPreEmitter
Description:
Signs a PGP message. This agent is deprecated in favor of PGPEncrypt.
Parameters:
Parameter Description
Armor * Determines whether the binary message will be armored fortransfer in ASCII.
Signature Hash Algorithm The algorithm to use for the signature digest.
Secret Key Ring The location of the secret key ring containing the signature key.
Signature Key User ID The User ID of the private key used for signing. The format canbe =name for the exact User ID, user@host to match only theemail address, or <user@host> optionally surrounded byignored comments to match only the value within anglebrackets against the email address. This property alsodetermines which User ID(s) will be listed in Signer's User IDsubpackets.
Signature Key ID The Key ID of the private key used for signing. The format canbe 8 hex digits for the short key ID, 16 hex digits for the longkey ID, or 40 hex digits for the fingerprint. Spaces are allowedand are not counted in the length. This property can be used inplace or together with the Signature Key User ID to select amore specific key.
Signature KeyPassphrase
A case-sensitive passphrase to unlock the Signature PrivateKey.
Signature Expiration The number of seconds after the signature creation time thatthe signature expires. The format is [xxh][xxm]xx[s]. If absent orhas a value of zero, the signature never expires.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 653
QA Print (com.ibi.preemit.XDQAPrint)
Syntax:
com.ibi.preemit.XDQAPrint
Description:
Emits the output document to a file along with additional runtime information, such as SpecialRegisters.
This preemitter is useful for extensive testing and debugging purposes. Thus, the outputdocument would contain the test results such as the special registers, errors generated andso on.
Parameters:
Parameter Description
Where File pattern to receive trace file.
When When to emit information.
Name Identifier name to mark emitted trace document.
Emit input Location (file pattern} to which to emit actual input document.If omitted or empty, the incoming document is not emitted.
Base64 Decode If set, the value is assumed to be in base64 notation. Onlyapplicable is a specific write value is specified.
Procedure: How to Use the QA Print Preemitter
1. Select XDQAPrint Preemitter from the list.
2. Click Next.
The Configuration Parameters for QA Print preemitter appears.
3. Enter the required values for Where, Name, and Emit input fields.
4. Choose always {always} for the When field.
The Name and Description pane opens.
5. Provide a name and optionally, a description for the preemitter.
6. Click Finish.
QA Print (com.ibi.preemit.XDQAPrint)
654 Information Builders
7. Name the preemitter QAPrint.
After you add the QAPrint Preemitter to iWay Service Manager, create an outlet,PreemitterOutlet and add the QAPrint Preemitter to this outlet.
Create a file emitter which writes to a flat file a*.txt. Also add the file emitter to thisoutlet. In this example, to test the QAPrint preemitter, use a process flow which doesconditional checking on special registers and printing it to a trace file using the QAPrintpreemitter. In this example, the pflow is constructed, as shown in the following image.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 655
The decision test object has the following condition:
Add the process flow to a route named CondRt. Construct the channel PreemitChannelusing a file listener case1 as inlet, CondRt route and the outlet created in the previousstep.
Let the input to this channel be:
</test>
QA Print (com.ibi.preemit.XDQAPrint)
656 Information Builders
The trace files are obtained as a result of the QAPrint preemitter as follows.
<?xml version="1.0" encoding="ISO-8859-1" ?><debug>trace*.txt<document> <test errors="0"> </test></document><variables> <variable name="SECCONFIGPORT" type="CFG">10001</variable> <variable name="SREG1" type="USR">X</variable> <variable name="X" type="CFG">X</variable> <variable name="basename" type="DOC">test</variable> <variable name="console-master-port" type="SYS">9999</variable> <variable name="debug" type="USR">false</variable> <variable name="doclocation" type="SYS">config</variable> <variable name="extension" type="DOC">xml</variable> <variable name="filename" type="DOC">test.xml</variable> <variable name="ibse-port" type="CFG">9000</variable> <variable name="iwayconfig" type="SYS">base</variable> <variable name="iwayhome" type="SYS">C:/tools/iway56sm/</variable> <variable name="iwayversion" type="SYS">7.0.000.SM.PATCH.32615</variable> <variable name="iwayworkdir" type="SYS">C:/tools/iway70sm/config/base</variable> <variable name="locale" type="SYS">en_us</variable> <variable name="name" type="SYS">PreemitChannel</variable> <variable name="parent" type="DOC">c:\case\in</variable> <variable name="protocol" type="SYS">FILE</variable> <variable name="source" type="DOC">C:\case\in\test.xml</variable> <variable name="tid" type="DOC">PreemitChannel-FILE- W.PreemitChannel.1_20090508174854961Z</variable> <variable name="timeout"type="USR">0</variable></variables></debug>
Remove Outer Tag (com.ibi.preemit.XDDeTag)
Syntax:
com.ibi.preemit.XDDeTag
Description:
This preemitter removes the outermost tag from the XML document and returns the remainderof the document. If the inner document is an XML file, it returns an XML or a flat file, if a flatfile is contained within the outer tag.
For example, the Remove outer tag preemitter can transform an XML file into a flat file (extractflat file from XML) if the flat file were originally transformed into XML by surrounding it withouter tags.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 657
Parameters:
Parameter Description
Name Name of the new Preemitter object definition.
Description Description for the new Preemitter object definition.
Procedure: How to Use the Remove Outer Tag Preemitter
1. Select Remove outer tag XDDeTag Preemitter from the list.
2. Click Next.
The Name and Description pane opens.
3. Provide a name and optionally, a description for the preemitter.
4. Click Finish.
5. Name the preemitter XDDetag.
After you add the XDDetag Preemitter to iWay Service Manager, create an outlet,PreemitterOutlet and add the XDDeTag Preemitter to this outlet.
Create a file emitter which writes to a flat file a*.txt. Also add the file emitter to thisoutlet. Construct the channel PreemitChannel using a file listener case1 as inlet, a simplemove route and the outlet created in the previous step.
The input to the channel is as follows.
<test>This is a detag preemitter test</test>
The output obtained is a file a*.txt output:
This is a detag preemitter test.
Replaced Paired Characters (com.ibi.preemit.XDCharRepl)
Syntax:
com.ibi.preemit.XDCharRepl
Replaced Paired Characters (com.ibi.preemit.XDCharRepl)
658 Information Builders
Description:
This preemitter replaces paired characters in the input stream. The lengths of the Input fieldand the Replace With field have to be the same. Use the Replaced paired characterspreemitter when the final document has character processing to be done whereby charactersand line feeds have to be replaced of if a specific character has to be replaced has to bereplaced in the output document.
For example, if a name is misspelled in the output document as rom instead of tom, then thecharacter r could be replaced with t in the document. It is similar to the find and replace inalmost all tools.
Parameters:
Parameter Description
Input String of individual characters replace. ([char]|\0x[hexpair]|\n|\t)*. For example, it could be (|\0x|\n|\t)* or a single charactersuch as [a...z].
Replace with String of characters to replace input with. Count must matchnumber in input. ([char]|\0x[hexpair]|\n|\t)*.
CR Replace Replace carriage return (0x0d) and line feed (0x0a) patterns.
Procedure: How to Use Replaced Pair Character Preemitter
1. Select Replace paired characters XDCharRepl Preemitter from the list.
2. Click Next.
The Input is r in this example. The Replace With field is t.
The Name and Description pane opens.
3. Provide a name and optionally, a description for the preemitter.
4. Click Finish.
The name of the preemitter should be CharRepl.
After the CharRepl Preemitter is added to iWay Service Manager, create an outlet,PreemitterOutlet and add the CharRepl Preemitter to this outlet. Create a file emitter whichwrites to a flat file a*.txt. Also add the file emitter to this outlet.
Construct the channel PreemitChannel using a file listener case1 as inlet, a simple moveroute and the outlet created in the previous step.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 659
The Input file is a text document, document2.txt as shown as follows.
<a> <t> <b name="rom"> <c>value of input element<c> </b> <b name="rom2"> <c>value of input element</c> </b> </t></a>
The output document document2_out.txt would look like the following output.
<?xml version="1.0" encoding="ISO-8859-1" ?><a> <t> <b name="tom"> <c>value of input element</c> </b> <b name="tom2"> <c>value of input element</c> </b> </t></a>
SWIFT Preemitter (com.ibi.preemit.SwiftPreEmitter)
Syntax:
com.ibi.preemit.SwiftPreEmitter
Description:
The SWIFTPreEmitter converts the XML-formatted SWIFT document to a SWIFT formatteddocument. The XML structure must be compliant with the schema supplied in the Ebix. TheSWIFTPreEmitter is used within an adapter framework. For more information on how toconfigure the SWIFTPreEmitter, see the iWay Integration Solution for SWIFT User's Guide.
UUEncodePreEmitter (com.ibi.preemit.XDUUEncodePreEmitter)
Syntax:
com.ibi.preemit.XDUUEncodePreEmitter
Description:
The UUEncoded document preemitter.
SWIFT Preemitter (com.ibi.preemit.SwiftPreEmitter)
660 Information Builders
Parameters:
Parameter Description
File Name * The file name to use for the UUEncoded header.
XDEDIFACT Preemitter (com.ibi.preemit.XDEDIFACTPreEmitter)
Syntax:
com.ibi.preemit.XDEDIFACTPreEmitter
Description:
XDEDIFACTPreemitter converts the XML formatted EDIFACT document to an EDIFACT formatteddocument. The XML structure must be compliant with the schema supplied in the Ebix. Formore information on how to configure the XDEDIFACTPreEmtter, see the iWay IntegrationSolution for UN/EDIFACT User's Guide.
XDSWIFT Preemitter (com.ibi.preemit.XDSwiftpreEmitter)
Syntax:
com.ibi.preemit.XDSwiftpreEmitter
Description:
The XDSWIFTPreEmitter converts the XML-formatted SWIFT document to a SWIFT formatteddocument. The XML structure must be compliant with the schema supplied in the Ebix. TheXDSWIFTPreEmitter is used outside an adapter framework. For more information on how toconfigure the SWIFTPreEmitter, see the iWay Integration Solution for SWIFT User's Guide.
XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
Syntax:
com.ibi.preemit.XDXSLTpreEmitter
Description:
Converts the XML document onto an HTML document using the XSLT file input to thepreemitter and thus produces HTML output. If you would like to generate HTML screens asoutput from the channel, the XML output can be converted to HTML using the XSLT template.
3. iWay Preemitters
iWay Service Manager Component Reference Guide 661
Parameters:
Parameter Description
Template Name Template for conversion.
Procedure: How to Use the XSLT Preemitter
1. Select XSLT preemitter from the list.
2. Click Next.
The template file is shown as follows.
<?xml version="1.0" encoding="ISO-8859-1"?><!-- Edited by XMLSpy® --><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"><xsl:template match="/"> <html> <body> <h2>My CD Collection</h2> <table border="1"> <tr bgcolor="#9acd32"> <th>Title</th> <th>Artist</th> </tr> <xsl:for-each select="catalog/cd"> <tr> <td><xsl:value-of select="title"/></td> <td><xsl:value-of select="artist"/></td> </tr> </xsl:for-each> </table> </body> </html></xsl:template></xsl:stylesheet>
The value for the field Template Name* is the full path name of the file. In this example, itis c:\test\sample.xslt.
The Name and Description pane opens.
3. Provide a name and optionally, a description for the preemitter.
4. Click Finish.
5. Name the preemitter XSLT.
6. Add the XSLT Preemitter to the iWay Service Manager.
XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
662 Information Builders
7. Create an outlet named PreemitterOutlet and add the XSLT Preemitter to this outlet.
8. Create a file emitter which writes to a file a*.html.
9. Add the file emitter to this outlet.
10. Construct the channel PreemitChannel using a file listener case1 as inlet, a simple moveroute and the outlet created in the previous step.
11. The input to this channel is as follows.
<?xml version="1.0" encoding="ISO-8859-1"?><!-- Edited by XMLSpy® --><catalog> <cd> <title>Empire Burlesque</title> <artist>Bob Dylan</artist> <country>USA</country> <company>Columbia</company> <price>10.90</price> <year>1985</year> </cd> <cd> <title>Hide your heart</title> <artist>Bonnie Tyler</artist> <country>UK</country> <company>CBS Records</company> <price>9.90</price> <year>1988</year> </cd> <cd> <title>Greatest Hits</title> <artist>Dolly Parton</artist> <country>USA</country> <company>RCA</company> <price>9.90</price> <year>1982</year> </cd>
3. iWay Preemitters
iWay Service Manager Component Reference Guide 663
<cd> <title>Still got the blues</title> <artist>Gary Moore</artist> <country>UK</country> <company>Virgin records</company> <price>10.20</price> <year>1990</year> </cd> <cd> <title>Eros</title> <artist>Eros Ramazzotti</artist> <country>EU</country> <company>BMG</company> <price>9.90</price> <year>1997</year> </cd> <cd> <title>One night only</title> <artist>Bee Gees</artist> <country>UK</country> <company>Polydor</company> <price>10.90</price> <year>1998</year> </cd> <cd> <title>Sylvias Mother</title> <artist>Dr.Hook</artist> <country>UK</country> <company>CBS</company> <price>8.10</price> <year>1973</year> </cd> <cd> <title>Maggie May</title> <artist>Rod Stewart</artist> <country>UK</country> <company>Pickwick</company> <price>8.50</price> <year>1990</year> </cd> <cd> <title>Romanza</title> <artist>Andrea Bocelli</artist> <country>EU</country> <company>Polydor</company> <price>10.80</price> <year>1996</year> </cd>
XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
664 Information Builders
<cd> <title>When a man loves a woman</title> <artist>Percy Sledge</artist> <country>USA</country> <company>Atlantic</company> <price>8.70</price> <year>1987</year> </cd> <cd> <title>Black angel</title> <artist>Savage Rose</artist> <country>EU</country> <company>Mega</company> <price>10.90</price> <year>1995</year> </cd>
<cd><title>1999 Grammy Nominees</title> <artist>Many</artist> <country>USA</country> <company>Grammy</company> <price>10.20</price> <year>1999</year> </cd> <cd> <title>For the good times</title> <artist>Kenny Rogers</artist> <country>UK</country> <company>Mucik Master</company> <price>8.70</price> <year>1995</year> </cd> <cd> <title>Big Willie style</title> <artist>Will Smith</artist> <country>USA</country> <company>Columbia</company> <price>9.90</price> <year>1997</year> </cd>
3. iWay Preemitters
iWay Service Manager Component Reference Guide 665
<cd> <title>Tupelo Honey</title> <artist>Van Morrison</artist> <country>UK</country> <company>Polydor</company> <price>8.20</price> <year>1971</year> </cd> <cd> <title>Soulsville</title> <artist>Jorn Hoel</artist> <country>Norway</country> <company>WEA</company> <price>7.90</price> <year>1996</year> </cd> <cd> <title>The very best of</title> <artist>Cat Stevens</artist> <country>UK</country> <company>Island</company> <price>8.90</price> <year>1990</year> </cd>
<cd> <title>Stop</title> <artist>Sam Brown</artist> <country>UK</country> <company>A and M</company> <price>8.90</price> <year>1988</year> </cd> <cd> <title>Bridge of Spies</title> <artist>T`Pau</artist> <country>UK</country> <company>Siren</company> <price>7.90</price> <year>1987</year> </cd> <cd> <title>Private Dancer</title> <artist>Tina Turner</artist> <country>UK</country> <company>Capitol</company> <price>8.90</price> <year>1983</year> </cd>
XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
666 Information Builders
<cd> <title>Midt om natten</title> <artist>Kim Larsen</artist> <country>EU</country> <company>Medley</company> <price>7.80</price> <year>1983</year> </cd> <cd> <title>Pavarotti Gala Concert</title> <artist>Luciano Pavarotti</artist> <country>UK</country> <company>DECCA</company> <price>9.90</price> <year>1991</year> </cd> <cd> <title>The dock of the bay</title> <artist>Otis Redding</artist> <country>USA</country> <company>Atlantic</company> <price>7.90</price> <year>1987</year> </cd> <cd> <title>Picture book</title> <artist>Simply Red</artist> <country>EU</country> <company>Elektra</company> <price>7.20</price> <year>1985</year> </cd> <cd> <title>Red</title> <artist>The Communards</artist> <country>UK</country> <company>London</company> <price>7.80</price> <year>1987</year> </cd>
<cd> <title>Unchain my heart</title> <artist>Joe Cocker</artist> <country>USA</country> <company>EMI</company> <price>8.20</price> <year>1987</year> </cd></catalog>
3. iWay Preemitters
iWay Service Manager Component Reference Guide 667
The obtained output is as follows.
<html><body><h2>My CD Collection</h2><table border="1"><tr bgcolor="#9acd32"><th>Title</th><th>Artist</th></tr><tr><td>Empire Burlesque</td><td>Bob Dylan</td></tr><tr><td>Hide your heart</td><td>Bonnie Tyler</td></tr><tr><td>Greatest Hits</td><td>Dolly Parton</td></tr><tr><td>Still got the blues</td><td>Gary Moore</td></tr><tr><td>Eros</td><td>Eros Ramazzotti</td></tr><tr><td>One night only</td><td>Bee Gees</td></tr>
<tr><td>Sylvias Mother</td><td>Dr.Hook</td></tr><tr><td>Maggie May</td><td>Rod Stewart</td></tr><tr><td>Romanza</td><td>Andrea Bocelli</td></tr><tr><td>When a man loves a woman</td><td>Percy Sledge</td></tr><tr><td>Black angel</td><td>Savage Rose</td></tr><tr><td>1999 Grammy Nominees</td><td>Many</td></tr><tr><td>For the good times</td><td>Kenny Rogers</td></tr><tr><td>Big Willie style</td><td>Will Smith</td></tr>
XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
668 Information Builders
<tr><td>Tupelo Honey</td><td>Van Morrison</td></tr><tr><td>Soulsville</td><td>Jorn Hoel</td></tr><tr><td>The very best of</td><td>Cat Stevens</td></tr><tr><td>Stop</td><td>Sam Brown</td></tr><tr><td>Bridge of Spies</td><td>T`Pau</td></tr><tr><td>Private Dancer</td><td>Tina Turner</td></tr>
<tr><td>Midt om natten</td><td>Kim Larsen</td></tr><tr><td>Pavarotti Gala Concert</td><td>Luciano Pavarotti</td></tr><tr><td>The dock of the bay</td><td>Otis Redding</td></tr><tr><td>Picture book</td><td>Simply Red</td></tr><tr><td>Red</td><td>The Communards</td></tr><tr><td>Unchain my heart</td><td>Joe Cocker</td></tr></table></body></html>
3. iWay Preemitters
iWay Service Manager Component Reference Guide 669
XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
670 Information Builders
Chapter4iWay Iterators
This section provides an overview of iterators and their usage within iWay ServiceManager process flows.
In this chapter:
Understanding Iterators
Iterator Parameters
Available Iterators
Iterator Example
Understanding Iterators
Iterators form the top of a loop in an iSM process flow. They test for a truth condition and passa portion of their incoming message to the next Service object (agent). On a false condition(such as end of data), the Iterator object passes control to the Service object immediatelybelow the loop. For example, consider the Count iterator. The Count iterator sends a copy ofthe incoming message to the next object in the process flow a specified number of times.
When the iterator completion condition is met, execution of the process flow continues withthe objects after the loop. Despite the appearance of the diagram in the iIT Designerworkspace area, at completion, the process flow jumps over the objects inside the loop,otherwise the logic inside the loop would be erroneously executed one additional time.
The following is a simple illustration of a loop operating within a process flow.
iWay Service Manager Component Reference Guide 671
The following are some guidelines for using Iterator objects in a process flow:
The loop must begin with an Iterator object. The process flow cannot branch into aniteration loop.
Iterator loops can be nested, however, loop lines cannot cross.
Only Execution objects (Service, Iterator, Transform, Adapter, Process, Web Service, SQL,ETL, BI, Email, FTP, File, HTTP, Emitter, and Queue) can end a loop.
Loops cannot be drawn from Control objects (Join, Junction, Decision Switch, DecisionTest, Set, Sync, and Debug).
For more specific information about using iterators within iIT Designer, see the iWay IntegrationTools Designer User’s Guide. This section discusses the iterators and their use.
Iterator Parameters
Each iterator uses parameters unique to its purpose. Some common parameters are usedacross the iterators.
Parameter Description
Iterating Document State Documents carry state (such as error state, encoding, andso on) as well as payload. You can affect the state as theiteration progresses.
Transient. The state in the next iteration reflects thestate from the last. For example, if the last state set itinto an error state, it will remain in an error state.
Original. The state is that of the input document.
Reset. Always reset at start of iteration to no error, andso on.
Iterator Parameters
672 Information Builders
Parameter Description
Output Document Determines the final document to be passed out of theiterator at the end of the iteration. Accumulations arememory intensive.
Status. A status document. This is a standard statusdocument.
Original. The original document arriving at the iterator.
Accum In. Accumulation of the documents coming out ofthe loop and back into the iterator.
Accum Out. Accumulation of the documents passed intoeach iteration.
Parameters for IterTest and IterCond
Iterate Rule Determines whether this iteration should be treated as a do-until or a do-while.
do_until. Iterate until the condition is true.
do_while. Iterate until the condition is false.
Available Iterators
There are many available iterators, each performing some process and then passing theappropriate document into the loop and to the end of the loop. The following table lists anddescribes the most commonly used iterators.
Iterator Description
Attachment Passes each attachment to the document (perhaps from an incomingHTTP or mail message) through the loop.
Chunk Splits the input document into equally sized chunks.
Condition Evaluates an iWay Functional Language (iFL) expression as either a do-while or do-until construction.
4. iWay Iterators
iWay Service Manager Component Reference Guide 673
Iterator Description
Counter Passes a document through the loop a specified number of times.
Delimited Value(DelVal)
Generates one row of XML at a time from a delimited value input (forexample, a comma separated value file.)
FTP Emit Emits through the FTP protocol to a specified host:port using variousFTP commands.
Island Iterates a loop for each EDA island within the document and insertsthe response text.
Iter RVI Relay Relays messages for external execution.
JSON Selects values from a JSON object and returns them one by one.
Line Pass each line of a text format input one at a time through theiterator. Lines end on terminator characters.
SQL Batch Insert Reads SQL rows one at a time and inserts results from the processflow.
SQL Select Each row from an SQL select operation is passed through the loop.The iterator can perform a batch update operation providing anExtract/Transform/Load operation within the process flow.
Sibling Iterates a loop for each sibling document.
Test Similar to the test node in a process flow and the condition iterator, itacts as a condition Do-While or Do-Until. It offers an extended range ofcomparisons, such as is empty or is equal ignore case.
XMLSplit An incoming XML message is split on an XPath and each split portionis passed through the loop. It is commonly used to extract repeatingelements from the incoming document, such that each can beprocessed individually.
Other iterators perform specialized operations, such as handling portions of very largedocuments and passing portions of messages to other processors (configurations) through theGateway protocol.
Available Iterators
674 Information Builders
Attachment Iterator (com.ibi.agents.XDIterAttachments)
Syntax:
com.ibi.agents.XDIterAttachments
Description:
The Attachment Iterator handles each attachment of the current document iteratively.
Parameters:
Parameter Description
Handling Option Select one of the following options from the drop-down list:
delete. Removes each attachment from the currentdocument after processing.
replace. Replaces the original attachment with themodified document.
leave. Leaves the original attachments unchanged. Thisoption is selected by default.
Start Index Index of first attachment to process in the mail object. Thefirst attachment to the main document has index 0.
Header Namespace Special register namespace where MIME headers for thecurrent attachment will be stored. If the replace option isselected for the Handling Option parameter, then registers inthis namespace will be added to the replaced attachment.
Main Body Part HeaderNamespace
If the current attachment is itself a Multipart, this is thespecial register namespace where the MIME headers for themain body part will be stored.
Keep Document Flat Determines whether to keep the body of the document as anarray of bytes. This parameter is set to false by default.
Chunk Iterator (com.ibi.agents.XDIterChunk)
Syntax:
com.ibi.agents.XDIterChunk
4. iWay Iterators
iWay Service Manager Component Reference Guide 675
Description:
The Chunk Iterator splits the input document into equally sized chunks. The input stream maycome from one of the streaming components, for example, a File listener set for streaming, ora File Read service configured with a stream format. The chunk is passed as a flat documentcontaining bytes, which can be manipulated within the process flow.
Parameters:
Parameter Description
Chunk Size The size of the chunk in bytes. The default value is 8192.
Condition Iterator (com.ibi.agents.XDIterCond)
Syntax:
com.ibi.agents.XDIterCond
Description:
The Condition Iterator is used to iterate a loop while (or until) a specified condition is met.
Parameters:
Parameter Description
Conditional Expression Expression controlling the termination of the loop.
Iterate Rule Determines the loop logic between do-while or do-until. Thisparameter is set to true by default.
Available Iterators
676 Information Builders
Parameter Description
Interim Document The document emitted at each iteration is the originaldocument or the result of the previous iteration. By default,transient is selected.
Output Document Final document emitted is a status document, the originaldocument, the result of the last iteration or an accumulation.Accumulations are memory intensive. By default, status isselected.
Counter Iterator (com.ibi.agents.XDIterCount)
Syntax:
com.ibi.agents.XDIterCount
Description:
The Counter Iterator is used to iterate a loop a specified number of times. This number can beconstant or computed at run time, for instance, with an XPath expression, as in this example.The inner part of the loop can be used to generate multiple outputs, read multiple inputs froma source, or perform any other operation repeatedly. The Counter Iterator can also be usedwith conditional logic to add retry functionality to an adapter that does not natively supportretry. The number of iterations of the loop is not dependent on the structure of the inputdocument, nor does the count iterator parse the document before injecting it into the loop.
Parameters:
Parameter Description
Iterations The number of times this iterator loop is to be repeated. Thedefault value is 1.
Interim Document The document emitted at each iteration is the originaldocument or the result of the previous iteration. By default,transient is selected.
4. iWay Iterators
iWay Service Manager Component Reference Guide 677
Parameter Description
Output Document Final document emitted is a status document, the originaldocument, the result of the last iteration or an accumulation.Accumulations are memory intensive. By default, status isselected.
Example:
The Counter Iterator in this example passes the input document into the loop the number oftimes specified by the <count> XML tag in the input document.
Input Document:
<IterCountTest> <count>3</count></IterCountTest>
Output Document(s):
In this example, three documents are output by the FileWrite object:
IterCount01.xml
IterCount02.xml
IterCount03.xml
<?xml version="1.0" encoding="UTF-16"?><IterCountTest> <count>3</count></IterCountTest>
Available Iterators
678 Information Builders
Delimited Value Iterator (com.ibi.agents.XDIterDelVal)
Syntax:
com.ibi.agents.XDIterDelVal
Description:
Accepts a delimited value input from a stream or flat document, and emits an XML documentrepresenting one row at a time to the flow. The first row may be a header row (often called aDIF header) containing names to be applied to the elements of the row representing thecolumn of data in the file.
Parameters:
Parameter Description
Root name The element name of the XML root. In the example in thissection, the root name was set to myroot.
Dif Determines whether the first row is a header row. If not (false),then the first row contains data and generated names areused for the elements. If set to true, then the first row holdsthe names, and the data starts at the second row.
This parameter is set to false by default.
Delimiter Determines the delimiter to be used. Select, enter onecharacter or a single hex value as \xvv, where vv is a hexvalue. By default, comma is selected as the delimiter.
Trim values Determines whether all values should be trimmed. Thisparameter is set to false by default.
Quotes Determines whether surrounding quotes should be eliminated.This parameter is set to false by default.
Empty elements Determines whether empty elements at the right should beeliminated. This parameter is set to false by default.
Output Document Final document emitted is a status document, the originaldocument, the result of the last iteration or an accumulation.Accumulations are memory intensive. By default, status isselected.
4. iWay Iterators
iWay Service Manager Component Reference Guide 679
Example:
Consider the following input file:
acol,bcol,ccolaa1,bb1,cc1aa2,bb2,cc2,aa3,bb3,cc3
Three iterations will be emitted. The first will be:
<myroot> <row> <acol>aa1</acol> <bcol>bb1</bcol> <ccol>cc1</ccol> </row></myroot>
The element names are derived from the header row.
FTP Emit Iterator (com.ibi.agents.XDIterNFTPEmitStdAgent)
Syntax:
com.ibi.agents.XDIterNFTPEmitStdAgent
Description:
The FTP Emit Iterator emits through the FTP protocol to a specified host:port using various FTPcommands.
Parameters:
Parameter Description
Host Parameters
Host Name DNS name (or IP address) of the FTP server to which you wantto connect. Use host:port if not standard port 21.
Remote Port The port to connect to on the FTP site, blank for default port21.
User Name A valid user ID for the FTP server.
Password A valid password for the FTP server.
Available Iterators
680 Information Builders
Parameter Description
Account Name A valid account name for the FTP server.
Use Passive Command Uses the PASV command if set to true, otherwise uses thePORT command. This parameter is set to false by default.
Timeout The timeout interval for the socket in seconds. This parameteris set to 5 by default.
Retry Interval The retry interval in seconds (allows for xxhxxmxxs format).Leave blank or specify 0 for no retry interval.
Connection Retry The number of retry attempts after failed connections to theFTP server.
Agent Parameters
Block Size The size of the transmission block to send. This parameter isset to 256 by default.
Input Source Input from the document (default) or from an external source(MFT use). This parameter is set to document by default.
Input Expression If the Input Source parameter is set to external, then specifythe file name in this field. For document source, thisparameter is ignored.
Remote Site Folder The folder or directory on the FTP site that you want to use asa starting location after a connection is established. Leaveblank for login directory.
File Pattern The output file pattern (* = timestamp). For example, *.xml,*.txt, and so on. Note *.* is unsupported.
Transfer Mode When files are transferred in ASCII mode, the transferred datais expected to contain only character formatted text. BINARYmode refers to transferring files as a binary stream of data.Where ASCII mode may use special control characters toformat data, BINARY mode transmits the raw bytes of the filebeing transferred. In this way, the file is transferred in its exactoriginal form. This parameter is set to ascii by default.
4. iWay Iterators
iWay Service Manager Component Reference Guide 681
Parameter Description
Put File Protection Determines whether the PUT is protected by a rename of atemporary file name. Using the rename protection can result inreduced performance, but can protect against partial updatesin the event of an error. This parameter is set to false bydefault.
Return Select one of the following values from the drop-down list:
status. The status document will be the output document.
original. The original input document will be the outputdocument.
SSL Parameters
Use SSL If set, then the connection is secured through Secure SocketsLayer (SSL). This parameter is set to false by default.
Security Protocol The Security protocol:
SSL. Supports some version of SSL; may support otherversions. This value is selected by default.
SSLv2. Supports SSL version 2 and higher.
SSLv3. Supports SSL version 3; may support otherversions.
TLS. Supports some version of TLS; may support otherversions.
TLSv1. Supports TLS version 1; may support otherversions.
This field is not required if the Keystore is a SSL Provider.
Secure Data Connection Use a secure data connection, for example, to transfer datasecurely. This is used in conjunction with Secure ControlConnection. This parameter is set to false by default.
Use 128-bit Encryption Enforces the use of 128-bit encryption. This parameter is setto false by default.
Available Iterators
682 Information Builders
Parameter Description
SSL Security The FTP Server connection type:
unknown. Defaults to Explicit Security then fails over toImplicit Security. This value is selected by default.
explicit. In order to establish the SSL link, explicit securityrequires that the FTP client issue a specific command tothe FTP server after establishing a connection. The defaultFTP server port is used.
implicit. Implicit security automatically begins with an SSLconnection as soon as the FTP client connects to an FTPserver. In implicit security, the FTP server defines a specificport for the client (typically 990) to be used for secureconnections.
Keystore File or KeystoreSecurity Provider
The full path to the Keystore file (which provides certificatematerial to be used for SSL connections), the name of aKeystore Security Provider, or leave blank to use theconfigured default Keystore Security Provider.
Keystore Password The password to access the Keystore file. This is not requiredif the Keystore File or Keystore Security Provider parameter isset to the name of a Keystore Security Provider.
Keystore Type The type of Keystore. This is not required if the Keystore File orKeystore Security Provider parameter is set to the name of aKeystore Security Provider.
Site Parameters
Starting SITE command The SITE command to issue before the transfer of data.
Successful SITEcommand
The SITE command to issue after the successful transfer ofdata.
Error SITE command The SITE command to issue if the transfer of data fails.
4. iWay Iterators
iWay Service Manager Component Reference Guide 683
Island Iterator (com.ibi.agents.XDIterIsland)
Syntax:
com.ibi.agents.XDIterIsland
Description:
The Island Iterator is used to iterate a loop for each EDA island within the document andinserts the response text.
The Island Iterator is designed to perform document enhancement, that is, to replace parts ofthe input XML document with the results of a call to an agent or adapter. Any external datasource can be targeted (web services, SQL data, and so on), but in this example embeddedfile names are replaced with the content of the named disk file. The replacement would behaveidentical regardless of the source, although the replacement data must be in XML format.Island replacement is iterated for as many tags as are present in the input document. The tagsto be replaced may be homogeneous, as in this example, or heterogeneous by using multiplesequential Island iterators that target different sources.
Parameters:
Parameter Description
Island Identifier The XML tag, which identifies the island command string.
Snip and Replace If set to true, the island is replaced with the incomingdocument arriving on the iteration loop for the island beingprocessed. If set to false, the island node is kept and theincoming document is carried as the first child of the islandnode. This parameter is set to true by default.
Example:
Available Iterators
684 Information Builders
Input Document
The primary input document is the document that contains the islands to be replaced. In thisexample, they are identified by the XML tag <file>.
<mydoc> <file>file1.txt</file> <file>file2.txt</file> <file>file3.txt</file></mydoc>
file1.txt
<content>Contents of file 1</content>
file2.txt
<content><line>Contents of file 2</line><line>There are 2 lines</line></content>
file3.txt
<content>Contents of file 3</content>
Output Document(s)
The input document and the island documents are combined according to the behavior of theiterator.
<?xml version="1.0" encoding="UTF-8" ?><mydoc> <content>Contents of file 1</content> <content> <line>Contents of file 2</line> <line>There are 2 lines</line> </content> <content>Contents of file 3</content></mydoc>
Iter RVI Relay Iterator (com.ibi.agents.XDIterRVIRelay)
Syntax:
com.ibi.agents.XDIterRVIRelay
Description:
The Iter RVI Relay Iterator relays messages for external execution.
4. iWay Iterators
iWay Service Manager Component Reference Guide 685
Parameters:
Parameter Description
Service Name The name of the service to execute the current message.
Tolerance The amount of time (in seconds) to await circuit availability toaccess the named service. This parameter is set to 30 bydefault.
Timeout The amount of time (in seconds) to await response from thegateway. This parameter is set to 30 by default.
Attempt Retry If set to true, a retry exception is generated when no gatewayconnections are available, a message cannot be written to thegateway, or this service times out while awaiting a response.The retry exception will activate the channel’s pending system,when available. If set to false, this service will attempt toacquire a new connection if the message cannot be written tothe gateway and, if a connection is available, will retryautomatically. If no connections are available, or if the servicetimes out or otherwise fails while reading the response, theservice will return a failure edge. This parameter is set to trueby default.
Output On Failure If the relay operation is unsuccessful, this parameterdetermines whether the agent should return the standard errordocument, or return its input. If input is selected, then theerror document will be stored in the rvi.status register [type:user]. By default, error is selected.
Method of compressionto use
The form of compression that should be used on the input. Bydefault, none is selected.
JSON Iterator (com.ibi.agents.XDIterJsonSplit)
Syntax:
com.ibi.agents.XDIterJsonSplit
Description:
The JSON Iterator selects values from a JSON object and returns them one by one.
Available Iterators
686 Information Builders
The values are selected by evaluating a JsonPath expression against a JSON input document.It is possible to select JSON objects, JSON arrays, and/or primitive values. An array isconsidered a single value. Therefore, to select multiple items within an array, a wildcard or aslice operator must be used.
The final output document can be a status document, the original document, the result of thelast iteration, or an accumulation. The format of the accumulation depends on the type of thefirst accumulated value. If the first value is a JSON object, then the accumulation will have thefollowing form:
{"accumulation":[val1,…,valN]}
Parameters:
Parameter Description
Path Expression A JsonPath expression, which selects the specific items toiterate.
Output Document The final document emitted can be a status document, theoriginal document, the result of the last iteration, or anaccumulation.
Note: Accumulations are memory intensive.
Examples:
Consider the following JSON object:
{"array":[1, "abc", true, false]}
The expression $.array returns the single value: [1, "abc", true, false].
The expression $.array[*] returns the four values: 1, "abc", true, and false.
The expression $.array[1:3] returns the two values: "abc" and true.
Line Iterator (com.ibi.agents.XDIterLine)
Syntax:
com.ibi.agents.XDIterLine
4. iWay Iterators
iWay Service Manager Component Reference Guide 687
Description:
The Line Iterator is used to iterate a loop for each line in the input document. The inner part ofthe loop can be used to generate multiple outputs, read multiple inputs from a source, orperform any other operation repeatedly. When using this iterator, the number of times throughthe loop and how the input is parsed is directly related to the structure of the input document,in particular, how many lines are present. It is recommended that non-XML, line-oriented inputbe read into the process flow with a File object rather than being passed through the Startnode.
Parameters:
Parameter Description
Keep blanks If set to true, then pass empty (blank) input lines into the loop.This parameter is set to false by default.
Skip Header Lines Sets the number of lines to be skipped for processing. Often adelimited file has a header row, which is not desired in theprocess. This parameter is set to 0 by default.
Output Document Final document emitted is a status document, the originaldocument, the result of the last iteration or an accumulation.Accumulations are memory intensive. By default, status isselected.
Example:
Input Document
This is the first lineThis is line 2Line 3
Available Iterators
688 Information Builders
Output Document(s)
In this example, three documents are output:
IterLine01.txt
IterLine02.txt
IterLine03.txt
This is the first lineThis is line 2Line 3
SQL Batch Insert Iterator (com.ibi.agents.XDIterSQLBatchAdd)
Syntax:
com.ibi.agents.XDIterSQLBatchAdd
Description:
The SQL Batch Iterator reads SQL rows one at a time and inserts results from the processflow.
Parameters:
Parameter Description
Source Parameters
Input Provider The name of the Data Provider that will be used for accessinginput.
Select SQL The SQL Select statement to retrieve rows to pass into theprocess flow.
Transaction IsolationLevel
The transaction isolation level to be set if possible. Thisparameter is set to asis by default.
Base 64 if Needed If set to true, all fields are checked for base64. This option isresource-intensive. This parameter is set to false by default.
Input Encoding The IANA character set to be used for the input database.Select from the standard list, or enter an encoding name. Bydefault, leave is selected.
4. iWay Iterators
iWay Service Manager Component Reference Guide 689
Parameter Description
Format as SQLAgent If set to true, the generated rows are formatted according tothe SQLAgent field schema. This parameter is set to false bydefault.
Three Part Name If set to true, the names will be presented as full three partnames if supported by the database. This parameter is set tofalse by default.
Destination Parameters
Output Provider The name of the Data Provider that will be used for insertingthe output.
Output Insert Output statement to be prepared. Use ?name notation forparameters.
Out Encoding The IANA character set to be used for the output database.Select from the standard list, or enter an encoding name. Bydefault, leave is selected.
Batch Size The size of sub-batches. If greater than 0, commit on batchsize is reached. This parameter is set to 0 by default.
Commit Sub-batches If sub-batches are requested, determines whether they shouldbe committed as they update. This parameter is set to false bydefault.
Fail First If the first row of the first batch fails, terminate the operationwith the fail_insert edge. This parameter is set to false bydefault.
Omit Test iWay Functional Language (iFL), which if true, causes thecurrent destination record to be omitted.
Main Parameters
Output document type Determines whether the emitted output document should bethe original input document (original) or a status document(status). By default, status is selected.
Available Iterators
690 Information Builders
SQL Select Iterator (com.ibi.agents.XDIterSQLSelect)
Syntax:
com.ibi.agents.XDIterSQLSelect
Description:
The SQL Select Iterator sends one row at a time to the process flow.
Parameters:
Parameter Description
Input Provider The name of the Data Provider that will be used for accessinginput.
Note: You must specify the actual name of this Data Provideras defined during configuration. For example:
DataProviderSQL
Select SQL The SQL Select statement to retrieve rows to pass into theprocess flow.
Transaction IsolationLevel
The transaction isolation level to be set if possible. Thisparameter is set to asis by default.
Base 64 if Needed If set to true, all fields are checked for base64. This option isresource-intensive. This parameter is set to false by default.
Input Encoding The IANA character set to be used for the input database.Select from the standard list, or enter an encoding name. Bydefault, leave is selected.
Output document type Determines whether the emitted output document should bethe original input document (original) or a status document(status). By default, status is selected.
Format as SQLAgent If set to true, the generated rows are formatted according tothe SQLAgent field schema. This parameter is set to false bydefault.
4. iWay Iterators
iWay Service Manager Component Reference Guide 691
Parameter Description
Three Part Name If set to true, the names will be presented as full three partnames if supported by the database. This parameter is set tofalse by default.
Inline xLOBs If set to true, character and boolean large objects are inline inthe select results. BLOBs are enclosed in base64() tags. Thisparameter is set to false by default.
Sibling Iterator (com.ibi.agents.XDIterSibSplit)
Syntax:
com.ibi.agents.XDIterSibSplit
Description:
The Sibling Iterator is used to iterate a loop for each sibling document. By bundling sets ofrows, siblings make the handling of very large result sets more practical. When used with theIterSibSplit operator, the logic inside the loop is executed once for each sibling document. Oneresult row per sibling document is recommended for this iterator. Because the entire answerset is fetched prior to executing the loop, process flows using this technique may have highmemory requirements.
Parameters:
Parameter Description
Output Document Final document emitted is a status document, the originaldocument, the result of the last iteration or an accumulation.Accumulations are memory intensive. By default, status isselected.
Test Iterator (com.ibi.agents.XDIterTest)
Syntax:
com.ibi.agents.XDIterTest
Available Iterators
692 Information Builders
Description:
The Test Iterator is used to iterate a loop while (or until) a condition is met. This iteratorrepeats the body of the loop while a specified logical comparison evaluates to true. Thepredicate is reevaluated each time through the loop. The inner part of the loop can be used togenerate multiple outputs, read input multiple times from a source, or perform any otheroperation repeatedly. Similar to the count iterator, the test iterator can be used to retry anoperation until it is successful or other criteria are met.
Parameters:
Parameter Description
Operand One The first of two operands to compare.
Operation The comparison operator. This parameter is set to equals casesensitive by default.
Operand Two The second of two operands to compare when the operation isdyadic.
Iterate Rule Determines the loop logic between do-while or do-until. Thisparameter is set to true by default.
Interim Document The document emitted at each iteration is the originaldocument or the result of the previous iteration. By default,transient is selected.
Output Document Final document emitted is a status document, the originaldocument, the result of the last iteration or an accumulation.Accumulations are memory intensive. By default, status isselected.
XML Iterator (com.ibi.agents.XDIterXMLSplit)
Syntax:
com.ibi.agents.XDIterXMLSplit
Description:
The XML Iterator is used to iterate a loop for each portion of an XML document.
4. iWay Iterators
iWay Service Manager Component Reference Guide 693
Parameters:
Parameter Description
Snip levels Determines how many tag levels to trim off of the new XMLdocument, starting from the top (root) node.
A value of 0 preserve all levels. A value of 1 cuts off the root.A value of 2 cuts off the root and immediate child, and so on,down to the XPath location being iterated. The default value is0, which will return all parent tags up to the root.
Note: Cross Section data may be lost depending on the sniplevel setting.
Expression Describes the XPath location of the element on which to split.When the Evaluate Expression is not set (false), enter anXPath expression directly. When the Evaluate Expression is set(true), enter an expression that returns an XPath expression.
Evaluate Expression When not set, the Expression parameter contains an XPathexpression directly. When set, the Expression parameter isevaluated and the returned value is the XPath expression usedfor splitting. This parameter is set to false by default.
XML Namespace MapProvider
If the XPath expression depends on namespaces, then specifythe name of an XML Namespace Map Provider that containsthe required namespace prefixes and URLs.
Cross Section If set to true, the iterated portion is included with theremainder of the non-iterated portion of the document.Otherwise, only the parental path is included. This parameteris set to false by default.
Iterating Document State In addition to content, a document carries state. Thisparameter determines how the state should be managed atthe iterations. This parameter is set to transient by default.
Available Iterators
694 Information Builders
Parameter Description
End Iteration Signal Determines whether an extra iteration is added at the end toemit the End Iteration document. If applicable, the end ofiteration signal will be emitted on the end_iteration edge. Thedefault is not to emit the End Iteration document. Thisparameter is set to false by default.
Output document Select one of the following values from the drop-down list:
status. The status document will be the output document.
original. The original input document will be the outputdocument.
accumulations. Allow gathering of partial documents, butcan be memory-intensive. Input is what passes from theiterator, and output is what is returned for each iteration.
XPath Syntax Determines which syntax level of XPath should be used. Thedefault option selects the syntax level as set in the consoleglobal settings. By default, this parameter is set to default.
Example:
Often, a single transaction document contains repeating groups of data, in this example, asimplified invoice with multiple line items. The XML Iterator extracts the repeating groupspecified by the XPath expression. The parsed document contains the indicated group andpreserves its direct parental lineage of XML nodes. If the logic inside your loop needs datafrom a parallel XML path (the invoice number in this example), then you can set the CrossSection parameter to true. Cross Section will preserve the entire document above the nodethat is the target of the Expression parameter.
4. iWay Iterators
iWay Service Manager Component Reference Guide 695
The body of the loop is repeated once for each occurrence of the indicated group. The innerpart of the loop can be used to process the repeating groups, call a web service, insert thedata into an SQL database, and so on. When using this iterator, the number of times throughthe loop and how the input is parsed depends on the structure of the input document and theXPath expression.
Input Document
<invoice> <invoice-number>1001</invoice-number> <line-item> <item-number>1</item-number> <item-desc>Red Widget</item-desc> </line-item> <line-item> <item-number>2</item-number> <item-desc>Blue Widget</item-desc> </line-item> <line-item> <item-number>3</item-number> <item-desc>Green Do-dad</item-desc> </line-item></invoice>
Output Document(s)
In this example, three documents are output by the FileWrite object:
IterXmlSplit01.xml
IterXmlSplit02.xml
IterXmlSplit03.xml
Available Iterators
696 Information Builders
<?xml version="1.0" encoding="UTF-16" ?><invoice> <line-item> <item-number>1</item-number> <item-desc>Red Widget</item-desc> </line-item></invoice><?xml version="1.0" encoding="UTF-16" ?><invoice> <line-item> <item-number>2</item-number> <item-desc>Blue Widget</item-desc> </line-item></invoice><?xml version="1.0" encoding="UTF-16" ?><invoice> <line-item> <item-number>3</item-number> <item-desc>Green Do-dad</item-desc> </line-item></invoice>
The following is an output document with the Cross Section parameter set to true.
<?xml version=”1.0” encoding=”UTF-16” ?><invoice> <invoice-number>1001</invoice-number> <line-item> <item-number>1</item-number> <item-desc>Red Widget</item-desc> </line-item></invoice>
The following is an output document when the Snip levels parameter is set to 1.
<?xml> version=”1.0” encoding=”UTF-16” ?><line-item> <item-number>1</item-number> <item-desc>Red Widget</item-desc></line-item
4. iWay Iterators
iWay Service Manager Component Reference Guide 697
Iterator Example
The following diagram illustrates a simple example where an Iterator object is used in aprocess flow.
The message reaching the iterator is operated upon accordingly (in this, case simplyduplicated) and then sent into the process flow, which performs some operation. Any Serviceobjects can be used in the loop, including iteration. When the message is handled by thesubflow, it is passed to another service, which serves as the bottom of the loop. In general,any service can be the loop bottom, although a common idiom is to use a Move service. TheOnComplete or the OnSuccess relation should be used between the end of a loop (Loop back)and the next service. The process flow interpreter looks for these edges to route the end of theiteration message.
Upon reaching the end of the iteration, control is passed to the Do More service object andthen to the End object of the process flow.
The iterator in this example is configured for the number of iterations and has instructions onwhat to pass to the end of the loop. While the iterator-specific configuration will vary, acommon configuration property for iterators is the Output Document property.
Iterator Example
698 Information Builders
The Output Document property instructs the iterator on what to pass to the end of loop. In thisexample, it is a Service object called Do More. While some iterators offer additional values forthe Output Document property, commonly available to all iterators is the Original and Statusvalues.
Original. The document that first reached the iterator.
Status. A status document describing the results of the iteration.
The status document has a structure, as shown in the following image.
Configuration of the iterator is performed at the start of a loop (when a message arrives at theiterator). It is not reconfigured during the loop. In this example, a count might come from anXPath into the arriving message. However, regardless of how that message changes, the countobtained at the start of the loop will be honored.
4. iWay Iterators
iWay Service Manager Component Reference Guide 699
Iterator Example
700 Information Builders
AppendixA Additional SQL Service ReferenceInformation
This appendix provides additional reference information for the SQL Service(com.ibi.agents.XDSQLAgent).
In this appendix:
SQL Service Edge Returns Sorted by XOPEN Code
Transaction Isolation Terminology
SQL Service Edge Returns Sorted by XOPEN Code
The following table lists SQL Service edge returns that are sorted by XOPEN code.
Note: All non-00000 edges also follow the fail_operation edge.
XOPEN Code Edge Description
00000 Success, found | notfound The operation is successful.
01000 A general warning is generated.
01001 A cursor operation conflict hasoccurred.
01002 A disconnect error has occurred.
01004 The data is truncated.
01006 The privilege is not revoked.
01S00 An invalid connection string attributeexists.
01S01 There is an error in a row.
01S02 The option value is changed.
07001 The wrong number of parameters areprovided.
iWay Service Manager Component Reference Guide 701
XOPEN Code Edge Description
07002 The parameters are mismatched.
07003 The cursor specification cannot beexecuted.
07004 Parameters are missing.
07005 There is an invalid cursor state.
07006 A restricted data type attributeviolation has occurred.
07008 There is an invalid descriptor count.
08000 A connection exception has occurred.
08001 A connection to the data sourcecannot be made (for example, invalidlicense key).
08002 A connection is already in use.
08003 A connection is not open.
08004 The data source rejected a connectionattempt.
08007 A connection failure has occurredduring a transaction.
08900 The server lookup failed.
08S01 A communication link failure hasoccurred.
21000 A cardinality violation has occurred.
21S01 An insert value list does not matchthe column list.
21S02 The degree of a derived table doesnot match the column list.
SQL Service Edge Returns Sorted by XOPEN Code
702 Information Builders
XOPEN Code Edge Description
22000 A data exception has occurred.
22001 String data has been truncated to theright.
22003 The numeric value is out of range.
22007 fail_syntax An invalid datetime format exists.
22012 Division by zero has occurred.
22018 An error in assignment exists.
22026 The length of string data ismismatched.
23000 An integrity constraint violation hasoccurred.
25000 There is an invalid transaction state.
25S02 The transaction is still active.
25S03 The transaction has been rolled back.
26000 The SQL statement identifier isinvalid.
28000 The authorization specification isinvalid.
34000 The cursor name is invalid.
3C000 duplicate There is a duplicate cursor name.
40000 The commit transaction resulted in arollback transaction.
40001 fail_timeout There is a serialization failure (forexample, timeout or deadlock).
A. Additional SQL Service Reference Information
iWay Service Manager Component Reference Guide 703
XOPEN Code Edge Description
42000 fail_syntax There is a syntax error or access ruleviolation.
42S01 duplicate The base table or view already exists.
42S02 fail_notfound The base table or view is not found.
42S11 duplicate The index already exists.
42S12 fail_notfound The index is not found.
42S21 duplicate The column already exists.
42S22 fail_notfound The column is not found.
42S23 There is no default for the column.
44000 A WITH CHECK OPTION violation hasoccurred.
HY000 A general error has occurred.
HY001 A storage allocation failure hasoccurred.
HY002 The column number is invalid.
HY003 The application buffer type is invalid.
HY004 The SQL data type is invalid.
HY008 The operation was cancelled.
HY009 The use of a null pointer is invalid.
HY010 A function sequence error hasoccurred.
HY011 The operation is invalid at this time.
HY012 The transaction operation code isinvalid.
SQL Service Edge Returns Sorted by XOPEN Code
704 Information Builders
XOPEN Code Edge Description
HY015 No cursor name is available.
HY018 The server declined a cancel request.
HY090 There is an invalid string or bufferlength.
HY091 The descriptor type is out of range.
HY092 The attribute or option type is out ofrange.
HY093 The parameter number is invalid.
HY095 The function type is out of range.
HY096 The information type is out of range.
HY097 The column type is out of range.
HY098 The scope type is out of range.
HY099 The nullable type is out of range.
HY100 The uniqueness option type is out ofrange.
HY101 The accuracy option type is out ofrange.
HY103 The direction option is out of range.
HY104 The precision or scale value is invalid.
HY105 The parameter type is invalid.
HY106 The fetch type is out of range.
HY107 The row value is out of range.
HY108 The concurrency option is out ofrange.
A. Additional SQL Service Reference Information
iWay Service Manager Component Reference Guide 705
XOPEN Code Edge Description
HY109 The cursor position is invalid.
HY110 The driver completion is invalid.
HY111 The bookmark value is invalid.
HYC00 The driver is not capable.
HYT00 fail_timeout The timeout expired.
HYT01 fail_timeout There is a timeout in some databases(not XOPEN standard).
HZ010 An Access control violation RDA errorhas occurred.
HZ020 A bad repetition count RDA error hasoccurred.
HZ080 A resource not available RDA errorhas occurred.
HZ090 A resource already open RDA errorhas occurred.
HZ100 A resource unknown RDA error hasoccurred.
HZ380 An SQL usage violation RDA error hasoccurred.
IM001 The driver does not support thisfunction.
IM002 fail_notfound The data source name is not foundand no default driver is specified.
IM003 The specified driver could not beloaded.
IM004 The AllocEnv property of the driverfailed.
SQL Service Edge Returns Sorted by XOPEN Code
706 Information Builders
XOPEN Code Edge Description
IM005 The AllocConnect property of thedriver failed.
IM006 The SetConnectOption property of thedriver failed.
IM007 No data source or driver is specified.The dialog is prohibited.
IM008 The dialog failed.
IM009 The translation DLL could not beloaded.
IM010 The data source name is too long.
IM011 The driver name is too long.
IM012 There is a driver keyword syntax error.
IM013 There is a trace file error.
Transaction Isolation Terminology
The following table lists and describes the transaction isolation terminology.
Term Definition
Dirty read This describes the situation in which a transaction is permitted toread data from a row that has been modified by another executingtransaction, but not yet committed.
For example:
Transaction 1 changes the row. Transaction 2 reads the changedrow before transaction 1 commits the change. If transaction 1rolls back its changes, then transaction 2 will have read a rowthat, following the rollback, is considered never to have existed.
A. Additional SQL Service Reference Information
iWay Service Manager Component Reference Guide 707
Term Definition
Nonrepeatable read A row is retrieved a second time by a transaction and the valuesin the row differ between the reads.
For example:
Transaction 1 reads a row. Transaction 2 deletes or updates thatrow and commits the change. If transaction 1 then attempts toreread the row, it will receive the updated value, or discover thatthe row does not exist.
Phantom read During the course of a transaction, two identical queries areexecuted and different result sets are returned.
For example:
Transaction 1 reads a set of rows that satisfy some searchcriteria. Transaction 2 then inserts a row that matches the searchcriteria. Therefore if transaction 1 re-executes the statement thatoriginally read the rows, it receives a different result set of rows.
Transaction Isolation Terminology
708 Information Builders
AppendixBApache Avro Components
Apache Avro is a remote procedure call and data serialization framework developedwithin the Hadoop project of Apache. It uses JSON for defining data types and protocols,and serializes data in a compact binary format. Its primary use is in Apache Hadoop,where it can provide both a serialization format for persistent data, and a wire format forcommunication between Hadoop nodes, and from client programs to the Hadoopservices.
This appendix describes the available components in iWay Service Manager (iSM) thathave been developed to integrate with Apache Avro.
In this appendix:
Avro File Read Service
Avro File Emit Service
Avro File Iterator Service
Avro File Listener
Avro RPC HTTP Emit Service
Avro RPC Over HTTP Listener
Avro File Read Service
Syntax:
com.ibi.agents.XDAvroFileReadAgent
Description:
This service reads an Avro container in binary format and returns the objects it contains. Theobjects are converted to XML or JSON depending on the Conversion Format property. Theconversion rules are documented below. The Avro data may come from the input document ora file.
Avro requires the presence of a schema. The Avro File Read service can use the schemaalways stored in the container, or it can specify a reader schema, in which case Avro will do itsbest to reconcile the two schemas. The effective schema is stored in the output document, soit can serve as a default for the Avro File Emit service.
iWay Service Manager Component Reference Guide 709
The path to the Avro Schema or the Avro Data File can be a regular path in the file system, or aURL starting with hdfs://, which indicates the file is in the Hadoop file system. When theHadoop file system is used, the parameters Hadoop Configuration and Default File System canbe optionally specified. Otherwise, they are ignored.
Parameters:
The following table describes the parameters of the Avro File Read service.
Parameter Description
Avro Schema Path to the Avro Schema file. If absent, the schema storedwith the data will be used.
Conversion Format Format of the incoming Avro data after conversion. Thechoices are XML or JSON.
Input Source Whether the Avro data is in the Input Document or in a File.
Avro Data File Path to the Avro data file. This is ignored if the Input Sourceis the Input Document.
Hadoop Configuration Path to the Hadoop configuration file, normally core-site.xml
Default File System In some Hadoop environments, this should be specified asthe URI of the namenode, for example hdfs://[yournamenode].
Edges:
The following table describes the edges that are returned by the Avro File Read service.
Edge Description
success The Avro data was successfully converted to XML.
fail_parse An iFL expression could not be evaluated.
fail_notfound A file path was specified but the file does not exist.
fail_operation The operation could not be completed successfully.
Avro File Read Service
710 Information Builders
XML Conversion Format:
When converting an Avro container to XML, the resulting document has the following format:
<av:avro xmlns:av="http://iwaysoftware.com/avro"> <av:item> ... </av:item> <av:item> ... </av:item> ...</av:avro>
The actual document is not indented. It is pretty-printed here for display purposes only.
The av:avro element represents the Avro container. Each av:item child element represents oneAvro object in the container. The contents of the av:item varies depending on its type.
The following table describes how the various Avro types are converted to XML:
Avro Type XML Representation
null The element has an xsi:nil attribute set to true and no contents. Forexample:
<av:item xsi:nil="true"/>
boolean The string true or false. For example:
<av:item>true</av:item>
int A numeric string. For example:
<av:item>123</av:item>
long A numeric string. For example:
<av:item>123</av:item>
float A numeric string in a fixed point or scientific notation. For example:
<av:item>12.34</av:item>
double A numeric string in fixed point or scientific notation. For example:
<av:item>1.23E-12</av:item>
B. Apache Avro Components
iWay Service Manager Component Reference Guide 711
Avro Type XML Representation
string The string. For example:
<av:item>abc</av:item>
enum The symbol string. For example:
<av:item>SPADES</av:item>
bytes A string of hexadecimal digits, each byte taking exactly two digits. Forexample:
<av:item>040AFCFF</av:item>
fixed A fixed-length string of hexadecimal digits, each byte taking exactlytwo digits. For example:
<av:item>040AFCFF</av:item>
record Each field becomes an unqualified sub-element with the same nameas the field and no XML namespace. For example:
<av:item> <name>John Smith</name> <address>123 Main Street</address> <city>New York</city> <state>NY</state></av:item>
array Each item in the array becomes an av:item sub-element. Forexample:
<av:item> <av:item>10</av:item> <av:item>42</av:item> <av:item>99</av:item></av:item>
The actual document is not indented.
Avro File Read Service
712 Information Builders
Avro Type XML Representation
map Each entry in the map becomes an av:entry sub-element with the keyattribute set to the key, and the contents set to the entry value. Forexample:
<av:item> <av:entry key="k1">val1</av:entry> <av:entry key="k2">val2</av:entry> <av:entry key="k3">val3</av:entry></av:item>
The actual document is not indented.
union The element has an xsi:type attribute set to the selected type and itscontents is the union value directly as if the union did not exist. Forexample:
<av:item xsi:type="int">123</av:item>
The xsi:type attribute is omitted If the union has only two possibletypes, one of which is null. For example:
<av:item>123</av:item>
or else:
<av:item xsi:nil="true"/>
For more complex types, the rules are applied recursively. The name of the elementrepresenting a value is always chosen by the rules of its parent scope. The outermost elementof an object is always av:item, then the sub-elements might be av:item, av:entry, or the nameof a field in a record depending on the type.
Consider the following Avro complex type:
{"type": "record", "name": "Outer", "fields": [ {"name": "rec1", "type": {"type": "record", "name": "Inner", "fields": [ {"name": "f1", "type": "string"}, {"name": "f2", "type": "int"}]}}, {"name": "map1", "type": {"type": "map", "values": "string"}}, {"name": "array1", "type": {"type": "array", "items": "int"}}, {"name": "union1", "type": ["null", "string"]}, {"name": "union2", "type": ["null", "string"]}, {"name": "union3", "type": ["int", "string"]}]}
B. Apache Avro Components
iWay Service Manager Component Reference Guide 713
An instance of this record might look like the following syntax, once it is converted to XML(shown for display purposes only):
<av:item> <rec1> <f1>str1</f1> <f2>11</f2> </rec1> <map1> <av:entry key="k1">v1</av:entry> <av:entry key="k2">v2</av:entry> </map1> <array1> <av:item>10</av:item> <av:item>20</av:item> <av:item>30</av:item> </array1> <union1 xsi:nil="true"/> <union2>u2</union2> <union3 xsi:type="int">33</union3> </av:item>
This would be one item in the av:avro element representing the Avro container.
JSON Conversion Format
When converting an Avro container to JSON, the resulting document is a JSON array. Each itemin the array represents one Avro object in the container. The type of each item depends on theAvro schema.
The following table describes how the various Avro types are converted to JSON.
Avro Type JSON Representation
null null
boolean The value true or false.
int The integer value.
For example:
123
long The long value.
For example:
123
Avro File Read Service
714 Information Builders
Avro Type JSON Representation
float The float value in a fixed point or scientific notation.
For example:
12.34
double The double value in a fixed point or scientific notation.
For example:
1.23E-12
string The string. For example:
"abc"
enum The symbol string. For example:
"SPADES"
bytes A string where every byte is converted to an ISO8859-1 character.
For example:
"éö"
fixed A string where every byte is converted to an ISO8859-1 character.
For example:
"éö"
record A JSON Object.
For example:
{"name":"John Smith", "address":"123 Main Street", "city":"New York", "state":"NY"}
The actual document is not indented.
B. Apache Avro Components
iWay Service Manager Component Reference Guide 715
Avro Type JSON Representation
array A JSON Array. The item values are converted recursively. Forexample:
[10,42,99]
The actual document is not indented.
map A JSON Object. The key becomes the field name. For example:
{"k1":"val1", "k2":"val2", "k3":"val3"}
The actual document is not indented.
union A JSON Object with a single field. The field name is the full name ofthe selected type. The field value is the value of the union. As aspecial case, a null value in a union is converted directly to null as ifthe union did not exist. For example:
{"int":123}
For more complex types, the rules are applied recursively. Consider this Avro complex type(shown indented for display purposes only):
{"type": "record", "name": "Outer", "fields": [ {"name": "rec1", "type": {"type": "record", "name": "Inner", "fields": [ {"name": "f1", "type": "string"}, {"name": "f2", "type": "int"}]}}, {"name": "map1", "type": {"type": "map", "values": "string"}}, {"name": "array1", "type": {"type": "array", "items": "int"}}, {"name": "union1", "type": ["null", "string"]}, {"name": "union2", "type": ["null", "string"]}, {"name": "union3", "type": ["int", "string"]}]}
An instance of this record might look like the following syntax once it is converted to JSON(shown indented for display purposes only).
Avro File Read Service
716 Information Builders
{"rec1": {"f1":"str1", "f2":11}, "map1": {"k1":"v1", "k2":"v2"}, "array1":[10,20,30], "union1":null, "union2":{"string":"u2"}, "union3":{"int":33}}
This would be one value within the array representing the whole container.
Avro File Emit Service
Syntax:
com.ibi.agents.XDAvroFileEmitAgent
Description:
This service converts an XML or JSON document into Avro binary format and writes the result inan Avro container file.
If the input document is XML, the root element in the input document can be <av:avro>, inwhich case multiple objects will be written to the container, one per <av:item> sub-element. Ifthe root element is <av:item>, a single object will be written to the container. Any other rootelement will cause a failure. The av prefix stands for the XML Namespace http://iwaysoftware.com/avro. The actual name of the prefix is immaterial. The rules to convert fromXML to Avro are strict and can be read backwards from the Avro to XML rules as described inthe Avro File Read Service on page 709.
If the input document is JSON, the value will typically be an array to write multiple objects tothe container, one per array item. Other value types will cause a single object to be written tothe container. To write a single array object, wrap it in an outer JSON array. The conversionfrom JSON back to Avro is lenient. The rules are described below.
The resulting container can be compressed to reduce its size. The choices for the compressionalgorithm are:
No Compression
BZip2
Deflate
Snappy
B. Apache Avro Components
iWay Service Manager Component Reference Guide 717
XZ
The default is No Compression.
Avro requires the presence of a schema. The Avro File Emit service can use the schemaspecified in its parameter, or it can use the schema stored in the input document as thedefault. The only way to store a schema in the document is to use another Avro componentthat produces XML, for example the Avro File listener, the Avro File Read service or the AvroFile Iterator service.
The output document returned can be the input document or a status document depending onthe Return property.
Parameters:
The following table describes the parameters of the Avro File Emit service.
Parameter Description
Avro Writer Schema Path to the Avro Schema file. If absent, the schema storedwith the document will be used.
Compression Codec Algorithm used to compress the data.
Target Directory The target output directory.
File Pattern The output file name, which can contain an asterisk (*)which gets expanded to a fine timestamp.
Avoid Preemitter Indicate which preemitter(s) should be avoided.
Return Whether the out document will be the input document or astatus document
Respect Transactionality If set, the emit respects the transactionality of the channel.If not set, the emit is always done.
Avro File Emit Service
718 Information Builders
Edges:
The following table describes the edges that are returned by the Avro File Emit service.
Edge Description
success The Avro data was successfully converted to XML.
fail_parse An iFL expression could not be evaluated.
fail_operation The operation could not be completed successfully.
JSON to Avro Conversion
The rules to convert from JSON to Avro are described in the following table. The natural JSONrepresentation can be read backwards in the Avro to JSON conversion rules as described in the Avro File Read Service on page 709.
Often, other JSON data types are supported with an extra conversion.
Avro Type toCreate
Accepted JSON Representation
null null
boolean JSON booleans map naturally. Integer numbers other than 0 map totrue, 0 maps to false, and the true and false Strings map to thecorresponding values. Objects and Arrays map to false.
int JSON numbers are coerced using default Java rules. Booleansconvert to 0 (false) and 1 (true), and Strings are parsed using defaultJava language integer parsing rules. Objects and Arrays map to 0.
long JSON numbers are coerced using default Java rules. Booleansconvert to 0 (false) and 1 (true), and Strings are parsed using defaultJava language integer parsing rules. Objects and Arrays map to 0.
float Numbers are coerced using default Java rules. Booleans convert to0.0 (false) and 1.0 (true), and Strings are parsed using default Javalanguage integer parsing rules. Objects and Arrays map to 0.
B. Apache Avro Components
iWay Service Manager Component Reference Guide 719
Avro Type toCreate
Accepted JSON Representation
double Numbers are coerced using default Java rules. Booleans convert to0.0 (false) and 1.0 (true), and Strings are parsed using default Javalanguage integer parsing rules. Objects and Arrays map to 0.
string Value nodes map to the string representation of the value. Objectsand Arrays map to the empty string.
enum Value nodes map to the string representation of the enum symbol.Objects and Arrays are invalid.
bytes Value nodes map to the string representation of the value. Objectsand Arrays map to the empty string. The string is then converted tobytes using ISO8859-1 encoding.
fixed Value nodes map to the string representation of the value. Objectsand Arrays map to the empty string. The string is then converted tobytes using ISO8859-1 encoding. The number of bytes must matchthe length of the fixed data type.
record A JSON Object.
array A JSON Array.
map A JSON Object.
union A JSON Object with a single field. The field name is the full name ofthe selected type. The field value is the value of the union. A JSONnull is also accepted if the union contains the null type.
Avro File Iterator Service
Syntax:
com.ibi.agents.XDIterAvroFile
Avro File Iterator Service
720 Information Builders
Description:
The Avro File Iterator opens an Avro container in the input document or in a file, and returnsthe objects it contains one by one. The object is converted to XML or JSON depending on theConversion Format property. The conversion rules are documented with the Avro File Readservice. For more information, see Avro File Read Service on page 709. Since the iterateddocument will only contain one object, the container wrapper will be absent. For example, theroot element will always be av:item when converting to XML.
Avro requires the presence of a schema. The Avro File Iterator service can use the schemaalways stored in the container, or it can specify a reader schema, in which case Avro will do itsbest to reconcile the two schemas. The effective schema is stored in the output document, soit can serve as a default for the Avro File Emit service.
The path to the Avro Schema or the Avro Data File can be a regular path in the file system, or aURL starting with hdfs://, which indicates the file is in the Hadoop file system. When theHadoop file system is used, the parameters Hadoop Configuration and Default File System canbe optionally specified, otherwise they are ignored.
The Output Document parameter determines the final document. It can be a status document,the original document, the result of the last iteration or an accumulation. The format of thefirst accumulated value determines the format of the whole accumulation. If the firstaccumulated value is XML, then the whole accumulation will be XML. Similarly, if the firstaccumulated value is JSON, then the whole accumulation will be JSON.
When accumulating XML, the XML Accumulation Root parameter determines the root element.Select av:avro when accumulating av:item elements into an XML document that represents anAvro container. This is the case with Iterated Accumulation (because the iterator alwaysproduces av:item elements) or with Loop Accumulation when the loop does not modify the rootelement. Selecting av:avro will also set the schema in the final document. That schema canserve as a default in an Avro File Emit service.
When accumulating JSON, the accumulated values are stored in a JSON array.
Parameters:
The following table lists and describes the parameters of the Avro File Iterator service.
Parameter Description
Avro Schema Path to the Avro Schema file. If absent, the schema stored withthe data will be used.
B. Apache Avro Components
iWay Service Manager Component Reference Guide 721
Parameter Description
Conversion Format Format of the incoming Avro data after conversion. The choicesare XML or JSON.
Input Source Whether the Avro data is in the input document or in a file.
Avro Data File Path to the Avro data file. Ignored if the Input Source is InputDocument.
Hadoop Configuration Path to the Hadoop configuration file, normally core-site.xml
Default File System In some Hadoop environments, this should be specified as theURI of the namenode, for example:
hdfs://[your namenode]
Output Document The final document emitted is a status document, which is theoriginal document or the result of the last iteration or anaccumulation. Accumulations are memory intensive.
XML Accumulation Root Determines the root element of an accumulation. Select av:avrowhen accumulating av:item elements. Otherwise, selectaccumulation. This is ignored if the Output Document is notaccumulating or if the first accumulated item is parsed JSON.
Avro File Listener
Syntax:
com.ibi.edaqm.XDAvroFileMaster
Description:
The Avro File Listener detects files in directories, opens each file as an Avro container, andreturns the objects it contains one by one. The objects are converted to XML or JSONdepending on the Conversion Format property. The conversion rules are documented with theAvro File Read service. For more information, see Avro File Read Service on page 709. Sincethe document will only contain one object, the container wrapper will be absent. For example,the root element will always be av:item when converting to XML.
Avro File Listener
722 Information Builders
Avro requires the presence of a schema. The Avro File Listener can use the schema alwaysstored in the container, or it can specify a reader schema, where Avro will do its best toreconcile the two schemas. The effective schema is stored in the output document so it canserve as a default for the Avro File Emit service.
Parameters:
The following table lists and describes the parameters of the Avro File Listener.
Parameter Description
Avro Schema Path to the Avro Schema file. If absent, the schema storedwith the data will be used.
Conversion Format Format of the incoming Avro data after conversion. Thechoices are XML or JSON.
Input Path Directory in which input messages are received. A specific filename or DOS-style regular expression pattern can be used. Ifyou include the suffix in the pattern (such as ab*.xml) then besure to configure the Suffix In to allow any suffix. Multiplelocations can be specified, separated by a comma (,) or semi-colon (;) character.
Destination Directory into which output files are stored. The specific filename is optional. Use an asterisk (*) in the file name to bereplaced by a timestamp and number sign (#) by sequentialcounter. If required directories are not present at run time,iSM will attempt to create them. At run time, if it is unclearwhether path names a directory or a filename, iSM willassume the path names a file.
Removal Destination Full path file pattern asserting where input files will be moved.Use an asterisk (*) in file name to be replaced by timestampand number sign (#) by sequential counter.
B. Apache Avro Components
iWay Service Manager Component Reference Guide 723
Parameter Description
Suffix In Filter The listener will match the extension exactly, in addition to thecorresponding all-uppercase and all-lowercase extensions.
Specify xml to accept files with .xml extensions. Do not use aperiod (.) character. Instead, use the en dash (-) character toindicate no extension, or an asterisk (*) character to indicateany extension.
Scan Subdirectories If true, all subdirectories will be scanned for files to process.
Suffix Out Extension for output files (name is the same as the input fileunless specified in the destination parameter).
Sort Order Sort the incoming documents by the specified rule.
Maximum File Size Only files smaller than this value will be processed by thelistener. You can leave this field blank or set it to zero for nolimit. The value can be entered with KB or MB, for example,23MB for 23 megabytes, or enter with no suffix to specify sizein bytes.
Large File Directory Full path file pattern asserting where files exceeding themaximum file size will be moved. Use an asterisk (*) in filename to be replaced by timestamp and number sign (#) bysequential counter.
Batch Mode If true, do not poll until all files from the previous poll havefinished processing.
Inbound HeaderNamespace
Special register namespace into which metadata values forthe input file will be saved.
Maximum Inputs Maximum number of files that can be accepted for processingin a single poll. Note that if the number of files in the inputdirectory exceeds this, sorting options may not work asexpected. Enter 0 or leave blank for no limit.
Avro File Listener
724 Information Builders
Avro RPC HTTP Emit Service
Syntax:
com.ibi.agents.XDAvroRpcHttpEmitAgent
Description:
This service converts an Avro RPC request from XML or JSON into Avro binary format, sends itover HTTP, and optionally returns the response.
The rules to convert the request from XML to Avro can be read backwards from the Avro to XMLrules, as described in the Avro File Read Service on page 709. The rules to convert the requestfrom JSON to Avro are documented with the Avro File Emit Service, as described in the AvroFile Emit Service on page 717.
An Avro Protocol file describes the possible interactions with the Avro server. The MessageName parameter selects which interaction to execute.
The path to the Avro Protocol file can be a regular path in the file system, or a URL startingwith hdfs://, which indicates the file is in the Hadoop file system. When the Hadoop filesystem is used, the parameters Hadoop Configuration and Default File System can beoptionally specified, otherwise they are ignored.
The Avro Protocol declares a request as an array of named parameters with their types. Fromthis, Avro derives the request schema as an anonymous record, each field of the record beingone of the parameters. The input document must be an XML document that obeys thatschema. For more information on the conventions of the XML representation of an Avro record,see the Avro File Read service.
The service can return the response, a status document, or the input document. The last twooptions make more sense for one-way messages.
The output will obey the response schema of the message if the service is configured to returnthe response and the call is successful. The response is converted to the same format usedby the input document (XML or JSON). For more information on conversion rules from XML orJSON to Avro, see Avro File Read Service on page 709. For one-way messages, the responseschema is equivalent to null. If the call is not successful, the response will obey the errorsschema. This is a union that implicitly always includes the string schema. The appropriateschema will be stored as extra metadata in the output document. For example, this can serveas a default for the schema in the Avro File Emit service.
The service refers to an HTTP Client Provider which is used to manage the HTTP clientconnections. The Provider must be created prior to the service. This can be done in the iSMconsole by selecting Pooling Providers in the left menu of the Server pane.
B. Apache Avro Components
iWay Service Manager Component Reference Guide 725
Parameters:
The following table lists and describes the parameters of the Avro RPC HTTP Emit service.
Parameter Descriptions
Target URL URL to post this information to, for example:
http://thehost:9876
Avro Protocol Path to the Avro Protocol file. The standard extension is .avpr
Hadoop Configuration Path to the Hadoop configuration file, normally core-site.xml
Default File System In some Hadoop environments, this should be specified as theURI of the namenode. For example:
hdfs://[your namenode]
Message Name Selects the message within the Avro Protocol.
HTTP Client Provider HTTP Client Provider (Pooling Provider) that manages HTTPconnections for this emitter.
Cookie Store Name Allows thread-specific management of cookies. If a name is notspecified, a cookie store global to the HTTP Client provider willbe used.
User ID User ID for authentication challenges.
Password Password for authentication challenges.
Domain Domain for NTLM authentication challenges. Note that to useNTLM, you must enable connection persistence.
Request HeaderNamespace
Special register namespace from which HTTP headers for theoutgoing request will be taken. Select Default Namespace tosend HDR type registers with no namespace prefix, or you cansupply a namespace prefix here. The None option means that nospecial registers will be sent as HTTP headers.
Avro RPC HTTP Emit Service
726 Information Builders
Parameter Descriptions
Response HeaderNamespace
Special register namespace into which HTTP headers from theincoming response will be saved. Select Default Namespace tocreate special registers with no namespace prefix, or you cansupply a namespace prefix here.
Excluded Headers Comma delimited list (case insensitive) of headers that shouldnot be sent with a request, even if it is found in a requestheader namespace.
Ask for CompressedResponse
If set, requests will set the Accept-Encoding header to indicatethat the client can accept a compressed response, as describedin RFC-2616. If the response has a compressed contentencoding, the client will automatically inflate.
Compress Request If set, the HTTP request entity will be compressed using theselected encoding and the Content-Encoding header will be setaccordingly.
Release ConnectionImmediately
If true, the connection will be released to the connection poolimmediately. This is the default. If false, the connectionidentifier is stored in the httpclient-key special register and theHTTP Client Manager agent must be called later to release theconnection explicitly.
Maximum HTTP ClientManager Delay
Maximum time the HTTP Client Manager can take to deal with aparticular connection before it is automatically aborted. Theformat is [xxh][xxm]xx[s]. The default is 60 seconds.
Try Expect/ContinueHandshake?
If selected, the client will send the HTTP Expect: 100-continueheader and await HTTP 100 response before sending therequest body.
Chunk EncodedRequest?
If true, the request entity will be sent with chunk encoding.
Maximum Request Size Maximum size, after compression, of a request entity that canbe sent with this emitter. 0 means no maximum, and a blankfield will default to 256KB.
B. Apache Avro Components
iWay Service Manager Component Reference Guide 727
Parameter Descriptions
Maximum ResponseSize
Maximum size of a response entity that can be received by thisemitter. 0 means no maximum, and a blank field will default to256KB.
Persistence If selected, ask the server to maintain the connection.
Response Timeoutvalue in Seconds
Seconds to wait for a response before signaling an error.
Return Return from this agent. Select input to return an inputdocument, status for an XML document with transactionparameters and status, or response to capture output from theserver.
Edges:
The following table describes the edges that are returned by the Avro RPC HTTP Emit service.
Edge Description
NNN Where NNN is a 3-digit integer, HTTP status codes 100-599.
success The Avro RPC request was successful.
fail_connect An iFL expression could not be evaluated.
fail_info HTTP status codes 100-199.
fail_redirection HTTP status codes 300-399.
fail_client HTTP status codes 400-499.
fail_server HTTP status codes 500-599.
fail_operation The operation could not be completed successfully.
fail_parse An iFL expression could not be evaluated.
fail_request_too_large The request is larger than the configured Maximum RequestSize.
Avro RPC HTTP Emit Service
728 Information Builders
Edge Description
fail_response_too_large The response is larger than the configured MaximumResponse Size.
The service often returns more than one edge with the more specific edge first. For example, ifthe request is unauthorized, the returned edges will be 401,fail_client. This can be handled bywiring the edge 401, or fail_client, or OnFailure.
Example:
The following syntax shows a sample Avro protocol taken from the Avro test suite.
{"namespace": "org.apache.avro.test", "protocol": "Mail", "types": [ {"name": "Message", "type": "record", "fields": [ {"name": "to", "type": "string"}, {"name": "from", "type": "string"}, {"name": "body", "type": "string"} ] } ], "messages": { "send": { "request": [{"name": "message", "type": "Message"}], "response": "string" }, "fireandforget": { "request": [{"name": "message", "type": "Message"}], "response": "null", "one-way": true } }}
A sample XML request to call the send message can be similar to the following syntax(indented for display purposes only):
<av:item xmlns:av=\"http://iwaysoftware.com/avro\"> <message> <to>wife</to> <from>husband</from> <body>I love you!</body> </message></av:item>
B. Apache Avro Components
iWay Service Manager Component Reference Guide 729
The same request in JSON is similar to the following syntax (indented for display purposesonly):
{"message": {"to":"wife", "from":"husband", "body":"I love you!"}}
Since the send message has a single request argument called message, the anonymousrecord contains a single field called message.
A sample XML response for the send message may appear similar to the following syntax:
<av:item xmlns:av=\"http://iwaysoftware.com/avro\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">Sent message to [wife] from [husband] with body [I love you!]</av:item>
The same response in JSON is similar to the following syntax:
"Sent message to [wife] from [husband] with body [I love you!]"
A sample request for the fireandforget message would be identical to the request for the sendmessage because they have the same request arguments. The selected message isconfigured by the Message Name parameter of the service, not within the input document.
The response for the fireandforget message will be the nil item since the message is one-way.
<av:item xmlns:av="http://iwaysoftware.com/avro" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
The same response in JSON is:
null
Avro RPC Over HTTP Listener
Syntax:
com.ibi.edaqm.XDAvroRpcHttpMaster
Descriptions:
The Avro RPC over HTTP Listener accepts Avro RPC requests in binary format over HTTP. Therequest is converted to XML or JSON depending on the Conversion Format property. After therequest is executed, the response is converted from XML or JSON to Avro RPC binary and sentback.
Avro RPC Over HTTP Listener
730 Information Builders
An Avro Protocol file describes the possible interactions between the Avro RPC client and thelistener. The path to the Avro Protocol file can be a regular path in the file system, or a URLstarting with hdfs://, which indicates the file is in the Hadoop file system. When the Hadoopfile system is used, the parameters Hadoop Configuration and Default File System can beoptionally specified. Otherwise, they are ignored.
In Avro RPC, an interaction is called a message. The Protocol declares the request, response,and errors schema for each message it contains. The Avro Protocol declares a request as anarray of named parameters with their types. From this, Avro derives the request schema as ananonymous record, each field of the record being one of the parameters. The responseschema is simpler because the Avro Protocol defines its type directly. The errors schema isalways a union, which implicitly includes the type string.
The listener can interpret the incoming request because it can retrieve the message metadatabased on the message name encoded in the request. The request is converted from binaryAvro to XML or JSON according to the request schema. That schema will be stored as extrametadata in the input document. For example, this can serve as a default for the schema inthe Avro File Emit service.
The response is converted to binary Avro based on the response schema in general, or theerrors schema if the document is in error.
For more information on the conventions of the XML representation of the Avro data, see theAvro File Read service documentation.
The rules to convert the request from binary Avro to XML or JSON are described in the Avro FileRead Service on page 709. The rules to convert the response from XML to Avro can be readbackwards from these tables. The rules to convert the response from JSON to Avro aredescribed in the Avro File Emit Service on page 717.
For more information and an example of an Avro Protocol and sample request/responsedocuments in XML or JSON, see the Avro RPC HTTP Emit Service document.
The Avro RPC over HTTP listener has many parameters similar to the HTTP 1.1 non-blocking IOlistener (NHTTP). For more information on the parameters controlling HTTP, see thedocumentation of that listener.
Parameters:
The following table lists and describes the parameters of the Avro RPC over HTTP Listener.
Parameter Description
Avro Protocol Path to the Avro Protocol file. Typical extension is .avpr.
B. Apache Avro Components
iWay Service Manager Component Reference Guide 731
Parameter Description
Conversion Format Format of the incoming Avro data after conversion. The choicesare XML or JSON.
Hadoop Configuration Path to the Hadoop configuration file, normally core-site.xml.
Default File System In some Hadoop environments, this should be specified as theURI of the namenode. For example:
hdfs://[your namenode]
Special Registers (SREGs):
The following table lists and describes the Special Registers (SREGs) for the Avro RPC overHTTP Listener.
Register Type Description
avromessage string The name of the message within the AvroProtocol that corresponds to the incomingrequest.
In addition to the avromessage SREG, the Avro RPC over HTTP Listener inherits the sameSREGs as the Non-blocking HTTP (nHTTP) Listener.
Avro RPC Over HTTP Listener
732 Information Builders
Index
C
COBOL 295
E
EDIFACT 587, 624, 661
Excel 591
H
HIPAA 599, 625, 640
I
Iterators 671
L
LDAP Reader 293
P
preemitters 630
adding 630
Constant PE preemitter 634
Deflate preemitter 635
EDIX12 preemitter 636
Entity Repl preemitter 636
File read preemitter 637
Flat Delim preemitter 638
HIPAA preemitter 640
iWay Transformations preemitter 640
preemitters 630
Legacy Record preemitter 647
Marshalls a message preemitter 648
Multi Part preemitter 649
PGP Sign Only preemitter 653
PGPEncrypt preemitter 651
QA Print preemitter 654
Remove Outer Tag preemitter 657
Replace Paired Characters preemitter 659
SWIFT preemitter 660
UUEncodePreEmitter 660
XDEDIFACT preemitter 661
XDSWIFT preemitter 661
XSL Tpre preemitter 661
preparsers 577
Append preparser 583
C Char Filter preparser 583
Char Repl preparser 585
Concatenated XML Document Stream
preparser 614
Delimited Value Splitter preparser 621
Delimited Value Stream preparser 616
EDIBatchSplitter preparser 623
EDIFACT preparser 587
EDIFACTBatchSplitter preparser 624
EDIH7PreParser preparser 587
EDIX12 preparser 588
EDIX12 XML validator preparser 588
EDIX12Splitter preparser 624
iWay Service Manager Component Reference Guide 733
preparsers 577
En Tag preparser 588
Error Filter preparser 590
Excel preparser 591
Flat Stream preparser 618
HIPAA preparser 599
HIPAABatchSplitter preparser 625
HIPAASplitter preparser 625
HTTP preparser 599
Inflate preparser 600
JMS Object preparser 601
Legacy Record preparser 602
Multipart nHTTP preparser 605
Multipart preparser 603
PGP Decrypt preparser 607
PGP Verify Signiture Only preparser 607
Replace characters on a one for one basis
preparser 607
Smime preparser 608, 612
SOAP preparser 609
splitters 620
SREG preparser 610
streaming 614
SWIFT preparser 611
SWIFTAck preparser 611
SWIFTBatchSplitter preparser 625
SWIFTSystemMessage preparser 612
Unmarshalls a message preparser 613
XDSWIFT preparser 614
XML Splitter preparser 626
R
RabbitMQ Emit service 363
RabbitMQ Read service 367
S
services 21
Accumulate EOS service 26
Activity Log Entry service 35
Add Attachment From File service 37
Add Attachment service 40
Add Correl Entry service 42
Alt Route IP service 43
Append Stream to File Service 44
AQ Emit service 46
AS 1 Emit service 56
AS 2 Emit service 60
AS 2 Nonblocking Emit service 49
AS 2 Nonblocking Send MDN service 65
Attachment Operations service 68
Attachment to Document service 69
Attachment to File Service 71
Base64 Operation service 76
Bearer Token Agent Service 78
Blank Elimination service 81
C Char Filter service 109
Cancel service 83
Catch service 85
Channel Information service 89
Check Schema service 92
Commit or Rollback within a Flow service 97
Index
734 Information Builders
services 21
Constant service 98
Controls Listeners service 100
Cookie Store Agent Service 105
Correl Inquiry By State service 106
Correl Inquiry service 107
Correl Set Inquiry service 108
Deflate service 119
Delete an Item Service 128
destroy status Service 130
Document Attachment service 154
Document Copy service 132
Document state modification Service 140
Document Update service 142
DQC (document-driven, pooling) 159
DQC (non-pooling, deprecated) 117
DQC (user parameter-driven, pooling) 163
DQC Batch Executor 156
DQC/MDC Flow Linkage 158
EDI Accumulator Service 168
EDI Rule Router Service 169
EDIFACT ValidationReportAgent Service 171
EDIFACTAckAgent Service 170
EDIHL7 ValidationReport Agent Service 173
EDIHL7AckAgent Service 172
EDIWrapperAgent Service 174
EDIX12AckAgent Service 176
EDIX12TransformAgent Service 175
Email Emit service 177
Entag service 182
services 21
Ethereum Call Agent Service 183
Ethereum Call Constant Function Agent
Service 185
Ethereum Deploy Agent Service 186
Ethereum Transfer Agent Service 188
Excel reader Service 189
Execute ETL service 190
Fail service 192
File Emit service 201
File operations Service 206
File read 208
File Read service 210
Form Data Agent Service 213
HTTP Client Pool Manager Service 221
HTTP Client Service 215
HTTP Cookie Agent Service 219
HTTP Emit service 222
HTTP Nonblocking Emit service 228
HTTP Read service 232
HTTP ReST Routing service 236
HTTP Session Invalidator Agent Service 238
Hyperledger Fabric Key History Agent Service
239
Hyperledger Fabric Query Agent Service 241
Hyperledger Fabric Query Block Agent Service
242
Hyperledger Fabric Transaction Agent Service
244
IEI Feed Agent Service 246
Index
iWay Service Manager Component Reference Guide 735
services 21
Inflate service 247
Insert SAML Assertion service 250
Insert WSSE Timestamp service 251
Insert WSSE Token service 251
Inserts data inside an XML document Service
248
Internal Emit service 251
Is Reachable service 257
JDBC service 269
JDBC via iWay JNDI Datasource Service 272
JMS Read Agent service 276
JMSQ Browse service 273
JMSQ Emit service 274
LDAP Reader 293
Legacy Record to XML Converter service 295
Local Master service 302
Log Business Error service 32
Mail Attach service 303
Mark Attach service 306
Move service 310
MQ Emit service 311
MQ JMS Emit Agent Service 312
MQ Read service 315
MQTT Emit Agent Service 317
MSMQ Emit service 318
MTOM service 320
Node Set Extract service 322
NTCP Client Write Agent Service 325
NTCP Emit Agent Service 323, 326
services 21
NTCP Read Agent Service 328
NTCP Respond Agent Service 330
OAuth 1.0 Authentication service 331
OAuth 2.0 Authentication service 332
OpenRules service 333
P Flow service 358
P Flow Test service 361
Parallel Execution: Counted iteration Service
334
Parallel Execution: JSON iteration Service 335
Parallel Execution: XML iteration Service 337
Parse to XML service 339
PDF Form Field Reader Service 341
PF File Operations service 342
PF File Read service 343
PGP Decryption and Verification Service 345
PGP Encryption and Signature Service 346
PGP Sign Only Service 350
PGP Verify Signature Only Service 351
Preemitter in Flow service 352
Print Emit service 354
Protocol Business service 357
QA service 361
RabbitMQ Emit service 363
RabbitMQ Read service 367
Route service 371
Rule Router service 372
Run OS Shell Command service 374
Index
736 Information Builders
services 21
RVI Relay: send message to gateway service
Service 377
RVI Response: return iterations to the RVI
Iterator Service 379
RVI Stream Relay Service 380
Schema Validation Service 384
Scripting Agent Service 386
search Service 387
Security Authenticate/Impersonate service 73
Security: Authenticate/Impersonate Service
391
Server Statistics Service 392
Set Document State service 393
Set special registers Service 395
SFTP Connection Cache Service 397
SFTP Direct Transfer Service 399
SFTP Emit Agent Service 402
SFTP File Ops Agent Service 405
SFTP Read Agent Service 408
show status Service 411
SMIME Packer Agent Service 413
SMIME Unpacker Agent Service 416
Snip service 418
Sonic Emit service 421
Sonic Queue Browser service 424
Sonic Read service 426
SP Router service 431
Split service 428
Split To MQ service 429
services 21
SQL service 439
SREG FTP: Pass register settings to iWay FTP
Server Service 457
SREG Insert service 461
SREG Namespace service 463
SREG service 468
SREG: Save/Restore Document Value Service
465
SREG: Save/Restore XML tree Service 466
Store or Reload a Document Value in a
Register service 381
Store or Reload an XML Tree in a Register
service 383
SWIFT Out Report service 474
SWIFT Transform service 475
SWIFT Validation service 476
SWIFT XML Transform service 477
TCP Emit Service 478
TIBCO RV Emit service 482
Transform service 488
Tree Evaluator service 492
UDP Emit service 493
Update Correl Entry service 495
Verify WSSE Timestamp Service 499
Web Service Client service 500
Web Service HTTP Client service 503
X12 Validation service 506
XA Log Inquiry By Context service 507
XA Log Inquiry By Date service 508
Index
iWay Service Manager Component Reference Guide 737
services 21
XA Log Inquiry By Partner service 509
XA Log Inquiry By Transaction ID service 510
XA Log Message service 511
XAdES Digital Signature Create Service 513
XAdES Digital Signature Verify Service 521
XDTwitterGetHomeTimeline Service 524
XDTwitterUpdateStatus Service 526
XML Decryption Service 541
XML Digital Signature Create service 543
XML Digital Signature Verify service 544
XML Encryption Service 544
XML Extract Service 549
XMLtoEDIFACTTransformAgent Service 550
XMLtoEDIHL7TransformAgent Service 553
services 21
XMLtoHIPAATransformAgent Service 553
XMLtoX12TransformAgent Service 556
XQuery Expression Evaluation service 558
Zip Out Service 567
SOAP 609
SQL 439
SWIFT 474–477, 611, 612, 614, 625, 660, 661
T
TIBCO 482
W
worksheets 591
Index
738 Information Builders
FeedbackCustomer success is our top priority. Connect with us today!
Information Builders Technical Content Management team is comprised of many talentedindividuals who work together to design and deliver quality technical documentation products.Your feedback supports our ongoing efforts!
You can also preview new innovations to get an early look at new content products andservices. Your participation helps us create great experiences for every customer.
To send us feedback or make a connection, contact Sarah Buccellato, Technical Editor,Technical Content Management at [email protected].
To request permission to repurpose copyrighted material, please contact Frances Gambino,Vice President, Technical Content Management at [email protected].
Information Builders, Inc.Two Penn PlazaNew York, NY 10121-2898
iWay Service Manager Component Reference GuideVersion 8.0 and Higher
DN3502114.0718