iWay Service Manager Component Reference Guide Version 8.0 and Higher
September 17, 2018 Active Technologies, EDA, EDA/SQL, FIDEL, FOCUS, Information Builders, the Information Builders logo, iWay, iWay Software, Parlay, PC/FOCUS, RStat, Table Talk, Web390, WebFOCUS, WebFOCUS Active Technologies, and WebFOCUS Magnify 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 registered trademarks 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 their trademarks. In most, if not all cases, these designations are claimed as trademarks or registered trademarks by their respective companies. It is not this publisher's intent to use any of these names generically. The reader is therefore cautioned to investigate all claimed trademark rights before using any of these names other than to refer to the product described.
Copyright © 2018, by Information Builders, Inc. and iWay Software. All rights reserved. Patent Pending. This manual, or parts 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 Contents
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
4 Information Builders Contents
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 iWay Service Manager Component Reference Guide 5 Contents
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
6 Information Builders Contents
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 iWay Service Manager Component Reference Guide 7 Contents
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
8 Information Builders Contents
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 iWay Service Manager Component Reference Guide 9 Contents
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
10 Information Builders Contents
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
iWay Service Manager Component Reference Guide 11 Contents
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
12 Information Builders Contents
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 iWay Service Manager Component Reference Guide 13 Contents
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
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, business analysts, and system administrators who want to integrate new XML-based applications seamlessly 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 services that are supplied with iWay Service Manager.
2 iWay Preparsers Provides a reference for all the predefined preparsers that are supplied with iWay Service Manager.
3 iWay Preemitters Provides a reference for all the predefined preemitters that are supplied with iWay Service Manager.
4 iWay Iterators Provides an overview of iterators and their usage within iWay Service Manager process flows.
A Additional SQL Service Provides additional reference information for the Reference Information SQL Service (com.ibi.agents.XDSQLAgent).
B Apache Avro Components Describes the available components in iWay Service Manager (iSM) that have been developed to integrate with Apache Avro.
Documentation Conventions The following table describes the documentation conventions that are used in this manual.
Convention Description
THIS TYPEFACE or Denotes syntax that you must enter exactly as shown. this typeface
iWay Service Manager Component Reference Guide 15 Related Publications
Convention Description
this typeface Represents a placeholder (or variable), a cross-reference, or an important term. It may also indicate a button, menu item, or dialog box 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 only the parameter, not the ellipsis (...).
. Indicates that there are (or could be) intervening or additional commands. .
.
Related Publications Visit our Technical Documentation Library at http://documentation.informationbuilders.com. You can 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 a message board. It is an interactive network of more than 3,000 developers from almost every profession and industry, collaborating on solutions and sharing tips and techniques. Access Focal Point at http://forums.informationbuilders.com/eve/forums.
16 Information Builders Preface
You can also access support services electronically, 24 hours a day, with InfoResponse Online. InfoResponse Online is accessible through our website, http:// www.informationbuilders.com. It connects you to the tracking system and known-problem database at the Information Builders support center. Registered users can open, update, and view the status of cases in the tracking system and read descriptions of reported software issues. New users can register immediately for this service. The technical support section of http://www.informationbuilders.com also provides usage techniques, diagnostic tips, and answers 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:00 a.m. and 8:00 p.m. EST to address all your questions. Information Builders consultants can also give you general guidance regarding product capabilities. Please be ready to provide your six-digit site code number (xxxx.xx) when you call.
To learn about the full range of available support services, ask your Information Builders representative 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 provide specifications 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, iWay Service Manager
Container For example, WebSphere
iWay Service Manager Component Reference Guide 17 Help Us to Serve You Better
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 through a service or event?
Provide usage scenarios or summarize the application that produces the problem.
When did the problem start?
Can you reproduce this problem consistently?
Describe the problem.
Describe the steps to reproduce the problem.
Specify the error message(s).
18 Information Builders Preface
Request/Question Error/Problem Details or Information
Any change in the application environment: software configuration, EIS/database configuration, application, and so forth?
Under what circumstance does the 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 staff welcomes your opinions regarding this document. Please use the Reader Comments form at the end of this document to communicate your feedback to us or to suggest changes that will support 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 for iWay Software and other Information Builders products. iWay Service Manager Component Reference Guide 19 iWay Software Training and Professional Services
For information on course descriptions, locations, and dates, or to register for classes, visit our website, http://education.informationbuilders.com, or call (800) 969-INFO to speak to an Education Representative.
Interested in technical assistance for your implementation? Our Professional Services department provides expert design, systems architecture, implementation, and project management services for all your business integration projects. For information, visit our website, http://www.informationbuilders.com/support.
20 Information Builders Chapter 1 iWay Services
iWay Service Manager includes many predefined services that you can use to enhance the business logic of a message. You can add these services to simple or complex business logic configurations using the iWay Service Manager Administration Console.
For reference purposes, this section lists and describes all the services that are supplied with 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 a message in iWay Service Manager (iSM).
A service is the business layer that incorporates the logic for encapsulating the business process which interacts with other distributed component services to provide transactions for business state information. This business layer incorporates the application business logic. In an iSM environment, business logic consists of one or more services acting on an input document. Services can be stacked, such that the output of one service is passed to the next service, or multiple services can be executed in parallel.
Services are written in standard Java language and can make use of any available Java libraries or services. iWay Software supplies a comprehensive set of predefined services with iSM that you can use as part of your business logic.
Services are configured within process flows using the Process Flow Designer in iWay Integration Tools (iIT). iIT is an Eclipse-based design-time environment that allows you to develop 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 Flow Designer objects to create your process flows.
iWay Service Manager Component Reference Guide 21 Services Overview
Most of the services described in this document are implemented by a corresponding object in the Process Flow Designer. For example, consider the File object, which is available from the Process Flow Designer Palette, under the Connectors group, as shown in the following image.
22 Information Builders 1. iWay Services
The following image shows a simple process flow in the workspace area, where the File object was added (dragged and dropped) between the Start and End nodes.
iWay Service Manager Component Reference Guide 23 Services Overview
The Properties tab is where you configure the parameters for any object that you add to your process flow, as shown in the following image.
Notice the Configuration tab in the left pane, which contains a Select Action drop-down list. All of the available actions that are listed represent a supported File service. In this example, the list 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 Flow Designer Palette and their corresponding actions/services.
24 Information Builders 1. iWay Services
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.
iWay Service Manager Component Reference Guide 25 Available Services
Available Services The following section provides a comprehensive reference for all the predefined services that are 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 XML documents as trees of element objects. A well-formed XML document has exactly one root element (also called document element). When you configure the Accumulate service, the name of the root element for the resulting document must be provided as the parameter. This means that the result of the processing must be enclosed between a root start-tag and a corresponding end-tag with the specified name. The root element of this document tree is serving as a wrapper for the accumulated document parts, combining them into a well-formed XML document. For example:
26 Information Builders 1. iWay Services
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 documents produced by the splitter for the final output. The architecture of a sample channel would contain an inlet with a File listener and a splitter (for example, XML Splitter preparser). The route 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:
iWay Service Manager Component Reference Guide 27 Available Services
In this incoming document, notice that the
The XML Splitter preparser is configured to split the iWay response document into multiple XML 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 a need to merge the rows again into a single document after performing certain operations.
28 Information Builders 1. iWay Services
The Accumulate service can be used to assemble these individual documents into one merged document. In this case, the root element iway would be specified as a value for the Final Root parameter.
The following is the assembled output of the channel:
iWay Service Manager Component Reference Guide 29 Available Services
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
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.
30 Information Builders 1. iWay Services
Parameter Description
Correlation Key Correlates gather and release side. Both must have the same 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: iWay Service Manager Component Reference Guide 31 Available Services
A business error is an error detected by a process relating to the business activity being performed. It is not a hardware or software error. Business errors can be added to the activity log by this agent.
Parameters:
Parameter Description
Transactional Determines whether this event record will be included in the log based on the transaction. If set to true, the event is logged only if the process flow rolls back. To achieve transactional recording, the channel must be declared to control the local transaction.
Message The text message to be logged.
Severity The severity of the error being logged. The two defined values are:
bizerror
bizfatal.
Edges:
The following table lists the available line edges for the Activity Log Business Error Message Service (com.ibi.agentsXDXALogBizErr).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
32 Information Builders 1. iWay Services
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 to be controlled. This log may be active or inactive.
Action Actions to take.
Start: Start an activity log exit that is in stop state.
Stop: Stop an activity log exit that is started.
iWay Service Manager Component Reference Guide 33 Available Services
Parameter Description
Wanteos When using a streaming preparser in a channel, the last call is made AFTER the last document service exit is called.
False
True
Edges:
The following table lists the available line edges for the Activity Log Business Error Message Service (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:
34 Information Builders 1. iWay Services
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 record security 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 based on the transaction. If set to true, the event is logged only if the entire process flow is successful. For transactional recording, the channel must be declared to control the local transaction.
Event The event class to be included in the log. Select one of the following values 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 that must be greater than 1000.
iWay Service Manager Component Reference Guide 35 Available Services
Parameter Description
Code A code that further describes the event. Select one of the following values 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 that must 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 build relation in a process flow, the available edges are provided in the Line Configuration dialog box.
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
36 Information Builders 1. iWay Services
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 character set encoding. The attachment headers are specified by the special registers of type HDR in the MIME Header Namespace.
There are also four parameters to specify the most common MIME headers. When used, these parameters override special registers of the same name. Notice the value of the Content-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
Attachments can have an optional Content_Disposition header, which can be generated and formatted by this service. For example, given a body payload of:
body data and a file containing:
iWay Service Manager Component Reference Guide 37 Available Services
Setting the Specific Name of Attachment and Content-Disposition parameters will provide a result as summarized in the following table.
Content Specific Name Result Disposition
none none ------=_Part_0_29701819.1486739647460 Content-Type: application/xml
body data ------=_Part_0_29701819.1486739647460 Content-Type: application/xml Content-Transfer-Encoding: 7bit Content-Length: 32none my_content_name.txt ------=_Part_2_1555061314.1486739752724 Content-Type: application/xml
body data ------=_Part_2_1555061314.1486739752724 Content-Type: application/xml Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=my_content_name.txt Content-Length: 32my_disposition none ------=_Part_4_811251587.1486739819946 Content-Type: application/xml
body data ------=_Part_4_811251587.1486739819946 Content-Type: application/xml Content-Transfer-Encoding: 7bit Content-Disposition: my_disposition Content-Length: 32my_disposition my_content_name.txt invalid combination
38 Information Builders 1. iWay Services
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 Header Special register namespace from which additional MIME headers Namespace for the attachment are taken. If no value is specified, no MIME headers are added beyond those generated by the header-specific agent parameters.
Specific Name of The name to be added into a Content_Disposition header if not Attachment overridden 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
iWay Service Manager Component Reference Guide 39 Available Services
Line Edge Description
fail_notfound File cannot be located or loaded into the attachment.
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 string expression. The Java Character Set parameter specifies how the Java characters in the string are converted to bytes in the body of the attachment. The attachment headers are specified by the special registers of type HDR in the MIME Header Namespace.
There are also four parameters available to specify the most common MIME headers. When used, these parameters override special registers of the same name. Notice the value of the Content-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
The use of the specific name of the attachment and Content Disposition operates the same as it does for the Add Attachment From File Service (com.ibi.agents.XDAddAttachmentFromFileAgent). However the content of the attachment is taken 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.
40 Information Builders 1. iWay Services
Parameter Description
Java Character Set The character set used to convert from Java characters to an array of bytes. If no value is specified, the default character set will be used.
Content-Type * Value of the Content-Type MIME header.
Content-Transfer- Value of the Content-Transfer-Encoding MIME header. Encoding
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 Header Special register namespace from which additional MIME headers Namespace for the attachment are taken. If no value is specified, no MIME headers are added beyond those generated by the header-specific agent parameters.
Specific Name of The name to be added into a Content_Disposition header if not Attachment overridden 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
iWay Service Manager Component Reference Guide 41 Available Services
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
42 Information Builders 1. iWay Services
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 host is 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 3 seconds. iWay Service Manager Component Reference Guide 43 Available Services
Edges:
The following table lists the available line edges for the Alt Route IP Service (com.ibi.agents.XDAltRouteIP).
Edge Description
OnSuccess A route could be obtained.
OnError
OnFailure
fail_parse Neither host is reachable.
fail_partner The host is not known. For example, the host is not identifiable in the DNS.
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 any other function
Destination File The path to the destination file. Path *
44 Information Builders 1. iWay Services
Parameter Description
Close File * When set to true, the cached file connection is closed. Often iFL such as _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 short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called 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 is considered an error.
OnFailedOperation Could not perform the operation requested.
AQ Emit Service (com.ibi.agents.XDAQEmitAgent) Syntax: com.ibi.agents.XDAQEmitAgent
iIT Service Object: iWay Service Manager Component Reference Guide 45 Available Services
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/ Usually the same as the login. Schema *
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 the classpath.
46 Information Builders 1. iWay Services
Parameter Description
Payload Object When using custom defined objects, specify the Oracle object that the class 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 the cache.
Cache Maximum The maximum number of connections to the queue to be held in the cache.
Cache Initial The initial number of connections to create in the cache.
Cache Inactive The maximum time a cached physical connection can remain idle. Timeout
Cache Abandoned The maximum time that a connection can remain unused before the Timeout connection is closed and returned to the cache.
Cache Maximum The maximum number of statements that a connection keeps open. Statements
iWay Service Manager Component Reference Guide 47 Available Services
Parameter Description
Cache Property Sets the time interval at which the cache manager inspects and Interval enforces all specified cache properties.
JMS
Message Priority The outgoing message priority. If no value is specified, the incoming message 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 Reply If set to a value, this is used as the correlation ID of the response. Correlation ID
Delivery Mode Retention of a message at the destination until its receipt is acknowledged 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 the message will live forever.
Agent Specific Parameters
Return * Return from this agent.
response
status
Preemitter Determines if any preemitter be avoided.
true
false
48 Information Builders 1. iWay Services
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
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 more information, see the iWay Service Manager Protocol Guide.
iWay Service Manager Component Reference Guide 49 Available Services
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 for this 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 a Message Disposition Notification (MDN).
Asynchronous Receipt If an asynchronous receipt should be requested, specify the URL URL 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. Specific file name is optional. Use * in file name to add a timestamp and use # to add a sequential counter.
Content-Type Specifies the content-type of data to be sent. Select from the drop-down list or provide your own.
Message ID Set this to control the emitted message ID. Usually this is left blank to let the system generate a unique ID meeting the requirements 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.
50 Information Builders 1. iWay Services
Parameter Description
Password Password for Basic Authentication challenges.
Domain Domain for NTLM authentication challenges. To use NTLM, you must enable connection persistence.
Request Header Special register namespace from which HTTP headers for the Namespace outgoing request will be taken.
Default Namespace. To send HDR type registers.
Supply a namespace prefix here to indicate which headers to send.
None. Means that no special registers will be sent as HTTP headers.
Request Main Part Special register namespace from which MIME headers for the Header Namespace outgoing request will be taken. Provide a prefix to control the request Main BodyPart headers in the presence of attachments. Selecting none means that no special registers will be sent as MIME headers.
Response Header Special register namespace into which HTTP headers for the Namespace incoming response will be saved.
Default Namespace. To create special registers with no namespace.
Supply a namespace prefix here to indicate header namespace.
MDN Header Namespace Special register namespace into which MIME headers of the multipart/report entity will be saved. This namespace is ignored if the MDN is unsigned since all headers will be in the Response Header Namespace.
MDN Field Namespace Special register namespace into which MDN fields will be saved.
iWay Service Manager Component Reference Guide 51 Available Services
Parameter Description
Excluded Headers A comma delimited list (case-insensitive) of headers that should not be sent with the request, even if they are found in the request header namespace.
Ask for Compressed If set, requests will set the Accept-Encoding header to indicate Response that the client can accept a compressed response, as described in RFC-2616. If the response has a compressed content encoding, the client will automatically inflate.
Compress Request If set, the HTTP request entity will be compressed using the selected encoding and the Content-Encoding header will be set accordingly.
Replace Connection? If set to false, the connection will not be returned to the connection pool immediately. The identifier of the connection will be stored in the HTTP client-key special register and the connection can be handled by the HTTP Client Manager agent.
Maximum HTTP Client Maximum time the HTTP Client Manager can take to address a Manager Delay particular connection before it is automatically aborted. The format is [xxh][xxm]xx[s]. The default is 60 seconds.
Maximum Request Size Maximum size, after compression, of a request entity that can be sent with this emitter. 0 means no maximum and blank will default to 256KB.
Maximum Response Size Maximum size of a response entity that can be received by this emitter. 0 means no maximum and blank will default to 256KB.
Try Expect/Continue If checked, client will send the HTTP Expect: 100-continue Handshake? header and await the HTTP 100 response before sending the request body.
Parameters: - S/MIME
Parameter Description
S/MIME
52 Information Builders 1. iWay Services
Parameter Description
Packaging Tells the emitter how the document should be packaged for transmission. 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 Keystore Provider for the Keystore used to sign and encrypt messages. Provider
S/MIME Truststore Provider for the Keystore containing the S/MIME Certificate Provider Authorities.
S/MIME Certificate Store Comma-separated list of Keystore, Directory CertStore, or Providers LDAP providers for the certificate stores used to complete signer certificate chains when the signed message contains fewer certificates than needed.
S/MIME JCE JCE Provider for S/MIME Cryptography services. Cryptography Provider
S/MIME Verification JCE JCE Provider for S/MIME verification cryptography services. Crypto Provider Normally left blank. Defaults to S/MIME JCE Provider.
S/MIME PKIX JCE JCE Provider for S/MIME PKIX services. If left blank, the Provider default JCE provider for PKIX will be used.
Recipient Public Key Alias The alias for the recipient public key entry used for encryption.
iWay Service Manager Component Reference Guide 53 Available Services
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, the password 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 is included in the message. Select from the drop-down list:
Complete Certificate Chain
No Certificate
Signer Certificate only
Enforce KeyUsage If set to on, verify certificates used for signing allow the digital Extension Signature KeyUsage extension, and certificates used for encryption allow the key Encipherment KeyUsage extension.
Enable Certificate If set to true, use the CRLs from the CertStores to check Revocation whether the signer's certificate has been revoked.
Unrecognized Certs Directory to store unrecognized certificates found in S/MIME Location messages.
Parameters: - IP Properties
Parameter Description
IP Properties
Persistence If checked, ask the server to maintain the connection.
Response Timeout value Seconds to wait for a response before signaling an error. in seconds
54 Information Builders 1. iWay Services
Parameters: - Agent Specific parameters
Parameter Description
Return Return from this agent. Select one of the following options from the drop-down list:
input
status
response
Preemitter Determines whether any preemitter should be avoided. If set to true, preemitters will not run.
Response Wrapper Tag The tag name with which to wrap the response if the response is non-XML and must be XML.
Response Base64 If set to true, Response will be Base64 encoded. 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
iWay Service Manager Component Reference Guide 55 Available Services
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 Protocol Guide.
56 Information Builders 1. iWay Services
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 delimited list).
Blind Copy To Blind copy this message to these locations (can be a comma delimited 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
iWay Service Manager Component Reference Guide 57 Available Services
Parameters: - SMIME
Parameter Description
Packaging * Tells the emitter how the document should be packaged for transmission. 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
58 Information Builders 1. iWay Services
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: iWay Service Manager Component Reference Guide 59 Available Services
General AS2 emitter for use within the service stack. For more information, see the iWay Service 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 signaling error.
Content Disposition File name to put in the Content-Disposition header value.
User ID User ID for Basic Authentication challenges.
Password Password for Basic Authentication challenges.
Packaging * Tells the emitter how the document should be packaged for transmission. For encrypted and/or signed packaging, configure S/MIME system properties.
encrypted
signed
signed and encrypted
un-encrypted
Compression If checked, compression will be applied.
true
false
60 Information Builders 1. iWay Services
Parameter Description
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, for example, 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 be sent. Supported values are in the form:
mailto:
http://
https://
Receipt Destination Encryption algorithm.
CAST5
DES-EDE3
IDEA
RC2
Public Key Entry Alias The alias for the public key entry used for encryption.
iWay Service Manager Component Reference Guide 61 Available Services
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 IP socket originates.
IP Interface Port Local IP Port from which the outgoing IP socket originates.
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 issued by Proxy.
62 Information Builders 1. iWay Services
Parameter Description
Proxy Password Password for Basic Authentication challenges issued by Proxy.
Parameters - HTTPS
Parameter Description
Secure Connection Use a secure connection. You may need to configure the Keystore under HTTPS section of the system properties if client authentication is required. Note, if keystore is configured in system properties make sure it has the CA certificate or the client certificate of the server you are connecting to. If keystore is not configured in system properties, default truststore located under JRE_HOME/lib/security/cacerts will be used.
true
false
Use 128-bit Encryption Enforces the use of 128-bit encryption.
true
false
iWay Service Manager Component Reference Guide 63 Available Services
Parameter Description
Security Protocol Security protocol.
SSL. Supports some version of SSL. May support other versions.
SSLv2. Supports SSL version 2 or higher.
SSLv3. Supports SSL version 3. May support other versions.
TLS. Supports some version of TLS. May support other versions.
TLSv1. Supports TLS version 1. May support other 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 if the response is non-XML and must be XML.
Response Base64 Encoded Checks to see if the response needs to be Base64 encoded.
true
false
64 Information Builders 1. iWay Services
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 adapter configuration. 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 iWay Service Manager Component Reference Guide 65 Available Services
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 after processing.
replace: replaces the original attachment with a the modified document.
leave: leaves original attachments unchanged.
Start Index Index of the first attachment to process in the mail object. The first attachment to the main document has an index of 0 (zero).
66 Information Builders 1. iWay Services
Parameter Description
Header Namespace The special register namespace where MIME headers for the current attachment will be stored. If replace handling option is selected, registers in the namespace will be added to the replaced attachment.
Main Body Part If the current attachment is itself a multipart, then this is the Header Namespace special register namespace where the MIME headers for the main body 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
iWay Service Manager Component Reference Guide 67 Available Services
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 this document. Select one of the following options from the drop-down list:
deleteAll (default)
deleteOne
Attachment Number For operations on a specific attachment, which one, base 0. If a value is specified, this parameter takes precedence over the Content-ID parameter.
Content-ID For operations on a specific attachment, the Content-ID of the attachment. This parameter is ignored if a value for the Attachment Number parameter is specified.
Although the specification of the Content-ID header requires the value to be enclosed in angle brackets, you must not use the angle brackets in this property.
68 Information Builders 1. iWay Services
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 can be selected by index or by Content-ID. If the Attachment Number is specified, it takes precedence over the Content- ID. The attachment index is base 0. If present, the Content- ID must NOT contain the surrounding angle brackets.
iWay Service Manager Component Reference Guide 69 Available Services
For example, the value cid for the Content-ID parameter will match an attachment with a Content-ID header equal to
The MIME headers of the Main Body Part will be saved as registers in the Main Body Part Header Namespace. This is needed to keep them distinct from the Multipart headers. The Delete Attachment parameter determines what to do with the selected attachment when it is not a Multipart: the attachment can be preserved or deleted. This service follows OnSuccess upon successful execution, otherwise, it follows fail_notfound if the attachment cannot be found, 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, it takes precedence over the Content-ID.
Content-ID The Content-ID of the attachment to be retrieved. This value is ignored if the attachment number is specified.
Header Namespace Special register namespace where MIME headers for the selected attachment will be stored.
Main Body Part If the current attachment is itself a Multipart, this is the special Header Namespace register namespace where the MIME headers for the main body part will be stored.
Keep Document Flat Determines whether to keep the body of the document as an array of bytes. This parameter is set to false by default.
Delete Attachment Determines whether to delete the attachment after it becomes the body of the document. This parameter is set to false by default.
70 Information Builders 1. iWay Services
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 takes precedence over the Content-ID.
iWay Service Manager Component Reference Guide 71 Available Services
Parameter Description
Content-ID The Content-ID of the attachment to be retrieved. It is ignored if the Attachment Number is specified.
Delete Attachment Specifies whether to delete the attachment after it becomes the body of the document.
File
Target Directory * The target output directory.
File Pattern * The output file name, which can contain a '*' which gets expanded to a fine timestamp.
Output Document Specifies whether the output document emitted should be the Type original input document (original) or a status document (status).
Output Encoding The encoding to apply to the output file being written. Does not apply when the output is base 64.
Base64 Decode If set, the value is assumed to be in base64 notation. Only applicable if a specific write value is specified.
Respect If set, the emit respects the transactionality of the channel. If not Transactionality * set, 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 the document.
Emit Zero Length If true, emit empty files if the process creates them. Files?
Edges:
72 Information Builders 1. iWay Services
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 is considered 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 credentials in a message or message context.
For more information about the Authenticate/Impersonate service, see the iWay Service Manager Security Guide.
Edges:
iWay Service Manager Component Reference Guide 73 Available Services
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 and File name and location in the form of a full path entry. For Location example, C:/Temp/Datafile.xml
74 Information Builders 1. iWay Services
Parameter Description
Real-time collection Frequency by which the real-time performance metrics are to be period (sec) written, where a lower number will have a greater impact on system performance. The default setting is set to 5 seconds.
File Backup Should the original file be backed up before creating a new log file.
You can select either True or False.
No of Files to Backup The number of real-time performance metric files to back up. All backed up files are numbered and kept in the same directory where the original file is written. The default setting is set to 15 minutes.
User defined Metrics Special Registers and time based performance aggregate function (COUTN, SUM, MIN, MAX, and AVG) to monitor in real-time and then archive. Multiple values should be separated by commas, and the aggregate function should be supplied as: FUNCTION(SREGNAME).
Choose Archive The Archive Frequency at which the data is persisted in the Frequency database. You can select either:
RealTime
Minutes
Hours
Time (in seconds) Specify the time (in seconds) since the last execution occurred. since last execution This will generate events in case of inactivity in iSM.
Channel Monitor Type Select which channels should be monitored. You can select either:
Active Only
All Channels (active, inactive, config)
Edges:
iWay Service Manager Component Reference Guide 75 Available Services
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 a specific content transfer encoding scheme that translates binary data into a base 64 representation. Base 64 is set of 64 characters that is part of the subset common to most encodings, and also printable. It is possible to store non-unicode fields within an internal document even though under XML rules such a document cannot be parsed. The Base64 service enables these fields, or the entire incoming document, to be replaced with bytes, and these 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 64 representation. The default value is encode.
76 Information Builders 1. iWay Services
Parameter Description
XPATH expression to The value of the XPath expression within the input document that Data will 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 short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called 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 picture or image. For example, you can use it to decode a picture that is temporarily stored in base64 format within the picture tag of an incoming XML document. The data can be placed in a file and later saved with the appropriate extension to be viewed by a photo editor.
iWay Service Manager Component Reference Guide 77 Available Services
The following image is an example of configuration settings for a Base64 service object in iIT Designer:
Refer to the Pictures sample that is packaged with iWay Service Manager for the sample input file. For example, the input document that is used by the Samples.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 Header Special register namespace where the Authorization HTTP header Namespace will 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.
78 Information Builders 1. iWay Services
Parameter Description
Expiration Field Name of the field in the JSON response that specifies the length of time (in seconds) for which the token is valid.
Default Expiration Time in seconds a token can stay in the token store. Applies only Time to tokens without a specific expiration time.
Authorization Server
Authorization Server URL where a new access token can be retrieved. The URL should URL * be fully specified, including the https scheme.
HTTP Client Provider HTTP Client Provider (Pooling Provider) that manages HTTP * connections for this emitter.
HTTP Method POST sends a URL encoded entity, GET sends the request without a request entity.
User ID User ID for authentication challenges.
Password Password for authentication challenges.
Request Header Special register namespace from which HTTP headers for the Namespace outgoing request will be taken. Choose Default Namespace to send HDR type registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be sent as HTTP headers.
Response Header Special register namespace into which HTTP headers from the Namespace incoming response will be saved. Choose Default Namespace to create special registers with no namespace prefix, or supply a namespace prefix here.
Excluded Headers A comma delimited list (case insensitive) of headers that should not be sent with the request, even if found in request header namespace.
Maximum Response Maximum size of a response entity that can be received by this Size emitter. 0 means no maximum and blank will default to 256KB.
Persistence If checked, have the server maintain the connection.
iWay Service Manager Component Reference Guide 79 Available Services
Parameter Description
Response Timeout Number of seconds to wait for a response before signalling an value in Seconds * error.
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 Owner The username to encode in the POST body when grant type is Username password.
Resource Owner The Password to encode in the POST body when grant type is Password password.
Special Register If specified, registers in this namespace will be included as fields Namespace for in body of a POST request. Additional Request Fields
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.
80 Information Builders 1. iWay Services
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, the iWay 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 XML document 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 or analysis easier.
Parameters:
Parameter Description
Method Select one of the following options to remove blank spaces:
All. Trims leading and trailing whitespaces from all element text values. This option is selected by default.
Empty. Trims whitespace-only element values; does not trim other element 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
iWay Service Manager Component Reference Guide 81 Available Services
Line Edge Description
OnFailure Failure
OnCustom
OnError OnFailure
OnSuccess
Example:
For example, given the following input XML document:
When the Method parameter is set to All, the following result is generated:
The value of the
When the Method parameter is set to Empty, the following result is generated:
The document is treated just as above, except that in this case, the value of the
Cancel Service (com.ibi.agents.XDCancelAgent) Syntax:
com.ibi.agents.XDCancelAgent
iIT Service Object:
operations: Cancel a Service
Description:
82 Information Builders 1. iWay Services
The execution of one or more services on other execution edges of a process flow can be cancelled by using the Cancel Service (com.ibi.agents.XDCancelAgent). This service accepts the name of one or more target services. Upon execution, a cancellation request is sent to the named 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. If the cache finds the required entry in the local database, then it can cancel the slower operation.
A cancel operation can only be directed to a service node (agent) that supports cancellation. In addition, that service must be able to actually cancel. For example, the SQL Object used in process flows can issue a cancel operation, but the effectiveness of the cancellation will depend upon the underlying database interfaces.
Parameters:
Parameter Description
Service to cancel Upon execution, the identified service(s) in this field will be sent a * cancellation request. The service(s) specified here should offer an OnCancel/cancellation edge to terminate the execution thread. You can specify an individual service name, a comma-delimited list of service names, or a space-delimited list of service names. Service names with spaces, commas, or other special characters must be enclosed in quotes.
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
iWay Service Manager Component Reference Guide 83 Available Services
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 database access, 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 thus to the End node, only one side will reach it.
Caches are very timing dependent. As a result, this example is simplified and is not intended to show a fully working cache.
84 Information Builders 1. iWay Services
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 number of different ways. Supported method and techniques include:
Explicitly checking for an error, post-service execution, by conditioning the edge with onError or onFailure.
Including an outlet conditioned with _iserror().
Including a Catch service at the beginning of the channel. This channel has two edges on the output side that are used for processing. The first is the onCompletion edge. The second 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 programming languages.
In other programming languages, a block of code is enclosed between the braces of a try statement. Following the try block is a catch block of code that is enclosed in braces. The code in 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 each statement is successful, execution continues at the statement following the closing brace of the catch block (assuming that there is not a finally block). If an error occurs within the try block, 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 might occur. There are five edges off this service:
onCompletion
onCustom
onSuccess
onError
onFailure iWay Service Manager Component Reference Guide 85 Available Services
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 the onSuccess edge.
The onCustom edge has three selected cases (onError, onFailure, and error_retry). Any errors or failures that occur within the path of the process flow are directed down the onError and onFailure edge. The logic in this branch contains any services necessary to handle errors. The error_retry edge is followed when there is a retry exception. For example, when a SQL Object contains 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 closest Catch node previous to where the error occurred. In this manner, you can add multiple error conditions for a given process flow if required.
The catch is hierarchical and each catch is considered nested in the prior Catch node. When a Catch node is triggered, the Special Register (SREG) iway.catchname is set to the name of the Catch node that first catches the error. The register is not replaced as succeeding Catch nodes see the error. This allows higher scopes to ascertain the scope under which the original error is caught. For example, if Task3 fails and the error is caught by CatchScope3, the register will be set 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 forward entry.
The Catch facility can also be configured to allow only a specified count of catches. This helps to deal with errors in the error handler reached through the catch itself. For example, consider what happens in the process flow shown in Example 2 if the Write Error node fails. In this case, because the Write Error node does not itself provide an OnFailure edge and handle the failure, the failure is propagated upward, where it reaches the Catch node. That node passes the error down its failure edge, back to the Write Error node, which might again fail. If this continues, a loop situation arises.
The Maximum Errors parameter allows a count of the number of times a Catch node will pass the error to an error handler (the default value is three). If the number of errors reaching the Catch node exceeds this specified count, then the Catch node does not handle the error, but rather allows the error to be propagated upward to the next higher Catch node, or (if none is encountered) terminates the process flow.
86 Information Builders 1. iWay Services
The count is reset each time a document passes through the Catch node in the forward direction, 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 may want to apply error handing for up to six times, but only every five seconds. Doing so would provide an external system with time to accept the error. In this case, you might set the Maximum Errors parameter to six, and add a five second delay (using a Document Copy Service, 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 (called Task1, Task2, and Task3). The process flow performs three tasks, as shown in the following image.
There is a requirement to handle errors in each task separately. So in our updated process flow, 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. If Task3 (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 a Bypass Catch Processing parameter set to true. For more information on the Fail service, see Fail Service (com.ibi.agents.XDFailAgent) on page 192. iWay Service Manager Component Reference Guide 87 Available Services
However, if Report3 fails, then the failure will be caught by CatchScope2. The Catch node for scope three does not catch the Report3 failure as it has already caught a failure. The scope in this example tests to determine whether the failure was in its scope, in which case Report2 will 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. Following the trace message reporting a failure in a lower scope, the process flow uses a Fail service to issue the fail that did not get issued in the lower scope. This maintains the statistics of the channel.
In the multiple Catch node use case, setting the Bypass Catch Processing parameter of the Fail node to true will cause the failure request to bypass upper-level Catch nodes, avoiding the need 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. The sample 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 possible outside issues. An error handling strategy is required so that none of the documents being processed are lost because of an outside issue.
88 Information Builders 1. iWay Services
In process flow, the Catch node immediately follows the Start block. An onCompletion edge connects the Catch Errors block to the FTP Write block. The FTP Write block is an FTP emitter that 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 an onSuccess edge. If a different edge were used and an error occurred, the error edge off of Catch Errors may not be executed.
The onCustom edge of Catch Errors has the onError and onFailure cases selected for the properties. This edge leads to a file write service, Write Error, that puts the file into a hold directory for later reprocessing. Following Write Error, there is an End with a Terminate since no further processing is required at this point. In a real world scenario, a requirement might be that 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 site is down or you cannot connect to it, the FTP write service will generate an error. This error causes 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 the system. The service is also available for use in process flows. Each channel (represented by a master 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)
iWay Service Manager Component Reference Guide 89 Available Services
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 the initialization.
Config. Errors were found during the initialization and the channel cannot start.
Retry. The channel initialization (or sometimes the execution phase) found a condition that is an error not related to the configuration. The channel 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 worker threads 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 queues themselves.
90 Information Builders 1. iWay Services
Property Description
queue The name of this queue. Usually this is the name of the internal listener that 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
iWay Service Manager Component Reference Guide 91 Available Services
Example:
The following is a sample of an XML document that is returned by the service:
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. In scenarios where a schema represents an agreement between the sender of a document and the receiver (for example, iWay Service Manager), schema checking is important for debugging purposes. It has lesser importance during actual production. However, this is ultimately an application design decision.
Note: Checking a schema can consume system resources and processing time. As a result, it is not recommended during operation in production environments.
92 Information Builders 1. iWay Services
Parameters:
Parameter Description
Schema File The source of the schema to be applied to the incoming document. You can specify a file path directly in this field, or select one of the following values from the drop-down list:
route {$route}. A schema published to the selected route that is currently managing the channel.
start node {$start}. A schema specified on the Start object of the process flow.
Schema If the schema is packaged in a .zip archive file, which is specified in the Name Schema 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 one of the following values from the drop-down list:
strict (default). The document must validate. Failure to validate results in a fail_parse result.
optional. If the schema is located, then the document must validate. If the schema cannot be located, then the document validation is ignored.
Is Target false (default). There is no namespace to apply. Namespace Enabled true. There is a namespace to apply.
Target Target Namespace location. This property is mandatory if the preceeding Namespace property is set to true. Location
When When to perform this operation.
Always (default) at each execution.
On debug, when running in debug mode.
iWay Service Manager Component Reference Guide 93 Available Services
Edges:
The following table lists and describes the edges that are returned by the XDCheckSchema service.
Edge Description
success Successful.
fail_parse The schema could not be parsed or the document failed the schema check.
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).
94 Information Builders 1. iWay Services
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 .zip archive file where the schema is packaged. In this case, you must also provide a value for the Schema 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
iWay Service Manager Component Reference Guide 95 Available Services
Strictness. strict
You can also select route or start node from the Schema File drop-down list. If route is selected, then the schema is retrieved from the route that is currently managing the channel. If start node is selected, then the schema is retrieved from the process flow Start object, as shown in the following image.
When the process flow is executed, the input file is validated against the specified schema and 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
96 Information Builders 1. iWay Services
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 node is a functional NOP.
When operating in Local Transaction mode, database and other operations begun by nodes within the flow are committed or rolled back based on the final status of the flow itself. The commit or rollback is performed within the constraints of the local transaction capability of the server.
The XDCommitAgent, when encountered in a flow, causes a commit or a rollback operation to take place immediately. This allows two or more transactions in a single flow. Use of this capability 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, if any. It then calls the commit manager to commit or roll back work established to date. This in turn causes all open connections to be released. The specific action on a commit or roll back is dependent on the resource being affected. Note that mis-specification of set or synch waits can cause the flow to enter a deadlock condition.
Once committed, the data cannot be rolled back, regardless of the manner in which the flow actually ends. The node is a punctuation within the flow, and users should consider actions subsequent 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 edge might issue a roll back and then proceed to take other action to record or recover from the error.
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
iWay Service Manager Component Reference Guide 97 Available Services
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 evaluated with the iWay Functional Language (iFL), this service is frequently used to modify the input or load a file from a disk, and so on.
Parameters:
Parameter Description
Constant Output To The value that will be emitted by the Constant service. If the Emit * Output Format parameter value is set to xml, this value needs to be valid XML, otherwise the original input document can be emitted 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.
98 Information Builders 1. iWay Services
Parameter Description
Output as Error Determines whether the input should be emitted as an error document. Select true or false (default) from the drop-down list.
Input Criterion Emit status criteria based on input type, else copy. Select one of the following values from the drop-down list:
always (default). Emits the constant regardless of the input document'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 short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called 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 is returned. For example, if you are using aaa as a constant, the following is the result: aaa
iWay Service Manager Component Reference Guide 99 Available Services
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. This functionality enables logical control of the server configuration from within a process flow. The following are the supported control operations/actions:
start
pause
pulse
stop
Using the Controls Listeners service, the activity on one listener can control another. For example, the detection of a message in an MQ Series queue can trigger an RDBMS listener to begin 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 can be entered with an ending asterisk character (*), meaning all with names starting with the entry characters.
100 Information Builders 1. iWay Services
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 enabled for 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 remains active and no resources are released.
pulse. Named listener or channel is started (or enabled) to acquire messages. It runs through one acquisition cycle (for example, reading all rows 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 pulsing should 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 that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default 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
iWay Service Manager Component Reference Guide 101 Available Services
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
Example:
You can use the Controls Listeners service to stop a channel that is currently running in iWay Service Manager (iSM). In a process flow, configure a Service object using the Controls Listeners 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).
102 Information Builders 1. iWay Services
Invoke the channel that contains the Controls Listeners service process flow in the route with a valid XML document. The stop command for the default channel will be issued. If the default channel is currently running, then it will be stopped.
You can verify this action by examining the status change for the default channel in the Channel Management pane after successfully passing the XML document through the Controls Listeners 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 these activities to some external media. A common exit is the BAMActivityProvider. Other exits relate to 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 all components, to whether the exit is initialized and started automatically when the server is initialized.
These exits can be configured for the server in the Activity Facility section of the iSM Administration Console.
This service can be used in a process flow to start or stop the named activity log exit. You might use this, for example, in a BAM error recovery flow to restart the exit that has been stopped due to a database error.
iWay Service Manager Component Reference Guide 103 Available Services
Parameters:
Parameter Description
Exit The name of the Activity Facility exit to be controlled. This exit must be available.
Action Determines the action to be taken. Select one of the following actions from the drop-down list:
start
stop
Call at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default 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. The operation of the server is generally asynchronous, so this only means that the start activity has been initiated.
fail_parse The configuration parameters cannot be understood.
fail_notfound The named exit cannot be located in the set of deployed exits.
fail_operation The requested action failed for some other reason.
Cookie Store Agent Service (com.ibi.agents.XDCookieStoreAgent) Syntax:
104 Information Builders 1. iWay Services
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 HTTP Client Provider.
Cookie Store Name The action will be performed on this cookie store. Leave empty for the 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: iWay Service Manager Component Reference Guide 105 Available Services
misc: Correl Inquiry By State Agent
Description:
Returns a document listing all correlation IDs in the requested state. For more information, see the 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 a namespace.
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
106 Information Builders 1. iWay Services
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 the Correlation Facility topic in the iWay Service Manager User's Guide.
Parameters:
Parameter Description
Correlation ID * Identifier for the correlated process. This is normally a runtime function, such as XPATH() or SREG().
Namespace Namespace for Correlation ID. IDs will normally be unique within a namespace.
Output Type * Should agent simply output its input, or should it output an XML correlation 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
iWay Service Manager Component Reference Guide 107 Available Services
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 more information, 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 is typically a batch or envelope identifier, expressed using a runtime function.
Namespace Namespace for Correlation ID. IDs will normally be unique within a namespace.
108 Information Builders 1. iWay Services
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 replaces or removes such characters.
iWay Service Manager Component Reference Guide 109 Available Services
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
110 Information Builders 1. iWay Services
Example:
If you need to replace a new line character in an incoming document with a period (.), this service needs to be configured with default parameter values, except for the Replace With parameter value, which must be set to period (.). The result of passing the incoming document with a new line character inside the
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 a mechanism that allows browsers to make cross-origin requests to resources that opt in to provide access. CORS defines a set of HTTP headers and the rules to process them. Most common browsers implement CORS natively. It is expected that the user agent making the request will be a browser. The CORS service implements the server-side rules to respond to CORS requests received by an nHTTP listener.
If the request is simple (such as GET, HEAD, or POST), then the user agent (for example, the browser) can make the request directly. The user agent adds the Origin header to indicate which 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 the actual 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 (for example, PUT). The optional Access-Control-Request-Headers header indicates which headers will be used in the actual request. Depending on the response of the pre-flight request, the user agent can abort or make the actual request following the same rules as a simple request. iWay Service Manager Component Reference Guide 111 Available Services
The CORS service analyzes the request, and depending on its configuration, will report one of the 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 only if the request is allowed. The new headers appear as Special Registers (SREGs) in the Response 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 appropriate result, but an application can modify the output document afterwards if necessary. For other requests, the CORS service returns the input document as the output document. Unlike the headers, 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. The OPTIONS Handling property must be set to event. This instructs the listener to pass the request to the channel instead of responding directly. The Request Header Namespace and the Response Header Namespace must not be none, and they must be different from each other. This makes the request headers available to the CORS service, and allows the response headers be sent with the response. Of course, the Excluded Headers property should not list the CORS headers. The HTTP Response Code must be 200 for a CORS pre-flight response. The Authentication Scheme and the Authentication Realm properties should be considered carefully. CORS is a mechanism used to relax security. It does not replace the need for user credentials to protect sensitive data.
112 Information Builders 1. iWay Services
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 or enter * 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 and influences the value of the Access-Control-Allow-Origin header in the response. The return value of the Access-Control-Allow-Origin header will be * if the Allowed Origins is * and Supports Credentials is false.
Allowed Methods Comma-separated list of HTTP methods that are supported by the resource. Leave empty to allow all methods. This is used to validate the Access-Control-Request-Method header in the pre-flight request and to initialize the Access-Control-Allow-Methods header in the pre- flight response.
Supported Comma-separated list of HTTP header field names that are supported Headers by the resource. Leave empty to claim support for all headers. This is used to validate the Access-Control-Request-Headers header in the pre-flight request and to initialize the Access-Control-Allow-Headers header in the pre-flight response.
Exposed Headers Comma-separated list of HTTP header field names of headers (other than the simple response headers) that the resource might use and can be exposed. This is used to initialize the Access-Control-Expose- Headers header in the response of the actual request.
Supports Indicates whether the resource supports user credentials in the Credentials request. This is used to initialize the Access-Control-Allow-Credentials header in the response. Notice the return value of the Access-Control- Allow-Origin header will never be * for a resource that supports credentials.
iWay Service Manager Component Reference Guide 113 Available Services
Parameter Description
Max Age Specifies the amount of seconds the user agent (for example, the browser) is allowed to cache the result of the pre-flight request. The value 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 successfully analyzed. The cors Special Register contains the result.
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_operation: the service is not executing a request received by an nHTTP listener.
open
closed
notfound
114 Information Builders 1. iWay Services
Special Registers:
The following table describes the Special Register (SREG) that is assigned upon a successful execution.
Special Description Register
cors The outcome of analyzing the request. This will be one of the following values:
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 Service on various HTTP requests. The following table lists the parameter values for the Cross-Origin Resource 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
iWay Service Manager Component Reference Guide 115 Available Services
Example 1
This HTTP request is missing the Origin header. When analyzing this request, the service would set the cors Special Register to notcompliant and return success. No response headers would be added. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com
Example 2
Since the Allowed Origins is not empty or *, the origin must match exactly one of the listed origins. When analyzing this request, the service would set the cors Special Register to notallowed and return success. No response headers would be added. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com Origin: http://host.com
Example 3
When analyzing this request, the service would set the cors Special Register to allowed and return success. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com
The following response headers will be added:
Access-Control-Allow-Origin: http://host1.com Access-Control-Expose-Headers: RespHdr1,RespHdr2 Access-Control-Allow-Credentials: true
Example 4
This pre-flight request is missing the Access-Control-Request-Method header. When analyzing this pre-flight request, the service would set the cors Special Register to notcompliant and return success. No response headers would be added. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com
116 Information Builders 1. iWay Services
Example 5
The actual request method HEAD is not allowed. When analyzing this pre-flight request, the service would set the cors Special Register to notallowed and return success. No response headers would be added. The output document is a zero-length byte array. OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com Access-Control-Request-Method: HEAD
Example 6
The header names in Access-Control-Request-Headers are all supported headers. When analyzing this pre-flight request, the service would set the cors Special Register to allowed and return success. The output document is a zero-length byte array. OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com Access-Control-Request-Method: GET Access-Control-Request-Headers: ReqHdr1,ReqHdr2
The following response headers will be added: Access-Control-Allow-Origin: http://host1.com Access-Control-Allow-Methods: GET,POST Access-Control-Allow-Headers: ReqHdr1,ReqHdr2,ReqHdr3 Access-Control-Allow-Credentials: true Access-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.
iWay Service Manager Component Reference Guide 117 Available Services
Parameters:
Parameter Description
Data Quality Provider * The name of the configured Data Quality provider that should be invoked by this service.
XPath Expression * Specify an XPath expression that will return one or more elements from the input document that will be used as input records when the iWay Data Quality Center (DQC) plan is invoked.
XPath Namespace Map If the input document contains namespaces, then this parameter specifies the configured namespace map to be used when evaluating XPath expressions.
Replace or Preserve? * Determines whether the children of the record element in the output document should be preserved (appending the result of the iWay DQC plan execution as new child elements), or should the original children be replaced with the iWay DQC plan 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:
118 Information Builders 1. iWay Services
This service is used to compress the document for transmission or storage. The document is flattened to a byte stream, and compression algorithms are applied. The output of this service is a flat document.
Parameters:
Parameter Description
Method of Determines what format of compression should be used on the compression to use * output. Select one of the following options from the drop-down list:
none (default). No compression is used.
smallest. The smallest possible output, regardless of the execution time.
fastest. The fastest possible execution time, even if the degree of deflation is reduced.
standard. A compromise between smallest and fastest is used.
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 not deflated.
Deidentification Service (com.ibi.agents.XDDeidentifyAgent) Syntax: com.ibi.agents.XDDeidentifyAgent
iIT Service Object: iWay Service Manager Component Reference Guide 119 Available Services
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 Insurance Portability and Accountability Act (HIPAA) Privacy Rule. Multiple algorithms can be configured since a combination of algorithms will be needed to deidentify the data correctly.
The Deidentification service takes an XML document as input. The first configured algorithm takes this document as input and modifies it in place. The result is fed into the next configured algorithm and so on. The result of the last configured algorithm is the XML document returned by 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 prefix and 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 the console 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 take an argument .
Targetnodes1 An XPath expression that returns a nodeset. The de- identification algorithm will be applied to each node in the nodeset. If XML Namespace prefixes are used, they must be declared in the XML Namespace Provider.
120 Information Builders 1. iWay Services
For more information about the available algorithms and the meaning of the argument, see the following 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 are needed. Instances for algorithm 6 and above can be created with user parameters named: algorithmNN argNN targetNN
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 instance numbers must be consecutive to be recognized. The service stops looking for more algorithm instances as soon as it finds one that is not configured. For example, if Algorithm 3 is not configured, Algorithm 4 and 5 will be ignored.
iWay Service Manager Component Reference Guide 121 Available Services
Algorithms:
The following table describes the available alogrithms in the Deidentification service.
Algorithm Argument Description
Encrypt Formatted encryption key Maps the digits in a formatted string with 4x4 Digits Playfair algorithm. The encryption key should contain only digits, and is padded if necessary to make it 16 digits long. Playfair works with pairs of characters. When the number of digits in the input is odd, the input is padded by one character and one character is ignored in the output. There is no validation of the resulting number. The algorithm will always produce the same output for the same input when using the same key. The mapping is not reversible. Different input might map to the same output, though this is not common. Only the digits are mapped, the other characters are preserved at the same position. For example, (212)223-3333 might map to (655)887-2424 with the format characters preserved.
122 Information Builders 1. iWay Services
Algorithm Argument Description
Encrypt SSN encryption key Maps Social Security Numbers by encrypting them with 4x4 Playfair algorithm. The encryption key should contain only digits, and is padded if necessary to make it 16 digits long. Playfair works with pairs of characters. The input is padded by one character. The output is 10 digits long and the last character is eliminated to make it 9 digits long. The algorithm will never produce a Social Security Number starting with 9, starting with 666, or with all zeroes in any of the three groups: 000- xx-xxxx, xxx-00-xxxx, and xxx-xx-0000. If the resulting Social Security Number is invalid, the output is re-encrypted until it becomes valid. The algorithm will always produce the same encrypted SSN for the same input SSN when using the same key. The mapping is not reversible. Different input SSN might map to the same encrypted SSN. Only the digits are mapped, while the other characters are preserved at the same position. For example, 111-22-3333 might map to 655-88-2233 with the hyphens preserved.
iWay Service Manager Component Reference Guide 123 Available Services
Algorithm Argument Description
Sequential SSN unused Maps Social Security Numbers to numbers in consecutive increasing order starting with 001010001. The numbers produced adhere to the rule used by Social Security Administration on June 25, 2011 and later. The algorithm will never produce a Social Security Number with all zeroes in any of the three groups: 000-xx- xxxx, xxx-00-xxxx, and xxx-xx-00000. Only the digits are mapped, while the other characters are preserved at the same position. For example, 111-22-3333 might map to 001-01-0035 with the hyphens preserved. Within a single run, a previously mapped SSN will map to the same number it was assigned earlier. The mapping is not preserved across runs.
Text Constant new text Replaces the contents of an element by a string constant. The element keeps its attributes, but all existing mixed content children are removed. The argument is evaluated once to obtain the string constant.
Random Day date pattern Parses a date using the pattern in the argument, replaces the day and month with random values, and clips the year to at most 90 years ago. The argument is evaluated once to obtain the date pattern in SimpleDateFormat syntax.
124 Information Builders 1. iWay Services
Algorithm Argument Description
Text Eval iFL expression Replaces the contents of an element by a string obtained by evaluating an iFL expression. The element keeps its attributes, but all existing mixed content children are removed. The argument is evaluated for each target node processed. The existing text value of the element is stored in the special register iway.value. The new value can depend on the existing value by calling _sreg (iway.value) within the iFL expression.
XML Constant XML String Replaces the contents of an element by a constant XML fragment. The element keeps its attributes, but all existing mixed content children are removed. The argument is evaluated once to obtain an XML string. The XML string is parsed for each target node, using the XML Namespace context of that node.
XML Delete unused Deletes the XML target nodes. The node itself, its attributes, and all mixed content children are removed.
XML Eval iFL expression Replaces an XML element by the result of an iFL expression parsed as XML. The node itself, its attributes, and all mixed content children are removed. The argument is evaluated for each target node processed. The resulting XML String is parsed using the XML Namespace context of the parent node. The first element of the resulting XML fragment is the new element replacing the target node. The new value can depend on the old value because the old element is passed as the root of the document during evaluation. For example, the _XPATH() function can be called to extract values from the old node. iWay Service Manager Component Reference Guide 125 Available Services
Algorithm Argument Description
XML Replace XML String Replaces an element by a constant XML element. The node itself, its attributes, and all mixed content children are removed. The argument is evaluated once to obtain an XML string. The XML string is parsed for each target node, using the XML Namespace context of the parent of that node. The first element of the resulting XML fragment is the new element replacing the target node.
Zip Keep First 3 unused Keeps the first three digits of the five digit zip code followed by 00. The four digit code after the hyphen is ignored when present. For example, 10121-2898 becomes 10100.
Zip Keep last 2 unused Keeps the last two digits of the five digit zip code preceded by 000. The four digit code after the hyphen is ignored when present. For example, 10121-2898 becomes 00021.
Example:
The following example shows the effect of various algorithms. The following table lists the parameter 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
126 Information Builders 1. iWay Services
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
Target Nodes 4 /workforce/employee/address
Name 5 XML Delete
Target Nodes 5 /workforce/employee/title
The following is a sample input document.
The resulting service output is shown below.
iWay Service Manager Component Reference Guide 127 Available Services
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".
128 Information Builders 1. iWay Services
Parameter Description
Request Timeout * Sets the amount of time to wait (in milliseconds) for the request to complete before giving up and timing out.
ConnectionTimeout * Sets the amount of time to wait (in milliseconds) when initially establishing a connection before giving up and timing out.
Execution Timeout * Sets the amount of time (in milliseconds) to allow the client to complete the execution of an API call.
Max Idle Timeout * Sets the maximum amount of time that an idle connection may sit in the connection pool and still be eligible for reuse.
Socket Timeout * Sets the amount of time to wait (in milliseconds) for data to be transferred over an established, open connection before the connection 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 retriable requests.
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 key The Item primary key value. 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,
iWay Service Manager Component Reference Guide 129 Available Services
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 authenticating user 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 this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token Secret.
130 Information Builders 1. iWay Services
Parameter Description
Consumer Secret * Is your Twitter Application Consumer Secret. If you don't have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 have * this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New 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 Read The Streaming API's HTTP Read timeout in milliseconds. Timeout
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.
iWay Service Manager Component Reference Guide 131 Available Services
Parameter Description
Stream Base URL The Streaming API base URL.
Site Stream Base The Site Streams API base URL. 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 operation requested.
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 to be emitted and a delay to be configured. Unless a delay or comment is required, it is recommended to use the Move service instead.
132 Information Builders 1. iWay Services
Note: The delay parameter can be specified for benchmarking purposes, while the comment parameter is typically used during troubleshooting.
Example:
If running it with
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 be text 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. iWay Service Manager Component Reference Guide 133 Available Services
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 within the XML Namespace context of the Parent Element.
Replace Determines whether the existing children of the parent node are removed Content before the data is inserted.
XML Provider for the mapping between the XML namespace prefix and the Namespace namespace URI in the XPath expressions. If left blank, the XPath Provider expressions in the Parent Element and the Next Sibling cannot contain namespaces.
XPath Syntax Determines which syntax level of XPath should be used. The default option selects the syntax level as set in the console global settings.
Create Parent Determines whether the parent element is created if it is missing. Element
Parent Element Path to the element where the data will be inserted. If left blank, the parent is the root element. If Create Parent Element is set to true, then the expression must adhere to the Restricted XPath syntax, or else the expression may adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter. The Restricted XPath has the form /step1/ step2/... where a step has the form ns:elem[predicate] or a pair of consecutive steps that has the form *[1]/ self::ns:elem[predicate] to indicate that the element must be the first child of its parent. The namespace prefixes are optional, but if present they must be declared in the XML Namespace provider. The predicate is optional, but if present it has the form [@ns1:attr1='val1' and @ns2:attr2='val2' and ...]. If no element matches the Restricted XPath expression and Create Parent Element is set to true, then the necessary elements and attributes will be created such that the expression would match successfully.
134 Information Builders 1. iWay Services
Parameter Description
Next Sibling Path to the next sibling node. If the sibling node is found, the data will be inserted before this node. Otherwise, the data is added as the last child of the Parent Element.
The Data Source is evaluated to obtain a string. If the Text format is selected, the string becomes the value of a text node that will be inserted. If the XML format is selected, the string is parsed as an XML fragment within the XML Namespace context of the Parent Element. An XML fragment can have multiple root nodes. All the XML Namespace declarations active on the Parent Element will be available without the need to redeclare them explicitly in the Data Source. 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 Data Source and a small wrapper containing the Namespace declarations are parsed.
If the XML Namespace declarations in the input document are unknown or unpredictable, it is recommended to explicitly declare all namespace declarations in the Data Source. In particular, the default namespace might have to be undeclared if the Data Source contains elements in the global namespace.
The Replace Content parameter is Boolean. When selected, the existing children of the parent node are removed before the data is inserted. In particular, this option is required when you wish 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 mapping between XML Namespace prefixes and XML Namespace URIs. If left blank, the Parent Element and Next Sibling path expressions cannot contain namespace prefixes.
The Parent Element is an XPath expression pointing to the element where the data will be inserted.
The Next Sibling is an XPath expression that points to a child of the parent element. The data will be inserted before this node. If the parameter is left blank or the sibling is not found, the data is added as the last child of the parent. This parameter is ignored if Replace Content is selected. 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 if needed, but the XPath expression must adhere to the Restricted XPath syntax. When the Create parent Element parameter is false, the parent element must exist but the expression may adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter. For more information on the Restricted XPath, see the Way Service Manager Security Guide.
iWay Service Manager Component Reference Guide 135 Available Services
Edges:
The following table lists and describes the line edges that are returned by the Document Insert Service (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.
The following syntax is the resulting output document.
Without Replace Content, the output document would contain two text nodes in the elem element, as shown below:
136 Information Builders 1. iWay Services
The following is another sample input document.
The service will return the edge fail_operation with an error document indicating that the Parent Element is missing. The service cannot create the parent element because that parameter is false.
Example 2: Creating the Parent This example shows how to use Restricted XPath to create the parent element if it is absent from 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 syntax shows a sample input document.
The following is the sample output document.
When the parent element is missing, the service will create it. The following syntax shows a sample input document.
The output document for it will be:
Notice how the elem element is created before the sib element. This is the result of the carefully crafted Restricted XPath expression. With the simpler expression /root/elem, the elem 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(
Data Format xml
Replace Content false
XML Namespace xmlnsprov Provider
Create Parent false Element
Parent Element /ns:root
Next Sibling /ns:root/sib2
This assumes that the value of the special register newval is 123 and the XML Namespace provider 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.
Its output document is shown in the following syntax.
If the Next Sibling is not found in the input document, the operation still succeeds but the data is inserted as the last child of the Parent Element. The following syntax shows a sample input document.
138 Information Builders 1. iWay Services
The output document is shown below.
Example 4: Inheriting XML Namspaces This example shows how the XML namespace declarations are inherited from the context of the Parent Element. It also demonstrates a Data Source containing an XML fragment with two root nodes.
The following table lists the parameters and values of the XML namespaces.
Parameter Value
Data Source
Data Format xml
Replace Content true
Create Parent true Element
Parent Element /root/sub
The following example shows an input document.
The corresponding output document is:
Note that he newelem element inherited its namespace prefix from an ancestor node in the input document.
The following example shows an input document.
The corresponding output document is:
The def element is now in the http://default.com namespace. If you do not wish to have the element in the namespace, then the default namespace must be explicitly undeclared in the Data Source, as shown in the following syntax:
If the application does not control the exact content of the input document, then it is recommended to explicitly declare all XML Namespaces in the Data Source, as shown in the following syntax.
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 Error Controls the document error state. The error state State sends the document to the errorTo destination and can be tested by _iserror(). Schema Error Controls the schema error state. The schema error State state can be tested the by _hasschemaerr() iFL function. Encoding * The IANA character set to be used for this document. Select from the standard list or enter an encoding name. Output Message Format Changes the format of the message in this document. If * flat string, you can apply an iFL expression. 140 Information Builders 1. iWay Services Parameter Description Apply iFL Applies this iFL to the flattened form of the message content. 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. In a file system the type can be the suffix, which in some systems 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 cancellation request. 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 iWay Service Manager Component Reference Guide 141 Available Services transform: Activity Log Control Description: The Document Update service can be used to run find and replace procedures, and modify data based on static or dynamic parameters. Note: This service requires a highly technical method to achieve the desired result. The same functionality can be performed through the use of a configured Transform component, which can 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 be processed as flat text, but the output document will result as designated. Select one of the following options from the drop- down list: Process to Flat text. Treats the incoming and outgoing data as 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/replace operation then parses the document. Build Document then Find/Replace. Parses the document then performs a find/replace operation. Only Find/Replace. Performs a find/replace operation only. Only Build Document. Parses the document as XML or flat (no replace is performed). 142 Information Builders 1. iWay Services Parameter Description Document Assembly A comma-separated field used to describe how the document is Instructions assembled. The build text is evaluated from left to right. iFL functions (for example, _SREG and _CONCAT) are evaluated at document build time. The following special text values are also used: 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 Document Assembly 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 Document Assembly 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 Document Assembly 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 Document Assembly Instructions parameter as DS4. Find/Replace Search Text to search for. Use a comma (,) to repeat searches (for example, search1,search2,search3). Replace Text to replace search text. Multiple searches must have an equal number of replacements. iWay Service Manager Component Reference Guide 143 Available Services Parameter Description Encoding Specifies the encoding when converting a flat document to XML format. Platform encoding is used by default. Note: The Encoding parameter is required for the Document Update service to function properly. Data Sources Data used to build the document. Use a comma (,) to repeat data sources (for example: _SREG(VAR_A),_SREG(VAR_B),_SREG(VAR_C)). Use DS0 to include the original incoming document. The following image shows the New Service Object dialog in iIT Designer and the corresponding parameters that displays when you add a new Document Update service object to a process flow. Edges: 144 Information Builders 1. iWay Services 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 the following fields contain an invalid iFL statement: Document Assembly Instructions DS1 DS2 DS3 DS4 Search Replace If Process to XML was selected and the document created is not a well formed XML document. OnSuccess Success: The service generated a successful output. Either a flat document was generated by the service (if Process to Flat text was selected), or a well formed XML document (if Process to XML was selected) was produced. OnFailure Failure iWay Service Manager Component Reference Guide 145 Available Services Line Edge Description OnCustom OnError OnSuccess OnFailure fail_parse fail_operation: An unexpected error occurred while processing the document or the parameters of the service. Check the 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 the document (DS0 represents the input document of the service). Because the Find/Replace operation is performed prior to compiling the output document, the second occurrence of bill is not replaced with buster. Document: 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,' ') 146 Information Builders 1. iWay Services Parameter Value DS2 _concat(is,' ') DS3 _concat(a,' ') DS4 bill Search bill Replace buster Encoding UTF-8 Results: 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 the document (DS0 represents the input document of the service). Because the Find/Replace operation is performed after compiling the output document, the second occurrence of bill is replaced with buster. Document: 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,' ') iWay Service Manager Component Reference Guide 147 Available Services Parameter Value DS2 _concat(is,' ') DS3 _concat(a,' ') DS4 bill Search bill Replace buster Encoding UTF-8 Results: Example 3: Only Find/Replace This example only performs a Find/Replace operation. In this case, only the document presented to the service is searched and any occurrence of bill is replaced with buster. Document: 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,' ') 148 Information Builders 1. iWay Services Parameter Value DS4 bill Search bill Replace buster Encoding UTF-8 Results: Example 4: Only Build Document This example parses the document as XML or flat (no replace is performed). The assembly instructions indicate that DS1, DS2, DS3, and DS4 are used to create the document that the service will output. There will be no replacements performed by the service. Document: 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 iWay Service Manager Component Reference Guide 149 Available Services 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: 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 the document assembly process. Because the Find/Replace operation is performed prior to compiling the output document, only the second occurrence of QA is replaced with Quality Assurance. Document: Parameters: Parameter Value Document Output Process to XML Processing Method Find/Replace then Build Document Document Assembly Instructions _sreg(xmlrecord),DS0 DS1 DS2 DS3 150 Information Builders 1. iWay Services Parameter Value DS4 Search QA Replace Quality Assurance Encoding UTF-8 Results: 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 the document assembly process. Because the Find/Replace operation is performed after compiling the output document, both occurrences of QA are replaced with Quality Assurance. Document: Parameters: Parameter Value Document Output Process to XML Processing Method Build Document then Find/Replace Document Assembly Instructions _sreg(xmlrecord),DS0 DS1 DS2 iWay Service Manager Component Reference Guide 151 Available Services Parameter Value DS3 DS4 Search QA Replace Quality Assurance Encoding UTF-8 Results: Example 7: Only Find/Replace This example only performs a Find/Replace operation. In this case, only the document that is presented to the service is searched and any occurrence of QA is replaced with Quality Assurance. Document: Parameters: Parameter Value Document Output Process to XML Processing Method Only Find/Replace Document Assembly Instructions DS1 DS2 152 Information Builders 1. iWay Services Parameter Value DS3 DS4 Search QA Replace Quality Assurance Encoding UTF-8 Results: 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 the document assembly process. There will be no replacements performed by the service. Document: Parameters: Parameter Value Document Output Process to XML Processing Method Only Build Document Document Assembly Instructions _sreg(xmlrecord),DS0 DS1 DS2 DS3 iWay Service Manager Component Reference Guide 153 Available Services Parameter Value DS4 Search QA Replace Quality Assurance Encoding UTF-8 Results: 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. The attachment headers are specified with user parameters. The name and value of the user parameter become the name and value of the header. Notice the value of the Content-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 application/binary if the document contains bytes text/plain if the document is flat application/xml otherwise 154 Information Builders 1. iWay Services 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 header value if desired. The Body Result parameter specifies what to return in the output document: keep copies the input document to the output document, empty returns an empty document instead. This service follows OnSuccess upon successful execution, otherwise it follows the fail_attach edge. 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 is generated based on the data format. Body Result Specify how to handle the body of this document by selecting one of 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 iWay Service Manager Component Reference Guide 155 Available Services 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 runtime The path to the runtime command file for iWay DQC. For example, command file * 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 be executed. 156 Information Builders 1. iWay Services Parameter Description Runtime Configuration The fully qualified path to the default runtime configuration file. File Location * Additional Path A comma-separated list of additional path variable names. Use Variable Name(s) this to add additional path variables to the default configuration. Additional Path A comma-separated list of additional path variable values. Use Variable Value(s) this 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 iWay Service Manager Component Reference Guide 157 Available Services 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 more elements, each of which will be sent to iWay MDC. Leave blank to send the input document as is. XPath Syntax * Determines the syntax level of XPath that should be used. The default option selects the syntax level as set in the General Settings section of the iSM Administration Console. Select one of the 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 158 Information Builders 1. iWay Services 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 Data Quality Runtime Provider. Parameters: Parameter Description Data Quality Runtime Specify the configured iWay Data Quality Runtime Provider Provider * that 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. iWay Service Manager Component Reference Guide 159 Available Services Parameter Description Runtime Config File Specify the location of the iWay DQC runtime configuration (Optional) file. This file is used to define an iWay DQC runtime variable, such as JDBC data sources or folder shortcuts used in the plan. XPath Expression * Specify an XPath expression that will return one or more elements from the input document that will be used as input records when the iWay DQC plan is invoked. XPath Namespace Map If the input document contains namespaces, then this parameter specifies the configured namespace map to be used when evaluating XPath expressions. Replace or Preserve? * Determines whether the children of the record element in the output document should be preserved (appending the result of the iWay DQC plan execution as new child elements), or should the original children be replaced with the iWay DQC plan 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 160 Information Builders 1. iWay Services 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 now includes a second group called Defined Data Quality Runtime Providers, as shown in the following image. iWay Service Manager Component Reference Guide 161 Available Services The former group (Defined Data Quality Providers) is now deprecated. It is recommended to migrate to the new provider (Data Quality Runtime Provider). The original Data Quality Provider represented a single iWay DQC plan. This required you to configure one Data Quality Provider for 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 local instance of iWay DQC that is installed with iSM. In a future iSM release, it will be possible to configure 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 the iWay DQC subsystem in use. Note that these pool settings apply to each iWay DQC plan that is managed by the provider. Thus, if the iWay DQC runtime loads 3 separate plans and the Maximum Pool Size parameter is set to 3, then a maximum of 9 execution threads will be pooled. 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 162 Information Builders 1. iWay Services The document-driven version of the service has the same functionality as the deprecated Data Quality 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 a specific iWay DQC plan, the service must be configured with the path to the plan file (and optional runtime configuration file). For more information about using Data Quality Runtime Providers with one of the supported services, see Using the Data Quality Center Service (User Parameter-Driven, Pooling) on page 165. 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 plan is dynamic and called by name. Parameters: Parameter Description Data Quality Runtime Specify the configured iWay Data Quality Runtime Provider that Provider * 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. Runtime Config File Specify the location of the iWay DQC runtime configuration file. (Optional) This file is used to define an iWay DQC runtime variable, such as JDBC data sources or folder shortcuts used in the plan. iWay Service Manager Component Reference Guide 163 Available Services Parameter Description Include Input? * Determines whether the input data (from user parameters), should be included in the output document that is generated by this service. Select true or false. Include Messages? * Determines whether messages generated during the execution of the iWay DQC plan should be included in the output document that is generated by this service. Select true or false. Edges: The following table lists the available line edges for the Data Quality Center Service (User Parameter-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 164 Information Builders 1. iWay Services 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). iWay Service Manager Component Reference Guide 165 Available Services The record that is passed to the iWay DQC plan is defined using user parameters. This can be configured using iWay Integration Tools Designer, or you can create a parameter set in the Registry under the Variables section, and then attach the parameter set to the configured service. The names of these parameters will be passed to iWay DQC as field names and the evaluated parameter values as the field values. Typically, the parameter values will be set using iFL expressions, using special registers or XPath to extract values from the input document of the service. 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, and optionally 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. 166 Information Builders 1. iWay Services Procedure: How to Use the Data Quality Center Service (User Parameter-Driven, Pooling) to Invoke a Sample Plan To invoke the sample hello_customer plan using the Data Quality Center Service (User Parameter-Driven, Pooling): 1. Configure a Data Quality Runtime Provider as described in Configuring Data Quality Runtime Providers on page 161. For this example, do not be concerned about the pooling options. You can leave the default value, which pools one execution thread. Specify DQRuntime as the name for the Data 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 for this service as indicated in the following table: Parameter Value Data Quality Runtime Provider DQRuntime DQC plan file Specify the path to the iWay DQC hello_customer.plan file. Runtime Config File 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 n the input document. Remember, this service only processes one record at a time. iWay Service Manager Component Reference Guide 167 Available Services 4. Test the process flow in the configuration where you created the Data Quality Runtime Provider using the following input document: The resulting output should be structured as shown in the following example: Note: The input record is included and the document also includes an element for messages. However, since this iWay DQC plan completed without any messages from iWay 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. 168 Information Builders 1. iWay Services 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 rule results. 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. iWay Service Manager Component Reference Guide 169 Available Services 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: 170 Information Builders 1. iWay Services Parameter Description Acknowledgment The EDIFACT Acknowledgment Type. Type Interchange Control The element location. Reference Message Reference The element location. Number 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 XML message. Parameters: iWay Service Manager Component Reference Guide 171 Available Services 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. 172 Information Builders 1. iWay Services 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: iWay Service Manager Component Reference Guide 173 Available Services 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 10 or code 13. 174 Information Builders 1. iWay Services 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. iWay Service Manager Component Reference Guide 175 Available Services 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 in tandem 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. Stream Acknowledgment the stream. Acknowledgment 176 Information Builders 1. iWay Services Parameter Description Acknowledgment Acknowledgment level. 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 data as an attachment. Parameters: Parameter Description Outgoing Mail Host * Outgoing email host used to route outgoing email (add:port for non-standard port). iWay Service Manager Component Reference Guide 177 Available Services Parameter Description To * Message recipient as an email address. Use a semicolon (;) to delimit 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 delimit multiple addresses. Blind Copy To Blind Carbon copy recipient of this email. Use a semicolon (;) to delimit multiple addresses. Reply-to Address to reply to, for this email. Use semicolon (;) to delimit multiple addresses. Content Contains the data for the email body, default (blank) is the inbound document. Attachment Tag Tag name that holds a path to a file to be attached. This is an exact element name and not an XPATH expression. If the add_attachment tag is defined in the incoming XML document, then provide add_attachment as the value for this parameter and not 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 Attachment Name of the inbound document attachment. Name Attachment Content Content Type of the attachment. Type 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. 178 Information Builders 1. iWay Services 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, then negotiate 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 iWay Service Manager Component Reference Guide 179 Available Services Example: To configure the Email Emit service, you must first specify the URL for your email server and the appropriate security level. The following example shows security settings that are configured for the Microsoft Exchange Server: 180 Information Builders 1. iWay Services If your connection parameters are valid, you will receive an email notification that would context the incoming document and a response document from running the service, in the following format: The following is an example of configuration settings for an Email Emit service object that includes an attachment in iIT Designer: iWay Service Manager Component Reference Guide 181 Available Services If your connection parameters are valid, you will receive an email attachment (test.doc) and a response document from running the service, in the following format: 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. If the 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 that valid XML could be formed. Select true or false from the drop- down list. 182 Information Builders 1. iWay Services 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 Encoding set to true, and incoming data as If Base64 Encoding is set to false, the result would be: 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: iWay Service Manager Component Reference Guide 183 Available Services 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 Contract The address of the smart contract to call. Address * Value The amount of Ether (in wei) you wish to deposit in the smart contract (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 transaction receipt. 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. 184 Information Builders 1. iWay Services 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 query the 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 Contract The address of the smart contract to call. Address * 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 return parameters. iWay Service Manager Component Reference Guide 185 Available Services Edges: The following table lists the available Line Edges for the Ethereum Call Constant Function Agent 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. 186 Information Builders 1. iWay Services Parameter Description Value The amount of Ether (in wei) you wish to deposit in the smart contract. This value must be 0 if the contract does not accept Ether. 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 transaction receipt. 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 iWay Service Manager Component Reference Guide 187 Available Services 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 Wallet The destination account where the funds will be deposited. Address * Value The amount of Ether (in wei) you wish to send to the destination address. Sleep Duration The time in milli-seconds between attempts to get the transaction receipt. 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. 188 Information Builders 1. iWay Services 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 to read 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 all sheets. Terminate * Terminate the agent when an error occurs. iWay Service Manager Component Reference Guide 189 Available Services 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 the operation requested. OnNotFound The resource was not found and this is considered 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 this service from a process flow. For more information, see the iWay Integration Tools Designer User's Guide. Parameters: Parameter Description SQL DML * SQL statement. Data Source URL * URL to reach the data source. 190 Information Builders 1. iWay Services Parameter Description Document Return Type Document to return. Select one of the following options from the * drop-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 return document is set to Statistics. Handler Parameters Parameters passed to the Statistic Handler. Stats Wait The amount of time in seconds to wait after an unsuccessful attempt 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 iWay Service Manager Component Reference Guide 191 Available Services 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 for the Type of failure parameter, the exception calls for a retry of the input, if possible. This service 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 following values from the drop-down list: fail retry The default value is fail. Message The message to be issued to the user. 192 Information Builders 1. iWay Services Parameter Description Bypass Catch Processing On failure, determines whether to bypass upper-level Catch nodes. Select one of the following values from the drop-down list: true. Immediately ends this process thread with an uncatchable termination, bypassing error processing. false. Allows the Fail service to participate in normal catch error handling. The default value is true. The setting of this parameter has no effect on process flows with no Catch nodes, or when issued within the execution of a single Catch node. When multiple Catch nodes are employed in a process flow, the use of this parameter can impact the execution flow after failure. In this case, the usual setting should be true to cause the fail node to have immediate effect. Setting false will cause the failure request to be processed by upper-level Catch nodes. Bypass Error Message Indicates not to trace at the error level when this service terminates the process. This is useful for cases where the trace 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 Log When set, a transaction log entry (XALOG) is written with the Report Message failure message. This causes a message to appear in the transaction log analysis. The default value is false. Call at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default value is false. iWay Service Manager Component Reference Guide 193 Available Services 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 (for example, if a certain fatal condition is reported). If you run this service in a process flow using 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 the termination as an error condition by searching upward on the execution edge to locate a Catch node. 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 to false. 194 Information Builders 1. iWay Services It is not recommended to design process flows in which failure indications are used to control execution logic (for example, simulating a long jump). Failure indications should only be used in the 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. By storing the output links to the file system, this service is able to achieve a level of high performance 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 is designated as a local transaction channel. The first record to reach the accumulator in the process flow opens the file and prepares for operation. Subsequent entries to the service continue to write to the same file. A common case is either a streaming preparser or an iterator that presents multiple records to the accumulator. The full path to the file created for the accumulation is available after each execution of this service 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, the content 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 the operation, the new data is appended to the existing file. iWay Service Manager Component Reference Guide 195 Available Services 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 Base64 encoding. By default, this parameter is set to false. Append CRLF If set to true, a line termination sequence is written after the document. Call at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS 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 an invalid 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 196 Information Builders 1. iWay Services 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. This may 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 the data to write can be specified, for example, as an xpath expression. Destination File Path The full path to the file where the data is to be appended. If the file is not open for the append operation, it is created or opened as appropriate. iWay Service Manager Component Reference Guide 197 Available Services Parameter Description Close File A value that, when true, causes the file to be closed. In a streaming mode, the iFL expression _iseos() can close the file at the end of a stream, however other expressions can be used. No data 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 parm is configured to test EOS, then this must be true. If another approach 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 and the file ops agent, in that the target file remains open. It is the responsibility of the application to 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 198 Information Builders 1. iWay Services Description: This service lists the contents of a file directory that is accessible through the file system. You may select to view files, subdirectories, or both. Parameters: Parameter Description Directory The directory to be listed. This service does not descend directories. Include Determines what items should be included in the listing. Select one 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 of the file or subdirectory. For example, to select only .xml files, you might use ".*\.xml" as the pattern (the quotes are not included in the pattern). Note: The expression, .*\.xml is deconstructed as follows. The leading dot means any character, and the asterisk means any number of them, until a suffix of .xml is reached. The problem with the .xml is that the dot would mean any character, so it is escaped. Because this is not iFL syntax, the backslash does not need to be escaped. Pattern Type If the Selection Expression is supplied, indicate whether it should be interpreted as a regular expression (regex) or a DOS style wildcard (wildcard). Call at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default value is false. iWay Service Manager Component Reference Guide 199 Available Services 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:
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 was produced.
200 Information Builders 1. iWay Services
Line Edge Description
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_notfound: The directory to be listed was not found.
fail_operation: The directory to be listed was not reachable. This can come about if a relative directory cannot be resolved or the directory was not specified. Access permissions will also produce this 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 the file 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 value meeting the XPATH() criteria is written as a file. The assigned names are allocated sequentially based on the entered pattern.
iWay Service Manager Component Reference Guide 201 Available Services
Parameters:
Parameter Description
Source of Data Determines the source of data to emit. If you require a document to be emitted, then enter the corresponding system path for this document. If no value is specified, then the current document is used by default. You can also specify an iWay expression, including the xpath() function to specify a data source location (for example, if an XML document is used).
Target Directory * The target output directory.
File Pattern * The file name pattern. In the pattern, an asterisk (*) character is replaced by the current timestamp. So T*.out might become T2002-06- 25_12:02:24:43.out. A # character is considered a unique number. The number of # characters controls the length.
Avoid Preemitter If a preemitter exists on this route for output, this allows it to be bypassed for this emit operation. Perform this action to enable the output file to include non-processed (raw) information. Select one 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 output document.
input. Input document will become the output document.
swap. As input, but replace written data in the source nodes with the file name to which the data was written.
202 Information Builders 1. iWay Services
Parameter Description
Base64 Decode If set, the value is assumed to be in base64 notation. Only applicable if a specific write value is specified. Select one of the following options from the drop-down list:
true
false (default)
Respect If set, the emit respects the transactionality of the channel. If not Transactionality * set, the file is always written. Select one of the following options from the drop-down list:
true
false (default)
Call at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called 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
iWay Service Manager Component Reference Guide 203 Available Services
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
notfound
204 Information Builders 1. iWay Services
Example:
The following is an example of configuration settings for a File Emit service object in iIT Designer:
iWay Service Manager Component Reference Guide 205 Available Services
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 (for example, c:/out), with its name formatted according to the value that was specified for the File Pattern parameter (for example, testsvc[date/time mask].xml). The return document of the process flow would be an update from running the service, which indicates that the File Emit service worked successfully. For example:
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 file paths are supported explicitly or through iFL.
206 Information Builders 1. iWay Services
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 Expression syntax.
File (to) The destination file to be operated on. Wild cards are accepted. Required except for delete, size, and exists.
File (to) a directory File (to) references a directory. If it is unclear whether the path name names a directory or a file name, Service Manager will assume the path names a file.
File (to) Create Creates directories if they doesn't exist. Used only for copy, move, Directories rename, and append operations.
Size A special register designated to hold size. Required for the size operation.
Out Document * The document returned by the operation (bad input defaults to result).
Action on Failure * Determines whether an input document or status document is returned 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.
iWay Service Manager Component Reference Guide 207 Available Services
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 not be 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 supported explicitly or through a SREG or XPath expression evaluated using the incoming document.
Delete After Read Determines whether the file is deleted on a successful read.
208 Information Builders 1. iWay Services
Parameter Description
Format Format of the input data. Select one of the following options from the drop-down list:
flat (default)
XML
json
stream
Tag The name of the node in which to wrap the data read, in flat format.
Character Set The character set encoding to be performed on input. Base 64 is Encoding required 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 into the input document.
Parent Tag Determines 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 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.
iWay Service Manager Component Reference Guide 209 Available Services
Line Edge Description
OnFailedOperation Could not perform the operation requested.
OnNotFound The resource was not found and this is considered 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 this request as an XDTextDocument. The transform business service and standard output can accept and operate upon this output. The input business service can operate on flat or XML data, 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 input document must be:
This assumes that the tagname is set to filename. If the input format is 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 flat by default, or if the entag option is set to any value even if the XML input data format is selected.
Base Path Optional directory to be used if the incoming name is not absolute.
210 Information Builders 1. iWay Services
Parameter Description
Input Data Format Format of the input data. Select one of the following options from the drop-down list:
flat (default)
XML
Enclose Tag The name of the tag in which to enclose that data that is read. If omitted, no tagging is performed. If used, the output is XML.
Encoding Encoding to be performed on the input. Can be as is or base64. If omitted, no encoding is performed.
Delete After Read Determines whether the file is deleted after it is read. Select one of the 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
iWay Service Manager Component Reference Guide 211 Available Services
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 the file you want to read. The following is an example of configuration settings for a File Read service object in iIT Designer. This example assumes that the path to the file is contained within the
Run this service with a document such as the following:
The contents of the input.xml file will be received as the output.
212 Information Builders 1. iWay Services
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
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 and implementation of applications where file transport services are required. iWay Service Manager (iSM) provides the following FTP and SFTP services.
iWay Service Manager Component Reference Guide 213 Available Services
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
214 Information Builders 1. iWay Services
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 Solutions Development 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 and HEAD will send a request to a configured URL. HEAD will always return a status document.
HTTP Client Provider * The HTTP Client Provider (Pooling Provider) that manages HTTP connections for this emitter.
Request Content Type The content type for HTTP requests to be sent by this emitter.
iWay Service Manager Component Reference Guide 215 Available Services
Parameter Description
Request Header The special register namespace from which HTTP headers for Namespace the outgoing request will be taken. Choose Default Namespace to send HDR type registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be sent as HTTP headers.
Response Header The special register namespace into which HTTP headers from Namespace the incoming response will be saved. Choose Default Namespace to create special registers with no namespace prefix, 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 use NTLM, you must enable connection persistence.
OAuth 2.0
Authorization Server URL The URL where a new access token can be retrieved. The URL should be fully specified, including the https scheme.
HTTP Method for Token POST sends a URL-encoded entity, GET sends the request Request without a request entity.
Token Field The name of the field that holds the token in the JSON response.
Expiration Field The name of the field in the JSON response that specifies the length of time (in seconds) for which the token is valid.
Grant Type Specifies the requested response type. Usually client_credentials.
Client ID The client or App ID for the caller. This will be sent as the user ID in basic authentication credentials with the authorization request, and, if specified, encoded in the body of a POST request to the authorization server.
216 Information Builders 1. iWay Services
Parameter Description
Client Secret The client or App secret for the caller. This will be sent as the password in basic authentication credentials with the authorization request, and, if specified, encoded in the body of a POST request to the authorization server.
Encode Client Credentials If true, the client ID and client secret will be encoded in the in Request Body body of a POST request to the authorization server, in addition to being used as basic authentication credentials.
Resource The App ID URI of the receiving web service.
Resource Owner The username to encode in the POST body when grant type is Username password.
Resource Owner The password to encode in the POST body when grant type is Password password.
Special Register If specified, registers in this namespace will be included as Namespace for Additional fields in body of a POST request. Request Fields
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 value Time in seconds to wait for a response before signalling error. in Seconds *
Ask for Compressed If set, requests will set the Accept-Encoding header to indicate Response that the client can accept a compressed response, as described in RFC-2616. If the response has a compressed content encoding, the client will automatically inflate.
Compress Request If set, the HTTP request entity will be compressed using the selected encoding and the Content-Encoding header will be set accordingly.
iWay Service Manager Component Reference Guide 217 Available Services
Parameter Description
Try Expect/Continue If checked, client will send the HTTP Expect: 100-continue Handshake? header and await HTTP 100 response before sending request body.
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 that can be sent with this emitter. 0 means no maximum and blank will default to 256KB.
Maximum Response Size The maximum size of a response entity that can be received by this emitter. 0 means no maximum and blank will default to 256KB.
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 and 399.
OnFailClientError Client error status code between 400 and 499.
OnFailServerError Server error status code between 500 and 599.
OnFailedOperation Could not perform the operation requested.
218 Information Builders 1. iWay Services
Line Edge Description
OnParseError Could not parse a document.
OnFailLargeRequest Request entity size exceeds configured maximum.
OnFailLargeResponse Response entity size exceeds configured maximum.
OnHTTP-201 Created The request was successful, we created a new resource and the response body contains the representation.
OnHTTP-400 Bad Request The data given in POST or PUT failed validation. Inspect the response body for details.
OnHTTP-401 Unauthorized The supplied credentials, if any, are not sufficient 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 many simultaneous 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: iWay Service Manager Component Reference Guide 219 Available Services
Parameter Description
Cookie Name * The name of the cookie.
Cookie Value The value of the cookie; the value set must comply with RFC 6265.
Path Attribute The value of the path attribute in the generated cookie. The value "/" 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 the attribute, which lets the user agent determine when the cookie expires.
Secure Attribute Determines whether to add the secure attribute in the generated cookie. Automatic adds the attribute only if the listener is secure.
HttpOnly Attribute Determines whether to add the HttpOnly attribute in the generated 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.
220 Information Builders 1. iWay Services
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) for httpclient 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 iWay Service Manager Component Reference Guide 221 Available Services
Description:
This service is a general HTTP emitter for use within the service stack. The document is posted using 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 content Overrides content type of response. Select one of the following type options 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 timeout Seconds to wait for response before signaling error. value in seconds
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.
222 Information Builders 1. iWay Services
Parameter Description
Relay Inbound Content If set to true, relay headers as received (content type). Select one Type of the following options from the drop-down list:
true
false (default)
Proxy
Proxy If set to true, emit through proxy server. Select one of the following 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 Keystore under HTTPS section of the system properties if client authentication is required. Note, if keystore is configured in system properties make sure it has the CA certificate or the client certificate of the server you're connecting to. If keystore is not configured in system properties default truststore located under JRE_HOME/lib/security/cacerts will be used. Select one of the following options from the drop-down list:
true
false (default)
iWay Service Manager Component Reference Guide 223 Available Services
Parameter Description
Use 128-bit Encryption Enforces the use of 128-bit encryption. Select one of the following options from the drop-down list:
true
false (default)
Security Protocol Select one of the following security protocols from the drop-down list:
SSL. Supports some version of SSL; may support other versions.
SSLv2. Supports SSL version 2 or higher.
SSLv3. Supports SSL version 3; may support other versions.
TLS (default). Supports some version of TLS; may support other versions.
TLSv1. Supports TLS version 1; may support other versions.
Agent Specific Parameters
Return * Return from this agent. Select one of the following options from the drop-down list:
input
response (default)
status
Use Preemitters If set to true, preemitters will be used for this emit. Select one of the following options from the drop-down list:
true (default)
false
Response Wrapper The tag name with which to wrap the response if the response is Tag non-XML and must be XML
224 Information Builders 1. iWay Services
Parameter Description
Response Base64 Determines whether the response should be Base64 encoded. Encoded Select one of the following options from the drop-down list:
true
false (default)
The result of the post appears in the
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
iWay Service Manager Component Reference Guide 225 Available Services
Example:
The following is an example of configuration settings for an HTTP Emit service object in iIT Designer:
226 Information Builders 1. iWay Services
A simple way to test your HTTP Read service is to first configure a channel that uses an HTTP listener as the inlet and a File emitter as the outlet to examine the messages that are received by the listener. Your HTTP listener configuration settings would look similar to the following example, 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 run your process flow, which contains an HTTP Emit service object. You must supply an incoming document with the appropriate content (for example, HTML):
If the service runs successfully, you will receive this HTML document in the output folder that is specified by your File emitter. The HTTP listener channel picks up the document that is emitted by the HTTP Emit service.
HTTP Nonblocking Emit Service (com.ibi.agents.XDNHttpEmitAgent) Syntax: com.ibi.agents.XDNHttpEmitAgent
iWay Service Manager Component Reference Guide 227 Available Services
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 more information, 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 for this emitter.
Cookie Store Name Allows thread-specific management of cookies. If not specified, a cookie store global to the HTTP Client provider will be 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 use NTLM, you must enable connection persistence.
228 Information Builders 1. iWay Services
Parameter Description
Request Header Special register namespace from which HTTP headers for the Namespace outgoing request will be taken. Choose Default Namespace to send HDR type registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be sent as HTTP headers.
Default Namespace. Sends HDR type registers with no namespace prefix.
Supply a namespace prefix here to indicate which headers to send.
none. Means that no special registers will be sent as HTTP headers.
Request Main Part Header Special register namespace from which MIME headers for the Namespace outgoing request will be taken. Provide a prefix to control the request Main BodyPart headers in the presence of attachments. Selecting none means that no special registers will be sent as MIME headers.
Response Header Special register namespace into which HTTP headers from the Namespace incoming response will be saved. Choose Default Namespace to create special registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be created.
Default Namespace. Creates special registers with no namespace prefix.
Supply a namespace prefix here to indicate header namespace.
Empty namespace prefix will be treated as default.
Excluded Headers A comma delimited list (case insensitive) of headers that should not be sent with the request, even if they are found in the request header namespace.
iWay Service Manager Component Reference Guide 229 Available Services
Parameter Description
Ask for Compressed If set to true, the request will set the accept-encoding to Response indicate that the client can accept a compressed response. If the response has a compressed content encoding, the client will automatically inflate the response.
Compress Request If set to true, the request entities will be compressed using the selected encoding and the content-encoding header will be set accordingly.
Replace Connection? If set to false, the connection is not returned to the connection pool immediately. The identifier of the connection will be stored in the HTTP client-key special register and the connection can be handled by the HTTP Client Manager agent.
Maximum HTTP Client Maximum time the HTTP Client Manager can take to handle a Manager Delay particular connection before it is automatically aborted. The format is [xxh][xxm]xx[s]. The default is 60 seconds.
Try Expect/Continue If checked, client will send the HTTP Expect: 100-continue Handshake? header and await HTTP 100 response before sending request body.
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 can be sent with this emitter. A value of 0 means no maximum and if no value is specified, the parameter defaults to 256KB.
Maximum Response Size Maximum size of a response entity that can be received by this emitter. 0 means no maximum and blank will default to 256KB.
TCP Properties
Persistence If checked, ask the server to maintain the connection.
Response Timeout value The value in seconds to wait for a response before generating in Seconds an error.
Agent Specific Parameters
230 Information Builders 1. iWay Services
Parameter Description
Return Return from this agent. Choose input to return input document, status for an XML document with transaction parameters and status, or response to capture output from the 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 response is non-XML and must be XML.
Response Base64 If set to true, the response will use Base64 encoding. Encoded
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
iWay Service Manager Component Reference Guide 231 Available Services
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 input accepts a URL in the incoming document and issues an HTTP GET through that URL. The transform business service and standard output can accept and operate upon this output. It is presumed that some output is returned, otherwise an error is generated.
232 Information Builders 1. iWay Services
In a use case scenario, the HTTP Read service can be part of an architecture for a web search engine, similar to the Google search engine. The service could be used to traverse or spider the 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 to 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
iWay Service Manager Component Reference Guide 233 Available Services
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
234 Information Builders 1. iWay Services
Example:
The following is an example of configuration settings for an HTTP Read service object in iIT Designer:
A simple way to test your HTTP Read service is to first configure a channel that uses an HTTP listener. Your HTTP listener configuration settings would look similar to the following example, where an HTTP port and a document root are specified.
iWay Service Manager Component Reference Guide 235 Available Services
After you deploy and start the channel with the HTTP listener, you can test run your process flow, which contains an HTTP Read service object. You must ensure that the file name you supply within the
If the service ran successfully, you will receive the contents of index1.hml as the output from the 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.
236 Information Builders 1. iWay Services
The main purpose of these components is to identify a process flow to execute, given a URI path and the type of the HTTP request. The name of the process flow will be stored in a special register (SREG). In addition to this routing function, some elements in the URI path, and all keys and values in the URI query string, will be stored as SREGs. This functionality will be made available as a service for use within a process flow, but also as a reviewer. This allows for earlier execution in the processing stage to allow conditional routing to handle the execution of the identified process flow.
Parameters:
Parameter Description
Route File Path * The path to the XML file describing the route. The file is loaded when the service is first executed and remains in effect until the listener 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 in the 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 the process flow to run.
Route Namespace SREG namespace prefix to use when creating SREGs from path steps, including the process flow name register.
Query Namespace SREG namespace prefix to use when creating SREGs from the query string portion of the URI.
Output Type Determines in the event of a routing error, what document should be output from this service. Select one of the following document types:
status
input
Edges:
iWay Service Manager Component Reference Guide 237 Available Services
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 to delete the cookie in the client.
Edges:
238 Information Builders 1. iWay Services
The following table lists the available Line Edges for the HTTP Session Invalidator Agent Service (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 chaincode name.
Key * The name of the key.
Block Number * The number of a block containing a transaction with a write of the key. This is a non-negative integer block number, or a negative integer block number relative to the current block height (-1 is the latest block).
iWay Service Manager Component Reference Guide 239 Available Services
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 to string, 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 is an ISO 8601 time zone. Limit the key history depth to key writes timestamped earlier than the early limit. Timestamps are created by clients without a central clock. It is therefore recommended to specify a date earlier than necessary by some 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 Agent Service (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
240 Information Builders 1. iWay Services
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 regular string, or a byte array encoded as a hex string with two consecutive 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 Agent Service (com.ibi.agents.XDFabricQueryAgent).
Line Edge Description
OnError An exception occurred during execution.
iWay Service Manager Component Reference Guide 241 Available Services
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 integer block number, or a negative integer block number relative to the current block height (-1 is the latest block). When querying by block hash, this is a hex-encoded string with two hex characters per byte. When querying by transaction ID, this is the transaction ID.
Output Format The format of the result.
Batch Mode
242 Information Builders 1. iWay Services
Parameter Description
Early Limit The format is yyyy-MM-dd'T'HH:mm:ss.SSSXXX where XXX is an ISO 8601 time zone. Specifying an Early Limit turns on batch mode which will always return the queried block, and also includes the previous blocks up to but not including the first encountered block with all transactions timestamped earlier than the early limit. Timestamps are created by clients without a central clock. It is therefore recommended to specify a date earlier than necessary by some margin. The batch is also limited by the Batch Size when defined.
Batch Size Specifying a batch size turns on batch mode which will return up to that many blocks, starting from the queried block and its previous blocks, within the limits of the Early Limit if defined or the origin of the chain.
Edges:
The following table lists the available Line Edges for the Hyperledger Fabric Query Block Agent Service (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 iWay Service Manager Component Reference Guide 243 Available Services
Description: Calls chaincode to execute a transaction on 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.
Minimum Successful The minimum number of successful proposals required to Proposals send the transaction to the orderers.
Maximum Failed The maximum number of failed proposals tolerated. The Proposals transaction will not be sent to the orderers if there are more failed proposals.
Return Determines the contents of the output document. Ignored if asynchronous mode is selected.
Call
Argument Type The data type of all the chaincode arguments, either a regular string, or a byte array encoded as a hex string with two consecutive 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
244 Information Builders 1. iWay Services
Parameter Description
Is Asynchronous? In asynchronous mode, the input document is returned immediately after the proposal request. The TransactionEvent response is sent to an internal queue when it arrives.
Queue Name The name of the internal queue where the asynchronous TransactionEvent 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 you want these registers to be emitted with the message, set this to true. In resubmit operations, this is usually set to false.
Priority The priority is an integer between 0 and 9 inclusive. The lowest priority is 0. The highest most expedited priority is 9.
Put Timeout Time, in milliseconds, to wait for queue to become available when attempting to put a message on the queue. You can enter 0 for an unlimited wait, but this is not recommended. If no value is supplied, timeout will be set to 3000 milliseconds.
Request Context For synchronous or asynchronous processing, namespace or Namespace list of namespaces containing registers that will be made available to the internal listener. Select Default for all registers in default (no prefix) namespace or None to send no registers at all. Enter '*' for registers from all namespaces.
Edgehs:
The following table lists the available Line Edges for the Hyperledger Fabric Transaction Agent Service (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.
iWay Service Manager Component Reference Guide 245 Available Services
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 to the search appliance.
Secure Search? * If checked, use HTTP basic authentication to secure the feed and queries.
Feed Type * FULL replaces all previous data in the index from this datasource. INCREMENTAL adds new data to index, leaving existing 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. If delete, the URL is removed from the index.
246 Information Builders 1. iWay Services
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 records can wait before posting to the search appliance.
Strip XML Tags? * Determines whether < and > and quote characters be stripped from feed. The search appliance will not index text inside of XML tags, so this option is useful when indexing XML data.
Output Type * Determines whether the agent simply outputs its input, or whether 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). iWay Service Manager Component Reference Guide 247 Available Services
Parameters:
Parameter Description
Inflated Format * Determines the format of the inflated output. Select one of the following 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 not deflated.
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-speed transformation for special situations.
Parameters:
248 Information Builders 1. iWay Services
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 within the XML Namespace context of the Parent Element.
Replace Content Determines whether the existing children of the parent node are removed before the data is inserted.
XML Namespace Provider The provider for the mapping between XML namespace prefix and namespace URI in XPath expressions. If left blank, the XPath expressions in the Parent Element and the Next Sibling cannot contain namespaces.
XPath Syntax Determines which syntax level of XPath should be used. The default option selects the syntax level as set in the console global settings.
Create Parent Element Determines whether the parent element is created, if it is missing.
Parent Element The path to the element where the data will be inserted. If left blank, the parent is the root element. If Create Parent Element is true, the expression must adhere to Restricted XPath syntax, otherwise the expression may adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter. Restricted XPath has the form /step1/step2/... where a step has the form ns:elem[predicate] or a pair of consecutive steps that has the form *[1]/self::ns:elem[predicate] to indicate the element must be the first child of its parent. The namespace prefixes are optional, but if present they must be 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 and Create Parent Element is true, then the necessary elements and attributes will be created such that the expression would match successfully.
iWay Service Manager Component Reference Guide 249 Available Services
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 data is 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 document Service (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 embedded SAML assertion.
For more information about the Insert SAML Assertion service, see the iWay Service Manager Security Guide.
250 Information Builders 1. iWay Services
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 Manager Security 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 Manager Security 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 with its 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 be processed. iWay Service Manager Component Reference Guide 251 Available Services
Parameters:
Parameter Description
Queue Name * The name of the internal queue that is serviced by an internal queue listener. The queue is created when the channel is started and exists as long as the server is running.
Want User If set to true, user-type registers are passed to the destination queue. Registers DOC and HDR registers are always transferred with the message. By default, this parameter is set to false.
Priority Determines the relative priority of the message. Use this parameter to reorder the execution of messages. Only the relative numbers matter. Higher numbers do not execute messages faster, only the acquisition order by the internal channel is affected. By default, this parameter is set to 4.
Put Timeout Determines the amount of time that the emit will wait for the internal channel to accept the message. If the destination queue is inhibited, the emit is paused until the message can be accepted. If the timeout period expires, a status message is sent down the timeout edge, where your application might chose to pend the message. For more information on using inhibition to provide cascading flow congestion management, see Chapter 1, Introducing iWay Service Manager in the iWay Service Manager User's Guide.
Request Context By specifying a namespace, registers in that namespace will be sent to Namespace the destination queue. This is used to limit the registers to those of interest to the message process.
Response This parameter is used only for synchronous emits. If set, registers Context returned from the internal channel are placed into this namespace. Namespace
252 Information Builders 1. iWay Services
Parameter Description
Return * Select one of the following options from the drop-down list:
status (default). A status document is returned showing the success of the queuing operation.
input. The input document that originally came into the emit service is returned.
response. The response from the execution through the internal channel is returned. When response is set, the emitter waits for the response from the internal channel, making this a synchronous call.
Avoid Preemitter Determines whether any preemitter should be avoided. Select one of the following options from the drop-down list:
true (default)
false
Respect Determines whether this emitter should post messages regardless of Transactionality the commit or rollback state of the transaction. For example, you may not want to respect transactionality when passing messages that reflect the progress of an application or errors within the application. By default, this parameter is set to true.
Call at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. By default, this parameter is set to false.
Timeout Determines how many seconds to wait for a synchronous response. Set to 0 or leave blank to wait indefinitely.
Edges:
The edges returned are listed in the following table.
iWay Service Manager Component Reference Guide 253 Available Services
Edge Description
success The message was enqueued for execution by the listener and channel that 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 time period specified in the Put Timeout parameter. This signifies that the queue 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 some other reason.
notfound The queue was not available. In some applications this may not be considered an error, so this edge is provided along with the fail_notfound edge.
254 Information Builders 1. iWay Services
Example:
In a sample use case, an Internal Emit service is used to forward incoming documents to an internal queue. The architecture for this use case consists of two channels. The first channel feeds incoming documents to the internal queue and the second channel is used to process the internal queue. The first channel also contains a route that is associated with a process flow where an Internal Emit service is used. For example:
iWay Service Manager Component Reference Guide 255 Available Services
Every time an incoming document is processed by the first channel, the document is added to the internal queue, for example, queue1. The second channel contains an inlet that is associated with an Internal listener to access queue1. For example:
The second channel also contains a Move route, which routes the documents that reside on queue1 to the appropriate outlet. This outlet can consist of a File or Email Emitter. For example:
256 Information Builders 1. iWay Services
As documents are picked up by the first channel, they are processed by the first channel and then by the second channel. When the processing is finished, the documents will appear at the final 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 be reached, 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 3 seconds.
Edges:
The edges returned are listed in the following table.
iWay Service Manager Component Reference Guide 257 Available Services
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 not identifiable 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 adapter must first be configured using iWay Explorer.
Parameters:
258 Information Builders 1. iWay Services
Parameter Description
iBSP URL * Select an available iBSP URL from the drop-down list or type a URL using the following format: http://host:port
where:
host Is the name of the machine where iWay Service Manager is installed.
port Is the port on which iBSP listens for SOAP requests. The default port is 9000.
The iBSP URL allows you to access targets defined in the iBSP repository.
Adapter * The name of the configured adapter you are working with, for example, RDBMS.
Target * The name of the user-defined target that is associated with the configured adapter, for example, Oracle11.
Class The name of the Java class that implements the adapter associated with the service. This field is populated by iWay Service Manager when you create the Adapter service and should not be modified.
Descriptor Key used by iWay Service Manager to locate the adapter target parameters to associate with the service. This field is populated by iWay Service Manager when you create the Adapter service and should not be modified.
Keys Key used by iWay Service Manager to locate the adapter persistence keys associated with the service. This field is populated by iWay Service Manager when you create the Adapter service and should not be modified.
iWay Service Manager Component Reference Guide 259 Available Services
Parameter Description
Persist Connection If enabled, the adapter connection is reused between execution attempts. Select one of the following options from the drop-down list:
none (false). Each invocation of this service will create a new instance of the adapter. Thus, for simple processing, one instance of the adapter is used for each requested operation. When streaming, one adapter instance will be reused for all messages in the stream. In a transaction, each created adapter instance receives the commit or rollback.
persist (true). This refers to persistence at the process flow instance level. When an instance of the adapter is first encountered for a target, the service creates a new instance of the adapter that is specific to that target.
This adapter instance is reused by subsequent invocations of the service, within an iterator loop and across invocations of the worker, including use within a streaming preparser situation.
At the end of the process flow, the adapter instance is no longer available.
pool. An adapter with a specific set of parameters and a specific target will be cached at the worker (sub-channel) level. This means that multiple services within a process flow will share an adapter and that multiple invocations of the process flow or a different process flow requiring the same adapter or target will reuse that adapter. If you have a threading count of n, then there will be n instances of the cached adapter.
Note: The term target refers to an evaluated target in which any iFL has been replaced with the value of that iFL. For example, a target with a port in a special register will be treated as the port value after the register value is obtained.
Promote OnFailure If set to false, failure edges, such as fail_connect, are promoted to OnError. This is used for upward compatibility purposes.
260 Information Builders 1. iWay Services
Parameter Description
Emit OnFailure If the Promote OnFailure parameter is set to false, this parameter determines the type of document to emit on failures. Select one of 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 or that 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 adapters rather than this service. For more information, see the Configuring the Adapter in iWay Designer chapter in the iWay adapter documentation that corresponds to the specific adapter you are trying to add or define (for example, iWay XML Adapter for RDBMS User's Guide).
iWay Service Manager Component Reference Guide 261 Available Services
Using iWay Functional Language With Adapters A frequent requirement is to use iFL to adjust the target of an adapter, for example, to change the 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 table named testtable. The two tables have the same structure, but contain different data. The application designer wants to create a flow using the RDBMS adapter that executes the SQL statement, select * from testable, against either the table in smd1 or the one in smd2, depending on the input document.
262 Information Builders 1. iWay Services
iWay Service Manager Component Reference Guide 263 Available Services
Using Application Explorer, create an RDBMS adapter target pointing at either of the two databases, as shown in the following image.
264 Information Builders 1. iWay Services
In the target, create the statement, which can be named stmt1.
Now, add the adapter to the iSM registry.
iWay Service Manager Component Reference Guide 265 Available Services
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 several connection parameters that are required to be set dynamically for each destination, you can store the values you need in a properties file using property names that follow a naming convention. Thus, if you can set the dest special register, then you can use the value of this register to get the values that are required to make a connection. For this example, the properties file has the following structure:
smd1.host=localhost smd1.port=1433 smd1.dbname=smd1 smd1.id=sa smd1.password=harrison smd1.url=jdbc:sqlserver://localhost:1433;databaseName=smd1 smd2.host=sdewitt4 smd2.port=1433 smd2.dbname=smd2 smd2.id=sa smd2.password=harrison smd2.url=jdbc:sqlserver://localhost:1433;databaseName=smd2
266 Information Builders 1. iWay Services
Save the adapter in the registry as DynamicRDBMS.
Other ways to store specific information includes the iWay Trading Profile Manager or another table reachable using the _jdbc() function call.
Now you need to create a flow that uses the DynamicRDBMS adapter. Since the adapter is defined in the registry, you must work in a registry based project. To keep things simple, the flow will contain two components. The XDSREGAgent service will set the dest special register to either smd1 or smd2, depending on the value of an attribute in the input document. To keep things 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:
iWay Service Manager Component Reference Guide 267 Available Services
Since the dest attribute is set to smd2, you should use the correct properties to connect to the smd2 database.
Finally, you can retest the flow using the following input:
268 Information Builders 1. iWay Services
Now, the dest attribute is smd1, which means the adapter should connect to the smd1 database 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
Note: This service is deprecated. As an alternative it is recommended to use the SQL service.
iWay Service Manager Component Reference Guide 269 Available Services
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:
270 Information Builders 1. iWay Services
The JDBC Data Server properties must be configured before you can use the JDBC service. If you already configured a server, for example, localDB, you can run this service using the following input document:
If your connection parameters are valid and the JDBC driver is configured, you will receive a response document from your local database in the following format (for the row output type):
JDBC via iWay JNDI Datasource Service (com.ibi.agents.XDJdbcDSAgent) Syntax:
com.ibi.agents.XDJdbcDSAgent
iIT Service Object: iWay Service Manager Component Reference Guide 271 Available Services
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 Isolation The transaction isolation level to be set, if possible. Level
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 the iWay JNDI (provider), the name takes the form 'jndi/'
Edges:
The following table lists the available Line Edges for the JDBC via iWay JNDI Datasource Service (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
272 Information Builders 1. iWay Services
Description:
This service browses a JMS (Java Messaging Server) queue. It returns the message read from the queue but does not delete the messages on the queue. For more information on JMS, see the 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 the dropdown 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 in special registers (separated by a period (.) ).
Output format How the output is provided. Select one of the following values from the drop-down list:
Status
Xml
Asread
iWay Service Manager Component Reference Guide 273 Available Services
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 a status document or the original input document as the output document. For more information on JMS queue, see the Queuing Adapters chapter in the iWay Service Manager Protocol Guide.
274 Information Builders 1. iWay Services
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 iWay Service Manager Component Reference Guide 275 Available Services
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 more information on JMS, see the Queuing Adapters chapter in the iWay Service Manager Protocol Guide.
Parameters:
Parameter Description
Name The name of the queue or topic to be read.
JMS Message Model Type of JMS Message Model to use. Select one of the following values from the drop- down list:
queue
topic
276 Information Builders 1. iWay Services
Parameter Description
Durable Subscriber A durable subscriber is a virtual message consumer for the specified topic, identified by the unique combination of a client identifier and subscriber name. When a message arrives for the topic and no message consumer is currently active for it, the message will be retained for later delivery.
Message Type The type of JMS Message the system is to expect. Select one of the following values from the dropdown list:
text
bytes
map
dynamic
Timeout The timeout period in seconds.
Tag Name of the XML tag to wrap the data read in. Required if data is flat.
Embed Whether to embed the data from the read operation into the input document. Select one of the following values from the dropdown list:
true
false
Parent Tag Where in the input document should the input data be embedded,
iWay Service Manager Component Reference Guide 277 Available Services
Parameter Description
Base64 Encode Base64 encode the read in document when embedding. Select one of the following values from the drop-down list:
true
false
Parse to XML Should the agent attempt to parse the input into XML:
true
false
Out Document Select one of the following values from the drop-down list:
status. A status document will become the output document.
input. Input document will become the output document.
result. Message read will become the out document.
Action on Failure Whether input document or status document returned on failure. Select one of the following values from the drop-down list:
input
status
Connection Factory The object store name.
278 Information Builders 1. iWay Services
Parameter Description
Local Context True if connecting to an internal jndi store. Select one of the following values from the drop-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. Select one 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
iWay Service Manager Component Reference Guide 279 Available Services
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 a choice 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 take an arbitrary JSON object and convert it to XML, but it can also take an arbitrary XML document and convert it to JSON. A round-trip will often produce the same input, but this is not guaranteed. JSON field names are reused as XML element names. This makes XPath expressions look natural when they are evaluated against the resulting XML document.
The Standard transformation is described in section 22 of the XSLT3 specification. This algorithm is simple because it is designed to express JSON objects in a specialized XML form that conforms to a specific XML schema. This supports a perfect round trip of JSON objects to XML and back. XPath expressions to query the XML form is slightly more verbose because predicates are needed to match field names stored in attribute values.
280 Information Builders 1. iWay Services
Parameters:
Parameter Description
Conversion Chooses the conversion from JSON to XML, or XML to JSON using the Standard transformation described in the XSLT3 specification, or the iWay transformation.
Outer Tag When converting from JSON to XML using the iWay transformation, the Outer Tag is the name of the root element wrapper in XML. When absent, only JSON objects with a single field can be converted to XML, with the field name promoted to the root element name. When converting from XML to JSON using the iWay transformation, this instructs to skip the root element if the 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 iWay transformation, this determines the data type of literal values in JSON. Dynamic will parse the XML text to discover the JSON type. This makes it convenient to use the values in JSON, but it assumes that everything that looks like a number is indeed a number. String will always quote the literal value. This always preserves the value without modification, but Boolean or numeric values 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 iWay transformation, this is the encoding used to convert the JSON string to bytes before storing in the document. This is ignored when using the Standard transformation.
Edges:
The following table lists and describes the edges that are returned by the JSON Conversion Service.
Line Edge Description
success The document was successfully converted.
iWay Service Manager Component Reference Guide 281 Available Services
Line Edge Description
fail_parse An iFL expression could not be evaluated or a JSON document could not 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 flat document. A flat document will be parsed to a JSON value before being transformed. An XML input 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 the name generated for the corresponding top level Element in XML. It is always recommended to define 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 promotes that field to top level. Without an Outer Tag, trying to convert a JSON object with zero or more than one fields causes an error.
An array is represented in XML with multiple consecutive elements of the same name. This requires an empty or singleton array be marked with the following attribute to indicate the array type for the round-trip: json:force-array="true"
An array within an array is also anonymous and will be converted to a containing element called array to preserve the array structure.
The namespace prefix json stands for the http://json.org/ namespace. The prefix is automatically declared.
282 Information Builders 1. iWay Services
JSON accepts more valid characters than XML. The iWay transformation handles this by replacing an invalid character with the escape character underscore followed by a 4-digit hexadecimal string. The underscore was chosen because it is a valid start character in XML element names. When a field name must be escaped, it is marked with the following XML attribute: 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 these attributes is false. The underscore character is not escaped, unless another character must be escaped 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 JSON document or a flat document is invalid and causes a fail_format error. The input can be any arbitrary XML document, but some conventions must be followed to produce desired JSON forms.
The output is a bytes document containing the serialized JSON object. The encoding used to convert 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 by name, they do not have to be consecutive.
Multiple text-nodes within a mixed-content parent Element are converted to a JSON field called content with an array value. This mapping is not reversible when going back to XML.
iWay Service Manager Component Reference Guide 283 Available Services
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. String literals will be double-quoted whereas numbers and Booleans will not. This makes it convenient to use the values in JSON but it assumes that everything that looks like a number is indeed a number. Setting the parameter to String will always quote the literal value. This always preserves the value without modification, but boolean or numeric values may have to be converted explicitly in JSON expressions.
An element with the following attribute will have its name unescaped to produce the JSON field name: json:escaped-key="true"
An element with the following attribute will have its value unescaped to produce the JSON string value. json:escaped="true"
iWay Transformation Examples The following table shows the correspondence between JSON and XML. The Outer Tag is assumed to be JSON, and the JSON Literal Type is set to Dynamic.
Concept JSON XML
Non-object 1
Empty Object 0
Null {"null1": null}
Number {"num1": 1}
String {"str1":"abc"}
Boolean {"bool1":true}
Multiple Fields {"key1": "val1", "key2":
Subobject {"obj1":{"sub1":1}}
284 Information Builders 1. iWay Services
Concept JSON XML
Empty Array {"array0":[]}
Singleton Array {"array1":[1]}
Array {"array3":[1,2,3]}
Subarray {"array2d":[[11,12],[21,22]]}
Regular {"a_b":1}
Escaped Key {"a:b":1}
Escaped {"a_\u0003":1}
Regular {"a":"a_b"}
Escaped Value {"a":"a_\u0003"}
Both Attributes {"a:b":"a_\u0003"} {"a:b":"a_\u0003"}
iWay Service Manager Component Reference Guide 285 Available Services
The following table shows how JSON is transformed to XML when the Outer Tag is absent. The conversion succeeds only when the input JSON object has a single field. To avoid this error, it is 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"}
Multiple Fields {"key1": "val1", Error document with fail_operation "key2": "val2"}
The following table shows how XML is transformed to JSON when the JSON Literal Type is set to String. The Outer Tag is assumed to be JSON. All primitive literals become quoted strings.
Concept XML JSON
Null
Number
String
Boolean
The following table shows some notable cases when XML is transformed to JSON. The Outer Tag is assumed to be JSON.
Concept XML JSON
Simple Type
Mixed Content
286 Information Builders 1. iWay Services
Concept XML JSON
iWay Transformation XPath Example The iWay transformation produces XML documents that are intuitive to query with XPath. For example, the following JSON object:
{"obj":{"list":[11,22,33]}}
is transformed into:
11
22
33
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 supports perfect 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 and causes 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-functions namespace 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
iWay Service Manager Component Reference Guide 287 Available Services
A JSON object is mapped to an element called map as indicated in this table. Each field is mapped to an XML subelement named according to this table. The field name is stored in the key attribute of the subelement.
An array item is mapped to an element called array. Each array item is mapped to an XML subelement 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 by replacing an invalid character with the escape character backslash followed by a 4-digit hexadecimal string. When a field name must be escaped, it is marked with the following XML attribute:
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 both attributes. When absent, the default value of these attributes is false. The backslash character is 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 a specific form, which means it must satisfy the expected XML schema. A parsed JSON or a flat input 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. For more 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 by the key attribute. If the attribute escaped-key="true" is present, then the value of the key attribute is unescaped first to produce the field name. It is an error if the key attribute is missing.
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 JSON field name.
escaped-key="true"
288 Information Builders 1. iWay Services
An element with the following attribute, will have its value unescaped to produce the JSON string value: escaped="true"
Standard Transformation Examples The following table shows the correspondence between JSON and XML and back. The examples are perfectly symmetric.
Concept JSON XML
Non-Object 1
Empty Object {}
Null {"null1": null}
Number {"num1": 1}
String {"str1":"abc"}
Boolean {"bool1":true}
Multiple Fields {"key1": "val1", "key2":
Subobject {"obj1":{"sub1":1}}
iWay Service Manager Component Reference Guide 289 Available Services
Concept JSON XML
Empty Array {"array0":[]}
Singleton Array {"array1":[1]}
Array {"array3":[1,2,3]}
Subarray {"array2d":[[11,12],[21,22]]}
Regular Backslash {"a\\b":1}
Escaped Key {"a\u0003":1}
Escaped Backslash {"a\\\u0003":1}
Regular Backslash {"a":"a\\b"}
290 Information Builders 1. iWay Services
Concept JSON XML
Escaped Value {"a":"a_\u0004"}
Both Attributes {"a\u0003":"a\u0004"}
Standard Transformation XPath Example The Standard transformation produces XML documents that require slightly verbose expressions to query with XPath. For example, the following JSON object:
{"str1":"abc","list":[11,22,33]}}
is transformed into:
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 the following 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 JSON input document, since any other type of document will return a fail_operation edge. iWay Service Manager Component Reference Guide 291 Available Services
The data source can be left unparsed to be inserted as a string, or it can be parsed as a JSON literal allowing the insertion of typed values (for example, a JSON object, JSON array, a quoted string, a number, a Boolean, or null).
The value is inserted in one or more parents selected by a JsonPath expression. Selecting no parents causes the fail_notfound edge to be returned. Selecting more than one parent causes the 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 old value. Otherwise, a new field is created. If the parent is an array, then the key is the index within the array and the value replaces the old value at that index. If the index is larger than the array length, then the array is first extended with null values. If the key is left blank, then the 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 format treats the Data Source as character data. The JSON format parses the Data Source as a JSON value.
Parent Path A JsonPath expression returning one or more parents where to assign the JSON value. A parent can be a JSON object or a JSON array.
Key Determines where to store the value in the parent. For a JSON object parent, this is the key in the map. For a JSON array parent, this is the index in the array, where an empty string means append to the end, which causes the array to grow by 1.
Edges:
The following table lists and describes the edges that are returned by the JSON Insertion Service.
Edge Description
success The value was successfully inserted.
292 Information Builders 1. iWay Services
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 JSON document {"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 JSON document {"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 on configuring LDAP components using iWay Service Manager, see the iWay Service Manager User's Guide.
Parameters:
Parameter Description
Provider A URL to identify the LDAP service and the optional root context. iWay Service Manager Component Reference Guide 293 Available Services
Parameter Description
User A valid user name for the LDAP connection.
Password A valid password that is associated with the user name for the LDAP connection.
Doc Can Carry Access * If set to true, then the request document is permitted to carry access information, which overrides the credentials that are set for the configuration of this service. By default, this parameter 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
294 Information Builders 1. iWay Services
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 input record.
Copybook Option File Full path to the Copybook option file. This file specifies special Location filed handling rules. For more information, see Using the Copybook Option File on page 297.
Full FD? Set this parameter to true if COBOL group field headings are required to appear in the output XML. By default, false is selected.
Multiple Records? If set to true, then multiple CommArea records are produced if the input byte array is larger than the copybook size. By default, false is selected.
Input
Source of Legacy Record The COBOL copybook formatted source. If no value is specified, then the flattened input document is used. Otherwise, use iWay Functional Language (iFL) to specify the source.
Base 64 Encoded Input Determines if the source input data is encoded using Base64.
Input Encoding The Internet Assigned Numbers Authority (IANA) character set for 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 default encoding of the listener.
Output
iWay Service Manager Component Reference Guide 295 Available Services
Parameter Description
Output Node An XPath expression to specify the node in the input document to which the converted legacy record will be added as a child. XPath must point to an existing node, since new nodes are not created. If no value is specified, then the converted record is used as the output document. If the input document is in non- XML format, then the converted record is always returned as the output document.
Edges:
The following table lists the available line edges for the Legacy Record to XML Converter Service (com.ibi.agents.XDLegacyRecordToXMLAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_operation
296 Information Builders 1. iWay Services
Using the Copybook Option File The copybook option file is an XML document that allows the following data handling options to be set: 1. Error handling options for packed (COMP-3), zoned, alphanumeric, and binary fields in bytes to 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 values may 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 character handling types indicated above, may also be handled by a rule. This can return an arbitrary string as the contents of the field, optionally reporting the raw error bytes as an attribute. 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 during the 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 copybook and if the _option suffix is appended. This copybook option file is then used. For example, if the copybook is c:\copybook.cbl, then c:\copybook.cbl_option would be its associated copybook option file.
The following is an example of a copybook option file.
iWay Service Manager Component Reference Guide 297 Available Services
The root element is
In the above sample copybook option file, the first
A
298 Information Builders 1. iWay Services
Requires the onValue attribute. If the value of a field matches "PATTERN", substitute the value 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 the field in the XML output document. For example:
This provides a mechanism for an application to inspect invalid input and handle it programmatically. If this attribute is omitted, the raw data value of a field will not be reported in the XML document.
Requires the onValue attribute. If the value of a field matches "PATTERN", then an exception is generated.
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 the field is set to empty. If the field has a blank value, then the field is set to empty. The blank rule is defined in the second
If an options file has multiple actions that are applicable to a field, then the actions that are defined in the most specific field rule applies. If the Account field has all 0xFF bytes, then the value of the field is set to 1000. This is because the first
iWay Service Manager Component Reference Guide 299 Available Services
If two applicable actions are defined at the same level in terms of field rule specificity, then the action that appears first in the options file will be applied. Once exception to this is the INVALID pattern. The INVALID pattern will be checked after the other patterns even if it appears before the other patterns.
If there is no options file or no rules are defined for a field, then an exception is generated if the field value is not valid data.
If a copybook option file does not have
If only specific fields should preserver leading zeros, more specific
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:
300 Information Builders 1. iWay Services
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.
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 the application. In this scenario, the following copybook option file can be used.
iWay Service Manager Component Reference Guide 301 Available Services
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 service accepts the name of a configured LOCAL protocol which can be configured in any manner desired. The routes are pooled for efficiency. Unlike using an internal emitter to route a document to the internal protocol, this call is synchronous. Any errors reported by the named workflow are reflected in the calling flow, and any timeout configured for the flow includes time in the called flow. LocalMasterAgent differs from simply calling an external process flow in the normal manner in that a complete workflow is available including preparsers, reviewers, and so on. It is strongly recommended that this agent not be used unless no other means are available 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 message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default value is false.
302 Information Builders 1. iWay Services
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).
iWay Service Manager Component Reference Guide 303 Available Services
Parameter Description
Encode If set to true, everything is base64 encoded. If false, only non-txt is encoded.
Target Target of attachments.
Output Directory The target output directory.
Output File Name The output file name, which can contain an asterisk character (*) and is expanded to a timestamp, if an empty attachment name is used.
Note: If you want to preserve the original name of the attachment, do not 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
304 Information Builders 1. iWay Services
Example:
In a sample scenario, a channel can be configured that uses an Email listener as an inlet, and a Mail Attach service as a route. The Mail Attach service processes the attachment from the incoming email and places the resulting document within the attachment tag. The following is an example of configuration settings for a Mail Attach service object in iIT Designer:
When an email containing simple HTML
Notice that the attachment element was added to the original email, along with the location of the 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 iWay Service Manager Component Reference Guide 305 Available Services
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
306 Information Builders 1. iWay Services
misc: Marshall Agent
Description:
This service collects and serializes the content of a current document and its channel context as a single message. The marshaled message can then be sent to another listener, where it will 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 the message to another listener on that protocol. The next listener picks up the message, and the processing of the message resumes. The second channel can exist on another configuration or even another host.
Sending a marshaled message insures that the continuation of execution is on the same transaction ID (TID) as that of the originating channel.
You must not use this service when sending messages through server facilities that are managed internally. These include the internal emit service, the internal emitter, the RVI gateway relay facilities, and messages to be placed on pending queues. These services automatically marshal their own messages, and marshaling a marshaled message would create 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 a small set of octets (such as an XML message), but works poorly when the message consists of randomly distributed octets, such as a binary message.
Marshall User Special Determines if marshaling should include the user-level Registers special registers. By default, DOC and HDR registers are included in the marshaled message, along with some specific registers needed for Business Activity Monitor (BAM) and transaction tracking.
iWay Service Manager Component Reference Guide 307 Available Services
Parameter Description
Namespace If a namespace is specified, only special registers in the designated namespace are included in the marshaled message, along with the specific registers needed for BAM and tracking. This can be helpful when preparing multiple marshals for different targets, each of which needs different header registers. Other services are available to manipulate special register namespaces as required.
Use Encryption Determines if marshaled messages should be encrypted. A secure AES cipher is used, and must be deciphered by the receiver (using the Unmarshal service). Automatic unmarshaling cannot be performed on an encrypted message.
AES Key A cipher key shared between the marshal and unmarshal services. Usually, this is specified as a special register or from 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, or marshaled.
For more information, see Unmarshall Service (com.ibi.agents.XDUnmarshallAgent) on page 494.
MLLP Emit Service (com.ibi.agents.XDMLLPEmitAgent) Syntax: com.ibi.agents.XDMLLPEmitAgent
308 Information Builders 1. iWay Services
Description:
This service emits a message using the Minimal Lower Layer Protocol (MLLP). This protocol allows you to wrap an HL7 message with a header and footer to ensure you know where a message 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 receive MLLP messages.
Secure Connection Select true from the drop-down list if you want use a secure connection 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 Security Provider for SSL Context. If the Secure Connection parameter is set to true and the SSL Context Provider field is blank, then the default provider will be used.
Set TCP No Delay If set to true, then Nagle's Algorithm on the client socket will be disabled. This will result in faster line turnaround at the 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 timeout value is specified, a read() function call on the socket will block for only the amount of time specified (in seconds). If the timeout expires, a java.net.SocketTimeoutException is generated. The default timeout is dependent on the operating system being used.
Persistence If set to true, then iWay Service Manager (iSM) is instructed to maintain the connection.
Persistence Timeout value in The maximum length of time (in minutes) that a connection Minutes can persist with no activity. If this parameter value is zero (0) or left blank, then the default is set to 60 minutes.
iWay Service Manager Component Reference Guide 309 Available Services
Parameter Description
Retry Count The number of times to try to send the message after an initial failure is encountered. By default, this parameter is set to 0.
Retry Pause The amount of time (in milliseconds) to wait between retry attempts. 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 or received 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 response document, 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 the fastest 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 channel may need to parse an EDI document with a preparser or emit the document to a message queue.
310 Information Builders 1. iWay Services
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 status document 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. iWay Service Manager Component Reference Guide 311 Available Services
Parameter Description
queuemanager The queue manager name.
queuename The queue name.
The message ID appears in the
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.
312 Information Builders 1. iWay Services
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 MQ client connection.
Port The port number. It is only needed for an MQ client connection.
Channel The server connection channel name. It is only needed for an MQ client connection.
SSL CipherSpec The MQ CipherSpec determines that SSL is to be used. This is configured for the channel by the IBM Websphere MQ Administrator. SSL can be used only in client mode.
SSL Context Provider The iWay Security Provider for SSL Context. If the SSL Context Provider is left blank, the SSL truststore and keystore come from global system properties which can easily lead to conflicts.
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 select BytesMessage, TextMessage or MapMessage depending on the document contents.
JMSCorrelationID The value of the JMSCorrelationID header field.
Message Priority The outgoing message priority. Value must be between 0 and 9, with 9 being the most expedited. If omitted, it uses the incoming priority.
iWay Service Manager Component Reference Guide 313 Available Services
Parameter Description
JMSReplyTo The value of the JMSReplyTo header field.
JMSType The value of the JMSType header field.
Request Header The special register namespace from which protocol headers Namespace for the outbound request will be taken.
Acknowledgement Makes the JMS Session transactional or else specifies how received messages are acknowledged.
Delivery Mode Non-Persistent mode has low overhead but may lose messages. Persistent mode takes extra care to ensure the message is not lost in transit, but makes no absolute guarantee.
Time to Live The message's lifetime (in milliseconds). The default will live forever
Delivery Delay The minimum length of time in milliseconds that must elapse after a message is sent before the JMS provider may deliver the message to a consumer. JMS 2 only.
Preemitter Determines if any preemitter be avoided.
Return Document Determines whether the output document will be a status document 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.
314 Information Builders 1. iWay Services
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 selected based on a correlation ID.
If the message read appears to be XML the agent will attempt to parse it. Otherwise it will be added 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 destructive read.
iWay Service Manager Component Reference Guide 315 Available Services
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
316 Information Builders 1. iWay Services
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. 0 means 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 the server as the last message published on the topic.
Return Document Determines whether the output document will be a status document 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.
iWay Service Manager Component Reference Guide 317 Available Services
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. It returns a status document or the original input document as the output document. For more information on MSMQ, see the Queuing Adapters chapter in the iWay Service Manager Protocol Guide.
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 as XPATH(). The value must be between 0 and 9, with 9 indicating most 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. Selecting express 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.
318 Information Builders 1. iWay Services
Parameter Description
Return Select one of the following values from the drop-down list:
status {status}. The status document will become the output document.
original {input}. The original input document will become the output 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 iWay Service Manager Component Reference Guide 319 Available Services
http: MTOM Agent
MTOM: MTOM Agent
Description:
The Message Transmission Optimization Mechanism (MTOM) service can be used to format a document for MTOM transmission or to reconstruct a document received in MTOM format. Reconstruction converts the received MTOM message into a message format that can be handled by the attachment capabilities of the server.
Parameters:
Parameter Description
Operation Select one of the following specific operations to perform from the drop-down list:
Reconstruct the original message {reconstruct}
Reconstructs the original XML message document by replacing the MTOM references with the actual binary content found in the attachments.
Create an MTOM package {create}
Creates an MTOM message by replacing the contents of some binary elements with references to body parts in a new multipart attachment.
Add an Include {include}
Assumes the document is already an MTOM message and replaces one more binary element with a reference to a new body part.
Delete Attachments If the Reconstruct the original message option is selected for the Operation parameter, the Delete Attachments parameter specifies whether to delete the attachments that have replaced xop:Include elements.
320 Information Builders 1. iWay Services
Parameter Description
Element Path If the Create an MTOM package option is selected for the Operation parameter, you must specify an XPath expression for the Element Path parameter that returns the set of base64binary nodes to extract.
If the Add an Include option is selected for the Operation parameter, you must specify an XPath expression that returns the element where the xop:Include element will be added.
XML Namespace Provider A provider for the mapping between XML namespace prefix and namespace URI in the Element Path.
XPath Syntax Determines the syntax level of XPath that should be used. The default option selects the syntax level as set in the General Settings section of the iSM console. Select one of the following 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 the Operation parameter, this is the Content-Type set on a new attachment when the xmlmime:contentType attribute is absent on the extracted element.
Attachment Content-ID If the Add an Include option is selected for the Operation parameter, this value is the Content-ID of the existing attachment being referred to.
If the Create an MTOM package option is selected for the Operation parameter, the Content-ID of the new attachments will be the prefix specified here followed by a numeric suffix.
The edges returned are listed in the following table:
iWay Service Manager Component Reference Guide 321 Available Services
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 by attempting 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 input document.
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
322 Information Builders 1. iWay Services
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 an incoming XML document. If you provide the XPath location for the node where the extraction begins, you will receive an output of the XML sub-tree from the original document with the specified node as a root.
In the following example, the XPath expression is specified as Test/attachment/. The incoming document consists of the following:
The Node Set Extract service will return a result of the edge as success, along with the following output document:
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: iWay Service Manager Component Reference Guide 323 Available Services
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 in the same process flow. This option is not allowed with the Message ends at EOS Message Protocol.
Return Document The type of output from this service. If response, the service will wait up to the Response Timeout for a response from the server and will output this response as a bytes-type document. If status, the service will output a standard status document immediately after emitting to the server and will not attempt to retrieve any response.
Response Timeout The maximum time, in milliseconds, to block while waiting for a response from the server. 0 means no timeout. A negative value will use the system default.
TCP Connection Provider The name of the TCP Connection Provider to use for the * message emit.
Persist Connections? If true, use a connection from the TCP Connection Provider's pool and return the connection to the pool after emit. If false, a new connection will be created for this emit and closed after emit is complete. Use of persistent connections is not allowed with 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 Persistent Connections? to false and you must not use an SSL connection. To use a custom handler, supply the fully qualified name of a class that implements com.ibi.edaqm.IClientProtocolHelper and ensure that the class is 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. 0 means no maximum. Empty defaults to 256KB.
324 Information Builders 1. iWay Services
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 the connection is registered by the NTCP Client Register agent.
Return Document Type of output from this service. If input, the service will output its input document. If status, the service will output a standard status document after emitting to the specified connection. iWay Service Manager Component Reference Guide 325 Available Services
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 in the same process flow. This option is not allowed with the Message ends at EOS Message Protocol.
326 Information Builders 1. iWay Services
Parameter Description
Return Document The type of output from this service. If response, the service will wait up to the Response Timeout for a response from the server, and will output this response as a bytes-type document. If status, the service will output a standard status document immediately after emitting to the server and will not attempt to retrieve any response.
Response Timeout The maximum time, in milliseconds, to block while waiting for a response from the server. 0 means no timeout. A negative value will use system default.
TCP Connection Provider The name of the TCP Connection Provider to use for message * emit.
Persist Connections? If true, use a connection from the TCP Connection Provider's pool and return the connection to the pool after emit. If false, a new connection will be created for this emit and closed after emit is complete. Use of persistent connections is not allowed with 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 Persistent Connections? to false and you must not use an SSL connection. To use a custom handler, supply the fully qualified name of a class that implements com.ibi.edaqm.IClientProtocolHelper and ensure that the class is 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. 0 means no maximum. Empty defaults to 256KB.
Edges:
iWay Service Manager Component Reference Guide 327 Available Services
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 a message.
Port * The TCP Port on Host from which the service will attempt to read a message.
Cache Socket Locally * If true, cache the socket locally for reuse by other agents in the same process flow. This option is not allowed with the Message ends at EOS Message Protocol.
328 Information Builders 1. iWay Services
Parameter Description
Response Timeout The maximum time, in milliseconds, to block while waiting for a response from the server. 0 means no timeout. A negative value will use the system default.
TCP Connection Provider The name of the TCP Connection Provider to use for message * emit.
Persist Connections? If true, use a connection from the TCP Connection Provider's pool and return the connection to the pool after emit. If false, a new connection will be created for this emit and closed after emit is complete. Use of persistent connections is not allowed with 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 Persistent Connections? to false and you must not use an SSL connection. To use a custom handler, supply the fully qualified name of a class that implements com.ibi.edaqm.IClientProtocolHelper and ensure that the class is 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. 0 means 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.
iWay Service Manager Component Reference Guide 329 Available Services
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, as stored in the ntcp_connectionid special register when messages are received by the NTCP channel. This value can be passed to other channels as part of the message context, possibly as a correlation ID. If this service is running on an NTCP channel, leave blank to send a response to the client who originated the message being handled by the current process flow. When used with other protocols, Connection ID is required.
Return Document Type of output from this service. If input, the service will output its input document. If status, the service will output a standard status document after emitting to the client.
Edges:
330 Information Builders 1. iWay Services
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 to access 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:
iWay Service Manager Component Reference Guide 331 Available Services
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 a Google service account. OAuth 2.0 is described in RFC6749 and RFC6750. It is an authorization 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.
332 Information Builders 1. iWay Services
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 as input. Specify the parameters as:
Parameters:
Parameter Description
OpenRules File * The main .xls file that contains the decision to be executed.
Decision Name * The OpenRules decision to execute.
iWay Service Manager Component Reference Guide 333 Available Services
Parameter Description
Decision Objects The Java package where the decision classes reside. Package *
Input Date Format The date format pattern to validate input date values. Use Java SimpleDateFormat syntax or leave blank for the locale default pattern.
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 embedded XDIterCount iterator.
Parameters:
Parameter Description
Name of the PFLOW * The PFLOW to run.
Maximum Parallel Tasks The maximum number of tasks processed simultaneously. If * an additional task must be performed, it will wait for a previous task to complete. 0 means unbounded.
Timeout * The maximum time to wait for all tasks to complete, in seconds. 0 means unbounded.
Accumulation Version * Determins which version of accumulation is desired. Simple uses less memory, but handles only a single result from the subflow.
Iterations * The number of times to repeat the loop.
Edges:
334 Information Builders 1. iWay Services
The following table lists the available Line Edges for the Parallel Execution: Counted iteration Service (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 cancellation request.
OnParseError Could not parse a document.
OnNotFound The resource was not found and this is considered an error.
OnTimeOut The operation timed out.
OnFailedOperation Could not perform the operation requested.
failed_incomplete An operation failed before all the tasks could 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 embedded XDIterJsonSplit iterator.
Parameters:
iWay Service Manager Component Reference Guide 335 Available Services
Parameter Description
Name of the PFLOW * The PFLOW to run.
Maximum Parallel Tasks The maximum number of tasks processed simultaneously. If * an additional task must be performed, it will wait for a previous task to complete. 0 means unbounded.
Timeout * The maximum time to wait for all tasks to complete, in seconds. 0 means unbounded.
Accumulation Version * Determins which version of accumulation is desired. Simple uses less memory, but handles only a single result from the subflow.
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 iteration Service (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 cancellation request.
fail_parse Could not parse a document.
fail_notfound The resource was not found and this is considered an error.
fail_timeout The operation timed out.
fail_operation Could not perform the operation requested.
336 Information Builders 1. iWay Services
Line Edge Description
failed_incomplete An operation failed before all the tasks could 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 embedded XDIterXMLSplit iterator.
Parameters:
Parameter Description
Name of the PFLOW * The PFLOW to run.
Maximum Parallel Tasks The maximum number of tasks processed simultaneously. If * an additional task must be performed, it will wait for a previous task to complete. 0 means unbounded.
Timeout * The maximum time to wait for all tasks to complete, in seconds. 0 means unbounded.
Accumulation Version * Determins which version of accumulation is desired. Simple uses less memory, but handles only a single result from the subflow.
Snip levels * The number of top-down levels to be snipped from generated documents.
Expression * Describes the XPath location of the element on which to split. When Evaluate Expression is not set, enter an XPath expression directly. When Evaluate Expression is set, enter an expression that returns an XPath expression.
iWay Service Manager Component Reference Guide 337 Available Services
Parameter Description
Evaluate Expression When not set, the Expression parameter contains an XPath expression directly. When set, the Expression parameter is evaluated, and the returned value is the XPath expression used for splitting.
XML Namespace Map If the XPath expression depends on namespaces, supply the Provider name of an XML Namespace Map Provider that contains the required namespace prefixes and URLs.
Cross Section * If set, the iterated portion is included with the remainder of the non-iterated portion of the document. Otherwise only the parental path is included.
XPath Syntax Determines which syntax level of XPath should be used. The default option selects the syntax level as set in the console global settings.
Edges:
The following table lists the available Line Edges for the Parallel Execution: XML iteration Service (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 cancellation request.
OnParseError Could not parse a document.
OnNotFound The resource was not found and this is considered an error.
OnTimeOut The operation timed out.
338 Information Builders 1. iWay Services
Line Edge Description
OnFailedOperation Could not perform the operation requested.
failed_incomplete An operation failed before all the tasks could 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 XML format, this service performs no action. This service is useful if a flat (non-XML) input document 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
iWay Service Manager Component Reference Guide 339 Available Services
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
fail_parse: the output will consist of the original input document.
Example:
In a use case scenario, a response document is received from a web server using an HTTP emitter, which sends a request to the server. When the response is received from the web server, it is unreadable by a File reader until it is converted to XML format. As a result, using the 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 be parsed as a valid XML file, an error is returned.
340 Information Builders 1. iWay Services
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 document containing the form data.
Parameters:
Parameter Description
Original PDF Document Path to the original PDF document. If left blank, the PDF document 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: iWay Service Manager Component Reference Guide 341 Available Services
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 are supported explicitly or through a SREG or XPath expression evaluated using the incoming document.
File (to) Destination file to be operated on. Wild cards accepted. Required except 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 returned * 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 PF File Operations Service (com.ibi.agents.XDPFFileOpsAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
342 Information Builders 1. iWay Services
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:
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 supported explicitly or through a SREG or XPath expression evaluated using the incoming document.
iWay Service Manager Component Reference Guide 343 Available Services
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 is flat.
Character Set Character set encoding of the document to be read in. Default Encoding system encoding will be used if left blank.
Embed * Determines whether to embed the data from the read operation into the 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
344 Information Builders 1. iWay Services
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 Key A case sensitive passphrase to decrypt the session key. This Passphrase is optional, it will be used when the session key has been encrypted with a passphrase.
Secret Key Ring The location of the secret key ring containing the private keys to decrypt the session keys. This is optional, it will be used when the session key has been encrypted with a public key.
Private Key Passphrase The case sensitive passphrase to unlock the Decryption Private Key within the Secret Key Ring. This is optional, it will be used when the session key has been encrypted with a public 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 signature public keys.
Acceptable Hash A space-separated list of hash names that can be used in PGP Algorithms signatures. Other hashes will cause a validation failure before being evaluated. The intention is to forbid weak algorithms defined in the PGP specification. The default is SHA1 SHA224 SHA256 SHA384 SHA512.
Edges:
iWay Service Manager Component Reference Guide 345 Available Services
The following table lists the available Line Edges for the PGP Decryption and Verification Service (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 security violation.
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 for transfer in ASCII.
Literal Filename The filename to appear in the Literal Data Packet. The receiving program may use this name when storing the data to disk. The special value _CONSOLE means the data is unusually sensitive.
Signature
346 Information Builders 1. iWay Services
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 signature key.
Signature Key User ID The User ID of the private key used for signing. The format can be =name for the exact User ID, user@host to match only the email address, or
Signature Key ID The Key ID of the private key used for signing. 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 the fingerprint. Spaces are allowed and are not counted in the length. This property can be used in place of or together with the Signature Key User ID to select a more specific key.
Signature Key Passphrase The case-sensitive passphrase to unlock the Signature Private Key.
Signature Expiration The number of seconds after the signature creation time that the signature expires. The format is [xxh][xxm]xx[s]. If absent or has a value of zero, the signature never expires.
Compression
Compress Determines whether to compress the data in the PGP message.
Compression Algorithm The algorithm to use to compress the data in the PGP message.
Encryption
Encrypt Determines whether to encrypt the data in the PGP message.
iWay Service Manager Component Reference Guide 347 Available Services
Parameter Description
Symmetric Algorithm A symmetric algorithm to be used for encryption.
Encryption Method Determines how the session key is encrypted, use Passphrase for Password-Based Encryption (PBE), use Keypair to encrypt with a public key.
Encryption Passphrase The case-sensitive passphrase for when using the Passphrase encryption method. The passphrase will be used to generate a key encryption key to encrypt the session key.
Recipient 1
Public Key Ring 1 When using the Keypair encryption method, this is the location of the public key ring containing the encryption public key for the first recipient.
Encryption Key User ID 1 When using the Keypair encryption method, this is the User ID of the public key for the first recipient. The format can be =name for the exact User ID, user@host to match only the email address, or
Encryption Key ID 1 When using the Keypair encryption method, this is the Key ID of the public key for the first recipient. 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 the fingerprint. Spaces are allowed and are not counted in the length. This property can be used in place or together with the Encryption Key User ID 1 to select a more specific key.
Recipient 2
Public Key Ring 2 When using the Keypair encryption method with more than one recipient, this is the Location of the public key ring containing the encryption public key for the second recipient.
348 Information Builders 1. iWay Services
Parameter Description
Encryption Key User ID 2 When using the Keypair encryption method with more than one recipient, this is the User ID of the public key for the second recipient. The format can be =name for the exact User ID, user@host to match only the email address, or
Encryption Key ID 2 When using the Keypair encryption method with more than one recipient, this is the Key ID of the public key for the second recipient. 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 the fingerprint. Spaces are allowed and are not counted in the length. This property can be used in place or together with the Encryption 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 security violation.
PGP Sign Only Service (com.ibi.agents.XDPGPSignAgent) Syntax: com.ibi.agents.XDPGPSignAgent iWay Service Manager Component Reference Guide 349 Available Services
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 for transfer 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 signature key.
Signature Key User ID The User ID of the private key used for signing. The format can be =name for the exact User ID, user@host to match only the email address, or
Signature Key ID The Key ID of the private key used for signing. 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 the fingerprint. Spaces are allowed and are not counted in the length. This property can be used in place or together with the Signature Key User ID to select a more specific key.
Signature Key Passphrase A case-sensitive passphrase to unlock the Signature Private Key.
Signature Expiration The number of seconds after the signature creation time that the signature expires. The format is [xxh][xxm]xx[s]. If absent or has a value of zero, the signature never expires.
Edges:
350 Information Builders 1. iWay Services
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 security violation.
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 of PGPDecryptAgent.
Parameters:
Parameter Description
Location The location of the public key ring containing the signature public keys.
Edges:
iWay Service Manager Component Reference Guide 351 Available Services
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 security violation.
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 is used.
352 Information Builders 1. iWay Services
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 message * that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. 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:
iWay Service Manager Component Reference Guide 353 Available Services
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.
354 Information Builders 1. iWay Services
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 be read by the _property() iWay Functional Language (iFL) function, or by any appropriate tool.
iWay Service Manager Component Reference Guide 355 Available Services
Parameters:
Parameter Description
Path* The full path to the properties file to be updated. The suffix .properties is appended if it is not included in the file name. If the file does not exist, then it will be created.
Call at In a streaming environment, End of Stream (EOS) is the short message that EOS? is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. By default this parameter is set to false.
The properties themselves are user parameters, each constituting of a name/value pair. The values 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 File Updater 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 an object in a process flow, this service focuses on the user parameters that are defined within the 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
356 Information Builders 1. iWay Services
Third = Mary
The Properties File Updater service will create or update these specific user parameters in the input document.
A typical use case would be to use XPath to set the values of the user parameters. For example, if your input document looked like the following:
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 a designated target or can read from a source. In the standard situation for output, a
Protocol Agents Result Document
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. iWay Service Manager Component Reference Guide 357 Available Services
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 string value or a SREG reference for dynamic process flow invocation. In order for the service to be successful, the referenced process flow must be deployed as a service during run time.
Called at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called 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
358 Information Builders 1. iWay Services
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 process flow. 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 a process flow name stored as an SREG value.
The following is an example of configuration settings for a PFlow service object in iIT Designer:
iWay Service Manager Component Reference Guide 359 Available Services
Using an SREG allows you to add or change the name or list of names for the process flow to be called without modifying the original caller process flow.
The single or multiple process flows that are being called need to be deployed as services in order to be found by the PFlow service. Services can be deployed using the iWay Service Manager Administration Console from the Services category in the Deployments section, as shown in the following image.
P Flow Test Service (com.ibi.agents.XDPFlowTestAgent) Syntax:
com.ibi.agents.XDPFlowTestAgent
iIT Service Object:
360 Information Builders 1. iWay Services
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 a move 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 mode for 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 QA service to output documents when set to QA mode.
To enable the QA service to output documents on debug, set the iSM debug special register to true. To deactivate the debug mode, set the debug special register to false.
Parameters:
Parameter Description
Where * File pattern to receive trace file.
iWay Service Manager Component Reference Guide 361 Available Services
Parameter Description
When Determines when to emit the information. Select one of the following options 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 omitted or empty, the incoming document is not emitted.
Base64 Decode If set to true, the value is assumed to be in base64 notation. Only applicable when a specific write value is specified.
Starting Offset If set, this value represents the starting offset within the data block to start the dump.
Note: The inbound document must be a flat file in order for this parameter to function as described.
Maximum Length If set, this value represents the total number of bytes to dump. If not set, the dump starts from the value specified for the Starting Offset parameter 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
362 Information Builders 1. iWay Services
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 Advanced Message Queuing Protocol (AMQP). The Broker URI is the server address. The destination is a combination 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 secure communication over TLS, the scheme is AMQPS with the port defaulting to 5671. The virtual host 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 not allowed.
When using AMQPS, the TLS configuration is specified with an SSL Context provider. This provider is created in the iSM Administration Console within the Security Provider page under the Server tab.
The user name and password are the credentials to access the RabbitMQ server. The user is created in the RabbitMQ console within the Users page under the Admin tab. Make sure the user is given permission to access the chosen virtual host. The RabbitMQ console can usually be accessed at:
http://host:15672 iWay Service Manager Component Reference Guide 363 Available Services
In version 0-9-1 of AMQP, the message is not sent directly to a queue. Instead, the sender sends the message to an exchange and associates a Routing Key. It is the responsibility of the exchange to route the message to all the queues with a binding that matches the message and 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 and the value it must have to match. It is possible to specify multiple headers at the same time, in which case the x match attribute determines 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 any queue bindings and therefore was routed to zero queues. When this happens, an error is returned if mandatory is set, otherwise the message is silently discarded.
The RabbitMQ Emit Service expects the exchange, the queue bindings, and the destination queues to be pre-configured on the server. The service does not declare those objects automatically.
AMQP defines a set of properties that are always part of the message. Most properties are open 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 receiving application may use the Content Encoding and Content Type to reconstruct the message, but that is just by convention.
The properties that affect the broker are: Delivery Mode, Expiration and Priority. The delivery mode is Persistent or Non-Persistent. Persistent messages held in a durable queue will survive a broker restart.
The Expiration is the time the message can remain in the queue before it expires. Expired messages are either discarded or dead-lettered, but only when they reach the head of the queue. Until then, they occupy storage and are counted in the queue statistics. The Priority affects the order messages are delivered by a priority queue. The AMQP specification says the priority is from 0 to 9 but RabbitMQ supports priorities from 0 to 255.
364 Information Builders 1. iWay Services
Unlike message properties, message headers are not standardized. They are under the sending application control. When the Request Header Namespace is specified, every special register 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 called ns.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 default is to skip the preemitters.
The Return Document parameter determines the contents of the output document. Choose status 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 Exchange The exchange where the outgoing message will be published. Name
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 for AMQPS.
virtualhost Is also optional.
SSL Context Provider The iWay Security Provider for SSL Context. If you are using AMQPS and SSL Context Provider is left blank, then the default provider will be used.
User * User ID for the Broker.
iWay Service Manager Component Reference Guide 365 Available Services
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 zero queues. When set to true, an error is returned. When set to false, 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 integral number 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 Header The special register namespace from which protocol headers for Namespace the outbound request will be taken.
By default, this parameter is set to none.
366 Information Builders 1. iWay Services
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 status document 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 Emit service (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 the Advanced Message Queuing Protocol (AMQP).
The Broker URI has the following format: scheme://host:port/virtualhost
iWay Service Manager Component Reference Guide 367 Available Services
The scheme is AMQP for communication in clear with the port defaulting to 5672. For secure communication over TLS, the scheme is AMQPS with the port defaulting to 5671. The virtual host 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 not allowed.
When using AMQPS, the TLS configuration is specified with an SSL Context provider. This provider is created in the iSM Administration Console within the Security Provider page under the Server tab.
The user name and password are the credentials to access the RabbitMQ server. The user is created in the RabbitMQ console within the Users page under the Admin tab. Make sure the user is given permission to access the chosen virtual host. The RabbitMQ console can usually be 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. When the timeout expires, the service returns the input document with the edge noMessage. A value of zero (0) indicates to return immediately.
368 Information Builders 1. iWay Services
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 for AMQPS.
virtualhost Is also optional.
SSL Context Provider The iWay Security Provider for SSL Context. If you are using AMQPS and SSL Context Provider is left blank, then the default provider 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 Header The special register namespace into which protocol headers Namespace from 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 become available. A value of zero (0) indicates to return immediately.
By default, this parameter is set to 5000.
Special Registers (SREGs): iWay Service Manager Component Reference Guide 369 Available Services
There is a fixed list of message properties as documented in the AMQP specification. The service 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 the properties 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 service based 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 indicates persistent.
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.
370 Information Builders 1. iWay Services
SREG Name Description
amqp.userId Creating user ID.
Unlike message properties, message headers are not standardized. They are under the sending application control. When present, message headers are stored as special registers in the specified Request Header Namespace. For example, if a header is named hdr1 and the Request 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 Read service (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:
iWay Service Manager Component Reference Guide 371 Available Services
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:
372 Information Builders 1. iWay Services
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: iWay Service Manager Component Reference Guide 373 Available Services
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 is common to prepend cmd /C before the command.
Encoding* The Internet Assigned Numbers Authority (IANA) character set used to decode the command result. You can select a value from the drop-down list or type an encoding name directly in the field.
CData* Set this parameter to true if the command results are expected to be in CDATA format.
Timeout The amount of time (in seconds) to wait before the command times 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 a success notification is not returned to the process flow, enabling this parameter is not recommended. As an alternative, it is recommended to use the native background processing of the operating system when possible.
Call at EOS In a streaming environment, a short message is delivered after the last document in the stream is sent to signify the End of Stream (EOS). The Call at EOS parameter determines whether the service should be called for the EOS message. By default, this parameter is set to false.
The Timeout and Detach parameters have entirely different and somewhat mutually exclusive functions.
374 Information Builders 1. iWay Services
If defined, the Timeout parameter halts the current thread for the specified amount of time while a command is being executed or until a command result is returned. If a specified timeout value is reached and a command is still being processed, then the process flow returns the fail_timeout edge.
If the Detach parameter is set to true, then any timeout value becomes irrelevant because the command is executed in parallel by a separate thread. As a result, the process flow does not wait for command results from that thread in order to continue. The process flow resumes its execution 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 Service Manager Administration Console.
iWay Service Manager Component Reference Guide 375 Available Services
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 to invoke a third-party FTP program (CoreFTP) to perform a required file transfer. Similarly, you can also use this service to run the supported commands in your shell environment as needed by referring to third-party tools.
Example #2
In this example, a UNIX Perl script that takes a substantial amount of time to run must be executed by a customer. In addition, a process flow must be processed immediately, without waiting 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 to true, as shown in the following image.
This configuration allows the UNIX Perl script to be executed by a separate thread, while the process flow continues to run without any interruption.
Available Response Failure Edges for the Run OS Shell Command Service (XDRunCmdAgent)
376 Information Builders 1. iWay Services
During the configuration of a process flow, when you connect a Service object for the Run OS Shell 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 named service, in seconds.
Timeout The time to await response from the gateway, in seconds.
iWay Service Manager Component Reference Guide 377 Available Services
Parameter Description
Attempt Retry If true, a retry exception is thrown when no gateway connections are available, the message cannot be written to gateway, 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 a new connection if the message cannot be written to the gateway and, if a connection is available, will retry automatically. If no connections are available, or if the service times out or otherwise fails while reading the response, the service will return a failure edge.
Output On Failure If relay operation is unsuccessful, determined whether the agent should return the standard error document, or return its input. If the input is selected, the error document will be stored in the rvi.status register [type: user].
Method of compression The form of compression that should be used on the output. to use *
Edges:
The following table lists the available Line Edges for the RVI Relay: send message to gateway service 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. Something occurred between the adapter and adaptee communication.
OnFailTimeout The operation timed out.
378 Information Builders 1. iWay Services
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. EOS tells the relay iterator that no more data is coming. Fail sends a message indicating that gateway processing has failed.
Edges:
The following table lists the available Line Edges for the RVI Response: return iterations to the RVI 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: iWay Service Manager Component Reference Guide 379 Available Services
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 named service, 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
380 Information Builders 1. iWay Services
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 document from a SREG.
A document is the unit of information that passes through a process flow. There can be only a single document on any line of the process flow at any time. Documents include payload and state information. State information in the document is automatically managed by the server and 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 be recovered later on a process flow line. The Save/Restore Document Value Service accomplishes this by storing the document (or its payload) in a SREG, and later recovering the document 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 the * document.
Action to take * Determines the type of action that is taken by the service. Select one of the 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 the SREG.
iWay Service Manager Component Reference Guide 381 Available Services
Parameter Description
Level * Determines the level of information to be saved. Select one of the following 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 not affected.
Note: This operand applies only to store actions. The load action restores the document based on what was stored.
Clear * Used only for load actions, this parameter determines if the contents of the register should be cleared when the load is completed. This parameter is set to true by default.
No Activity Log If set, this register will not be logged in an activity log. Some drivers will * not 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 the appropriate type of information loaded.
382 Information Builders 1. iWay Services
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 the edge 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 from the 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 XML element names.
iWay Service Manager Component Reference Guide 383 Available Services
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.
384 Information Builders 1. iWay Services
Parameter Description
Schema Name The schema name, for example, xyz.xsd, xyz.rng, or xyz.sch.
Schema validation The schema validation type. Technique *
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 iWay Service Manager Component Reference Guide 385 Available Services
Description: Allows for the configuration and execution of scripts using the iSM Scripting Engine.
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 file located somewhere on the server file system.
dynamic - The script field will contains the actual script to be 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 the inbound document's element named script, SCRIPT, or Script.
Script The path to the script file or script document.
Script Parameters The script entry point and additional variables used to process the script. To specify a script entry point enter the value as '- entry functionName'. The entry point value is followed by any additional parameters that the script needs to execute. If no entry point is specifies the Scripting Engine starts execution with the first script statement not contained within a script function.
Output Document Type Determines whether the output document emitted should be the original input document (input), the agent's results (result) or a status document (status).
Edges:
386 Information Builders 1. iWay Services
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 security violation.. 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 characters maximum, including operators. Queries may additionally be limited by complexity.
Lang Restricts tweets to the given language, given by an ISO 639-1 two-letter code. Language detection is best-effort.
iWay Service Manager Component Reference Guide 387 Available Services
Parameter Description
Locale Specifies the language of the query you are sending (only ja is currently effective). This is intended for language-specific consumers, and the default should work in the majority of cases.
Max ID Returns results with an ID less than (that is, older than) or equal to the specified ID.
Since ID Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of tweets which can be accessed through the API. If the limit of tweets has occurred since the since_id, the since_id will be forced to the oldest ID available.
Count The number of tweets to return per page, up to a maximum of 100. The defaults is 15. This was formerly the parameter in the old Search API.
Result Type Optional. Specifies what type of search results you would prefer to receive. The current default is mixed. Valid values include:
mixed - Include both popular and real time results in the response.
recent - return only the most recent results in the response.
popular - return only the most popular results in the response.
Until Returns tweets created before the given date. Date should be formatted as YYYY-MM-DD. Keep in mind that the search index has a seven-day limit. In other words, no tweets will be found for a date older than one week.
388 Information Builders 1. iWay Services
Parameter Description
Geocode Returns tweets by users located within a given radius of the given 'latitude,longitude'. The location is preferentially taken from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by 'latitude,longitude,radius', where radius units must be specified as either mi (miles) or km (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations. However, you can use this geocode parameter to search near geocodes directly. A maximum of 1,000 distinct sub-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 have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token Secret.
Consumer Secret * Is your Twitter Application Consumer Secret. If you don't have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token Secret.
iWay Service Manager Component Reference Guide 389 Available Services
Parameter Description
Access Token Secret * Is your Twitter Application Access Token Secret. If you don't have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token 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.
390 Information Builders 1. iWay Services
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 operation requested.
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:
iWay Service Manager Component Reference Guide 391 Available Services
The following table lists the available Line Edges for the Security: Authenticate/Impersonate Service (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 security violation..
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.
392 Information Builders 1. iWay Services
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 and current format.
Parameters:
iWay Service Manager Component Reference Guide 393 Available Services
Parameter Description:
Error Sets whether the document is in error state. Documents in error state are sent to the errorTo addresses. The error state 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, this state 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 the correct IANA code. The encoding is used when the document is flattened or serialized for output. This does not affect the encoding in which the document is actually carried in the document.
Output Form Messages are carried in document in a form appropriate to their processing. Usually this is an XML tree. Use this option to change the form to either a binary byte array produced according to the encoding set, or a Unicode string. These formats are often called Flat in iSM documentation. Subsequent use of the document must expect that the message contained in the document arrives in the specified format
iFL Applies only if output form is String. If present, this iFL expression is applied to the flattened string.
394 Information Builders 1. iWay Services
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 in definition order.
Parameters:
Parameter Description
Type of variable The type of variable (headers appear in emitted documents as header values). Use the del type to delete the register. iWay Service Manager Component Reference Guide 395 Available Services
Parameter Description
Scope of variable Determines at what level the variable is defined, and therefore controls 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 for special situations like JMS properties.
Lock Name The name of a serialization lock for this set of register operations.
Automatic evaluation Causes the contents to hold functions that are evaluated on access.
No Activity Log If set, this register will not be logged in an activity log (some drivers may not respect this setting).
No Marshal If set, this register will not be marshalled for transfer via for example, gateway, pending storage, or AFTI.
Call at EOS When using a streaming preparser in a channel, a last call is made AFTER the last document. Determines whether this Service 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.
396 Information Builders 1. iWay Services
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 this service is cached until stopped.
Parameters:
Parameter Description
Host Name * The DNS name (or IP address) of the SFTP server that you want to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank for default port 22.
Buffer Size The size of the SFTP buffer to be used when sending or retrieving data. The default value of 32768 is used if this field is not set. A larger buffer may improve performance, but setting this field to a value greater than 65536 will default to 65536. The value must be entered as a whole number (for example, 32768, 65536). iWay recommends leaving the buffer 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 you want 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 iWay Service Manager Component Reference Guide 397 Available Services
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 no Provider name is specified, enter the user name and either a password or a Private Key and passphrase values (Passphrase is 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 will be 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 is cached until stopped. If set to stop, the cached connection is closed.
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 .
398 Information Builders 1. iWay Services
Line Edge Description
OnFailSecurity Could not operate dues to a security violation..
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 you want to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank for default port 22.
Buffer Size The size of the SFTP buffer to be used when sending or retrieving data. The default value of 32768 is used if this field is not set. A larger buffer may improve performance, but setting this field to a value greater than 65536 will default to 65536. The value must be entered as a whole number (for example, 32768, 65536). iWay recommends leaving the buffer 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 you want to connect to.
Proxy Port The port to connect to on the proxy site. iWay Service Manager Component Reference Guide 399 Available Services
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 no Provider name is specified, enter the user name and either a password or a Private Key and passphrase values (Passphrase is 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 will be 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 support the use of SCP.
Name of File * The file to be read or written. Relative or absolute file paths are supported explicitly or through an SREG or XPATH expression evaluated using the incoming document.
Host Directory An optional directory to be used if Name of File is not absolute.
Working Directory * The path to the iSM working directory.
Transfer Type * The direction of transfer. Select retrieve to retrieve the file from the server. Select send to send the file to the server.
400 Information Builders 1. iWay Services
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 desired name.
Delete After Read This parameter configures the action to be taken after the read. 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 the listener supports transactions. Otherwise the file is deleted immediately after the file is read. If the listener supports transactions, the file is not deleted unless the flow ends in success. Note: The connection to the SFTP server is maintained until that time. Users are strongly cautioned that use of this option within an iteration can result in a holding of connections to the server, which in turn can cause subsequent connection failures and resource buildup.
Action on Failure Determines whether an input document or status document is returned on failure.
Connection Retry Determines the attempted failed connects to the SFTP server.
Retry Interval Retry interval in seconds (allows for xxhxxmxxs format). Omit or use 0 for no retry.
Edges:
iWay Service Manager Component Reference Guide 401 Available Services
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 security violation..
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 you want to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank for default port 22.
402 Information Builders 1. iWay Services
Parameter Description
Buffer Size The size of the SFTP buffer to be used when sending or retrieving data. The default value of 32768 is used if this field is not set. A larger buffer may improve performance, but setting this field to a value greater than 65536 will default to 65536. The value must be entered as a whole number (for example, 32768, 65536). iWay recommends leaving the buffer 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 you want 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 no Provider name is specified, enter the user name and either a password or a Private Key and passphrase values (Passphrase is 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 will be accepted by this server.
Host Key Repository The path to the Known Host Keys repository on this server.
iWay Service Manager Component Reference Guide 403 Available Services
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 use as a starting location when you connect. Blank designates the login directory.
File Protect Emit a temporary name and then rename it to the desired name.
Emit Zero Bytes Allow the Emitter to transmit zero bytes to the server. This flag will 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). Omit or 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 .
404 Information Builders 1. iWay Services
Line Edge Description
OnFailSecurity Could not operate dues to a security violation..
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 you want to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank for default port 22.
Buffer Size The size of the SFTP buffer to be used when sending or retrieving data. The default value of 32768 is used if this field is not set. A larger buffer may improve performance, but setting this field to a value greater than 65536 will default to 65536. The value must be entered as a whole number (for example, 32768, 65536). iWay recommends leaving the buffer 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 you want to connect to.
Proxy Port The port to connect to on the proxy site. iWay Service Manager Component Reference Guide 405 Available Services
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 no Provider name is specified, enter the user name and either a password or a Private Key and passphrase values (Passphrase is 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 will be 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 file paths are supported through an SREG or XPATH expression evaluated using the incoming document.
File (to) The destination file to be operated on. Wild cards are accepted. Required except for delete and size exist.
File (to) a directory name File (to) references a directory. If it is unclear whether the path names a directory or a filename, the Service Manager will assume 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.
406 Information Builders 1. iWay Services
Parameter Description
Remote Size or The name of the Special Register designated to hold size (if Permissions Operation is size), or the file's octal permissions (if Operation is chmod). This field is required when the Operation is either size or chmod.
Out Document * The document returned by operation (bad input defaults to result).
Action on Failure * Determines whether an input document or status document is returned 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 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 security violation..
OnNotFound The resource was not found and this is considered an error.
iWay Service Manager Component Reference Guide 407 Available Services
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 you want to connect to.
Remote Port * The port to connect to on the SFTP site. Leave blank for default port 22.
Buffer Size The size of the SFTP buffer to be used when sending or retrieving data. The default value of 32768 is used if this field is not set. A larger buffer may improve performance, but setting this field to a value greater than 65536 will default to 65536. The value must be entered as a whole number (for example, 32768, 65536). iWay recommends leaving the buffer 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 you want 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
408 Information Builders 1. iWay Services
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 no Provider name is specified, enter the user name and either a password or a Private Key and passphrase values (Passphrase is 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 will be 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 in which to find the file name.
File Name not a The File Name is not a tag. False if the File Name is a Document Tag * document tag. Otherwise True if the File Name evaluates to a valid file name.
Base Path An optional directory to be used if the incoming name is not absolute.
Enclose Tag The name of the tag in which to enclose the data read. If omitted, 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.
iWay Service Manager Component Reference Guide 409 Available Services
Parameter Description
Delete After Read This parameter configures the action to be taken after the read. 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 the listener supports transactions. Otherwise the file is deleted immediately after the file is read. If the listener supports transactions, the file is not deleted unless the flow ends in success. Note: The connection to the SFTP server is maintained until that time. Users are strongly cautioned that use of this option within an iteration can result in a holding of connections to the server, which in turn can cause subsequent connection failures and resource buildup.
Special Register The prefix to give to any Special Register that is generated by Namespace * the agent (for example, ftp.read, sftp.read, etc.). Do not terminate the Namespace with a dot (.). That will be be done automatically by the Service Manager. If not specified, the default 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.
410 Information Builders 1. iWay Services
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 security violation..
OnNotFound The resource was not found and this is considered 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 will also 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 have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token Secret.
iWay Service Manager Component Reference Guide 411 Available Services
Parameter Description
Consumer Secret * Is your Twitter Application Consumer Secret. If you don't have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token 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.
412 Information Builders 1. iWay Services
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 operation requested.
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:
iWay Service Manager Component Reference Guide 413 Available Services
Parameter Description
Message ID Set this to control the emitted message ID. Usually this is left blank to let the system generate a unique id meeting the requirements 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 for transmission.
Compression Determines when or if the S/MIME packager should compress the message.
S/MIME Keystore The provider for the keystore used to sign and encrypt Provider messages.
S/MIME Digest JCE The JCE Provider for S/MIME Digest Cryptography services. Provider Defaults to the S/MIME Signature JCE Provider.
S/MIME Signature JCE The JCE Provider for S/MIME Signature Cryptography services. Provider *
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 is included in the message.
414 Information Builders 1. iWay Services
Parameter Description
Enforce KeyUsage Determines how the KeyUsage Extension is verified when Extension present in the certificate. The requirement for S/MIME digital signatures is followed by the requirement for S/MIME encryption, separated by a slash.
Header Management
Payload Header The special register namespace from which additional MIME Namespace headers for the payload are taken. If not supplied, no MIME headers are added beyond the content headers generated by the packaging process.
Message Header The Message Header Namespace. 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 iWay Service Manager Component Reference Guide 415 Available Services
Description: Expects input in the form of an S/MIME multipart document.
Parameters:
Parameter Description
S/MIME Keystore The provider for the keystore used to decrypt incoming Provider * messages.
S/MIME TrustStore The provider for the keystore containing the S/MIME Provider * Certificate Authorities.
S/MIME Certificate Store A comma-separated list of Keystore, Directory CertStore, or Providers LDAP providers for the certificate stores used to complete signer certificate chains when the signed message contains fewer certificates than needed.
S/MIME Signature JCE The JCE Provider for S/MIME Signature Cryptography services. Provider *
S/MIME PKIX JCE The JCE Provider for S/MIME PKIX services. If left blank, the Provider default JCE provider for PKIX will be used.
S/MIME Decryption Key The private key alias used to decrypt incoming messages Alias
S/MIME Decryption Key The password for the decryption private key. If left blank, the Password password for accessing the keystore will be used.
Enforce KeyUsage Determines how the KeyUsage Extension is verified when Extension present in the certificate. The requirement for S/MIME digital signatures is followed by the requirement for S/MIME encryption, separated by a slash.
Enable Certificate Enables CRL or OCSP checking of the signer certificates Revocation
OCSP Responder The name of the OCSP Responder provider. This verifies the status of certificates online instead of relying on Certificate Revocation Lists.
Unrecognized Certs The directory to store unrecognized certificates found in S/ Location MIME messages.
416 Information Builders 1. iWay Services
Parameter Description
Signature Required If set, incoming documents require a valid signature.
Default Content Transfer The default encoding when the Content-Transfer-Encoding is Encoding absent. For S/MIME, this is 7bit. For AS2, this must be set to binary.
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 Header The special register namespace where message headers can Namespace be found. If not supplied, HDR registers from the default namespace will be used.
Payload Header The special register namespace into which any headers on the Namespace extracted body part will be stored as HDR registers. If not supplied, body part headers will be saved in the default namespace.
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.
iWay Service Manager Component Reference Guide 417 Available Services
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 the output document. This may be especially useful to pull the body payload from a surrounding envelope with headers.
Parameters:
Parameter Description
Target 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 be an 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.
XML Namespace Provider for the mapping between XML namespace prefix and Provider namespace URI in XPath expressions. If left blank, then the XPath expression in the Target cannot contain namespaces.
XPath Syntax Determines which syntax level of XPath should be used. The default option selects the syntax level as set in the console global settings.
When snipping an XML subtree, the inherited XML namespaces from the ancestor elements are 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.
418 Information Builders 1. iWay Services
When the Target Type is XPath, the Target is an XPath expression that is evaluated against the input XML document. The result must be a single element that is moved to the root of the output document. The service returns notfound if the result is empty, or duplicate if it contains multiple elements. The XML Namespace Provider parameter is optional. When the provider is specified, 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 a depth-first search within the input XML document. The parent must contain a single child element that is moved to the root of the output document. The service returns notfound if the parent is not found or if it does not contain a child element. The service returns duplicate if the parent contains multiple child elements.
When the Target Type is Root, the Target is the name of the target element located with a depth-first search within the input XML document. The target element is moved to the root of the 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 evaluated against the input JSON document. The result must be a single JSON value that is moved to the root of the output document. The service returns notfound if the result is empty, or duplicate if it 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 node under the parent has siblings.
iWay Service Manager Component Reference Guide 419 Available Services
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 lists the 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:
420 Information Builders 1. iWay Services
This service emits data using the Sonic version of JMS to a queue or topic. For more information, 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 Manager is listening on a Sonic broker configured to listen on TCP, the format of the URL is tcp://host:port. The default TCP port on which Sonic listens is 2506. This value is configured in the Sonic broker.ini file. When Service Manager listens to Sonic, the URL is in the form of http://host:port where the HTTP port is defined in the Sonic broker.ini file.
The Sonic listener supports fail over if it is unable to reach a particular broker. You must provide a comma-separated list of broker 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 the drop-down list:
queue
topic
Output Message Type The output message type. Select one of the following options from the drop-down list:
bytes
text
dynamic
iWay Service Manager Component Reference Guide 421 Available Services
Parameter Description
Ackmode The acknowledgement mode, or transactional. Select one of the following options from the drop-down list:
auto
dupsok
client
trans
Send Persistently Support for persistent and non-persistent messages. In the event of a network or system failure, the persistent option prevents messages from being lost.
In the event of a broker or Service Manager failure, non-persistent messages are volatile. Persistent messages are saved to disk.
Load balance Determines whether to load balance among brokers. Select true or false.
Detect Determines whether to detect for duplicates. Select true or false.
Priority Priority of the message, which can also be specified using XPATH(). The default is 3.
Correlation ID Correlation ID of the message, which can also be specified using XPATH().
Preserve undelivered Determines whether to preserve undelivered documents. Select true or false.
Notify undelivered Determines whether to notify if documents are undelivered. Select true or false.
Preemitter Should any preemitter be avoided?
422 Information Builders 1. iWay Services
Parameter Description
Fault Tolerant Determines whether the listener is connecting to the Sonic Broker as 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 installed with a Sonic Fault Tolerance license code.
Sequential When multiple brokers listed, this parameter determines whether they are used sequentially or randomly. Select true or false.
Reconnect Fault Determines how long to wait (in seconds) before trying to Timeout reconnect.
Initial Connect Determines how long to wait (in seconds) after failing initially, Timeout 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
iWay Service Manager Component Reference Guide 423 Available Services
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 does not delete the message from the queue For more information on Sonic, see the Queuing Adapters 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 list used for failover). Protocols are TCP and HTTP.
User ID User ID for challenges.
Password Password for challenges
Filter Selection Filter
424 Information Builders 1. iWay Services
Parameter Description
Output Format How the output is provided. Select one of the following values from the drop-down list:
Status
Xml
Asread
Load balance Load balance among brokers. Select one of the following 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 a connection failure?) Select one of the following values from the drop-down list:
true
false
Sequential When multiple brokers are listed, they are used sequentially or randomly. Select one of the following values from the drop-down list:
true
false
Reconnect Fault Timeout In seconds, how long to wait before trying to connect again.
Initial Connect Timeout In seconds, how long to wait after failing initially, before trying to connect again.
iWay Service Manager Component Reference Guide 425 Available Services
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 more Information on Sonic, see the Queuing Adapters chapter in the iWay Service Manager Protocol Guide.
Parameters:
Parameter Description
Name The name of the queue or topic to be read.
Broker URL URL of Sonic Broker. The format of the URL is Protocol://host:port.
User ID User ID for challenges.
426 Information Builders 1. iWay Services
Parameter Description
Password Password for challenges.
Acknowledgement Acknowledgment mode, or transactional. Select one of the following options from the dropdown list:
Auto Acknowledge. The session automatically acknowledges the client receipt of a message by successfully returning from a call to receive (synchronous mode) or when the session message listener successfully returns (asynchronous mode).
Client Acknowledge. An explicit acknowledge on a message acknowledges the receipt of all messages that were produced and consumed by the session that gives the acknowledgement. When a session is forced to recover, it restarts with its first unacknowledged message.
Dups OK Acknowledge - The session slowly acknowledges the delivery of messages to consumers, possibly allowing some duplicate messages after a 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
iWay Service Manager Component Reference Guide 427 Available Services
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
428 Information Builders 1. iWay Services
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 document format 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. The default is 1414.
Channel The MQ server channel, which is needed if you are using MQ client.
Delivery Request confirmation of delivery.
Arrival Request confirmation of arrival.
iWay Service Manager Component Reference Guide 429 Available Services
Parameter Description
Report Queue The name of the report queue. Required if COA or COD is requested or msgtype is response.
Priority Priority of message, which can be specified using XPATH(). The default 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 is unlimited.
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 Local If the listener is a transaction manager, should this emit be rolled Transaction? back if the transaction fails?
Call at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default value is false.
430 Information Builders 1. iWay Services
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.
iWay Service Manager Component Reference Guide 431 Available Services
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 a process that is being run from a splitting preparser. The batch inserter uses SQL batch operations where supported to update the database efficiently. The actual performance can be influenced by the blocking factors configured for this service and the blocking factors implemented on the database.
The inserts will be queued and issued to the database in groups, depending on the configuration. Any outstanding inserts will be issued upon successful completion of the process flow. The process flow must be configured to operate under local channel transaction control.
432 Information Builders 1. iWay Services
When the SQL Batch Row Insert service is used in an iteration process, your application process flow must inform the service that the iteration has completed. Otherwise, the SQL Batch 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 (for example, XML Split Iterator) provide a special service that must be configured to cause this notification to be made. This service takes the form of an end of iteration message that passes out of the iterator on the end_iteration edge. This is a custom edge that you must configure in your process flow. It should pass into the SQL Batch Row Insert service through a Junction 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 of insertions into the database.
Parameters:
Parameter Description
Output document type Determines whether this service generates a status document or passes the input document to the process flow. Select one of the following 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. The insert operation will be performed on this database.
Output SQL * The Data Manipulation Language (DML) statement used to perform the insert into the database. Use the ?name parameter format that is used for the SQL service.
Batch Size The number of statements in a batch. Enter zero (0) if all inserts are to be considered as one batch. If a value is entered, sub- batches may result, where commits are performed on the batch when the number of inserts reaches the specified value. The default batch size is zero (0).
iWay Service Manager Component Reference Guide 433 Available Services
Parameter Description
Commit Sub-batches If sub-batches are requested, this parameter determines whether they should be committed as they update. The default value is set to false.
Fail First If set to true and the first row of the first batch fails, then the operation is terminated with a fail_insert edge. This usually indicates that the database cannot be reached or an insert cannot be performed for some reason. If this is omitted, then the generated status document will indicate which rows were successfully inserted. By default, false is selected.
Fail Count If greater than 0, if the specified number of inserts fail, the operation terminates on the fail_insert edge. The default value is 0.
Omit Test Performs the specified iFL operation. If the operation returns a result 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 key and time to extract the key.
434 Information Builders 1. iWay Services
Parameter Description
Out Encoding The Internet Assigned Numbers Authority (IANA) character set to be used for the output database. Select one of the following character 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 batch size was reached, then the batch operation was completed successfully.
cancelled A cancel was recognized.
fail_parse The parameters could not be parsed.
fail_connect A connection to the provider failed.
fail_connect_destinati A connection to the output database failed. on
iWay Service Manager Component Reference Guide 435 Available Services
Edge Description
fail_operation The insert operation failed to execute for some reason other than the error that is reported by the database. For example, the insert statement could not be formatted.
fail_insert Failed on the actual commit if the number of invalid inserts exceeded 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 XML message. 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 the process 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 for the next row. The SQL insert service could have anchored the loop, but using a move service is a 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 iterator sends the end of iteration message on the end_iteration edge. This edge can be wired into the Junction object that leads to the inserter. Naturally, other logic can also appear on either edge from the iterator. When control returns to the iterator, control is passed to the End node. As the 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 a successful completion of the process flow. If the process is not running in a transactional mode, then the commit will be performed immediately.
If you have configured to commit on sub-batches, then it is possible that a transactional rollback will not avoid updating the database. Also, the behavior in the event of an error may differ amongst databases and drivers themselves.
436 Information Builders 1. iWay Services
For very simple types of insert operations, where no processing is to be done on the message other than simply inserting it, you can wire the end_iteration and the success edge to the same 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 separate the edges so that the intermediate services (for example, the Transform object in the following image) need not see the end of the iteration message.
The status document includes the error information. The type and specific error descriptions vary depending upon the capabilities of the specific JDBC driver currently in use.
iWay Service Manager Component Reference Guide 437 Available Services
SQL Service (com.ibi.agents.XDSQLAgent) Syntax:
com.ibi.agents.XDSQLAgent
iIT Service Object:
SQL: SQL Agent
438 Information Builders 1. iWay Services
Description:
The SQL Service enables you to execute an arbitrary SQL statement, specified as a service configuration parameter. The service returns an EDA response document, as defined elsewhere. This service differs from the more complete RDBMS services and adapters in that it does not interrogate an iWay response document to obtain its SQL. Instead, it accepts the SQL as a configuration parameter and modifies the statement based on the current document or environment. The SQL expression can be modified during execution by iWay standard parameter expressions.
Using the SQL service instead of the RDBMS Adapter is preferred in cases where dynamically built queries are processed or when simple (non-looping) SQL statements need to be processed quickly. This service also provides conditional transactionality support, multi-part transactional support, advanced SQL language capabilities, and error-handing features.
Parameters:
Parameter Description
SQL DML * The SQL Data Manipulation Language (DML) statement, which can also evaluate an iFL expression to build an SQL statement dynamically. For example, inserting SREG(value) into the text of your query.
Evaluate SQL If set to true, an attempt is made to treat the SQL as an expression. 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, and produces 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.
iWay Service Manager Component Reference Guide 439 Available Services
Parameter Description
Use JNDI * If set to true, a connection from a data source accessed through JNDI is used. Otherwise, connect directly using JDBC driver manager. When set to true, the Pool Connections configuration parameter should not be used, and pooling is handled in the JNDI data source manager.
JNDI Name JNDI name for the requested data source. To use an iWay JDBC provider, specify as jdbc/provider. This is required if you are using JNDI.
JNDI Factory JNDI initial context factory class. Leave blank for default.
Transaction Isolation Transaction isolation level to be set if possible. Level These are the standard transaction Isolation levels defined in the ANSI/ISO SQL standard. For more information on these settings, see the DBMS, JDBC, or ODBC documentation. Based on standard terminology, the following transaction isolation levels can be selected:
As Is. Does not change the transaction isolation level. The default is accepted, as it is found on the connection.
Read Uncommitted. Allows reading of a record that may be rolled back later. Dirty reads, nonrepeatable reads, and phantom reads are possible.
Read Committed. Dirty reads are not possible, but nonrepeatable reads and phantom reads are possible.
Repeatable Read. Dirty reads and nonrepeatable reads are not possible, but phantom reads are possible.
Serializable. This is the highest level of isolation. Phantom reads are not possible. Other users are prevented from updating or inserting rows into the data set until the transaction is completed.
For more information on the terminology related to transaction isolation, see Transaction Isolation Terminology on page 707.
440 Information Builders 1. iWay Services
Parameter Description
Pool Connections If set to true, connections are pooled. The default value is false.
Applies to non-local transactions only. This pools connections within the flow itself. Connections can be reused across messages, depending on the commit strategy and the specifics of the database being used. If used with JNDI data sources, this local service pooling may inhibit optimum use of any JNDI data source pooling and connection management. In most cases, the Pool Connections parameter for this service should not be set when using JNDI data sources.
Pooled connections are identified by connection URL and user ID. The pooled connection is shared by all instances of this service either within the channel as a whole or within a single execution (worker) thread. To pool at the worker level, set the Need Commit parameter to true.
In local transactions, connections are always shared within the transaction.
Attempt Read Only For select set JDBC read only flag. Some drivers cannot handle this optimization and can give security failures.
Connection Properties Properties to apply to a connection.
iWay Service Manager Component Reference Guide 441 Available Services
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 of the Data Manipulation Language (DML) execution, regardless of 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 or rollback will be performed on the connection depending on the completion status of the process flow. If the process is not running in a local transaction, this defaults to the Immediate option.
Never. No commit is ever issued by the service for this statement. This is the default for a select statement. For a DML that requires a commit, the process flow is responsible for committing the connection by use of DML in another service. This gives the transaction complete control and responsibility for the commit or rollback. A commit or rollback is not executed by the use of the Commit service or by the transactional status of the process flow.
Force. Always issue a commit before closing the connection. Use only in non-transactional mode. Setting the Force option is required only for certain JDBC drivers that require a commit in order to close all resources. For example, some DB2 drivers will generate an error if a connection is closed without a commit. For other drivers, issuing a commit with no outstanding work can generate an error. Users are cautioned to only use the Force option if it is required by your driver and application design.
442 Information Builders 1. iWay Services
Parameter Description
Note: Prior to iSM version 6.1.4, the Boolean values true (Immediate) and false (Transactional) were provided as options for this parameter. These internal settings continue to perform as in previous releases.
Users are cautioned that commits are issued on connections, rather than statements. Selecting the Never option delegates application responsibility for the connection to the application rather than the transaction manager of the process flow. Failure to execute an SQL service with never having a COMMIT WORK or ROLLBACK WORK (as appropriate for the specific database), will leave the connection uncommitted.
For DML-based statements with the Never option selected, you will require pooling enabled to insure that the TCL (Transaction Control Language) affects the proper connection. Pooling is automatic when using JNDI-based connections.
Timeout Number of seconds this service will wait for an operation to complete. 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 Rows group.
Sibling documents are full documents that are chained to the emitted document from the service. They can be accessed by use of an iterator, and will be emitted automatically if they exist for the 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.
iWay Service Manager Component Reference Guide 443 Available Services
Parameter Description
xLOB Handling Determines how blobs and clobs should be handled. Select one of the 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 statement are 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 short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called 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 named tokens to represent the values to be used in the statement. For example: Select name, address from addresses where zip='?zipval' and state = '? stateval'
444 Information Builders 1. iWay Services
Then in the user properties, represent the values as name/value token pairs, as listed in the following 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 OUT parameters. To use a stored procedure with output parameters, you must describe each output parameter that is expected. The values returned by these parameters are stored in the response 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 iWay Service Manager Component Reference Guide 445 Available Services
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) and receive 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 a result set.
A stored procedure that uses an input parameter might accept a partial key, and return the complete 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, and the value will also appear as an output parameter.
Examples of using out and IN OUT parameters with stored procedures are provided in Examples of 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 token pairs to represent the values.
Name Value
first _sreg('firstname')
middle _qval(_sreg('middle'),'\','empty')
446 Information Builders 1. iWay Services
Name Value
last _sreg('lastname')
If a middle name is not present, then the text NULL is used in the SQL. Otherwise, the quoted string of the middle name is used.
Edges:
The SQL service (and by extension the SQL object used in process flows) returns edges that can be used to analyze execution results at any required level of granularity. Any SQL service failure returns a fail_operation edge, but a duplicate or a missing result can also be used. At the 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 following table.
Edge XOPEN Description
success 00000 The operation was successful. For SELECT operations, success can be considered as the join of found and notfound edges.
found 00000 Rows were returned. Always issued in conjunction with the success edge. You may wire found or success edges depending on your application requirements.
notfound 00000 No rows were returned. You may wire notfound or success edges depending on your application requirements.
Note: The notfound edge indicates a successful operation, as distinct from the fail_notfound edge, which indicates that some components, such as a table or column, is not found in the database.
iWay Service Manager Component Reference Guide 447 Available Services
Edge XOPEN Description
duplicate 3C000, 42S01, Some item is duplicated, for example, 42S11, 42S21 insert to an existing unique key.
fail_notfound 42S02, 42S12, A component required in the DML, such 42S22 as 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, The operation times out on the channel. 40001
fail_parse Parameters cannot be parsed in iFL.
fail_syntax 4200, 22007 The SQL had syntax errors as reported by the DBMS.
fail_other The SQL operation has failed for a reason that is not included in any other edge (for example, fail_notfound). You can use the sqlcode special register for further analysis.
For more information on SQL Service edge returns sorted by XOPEN code, see SQL Service Edge 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 number of rows affected by an UPDATE or DELETE operation.
iway.genkey Generated key associated with an INSERT operation, if appropriate to the database.
448 Information Builders 1. iWay Services
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 three formats:
Field
Column
Row
iWay Service Manager Component Reference Guide 449 Available Services
Field format is designed for efficient XPath. Within each row, the fields are presented as children. For example:
450 Information Builders 1. iWay Services
Column format is often effective for transformations. For example:
iWay Service Manager Component Reference Guide 451 Available Services
Row format was originally designed for extremely fast retrieval, but your application is responsible for extracting information for the rows through string manipulation. This format matches the format returned by the EDA API of the Full Function Server, and should only be used with that database. iWay Software does not recommend this format for most general applications.
Examples of Using the SQL Service With Stored Procedure Calls and Output Parameters When using the SQL Service to execute any stored procedure with parameters, iWay Software recommends that the service be configured to use the bind issuance strategy. However, when a 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 as output values:
452 Information Builders 1. iWay Services
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. In the response document, the value of this parameter can be identified from its index.
?date An output parameter of type date. Again, no name is specified, but the resulting value can be identified from the index of the parameter.
iWay Service Manager Component Reference Guide 453 Available Services
If the procedure executes successfully, the SQL Service will generate the following type of response document:
Note: The value of the index attribute on the outparm elements refers to the index of the parameter 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 OUT parameter of type varchar. For input, you will bind the value of the user parameter name and you will also use name to identify the output of this parameter in the response document. An IN OUT parameter must be defined with a name.
454 Information Builders 1. iWay Services
If the procedure executes successfully, the SQL Service will generate the following type of response document:
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 parameter mytid, evaluated at execution time, will be bound.
?? An output parameter that will have the cursor datatype and be $cursor.tidresult identified in the response document as tidresult.
iWay Service Manager Component Reference Guide 455 Available Services
If the service succeeds in executing the procedure and is configured to output its result in column format, then the service will generate the following type of response document:
456 Information Builders 1. iWay Services
Note: The resultset is formatted in exactly the same way as if it had been returned from a SELECT statement, except that it becomes a child of the outparm element. Also, note that the name attribute of the output element holds the out parameter name as specified in the SQL DML.
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 want to 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 the default 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 following range 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 FTP server. iWay Service Manager Component Reference Guide 457 Available Services
Parameter Description
Sregs
Type of variable The type of variable (headers appear in emitted documents as header 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 you want 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).
458 Information Builders 1. iWay Services
Parameter Description
Security Protocol Security protocol.
SSL - Supports some version of SSL. May support other versions.
SSLv2 - Supports SSL version 2 or higher.
SSLv3 - Supports SSL version 3. May support other versions.
TLS - Supports some version of TLS. May support other versions.
TLSv1 - Supports TLS version 1. May support other versions.
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 to Implicit Security.
explicit - In order to establish the SSL link, explicit security requires that the FTP client issue a specific command to the FTP server after establishing a connection. The default FTP server port is used.
implicit - Implicit security automatically begins with an SSL connection as soon as the FTP client connects to an FTP server. In implicit security, the FTP server defines a specific port for the client (typically 990) to be used for secure connections.
iWay Service Manager Component Reference Guide 459 Available Services
Parameter Description
Keystore File or Security The full path to the Keystore file, which provides certificate Provider material to be used for SSL connection, the name of the Security Provider, or leave blank to use the configured default Security Provider.
Keystore Password The password to access Keystore file. Not needed if Keystore File or Security Provider is the name of a Security Provider.
Keystore Type The type of the Keystore. Not needed if the Keystore File or Security Provider is the name of a Security Provider.
Edges:
The following table lists the available Line Edges for the SREG FTP: Pass register settings to iWay 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 security violation..
SREG Insert Service (com.ibi.agents.XDSregInsertToDocAgent) Syntax: com.ibi.agents.XDSregInsertToDocAgent
460 Information Builders 1. iWay Services
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 namespace for a group of registers and insert them as elements under the specified node. Special register names and values will be inserted as attributes. You can use this service if you need to insert a number of elements into your document, but you do not initially know how many of them will be 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
iWay Service Manager Component Reference Guide 461 Available Services
Line Edge Description
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
none
one
many
Example:
The following is a sample input document:
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
462 Information Builders 1. iWay Services
The following special registers are defined:
mysregs.first = one
mysregs.second = two
mysregs.third = three
The following is a sample output document:
If running it with
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 a copy 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. iWay Service Manager Component Reference Guide 463 Available Services
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 of these parameters offers the [listener] and [default] options which are interpreted as described above.
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] from the drop-down list to receive the values configured on the listener.
To Namespace Copy/move to namespace. Select [listener-xx] from the drop-down list 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
464 Information Builders 1. iWay Services
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 restricted character conventions. In many cases the namespace portion of the name will be removed for use 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 a special 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 in the named register.
Load from register restores it.
iWay Service Manager Component Reference Guide 465 Available Services
Parameter Description
Level * Payload addresses only the message information.
Full document includes all state information such as addresses, error status, etc.
Clear * Determines on load whether the register should be cleared after loading.
No Activity Log * If set, this register will not be logged in an activity log (some drivers may not respect this setting).
No Marshal * If set, this register will not be marshalled for transfer via, for example, gateway, pending storage, or AFTI.
Edges:
The following table lists the available Line Edges for the SREG: Save/Restore Document Value Service (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 is considered 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.
466 Information Builders 1. iWay Services
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 be an 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 a special register, or load document subtree from a special register.
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 a resource. This may or may not be a failure.
OnNotFound The resource was not found and this is considered an error.
OnFailedOperation Could not perform the operation requested.
iWay Service Manager Component Reference Guide 467 Available Services
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 SREGs can be set to any of the supported scopes (Message, Flow, or Thread) and can belong to any defined category (Header, User, or Document).
Setting SREGs above the Message scope requires specification of a lock to avoid race conditions in a multithreading situation.
Parameters:
Parameter Description
Type of variable Type of variable (headers appear in emitted documents as header values). Select one of the following options from the drop-down list:
User. This variable is part of the process flow logic and is the most 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 routing information, such as an HTTP header or an IBM MQSeries descriptor.
Metric. This variable is used to maintain statistics at the server or channel (protocol) level. For example, the maximum value of transactions received or the number of errors of a certain type.
Delete. This variable indicates the removal of the register set that is used in a process flow.
468 Information Builders 1. iWay Services
Parameter Description
Scope of variable For process flows, scope can be for all nodes or only nodes forward on this edge. Select one of the following options from the drop-down list:
Message
Flow
Thread
Channel
Server
Flow- and message-scoped variables have one shared copy for the entire process flow. Therefore, a change made to the variable will be seen on all parallel paths. Unless various points of the parallel process flows are synchronized, the results that are written to a global variable may leave the variable with an unpredictable value.
Flow-scoped variables are deleted at the termination of the process flow (or sub-flow) in which they are declared. If you need a variable to be available to the calling process flow (parent flow) or to subsequent components, such as outlets and emitters, select Message as the scope.
Thread-scoped variables are duplicated for each parallel document path, allowing independent manipulation of each copy. After parallel paths converge at a Join object, the value of the thread is undefined.
Channel-scoped variables are at the protocol level and can be used in a metric to keep information across workers. Registers with a channel scope require a lock.
Server-scoped variables are above the channel level and can keep metrics across the entire server. Registers with a server scope require a lock.
iWay Service Manager Component Reference Guide 469 Available Services
Parameter Description
Lock A lock is a name that applies to one or more metrics being updated or referenced as a whole. This allows synchronous values to be retained. For example, if metrics A and B are updated, it is a good practice to keep their settings in the same relationship to one another. You do not want to change them in such a way that metrics A and B are no longer related.
Automatic Causes contents to be evaluated to hold functions. Select one of evaluation the 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 is stored.
To summarize, if you select false, the expression is not evaluated upon storage into the SREG. If you select true, the contents of the SREG are evaluated every time it is retrieved.
For expressions that have different results at different times, this offers 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 document itself, the result will always be NULL because access to “the document” is not available.
Call at EOS? In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default value is false.
470 Information Builders 1. iWay Services
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 specific parameter, such as an XPath value. For example, you need to run a transformation on a document, but also want to capture the document first by saving it in a SREG value. In the event of an error during the transformation, you can provide the original document that caused the error.
iWay Service Manager Component Reference Guide 471 Available Services
The service can be invoked using the typical parameter values, as shown in the following image:
472 Information Builders 1. iWay Services
The user-defined parameters pane is where the SREGs must be defined, as shown in the following image:
The SREGs are evaluated in the order they are defined in the pane. Therefore, one SREG can refer 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 process flow.
The following SREG types are supported:
Boolean. Boolean values (true or false).
Duration. Date/time value.
Decimal. Decimal number value.
Integer. Integer number value.
iWay Service Manager Component Reference Guide 473 Available Services
Password. Password (masked) text value.
String. String text value.
Note: Register names must conform to the requirements used for XML element names. The names are further restricted for HDR registers if the register will be used to form a message header for a protocol that itself has restricted character conventions. Use of the namespace designator '.' 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 any errors in the generated SWIFT document. For more information, see the iWay Integration Solution 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
474 Information Builders 1. iWay Services
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
iWay Service Manager Component Reference Guide 475 Available Services
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 any errors in the SWIFT document that is received. For more information, see the iWay Integration Solution 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.
476 Information Builders 1. iWay Services
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.
iWay Service Manager Component Reference Guide 477 Available Services
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:
478 Information Builders 1. iWay Services
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 with the 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 of this 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 iWay Service Manager Component Reference Guide 479 Available Services
Line Edge Description
OnCustom OnError
OnSuccess
OnFailure
Example:
480 Information Builders 1. iWay Services
A simple way to test your TCP emitted messages is to configure another running channel with a TCP listener and an appropriate emitter (for example, a File emitter) to consume the messages that are emitted by the service. The following image is an example of configuration settings for a TCP listener:
After deploying and starting the channel with the TCP listener and File emitter, you can test run your process flow containing the TCP Emit service object. You must supply an incoming document that contains the appropriate content. For example, HTML:
If the service runs successfully, the TCP listener picks up the sample HTML document that is emitted by the TCP Emit service. The HTML document is then received in the destination folder that is specified for the File emitter.
TIBCO RV Emit Service (com.ibi.agents.XDTIBRVEmitAgent) Syntax: iWay Service Manager Component Reference Guide 481 Available Services
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. For more 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 the following options from the drop-down list:
true
false (default)
Timeout Maximum time to wait for the answer (in seconds), -1 means infinite wait.
482 Information Builders 1. iWay Services
Parameter Description
Data Type Reads a file and returns the read result. Select one of the following options from the drop-down list:
Opaque (default)
String
TibrvMsg
TibrvXml
Preemitter Determines whether any preemitter should be avoided. Select one of the 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
iWay Service Manager Component Reference Guide 483 Available Services
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 accumulates messages to record the progress of activity within the server. Usually the trace log is used for debugging 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 the message will be logged in the standard logger category. If specified, then the name provided will appear as the log message category.
484 Information Builders 1. iWay Services
Parameter Description
Isolate Category Applies only for error messages with a category name. Logger A trace to a named category logger is never deferred. By default, an error trace is considered a general error causing a reset of the defer mode of the standard logger. If isolated, then a category logger is considered independent and the defer mode of the standard logger is not affected. If the standard logger is not in defer mode, then this parameter 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 short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message.
The following table lists and describes the edges that are returned by the Trace Message Writer 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 system must be configured to accept the message on the issued level. Users must be made aware that the use of a trace log can adversely affect server performance.
iWay Service Manager Component Reference Guide 485 Available Services
Caution: The trace log is not the transaction log, which can hold messages regarding operations within the server. Messages can be written to the transaction log using the Activity Log Entry service (XDXALogEvent) and the Activity Log Business Error Message service (XDXALogBizErr). While trace messages are usually free format and designed to help debug a problem, the XALog (transaction log) is more structured and often has externally imposed security, 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 local transaction. These process flows can include compensating logic when an application interacts with 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. This process flow must be published to the system level of the current configuration.
Commit Flow Process flow to execute if the local transaction is committed. This process flow must be published to the system level of the current configuration.
486 Information Builders 1. iWay Services
Services capable of supporting transaction commit/rollback in a process flow automatically respond the success of failure of the process flow as a whole by issuing a commit or rollback accordingly. Examples of such services are the SQL service, MQ Read service, and the MQ Emit service. Other services do not so respond to commit or rollback, either because the underlying service (for example, a Siebel system) does not support transactionality or the operation required must rely on application logic. In such a situation, your flow can register a process flow to be run at transaction commit/rollback (end of the process flow) appropriate to the 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 the XDTxAgent. 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 the registration service registered the event flow.
You can also enter user variables (Special Registers) to the service, which will be available as flow-level registers when the commit or rollback event flow is invoked. The value seen by the process 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 Registration Service (com.ibi.agents.XDTxAgent).
Line Edge Description
OnError Error
OnSuccess Success
OnFailure Failure
OnCustom OnError
OnSuccess
OnFailure
fail_parse
fail_notfound
iWay Service Manager Component Reference Guide 487 Available Services
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 an alias specified in the transforms section of the engine configuration. The transformation can be an iWay transform or an XSLT transform. The transform service is especially useful as part of a sequence of business services in which the output is chained to another business service to execute a business process.
Note: The Transform service is only used to call a transform dynamically. Otherwise, you must configure a Transform object using iIT Designer. In order for a transform to be called properly during run time, the transform must be contained in a process flow, which is deployed as a service.
Parameters:
Parameter Description
Transform name * The name of the defined transform to execute.
488 Information Builders 1. iWay Services
Parameter Description
Expected input The type of document to reach this service. The actual input format must match the type that is declared. Select one of the following options:
All Types (default). Any payload received by the service is passed 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 iWay error status document, which will be rejected.
iWay Error. Only an iWay error status document will be accepted. Other payloads will be rejected.
All XML. Any XML payload (including the iWay error format) is accepted. Only flat formats are rejected.
Document type Type of output document being emitted by the transform. Select one 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 before transformation. By default, this parameter is set to false.
Error Status Output Sets the output format that is emitted by the service if an error occurs. Select one of the following options:
status (default). Sets the output format as an error status document.
input. Sets the output format as the input document.
iWay Service Manager Component Reference Guide 489 Available Services
Parameter Description
Call at EOS In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document is processed, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. By default, this parameter is set to false.
Error Masks
Input Side If set to true, all non-fatal errors that occur during transform input parsing are suppressed. By default, this parameter is set to false.
Output Side If set to true, all non-fatal errors that occur during transform output parsing are suppressed. By default, this parameter is set to 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 Status Output parameter and follows the fail_transform edge instead.
490 Information Builders 1. iWay Services
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 input transform format.
The following is an example of an error status document that is returned:
Tree Evaluator Service (com.ibi.agents.EvalWalk) Syntax:
com.ibi.agents.EvalWalk
iIT Service Object:
document: Tree Evaluator iWay Service Manager Component Reference Guide 491 Available Services
sreg: Tree Evaluator
transform: Tree Evaluator
Description:
This service passes an incoming XML tree and applies iFL evaluation to all or selected nodes of the tree. Element values and their attributes are evaluated.
Parameters:
Parameter Description
Filter Expression An XPath expression (optional) used to select items to be evaluated. If no value is provided, then all element values and their attributes will be evaluated.
XML Namespace Map Provider used to map between an XML namespace prefix and a Provider namespace URI. If no value is provided, then elements in the document 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-down list.
Default. Selects the syntax level as specified in the General Settings section of the iSM Administration Console.
iWay abbreviated syntax. iWay implementation is fast, but has limited language support.
Full XPath 1.0 syntax. XPath 1.0 provides full language support, 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.
492 Information Builders 1. iWay Services
Edge Description
fail_parse The service configuration or the incoming XML tree contains invalid iFL.
fail_operation The incoming document is not in XML format, or the required namespace provider cannot be located.
Example 1:
The following node, if selected for evaluation:
might become:
Example 2:
The following node, if selected for evaluation:
might become:
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.
iWay Service Manager Component Reference Guide 493 Available Services
Parameters:
Parameter Description
Host The host name or IP address of the machine to which the UDP message packet will be sent.
Port The port number of the host to which the UDP message packet will be sent.
Prepend Packet Determines whether to prepend the data packet length. Select Length one of the following values from the drop-down list.
true. The UDP message packet will contain a length prefix. The emitter calculates the binary length of the message. This length is exclusive of the four byte packet length. The length is then prepended to the packet.
false. The UDP message packet will not contain a length prefix.
By default, false is selected.
Note: Due to the nature of UDP, the only error checking that is performed is whether the host machine can be reached. Message packets are sent to the host with no guarantee that the packet 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) is automatically unmarshaled by the server, so that no application action is required. In some cases, the marshaled message must be specifically unmarshaled. These include the use of encryption in the marshaling process and the acquisition of a marshaled message through a channel other than a listener.
494 Information Builders 1. iWay Services
Note: This service is packaged with the iwgateway.jar extension.
Parameters:
Parameter Description
Use Encryption Determines whether the marshaled message will be encrypted. A secure AES cipher is used and must be deciphered by the receiver using the Unmarshal service. Automatic unmarshaling cannot be performed on an encrypted message.
AES Key A cipher key shared between the marshal and unmarshal services. 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, or unmarshaled.
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.
iWay Service Manager Component Reference Guide 495 Available Services
Parameters:
Parameter Description
Correlation ID * The identifier for the correlated process. Normally a runtime function such as XPATH() or SREG().
Namespace Namespace for the correlation ID. IDs will normally be unique within 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 correlated process.
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
496 Information Builders 1. iWay Services
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 Service Manager. 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 can specify 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 necessarily represent 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 on your agility in cutting, pasting, saving, and decoding using WinZip. Enjoy!
iWay Service Manager Component Reference Guide 497 Available Services
The output document appears as shown below: begin 666 encoded.txt M5&5S="$-"@T*1V5N=&QE(%)E861E If no element matches the Restricted XPath expression and Create Parent Element is true, then the necessary elements and attributes will be created so that the expression would match successfully. KeyInfo Include Signing Certificate Indicates whether the signing certificate should be included in a ds:X509Certificate element within ds:KeyInfo. Include Public Key Indicates whether a ds:KeyValue element containing the public key's value should be included in ds:KeyInfo. Qualifying Properties iWay Service Manager Component Reference Guide 515 Available Services Parameter Description All Signed Data Objects The commitment type that applies to all the signed data Commitment objects. All Signed Data Objects The text description for the commitment type that applies to Commitment Description all the signed data objects. A default English description will be used if a standard commitment type is chosen and this property is left blank. All Signed Data Objects Adds a time stamp computed before the signature production, Time Stamp over the sequence formed by ALL the Reference elements within the SignedInfo referencing whatever the signer wants to sign except the SignedProperties element. Sign Signing Certificate Indicates whether the signature should cover the ds:X509Certificate element containing the signing certificate. This is only considered if Include Signing Certificate is selected. Signing Time Specifies the time at which the signer purportedly performed the 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 time stamps. Signature Production Place City The purported city where the signer was at the time of signature creation. State Or Province The purported state or province where the signer was at the time of signature creation. Postal Code The purported postal code where the signer was at the time of signature creation. Country The purported country where the signer was at the time of signature creation. Signature Policy 516 Information Builders 1. iWay Services Parameter Description Signature Policy Identifier An Object Identifier that uniquely identifies a specific version of the signature policy. Leave this property blank to specify an Implied policy in XAdES-EPES form and above. Signature Policy The path to the file containing a copy of the Signature Policy Document Document. Leave this property blank to specify an Implied policy in XAdES-EPES form and above. Complete Form TrustStore Provider The provider for the keystore containing the Certificate Authorities. This property is required for XAdES-C forms and above. Certificate Store Providers A comma-separated list of Keystore, Directory CertStore, or LDAP providers for the certificate stores used to retrieve revocation material. This property is required for XAdES-C forms and above. Reference 1 Reference 1 URI The URI to the first piece of data that will be digested and signed. If left blank, the whole XML document will be digested and signed. Reference 1 Transform 1 The first transform algorithm to apply to the first reference data. Reference 1 Transform 1 The parameters for the first transform algorithm to apply to the Parameters first reference data. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes. For XSLT, this is the name of a defined transform. For XPathFilter, this is an XPath expression. Reference 1 Transform 1 The provider for the XML Namespace Map for XPathFilter XML Namespace Provider transforms. Reference 1 Transform 2 The second transform algorithm to apply to the first reference data. iWay Service Manager Component Reference Guide 517 Available Services Parameter Description Reference 1 Transform 2 The parameters for the second transform algorithm to apply to Parameters the first reference data. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes. For XSLT, this is the name of a defined transform. For XPathFilter, this is an XPath expression. Reference 1 Transform 2 The provider for the XML Namespace Map for XPathFilter XML Namespace Provider transforms. Reference 1 MimeType The MimeType element of the DataObjectFormat. Indicates how a human should interpret the signed data in the first reference (text, sound, video, etc.) Reference 1 Encoding The Encoding element of the DataObjectFormat. Indicates the encoding of the signed data in the first reference. Ignored if MimeType is left blank. Reference 1 Description The Description element of the DataObjectFormat. Holds textual information related to the signed data in the first reference. Ignored if MimeType is left blank. Reference 1 A DocumentationReference sub-element of the ObjectIdentifier Documentation URI element of the DataObjectFormat. Points to a document where additional information about the nature of the data object can be found. Ignored if MimeType is left blank. Reference 1 Identifier The Identifier sub-element of the ObjectIdentifier element of the DataObjectFormat. Contains a permanent identifier of the nature of the object. Ignored if MimeType is left blank. Reference 1 Commitment The commitment type that applies to this signed data object. Reference 1 Commitment The text description for the commitment type that applies to Description this signed data object. A default English description will be used if a standard commitment type is chosen and this property is left blank. 518 Information Builders 1. iWay Services Parameter Description Reference 1 Time Stamp Requests a time stamp to be computed before the signature production, over a sequence formed by some of the ds:Reference elements within the ds:SignedInfo referencing whatever the signer wants to sign except the SignedProperties element. Reference 2 Reference 2 URI The URI to the second piece of data that will be digested and signed. If you need more references, create user parameters named 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. For example, ref3transform2 is the second transform of the third reference. Reference 2 Transform 1 The first transform algorithm to apply to the second reference data. Reference 2 Transform 1 The parameters for the first transform algorithm to apply to the Parameters second reference data. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes. For XSLT, this is the name of a defined transform. For XPathFilter, this is an XPath expression. Reference 2 Transform 1 The provider for the XML Namespace Map for XPathFilter XML Namespace Provider transforms. Reference 2 Transform 2 The second transform algorithm to apply to the second reference data. Reference 2 Transform 2 The parameters for the second transform algorithm to apply to Parameters the second reference data. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes. For XSLT, this is the name of a defined transform. For XPathFilter, this is an XPath expression. iWay Service Manager Component Reference Guide 519 Available Services Parameter Description Reference 2 Transform 2 The provider for the XML Namespace Map for XPathFilter XML Namespace Provider transforms. Reference 2 MimeType The MimeType element of the DataObjectFormat. Indicates how a human should interpret the signed data in the second reference (text, sound, video, etc.) Reference 2 Encoding The Encoding element of the DataObjectFormat. Indicates the encoding of the signed data in the second reference. Ignored if MimeType is left blank. Reference 2 Description The Description element of the DataObjectFormat. Holds textual information related to the signed data in the second reference. Reference 2 A DocumentationReference sub-element of the ObjectIdentifier Documentation URI element of the DataObjectFormat. Points to a document where additional information about the nature of the data object can be found. Reference 2 Identifier The Identifier sub-element of the ObjectIdentifier element of the DataObjectFormat. Contains a permanent identifier of the nature of the object. Reference 2 Commitment The commitment type that applies to this signed data object. Reference 2 Commitment The text description for the commitment type that applies to Description this signed data object. A default English description will be used if a standard commitment type is chosen and this property is left blank. Reference 2 Time Stamp Requests a time stamp to be computed before the signature production, over a sequence formed by some of the ds:Reference elements within the ds:SignedInfo referencing whatever the signer wants to sign except the SignedProperties element. Edges: 520 Information Builders 1. iWay Services 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 namespace prefix and the namespace URI. If left blank, the XPath expression in the Signature Element Path and Required Signature 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 the console global settings. iWay Service Manager Component Reference Guide 521 Available Services Parameter Description Signature Element Path The path to the signature XML element. If left blank, the agent will search throughout the document for an element named Signature in the namespace http://www.w3.org/2000/09/ xmldsig#. Remove Security Parent After successful verification, determines whether to remove Element the WSSE Security parent element and all of its contents. Signature Criteria TrustStore Provider * The provider for the keystore containing the Certificate Authorities. Certificate Store Providers A comma-separated list of Keystore, Directory CertStore, or LDAP providers for the certificate stores used to complete the certificate chain and to retrieve revocation material. Enable Certificate Enables CRL checking of signer certificates. Revocation Maximum Path Length The maximum number of non-self-issued intermediate certificates that may exist in a certification path. The last certificate in a certification path is not included in this limit. 0 implies that the path can only contain a single certificate. -1 implies that there is no maximum. If any of the CA certificates contain the BasicConstraintsExtension, the value of the pathLenConstraint field of the extension overrides the Maximum Path Length parameter. Enforce KeyUsage Determines how the KeyUsage Extension is verified when Extension present in the signer certificate. Message Digest JCE The JCE Provider for the MessageDigest service. Provider Required Signature An XPath expression that returns a NodeSet, where each node Coverage in the set must have been signed by the Signature to be considered valid. 522 Information Builders 1. iWay Services Parameter Description Unsigned Attachment The action to perform when a document contains an unsigned attachment. XAdES Criteria Minimum XAdES Form Specifies the minimum acceptable XAdES form. Signatures simpler than this form will cause a validation failure. Signature Policy Provider The name of a Signature Policy Provider. This specifies the mapping from ObjectIdentifier (URI or OID) to the policy file. The policy file is needed to verify signatures with an explicit policy. If left blank, only absent or implied policies can be validated. Accept Implied Policy Indicates whether the verifier should accept an implied signature policy. Accept Unknown Indicates whether the verifier should accept unknown Properties properties. 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. iWay Service Manager Component Reference Guide 523 Available Services 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 authenticating user 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 than or equal to 200. Since Id * Returns results with an ID greater than (that is, more recent than) the specified ID. Max Id * Returns results with under an Max ID. Consumer Key * Is your Twitter Application Consumer Key. If you don't have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token Secret. 524 Information Builders 1. iWay Services Parameter Description Consumer Secret * Is your Twitter Application Consumer Secret. If you don't have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token 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. iWay Service Manager Component Reference Guide 525 Available Services 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 operation requested. 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. The update text is compared with the authenticating user's recent Tweets. Any attempt that would result in duplication will be blocked. A user cannot submit the same status twice in a row. Parameters: 526 Information Builders 1. iWay Services 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. This parameter will be ignored unless the author of the Tweet this parameter references is mentioned within the status text. Therefore, you must include username, where username is the author of the referenced Tweet, within the update. Image Sends a Tweet with an image. This version only supports three type image files: jpg, gif, and png. Consumer Key * Is your Twitter Application Consumer Key. If you don't have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token Secret. Consumer Secret * Is your Twitter Application Consumer Secret. If you don't have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application 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 have this information, please go to http://dev.twitter.com. Sign in with your Twitter account, Choose My Applications and click Create a New Application then follow the prompts to get Consumer Key, Consumer Secret, Access Token, and Access Token Secret. iWay Service Manager Component Reference Guide 527 Available Services 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. This parameter will be ignored unless it is inside the range -90.0 to +90.0 inclusive (north is positive). It will also be ignored if there is no corresponding long parameter. Longitude The longitude of the location this Tweet refers to. The valid ranges for longitude are -180.0 to +180.0 inclusive (east is positive). This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there no corresponding lat parameter. Place Place Id The ID of the place in the world. 528 Information Builders 1. iWay Services 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 operation requested. 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 for the exchange of calendaring and scheduling data. A common example is an email message containing an iCalendar attachment for a meeting request. iCalendar is defined in the RFC 5545 specification. xCal is the XML format for iCalendar, and is defined in the RFC 6321 specification. xCal is designed to support the round trip from iCalendar to xCal back into iCalendar without losing semantic information. This allows the application query to update the information in the more convenient XML format, with no loss of information. Parameters: iWay Service Manager Component Reference Guide 529 Available Services 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 completed successfully. This service requires iCalendar input to be stored as bytes or lines, directly within the input document. 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 service stores 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 is represented by an 530 Information Builders 1. iWay Services 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 element of the same name. When present, the properties are grouped within the A property has optional parameters and a value. In xCal, a property maps to an element of the same name. When present, the parameters are grouped within the 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, with the textual value as contents. This approach is used because many properties accept values of 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. iWay Service Manager Component Reference Guide 531 Available Services iCalendar defines a folding algorithm to limit the line length to under 75 octets. It also defines an escape mechanism for some characters. This service automatically unfolds and unescapes when parsing iCalendar input. Conversely, this service automatically folds and escapes when generating iCalendar output. Example 1 This example shows how a calendar request can be converted to xCal. These instructions describe how to configure a process flow to handle iCalendar attachments in an email message. Richard Smith is organizing a meeting with John Doe and Jane Roe. It is scheduled for March 4, 2014 and runs weekly for another 5 weeks. He used a calendar application to send this calendar request to the attendees. The multipart/alternative message, is composed of two parts: A text or plain description. A text or calendar part. From: "Smith, Richard" 532 Information Builders 1. iWay Services V2hlbjogT2NjdXJzIGV2ZXJ5IFR1ZXNkYXkgZnJvbSAxMDowMCBBTSB0byAxMTowMCBBTSBlZmZl Y3RpdmUgMy80LzIwMTQgdW50aWwgNC8xLzIwMTQuIFRoZXJlIGFyZSA1IG1vcmUgb2NjdXJyZW5j ZXMuIChHTVQtMDU6MDApIEVhc3Rlcm4gVGltZSAoVVMgJiBDYW5hZGEpDQpXaGVyZTogbGFyZ2Ug Y29uZmVyZW5jZSByb29tDQoNCip+Kn4qfip+Kn4qfip+Kn4qfioNCg== --_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_ Content-Type: text/calendar; charset="utf-8"; method=REQUEST Content-Transfer-Encoding: base64 QkVHSU46VkNBTEVOREFSDQpNRVRIT0Q6UkVRVUVTVA0KUFJPRElEOk1pY3Jvc29mdCBFeGNoYW5n ZSBTZXJ2ZXIgMjAwNw0KVkVSU0lPTjoyLjANCkJFR0lOOlZUSU1FWk9ORQ0KVFpJRDpFYXN0ZXJu IFN0YW5kYXJkIFRpbWUNCkJFR0lOOlNUQU5EQVJEDQpEVFNUQVJUOjE2MDEwMTAxVDAyMDAwM A0KVFpPRkZTRVRGUk9NOi0wNDAwDQpUWk9GRlNFVFRPOi0wNTAwDQpSUlVMRTpGUkVRPVlFQVJMW TtJ TlRFUlZBTD0xO0JZREFZPTFTVTtCWU1PTlRIPTExDQpFTkQ6U1RBTkRBUkQNCkJFR0lOOkRBWUxJ R0hUDQpEVFNUQVJUOjE2MDEwMTAxVDAyMDAwMA0KVFpPRkZTRVRGUk9NOi0wNTAwDQpUWk9GRlNF VFRPOi0wNDAwDQpSUlVMRTpGUkVRPVlFQVJMWTtJTlRFUlZBTD0xO0JZREFZPTJTVTtCWU1PTlRI PTMNCkVORDpEQVlMSUdIVA0KRU5EOlZUSU1FWk9ORQ0KQkVHSU46VkVWRU5UDQpPUkdBTklaRVI7 Q049IlNtaXRoLCBSaWNoYXJkIjpNQUlMVE86UmljaGFyZF9TbWl0aEBpYmkuY29tDQpBVFRFTkRF RTtST0xFPVJFUS1QQVJUSUNJUEFOVDtQQVJUU1RBVD1ORUVEUy1BQ1RJT047UlNWUD1UUlVFO0NO PSJEb2UsIEpvaG4NCiAiOk1BSUxUTzpKb2huX0RvZUBpYmkuY29tDQpBVFRFTkRFRTtST0xFPVJF US1QQVJUSUNJUEFOVDtQQVJUU1RBVD1ORUVEUy1BQ1RJT047UlNWUD1UUlVFO0NOPSJSb2UsIEph bmUNCiAiOk1BSUxUTzpKYW5lX1JvZUBpYmkuY29tDQpERVNDUklQVElPTjtMQU5HVUFHRT1lbi1V UzpXaGVuOiBPY2N1cnMgZXZlcnkgVHVlc2RheSBmcm9tIDEwOjAwIEFNIHRvIDExOjANCiAwIEFN IGVmZmVjdGl2ZSAzLzQvMjAxNCB1bnRpbCA0LzEvMjAxNC4gVGhlcmUgYXJlIDUgbW9yZSBvY2N1 cnJlbmNlcy4gKEdNVA0KIC0wNTowMCkgRWFzdGVybiBUaW1lIChVUyAmIENhbmFkYSlcbldoZXJl OiBsYXJnZSBjb25mZXJlbmNlIHJvb21cblxuKn4qfip+DQogKn4qfip+Kn4qfip+KlxuDQpSUlVM RTpGUkVRPVdFRUtMWTtDT1VOVD01O0lOVEVSVkFMPTE7QllEQVk9VFU7V0tTVD1TVQ0KU1VNTUFS WTtMQU5HVUFHRT1lbi1VUzpncm91cCBtZWV0aW5nDQpEVFNUQVJUO1RaSUQ9RWFzdGVybiBTdGFu ZGFyZCBUaW1lOjIwMTQwMzA0VDEwMDAwMA0KRFRFTkQ7VFpJRD1FYXN0ZXJuIFN0YW5kYXJkIFRp bWU6MjAxNDAzMDRUMTEwMDAwDQpVSUQ6MDQwMDAwMDA4MjAwRTAwMDc0QzVCNzEwMUE4MkUwMDgw MDAwMDAwMDM2RDU1NkQyMkIzN0NGMDEwMDAwMDAwMDAwMDAwMDANCiAwMTAwMDAwMDAyMEFGO DMwMjVEMjA1RDQ4QjY3OTNCMzhBNzFGQ0JCQg0KQ0xBU1M6UFVCTElDDQpQUklPUklUWTo1DQpEV FNU QU1QOjIwMTQwMzAzVDIxNTkxNloNClRSQU5TUDpPUEFRVUUNClNUQVRVUzpDT05GSVJNRUQNClNF UVVFTkNFOjANCkxPQ0FUSU9OO0xBTkdVQUdFPWVuLVVTOmxhcmdlIGNvbmZlcmVuY2Ugcm9vbQ0K WC1NSUNST1NPRlQtQ0RPLUFQUFQtU0VRVUVOQ0U6MA0KWC1NSUNST1NPRlQtQ0RPLU9XTkVSQVBQ VElEOjIxMTIwMzUzODINClgtTUlDUk9TT0ZULUNETy1CVVNZU1RBVFVTOlRFTlRBVElWRQ0KWC1N SUNST1NPRlQtQ0RPLUlOVEVOREVEU1RBVFVTOkJVU1kNClgtTUlDUk9TT0ZULUNETy1BTExEQVlF VkVOVDpGQUxTRQ0KWC1NSUNST1NPRlQtQ0RPLUlNUE9SVEFOQ0U6MQ0KWC1NSUNST1NPRlQtQ0RP LUlOU1RUWVBFOjENCkJFR0lOOlZBTEFSTQ0KQUNUSU9OOkRJU1BMQVkNCkRFU0NSSVBUSU9OOlJF TUlOREVSDQpUUklHR0VSO1JFTEFURUQ9U1RBUlQ6LVBUMTVNDQpFTkQ6VkFMQVJNDQpFTkQ6VkVW RU5UDQpFTkQ6VkNBTEVOREFSDQo= --_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_-- The email listener (com.ibi.edaqm.XDPop3Master) reads this email message and stores the main body part in the document. The base64 data is automatically decoded. The listener is configured to keep the document in flat format because it is not XML. The calendar part is not shown in this example because it is stored as an attachment in the document. iWay Service Manager Component Reference Guide 533 Available Services 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 Attachment Iterator (com.ibi.agents.XDIterAttachments). The following table lists the parameter values that are 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 iCalendar attachment, 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 an iCalendar request stored as bytes in the current document. BEGIN:VCALENDAR METHOD:REQUEST PRODID:Microsoft Exchange Server 2007 VERSION:2.0 BEGIN:VTIMEZONE TZID:Eastern Standard Time BEGIN:STANDARD DTSTART:16010101T020000 TZOFFSETFROM:-0400 TZOFFSETTO:-0500 RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=1SU;BYMONTH=11 END:STANDARD BEGIN:DAYLIGHT DTSTART:16010101T020000 TZOFFSETFROM:-0500 TZOFFSETTO:-0400 RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=2SU;BYMONTH=3 END:DAYLIGHT END:VTIMEZONE BEGIN:VEVENT ORGANIZER;CN="Smith, Richard":MAILTO:[email protected] ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN="Doe, John 534 Information Builders 1. iWay Services ":MAILTO:[email protected] ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN="Roe, Jane ":MAILTO:[email protected] DESCRIPTION;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*~*~*~ *~*~*~*~*~*~*\n RRULE:FREQ=WEEKLY;COUNT=5;INTERVAL=1;BYDAY=TU;WKST=SU SUMMARY;LANGUAGE=en-US:group meeting DTSTART;TZID=Eastern Standard Time:20140304T100000 DTEND;TZID=Eastern Standard Time:20140304T110000 UID:040000008200E00074C5B7101A82E0080000000036D556D22B37CF01000000000000000 01000000020AF83025D205D48B6793B38A71FCBBB CLASS:PUBLIC PRIORITY:5 DTSTAMP:20140303T215916Z TRANSP:OPAQUE STATUS:CONFIRMED SEQUENCE:0 LOCATION;LANGUAGE=en-US:large conference room X-MICROSOFT-CDO-APPT-SEQUENCE: 0 X-MICROSOFT-CDO-OWNERAPPTID:2112035382 X-MICROSOFT-CDO-BUSYSTATUS:TENTATIVE X-MICROSOFT-CDO-INTENDEDSTATUS:BUSY X-MICROSOFT-CDO-ALLDAYEVENT:FALSE X-MICROSOFT-CDO-IMPORTANCE:1 X-MICROSOFT-CDO-INSTTYPE:1 BEGIN:VALARM ACTION:DISPLAY DESCRIPTION:REMINDER TRIGGER;RELATED=START:-PT15M END:VALARM END:VEVENT END: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 Attachment Iterator. The _token() function is just a convenient way to extract the MIME type without any parameters. The _lcase() function is needed to convert to lowercase format because MIME types are case-insensitive. For example, the following expression returns text/calendar for this Content-Type: Content-Type: text/calendar; charset="utf-8"; method=REQUEST iWay Service Manager Component Reference Guide 535 Available Services The value of the Switch expression becomes the outgoing edge name.The Switch object is bound to the xCal and iCalendar service by an OnCustom edge called text/calendar.The OnDefault edge of the Switch object should also be bound to other services to handle attachments of other types. The Operation parameter of the xCal and iCalendar service is set to iCalendar to xCal.The output is a parsed XML tree in the current document (indented for display purposes only): 536 Information Builders 1. iWay Services iWay Service Manager Component Reference Guide 537 Available Services 538 Information Builders 1. iWay Services iWay Service Manager Component Reference Guide 539 Available Services This document can be processed by more services (agents) according to the application requirements. The various processing paths within the Attachment iterator loop must converge into a single Junction object. The loop edge points from the junction back to the iterator. 540 Information Builders 1. iWay Services Example 2 This example explains how to read an iCalendar request from an email message stored in a file. The email and HTTP listeners can automatically parse the multipart/alternative message because their underlying protocol requires the presence of headers. This step must also be added 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 can handle complex cryptographic messages, but also simple MIME messages like the multipart/ alternative message in Example 1. The S/MIME KeyStore and S/MIME TrustStore providers are not used to parse simple MIME messages, but they must still be configured to satisfy the parameters 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. This is required to parse the multipart message into the main body and its attachments. In the sample input message, the Content-Type of the main body is text/plain, therefore the service will 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 namespace prefix and the namespace URI. If left blank, the XPath expression in the Processed Elements property and the attribute declarations in the ID Attributes property cannot contain namespaces. iWay Service Manager Component Reference Guide 541 Available Services Parameter Description XPath Syntax Determines which syntax level of the XPath should be used. The default option selects the syntax level as set in the console global settings. Processed Elements The XPath expression returning the elements to be processed. The result must be a node set consisting of independent EncryptedData, EncryptedKey, and/or ReferenceList elements. If left blank, the agent will search throughout the document for all elements named EncryptedData in the namespace http:// www.w3.org/2001/04/xmlenc#. Remove Processed Determines whether the processed elements are removed Elements from the document after being processed. EncryptedData elements are always replaced. EncryptedKey and ReferenceList elements are removed only when this property is true. ID Attributes A space-separated list of attributes that are considered type ID. 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 ns and ns1 prefixes must be declared in the XML Namespace Provider. The form @ns1:attrib means an Attribute named attrib in XML Namespace ns1. The form ns:*/@ns1:attrib is similar except the attribute must also appear on an element of any name in the XML Namespace ns. The default value is xml:id ds:*/@Id xenc:*/@Id wsu:Id. JCE Provider The JCE provider that supplies the cryptographic needs. KeyStore Provider * The provider for the keystore containing the key encryption key. 542 Information Builders 1. iWay Services Parameter Description Key Encryption Key Alias The alias for keystore entry holding the key that will be used to decrypt the symmetric key. When left empty, the Key Encryption Key is resolved based on the information in the KeyInfo element. Key Encryption Key The password for the keystore entry holding the key that will Password be used to decrypt the symmetric key. If left blank, the password for accessing the keystore will be used. Enforce KeyUsage If on, verify certificates used for encryption allow the Extension keyEncipherment 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. iWay Service Manager Component Reference Guide 543 Available Services For more information about the XML Digital Signature Create service, see the iWay Service Manager 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 Service Manager 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 generated symmetric key. JCE Provider The JCE provider that supplies the cryptographic needs. XML Namespace Provider The provider for the mapping between the XML namespace prefix and the namespace URI. If left blank, XPath expressions in the Encrypted Data and EncryptedKey Parent properties cannot contain namespaces. 544 Information Builders 1. iWay Services Parameter Description XPath Syntax Determines which syntax level of the XPath should be used. The default option selects the syntax level as set in the console global settings. Encrypted Data * An XPath expression that returns a nodeset containing the elements to be encrypted. Encryption Type When encrypting an Element, determines whether the whole element or just the Element content is encrypted. Minimum Count The minimum number of elements to encrypt. This must be a non-negative integer. Manifest Create EncryptedKey Determines whether the parent element of the EncryptedKey is Parent created if it is missing. Ignored if the EncryptedKey is embedded in the EncryptedData. iWay Service Manager Component Reference Guide 545 Available Services Parameter Description EncryptedKey Parent The path to the element where the independent EncryptedKey Element will be inserted. If left blank, the EncryptedKey is embedded in the EncryptedData. If Create EncryptedKey Parent is true, the expression must adhere to Restricted XPath syntax, otherwise the expression may adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter. Restricted XPath has the form /step1/step2/... where a step has the form ns:elem[predicate] or a pair of consecutive steps that has the form *[1]/self::ns:elem[predicate] to indicate the element must be the first child of its parent. The namespace prefixes are optional, but if present they must be 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 and Create EncryptedKey Parent is true, then the necessary elements and attributes will be created such that the expression would match successfully. Create ReferenceList Determines whether the parent element of ReferenceList is Parent created if it is missing. Ignored if the ReferenceList is embedded in the EncryptedKey. 546 Information Builders 1. iWay Services Parameter Description ReferenceList Parent The path to the element where the independent ReferenceList Element will be inserted. If left blank, the ReferenceList is embedded in the independent EncryptedKey if applicable. If Create EncryptedKey Parent is true, the expression must adhere to Restricted XPath syntax, otherwise the expression may adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter. Restricted XPath has the form /step1/step2/... where a step has the form ns:elem[predicate] or a pair of consecutive steps that has the form *[1]/self::ns:elem[predicate] to indicate the element must be the first child of its parent. The namespace prefixes are optional, but if present they must be 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 and Create ReferenceList Parent is true, then the necessary elements and attributes will be created such that the expression would match successfully. Id Prefix A numeric suffix will be added to this prefix to create the Id attribute. The Id attribute is created only when the element is referenced 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 encryption key. Key Encryption Key Alias The alias for keystore entry holding the key that will be used to * encrypt the symmetric key. iWay Service Manager Component Reference Guide 547 Available Services Parameter Description Key Encryption Key The password for the keystore entry holding the key that will Password be used to encrypt the symmetric key. A trusted certificate entry does not need a password. If left blank, the password for accessing the keystore will be used to access a private key entry or a symmetric key entry. Enforce KeyUsage If on, verify certificates used for encryption allow the Extension keyEncipherment KeyUsage extension. KeyInfo Include Issuer Serial Determines whether the X509IssuerSerial element is included in the KeyInfo X509Data element when the Key Encryption Key to describe came from an X509Certificate. Include Subject Name Determines whether the X509SubjectName element is included in the KeyInfo X509Data element when the Key Encryption Key to describe came from an X509Certificate. Include Certificate Determines whether the X509Certificate element is included in the KeyInfo X509Data element when the Key Encryption Key to describe came from an X509Certificate. Key Name Specifies the value of the KeyName element added to the KeyInfo element. This property is most useful when the Key Encryption Key is a symmetric key. Usually left blank to omit the KeyName element when using a public key. Include WSSE Security Determines whether a WSSE SecurityTokenReference to a pre- Token Reference existing BinarySecurityToken is included in the KeyInfo element. WSSE Security Token Id The value of the BinarySecurityToken ID Attribute referenced by the WSSE SecurityTokenReference. If left blank, the default value is token. Edges: 548 Information Builders 1. iWay Services 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 is considered 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 a node 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 the console global settings. iWay Service Manager Component Reference Guide 549 Available Services Parameter Description XML Namespace Map If the XPath expression depends on namespaces, supply the Provider name of an XML Namespace Map Provider that contains the required 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 is considered an error. failed_structure Extracted multiple nodes, but no rootParm was 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: 550 Information Builders 1. iWay Services Parameter Description template The XMLtoFACT_%_^.xch, where [%] represents the message type and [^] represents the release number. The pattern is used to lookup a document inside the EBIX. If the only document in use was D08A ORDERS, and you were to hard- code for just that transformation, the value would be FACTtoXML_ORDERS_D08A.xch, which is the template name within 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 the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. segSuffix The Segment Suffix marks the end of the Segment. This is used in combination with Segment Terminator Character. Note: Users can select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. eDelimiter The control character used to separate elements in a segment. It follows the segment identifier and each data element in a segment except the last. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. iWay Service Manager Component Reference Guide 551 Available Services Parameter Description compDelimiter The control character used to separate sub-elements/ components in a composite element. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. eCharacter The escape character is necessary if any of the EDI document separators are part of the actual value of an attribute. The default value is '\'. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading 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: 552 Information Builders 1. iWay Services 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: iWay Service Manager Component Reference Guide 553 Available Services Parameter Description template * The XMLtoHIPAA_%_^.xch, where [%] represents the message type and [^] represents the release number. The pattern is used to lookup a document inside the EBIX. For example, the value for the 4010 837 Professional template, if hard-coded, would be XMLtoHIPAA_837_004010X098A1.xch, which is the template name within the EBIX. debug * The transformation components are written to files in the local directory (very slow). sTerminator The control character that marks the end of a specific variable- length segment. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. segSuffix The Segment Suffix marks the end of the Segment. This is used in combination with Segment Terminator Character. Note: Users can select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. eDelimiter The control character used to separate elements in a segment. It follows the segment identifier and each data element in a segment except the last. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. 554 Information Builders 1. iWay Services Parameter Description compDelimiter The control character used to separate sub-elements/ components in a composite element. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. eCharacter The escape character is necessary if any of the EDI document separators is part of the actual value of an attribute. The default value is '\'. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading 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: iWay Service Manager Component Reference Guide 555 Available Services 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 message type and [^] represents the release number. The pattern is used to lookup a document inside the EBIX. If the only document in use was 4010 850, and you were to hard-code for just that transformation, the value would be XMLtoX12_850_004010.xch, which is the template name within the EBIX. debug * The transformation components are written to files in the local directory (very slow). sTerminator The control character that marks the end of a specific variable- length segment. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. segSuffix The Segment Suffix marks the end of the Segment. This is used in combination with Segment Terminator Character. Note: Users can select the character from the predefined list or can a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. 556 Information Builders 1. iWay Services Parameter Description eDelimiter The control character used to separate elements in a segment. It follows the segment identifier and each data element in a segment except the last. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. compDelimiter The control character used to separate sub-elements/ components in a composite element. Note: Users can either select the character from the predefined list or can a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading Partner Profile. eCharacter The escape character is necessary if any of the EDI document separators is part of the actual value of an attribute. The default value is '\'. Note: Users can either select the character from the predefined list or enter a predefined SREG, whose value is resolved at run time, or a function to retrieve the value from a Trading 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. iWay Service Manager Component Reference Guide 557 Available Services 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 incoming document. The results are available in an outgoing document. XQuery can be used to select portions 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 of XML data. XQuery 1.0 was developed by the XML Query working group of the W3C. The work was closely coordinated with the development of XSLT 2.0 by the XSL Working Group. The two groups shared responsibility for XPath 2.0, which is a subset of XQuery 1.0. Parameters: Parameter Description XQuery The XQuery expression to evaluate. To put the expression in a file, you Expression can use _file(). Evaluate When true, the XQuery Expression is evaluated by iFL to return the Expression actual XQuery expression to use. The default is to take the XQuery expression as is, which simplifies quoting considerably. 558 Information Builders 1. iWay Services 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 a flat document. Select markup to return the serialization of each result sequence item in a flat document. Select root to return the Element or Document in the first result sequence item as the root of a tree document. Select wrap to return a tree where each result sequence item appears under an item element. Minimum Minimum number of items in result sequence, otherwise return the Occurrence edge fail_empty. Include All Items Determines if all items in the result sequence are part of the return document, otherwise only the first item is included. Separator The separator to insert between result sequence items when returning a 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 iWay Service Manager Component Reference Guide 559 Available Services Line Edge Description OnCustom OnError OnSuccess OnFailure fail_parse: The parameters are incorrect. This includes syntax errors in the XQuery expression or missing a value for an external variable. The output document is an error status document. fail_operation: Failed for another cause. The output document is an error status document. fail_empty: The application indicated that it requires at least one item in the result sequence but the result sequence was empty. The output document is an error status document. When the Evaluate Expression parameter is false, the XQuery Expression parameter contains the actual XQuery Expression. For example: //elem[@attr="1"] When the Evaluate Expression parameter is true, the XQuery Expression parameter contains an iFL 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 against the 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 an error status document and it follows the fail_parse edge. The returned value of an XQuery expression is always a result sequence. The Return parameter determines how the result sequence is stored in the output document. Selecting value or markup will return a string in a flat document. Selecting root or markup will return a parsed XML tree. 560 Information Builders 1. iWay Services Consider the input document Return Parameter Return Output Output Document Value Parameter Document value flat "e1" markup flat " root tree wrap tree The root option can only return the first item in the result sequence. That item must be an element or a document. If the element inherits XML declarations from its ancestors, those XML Namespace declarations will be added directly to the element. The wrap option can return zero or more items. The intermediate The Minimum Occurrence parameter is useful to reject empty results. When the application requires a value, it can set the Minimum Occurrence parameter to 1. If the result sequence is empty, 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 the return document, otherwise only the first item is included. When all items are returned in a tree document, they must always be copied in case two items would overlap. When a single item 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 true and the return document is a flat String. For example, if the separator is |, the expression is //e, the return selection is value and the input document is: 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 following expression declares two external variables, $v1 and $ns:v2. declare namespace ns="http://ns"; declare variable $v1 external; declare variable $ns:v2 external; These variables must be given a value from the environment. The XDXQueryAgent accomplishes this with the help of User Defined Properties. The name of the User Property is related 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 external variable 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 the namespace prefix in the external variable name. This convention eliminates the need for namespace declarations in the parameters since the URI is used instead. For example, the $v1 variable above is not in a namespace, therefore the corresponding User Property is v1. The $ns:v2 variable above is in the namespace http://ns, therefore, the corresponding User Property is {http://ns}v2. 562 Information Builders 1. iWay Services The User Properties can be given a value in iIT Designer. First, create a Service Object for XDXQueryAgent. iWay Service Manager Component Reference Guide 563 Available Services Click Next twice and enter the agent parameters. 564 Information Builders 1. iWay Services Click Next to display the User Properties. Click the label Click here to add to add the User Properties one at a time. Click Finish to create the Service Object. iWay Service Manager Component Reference Guide 565 Available Services The User Properties can be modified after the object is created. Double-click on the Service Object 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 User Properties shown, the result will be: If an external variable does not have a corresponding User Property, the agent returns an error status 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 is configured to call SaxonHE (Home Edition). The default can be modified by assigning a class name to the Java system property javax.xml.xquery.XQDataSource. The class specified must implement the XQDataSource interface. For example, this call to the java interpreter assigns the same XQDataSource as the default: java -Djavax.xml.xquery.XQDataSource=net.sf.saxon.xqj.SaxonXQDataSource Zip Out Service (com.ibi.agents.XDZipOutAgent) Syntax: 566 Information Builders 1. iWay Services 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: iWay Service Manager Component Reference Guide 567 Parallel Control Services The following image shows configuration settings specified in the Properties tab for a Zip Out service object in iIT Designer: You can test the Zip Out service by configuring a channel with a basic File listener as the inlet and 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 File listener) are added to a .zip file, which is placed in the destination folder specified by your File listener. The name of the entry that is added to the .zip file is composed from the value that is specified for the Entry name parameter (for example, testzip.xml). When you configure the File listener, it is recommended to specify zip for the Suffix Out parameter. However, you can always rename the extension of the output file that is generated to .zip and extract the contents. Parallel Control Services You can run multiple operations in parallel within a flow. For example, you can query multiple data stores simultaneously, or update multiple databases. This can be accomplished with parallel edges (multiple matching edges coming out of a node), though it is difficult to design a flow 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 arbitrary number of identical parallel operations. It will then proceed down its flow on its output edge only when all of the parallel operations are complete. All threading control is managed by the agent, 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 iterator is initialized with the input document reaching the agent. The agent uses each item returned by the iterator as the input document of a subflow it runs in parallel. When all subflows have returned, the agent itself terminates. The output is the accumulated result of all the subflows. 568 Information Builders 1. iWay Services Each subflow is independent. For example, the subflow can itself contain iterators or other objects that maintain state without interfering with other parallel flows. Subflows should be designed to be relatively quick to complete, as the parallel control agent cannot proceed until all subflows either return or are timed out. There are multiple variants of the parallel control agent depending on the type of iterator it embeds. For example, the XDParallelXMLSplitAgent embeds an XDIterXMLSplit iterator. The XDParallelCountAgent embeds an XDIterCount iterator. The following table shows parallel services with common parameters. Parameter Description Flow Name Name of the published subflow to run in parallel. This must have been published. Maximum Parallel Tasks Used to throttle the execution to limit the amount of resources needed. It specifies the maximum number of subflows to process simultaneously. If an additional subflow must be executed, it will wait for a previous subflow to complete. The value 0 means unbounded, therefore all items returned by the iterator will attempt to run in parallel. Timeout Specifies the maximum time to wait for all subflows to complete. The agent timeout should probably be bigger than the subflow timeout if throttling is used. The value 0 means there is no time limit. Accumulation Version The parallelized result is accumulated. The result is either Simple or Multiple. Simple means that only a single, XML document is accumulated from each parallel subflow. Multiple allows several documents of XML or non-XML to be accumulated from each parallel subflow. Simple uses less memory. Multiple allows a wider variety of parallelized flows. iWay Service Manager Component Reference Guide 569 Parallel Control Services The remaining parameters are specific to the embedded iterator. The agent assigns a unique integer value to the special register iway.taskindex for each subflow that it executes. The value of taskIndex for the first subflow is 1, the value for the second 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 parameter expressions. 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 successfully and at least one returned abnormally. Users are warned that fail_incomplete, if not wired, will be reflected as an error. Some flows may wish to wire this and the success edges to the same node, and do analysis later in the flow. Fail_incomplete is not a reflection of decisions made in the execution of the item, but rather of the success 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 agent to return fail_operation or fail_incomplete depending on the result of other process flows. The agent 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 following example. Note: The XML output shown is for the 570 Information Builders 1. iWay Services The final result for Multiple Accumulation Version has the following form. Note: The XML output shown is for the In this example, the subflows terminated in the end nodes named success and backout. The subflow with index 2 returned an error, and the error status of the document is noted for analysis. The subflows also returned different types of information. The application designer is responsible for the data and the format in which it is returned. iWay Service Manager Component Reference Guide 571 Parallel Control Services The following table shows informal attributes in the output accumulation. Attribute Description encoding The IANA encoding associated with the document. (Multiple format only) format The payload type. See below for information on the types. (Multiple format only) edge The name of the end node in the subflow that returned this document. error If the returned document has the error state set, this attribute will be set to true. The following table shows the formats and how data values are returned in the output accumulation. Format Description xml The returned information is carried as a child (subtree) of the string The information is returned as the value of the bytes The information is returned as the value of the It is legal if the iterator returns no item. In this case, no subflow will be executed and the Each 572 Information Builders 1. iWay Services Once the parallel agent completes, the resulting accumulation is available to subsequent flow nodes. These nodes can deal with the result in any manner appropriate to the application. For example, you can execute an XDIterXMLSplit iteration and process each result as needed. In this case, the agent did not remove the need for iteration. However, it executed a potentially lengthy computation in parallel, saving a lot of time. Running iteration on a pre-computed result is 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 lock is advisable when the Maximum Parallel Tasks property is more than 1. The scope and Lock Name 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 further subflows are started. The parallel control agent awaits completion of the current set, and then passes the status document down the cancel edge. Developer Cautions Developers using the parallel control agent are reminded that several issues must be considered in use and tuning of the application. 1. Parallel operations are passed among the available execution threads of the computer. On a computer with a large number of processors, this can result in significantly improved performance. However, on a computer with a few processors, control may be passed back and forth among the threads and little if any overall performance gain is achieved. It is easy to 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 the subflows 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, and each needs memory to do its work, memory considerations should be taken into account in design of the application. The services support a Maximum Parallel Tasks parameter. This is the number of executions that will take place in parallel. Managing use of iFL, coupled with an understanding of the dynamics of the application, can help in setting this parameter. For example, the following command sets the number of attempted simultaneous parallel executions to a multiple of the available processors. iWay Service Manager Component Reference Guide 573 Parallel Control Services _int(_ceil(_mul(_div(_sysinfo(processors),_chaninfo(*,'active')),8))) XDParallelCountAgent Properties The following image shows the configuration parameters for Parallel Execution: Counted iteration service. XDParallelJsonSplitAgent Properties The following image shows the configuration parameters for Parallel Execution: JSON iteration service. 574 Information Builders 1. iWay Services XDParallelXMLSplitAgent Properties The following image shows the configuration parameters for Parallel Execution: XML iteration service. The following image shows the configuration parameters for Parallel Execution: XML iteration service. iWay Service Manager Component Reference Guide 575 Parallel Control Services 576 Information Builders Chapter 2 iWay Preparsers iWay Service Manager includes many predefined preparsers that you can use to convert incoming messages into processable documents. You can add these preparsers to simple or complex business logic configurations using the iWay Service Manager Administration Console. For reference purposes, this section lists and describes all the predefined preparsers that 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. The preparsed document then passes through the standard transformation services to reach the designated 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 the methodology 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 Java classpath. iWay Service Manager includes preparsers that have been preconfigured. Available Preparsers The following section provides a comprehensive reference for all the predefined preparsers that are supplied with iWay Service Manager. iWay Service Manager Component Reference Guide 577 Available Preparsers Preparser Class Name Streaming? Description Name Append XDAppend No Used for appending text to an existing flat file. C Char Filter CCharFilter No Eliminates control characters from an incoming message. Char Repl XDCharRepl No Performs character replacements in the incoming document. Cross-Origin XDCors No Implements the same Resource functionality as the Cross- Sharing Origin Resource Sharing Service. Delimited XDDelVal No Delimited value handler. Value Delimited XDDelValStream Yes Streamable delimited value Value Stream handler. EDIFACT XDEDIFACTBatchSplitter No Splits EDIFACT input files Batch Splitter that contain multiple Preparser transactions or envelopes. EDI Batch XDEDIBatchSplitter Yes Splits a batch of EDI Splitter documents. EDIFACT XDEDIFACTPreParser No Accepts a % in the template name, which is filled in by message type. EDIX12 XDEDIpreParser No After a batch of EDI messages is split, this preparser converts each EDI message into XML format. 578 Information Builders 2. iWay Preparsers Preparser Class Name Streaming? Description Name EDIX12 EDISplitPP Yes Parses an EDI input file that Splitter contains one or more Preparser interchanges (ISA) and multiple documents, and creates multiple XML output files. For more information, see the iWay Integration Solution for EDI User's Guide. EDIX12 XML XDXMLEDIValidator No Takes EDI XML as input and Validator returns that input with the structural errors section added to be processed by the appropriate rule. En Tag XDEnTag No Surrounds the incoming message with a designated tag. Error Filter ErrorFilter No Obtains the original input document from the error document. Excel XDExcelpreParser No Transforms an Excel worksheet into an XML formatted document. Extract XDExractPreparser Yes Decompresses compressed Preparser files. Flat Stream XDFlatStreamPreParser Yes Splits non-XML messages that are to be split on a recognized character. HIPAA Batch XDHIPAABatchSplitter No Splits a batch of HIPAA Splitter documents. iWay Service Manager Component Reference Guide 579 Available Preparsers Preparser Class Name Streaming? Description Name HIPAA XDHIPAAPreParser No Transform a HIPAA Preparser document into a HIPAA XML document. HIPAA Splitter HIPAASplitPP No Parses a HIPAA input file Preparser that contains one or more interchanges (ISA) and multiple documents, and creates multiple XML output files. For more information, see the iWay Integration Solution for HIPAA User's Guide. HTTP XDHTTPpreParser No Transforms a key=value query string into an XML string with the POST action as the root. HTTP XDHTTPMultipartPreparser No Transforms a key=value Multipart query string into an XML string with the POST action as the root. Inflate XDInflate No Inflates data produced by the deflate preemitter. JMS Object XDJMSObjectPreParser No Used to convert a JMS Preparser ObjectMessage to a suitable iSM message. Legacy Record LegacyRecordPreparser No Converts an incoming legacy flat file (copybook) into an XML file. For more information, see the iWay Transaction Adapter for CICS User's Guide. 580 Information Builders 2. iWay Preparsers Preparser Class Name Streaming? Description Name Multi Part XDMultiPart No Divides multipart documents for later use. Multi Part for XDMultiPartForNHTTP No Divides multipart documents NHTTP into body and attachments. PgpDecrypt PGPDecrypt No Decrypts an incoming message on the channel into the original unencrypted format. Safestore XDSafestorePreparser No Stores incoming HTTP messages. By default, messages are written to the disk. SOAP XDSOAPPreParser No Accepts SOAP message from any JMS listener. SREG XDSREGPreparser No Sets one or more special Preparser registers of a given type. SWIFT ACK SwiftBPP No Transforms MT021 Systems Messages to XML-formatted documents. For more information, see the iWay Integration Solution for SWIFT User's Guide. SWIFT Batch XDSWIFTBatchSplitter Yes Splits the input stream and Splitter produces groups of byte[]'s as per the predefined splitting logic. For more information, see the iWay Integration Solution for SWIFT User's Guide. iWay Service Manager Component Reference Guide 581 Available Preparsers Preparser Class Name Streaming? Description Name SWIFT System XDSWIFTSysMsgPreParser No Transforms SWIFT User-to - Message System and System-to-User FIN Format Messages to XML-formatted documents. For more information, see the iWay Integration Solution for SWIFT User's Guide. XDSWIFT XDSWIFTpreParser No Accepts a % in the template name, which is filled in by message type. For more information, see the iWay Integration Solution for SWIFT User's Guide. XML Split XDXMLSplit No Splits an incoming XML document based on an XPATH value. XML Stream XDXMLStreamPreParser Yes Accepts an input file containing multiple XML documents and creates single XML documents from the original input file. Append Preparser (com.ibi.preparsers.XDAppend) Syntax: com.ibi.preparsers.XDAppend 582 Information Builders 2. iWay Preparsers Description: The Append preparser is used to append text to an existing flat file. This preparser should not be the last in the chain before a route is called. You can use the En Tag preparser to enclose the flat appended text into an XML structure or use iWay Transformer to convert a flat file to XML format. In a use case scenario, the Append preparser is useful when two flat files need to be appended. However, to convert to XML, an additional preparser, such as En Tag ,should be used 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 list and 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 this document 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. iWay Service Manager Component Reference Guide 583 Available Preparsers In a use case scenario, the C Char filter preparser can be used when an incoming message is unformatted and contains carriage returns. The C Char filter preparser can remove the carriage return 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 be removed. Bell * Indicates whether bell (0x07) characters need to be removed. Control Replace With * Indicates whether the removed characters are replaced with a space, 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 items on a single line. 1. Select the C Char Filter (com.ibi.preparsers.CCharFilter) preparser from the Type drop-down list 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 and the new preparser (XDCCharFilter) to enclose each split flat file into an XML file. 584 Information Builders 2. iWay Preparsers 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 the following list of travel items: suitcase toothbrush travel case comb soap 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 of Tom, then the character R could be replaced with T in this document. It is analogous to the find 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 list and click Next. The configuration parameters pane opens. 2. Enter R for the Input parameter and T for the Replace with parameter. iWay Service Manager Component Reference Guide 585 Available Preparsers 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 and the 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 the following: When this input document is processed by the channel, an output XML document is generated with the following contents: 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 Sharing Service (com.ibi.agents.XDCorsAgent). For more information, see Cross-Origin Resource Sharing Service (com.ibi.agents.XDCorsAgent). The preparser causes an error if the returned edge would be anything other than success. 586 Information Builders 2. iWay Preparsers EDIFACTPreParser (com.ibi.preparsers.XDEDIFACTPreParser) Syntax: com.ibi.preparsers.XDEDIFACTPreParser Description: After a batch of EDIFACT messages are split, the EDIFACTPreParser converts each EDIFACT message 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 the message type. Parameters: Parameter Description Template The HL7_%_^toXML.xch, where [%] represents the message type and [^] represents the version. The pattern is used to lookup a document 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 iWay Service Manager Component Reference Guide 587 Available Preparsers Description: After a batch of EDI messages is split, the EDIX12PreParser converts each EDI message into XML format. Note: The EDIX12PrePreparser is deprecated. As an alternative it is recommended to use the EDIX12SplitterPreParser (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 the structural 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, it passes on the incoming message as CDATA to the tag. Additional features allow configuration of 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 be converted into an XML file without changing the format of the flat file (using the entire content of the flat file as is). For instance, if a flat file contained a list of names separated by carriage returns, 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. 588 Information Builders 2. iWay Preparsers 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 base64 form. Result Form Specifies the type of output that is required. Select parsable or tree 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 and click 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 to illustrate its use. 7. Construct an inlet, for example, PreparseInlet, which is associated with a file listener, an Append 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. iWay Service Manager Component Reference Guide 589 Available Preparsers When this input document is processed by the channel, the contents are appended and enclosed. The following XML output document is generated: 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 standard by which iWay Service Manager reports errors back to the user. These documents contain the complete incoming message associated with an error. The preparser extracts the original message and passes it into the system for processing. Messages that are identified as not being error documents are passed along without any modifications. In a use case scenario, the Error Filter preparser can be used to obtain the original document from an error document if the user needs to retest a component, but does not have the original 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 and the new preparser (XDErrorFilter). 5. Define a simple move route and a default outlet for the channel. 6. Build, deploy, and start the channel. 590 Information Builders 2. iWay Preparsers 7. Create an input document, which contains the following: When this input document is processed by the channel, the following XML output document is generated: Excel Preparser (com.ibi.preparsers.XDExcelpreParser) Syntax: com.ibi.preparsers.XDExcelpreParser Description: The Excel preparser transforms an Excel worksheet into an XML formatted document. If required, this preparser uses the header row in the Excel worksheet as XML tags for the data elements. In a use case scenario, the Excel preparser is useful when data in Excel must be transformed into XML. iWay Service Manager Component Reference Guide 591 Available Preparsers Note: When using the Excel preparser to convert an Excel document to XML, it changes the dates from mm/dd/yyyy to mm/dd/yy. For example, if the Excel document has a cell format of Date *03/14/2001 (with an asterisk), the date will convert to 03/14/01. If the cell format is Date 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 date selection that will keep the original format. Parameters: Parameter Description hasheaders Determines whether the contents of the first row are the names to be used for subsequent rows. Example: 1. Select EXCELPreParser (com.ibi.preparsers.XDExcelpreParser) from the Type drop-down list and 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. 592 Information Builders 2. iWay Preparsers 6. Construct an inlet, for example, PreparseInlet, which is associated with a file listener, and the 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 Use Use Example Return type 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 in 26 month The output document [document_out]*.xml will have the following format: ExtractPreparser (com.ibi.preparsers.XDExtractPreparser) Syntax: com.ibi.preparsers.XDExtractPreparser 594 Information Builders 2. iWay Preparsers Description: Compressed files, such as .zip or TAR/GZ, can be decompressed using this preparser. Each entry in the compressed file is presented sequentially to the channel for processing. For example, a .zip file containing a group of related HL7 documents could process those documents one at a time as if they had arrived on the channel individually. All entries in the file are 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 a file system location, and present the location in a Service Manager Signal document and Special Registers. The application can elect to read the file if needed using agents such as XDFileOpsAgent and XDFileReadAgent. The channel should delete the file as part of processing the file. Stream The preparser can emit a decompressed file in stream format. This presents a single access stream for each entry in the archive (even if the archive is a single compressed file). The preparser appears as any streaming preparser with an end of stream signal ( Special Registers The following table lists and describes the Service Manager Special Registers that are set by the preparser with each decompressed entry. Special Register Description Name archive Name of the archive file. iWay Service Manager Component Reference Guide 595 Available Preparsers Special Register Description Name source File name and directory path. If you select the Signal option, the file will be decompressed to the file system with Service Manager, especially if the register contains the absolute path of the file. However, if you select either the Data or Stream option, then the register will represent the directory structure within the archive file. parent Directory that contains the file (or missing if there is no parent directory) 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 be used to decompress this type of file upon receipt of the file. However the File listener is not capable of decompressing anything other than .zip files. This preparser is a streaming preparser. What this means is that one file (in this case the .zip archive) is broken down into separate documents each representing a file contained in the archive. For example, if the user is configuring a File listener channel to process the archive file and uses the default.outlet as the channel outlet, then each extracted file is emitted to the configured 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.default channel outlet, then the File listener's configuration for Destination must be configured, as shown in the following image. 596 Information Builders 2. iWay Preparsers The back-tick character (`) is used by iSM to delay the evaluation of the iFL function SREG until runtime. If the back-tick character is excluded, then the iFL evaluation is performed when the listener is configured. This is very important to remember because the SREG source is only set when the .zip archive file is extracted. It is also important to remember the setting of the Data Format 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 the archived file's directory structure. Therefore, if the archived file is data/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 included the archived file's directory structure. Therefore if the archived file is data/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 the extracted 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 one exists) only. If the user wants to save the iSM Signal document in the Destination, 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 than output.default overrides the Destination parameter in favor of the outlet's File Emitter configuration. The use of iFL and SREGs would mirror the File listener's Destination parameter without the back-tick character. The back-tick character is not required at this point because the iSM SREGs already reflect the information about the archive's extracted file. iWay Service Manager Component Reference Guide 597 Available Preparsers 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 be appropriate for decompressed files larger than a few megabytes. Signal The decompressed file is stored on the file system of Service Manager and a Signal document containing the information and location of the file is created. This option takes up only the amount of memory needed for the signal document itself. You can then obtain the location of the file from the Signal document. Note: You are responsible for deleting (if desired) the decompressed archive file(s). Stream The decompressed InputStream of the file is stored in the document. A Signal document is created containing information about the decompressed file. This option takes up only the amount of memory needed for the signal document itself and the data stream of the decompressed file. 598 Information Builders 2. iWay Preparsers 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 the HIPAASplitterPreParser (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 action as the root. This preparser can be used to construct an XML document with the HTTP parameters that are being passed as a query string. The HTTP preparser can only be used with an HTTP listener. In a use case scenario, if you need to generate an XML document with the HTTP request parameters, the HTTP preparser can be used to transform the HTTP GET request for a web application. Example: 1. Select the HTTP (com.ibi.preparsers.XDHTTPpreParser) preparser from the Type drop-down list 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. iWay Service Manager Component Reference Guide 599 Available Preparsers 5. Construct a simple index.html page. For example:
6. In the Document Root field for the HTTP listener, specify the base directory from which the sample index.html page is served. 7. Construct an inlet, for example, HttpPreparseInlet, which is associated with the HTTP listener (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:
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 MB in size) must be sent by email using an Email emitter. In this scenario, the destination email server does not accept messages that are greater than 3 MB in size. The Deflate preemitter could be used before the Email emitter to send the message in an email. The Inflate preparser could be used once the email is read through an Email listener and subsequently picked up by the Inflate preparser in the channel.
600 Information Builders 2. iWay Preparsers
Example: 1. Select the Inflate (com.ibi.preparsers.XDInflate) preparser from the Type drop-down list and click 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 and the 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 iSM message. While the server can deal with most message type automatically, it needs application programming assistance to deal with the generic ObjectMessage. This preparser or an extension of it must be invoked by the channel to manage the ObjectMessage retrieved from the JMS Queue or Topic.
Parameters:
Parameter Description
Root Tag Root tag of the output XML document. If not specified, 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 the Type drop-down list and click Next. iWay Service Manager Component Reference Guide 601 Available Preparsers
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 ObjectMessage that was retrieved from the JMS Queue or Topic.
Below is a sample document returned by the XDJMSObjectPreParser.
For more information on the JMS Object preparser, see the iWay Service Manager Protocol Guide .
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 the iWay Transaction Adapter for CICS User's Guide.
602 Information Builders 2. iWay Preparsers
Parameters:
Parameter Description
Copybook Location * The full path to the COBOL copybook.
Input Encoding * The Internet Assigned Numbers Authority (IANA) character set for 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 default encoding of the listener.
Full FD? * If set to true, then the COBOL record headings appear in the output XML. By default, false is selected.
Multiple Records? * If set to true, then multiple CommArea records are produced if the input byte array is larger than the copybook size. By default, false is 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 last in the chain. When used, the multipart message is divided so that the body of the message is part 0 and subsequent attachments are 1 to n. The multipart object is carried in the XML document (XDDocument) and can be retrieved and interrogated by your own business service to obtain the individual parts for processing. If the body is a MIME type of _/XML, it is parsed and carried as an XML document.
In a use case scenario, an incoming document can consist of an email where specific information from the email message must be extracted, such as the attachment headers and the attachment file name. The Multipart preparser can transform the message into a multipart format 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 Type drop-down list and click Next. iWay Service Manager Component Reference Guide 603 Available Preparsers
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 new preparser (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 (for example, 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. For example:
content-type: multipart/mixed; boundary="----=_Part_5_23514719.1234266657921" content-length: 571 mime-version: 1.0 message-id: <17237217.1234266657984.JavaMail.ksugauchi@kmaruyama> ------=_Part_5_23514719.1234266657921 Content-Type: application/xml Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=a.xml a ------=_Part_5_23514719.1234266657921 Content-Type: text/document Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=b.xml Content-Id: mydata1 b ------=_Part_5_23514719.1234266657921 Content-Type: text/document Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=c.xml Content-Id: mydata2
When this multipart input document is processed by the channel, an output XML document (a#.txt) is generated with the following contents:
604 Information Builders 2. iWay Preparsers
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 the chain. When used, the multipart message is broken up so that the body of the multipart message is part 0 and subsequent attachments are 1 to n.
In a use case scenario, the Multipart for nHTTP preparser is useful when the incoming message is a multipart document and the headers and attachment portions of the document need to be extracted from the document for additional message processing.
Parameters:
Parameter Description
Payload Header A special register namespace into which any headers on the Namespace extracted body part will be stored as HDR registers. If not supplied, body part headers will be saved in the default namespace.
Message Header A special register namespace where message headers can be Namespace found. If not supplied, HDR registers from the default namespace will be used.
Keep Message Flat Determines whether to keep the body of the message as an array of bytes. Select true or false from the drop-down list.
Example: 1. Select the Multi Part For NHTTP (com.ibi.preparsers.XDMultiPartForNHTTP) preparser from the 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.
iWay Service Manager Component Reference Guide 605 Available Preparsers
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 the new 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. For example:
content-type: multipart/mixed; boundary="----=_Part_5_23514719.1234266657921" content-length: 571 mime-version: 1.0 message-id: <17237217.1234266657984.JavaMail.soumya@ibi> ------=_Part_5_23514719.1234266657921 Content-Type: application/xml Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=a.xml a ------=_Part_5_23514719.1234266657921 Content-Type: text/document Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=b.xml Content-Id: mydata1 b ------=_Part_5_23514719.1234266657921 Content-Type: text/document Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=c.xml Content-Id: mydata2
When this input document is processed by the channel, an output document (outmpart*.xml) is generated with the following contents:
PGP Decrypt Preparser (com.ibi.preparsers.PGPDecrypt) Syntax:
com.ibi.preparsers.PGPDecrypt
606 Information Builders 2. iWay Preparsers
Description:
The PGP Decrypt preparser decrypts an incoming message on the channel into the original unencrypted format. For more information on how to configure the PGP Decrypt preparser, see the 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 public keys.
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 the number in the input. (|\0x|\n|\t)*
End of Line Replaces carriage return (0x0d) and line feed (0x0a) patterns. Conversion
iWay Service Manager Component Reference Guide 607 Available Preparsers
Smime Preparser (com.ibi.smime.XDSmimePreParser) Syntax:
com.ibi.smime.XDSmimePreParser
Description:
Reads S/MIME messages.
Parameters:
Parameter Description
S/MIME Keystore The provider for the keystore used to decrypt incoming messages. Provider *
S/MIME TrustStore The provider for the keystore containing the S/MIME Certificate Provider * Authorities.
S/MIME Certificate A comma-separated list of Keystore, Directory CertStore or LDAP Store Providers providers for the certificate stores used to complete signer certificate chains when the signed message contains fewer certificates than needed.
S/MIME Signature JCE The JCE Provider for S/MIME Signature Cryptography services. Provider *
S/MIME PKIX JCE The JCE Provider for S/MIME PKIX services. If left blank, the Provider default JCE provider for PKIX will be used.
S/MIME Decryption The private key alias used to decrypt incoming messages. Key Alias
S/MIME Decryption The password for decryption private key. If left blank, the Key Password password for accessing the keystore will be used.
Enforce KeyUsage Determines how the KeyUsage Extension is verified when present Extension in the certificate. The requirement for S/MIME digital signatures is followed by the requirement for S/MIME encryption, separated by a slash.
Enable Certificate Enables CRL or OCSP checking of the signer certificates. Revocation
608 Information Builders 2. iWay Preparsers
Parameter Description
OCSP Responder The name of the OCSP Responder provider. This verifies the status of certificates online instead of relying on Certificate Revocation Lists.
Unrecognized Certs The directory to store unrecognized certificates found in S/MIME Location messages.
Default Content The default encoding when the Content-Transfer-Encoding is Transfer Encoding absent. For S/MIME, this is 7bit. For AS2, this must be set to binary.
Payload Header The special register namespace into which any headers on the Namespace extracted body part will be stored as HDR registers. If not supplied, body part headers will be saved in the default namespace.
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 SOAP portion from the envelope. The preparser then parses the SOAP body by iterating through all child nodes and constructs an XML document (XDDocument), which is used to pass between components 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. iWay Service Manager Component Reference Guide 609 Available Preparsers
In a use case scenario, the SREG preparser is useful when the incoming message has variables associated with it and if changes need to be made to the special registers set at a global level, application level, or server level.
Parameters:
Parameter Description
Type of variable Type of variable (headers appear in emitted documents as header values). Type del to delete the register. Select one of the following options from the drop-down list:
User
Document
Header
Metric
Scope of variable Determines at what level the variable is defined and therefore controls its life span and visibility. Select one of the following options 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-down list 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.
610 Information Builders 2. iWay Preparsers
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 the new 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:
SWIFTPreParser (com.ibi.preparsers.SwiftPreParser) Syntax:
com.ibi.preparsers.SwiftPreParser
Description:
The SWIFTPreParser converts an incoming SWIFT message to XML format. If you require a SWIFT Validation Report, the SWIFTPreParser must be used. If you do not require a SWIFT Validation Report, the SWIFTPreParser or XDSWIFTPreParser can be used. When the SWIFTPreParser is used, an Ebix must be attached to the iSM channel. For more information on 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-formatted documents. For more information on how to configure the SWIFTAckPreParser, see the iWay Integration Solution for SWIFT User's Guide.
iWay Service Manager Component Reference Guide 611 Available Preparsers
SWIFTSystemMessagePreParser (com.ibi.preparsers.XDSWIFTSysMsgPreParser) Syntax: com.ibi.preparsers.XDSWIFTSysMsgPreParser
Description:
The XDSWIFTSysMsgPreParser Transforms SWIFT User-to-System and System-to-User FIN Format Messages to XML formatted documents. For more information on how to configure the XDSWIFTSysMsgPreParser, 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.
Parameter The special register namespace from which XSLT stylesheet Namespace parameters will be taken. The default is to execute the XSLT transform with no stylesheet parameters defined. The Parameter Namespace 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 be emitted from the service.
Error Masks
612 Information Builders 2. iWay Preparsers
Parameter Description
Input Side Mask intermediate errors on input side of iWay transformation. The special register 'iway.transform.errormask.in.format' where format is the input format (for example, 'fwf'), can also control the masking.
Output Side Mask intermediate errors on output side of iWay transformation. The special register 'iway.transform.errormask.out.format' where format is the output format (for example, 'fwf'), can also control the 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 allows messages to be sent cross-configuration.
Parameters:
Parameter Description
Use encryption * Set to true if the marshall and unmarshall messages are to be encrypted. Both the marshalling and unmarshalling channels must be set the same way.
AES Key If using an encrypted channel, set the AES key (maximum 16 characters) to be used.
XDSWIFTPreParser (com.ibi.preparsers.XDSWIFTpreParser) Syntax: com.ibi.preparsers.XDSWIFTpreParser
iWay Service Manager Component Reference Guide 613 Streaming Preparsers
Description:
The XDSWIFTPreParser converts an incoming SWIFT message to XML format. Use the XDSWIFTPreParser only if you do not require a SWIFT Validation Report. When the XDSWIFTPreParser is used, an Ebix must be attached to the iSM channel. For more information on how to configure the XDSWIFTPreParser, see the iWay Integration Solution for SWIFT User's Guide.
Streaming Preparsers To handle large files, iWay Service Manager provides a streaming interface. You can use streaming preparsers only with the HTTP, File, and JMS adapters. To use a streaming preparser in conjunction with other preparsers, you must define it as the first preparser in the chain. 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 multiple XML documents and creates single XML documents from the original input file.
For example, this preparser can process the following batch of XML documents:
This is my document This is my document This is my document This is my document
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.
614 Information Builders 2. iWay Preparsers
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 specified repeating child, for example:
With a split specified as a/b, it results in three passes through the configured flow.
Pass 1
Pass 2
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. iWay Service Manager Component Reference Guide 615 Streaming Preparsers
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 the incoming message consists of a delimited value stream such as lines of comma separated values. The first line can optionally hold field names (DIF format input). An XML document is generated from 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 Stream preparser can be used when an incoming message 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 element name.
Delimiter * Determines the delimiter to be used. Select comma or tab from the drop-down list, or enter a specific character (for example, $) directly in the field. This is a single character, and can be specified in hex form as \xvv where vv is a hexadecimal value specification (for example, \x31).
Rows The number of rows in each document.
616 Information Builders 2. iWay Preparsers
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 be eliminated.
Example: 1. Select the Del Val Stream (com.ibi.preparsers.XDDelValStream) preparser from the Type drop-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 remaining fields. 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 and the new preparser (DelvalStreamPreparser). 9. Define a simple move route and a default outlet for the channel. 10.Build, deploy, and start the channel.
iWay Service Manager Component Reference Guide 617 Streaming Preparsers
11.Create a simple input text document (for example, TestData.txt), which contains the following:
02|penny|copper|$0.01 03|one dollar|paper|$1.00 04|five dollars|paper|$5.00 05|ten dollars|paper|$10.00 06|twenty dollars|paper|$20.00
When this input document is processed by the channel, an output XML document is generated with the following contents:
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 recognized character. During configuration, the character can be specified as any character, a special character, or a HEX character.
618 Information Builders 2. iWay Preparsers
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 values include:
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 Type drop-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, the new preparser (FlatStreamPreparser), and an En Tag preparser to enclose each split flat file into 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 the following: First Line Second Line Third Line Fourth Line
iWay Service Manager Component Reference Guide 619 Splitter Preparsers
When this input document is processed by the channel, the output document (document2_1.txt) contains the following:
The output document (document2_2.txt) contains the following:
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 without doing 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 specified delimiter. The incoming document could be an XML document or a flat file. Different preparsers handle different types of incoming documents. All streaming preparsers are splitter preparsers, but all splitter preparsers are not streaming preparsers. The following splitter preparsers are available:
Delimited Value Splitter Preparser
XML Splitter Preparser
620 Information Builders 2. iWay Preparsers
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 incoming message consists of a delimited value stream such as lines of comma separated values. The first line can optionally hold field names (DIF format input). An XML document is generated from 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 incoming message 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 element name.
Delimiter * Determines the delimiter to be used. Select comma or tab from the drop-down list, or enter a specific character (for example, $) directly in the field. This is a single character, and can be specified in hex form as \xvv where vv is a hexadecimal value specification (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 be eliminated.
Include blanks * Determines whether a blank line should be treated as a row with all null elements, or ignored.
iWay Service Manager Component Reference Guide 621 Splitter Preparsers
Example: 1. Select the Del Val (com.ibi.preparsers.XDDelVal) preparser from the Type drop-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 remaining fields. 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 and the new preparser (DelvalPreparser). 9. Define a simple move route and a default outlet for the channel. 10.Build, deploy, and start the channel.
622 Information Builders 2. iWay Preparsers
11.Create a simple input text document (for example, TestData.txt), which contains the following:
02|penny|copper|$0.01 03|one dollar|paper|$1.00 04|five dollars|paper|$5.00 05|ten dollars|paper|$10.00 06|twenty dollars|paper|$20.00
When this input document is processed by the channel, an output XML document is generated with the following contents:
EDIBatchSplitter Preparser (com.ibi.preparsers.XDEDIBatchSplitter) Syntax:
com.ibi.preparsers.XDEDIBatchSplitter
Description:
Description: The EDIBatchSplitter preparser splits a batch of EDI documents. For more information on how to configure the EDIBatchSplitter preparser, see the iWay Integration Solution for EDI User's Guide.
iWay Service Manager Component Reference Guide 623 Splitter Preparsers
EDIFACTBatchSplitterPreparser (com.ibi.preparsers.XDEDIFACTBatchSplitter) Syntax:
com.ibi.preparsers.XDEDIFACTBatchSplitter
Description:
The EDIFACTBatchSplitter preparser splits EDIFACT input files that contain multiple transactions or envelopes. This preparser should be used with the EDIFACTPreParser. For more information on how to configure the EDIFACTBatchSplitter preparser, see the iWay Integration Solution 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 is produced for each document. For example, if the EDI input file contains three documents within one ISA, the EDIX12SplitterPreParser creates three XML output files, one per document. For more information on how to configure the EDIX12SplitterPreParser, see the iWay Integration Solution for EDI User's Guide.
624 Information Builders 2. iWay Preparsers
HIPAABatchSplitter (com.ibi.preparsers.XDHIPAABatchSplitter) Syntax: com.ibi.preparsers.XDHIPAABatchSplitter
Description:
The HIPAABatchSplitter splits a batch of HIPAA documents. For more information on how to configure 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 is produced for each document. For example, if the HIPAA input file contains three documents within one ISA, the HipaaSplitterPreParser creates three XML output files, one per document. For more information on how to configure the HIPAASplitterPreParser, see the iWay Integration Solution 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 contains multiple 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 the SWIFTBatchSplitter, see the iWay Integration Solution for SWIFT User's Guide.
XML Splitter Preparser (com.ibi.preparsers.XDXMLSplit) Syntax: com.ibi.preparsers.XDXMLSplit
iWay Service Manager Component Reference Guide 625 Splitter Preparsers
Description:
The XML Splitter preparser is used to divide an incoming XML document into smaller documents 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 messages are processed.
Parameters:
Parameter Description
Level string * Define in dot of slash notation, the path to the element on which to split. An asterisk character (*) specifies any tag at that element.
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-down list 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 file listener 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.
626 Information Builders 2. iWay Preparsers
9. Create a simple input text document (for example, a.xml), which contains the following:
When this input document is processed by the channel, the following output XML documents are generated:
iWay Service Manager Component Reference Guide 627 Splitter Preparsers
628 Information Builders Chapter 3 iWay Preemitters
iWay Service Manager includes many predefined preemitters that you can use to convert outgoing messages into processable documents. You can add these preemitters to simple or complex business logic configurations using the Administration Console.
For reference purposes, this section lists and describes all the predefined preemitters that are supplied with iWay Service Manager. In this chapter:
Overview of Preemitter Marshalls a message Preemitter (com.ibi.preemit.XDMarshall) Available Preemitters Multi Part (com.ibi.preemit.XDMultiPart) Constant PE (com.ibi.preemit.XDConstantPE) PGPEncrypt Preemitter (com.ibi.preemit.PGPEncrypt) Deflate (com.ibi.preemit.XDDeflate) PGP Sign Only Preemitter EDIX12 Preemitter (com.ibi.preemit.XDPGPSignPreEmitter) (com.ibi.preemit.XDX12PreEmitter) QA Print (com.ibi.preemit.XDQAPrint) Entity Repl Preemitter (com.ibi.preemit.XDEntityRepl) Remove Outer Tag (com.ibi.preemit.XDDeTag) File read Preemitter (com.ibi.preemit.XDFilePreEmitter) Replaced Paired Characters (com.ibi.preemit.XDCharRepl) Flat Delim Preemitter (com.ibi.preemit.XDFlatDelimPreEmitter) SWIFT Preemitter (com.ibi.preemit.SwiftPreEmitter) HIPAA Preemitter (com.ibi.preemit.XDHIPAAPreEmitter) UUEncodePreEmitter (com.ibi.preemit.XDUUEncodePreEmitter) iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter) XDEDIFACT Preemitter (com.ibi.preemit.XDEDIFACTPreEmitter) Legacy Record Preemitter (com.ibi.preemit.LegacyRecordPreemitter XDSWIFT Preemitter ) (com.ibi.preemit.XDSwiftpreEmitter)
iWay Service Manager Component Reference Guide 629 Overview of Preemitter
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 on the methodology used in writing preemitters, see the iWay Service Manager Programmer's Guide.
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 preemitters that are supplied with iWay Service Manager.
Preemitter Name Class Name Description
CharRepl Preemitter XDCharRepl Replaces paired characters in the input stream.
ConstantPE Preemitter XDConstantPE Returns a constant document.
Deflate Preemitter XDDeflate Deflates data prior to emit.
Detag Preemitter XDDeTag Removes the outermost tag from the XML document and returns the remainder of the document.
Flat Delim Preemitter XDFlatDelimPreemitter Transforms an XML document into a flat file.
EDIX12 Preemitter XDX12PreEmitter Converts the XML formatted EDI document to an EDI-X12 formatted document.
EXIX12 Preemitter XDX12PreEmitter Transforms X12 XML document. For more information, see the iWay Integration Solution for EDI User's Guide.
630 Information Builders 3. iWay Preemitters
Preemitter Name Class Name Description
HIPAA Preemitter XDHIPAAPreEmitter Converts the XML formatted HIPAA document to a HIPAA formatted document.
HL7LLP HL7LLP Adds an LLP envelope to HL7 messages. For more information, see iWay Integration Solution for HL7 User's Guide.
HL7 Preemitter HL7PreEmitter Converts from XML to HL7 format. For more information, see the iWay Integration Solution for HL7 User's Guide.
ISO8583PreEmitter ISO8583PreEmitter Transforms an XML document into an ISO 8583 message. This is also performed by the ISO8583 adapter.
Legacy Record LegacyRecordPreemitter Converts COMMAREA XML nodes to Preemitter bytes as described by a COBOL copybook. For more information, see the iWay Transaction Adapter for CICS User's Guide.
MultiPart Preemitter XDMultipart Outputs a multipart document from the XML document.
PGP Encrypt preemitter PGPEncrypt Encrypts an outgoing message from the channel into an encrypted XML document.
QAPrint Preemitter XDQAPrint Emits the input document to a file along with additional run-time information, such as Special Registers, and so on.
SWIFT Preemitter SwiftPreEmitter Transforms a SWIFT XML document into a SWIFT Message.
iWay Service Manager Component Reference Guide 631 Available Preemitters
Preemitter Name Class Name Description
XDEDIFACT Preemitter XDEDIFACTPreEmitter Transforms an EDIFACT XML document into an EDIFACT message. For more information, see the iWay Integration Solution for UN/EDIFACT User's Guide.
XDEntityRepl XDEntityRepl Eliminates XML entities (such as <. to < and > to >).
XDHIPAA XDHIPPAPreEmitter Transforms a HIPAA EDIX12 XML document into a HIPAA EDIX12 document. For more information, see the iWay Integration Solution for HIPAA User's Guide.
XDHL7 Preemitter XDHL7NewPreEmitter Transforms a HL7 XML document into a HL7 message.
XD SWIFT Preemitter XDSwiftpreEmitter Transforms a SWIFT XML document into a SWIFT FIN Message. For more information, see the iWay Integration Solution for SWIFT User's Guide.
XML GpreEmitter XDXMLGpreEmitter Transforms output using iWay transformations tooling.
XSLT Preemitter XDXSLTpreEmitter Converts the XML document into a HTML document using the XSLT file input.
XMLtoASN1 preemitter XDXMLtoASN1pe Converts an XML message to ASN.1
632 Information Builders 3. iWay Preemitters
Procedure: How to Add a Preemitter 1. In the left console pane of the registry menu, select preemitter as shown in the following image.
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 an outlet that is used to construct a channel.
iWay Service Manager Component Reference Guide 633 Constant PE (com.ibi.preemit.XDConstantPE)
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 constant document.
Use the Constant preemitter if the user needs to return a constant output, say for testing purposes.
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 ConstantPE preemitter and file emitter to this outlet.
Construct the channel PreemitChannel using a file listener case1 as inlet, a simple move route and the outlet created in the previous step.
Let the input to this channel be:
634 Information Builders 3. iWay Preemitters
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 email emitter. The destination email mailbox cannot accept greater than 3 MB. In this case the deflate preemitter could be used before the email emitter to send the message in the email.
Parameter:
Parameter Description
Method of compression Determines what form of compression should be used on the to use output.
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 the form 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.
iWay Service Manager Component Reference Guide 635 EDIX12 Preemitter (com.ibi.preemit.XDX12PreEmitter)
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 Deflate Preemitter would take. You will now construct the channel Deflate using a file listener as inlet is 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 formatted document. The XML structure must be compliant with the schema supplied in the Ebix. For more information on how to configure the EDIX12PreEmitter, see the iWay Integration Solution for 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 XML formatted document.
Use the Entity Repl Preemitter if one XML document is enclosed inside another XML document using < and > characters, then the user can convert the enclosed XML document to XML representation 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.
636 Information Builders 3. iWay Preemitters
2. Click Next. The Name and Description pane opens. 3. Provide a name and optionally, a description for the preemitter and click Finish. Name the preemitter 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 move route and the outlet created in the previous step as shown in the following process. Let the input to this channel be a.xml.
The output obtained is a file with <b> replaced with XML notation
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.
iWay Service Manager Component Reference Guide 637 Flat Delim Preemitter (com.ibi.preemit.XDFlatDelimPreEmitter)
Parameters:
Parameter Description
Name of File * The file to be read. Relative or absolute file paths are supported explicitly or through a SREG or XPath expression evaluated 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 64 is 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 the input 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-second intervals.
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 XML data 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 processing and transformation of the XML data and send the data back to a legacy system then this preemitter can transform the XML into a flat file using pile symbol as the delimiter.
638 Information Builders 3. iWay Preemitters
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 this outlet.
Construct the channel PreemitChannel using a file listener case1 as inlet, a simple move route and the outlet created in the previous step.
The input to this channel is the following:
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 iWay Service Manager Component Reference Guide 639 iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
Description:
The HIPAAPreEmitter converts the XML-formatted HIPAA document to a HIPAA formatted document. The XML structure must be compliant with the schema supplied in the Ebix. For more information on how to configure the HIPAAPreEmitter, see the iWay Integration Solution for 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 Transformations tooling. Use this preemitter to transform the output into a desired user-defined format or any other 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.
640 Information Builders 3. iWay Preemitters
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 named PreemitterOutlet. Add the XMLGPreemitter to this outlet.
Construct the channel PreemitChannel using a file listener case1 as inlet, a simple move route and the outlet created in the previous step.
This input to this channel is as follows.
iWay Service Manager Component Reference Guide 641 iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
642 Information Builders 3. iWay Preemitters
iWay Service Manager Component Reference Guide 643 iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
644 Information Builders 3. iWay Preemitters
The output obtained is a file a0.txt:
iWay Service Manager Component Reference Guide 645 iWay Transformations Preemitter (com.ibi.preemit.XDXMLGpreEmitter)
646 Information Builders 3. iWay Preemitters
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 more information, see the iWay Transaction Adapter for CICS User's Guide.
iWay Service Manager Component Reference Guide 647 Marshalls a message Preemitter (com.ibi.preemit.XDMarshall)
Parameters:
Parameter Description
Copybook Location * The full path to the COBOL copybook that describes the output record.
Input Encoding * The Internet Assigned Numbers Authority (IANA) character set for 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 default encoding of the listener.
Full FD? * If set to true, then the COBOL group field headings appear in the input 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 messages to be sent cross-configuration.
Parameters:
Parameter Description
Compress Messages * Compression reduces the size of the marshalled message. Compression is performed before encryption. Compression is most valuable when the message is XML, and should not be used if large byte messages are being passed.
Marshall User Special Set if the marshalling is to include user registers. Normally the Registers marshaller passes header, document, and system registers associated with the message.
648 Information Builders 3. iWay Preemitters
Parameter Description
Namespace If empty or set to asterisk, all namespaces are marshalled. If there is a value, only registers in the specified namespace are marshalled.
Security
Use encryption * Set to true if the marshall and unmarshall messages are to be encrypted. Both the marshalling and unmarshalling channels must be set the same way.
AES Key If using an encrypted channel, set the AES key (maximum 16 characters) 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 outgoing message is an email document, and if the user needs to create a multipart (.mpart) document from the XML message which underwent processing, this preemitter can be used. This is useful when the input message is an email message or a .mpart message which is processed by the iway channel and needs to be emailed back or written to the output as a multipart document. This could be used in conjunction with a multipart preparser which initially converts the 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. iWay Service Manager Component Reference Guide 649 Multi Part (com.ibi.preemit.XDMultiPart)
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 which writes to a file a*.mpart. Also add the file emitter to this outlet. Construct the channel PreemitChannel 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: 578 mime-version: 1.0 message-id: <9116239.1237437239765.JavaMail.kkauser@shoko2>
------=_Part_1_8573456.1237437239687 Content-Type: application/xml Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=a.xml
The output obtained is a file a*.mpart:- content-type: multipart/mixed; boundary="---- =_Part_1_8573456.1237437239687" content-length: 578 mime-version: 1.0 message-id: <9116239.1237437239765.JavaMail.kkauser@shoko2>
650 Information Builders 3. iWay Preemitters
------=_Part_1_8573456.1237437239687 Content-Type: application/xml Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=a.xml
The input multipart document is successfully moved through the channel and is written as a 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 encrypted XML document. This has to be the last preemitter in the chain as the channel cannot process the encrypted document unless it is decrypted by a preparser.
For more information, see the section on PGP in iWay Extensions Guide.
iWay Service Manager Component Reference Guide 651 PGPEncrypt Preemitter (com.ibi.preemit.PGPEncrypt)
Parameters:
Parameter Description
Encrypt method* The encryption method being used. Select one of the following encryption 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 binary transfer. 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. Select true or false from the drop-down list.
Algorithm* The type of algorithm being used. Select one of the following algorithms from the drop-down list:
cast5
tripledes
blowfish
safer
idea
none
FingerPrint Finger print of the Encryption Hex Decimal Key.
652 Information Builders 3. iWay Preemitters
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 for transfer 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 can be =name for the exact User ID, user@host to match only the email address, or
Signature Key ID The Key ID of the private key used for signing. 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 the fingerprint. Spaces are allowed and are not counted in the length. This property can be used in place or together with the Signature Key User ID to select a more specific key.
Signature Key A case-sensitive passphrase to unlock the Signature Private Passphrase Key.
Signature Expiration The number of seconds after the signature creation time that the signature expires. The format is [xxh][xxm]xx[s]. If absent or has a value of zero, the signature never expires.
iWay Service Manager Component Reference Guide 653 QA Print (com.ibi.preemit.XDQAPrint)
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 Special Registers.
This preemitter is useful for extensive testing and debugging purposes. Thus, the output document would contain the test results such as the special registers, errors generated and so 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. Only applicable 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.
654 Information Builders 3. iWay Preemitters
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 this outlet. In this example, to test the QAPrint preemitter, use a process flow which does conditional checking on special registers and printing it to a trace file using the QAPrint preemitter. In this example, the pflow is constructed, as shown in the following image.
iWay Service Manager Component Reference Guide 655 QA Print (com.ibi.preemit.XDQAPrint)
The decision test object has the following condition:
Add the process flow to a route named CondRt. Construct the channel PreemitChannel using a file listener case1 as inlet, CondRt route and the outlet created in the previous step.
Let the input to this channel be:
656 Information Builders 3. iWay Preemitters
The trace files are obtained as a result of the QAPrint preemitter as follows.
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 remainder of the document. If the inner document is an XML file, it returns an XML or a flat file, if a flat file is contained within the outer tag.
For example, the Remove outer tag preemitter can transform an XML file into a flat file (extract flat file from XML) if the flat file were originally transformed into XML by surrounding it with outer tags.
iWay Service Manager Component Reference Guide 657 Replaced Paired Characters (com.ibi.preemit.XDCharRepl)
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 this outlet. Construct the channel PreemitChannel using a file listener case1 as inlet, a simple move route and the outlet created in the previous step.
The input to the channel is as follows.
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
658 Information Builders 3. iWay Preemitters
Description:
This preemitter replaces paired characters in the input stream. The lengths of the Input field and the Replace With field have to be the same. Use the Replaced paired characters preemitter when the final document has character processing to be done whereby characters and line feeds have to be replaced of if a specific character has to be replaced has to be replaced in the output document.
For example, if a name is misspelled in the output document as rom instead of tom, then the character r could be replaced with t in the document. It is similar to the find and replace in almost 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 character such as [a...z].
Replace with String of characters to replace input with. Count must match number 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 which writes 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 move route and the outlet created in the previous step. iWay Service Manager Component Reference Guide 659 SWIFT Preemitter (com.ibi.preemit.SwiftPreEmitter)
The Input file is a text document, document2.txt as shown as follows.
The output document document2_out.txt would look like the following output.
SWIFT Preemitter (com.ibi.preemit.SwiftPreEmitter) Syntax:
com.ibi.preemit.SwiftPreEmitter
Description:
The SWIFTPreEmitter converts the XML-formatted SWIFT document to a SWIFT formatted document. The XML structure must be compliant with the schema supplied in the Ebix. The SWIFTPreEmitter is used within an adapter framework. For more information on how to configure 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.
660 Information Builders 3. iWay Preemitters
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 formatted document. The XML structure must be compliant with the schema supplied in the Ebix. For more information on how to configure the XDEDIFACTPreEmtter, see the iWay Integration Solution 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 formatted document. The XML structure must be compliant with the schema supplied in the Ebix. The XDSWIFTPreEmitter is used outside an adapter framework. For more information on how to configure 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 the preemitter and thus produces HTML output. If you would like to generate HTML screens as output from the channel, the XML output can be converted to HTML using the XSLT template.
iWay Service Manager Component Reference Guide 661 XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
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.
My CD Collection
Title Artist
The value for the field Template Name* is the full path name of the file. In this example, it is 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.
662 Information Builders 3. iWay Preemitters
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 move route and the outlet created in the previous step. 11. The input to this channel is as follows.
iWay Service Manager Component Reference Guide 663 XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
664 Information Builders 3. iWay Preemitters
iWay Service Manager Component Reference Guide 665 XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
666 Information Builders 3. iWay Preemitters
iWay Service Manager Component Reference Guide 667 XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
The obtained output is as follows.
My CD Collection
| Title | Artist |
|---|---|
| Empire Burlesque | Bob Dylan |
| Hide your heart | Bonnie Tyler |
| Greatest Hits | Dolly Parton |
| Still got the blues | Gary Moore |
| Eros | Eros Ramazzotti |
| One night only | Bee Gees |
| Sylvias Mother | Dr.Hook |
| Maggie May | Rod Stewart |
| Romanza | Andrea Bocelli |
| When a man loves a woman | Percy Sledge |
| Black angel | Savage Rose |
| 1999 Grammy Nominees | Many |
| For the good times | Kenny Rogers |
| Big Willie style | Will Smith |
| Tupelo Honey | Van Morrison |
| Soulsville | Jorn Hoel |
| The very best of | Cat Stevens |
| Stop | Sam Brown |
| Bridge of Spies | T`Pau |
| Private Dancer | Tina Turner |
| Midt om natten | Kim Larsen |
| Pavarotti Gala Concert | Luciano Pavarotti |
| The dock of the bay | Otis Redding |
| Picture book | Simply Red |
| Red | The Communards |
| Unchain my heart | Joe Cocker |
iWay Service Manager Component Reference Guide 669 XSL Tpre (com.ibi.preemit.XDXSLTpreEmitter)
670 Information Builders Chapter 4 iWay Iterators
This section provides an overview of iterators and their usage within iWay Service Manager 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 pass a 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 immediately below the loop. For example, consider the Count iterator. The Count iterator sends a copy of the 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 with the objects after the loop. Despite the appearance of the diagram in the iIT Designer workspace 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 Iterator Parameters
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 an iteration 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, Decision Test, Set, Sync, and Debug).
For more specific information about using iterators within iIT Designer, see the iWay Integration Tools 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 used across the iterators.
Parameter Description
Iterating Document State Documents carry state (such as error state, encoding, and so on) as well as payload. You can affect the state as the iteration progresses.
Transient. The state in the next iteration reflects the state from the last. For example, if the last state set it into 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, and so on.
672 Information Builders 4. iWay Iterators
Parameter Description
Output Document Determines the final document to be passed out of the iterator at the end of the iteration. Accumulations are memory intensive.
Status. A status document. This is a standard status document.
Original. The original document arriving at the iterator.
Accum In. Accumulation of the documents coming out of the loop and back into the iterator.
Accum Out. Accumulation of the documents passed into each 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 the appropriate document into the loop and to the end of the loop. The following table lists and describes the most commonly used iterators.
Iterator Description
Attachment Passes each attachment to the document (perhaps from an incoming HTTP 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.
iWay Service Manager Component Reference Guide 673 Available Iterators
Iterator Description
Counter Passes a document through the loop a specified number of times.
Delimited Value Generates one row of XML at a time from a delimited value input (for (DelVal) example, a comma separated value file.)
FTP Emit Emits through the FTP protocol to a specified host:port using various FTP commands.
Island Iterates a loop for each EDA island within the document and inserts the 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 the iterator. Lines end on terminator characters.
SQL Batch Insert Reads SQL rows one at a time and inserts results from the process flow.
SQL Select Each row from an SQL select operation is passed through the loop. The iterator can perform a batch update operation providing an Extract/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, it acts as a condition Do-While or Do-Until. It offers an extended range of comparisons, such as is empty or is equal ignore case.
XMLSplit An incoming XML message is split on an XPath and each split portion is passed through the loop. It is commonly used to extract repeating elements from the incoming document, such that each can be processed individually.
Other iterators perform specialized operations, such as handling portions of very large documents and passing portions of messages to other processors (configurations) through the Gateway protocol.
674 Information Builders 4. iWay Iterators
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 current document after processing.
replace. Replaces the original attachment with the modified document.
leave. Leaves the original attachments unchanged. This option is selected by default.
Start Index Index of first attachment to process in the mail object. The first attachment to the main document has index 0.
Header Namespace Special register namespace where MIME headers for the current attachment will be stored. If the replace option is selected for the Handling Option parameter, then registers in this namespace will be added to the replaced attachment.
Main Body Part Header If the current attachment is itself a Multipart, this is the Namespace special register namespace where the MIME headers for the main body part will be stored.
Keep Document Flat Determines whether to keep the body of the document as an array of bytes. This parameter is set to false by default.
Chunk Iterator (com.ibi.agents.XDIterChunk) Syntax: com.ibi.agents.XDIterChunk iWay Service Manager Component Reference Guide 675 Available Iterators
Description:
The Chunk Iterator splits the input document into equally sized chunks. The input stream may come from one of the streaming components, for example, a File listener set for streaming, or a File Read service configured with a stream format. The chunk is passed as a flat document containing 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. This parameter is set to true by default.
676 Information Builders 4. iWay Iterators
Parameter Description
Interim Document The document emitted at each iteration is the original document or the result of the previous iteration. By default, transient is selected.
Output Document Final document emitted is a status document, the original document, the result of the last iteration or an accumulation. Accumulations are memory intensive. By default, status is selected.
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 be constant 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 from a source, or perform any other operation repeatedly. The Counter Iterator can also be used with conditional logic to add retry functionality to an adapter that does not natively support retry. The number of iterations of the loop is not dependent on the structure of the input document, 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. The default value is 1.
Interim Document The document emitted at each iteration is the original document or the result of the previous iteration. By default, transient is selected.
iWay Service Manager Component Reference Guide 677 Available Iterators
Parameter Description
Output Document Final document emitted is a status document, the original document, the result of the last iteration or an accumulation. Accumulations are memory intensive. By default, status is selected.
Example:
The Counter Iterator in this example passes the input document into the loop the number of times specified by the
Input Document:
Output Document(s):
In this example, three documents are output by the FileWrite object:
IterCount01.xml
IterCount02.xml
IterCount03.xml
678 Information Builders 4. iWay Iterators
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 document representing one row at a time to the flow. The first row may be a header row (often called a DIF header) containing names to be applied to the elements of the row representing the column of data in the file.
Parameters:
Parameter Description
Root name The element name of the XML root. In the example in this section, 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 are used for the elements. If set to true, then the first row holds the 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 one character or a single hex value as \xvv, where vv is a hex value. By default, comma is selected as the delimiter.
Trim values Determines whether all values should be trimmed. This parameter 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 be eliminated. This parameter is set to false by default.
Output Document Final document emitted is a status document, the original document, the result of the last iteration or an accumulation. Accumulations are memory intensive. By default, status is selected. iWay Service Manager Component Reference Guide 679 Available Iterators
Example:
Consider the following input file:
acol,bcol,ccol aa1,bb1,cc1 aa2,bb2,cc2, aa3,bb3,cc3
Three iterations will be emitted. The first will be:
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 FTP commands.
Parameters:
Parameter Description
Host Parameters
Host Name DNS name (or IP address) of the FTP server to which you want to connect. Use host:port if not standard port 21.
Remote Port The port to connect to on the FTP site, blank for default port 21.
User Name A valid user ID for the FTP server.
Password A valid password for the FTP server.
680 Information Builders 4. iWay Iterators
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 the PORT command. This parameter is set to false by default.
Timeout The timeout interval for the socket in seconds. This parameter is 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 the FTP server.
Agent Parameters
Block Size The size of the transmission block to send. This parameter is set 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 specify the file name in this field. For document source, this parameter is ignored.
Remote Site Folder The folder or directory on the FTP site that you want to use as a starting location after a connection is established. Leave blank 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 data is expected to contain only character formatted text. BINARY mode refers to transferring files as a binary stream of data. Where ASCII mode may use special control characters to format data, BINARY mode transmits the raw bytes of the file being transferred. In this way, the file is transferred in its exact original form. This parameter is set to ascii by default.
iWay Service Manager Component Reference Guide 681 Available Iterators
Parameter Description
Put File Protection Determines whether the PUT is protected by a rename of a temporary file name. Using the rename protection can result in reduced performance, but can protect against partial updates in the event of an error. This parameter is set to false by default.
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 output document.
SSL Parameters
Use SSL If set, then the connection is secured through Secure Sockets Layer (SSL). This parameter is set to false by default.
Security Protocol The Security protocol:
SSL. Supports some version of SSL; may support other versions. This value is selected by default.
SSLv2. Supports SSL version 2 and higher.
SSLv3. Supports SSL version 3; may support other versions.
TLS. Supports some version of TLS; may support other versions.
TLSv1. Supports TLS version 1; may support other versions.
This field is not required if the Keystore is a SSL Provider.
Secure Data Connection Use a secure data connection, for example, to transfer data securely. This is used in conjunction with Secure Control Connection. This parameter is set to false by default.
Use 128-bit Encryption Enforces the use of 128-bit encryption. This parameter is set to false by default.
682 Information Builders 4. iWay Iterators
Parameter Description
SSL Security The FTP Server connection type:
unknown. Defaults to Explicit Security then fails over to Implicit Security. This value is selected by default.
explicit. In order to establish the SSL link, explicit security requires that the FTP client issue a specific command to the FTP server after establishing a connection. The default FTP server port is used.
implicit. Implicit security automatically begins with an SSL connection as soon as the FTP client connects to an FTP server. In implicit security, the FTP server defines a specific port for the client (typically 990) to be used for secure connections.
Keystore File or Keystore The full path to the Keystore file (which provides certificate Security Provider material to be used for SSL connections), the name of a Keystore Security Provider, or leave blank to use the configured default Keystore Security Provider.
Keystore Password The password to access the Keystore file. This is not required if the Keystore File or Keystore Security Provider parameter is set to the name of a Keystore Security Provider.
Keystore Type The type of Keystore. This is not required if the Keystore File or Keystore Security Provider parameter is set to the name of a Keystore Security Provider.
Site Parameters
Starting SITE command The SITE command to issue before the transfer of data.
Successful SITE The SITE command to issue after the successful transfer of command data.
Error SITE command The SITE command to issue if the transfer of data fails.
iWay Service Manager Component Reference Guide 683 Available Iterators
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 and inserts the response text.
The Island Iterator is designed to perform document enhancement, that is, to replace parts of the input XML document with the results of a call to an agent or adapter. Any external data source can be targeted (web services, SQL data, and so on), but in this example embedded file names are replaced with the content of the named disk file. The replacement would behave identical 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 tags to be replaced may be homogeneous, as in this example, or heterogeneous by using multiple sequential 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 incoming document arriving on the iteration loop for the island being processed. If set to false, the island node is kept and the incoming document is carried as the first child of the island node. This parameter is set to true by default.
Example:
684 Information Builders 4. iWay Iterators
Input Document
The primary input document is the document that contains the islands to be replaced. In this example, they are identified by the XML tag
file1.txt
file2.txt
file3.txt
Output Document(s)
The input document and the island documents are combined according to the behavior of the iterator.
Iter RVI Relay Iterator (com.ibi.agents.XDIterRVIRelay) Syntax:
com.ibi.agents.XDIterRVIRelay
Description:
The Iter RVI Relay Iterator relays messages for external execution. iWay Service Manager Component Reference Guide 685 Available Iterators
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 to access the named service. This parameter is set to 30 by default.
Timeout The amount of time (in seconds) to await response from the gateway. This parameter is set to 30 by default.
Attempt Retry If set to true, a retry exception is generated when no gateway connections are available, a message cannot be written to the gateway, 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 to acquire a new connection if the message cannot be written to the gateway and, if a connection is available, will retry automatically. If no connections are available, or if the service times out or otherwise fails while reading the response, the service will return a failure edge. This parameter is set to true by default.
Output On Failure If the relay operation is unsuccessful, this parameter determines whether the agent should return the standard error document, or return its input. If input is selected, then the error document will be stored in the rvi.status register [type: user]. By default, error is selected.
Method of compression The form of compression that should be used on the input. By to use default, 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.
686 Information Builders 4. iWay Iterators
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 is considered a single value. Therefore, to select multiple items within an array, a wildcard or a slice operator must be used.
The final output document can be a status document, the original document, the result of the last iteration, or an accumulation. The format of the accumulation depends on the type of the first accumulated value. If the first value is a JSON object, then the accumulation will have the following form: {"accumulation":[val1,…,valN]}
Parameters:
Parameter Description
Path Expression A JsonPath expression, which selects the specific items to iterate.
Output Document The final document emitted can be a status document, the original document, the result of the last iteration, or an accumulation.
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
iWay Service Manager Component Reference Guide 687 Available Iterators
Description:
The Line Iterator is used to iterate a loop for each line in the input document. The inner part of the loop can be used to generate multiple outputs, read multiple inputs from a source, or perform any other operation repeatedly. When using this iterator, the number of times through the 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 input be read into the process flow with a File object rather than being passed through the Start node.
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 a delimited file has a header row, which is not desired in the process. This parameter is set to 0 by default.
Output Document Final document emitted is a status document, the original document, the result of the last iteration or an accumulation. Accumulations are memory intensive. By default, status is selected.
Example:
Input Document This is the first line This is line 2 Line 3
688 Information Builders 4. iWay Iterators
Output Document(s)
In this example, three documents are output:
IterLine01.txt
IterLine02.txt
IterLine03.txt
This is the first line This is line 2 Line 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 process flow.
Parameters:
Parameter Description
Source Parameters
Input Provider The name of the Data Provider that will be used for accessing input.
Select SQL The SQL Select statement to retrieve rows to pass into the process flow.
Transaction Isolation The transaction isolation level to be set if possible. This Level parameter is set to asis by default.
Base 64 if Needed If set to true, all fields are checked for base64. This option is resource-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. By default, leave is selected. iWay Service Manager Component Reference Guide 689 Available Iterators
Parameter Description
Format as SQLAgent If set to true, the generated rows are formatted according to the SQLAgent field schema. This parameter is set to false by default.
Three Part Name If set to true, the names will be presented as full three part names if supported by the database. This parameter is set to false by default.
Destination Parameters
Output Provider The name of the Data Provider that will be used for inserting the output.
Output Insert Output statement to be prepared. Use ?name notation for parameters.
Out Encoding The IANA character set to be used for the output database. Select from the standard list, or enter an encoding name. By default, leave is selected.
Batch Size The size of sub-batches. If greater than 0, commit on batch size is reached. This parameter is set to 0 by default.
Commit Sub-batches If sub-batches are requested, determines whether they should be committed as they update. This parameter is set to false by default.
Fail First If the first row of the first batch fails, terminate the operation with the fail_insert edge. This parameter is set to false by default.
Omit Test iWay Functional Language (iFL), which if true, causes the current destination record to be omitted.
Main Parameters
Output document type Determines whether the emitted output document should be the original input document (original) or a status document (status). By default, status is selected.
690 Information Builders 4. iWay Iterators
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 accessing input.
Note: You must specify the actual name of this Data Provider as defined during configuration. For example: DataProviderSQL
Select SQL The SQL Select statement to retrieve rows to pass into the process flow.
Transaction Isolation The transaction isolation level to be set if possible. This Level parameter is set to asis by default.
Base 64 if Needed If set to true, all fields are checked for base64. This option is resource-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. By default, leave is selected.
Output document type Determines whether the emitted output document should be the 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 to the SQLAgent field schema. This parameter is set to false by default.
iWay Service Manager Component Reference Guide 691 Available Iterators
Parameter Description
Three Part Name If set to true, the names will be presented as full three part names if supported by the database. This parameter is set to false by default.
Inline xLOBs If set to true, character and boolean large objects are inline in the select results. BLOBs are enclosed in base64() tags. This parameter 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 of rows, siblings make the handling of very large result sets more practical. When used with the IterSibSplit operator, the logic inside the loop is executed once for each sibling document. One result row per sibling document is recommended for this iterator. Because the entire answer set is fetched prior to executing the loop, process flows using this technique may have high memory requirements.
Parameters:
Parameter Description
Output Document Final document emitted is a status document, the original document, the result of the last iteration or an accumulation. Accumulations are memory intensive. By default, status is selected.
Test Iterator (com.ibi.agents.XDIterTest) Syntax: com.ibi.agents.XDIterTest
692 Information Builders 4. iWay Iterators
Description:
The Test Iterator is used to iterate a loop while (or until) a condition is met. This iterator repeats the body of the loop while a specified logical comparison evaluates to true. The predicate is reevaluated each time through the loop. The inner part of the loop can be used to generate multiple outputs, read input multiple times from a source, or perform any other operation repeatedly. Similar to the count iterator, the test iterator can be used to retry an operation 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 case sensitive by default.
Operand Two The second of two operands to compare when the operation is dyadic.
Iterate Rule Determines the loop logic between do-while or do-until. This parameter is set to true by default.
Interim Document The document emitted at each iteration is the original document or the result of the previous iteration. By default, transient is selected.
Output Document Final document emitted is a status document, the original document, the result of the last iteration or an accumulation. Accumulations are memory intensive. By default, status is selected.
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.
iWay Service Manager Component Reference Guide 693 Available Iterators
Parameters:
Parameter Description
Snip levels Determines how many tag levels to trim off of the new XML document, 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 is 0, which will return all parent tags up to the root.
Note: Cross Section data may be lost depending on the snip level setting.
Expression Describes the XPath location of the element on which to split. When the Evaluate Expression is not set (false), enter an XPath 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 XPath expression directly. When set, the Expression parameter is evaluated and the returned value is the XPath expression used for splitting. This parameter is set to false by default.
XML Namespace Map If the XPath expression depends on namespaces, then specify Provider the name of an XML Namespace Map Provider that contains the required namespace prefixes and URLs.
Cross Section If set to true, the iterated portion is included with the remainder of the non-iterated portion of the document. Otherwise, only the parental path is included. This parameter is set to false by default.
Iterating Document State In addition to content, a document carries state. This parameter determines how the state should be managed at the iterations. This parameter is set to transient by default.
694 Information Builders 4. iWay Iterators
Parameter Description
End Iteration Signal Determines whether an extra iteration is added at the end to emit the End Iteration document. If applicable, the end of iteration signal will be emitted on the end_iteration edge. The default is not to emit the End Iteration document. This parameter 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 output document.
accumulations. Allow gathering of partial documents, but can be memory-intensive. Input is what passes from the iterator, and output is what is returned for each iteration.
XPath Syntax Determines which syntax level of XPath should be used. The default option selects the syntax level as set in the console global settings. By default, this parameter is set to default.
Example:
Often, a single transaction document contains repeating groups of data, in this example, a simplified invoice with multiple line items. The XML Iterator extracts the repeating group specified by the XPath expression. The parsed document contains the indicated group and preserves its direct parental lineage of XML nodes. If the logic inside your loop needs data from a parallel XML path (the invoice number in this example), then you can set the Cross Section parameter to true. Cross Section will preserve the entire document above the node that is the target of the Expression parameter.
iWay Service Manager Component Reference Guide 695 Available Iterators
The body of the loop is repeated once for each occurrence of the indicated group. The inner part of the loop can be used to process the repeating groups, call a web service, insert the data into an SQL database, and so on. When using this iterator, the number of times through the loop and how the input is parsed depends on the structure of the input document and the XPath expression.
Input Document
Output Document(s)
In this example, three documents are output by the FileWrite object:
IterXmlSplit01.xml
IterXmlSplit02.xml
IterXmlSplit03.xml
696 Information Builders 4. iWay Iterators
The following is an output document with the Cross Section parameter set to true.
The following is an output document when the Snip levels parameter is set to 1. version=”1.0” encoding=”UTF-16” ?> iWay Service Manager Component Reference Guide 697 Iterator Example Iterator Example The following diagram illustrates a simple example where an Iterator object is used in a process flow. The message reaching the iterator is operated upon accordingly (in this, case simply duplicated) and then sent into the process flow, which performs some operation. Any Service objects can be used in the loop, including iteration. When the message is handled by the subflow, 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. The OnComplete 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 the iteration message. Upon reaching the end of the iteration, control is passed to the Do More service object and then to the End object of the process flow. The iterator in this example is configured for the number of iterations and has instructions on what to pass to the end of the loop. While the iterator-specific configuration will vary, a common configuration property for iterators is the Output Document property. 698 Information Builders 4. iWay Iterators The Output Document property instructs the iterator on what to pass to the end of loop. In this example, it is a Service object called Do More. While some iterators offer additional values for the Output Document property, commonly available to all iterators is the Original and Status values. 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 the iterator). It is not reconfigured during the loop. In this example, a count might come from an XPath into the arriving message. However, regardless of how that message changes, the count obtained at the start of the loop will be honored. iWay Service Manager Component Reference Guide 699 Iterator Example 700 Information Builders Additional SQL Service Reference Appendix A Information 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 has occurred. 01002 A disconnect error has occurred. 01004 The data is truncated. 01006 The privilege is not revoked. 01S00 An invalid connection string attribute exists. 01S01 There is an error in a row. 01S02 The option value is changed. 07001 The wrong number of parameters are provided. iWay Service Manager Component Reference Guide 701 SQL Service Edge Returns Sorted by XOPEN Code XOPEN Code Edge Description 07002 The parameters are mismatched. 07003 The cursor specification cannot be executed. 07004 Parameters are missing. 07005 There is an invalid cursor state. 07006 A restricted data type attribute violation has occurred. 07008 There is an invalid descriptor count. 08000 A connection exception has occurred. 08001 A connection to the data source cannot be made (for example, invalid license key). 08002 A connection is already in use. 08003 A connection is not open. 08004 The data source rejected a connection attempt. 08007 A connection failure has occurred during a transaction. 08900 The server lookup failed. 08S01 A communication link failure has occurred. 21000 A cardinality violation has occurred. 21S01 An insert value list does not match the column list. 21S02 The degree of a derived table does not match the column list. 702 Information Builders A. Additional SQL Service Reference Information XOPEN Code Edge Description 22000 A data exception has occurred. 22001 String data has been truncated to the right. 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 is mismatched. 23000 An integrity constraint violation has occurred. 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 is invalid. 28000 The authorization specification is invalid. 34000 The cursor name is invalid. 3C000 duplicate There is a duplicate cursor name. 40000 The commit transaction resulted in a rollback transaction. 40001 fail_timeout There is a serialization failure (for example, timeout or deadlock). iWay Service Manager Component Reference Guide 703 SQL Service Edge Returns Sorted by XOPEN Code XOPEN Code Edge Description 42000 fail_syntax There is a syntax error or access rule violation. 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 has occurred. HY000 A general error has occurred. HY001 A storage allocation failure has occurred. 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 has occurred. HY011 The operation is invalid at this time. HY012 The transaction operation code is invalid. 704 Information Builders A. Additional SQL Service Reference Information XOPEN Code Edge Description HY015 No cursor name is available. HY018 The server declined a cancel request. HY090 There is an invalid string or buffer length. HY091 The descriptor type is out of range. HY092 The attribute or option type is out of range. 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 of range. HY101 The accuracy option type is out of range. 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 of range. iWay Service Manager Component Reference Guide 705 SQL Service Edge Returns Sorted by XOPEN Code 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 error has occurred. HZ020 A bad repetition count RDA error has occurred. HZ080 A resource not available RDA error has occurred. HZ090 A resource already open RDA error has occurred. HZ100 A resource unknown RDA error has occurred. HZ380 An SQL usage violation RDA error has occurred. IM001 The driver does not support this function. IM002 fail_notfound The data source name is not found and no default driver is specified. IM003 The specified driver could not be loaded. IM004 The AllocEnv property of the driver failed. 706 Information Builders A. Additional SQL Service Reference Information XOPEN Code Edge Description IM005 The AllocConnect property of the driver failed. IM006 The SetConnectOption property of the driver failed. IM007 No data source or driver is specified. The dialog is prohibited. IM008 The dialog failed. IM009 The translation DLL could not be loaded. 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 to read data from a row that has been modified by another executing transaction, but not yet committed. For example: Transaction 1 changes the row. Transaction 2 reads the changed row before transaction 1 commits the change. If transaction 1 rolls back its changes, then transaction 2 will have read a row that, following the rollback, is considered never to have existed. iWay Service Manager Component Reference Guide 707 Transaction Isolation Terminology Term Definition Nonrepeatable read A row is retrieved a second time by a transaction and the values in the row differ between the reads. For example: Transaction 1 reads a row. Transaction 2 deletes or updates that row and commits the change. If transaction 1 then attempts to reread the row, it will receive the updated value, or discover that the row does not exist. Phantom read During the course of a transaction, two identical queries are executed and different result sets are returned. For example: Transaction 1 reads a set of rows that satisfy some search criteria. Transaction 2 then inserts a row that matches the search criteria. Therefore if transaction 1 re-executes the statement that originally read the rows, it receives a different result set of rows. 708 Information Builders Appendix B Apache Avro Components Apache Avro is a remote procedure call and data serialization framework developed within 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 for communication between Hadoop nodes, and from client programs to the Hadoop services. This appendix describes the available components in iWay Service Manager (iSM) that have 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. The objects are converted to XML or JSON depending on the Conversion Format property. The conversion rules are documented below. The Avro data may come from the input document or a file. Avro requires the presence of a schema. The Avro File Read service can use the schema always stored in the container, or it can specify a reader schema, in which case Avro will do its best to reconcile the two schemas. The effective schema is stored in the output document, so it can serve as a default for the Avro File Emit service. iWay Service Manager Component Reference Guide 709 Avro File Read Service The path to the Avro Schema or the Avro Data File can be a regular path in the file system, or a URL starting with hdfs://, which indicates the file is in the Hadoop file system. When the Hadoop file system is used, the parameters Hadoop Configuration and Default File System can be 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 stored with the data will be used. Conversion Format Format of the incoming Avro data after conversion. The choices 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 Source is 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 as the URI of the namenode, for example hdfs://[your namenode]. 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. 710 Information Builders B. Apache Avro Components XML Conversion Format: When converting an Avro container to XML, the resulting document has the following format: 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 one Avro 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. For example: boolean The string true or false. For example: int A numeric string. For example: long A numeric string. For example: float A numeric string in a fixed point or scientific notation. For example: double A numeric string in fixed point or scientific notation. For example: iWay Service Manager Component Reference Guide 711 Avro File Read Service Avro Type XML Representation string The string. For example: enum The symbol string. For example: bytes A string of hexadecimal digits, each byte taking exactly two digits. For example: fixed A fixed-length string of hexadecimal digits, each byte taking exactly two digits. For example: record Each field becomes an unqualified sub-element with the same name as the field and no XML namespace. For example: array Each item in the array becomes an av:item sub-element. For example: The actual document is not indented. 712 Information Builders B. Apache Avro Components Avro Type XML Representation map Each entry in the map becomes an av:entry sub-element with the key attribute set to the key, and the contents set to the entry value. For example: The actual document is not indented. union The element has an xsi:type attribute set to the selected type and its contents is the union value directly as if the union did not exist. For example: For more complex types, the rules are applied recursively. The name of the element representing a value is always chosen by the rules of its parent scope. The outermost element of an object is always av:item, then the sub-elements might be av:item, av:entry, or the name of 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"]}]} iWay Service Manager Component Reference Guide 713 Avro File Read Service An instance of this record might look like the following syntax, once it is converted to XML (shown for display purposes only): 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 item in the array represents one Avro object in the container. The type of each item depends on the Avro 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 714 Information Builders B. Apache Avro Components 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. iWay Service Manager Component Reference Guide 715 Avro File Read Service Avro Type JSON Representation array A JSON Array. The item values are converted recursively. For example: [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 of the selected type. The field value is the value of the union. As a special case, a null value in a union is converted directly to null as if the 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). 716 Information Builders B. Apache Avro Components {"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 in an Avro container file. If the input document is XML, the root element in the input document can be If the input document is JSON, the value will typically be an array to write multiple objects to the container, one per array item. Other value types will cause a single object to be written to the container. To write a single array object, wrap it in an outer JSON array. The conversion from 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 compression algorithm are: No Compression BZip2 Deflate Snappy iWay Service Manager Component Reference Guide 717 Avro File Emit Service XZ The default is No Compression. Avro requires the presence of a schema. The Avro File Emit service can use the schema specified in its parameter, or it can use the schema stored in the input document as the default. The only way to store a schema in the document is to use another Avro component that produces XML, for example the Avro File listener, the Avro File Read service or the Avro File Iterator service. The output document returned can be the input document or a status document depending on the 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 stored with 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 a status document Respect Transactionality If set, the emit respects the transactionality of the channel. If not set, the emit is always done. 718 Information Builders B. Apache Avro Components 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 JSON representation 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 to Accepted JSON Representation Create null null boolean JSON booleans map naturally. Integer numbers other than 0 map to true, 0 maps to false, and the true and false Strings map to the corresponding values. Objects and Arrays map to false. int JSON numbers are coerced using default Java rules. Booleans convert to 0 (false) and 1 (true), and Strings are parsed using default Java language integer parsing rules. Objects and Arrays map to 0. long JSON numbers are coerced using default Java rules. Booleans convert to 0 (false) and 1 (true), and Strings are parsed using default Java language integer parsing rules. Objects and Arrays map to 0. float Numbers are coerced using default Java rules. Booleans convert to 0.0 (false) and 1.0 (true), and Strings are parsed using default Java language integer parsing rules. Objects and Arrays map to 0. iWay Service Manager Component Reference Guide 719 Avro File Iterator Service Avro Type to Accepted JSON Representation Create double Numbers are coerced using default Java rules. Booleans convert to 0.0 (false) and 1.0 (true), and Strings are parsed using default Java language integer parsing rules. Objects and Arrays map to 0. string Value nodes map to the string representation of the value. Objects and 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. Objects and Arrays map to the empty string. The string is then converted to bytes using ISO8859-1 encoding. fixed Value nodes map to the string representation of the value. Objects and Arrays map to the empty string. The string is then converted to bytes using ISO8859-1 encoding. The number of bytes must match the 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 of the selected type. The field value is the value of the union. A JSON null is also accepted if the union contains the null type. Avro File Iterator Service Syntax: com.ibi.agents.XDIterAvroFile 720 Information Builders B. Apache Avro Components Description: The Avro File Iterator opens an Avro container in the input document or in a file, and returns the objects it contains one by one. The object is converted to XML or JSON depending on the Conversion Format property. The conversion rules are documented with the Avro File Read service. For more information, see Avro File Read Service on page 709. Since the iterated 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 requires the presence of a schema. The Avro File Iterator service can use the schema always stored in the container, or it can specify a reader schema, in which case Avro will do its best to reconcile the two schemas. The effective schema is stored in the output document, so it 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 a URL starting with hdfs://, which indicates the file is in the Hadoop file system. When the Hadoop file system is used, the parameters Hadoop Configuration and Default File System can be 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 the first accumulated value determines the format of the whole accumulation. If the first accumulated value is XML, then the whole accumulation will be XML. Similarly, if the first accumulated 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 an Avro container. This is the case with Iterated Accumulation (because the iterator always produces av:item elements) or with Loop Accumulation when the loop does not modify the root element. Selecting av:avro will also set the schema in the final document. That schema can serve 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 with the data will be used. iWay Service Manager Component Reference Guide 721 Avro File Listener Parameter Description Conversion Format Format of the incoming Avro data after conversion. The choices 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. Ignored if the Input Source is 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 as the URI of the namenode, for example: hdfs://[your namenode] Output Document The final document emitted is a status document, which is the original document or the result of the last iteration or an accumulation. Accumulations are memory intensive. XML Accumulation Root Determines the root element of an accumulation. Select av:avro when accumulating av:item elements. Otherwise, select accumulation. This is ignored if the Output Document is not accumulating 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, and returns the objects it contains one by one. The objects are converted to XML or JSON depending on the Conversion Format property. The conversion rules are documented with the Avro File Read service. For more information, see Avro File Read Service on page 709. Since the 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. 722 Information Builders B. Apache Avro Components Avro requires the presence of a schema. The Avro File Listener can use the schema always stored in the container, or it can specify a reader schema, where Avro will do its best to reconcile the two schemas. The effective schema is stored in the output document so it can serve 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 stored with the data will be used. Conversion Format Format of the incoming Avro data after conversion. The choices are XML or JSON. Input Path Directory in which input messages are received. A specific file name or DOS-style regular expression pattern can be used. If you include the suffix in the pattern (such as ab*.xml) then be sure to configure the Suffix In to allow any suffix. Multiple locations can be specified, separated by a comma (,) or semi- colon (;) character. Destination Directory into which output files are stored. The specific file name is optional. Use an asterisk (*) in the file name to be replaced by a timestamp and number sign (#) by sequential counter. If required directories are not present at run time, iSM will attempt to create them. At run time, if it is unclear whether path names a directory or a filename, iSM will assume 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 timestamp and number sign (#) by sequential counter. iWay Service Manager Component Reference Guide 723 Avro File Listener Parameter Description Suffix In Filter The listener will match the extension exactly, in addition to the corresponding all-uppercase and all-lowercase extensions. Specify xml to accept files with .xml extensions. Do not use a period (.) character. Instead, use the en dash (-) character to indicate no extension, or an asterisk (*) character to indicate any 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 file unless 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 the listener. You can leave this field blank or set it to zero for no limit. The value can be entered with KB or MB, for example, 23MB for 23 megabytes, or enter with no suffix to specify size in bytes. Large File Directory Full path file pattern asserting where files exceeding the maximum file size will be moved. Use an asterisk (*) in file name to be replaced by timestamp and number sign (#) by sequential counter. Batch Mode If true, do not poll until all files from the previous poll have finished processing. Inbound Header Special register namespace into which metadata values for Namespace the input file will be saved. Maximum Inputs Maximum number of files that can be accepted for processing in a single poll. Note that if the number of files in the input directory exceeds this, sorting options may not work as expected. Enter 0 or leave blank for no limit. 724 Information Builders B. Apache Avro Components 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 it over HTTP, and optionally returns the response. The rules to convert the request from XML to Avro can be read backwards from the Avro to XML rules, as described in the Avro File Read Service on page 709. The rules to convert the request from JSON to Avro are documented with the Avro File Emit Service, as described in the Avro File Emit Service on page 717. An Avro Protocol file describes the possible interactions with the Avro server. The Message Name 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 starting with hdfs://, which indicates the file is in the Hadoop file system. When the Hadoop file system is used, the parameters Hadoop Configuration and Default File System can be optionally specified, otherwise they are ignored. The Avro Protocol declares a request as an array of named parameters with their types. From this, Avro derives the request schema as an anonymous record, each field of the record being one of the parameters. The input document must be an XML document that obeys that schema. 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 two options make more sense for one-way messages. The output will obey the response schema of the message if the service is configured to return the response and the call is successful. The response is converted to the same format used by the input document (XML or JSON). For more information on conversion rules from XML or JSON to Avro, see Avro File Read Service on page 709. For one-way messages, the response schema is equivalent to null. If the call is not successful, the response will obey the errors schema. This is a union that implicitly always includes the string schema. The appropriate schema will be stored as extra metadata in the output document. For example, this can serve as 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 client connections. The Provider must be created prior to the service. This can be done in the iSM console by selecting Pooling Providers in the left menu of the Server pane. iWay Service Manager Component Reference Guide 725 Avro RPC HTTP Emit Service 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 the URI 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 HTTP connections for this emitter. Cookie Store Name Allows thread-specific management of cookies. If a name is not specified, a cookie store global to the HTTP Client provider will be used. User ID User ID for authentication challenges. Password Password for authentication challenges. Domain Domain for NTLM authentication challenges. Note that to use NTLM, you must enable connection persistence. Request Header Special register namespace from which HTTP headers for the Namespace outgoing request will be taken. Select Default Namespace to send HDR type registers with no namespace prefix, or you can supply a namespace prefix here. The None option means that no special registers will be sent as HTTP headers. 726 Information Builders B. Apache Avro Components Parameter Descriptions Response Header Special register namespace into which HTTP headers from the Namespace incoming response will be saved. Select Default Namespace to create special registers with no namespace prefix, or you can supply a namespace prefix here. Excluded Headers Comma delimited list (case insensitive) of headers that should not be sent with a request, even if it is found in a request header namespace. Ask for Compressed If set, requests will set the Accept-Encoding header to indicate Response that the client can accept a compressed response, as described in RFC-2616. If the response has a compressed content encoding, the client will automatically inflate. Compress Request If set, the HTTP request entity will be compressed using the selected encoding and the Content-Encoding header will be set accordingly. Release Connection If true, the connection will be released to the connection pool Immediately immediately. This is the default. If false, the connection identifier is stored in the httpclient-key special register and the HTTP Client Manager agent must be called later to release the connection explicitly. Maximum HTTP Client Maximum time the HTTP Client Manager can take to deal with a Manager Delay particular connection before it is automatically aborted. The format is [xxh][xxm]xx[s]. The default is 60 seconds. Try Expect/Continue If selected, the client will send the HTTP Expect: 100-continue Handshake? header and await HTTP 100 response before sending the request body. Chunk Encoded If true, the request entity will be sent with chunk encoding. Request? Maximum Request Size Maximum size, after compression, of a request entity that can be sent with this emitter. 0 means no maximum, and a blank field will default to 256KB. iWay Service Manager Component Reference Guide 727 Avro RPC HTTP Emit Service Parameter Descriptions Maximum Response Maximum size of a response entity that can be received by this Size emitter. 0 means no maximum, and a blank field will default to 256KB. Persistence If selected, ask the server to maintain the connection. Response Timeout Seconds to wait for a response before signaling an error. value in Seconds Return Return from this agent. Select input to return an input document, status for an XML document with transaction parameters and status, or response to capture output from the server. 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 Request Size. 728 Information Builders B. Apache Avro Components Edge Description fail_response_too_large The response is larger than the configured Maximum Response Size. The service often returns more than one edge with the more specific edge first. For example, if the request is unauthorized, the returned edges will be 401,fail_client. This can be handled by wiring 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): iWay Service Manager Component Reference Guide 729 Avro RPC Over HTTP Listener The same request in JSON is similar to the following syntax (indented for display purposes only): {"message": {"to":"wife", "from":"husband", "body":"I love you!"}} Since the send message has a single request argument called message, the anonymous record contains a single field called message. A sample XML response for the send message may appear similar to the following syntax: 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 send message because they have the same request arguments. The selected message is configured 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. 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. The request is converted to XML or JSON depending on the Conversion Format property. After the request is executed, the response is converted from XML or JSON to Avro RPC binary and sent back. 730 Information Builders B. Apache Avro Components An Avro Protocol file describes the possible interactions between the Avro RPC client and the listener. The path to the Avro Protocol file can be a regular path in the file system, or a URL starting with hdfs://, which indicates the file is in the Hadoop file system. When the Hadoop file system is used, the parameters Hadoop Configuration and Default File System can be optionally 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 an array of named parameters with their types. From this, Avro derives the request schema as an anonymous record, each field of the record being one of the parameters. The response schema is simpler because the Avro Protocol defines its type directly. The errors schema is always a union, which implicitly includes the type string. The listener can interpret the incoming request because it can retrieve the message metadata based on the message name encoded in the request. The request is converted from binary Avro to XML or JSON according to the request schema. That schema will be stored as extra metadata in the input document. For example, this can serve as a default for the schema in the Avro File Emit service. The response is converted to binary Avro based on the response schema in general, or the errors schema if the document is in error. For more information on the conventions of the XML representation of the Avro data, see the Avro File Read service documentation. The rules to convert the request from binary Avro to XML or JSON are described in the Avro File Read Service on page 709. The rules to convert the response from XML to Avro can be read backwards from these tables. The rules to convert the response from JSON to Avro are described in the Avro File Emit Service on page 717. For more information and an example of an Avro Protocol and sample request/response documents 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 IO listener (NHTTP). For more information on the parameters controlling HTTP, see the documentation 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. iWay Service Manager Component Reference Guide 731 Avro RPC Over HTTP Listener Parameter Description Conversion Format Format of the incoming Avro data after conversion. The choices are 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 the URI 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 over HTTP Listener. Register Type Description avromessage string The name of the message within the Avro Protocol that corresponds to the incoming request. In addition to the avromessage SREG, the Avro RPC over HTTP Listener inherits the same SREGs as the Non-blocking HTTP (nHTTP) Listener. 732 Information Builders Index C preemitters 630 Legacy Record preemitter 647 COBOL 295 Marshalls a message preemitter 648 E Multi Part preemitter 649 PGP Sign Only preemitter 653 EDIFACT 587, 624, 661 PGPEncrypt preemitter 651 Excel 591 QA Print preemitter 654 Remove Outer Tag preemitter 657 H Replace Paired Characters preemitter 659 HIPAA 599, 625, 640 SWIFT preemitter 660 UUEncodePreEmitter 660 I XDEDIFACT preemitter 661 Iterators 671 XDSWIFT preemitter 661 XSL Tpre preemitter 661 L preparsers 577 Append preparser 583 LDAP Reader 293 C Char Filter preparser 583 P Char Repl preparser 585 Concatenated XML Document Stream preemitters 630 preparser 614 adding 630 Delimited Value Splitter preparser 621 Constant PE preemitter 634 Delimited Value Stream preparser 616 Deflate preemitter 635 EDIBatchSplitter preparser 623 EDIX12 preemitter 636 EDIFACT preparser 587 Entity Repl preemitter 636 EDIFACTBatchSplitter preparser 624 File read preemitter 637 EDIH7PreParser preparser 587 Flat Delim preemitter 638 EDIX12 preparser 588 HIPAA preemitter 640 EDIX12 XML validator preparser 588 iWay Transformations preemitter 640 EDIX12Splitter preparser 624 iWay Service Manager Component Reference Guide 733 Index preparsers 577 R En Tag preparser 588 RabbitMQ Emit service 363 Error Filter preparser 590 RabbitMQ Read service 367 Excel preparser 591 Flat Stream preparser 618 S HIPAA preparser 599 services 21 HIPAABatchSplitter preparser 625 Accumulate EOS service 26 HIPAASplitter preparser 625 Activity Log Entry service 35 HTTP preparser 599 Add Attachment From File service 37 Inflate preparser 600 Add Attachment service 40 JMS Object preparser 601 Add Correl Entry service 42 Legacy Record preparser 602 Alt Route IP service 43 Multipart nHTTP preparser 605 Append Stream to File Service 44 Multipart preparser 603 AQ Emit service 46 PGP Decrypt preparser 607 AS 1 Emit service 56 PGP Verify Signiture Only preparser 607 AS 2 Emit service 60 Replace characters on a one for one basis AS 2 Nonblocking Emit service 49 preparser 607 AS 2 Nonblocking Send MDN service 65 Smime preparser 608, 612 Attachment Operations service 68 SOAP preparser 609 Attachment to Document service 69 splitters 620 Attachment to File Service 71 SREG preparser 610 Base64 Operation service 76 streaming 614 Bearer Token Agent Service 78 SWIFT preparser 611 Blank Elimination service 81 SWIFTAck preparser 611 C Char Filter service 109 SWIFTBatchSplitter preparser 625 Cancel service 83 SWIFTSystemMessage preparser 612 Catch service 85 Unmarshalls a message preparser 613 Channel Information service 89 XDSWIFT preparser 614 Check Schema service 92 XML Splitter preparser 626 Commit or Rollback within a Flow service 97 734 Information Builders Index services 21 services 21 Constant service 98 Ethereum Call Agent Service 183 Controls Listeners service 100 Ethereum Call Constant Function Agent Cookie Store Agent Service 105 Service 185 Correl Inquiry By State service 106 Ethereum Deploy Agent Service 186 Correl Inquiry service 107 Ethereum Transfer Agent Service 188 Correl Set Inquiry service 108 Excel reader Service 189 Deflate service 119 Execute ETL service 190 Delete an Item Service 128 Fail service 192 destroy status Service 130 File Emit service 201 Document Attachment service 154 File operations Service 206 Document Copy service 132 File read 208 Document state modification Service 140 File Read service 210 Document Update service 142 Form Data Agent Service 213 DQC (document-driven, pooling) 159 HTTP Client Pool Manager Service 221 DQC (non-pooling, deprecated) 117 HTTP Client Service 215 DQC (user parameter-driven, pooling) 163 HTTP Cookie Agent Service 219 DQC Batch Executor 156 HTTP Emit service 222 DQC/MDC Flow Linkage 158 HTTP Nonblocking Emit service 228 EDI Accumulator Service 168 HTTP Read service 232 EDI Rule Router Service 169 HTTP ReST Routing service 236 EDIFACT ValidationReportAgent Service 171 HTTP Session Invalidator Agent Service 238 EDIFACTAckAgent Service 170 Hyperledger Fabric Key History Agent Service EDIHL7 ValidationReport Agent Service 173 239 EDIHL7AckAgent Service 172 Hyperledger Fabric Query Agent Service 241 EDIWrapperAgent Service 174 Hyperledger Fabric Query Block Agent Service EDIX12AckAgent Service 176 242 EDIX12TransformAgent Service 175 Hyperledger Fabric Transaction Agent Service Email Emit service 177 244 Entag service 182 IEI Feed Agent Service 246 iWay Service Manager Component Reference Guide 735 Index services 21 services 21 Inflate service 247 NTCP Read Agent Service 328 Insert SAML Assertion service 250 NTCP Respond Agent Service 330 Insert WSSE Timestamp service 251 OAuth 1.0 Authentication service 331 Insert WSSE Token service 251 OAuth 2.0 Authentication service 332 Inserts data inside an XML document Service OpenRules service 333 248 P Flow service 358 Internal Emit service 251 P Flow Test service 361 Is Reachable service 257 Parallel Execution: Counted iteration Service JDBC service 269 334 JDBC via iWay JNDI Datasource Service 272 Parallel Execution: JSON iteration Service 335 JMS Read Agent service 276 Parallel Execution: XML iteration Service 337 JMSQ Browse service 273 Parse to XML service 339 JMSQ Emit service 274 PDF Form Field Reader Service 341 LDAP Reader 293 PF File Operations service 342 Legacy Record to XML Converter service 295 PF File Read service 343 Local Master service 302 PGP Decryption and Verification Service 345 Log Business Error service 32 PGP Encryption and Signature Service 346 Mail Attach service 303 PGP Sign Only Service 350 Mark Attach service 306 PGP Verify Signature Only Service 351 Move service 310 Preemitter in Flow service 352 MQ Emit service 311 Print Emit service 354 MQ JMS Emit Agent Service 312 Protocol Business service 357 MQ Read service 315 QA service 361 MQTT Emit Agent Service 317 RabbitMQ Emit service 363 MSMQ Emit service 318 RabbitMQ Read service 367 MTOM service 320 Route service 371 Node Set Extract service 322 Rule Router service 372 NTCP Client Write Agent Service 325 Run OS Shell Command service 374 NTCP Emit Agent Service 323, 326 736 Information Builders Index services 21 services 21 RVI Relay: send message to gateway service SQL service 439 Service 377 SREG FTP: Pass register settings to iWay FTP RVI Response: return iterations to the RVI Server Service 457 Iterator Service 379 SREG Insert service 461 RVI Stream Relay Service 380 SREG Namespace service 463 Schema Validation Service 384 SREG service 468 Scripting Agent Service 386 SREG: Save/Restore Document Value Service search Service 387 465 Security Authenticate/Impersonate service 73 SREG: Save/Restore XML tree Service 466 Security: Authenticate/Impersonate Service Store or Reload a Document Value in a 391 Register service 381 Server Statistics Service 392 Store or Reload an XML Tree in a Register Set Document State service 393 service 383 Set special registers Service 395 SWIFT Out Report service 474 SFTP Connection Cache Service 397 SWIFT Transform service 475 SFTP Direct Transfer Service 399 SWIFT Validation service 476 SFTP Emit Agent Service 402 SWIFT XML Transform service 477 SFTP File Ops Agent Service 405 TCP Emit Service 478 SFTP Read Agent Service 408 TIBCO RV Emit service 482 show status Service 411 Transform service 488 SMIME Packer Agent Service 413 Tree Evaluator service 492 SMIME Unpacker Agent Service 416 UDP Emit service 493 Snip service 418 Update Correl Entry service 495 Sonic Emit service 421 Verify WSSE Timestamp Service 499 Sonic Queue Browser service 424 Web Service Client service 500 Sonic Read service 426 Web Service HTTP Client service 503 SP Router service 431 X12 Validation service 506 Split service 428 XA Log Inquiry By Context service 507 Split To MQ service 429 XA Log Inquiry By Date service 508 iWay Service Manager Component Reference Guide 737 Index services 21 services 21 XA Log Inquiry By Partner service 509 XMLtoHIPAATransformAgent Service 553 XA Log Inquiry By Transaction ID service 510 XMLtoX12TransformAgent Service 556 XA Log Message service 511 XQuery Expression Evaluation service 558 XAdES Digital Signature Create Service 513 Zip Out Service 567 XAdES Digital Signature Verify Service 521 SOAP 609 XDTwitterGetHomeTimeline Service 524 SQL 439 XDTwitterUpdateStatus Service 526 SWIFT 474–477, 611, 612, 614, 625, 660, 661 XML Decryption Service 541 XML Digital Signature Create service 543 T XML Digital Signature Verify service 544 TIBCO 482 XML Encryption Service 544 XML Extract Service 549 W XMLtoEDIFACTTransformAgent Service 550 worksheets 591 XMLtoEDIHL7TransformAgent Service 553 738 Information Builders Feedback Customer success is our top priority. Connect with us today! Information Builders Technical Content Management team is comprised of many talented individuals 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 and services. 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]. iWay Service Manager Component Reference Guide Version 8.0 and Higher DN3502114.0718 Information Builders, Inc. Two Penn Plaza New York, NY 10121-2898